isc_dsql_execute2()
Go Up to API Function Reference
Executes a previously prepared DSQL statement. For more information about creating and populating the XSQLDA
, see Understanding the XSQLDA.
Syntax
ISC_STATUS isc_dsql_execute2(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
isc_stmt_handle *stmt_handle,
unsigned short da_version,
XSQLDA *in_xsqlda,
XSQLDA *out_xsqlda);
Parameter | Type | Description |
---|---|---|
|
|
Pointer to the error status vector |
|
|
Pointer to a transaction handle whose value has been set by a previous |
|
|
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 an optional, previously allocated |
|
|
Pointer to an optional, previously allocated |
Description
isc_dsql_execute2()
executes a previously prepared DSQL statement that has input parameters and returns results, such as EXECUTE PROCEDURE
and SELECT
.
If the statement to execute requires input parameter values (that is, if it contains parameter markers), these values must be supplied in the input XSQLDA
, in_xsqlda
before calling isc_dsql_execute2()
.
If the statement to execute returns values, they are placed in the specified output XSQLDA
, out_xsqlda
. If a NULL
value is supplied for the output XSQLDA
and the statement returns values, they are stored in a result set. To access the returned data, use isc_dsql_fetch()
in a loop.
- Tip: If you just want to execute once a statement returning just one group of data, call
isc_dsql_exec_immed2()
instead ofisc_dsql_prepare()
andisc_dsql_execute2()
.
To execute a statement that does not return any data a single time, call isc_dsql_execute_immediate
() instead of isc_dsql_prepare()
and isc_dsql_execute2
().
- Note:
CREATE DATABASE
andSET TRANSACTION
cannot be executed withisc_dsql_execute()
orisc_dsql_execute2()
. To execute these statements, useisc_dsql_execute_immediate()
.
Example
The following program fragment illustrates a sequence of calls that allocates an input XSQLDA
and loads values into it, allocates an output XSQLDA
, prepares an EXECUTE
PROCEDURE
statement, allocates space in the output XSQLDA
for each column returned for each row retrieved by the call, and executes the prepared statement, placing return values in the output XSQLDA
.
#include <ibase.h> ISC_STATUS status_vector[20]; XSQLDA *isqlda, *osqlda; XSQLVAR *ivar, *ovar; short null_flag; char *str = "EXECUTE PROCEDURE P1"; char *state = "CA"; /* Allocate an output XSQLDA osqlda. This example assumes you know that * P1 will return one value. */ osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1); osqlda->version = SQLDA_CURRENT_VERSION; osqlda->sqln = 1; /* Prepare the statement, including filling in osqlda with information * about the item to be returned by the statement (procedure). */ 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, osqlda); if (status_vector[0] == 1 && status_vector[1]) { /* Process error. */ isc_print_status(status_vector); return(1); } /* Set up the output XSQLVAR structure to allocate space for the return * value. Again, this example assumes you know that P1 returns just one * value. For an example of what to do if you’re not sure, see * isc_dsql_describe(). For an example of setting up an output XSQLVAR * structure to allocate space for multiple return items, see the * isc_dsql_execute() example program. */ ovar = osqlda->sqlvar[0]; dtype = (ovar->sqltype & ~1); /* Drop NULL bit for now. */ switch(dtype) { case SQL_TEXT: ovar->sqldata = (char *)malloc(sizeof(char) * ovar->sqllen); break; case SQL_LONG: ovar->sqldata = (char *)malloc(sizeof(long)); /* Process remaining types. */ . . . } if (ovar->sqltype & 1) { /* Assign a variable to hold NULL status. */ ovar->sqlind = &null_flag; } /* Allocate and fill in the input XSQLDA. This example assumes you know * how many input parameters there are (1), and all other information * necessary to supply a value. If this is not true, you will need to * call isc_dsql_describe_bind(). */ isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1); isqlda->version = SQLDA_CURRENT_VERSION; isqlda->sqln = 1; isqlda->sqld = 1; ivar = isqlda->sqlvar[0]; ivar->sqltype = SQL_TEXT; ivar->sqllen = sizeof(state); ivar->sqldata = state; /* Execute the statement. */ isc_dsql_execute2(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. */ 1, isqlda, osqlda); if (status_vector[0] == 1 && status_vector[1]) { /* Process error. */ isc_print_status(status_vector); return(1); } /* Now process the value returned in osqlda->sqlvar[0]. */ . . .
Return value
isc_dsql_execute2()
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_trans_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.
See Also
- isc_dsql_exec_immed2()
- isc_dsql_execute_immediate()
- isc_dsql_execute()
- isc_dsql_fetch()
- isc_dsql_prepare()