IIapi_query() Function—Begin Query Statement and Allocate Statement Handle

The IIapi_query() function begins a query statement. IIapi_query() allocates a statement handle. The statement handle must eventually be freed with the IIapi_close() function.

An application enters parameters for the query statement with subsequent calls to the IIapi_setDescriptor() and IIapi_putParms() functions. It can also use the qy_queryText parameter of IIapi_query() to enter the syntax of the query statement. The qy_queryText parameter should contain NULL if query text is not required.

Note: For a list of SQL statements that can be invoked by IIapi_query(), see Accessing a DBMS Using SQL).

When entering the syntax of SQL statements in the qy_queryText parameter, see SQL Syntax) and the SQL Reference Guide.

An application specifies the beginning of a transaction with the qy_tranHandle input parameter. If this parameter is NULL or is a transaction ID handle created by IIapi_registerXID(), a new transaction is begun and a transaction handle is allocated. Otherwise, this parameter must be an existing transaction handle and the statement is executed as part of the current transaction.

A transaction handle allocated by this function must be released using IIapi_commit() or IIapi_rollback(). If a transaction handle is allocated for a request which eventually fails, the transaction handle should be released using IIapi_rollback().

Currently, the GCA protocol does not support multiple, concurrent non-cursor statements in the same transaction, or multiple concurrent transactions on the same connection.

This function has the following syntax:

typedef struct _IIAPI_QUERYPARM
{
       IIAPI_GENPARM       qy_genParm;
       II_PTR              qy_connHandle;
       IIAPI_QUERY_TYPE    qy_queryType;
       II_BOOL             qy_parameters;
       II_CHAR             *qy_queryText;
       II_PTR              qy_tranHandle;
       II_PTR              qy_stmtHandle;
       II_ULONG            qy_flags;
} IIAPI_QUERYPARM;

This function has the following parameters:

Specifies the generic parameters. For a description, see Generic Parameters).

Specifies the connection handle, identifying the connection to the target server.

Note: If connecting to a DBMS, see Accessing a DBMS Using SQL) for valid DBMS query type macros.

Specifies the syntax of the query statement, if syntax is required. The query text should be a NULL-terminated string containing the query text with zero or more parameter markers.

Indicates whether there are parameters to be sent with the query. TRUE if the application intends to send parameters with the query using IIapi_setDescriptor() and IIapi_putParms(); FALSE if there are no parameters to be sent with the query. OpenAPI requires some parameters for certain query types.

Note: If FALSE, the query is sent to the server for processing; otherwise, OpenAPI waits for calls to IIapi_setDescriptor() and IIapi_putParms() before sending the query to the server.

Indicates whether a new transaction should be started or whether an existing transaction should be used. If the parameter is NULL or a transaction ID handle created by IIapi_registerXID(), a new transaction should be started. If the parameter is a transaction handle previously returned by another query, the existing transaction should be used.

For a Name Server connection, this parameter must be an autocommit transaction handle returned by IIapi_autoCommit().

Specifies the statement handle identifying the query statement for future OpenAPI function calls.

Specifies query options. This parameter is ignored if the OpenAPI version is less than IIAPI_VERSION_6. The following flags can be set:

Requests a scrollable cursor. Only applicable when qy_queryType is IIAPI_QT_OPEN.