OpenAPI User Guide > OpenAPI User Guide > OpenAPI Function Reference > OpenAPI Functions > IIapi_batch() Function--Execute Batch Statements
Was this helpful?
IIapi_batch() Function--Execute Batch Statements
The IIapi_batch() function enables an application to request batch execution of multiple query statements. Using IIapi_batch() is similar to using IIapi_query() (see IIapi_query() Function--Begin Query Statement and Allocate Statement Handle) to execute a query statement. IIapi_batch() differs from IIapi_query() in the following ways.
The handling of transaction and statement handles for the first call to IIapi_batch() for a group of query statements is the same as for calling IIapi_query(). IIapi_batch() allocates a statement handle. The statement handle must eventually be freed with the IIapi_close() function. Additional query statements are added to a batch by calling IIapi_batch() and providing the statement handle returned by the first IIapi_batch() call.
IIapi_batch() permits only a limited set of query types: general query statements (IIAPI_QT_QUERY), prepared statements (IIAPI_QT_EXEC), and database procedures (IIAPI_QT_EXEC_PROCEDURE). In addition to the query type limitation, query statements in a batch are not permitted to return data rows, either through a SELECT query or row-returning database procedure.
If a query statement added to a batch has parameters, the parameters are provided by calls to IIapi_setDescriptor() and IIapi_putParms(), just as is done for a query statement being executed using IIapi_query(), prior to adding the next query statement to the batch. A single query statement can be executed with multiple parameter sets in a batch by calling IIapi_batch(), IIapi_setDescriptor(), and IIapi_putParms() for each set of parameters.
A single query statement also may be executed with multiple parameter sets using a single call to IIapi_batch(). Following the first call to IIapi_batch(), IIapi_setDescriptor(), and IIapi_putParms(), to provide the first set of parameters, additional calls to IIapi_setDescriptor() and IIapi_putParms() may be made to provide the additional parameter sets without calling IIapi_batch() to re-submit the statement. The DBMS may be able to execute the statement more efficiently when submitted this way. For more information, see Batch Statement Execution on page 17.
Batch processing is not supported on Name Server connections.
This function has the following syntax:
II_VOID IIapi_batch( IIAPI_BATCHPARM *batchParm );
typedef struct _IIAPI_BATCHPARM
{
      IIAPI_GENPARM      ba_genParm;
      II_PTR             ba_connHandle
      IIAPI_QUERYTYPE    ba_queryType;
      II_CHAR            *ba_queryText;
      II_BOOL            ba_parameters;
      II_UINT4           ba_flags;
      II_PTR             ba_tranHandle;
      II_PTR             ba_stmtHandle;
} IIAPI_BATCHPARM;
This function has the following parameters:
ba_genParm
Type: input and delayed output
Specifies the generic parameters (see Generic Parameters).
ba_connHandle
Type: input
Specifies the connection handle, identifying the connection to the target server.
ba_queryType
Specifies the query type. Batch processing limits the query types that may be executed to the following types:
IIAPI_QT_QUERY
IIAPI_QT_EXEC
IIQPI_QT_EXEC_PROCEDURE
*ba_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.
ba_parameters
Type: input
Indicates whether there are parameters to be sent with the batch. TRUE if the application intends to send parameters with the batch using IIapietDescriptor() and IIapi_putParms(); FALSE if there are no parameters to be sent with the batch.
ba_flags
Type: input
Specifies query options. Currently, there are no query options applicable to batch processing. This parameter should be set to zero.
ba_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.
ba_stmtHandle
Type: immediate output
Specifies the statement handle identifying the query statement for future OpenAPI function calls.
This parameter is also an input parameter for batch processing. It should be set to NULL for the first statement in a batch. A statement handle will be returned that should be provided as input for all subsequent statements in the batch.
Last modified date: 01/30/2023