Using SQL with the Advantage Client Engine

Advantage Client Engine

This section provides an overview of how to use the SQL support provided by the Advantage Client Engine (ACE). See Advantage SQL Engine for a detailed description of the SQL language supported by Advantage. The Advantage SQL engine section also includes information about the types of cursors generated by SELECT statements.

Relational access through the Advantage Client Engine is accomplished using cursor handles (very similar to table handles) and statement handles. The following API’s are essential to the base usage of SQL through the Advantage Client Engine:

In addition, there are a number of APIs that can be used to change the default settings of statement handles. In general, these affect the settings used by the server when it opens base tables referenced in SQL statements.

The first step in executing an SQL statement via the Advantage Client Engine is to create a connection to either the Advantage Database Server (ADS) or the Advantage Local Server (ALS). This can be accomplished using AdsConnect . Note that this example assumes it is written in C or C++ and, thus, uses the double backslash in the path. If you use a language in which the backslash is not the escape character in string constants, then the path would have a single backslash.

AdsConnect( "x:\\data\\example", &hConnection );

Next you will need to use this connection handle to obtain a statement handle:

AdsCreateSQLStatement( hConnection, &hStatement );

The choice of which API to use next will depend on the type of SQL statement being executed. If executing an SQL statement that contains parameters, a combination of AdsPrepareSQL and AdsExecuteSQL must be used. See Parameters in SQL Statements for a discussion on using parameters.

In this example the next API to be called will be AdsExecuteSQLDirect. AdsExecuteSQLDirect is a combination of AdsPrepareSQL and AdsExecuteSQL, and this API is a more direct approach to executing an SQL statement when you will not be dealing with any parameters.

AdsExecuteSQLDirect( hStatement,

"SELECT * FROM test WHERE dept = ‘R&D’ AND salary < 40000",

&hCursor );

After the SQL statement has been executed, a cursor handle may be returned depending on the type of SQL statement. If the SQL statement is a Data Manipulation Language (DML) statement or a Data Definition Language (DDL) statement, then no cursor is returned. A DML statement starts with the INSERT, UPDATE, or DELETE keywords. A DDL statement starts with either the CREATE or DROP keywords. Any statement that starts with the keyword SELECT will return a cursor handle. See Working with Cursor Handles for a discussion on using cursor handles.

When finished with the rowset the user should free the cursor handle with a call to AdsCloseTable:

AdsCloseTable( hCursor );

The statement handle is now available for another query. If the cursor is not closed prior to a new query using the statement handle, an error will be returned. You are required to free the cursor before another cursor can be created on this statement handle. It is, however, possible to have multiple statement handles, each with an active cursor handle.