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
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`trans_handle`	`isc_tr_handle *`	Pointer to a transaction handle whose value has been set by a previous `isc_start_transaction()` call; `trans_handle` returns an error if `NULL`.
`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`.
`da_version`	`unsigned short`	Specifies that the XSQLDA descriptor, rather than SQLDA, should be used; set this value to 1.
`in_xsqlda`	`XSQLDA` `*`	Pointer to an optional, previously allocated `XSQLDA` used for input; if input parameters are not supplied, set this value to NULL.
`out_xsqlda`	`XSQLDA` `*`	Pointer to an optional, previously allocated `XSQLDA` used for results of statement execution; if not required, set this value to NULL.

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 of isc_dsql_prepare() and isc_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 and SET TRANSACTION cannot be executed with isc_dsql_execute() or isc_dsql_execute2(). To execute these statements, use isc_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.

Advance To:

isc_dsql_execute_immediate()