IIapi_batch() Function—Execute Batch Statements

2. OpenAPI Function Reference : OpenAPI Functions : IIapi_batch() Function—Execute Batch Statements

Share this page

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.

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.

For more information, see How Batch Statements with Parameters Are Executed and How Batch Statements with Multiple Parameter Sets Are Repeated.

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.