isc_dsql_allocate_statement()

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

Syntax

 ISC_STATUS isc_dsql_allocate_statement(
 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`(). `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_allocate_statement() 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_allocate_statement() or isc_dsql_alloc_statement2() should be called to allocate a statement handle prior to preparing and executing the statement with isc_dsql_prepare() and isc_dsql_execute().

Note: The function isc_dsql_allocate_statement() is very similar to the function isc_dsql_alloc_statement2(), except that statement handles allocated using isc_dsql_allocate_statement() are not automatically reset to NULL when the database under which they are allocated is detached. To reset statement handles automatically, use isc_dsql_alloc_statement2().

When you are done processing a statement, the statement handle can be freed with isc_dsql_free_statement() or by calling isc_detach_database().

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;

statement_handle = NULL; /* Set handle to NULL before allocating it. */
isc_dsql_allocate_statement(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 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. Free the statement handle when it is no longer needed. */

Return value

isc_dsql_allocate_statement() 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_alloc_statement2()