An SQLDA is a set of variables that is used for execution
of the SQL DESCRIBE statement, and it may optionally be used by the
PREPARE, OPEN, CALL, FETCH, and EXECUTE statements.
An SQLDA can be used in a DESCRIBE or PREPARE statement,
altered with the addresses of storage areas1, and then used again in a FETCH statement.
SQLDAs are supported for all languages, but predefined
declarations are provided only for C (and C++), COBOL, ILE RPG, PL/I,
and REXX.
In REXX, the
SQLDA is somewhat different than in the other languages; for information
about the use of SQLDAs in REXX, see the Embedded SQL Programming topic
collection.
The meaning of the information in an SQLDA depends on
its use.
- When an SQLDA is used in a DESCRIBE or PREPARE statement,
an SQLDA provides information to an application program about a prepared select-statement. Each
column of the result table is described in an SQLVAR occurrence or
set of related SQLVAR occurrences.
- In OPEN, EXECUTE, CALL, and FETCH, an SQLDA provides information
to the database manager about storage areas for input or output data.
Each storage area is described in the SQLVARs.
- For OPEN and EXECUTE of a statement other than CALL, each SQLVAR
occurrence or set of related SQLVAR occurrences describes a storage
area that is used to contain an input value which is substituted for
a parameter marker in the associated SQL statement that was previously
prepared.
- For FETCH, each SQLVAR occurrence or set of related SQLVAR occurrences
describes a storage area that is used to contain an output
value from a row of the result table.
- For CALL and EXECUTE of a prepared CALL statement, each SQLVAR
occurrence or set of related SQLVAR occurrences describes a storage
area that is used to contain an input or output value (or both)
that corresponds to an argument in the argument list for the procedure.
An SQLDA consists of four variables in a header followed
by an arbitrary number of occurrences of a base SQLVAR.
When the SQLDA desribes either LOBs or distint types the base SQLVARs
are followed by the same number of occurrences of an extended
SQLVAR.
- Base SQLVAR entry
- The base SQLVAR entry is always present. The fields of this entry
contain the base information about the column or variable such as
data type code, length attribute (except for LOBs), column name (or
label), CCSID, variable address, and indicator variable address.
- Extended SQLVAR entry
- The extended SQLVAR entry is needed (for each column) if the result
includes any LOB or distinct type columns. For distinct types, the
extended SQLVAR contains the distinct type name. For LOBs, the extended
SQLVAR contains the length attribute of the variable and a pointer
to the buffer that contains the actual length. If locators or file
reference variables are used to represent LOBs, an extended SQLVAR
is not necessary.
The extended SQLVAR entry is also needed for
each column when:
- USING BOTH is specified, which indicates that column names and
labels are returned.
- USING ALL is specified, which indicates that column names, labels,
and system column names are returned.
The fields in the extended SQLVAR that return LOB and distinct
type information do not overlap, and the fields that return LOB and
label information do not overlap. Depending on the combination of
labels, LOBs and distinct types, more than one extended SQLVAR entry
per column may be required to return the information. See Determining how many SQLVAR occurrences are needed.