DESCRIBE
Function
The DESCRIBE statement makes information about a prepared statement available to the application program.
Invocation
Embedded Mode P Dynamic Mode Interactive Mode
Syntax
statement_identifier | A valid identifier denoting the prepared statement of which the information is to be retrieved. |
host_variable_identifier | A valid single host variable identifier. It must have been defined in the application program according to the host language rules. The value of the host variable must be the value returned by the PREPARE statement and thus identifying the prepared statement. |
OUTPUT hvu | The definition of the SQL descriptor area used to describe the expected output of the identified statement. |
INPUT hvu | The definition of the SQL descriptor area used to describe the expected input of the identified statement. |
host_variable_specification | A valid single host variable identifier and must have been defined in the application program according to the host- language-dependent rules. The value of the host variable must be the address of an SQL descriptor area (SQLDA). |
Description
The DESCRIBE statement places information about the prepared statement identified by statement identifier or host variable identifier in one or two SQL descriptor areas.
The keyword OUTPUT is relevant only if the prepared statement is a SELECT statement. In this case, the SQL descriptor area indicated by host variable identifier 2 is filled with information concerning the elements in the derived column list of the SELECT statement. For each element in the derived column list, an element in the SQL descriptor area is filled. The elements in the derived column list are processed from left to right and the descriptive elements in the SQL descriptor area are filled in the that order.
The keyword INPUT is relevant only if the prepared statement contains host variable markers, i.e., "?". In this case, the SQL descriptor area indicated by host variable identifier 2 is filled with information concerning the host variable markers used in the prepared statement. For each host variable marker, an element in the SQL descriptor area is filled. The host variable markers are processed in the order that they appear in the prepared statements. The descriptive elements in the SQL descriptor area are filled in that order.
If the prepared statement is a SELECT statement where host variable markers have been used, the usage of not only the OUTPUT clause but also the INPUT clause is recommended.
Limitations
The statement indicated by statement identifier or host variable identifier 1 must be a successfully prepared statement.
If not enough elements have been provided in the SQL descriptor area to cater for the total number of elements that need to be described, all the elements that can be catered for are described, the rest of the information is ignored. The actual number of elements required is returned in field SQLN in the SQLDA.
ANSI Specifics
None.
CONNX Embedded SQL Specifics
This statement can be mixed with any other DML, DDL and/or DCL statements in the same transaction.
Here is an example:
DESCRIBE statement_identifier INTO
OUTPUT :sqlda_address ;
