isc_dsql_describe()

Go Up to API Function Reference

Provides information about columns retrieved by the execution of a DSQL SELECT or EXECUTE PROCEDURE statement. For more information about preparing a DSQL statement with return values, see DSQL Programming Methods. For more information about creating and populating the XSQLDA, see Understanding the XSQLDA.

Syntax

 ISC_STATUS isc_dsql_describe(
 ISC_STATUS *status_vector,
 isc_stmt_handle *stmt_handle,
 unsigned short da_version,
 XSQLDA *xsqlda);

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.
da_version	unsigned short	Specifies that the XSQLDA descriptor, rather than SQLDA, should be used; set this value to 1.
xsqlda	XSQLDA *	Pointer to a previously allocated XSQLDA used for output.

Description

isc_dsql_describe() stores into XSQLDA a description of the columns that make up the rows returned for a SELECT statement, or a description of the result values returned by an EXECUTE PROCEDURE statement. These ­statements must have been previously prepared for execution with ­isc_dsql_prepare(), before ­isc_dsql_describe() can be called.

Note: Using isc_dsql_describe() is not necessary unless a previously issued ­isc_dsql_prepare() function indicates that there is insufficient room in the output XSQLDA for the return values of the DSQL statement to be ­executed.

Example

The following program fragment illustrates a sequence of calls which allocates an XSQLDA, prepares a statement, checks whether or not the appropriate number of XSQLVAR was allocated, and corrects the situation if needed.

#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *osqlda;
int n;
char *query = "SELECT * FROM CITIES
WHERE STATE = 'NY'
ORDER BY CITY DESCENDING";
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);
osqlda->version = SQLDA_CURRENT_VERSION;
osqlda->sqln = 3;
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, query, 1, osqlda);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}

if (osqlda->sqld > osqlda->sqln) {    /* Need more XSQLVARS. */
n = osqlda->sqld;
free(osqlda);
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);
osqlda->sqln = n;
osqlda->version = SQLDA_CURRENT_VERSION;
isc_dsql_describe( status_vector, &stmt_handle, 1, osqlda);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}
}

Return value: isc_dsql_describe() 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.

See Also

• isc_dsql_describe_bind()
• isc_dsql_execute()
• isc_dsql_execute2()
• isc_dsql_prepare()

Advance To:

• isc_dsql_describe_bind()