Advantage Client Engine

Executes an SQL statement



AdsExecuteSQLDirect( ADSHANDLE hStatement,


ADSHANDLE *phCursor )


hStatement (I)

Handle of an SQL statement created by a call to AdsCreateSQLStatement .

pucSQL (I)

The SQL statement given as a null terminated string.

phCursor (O)

Returns the cursor handle if executing a SELECT statement, otherwise returns NULL.


AdsExecuteSQLDirect is a combination of AdsPrepareSQL and AdsExecuteSQL. The SQL statement cannot have parameters. If parameters are required, use AdsPrepareSQL and AdsExecuteSQL.

The value returned in the phCursor parameter is dependent on the type of SQL statement being executed. If executing a SELECT statement a handle to the cursor will be returned, and this cursor handle can then be used in calls that accept normal ADS table handles (e.g., AdsGetField). If executing a statement other than a SELECT the phCursor parameter can be passed in as NULL. If executing a statement other than a SELECT and the phCursor parameter is not passed in as NULL, it will be set to NULL by AdsExecuteSQLDirect.

If the SQL statement is an UPDATE statement the statement handle can be passed to AdsGetRecordCount to determine how many rows were affected by the UPDATE statement.

If the statement handle has an open cursor associated with it AdsExecuteSQLDirect will return an error. The cursor must first be closed with AdsCloseTable.

After the SQL statement has been executed a cursor handle will be returned. This cursor handle provides access to the rowset returned. Note that statements other than SELECT statements will not return a rowset, therefore they will not return a cursor (e.g., INSERT, UPDATE). Except for the APIs listed below this cursor handle can take the place of a table handle in any Advantage Client Engine API. For example, API AdsGetField is documented as accepting a table handle for its first parameter. This table handle can be replaced with a cursor handle to obtain data from the rowset:

  AdsGetField( hCursor, "lastname", aucBuffer,

&ulLen, ADS_TRIM );

The following APIs are not compatible with cursor handles:

Cursors returned by SELECT statements may be static cursors or dynamic cursors (updateable). See the family of AdsStmtSet APIís for information on specifying a cursor as read-only or updateable. AdsGetTableOpenOptions can be used to determine if the returned cursor is read-only (and thus static) or not.

Note This function is capable of utilizing registered callback functions. To learn more about callback functionality and how it behaves with this function, see Callback Functionality.


Click Here

See Also