Previous Topic: DELETENext Topic: DESCRIBE CURSOR

Statements › DESCRIBE

DESCRIBE

The DESCRIBE data compilation statement directs CA IDMS to return information about a dynamically-compiled SQL statement into an SQL descriptor area.

You can use this statement only in SQL that is embedded in a program.

Authorization

None required.

Syntax
►►─ DESCRIBE ─┬─ OUTPUT ◄──┬─ statement-name ─────────────────────────────────►
              └─ INPUT ────┘

 ►─ USING sql DESCRIPTOR descriptor-area-name1 ───────────────────────────────►

 ►─┬─────────────────────────────────────────────────────────┬────────────────►◄
   ├─ INPUT ──┬─ USING sql DESCRIPTOR descriptor-area-name2 ─┘
   └─ OUTPUT ─┘

Note: If DESCRIBE OUTPUT is specified or implied, you may only specify the INPUT USING parameter; similarly, if DESCRIBE INPUT is specified, you may only specify the OUTPUT USING parameter.

Note: For compatibility with earlier releases, you can specify "INTO sql descriptor" in place of "USING sql DESCRIPTOR"; however, this is an extension to the SQL standard.
Parameters
INPUT/OUTPUT

Specifies the type of information to be returned in the associated descriptor area. INPUT means that information about dynamic parameters is to be returned in the SQL descriptor area. OUTPUT means that information about output values is to be returned.

statement-name

Specifies the name of the statement being described.

Note: For more information about the expansion of statement-name, see Expansion of Statement-name.

USING SQL DESCRIPTOR

Specifies the SQL descriptor area where CA IDMS is to return information about the named statement.

descriptor-area-name1

Directs CA IDMS to use the named area as the descriptor area. Descriptor-area-name1 must identify an SQL descriptor area.

INPUT/OUTPUT USING SQL DESCRIPTOR descriptor-area-name2

Specifies the type of information to be returned in the associated descriptor area. INPUT means that information about dynamic parameters is to be returned in the SQL descriptor area. OUTPUT means that information about output values is to be returned.

Descriptor-area-name2 is the name of the SQL descriptor area.

Note: If DESCRIBE OUTPUT is specified or implied, you may only specify the INPUT USING parameter; similarly, if DESCRIBE INPUT is specified, you may only specify the OUTPUT USING parameter.

The ability to specify INPUT/OUTPUT USING SQL DESCRIPTOR descriptor-area-name2 is a CA IDMS extension to the SQL standard.

Usage

Describing Dynamic Parameters

The INPUT option is used to return information about dynamic parameters that may be embedded in the SQL statement being described. The SQLD field of the descriptor area indicates the number of dynamic parameters that appear in the statement. If no dynamic parameters are used, this field is zero (0).

If dynamic parameters do appear in the statement, CA IDMS returns descriptions of the parameters in the descriptor area. The data type information is derived from the context in which the dynamic parameter appears.

Describing Output Values

The OUTPUT option is used to return information about values output from CA IDMS:

Specifying the Maximum Number of Column Entries

The application program must specify the maximum number of entries it can accept by setting the value of the SQLN field of the descriptor area before issuing the DESCRIBE statement. If the number of entries is insufficient to hold all the requested information, CA IDMS returns the number of entries needed into the SQLD field but does not return any descriptions.

Example

Describing a Dynamically Compiled Statement

The following DESCRIBE statement returns information about the result table of the dynamically compiled statement named DYN_TEMP_SEL_1 in the descriptor area named SQLDA:

EXEC SQL
   DESCRIBE DYN_TEMP_SEL_1
      USING DESCRIPTOR SQLDA
END-EXEC
More Information