isc_dsql_free_statement()

Performs one of three actions:

Frees a statement handle and all resources allocated for it.
Closes a cursor associated with the statement referenced by a statement handle.
Cancels statement execution in the server.

Syntax

 ISC_STATUS isc_dsql_free_statement(
 ISC_STATUS *status_vector,
 isc_stmt_handle *stmt_handle,
 unsigned short option);

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`stmt_handle`	`isc_stmt_handle *`	Pointer to a statement handle previously allocated with `isc_dsql_allocate_statement()` or `isc_dsql_alloc_statement2`(); the handle returns an error in status_vector if it is `NULL`.
`option`	`unsigned short`	One of the following: `DSQL_close` `DSQL_drop` DSQL_cancel

Description

isc_dsql_free_statement() either frees a statement handle and all resources allocated for it (option = DSQL_drop), closes a cursor associated with the statement (option = DSQL_close), or cancels execution of the statement (option = DSQL_cancel).

Note: isc_dsql_free_statement() does nothing if it is called with an option value other than DSQL_drop, DSQL_close, or DSQL_cancel.

DSQL_close:

The DSQL_close option closes a cursor after it is no longer needed, that is, after fetching and processing all the rows resulting from the execution of a query. A cursor only needs to be closed in this manner if it was previously opened and associated with stmt_handle by isc_dsql_set_cursor_name().

DSQL_close closes a cursor, but the statement it was associated with remains available for further execution.

If you have used a cursor to perform updates or deletes on all the rows returned from the execution of a query, and you want to perform other update or delete operations on rows resulting from the execution of the same statement again (possibly with different input parameters), follow these steps:

Close the cursor with isc_dsql_free_statement().
Re-open it with isc_dsql_set_cursor_name().
If desired, change the input parameters to be passed to the statement.
Re-execute the statement to retrieve a new select list.
Retrieve rows in a loop with isc_dsql_fetch() and process them again with isc_dsql_execute_immediate().

DSQL_drop:

Statement handles allocated with isc_dsql_allocate_statement() must be released when no longer needed by calling isc_dsql_free_statement() with the DSQL_drop option. This option frees all resources associated with the statement handle, and closes any open cursors associated with the statement handle.

DSQL_cancel:

The DSQL_cancel option allows for the asynchronous cancellation of an executing statement. The client that was executing the statement receives a status code of isc_cancelled. Once a statement has been cancelled, any subsequent execution restarts the statement, rather than resuming it.

Example

The following program fragment shows examples of the two types of isc_dsql_free_statement() calls. It assumes that stmt_handle1 and stmt_handle2 are statement handles, each of which was previously allocated with either isc_dsql_allocate_statement() or isc_dsql_alloc_statement2(). A cursor is also assumed to have been associated with the statement referenced by stmt_handle1.

#include <ibase.h>
ISC_STATUS status_vector[20];
. . .
/* Free the cursor associated with stmt_handle1. */
isc_dsql_free_statement(status_vector, &stmt_handle1, DSQL_close);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector);
return(1);
}
/* Free stmt_handle2. */
isc_dsql_free_statement(status_vector, &stmt_handle2, DSQL_drop);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector);
return(1);
}

Return value

isc_dsql_free_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, 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_prepare()