isc_dsql_alloc_statement2()

Allocates a statement handle for subsequent use with other API dynamic SQL (DSQL) calls.

Syntax

 ISC_STATUS isc_dsql_alloc_statement2(
 ISC_STATUS *status_vector, 
 isc_db_handle *db_handle, 
 isc_stmt_handle *stmt_handle);

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`db_handle`	`isc_db_handle *`	Pointer to a database handle set by a previous call to `isc_attach_database()`; the handle identifies the database containing the array column. `db_handle` returns an error in `status_vector` if it is `NULL`.
`stmt_handle`	`isc_stmt_handle *`	Pointer to the statement handle to be allocated by this function; the handle must be NULL when this function is called, or an error is returned in `status_vector`.

Description

isc_dsql_alloc_statement2() allocates a statement handle and returns a pointer to it in stmt_handle. This pointer is passed to isc_dsql_prepare() to associate the statement handle with a particular DSQL statement for processing.

If a DSQL statement is to be executed multiple times, or if it returns output (other than the results from a stored procedure), isc_dsql_alloc_statement2() or isc_dsql_allocate_statement() should be called to allocate a statement handle prior to preparing and executing the statement with isc_dsql_prepare() and isc_dsql_execute().

Note: When a database is detached, the handles that you allocated under that database using isc_dsql_alloc_statement2() are automatically reset to NULL; the handles that you allocated under that database using isc_dsql_alloc_statement() are not modified.

Example

The following program fragment allocates a statement handle for a SQL statement that will access the database referenced by the database handle, database_handle:

ISC_STATUS status_vector[20];
isc_stmt_handle statement_handle;

isc_dsql_alloc_statement2( status_vector,
&database_handle, /* Set in previous
  * isc_attach_database() call. */
&statement_handle);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector); /* Display an error message. */
return(1); /* Return now. */
};
/* Call other functions to associate a particular SQL statement with the
 * statement handle, and to do other operations necessary to prepare and
 * execute the DSQL statement. */

Return value

isc_dsql_alloc_statement2() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to isc_bad_stmt_handle, isc_bad_db_handle, or another InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

Advance To:

isc_dsql_batch_execute