adoRSetQuery

Synopsis:

adoRSetQuery(handle,cursor_type,lock_type,options,query_str1[,query_str2...])

Arguments:

handle - The recordset handle.

cursor_type - The type of cursor

lock_type - The locking type

options - Additional options

query_str1 - The query string

[query_str2..] - optional additional text that will be concatenated to make the complete query string..

Description: This function executes a query on the resordset specified by the handle argument. The cursor_type argument can be set to one of the following constants (as defined in ado.inc):

Constant	Value	Description
adOpenUnspecified	-1	Does not specify the type of cursor.
adOpenForwardOnly	0	Default. Uses a forward-only cursor. Identical to a static cursor, except that you can only scroll forward through records. This improves performance when you need to make only one pass through a Recordset.
adOpenKeyset	1	Uses a keyset cursor. Like a dynamic cursor, except that you can't see records that other users add, although records that other users delete are inaccessible from your Recordset. Data changes by other users are still visible.
adOpenDynamic	2	Uses a dynamic cursor. Additions, changes, and deletions by other users are visible, and all types of movement through the Recordset are allowed, except for bookmarks, if the provider doesn't support them.
adOpenStatic	3	Uses a static cursor. A static copy of a set of records that you can use to find data or generate reports. Additions, changes, or deletions by other users are not visible.

The lock_type argument can be set to one of the following constants (as define in ado.inc):

Constant	Value	Description
adLockUnspecified	-1	Unspecified type of lock.
adLockReadOnly	1	Read-only records
adLockPessimistic	2	Pessimistic locking, record by record. The provider lock records immediately after editing
adLockOptimistic	3	Optimistic locking, record by record. The provider lock records only when calling update
adLockBatchOptimistic	4	Optimistic batch updates. Required for batch update mode

If adLockBatchOptimistic is specified then the recordset is opened in batch mode which enables the use of the adoRSetUpdBatch() and adoRSetCancelBatch() functions to be used (if supported by the data provider).

The options argument allows additional options to be specified and can be one or more of the CommandTypeEnum values or the ExecuteOptionEnum values shown below (these constants are defined in the ado.inc file) . The adoRSetQuery() function will always add the options: adoAsyncExecute, adoAsyncFetch and adoAsyncFetchNonBlocking options, and this functionality cannot be turned off. Care should be taken when adding some of these options as it may effect the way the library reacts to ADO events. for example, setting the adoExecuteNoRecords option will probably stop the FetchComplete event being triggered so in blocking mode the adoRSetQuery() function call will block forever and never return.

CommandTypeEnum values:

Constant	Value	Description
adCmdUnspecified	-1	Unspecified type of command
adCmdText	1	Evaluates CommandText as a textual definition of a command or stored procedure call
adCmdTable	2	Evaluates CommandText as a table name whose columns are returned by an SQL query
adCmdStoredProc	4	Evaluates CommandText as a stored procedure name
adCmdUnknown	8	Default. Unknown type of command
adCmdFile	256	Evaluates CommandText as the file name of a persistently stored Recordset. Used with Recordset.Open or Requery only.
adCmdTableDirect	512	Evaluates CommandText as a table name whose columns are all returned. Used with Recordset.Open or Requery only. To use the Seek method, the Recordset must be opened with adCmdTableDirect. Cannot be combined with the ExecuteOptionEnum value adAsyncExecute.

ExecuteOptionEnum values.

adOptionUnspecified	-1	Unspecified command
adAsyncExecute	16	The command should execute asynchronously. Cannot be combined with the CommandTypeEnum value adCmdTableDirect
adAsyncFetch	32	The remaining rows after the initial quantity specified in the CacheSize property should be retrieved asynchronously
adAsyncFetchNonBlocking	64	The main thread never blocks while retrieving. If the requested row has not been retrieved, the current row automatically moves to the end of the file. If you open a Recordset from a Stream containing a persistently stored Recordset, adAsyncFetchNonBlocking will not have an effect; the operation will be synchronous and blocking. adAsynchFetchNonBlocking has no effect when the adCmdTableDirect option is used to open the Recordset
adExecuteNoRecords	128	The command text is a command or stored procedure that does not return rows. If any rows are retrieved, they are discarded and not returned. adExecuteNoRecords can only be passed as an optional parameter to the Command or Connection Execute method
adExecuteStream	256	The results of a command execution should be returned as a stream. adExecuteStream can only be passed as an optional parameter to the Command Execute method
adExecuteRecord	512	The CommandText is a command or stored procedure that returns a single row which should be returned as a Record object

The SQL query string is specified in one or more of the the remaining arguments (query_str1, query_str2 ...), which will be concatenated together into one complete string. The concatenated query string must not exceed 2047 characters. For example in the following query string is made up from a number of arguments that have been concatenated together in this way:

acc_no="129934";

x=adoRSetQuery(handle,adOpenStatic,adLockReadOnly,-1,"select * from customers where acc_no=",acc_no);

which is equivalent to the following:

x=adoRSetQuery(handle,adOpenStatic,adLockReadOnly,-1,"select * from customers where acc_no=129934");

Remember that the maximum number of arguments that can be passed to a DLL library function in the Telecom Engine is 32.

Note that this function relies on the FetchComplete event being triggered in blocking mode in order to wake up the calling task. If for some reason the data provider does not cause the FetchComplete task to trigger then use the adoRSetCmd() function instead, which is identical except for it relies on the ExecuteComplete event instead.

Returns: Returns 0 upon success or a negative error code. If ADOERR_COMERR is returned, then the underlying ADO error can be obtained by calling adoLastError()