DESCRIBE statement Format 1 (Receive retrieval information and I/O information)
Function
Receives into an SQL descriptor area the retrieval item information or output ? parameter information (such as data code and data length) of an SQL statement pre-processed by a PREPARE statement.
For details about the information to be received, see the HiRDB Version 9 UAP Development Guide. If the SQL statement pre-processed by the PREPARE statement does not have SQL retrieval item information or output ? parameter information, 0 is set in the SQLD area of the SQL descriptor area.
Privileges
Format 1: Receiving retrieval information or output ? parameter information
DESCRIBE [OUTPUT]{ SQL-statement-identifier | extended-statement-name} INTO
[:]SQL-descriptor-area-name
[[:]Column-Name-Descriptor-Area-name]
[TYPE[:]Type-Name-Descriptor-Area-name]
[CHARACTER_SET[:]character-set-descriptor-area-name]
Operands
- {SQL-statement-identifier | extended-statement-name}
- SQL-statement-identifier
Specifies the SQL statement identifier that was specified in the PREPARE statement.
Specifies the extended statement name that identifies the SQL statement preprocessed by the PREPARE statement.
For extended statement names, see 2.26 Extended statement name.
- [:]SQL-descriptor-area-name[[:]Column-Name-Descriptor-Area-name]
- SQL-descriptor-area-name
- Specifies the name of the SQL descriptor area that is to receive SQL retrieval item information (if the preprocessed SQL is a SELECT statement) or output ? parameter information (if the preprocessed SQL is a CALL statement).
- For SQL descriptor areas, see the HiRDB Version 9 UAP Development Guide.
- Column-Name-Descriptor-Area-name
- Specifies the Column Name Descriptor Area that is to receive the names retrieval items or the parameter names of routines.
- For Column Name Descriptor Areas, see the HiRDB Version 9 UAP Development Guide.
- [TYPE:]Type-Name-Descriptor-Area-name]
- Type-Name-Descriptor-Area-name
- Specifies the name of the Type Name Descriptor Area for receiving a user-defined data type name for a retrieval item.
- For Type Name Descriptor Areas, see the HiRDB Version 9 UAP Development Guide.
- [CHARACTER_SET[:]character-set-descriptor-area-name]
- character-set-descriptor-area-name
- Specify a character set descriptor area in which the character set name for retrieval item information (if the preprocessed SQL is a SELECT statement), or output ? parameter information (if the preprocessed SQL is a CALL statement) is to be stored.
- For details about character set descriptor areas, see the HiRDB Version 9 UAP Development Guide.
Common rules
- Before executing the DESCRIBE statement, the UAP should set the number of SQLVARs (SQLN areas) in the SQL descriptor area.
- Both SQLDATA and SQLIND are cleared when the DESCRIBE statement executes. Therefore, executing the DESCRIBE statement is executed, appropriate values must be set in SQLDATA and SQLIND.
- When a Column Name Descriptor Area is specified, the WITH SQLNAME OPTION must be specified in the associated PREPARE statement.
- Specify a Column Name Descriptor Area name only when the names of retrieval items or the parameter names of routines are to be received. However, the parameter name of a routine can be received only when a ? parameter is specified singly in an argument of the CALL statement. If a value expression containing a ? parameter is specified, the length of the name of the Column Name Descriptor Area is 0.
- When a Type Name Descriptor Area name is specified, WITH [ALL] TYPE OPTION must be specified in the corresponding PREPARE statement.
- Specify a Type Name Descriptor Area name only when a user-defined data type name is to be received for a retrieval item.
- Specify a character set descriptor area only if a character set has to be specified for retrieval item information (if the preprocessed SQL is a SELECT statement), or output ? parameter information (if the preprocessed SQL is a CALL statement) for which the data type is character data.
Notes
- As an embedded variable name, an SQL statement identifier is effective in a compile-unit file. Multiple SQL statements referencing the same SQL statement identifier cannot be used in multiple modules.
- If the output ? parameter is a procedure of a user-defined data type, the data type name information will not be set in the output ? parameter of the user-defined data type.
- Even if a DESCRIBE [OUTPUT] statement is not used, the same information as that obtained by using DESCRIBE [OUTPUT] can be obtained by specifying OUTPUT in a PREPARE statement.
Examples
- Specify retrieval item information on the SELECT statement (SQL statement identifier: PRESQL) preprocessed by the PREPARE statement, the names of retrieval items, or the parameter names of routines in the SQL descriptor area and in the Column Name Descriptor Area:
DESCRIBE PRESQL INTO :SQLDA :SQLCNDA
- Specify retrieval item information and the names of retrieval items for the SELECT statement (extended statement name: pre) preprocessed by the PREPARE statement in the SQL descriptor area and the Column Name Descriptor Area.
PREPARE GLOBAL :pre FOR :sel WITH SQLNAME OPTION
DESCRIBE GLOBAL :pre INTO :SQLDA :SQLCNDA