Advantage Client Engine
Prepares an SQL statement for execution
UNSIGNED32 |
AdsPrepareSQL( ADSHANDLE hStatement, UNSIGNED8 *pucSQL ) |
hStatement (I) |
Handle of an SQL statement created by a call to AdsCreateSQLStatement. |
pucSQL (I) |
The SQL statement given as a null terminated string. |
Use AdsPrepareSQL when executing SQL statements that contain parameters.
The Advantage Client Engine supports named parameters as well as unnamed parameters. An unnamed parameter is represented with a question mark (?). Named parameters are represented with a string preceded by a colon. The "String" portion may contain the characters ‘0..9’, ‘A..Z’, ‘a..z’, or the underscore character (‘_’). Any sub-string in the SQL statement that meets the following criteria will be assumed to be a named parameter:
It is of the form ":String"
It is not within a quoted string
NAMED PARAMETER EXAMPLE |
"select * from test where lastname = :value" |
UNNAMED PARAMETER EXAMPLE |
"select * from test where lastname = ?" |
Once the call to AdsPrepareSQL has been performed the AdsSet family of functions may be used to assign values to parameters.
Each of the AdsSet* functions has at least three parameters: hAdsHandle, pucFieldName, and xxxValue. When defining SQL parameters, pass the statement handle that has been prepared as the hAdsHandle value. Then use pucFieldName to indicate the parameter name/number and xxxValue to set the parameter’s value.
AdsPrepareSQL( hStatement, "select * from test where lastname < :name" );
AdsSetString( hStatement, "name", "Anderson", strlen("Anderson") );
AdsExecuteSQL( hStatement, &hCursor);
The pucFieldName argument can reference a string that stores the named parameter name or it can contain a parameter number. Every parameter may be referenced by a number regardless if it is named or unnamed. The numbers start with 1 and increment from left to right.
AdsPrepareSQL( hStatement, "select * from test where lastname < :name" );
AdsSetString( hStatement, ADSFIELD(1), "Anderson", strlen("Anderson") );
AdsExecuteSQL( hStatement, &hCursor);
Subsequent calls to AdsExecuteSQL will cause only changed parameter values or SQL statements to be sent to the server.
AdsPrepareSQL( hStatement,
"select * from test where lastname = :lname and firstname = : fname" );
AdsSetString( hStatement, "lname", "Anderson", strlen("Anderson") );
AdsSetString( hStatement, "fname", "John", strlen("John") );
AdsExecuteSQL( hStatement, &hCursor);
// now close the cursor and change one of the parameters
AdsCloseTable( hCursor );
AdsSetString( hStatement, "fname", "Frank", strlen("Frank") );
// now the statement will resolve to
// "select * from test where lastname = ‘Anderson’ and firstname = ‘Frank’ " );
AdsExecuteSQL( hStatement, &hCursor );
If the SQL statement is changed, the old parameter values will be matched with the new statement by using the parameter number. Use AdsClearSQLParams to destroy all parameters and free their associated memory.
If the statement handle has an open cursor associated with it, AdsPrepareSQL will return an error. The cursor must first be closed with AdsCloseTable.