Understanding the XSQLDA (Embedded SQL Guide)
Go Up to Using 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, the XSQLVAR, 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:
XSQLDA and XSQLVAR relationship
An input XSQLDA consists of a single XSQLDA structure, and one XSQLVAR structure for each input parameter. An output XSQLDA also 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 PREPARE and DESCRIBE statements 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 (Embedded SQL Guide).
Topics
- XSQLDA Field Descriptions (Embedded SQL Guide)
- XSQLVAR Field Descriptions (Embedded SQL Guide)
- Input Descriptors (Embedded SQL Guide)
- Output Descriptors (Embedded SQL Guide)
- Using the XSQLDA LENGTH Macro (Embedded SQL Guide)
- SQL Data Type Macro Constants (Embedded SQL Guide)
- Handling Varying String Data Types (Embedded SQL Guide)
- NUMERIC and DECIMAL Data Types
- Coercing Data Types (Embedded SQL Guide)
- Aligning Numerical Data (Embedded SQL Guide)