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.
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:
II_VOID IIapi_query (IIAPI_QUERYPARM *queryParm);
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:
qy_genParm
Type: input and delayed output
qy_connHandle
Type: input
Specifies the connection handle, identifying the connection to the target server.
qy_queryType
Type: input
Specifies the type of query statement.
For a Name Server connection, this parameter must be IIAPI_QT_QUERY.
qy_queryText
Type: input
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.
qy_parameters
Type: input
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.
qy_tranHandle
Type: input and immediate output
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().
qy_stmtHandle
Type: immediate output
Specifies the statement handle identifying the query statement for future OpenAPI function calls.
qy_flags
Type: input
Specifies query options. This parameter is ignored if the OpenAPI version is less than IIAPI_VERSION_6. The following flags can be set:
IIAPI_QF_LOCATOR
Enables retrieval of Blob/Clob locators instead of actual LOB data.
IIAPI_QF_SCROLL
Requests a scrollable cursor. Only applicable when qy_queryType is IIAPI_QT_OPEN.
Last modified date: 08/14/2024