Understanding the XSQLDA

Go Up to Working with Dynamic SQL

All DSQL applications must declare one or more extended SQL descriptor areas (XSQLDA). The XSQLDA structure definition can be found in the ibase.h header file in the InterBase include directory. Applications declare instances of the XSQLDA for use.

The XSQLDA is a host-language data structure that DSQL uses to transport data to or from a database when processing a SQL statement string. There are two types of XSQLDA: input descriptors and output descriptors. Both input and output descriptors are implemented using the XSQLDA structure.

One field in the XSQLDA, sqlvar, is an XSQLVAR structure. The sqlvar is especially important, because one XSQLVAR must be defined for each input parameter or column returned. Like the XSQLDA, the XSQLVAR is a structure defined in ibase.h in the InterBase include directory.

Applications do not declare instances of the XSQLVAR ahead of time, but must, instead, dynamically allocate storage for the proper number of XSQLVAR structures required for each DSQL statement before it is executed, then deallocate it, as appropriate, after statement execution.

The following figure illustrates the relationship between the XSQLDA and the XSQLVAR:

An input XSQLDA consists of a single XSQLDA structure and one XSQLVAR structure for each input parameter.
An output XSQLDA consists of one XSQLDA structure and one XSQLVAR structure for each data item returned by the statement.

An XSQLDA and its associated XSQLVAR structures are allocated as a single block of contiguous memory.

The isc_dsql_prepare(), isc_dsql_describe(), and isc_dsql_describe_bind() functions can be used to determine the proper number of XSQLVAR structures to allocate, and the XSQLDA_LENGTH macro can be used to allocate the proper amount of space.

For more information about the XSQLDA_LENGTH macro, see Using the XSQLDA_LENGTH Macro.

Topics

Advance To:

XSQLDA Field Descriptions