OpenAPI User Guide > OpenAPI User Guide > OpenAPI Function Reference > OpenAPI Functions > IIapi_query() Function--Begin Query Statement and Allocate Statement Handle
Was this helpful?
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:
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
Specifies the generic parameters. For a description, see Generic Parameters).
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.
Note:  If connecting to a DBMS, see Accessing a DBMS Using SQL) for valid DBMS query type macros.
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:  For more information, see Queries, Parameters, and Query Data Correlation).
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: 11/09/2022