If the program has no advance knowledge of the resulting columns, the first step in executing a dynamic SELECT statement is to prepare and describe the statement. Preparing the statement encodes and saves the statement and assigns it a name. For information about the syntax and use of PREPARE, see Prepare and Execute Statements (see page Prepare and Execute Statements).

The DESCRIBE statement returns descriptive information about a prepared statement into a program descriptor, that is, an SQLDA structure. This statement is primarily used to return information about the result columns of a SELECT statement to the program, but other statements can be described. When describing a non‑select statement, the only information returned to the program is that the statement was not a SELECT statement.

The DESCRIBE statement has the following syntax:

EXEC SQL DESCRIBE statement_name INTO|USING descriptor_name;

When a SELECT statement is described, OpenSQL returns the information about each result column to a sqlvar element (described in Structure of the SQLDA (see page Structure of the SQLDA)). This is a one‑to‑one correspondence: the information in one sqlvar element corresponds to one result column. Before issuing the DESCRIBE statement, the program must allocate sufficient sqlvar elements and set the SQLDA sqln field to the number of allocated sqlvars. The program must set sqln before the DESCRIBE statement is issued.

After issuing the DESCRIBE statement, the program must check the value of sqld, which contains the number of sqlvar elements actually used to describe the statement. If sqld is zero, the prepared statement was not a SELECT statement. If sqld is greater than sqln, the SQLDA does not have enough sqlvar elements: more storage must be allocated and the statement must be redescribed.

The following fragment shows a typical DESCRIBE statement and the surrounding host program code. The program assumes that 20 sqlvar elements will be sufficient: