Valid in: ESQL
The Describe statement retrieves information about the result of a prepared dynamic SQL statement. This statement returns the data type, length, and name of the result columns of the prepared select. If the prepared statement is not a select, describe returns a zero in the SQLDA sqld field.
The Describe statement has the following format:
EXEC SQL DESCRIBE statement_name INTO|USING [:]descriptor_name [USING NAMES];
Specifies a valid prepared statement. Specify the statement_name using a string literal or a host language string variable. If an error occurs when the specified statement is prepared, the statement is not valid. If a commit or rollback statement is executed after the statement is prepared and before it is executed, the statement is discarded and cannot be described or executed.
Identifies an SQLDA. The descriptor name can be SQLDA or any other valid object name defined by the program when the structure is allocated. Because the SQLDA is not declared in a declaration section, the preprocessor does not verify that descriptor_name represents an SQLDA structure. If descriptor_name does not represent an SQLDA structure, undefined errors occur at runtime. For information about the structure of an SQLDA and its allocation and inclusion in an embedded program, see the Embedded SQL Companion Guide.
Directs the DBMS Server to return the names of result columns in the descriptor if the described statement is a select statement. (The USING NAMES clause is optional and has no effect on the results of the DESCRIBE statement.)
The DESCRIBE statement cannot be issued until after the program allocates the SQLDA and sets the value of the SQLDA's sqln field to the number of elements in the SQLDA's sqlvar array. The results of the DESCRIBE statement are complete and valid only if the number of the result columns (from the select) is less than or equal to the number of allocated sqlvar elements. (The maximum number of result columns that can be returned is 1024.)
The PREPARE statement can also be used with the INTO clause to retrieve the same descriptive information provided by describe. For examples of the DESCRIBE statement and information about using the information it returns, see the Embedded SQL Companion Guide.
All users are permitted to use this statement.