DESCRIBE | Teradata Vantage - DESCRIBE - Advanced SQL Engine

Purpose

Obtains information about the data to be returned when a previously prepared dynamic SQL statement is executed.

Invocation

Executable.

Dynamic SQL.

Embedded SQL only.

Syntax

DESCRIBE statement_name INTO [:] descriptor_area
  [ USING { NAMES | ANY | BOTH | LABELS } ]
  [ FOR STATEMENT { statement_number | [:] statement_number_variable } ]

statement_name: The name associated with the previously prepared statement. Must be a valid SQL identifier, not enclosed within apostrophes.
descriptor_area: The area to receive the information about the data which will be returned when the previously prepared statement is executed.; Must identify an SQLDA.; You can specify descriptor_area in C programs as a name or as a pointer reference (*sqldaname) when SQLDA is declared as a pointer.
statement_number: The statement number within the request for which the information is required.; Must be a valid integer numeric literal.
statement_number_variable: The statement number within the request for which the information is required.; Must identify a host variable of type INTEGER or SMALLINT.

ANSI Compliance

DESCRIBE is a Teradata extension to the ANSI/ISO SQL:2011 standard.

DESCRIBE functions like the ANSI/ISO SQL:2011 statements DESCRIBE INPUT and DESCRIBE OUTPUT.

Authorization

None.

General Rules

An SQLDA must be defined.
The statement specified by statement_name must be prepared within the same transaction.
If the prepared statement is a non-data returning statement, no useful information is obtained other than verification that the prepared statement is not a data returning statement.
DESCRIBE itself cannot be executed as a dynamic SQL statement.

USING Clause Rules

IF this form of USING is specified …	THEN column …
NAMES	names are placed in the SQLNAME fields of the SQLDA. This also happens if you do not specify a USING clause.
LABELS	titles are placed in the SQLNAME fields of the SQLDA. If you specify a TITLE clause for a column in the select list, then that title is returned. If a column was defined with a TITLE at CREATE TABLE time and no title is specified in the SELECT statement, then the title specified for the CREATE TABLE statement is returned. In the absence of either, the default title, the column name, is returned.
BOTH	names and titles are placed in the SQLNAME fields of the SQLDA. In this case, the SQLVAR array must have two elements per column (2 * n elements) as follows: The first set of elements contains the names and column information. The second set contains the titles of the columns.
ANY	titles or names are placed in the SQLNAME fields of the SQLDA. If a column has a title, then that title is placed in the SQLNAME field. If a column has no title, then the column name is placed in the SQLNAME field.

FOR STATEMENT Clause Rules

The FOR STATEMENT clause is intended to support dynamic multistatement requests, but can also be used for single statement requests.
If you do not specify a FOR STATEMENT clause, the descriptive information is returned for the first or only SQL statement of the prepared dynamic SQL request.
If you specify a FOR STATEMENT clause, the descriptive information is returned for that SQL statement of the prepared dynamic SQL request that is identified by the integer numeric operand of the clause.
If there is no such statement (for example, if FOR STATEMENT 3 is coded and the request contains only two statements), the value -504 is returned in SQLCODE, and no information is returned.

DESCRIBE | Teradata Vantage - DESCRIBE - Advanced SQL Engine - Teradata Database

SQL Stored Procedures and Embedded SQL