isc_dsql_describe_bind()
Go Up to API Function Reference
Provides information about dynamic input parameters required by a previously prepared DSQL statement. For more information about preparing a DSQL statement with input parameters, see DSQL Programming Methods. For more information about creating and populating the XSQLDA, see Understanding the XSQLDA.
Syntax
ISC_STATUS isc_dsql_describe_bind(
ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short da_version,
XSQLDA *xsqlda);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to a statement handle previously allocated with |
|
|
|
Specifies that the XSQLDA descriptor, rather than SQLDA, should be used; set this value to 1. |
|
|
|
Pointer to a previously allocated |
Description
isc_dsql_describe_bind() stores into the input XSQLDA xsqlda information about the dynamic input parameters required by a DSQL statement previously prepared with isc_dsql_prepare().
Before an application can execute a statement with input parameters, it must supply values for them in an input XSQLDA structure. If you know exactly how many parameters are required, and their data types, you can set up the XSQLDA directly without calling isc_dsql_describe_bind(). But if you need InterBase to analyze the statement and provide information such as the number of parameters and their data types, you must call isc_dsql_describe_bind() to supply the information.
Example
The following program fragment illustrates a sequence of calls that allocates an input XSQLDA, prepares a DSQL UPDATE statement, calls the function isc_dsql_describe_bind(), checks whether or not the appropriate number of XSQLVAR was allocated, and corrects the situation if necessary.
#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *isqlda
int n;
char *str = "UPDATE DEPARTMENT SET BUDGET = ?, LOCATION = ?";
isc_dsql_prepare( status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle, /* Allocated previously by
* isc_dsql_allocate_statement()
* or isc_dsql_alloc_statement2() call. */
0, str, 1, NULL);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}
/* Allocate an input XSQLDA. */
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);
isqlda->version = SQLDA_CURRENT_VERSION;
isqlda->sqln = 1;
isc_dsql_describe_bind( status_vector,
&stmt_handle, /* Allocated previously by
* isc_dsql_allocate_statement()
* or isc_dsql_alloc_statement2() call. */
1, isqlda);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}
if (isqlda->sqld > isqlda->sqln) { /* Need more XSQLVARs. */
n = isqlda->sqld;
free(isqlda);
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);
isqlda->sqln = n;
isqlda->version = SQLDA_CURRENT_VERSION;
isc_dsql_describe_bind( status_vector, &stmt_handle, 1, isqlda);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}
}
Return value
isc_dsql_describe_bind() 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.