Rx Query

Description:
TRxQuery component is inherited from TQuery component. In addition, an application can supply macros values for dynamic queries with the Macros property and the MacroByName method. Standard Delphi's parameters can replace only column names or data values. Macros allows you change at run-time dinamically any part of SQL text.

Property MacroChar
Declaration: MacroChar: Char;

MacroChar determines character which indicates macros in the SQL query text (default value is '%').

Property MacroCount
Declaration: MacroCount: Word;

Run-time and read-only. The MacroCount property specifies how many entries the TRxQuery has in its Macros array, that is, how many macros the query has. Adding a new item to Macros will automatically increase the value; removing an item will automatically decrease the value.

Property Macros
Declaration: Macros: TParams;

When you enter a query, TRxQuery creates a Macros array for the macros of a dynamic SQL statement. Macros is a zero-based array of TParam objects with an element for each macro (indicated by the leading MacroChar character) in the query; that is, the first macro is Macros[0], the second Macros[1], and so on. The number of macros is specified by MacroCount.

Note: Use the MacroByName method instead of Macros to avoid dependencies on the order of the parameters.

Property Macros example

For example, suppose a TRxQuery component named rxQuery2 has the following statement for its SQL property:

SELECT * FROM ITEMS ORDER BY %ORDER and MacroChar = '%'.

An application could use Macros property and MacroByName method to specify the value of the "ORDER" macro as follows:

rxQuery2.Close;
rxQuery2.MacroByName('ORDER').AsString := 'ITEMS.ID';
rxQuery2.Open;
rxQuery2.Close;
rxQuery2.MacroByName('ORDER').AsString := 'ITEMS.NAME';
rxQuery2.Open;
rxQuery2.Close;
rxQuery2.MacroByName('ORDER').AsString := 'ITEMS.VENDOR';
rxQuery2.Open;

These three statements would sort the query result by the ID, NAME and VENDOR field correspondingly.

Property OpenStatus
Declaration: OpenStatus: TQueryOpenStatus;

OpenStatus reads the current status of the query component after calling OpenOrExec method. The possible values are those of the TQueryOpenStatus type:

• qsOpened - query was successfully executed and result set was returned (i.e. SELECT statement);
• qsExecuted - query was successfully executed but result set has not generated (i.e. INSERT, UPDATE, DELETE, or any DDL statement);

• qsFailed - error has detected during query execution.

Method ExecDirect
Declaration: ExecDirect

This method is used to immediately prepare and execute a query. Use ExecDirect method to avoid having the SQL statement parsed for parameters (i.e. anything preceded by a colon ':').

In this case, it is being used to create an Oracle trigger, where ":new" refers to the new version of the updated record. Conversely, ":old" refers to the record before the update. Oracle also happens to use ":=" as an assignment operator in triggers.

Method ExpandMacros
Declaration: procedure ExpandMacros;

Replace all macroses in the SQL text by their string values before executing of the query. Called automatically by the Open, Prepare or ExecSQL methods, by must be called manually before ExecDirect or OpenOrExec methods if SQL statements has macroses (MacroCount > 0).

Method IsEmpty
Declaration: function IsEmpty: Boolean;

Checks for a dataset without records.

Method MacroByName
Declaration: function MacroByName(const Value: string): TParam;

The MacroByName method returns the element of the Macros property whose Name property matches Value. Use it to assign values to macroses in a dynamic TRxQuery by their names.

Method MacroByName example

rxQuery1.ParamByName('ORDER').AsString := 'ITEMS.NAME';

Method OpenOrExec
Declaration: procedure OpenOrExec(ChangeLive: Boolean);

If you do not know at design time whether a query will return a result set at run time, use OpenOrExec method to execute query. After calling OpenOrExec you can check OpenStatus property value to determine whether a result set has been returned. If ChangeLive parameter is True and an application requests a live result set, but the SELECT statement syntax does not allow it, the OpenOrExec will try query execution again without request a live result set.

Method OpenOrExec example

begin
__{...}
__rxQuery1.SQL := Memo1.Lines;
__if Memo1.Lines.Count = 0 then
____Exit;
__rxQuery1.RequestLive := True;
__rxQuery1.Params.Clear;
__StartWait;
__try
____rxQuery1.OpenOrExec(True);
__finally
____StopWait;
__end;
__if rxQuery1.OpenStatus = qsExecuted then
____MessageDlg('Query successfully executed.', mtInformation, [mbOk], 0);
__{...}
end;

Index Page | About | Download
Creation Date: 4 Feb 1998 | Last Update: 16 Mar 2000