DESCRIBE INPUT

The DESCRIBE INPUT statement obtains information about the IN and INOUT parameter markers of a prepared statement. For an explanation of prepared statements, see PREPARE.

This statement can only be embedded in an application program, SQL function, SQL procedure, or trigger. It is an executable statement that cannot be dynamically prepared. It must not be specified in Java™ or REXX.

Authorization

None required.

Syntax

>>-DESCRIBE INPUT--statement-name------------------------------->
 
            .-SQL-.              .-LOCAL--.
>--+-USING--+-----+--DESCRIPTOR--+--------+--SQL-descriptor-name-+-><
   |                             '-GLOBAL-'                      |
   '-INTO----descriptor-name-------------------------------------'

Description

statement-name

Identifies the prepared statement. When the DESCRIBE INPUT statement is executed, the name must identify a prepared statement at the application server.

USING

Identifies an SQL descriptor.

LOCAL: Specifies the scope of the name of the descriptor to be local to program invocation.
GLOBAL: Specifies the scope of the name of the descriptor to be global to the SQL session.
SQL-descriptor-name: Names the SQL descriptor. The name must identify a descriptor that already exists with the specified scope.

INTO descriptor-name

Identifies an SQL descriptor area (SQLDA), which is described in Appendix D. SQLDA (SQL descriptor area). Before the DESCRIBE INPUT statement is executed, the following variable in the SQLDA must be set.

SQLN: Specifies the number of SQLVAR occurrences provided in the SQLDA. SQLN must be set to a value greater than or equal to zero before the DESCRIBE INPUT statement is executed. For information on techniques to determine the number of occurrences requires, see Determining how many SQLVAR occurrences are needed.

When the DESCRIBE INPUT statement is executed, the database manager assigns values to the variables of the SQLDA as follows:

SQLDAID

The first 6 bytes are set to 'SQLDA ' (that is, 5 letters followed by the space character).

The seventh byte is set based on the parameter markers described:

If the SQLDA contains two SQLVAR entries for every input parameter, the seventh byte is set to '2'. This technique is used in order to accommodate LOB input parameters.
Otherwise, the seventh byte is set to the space character.

The seventh byte is set to the space character if there is not enough room in the SQLDA to contain the description of all input parameter markers.

The eighth byte is set to the space character.

SQLDABC

Length of the SQLDA in bytes.

SQLD

The number of input parameter markers in the prepared statement.

SQLVAR

If the value of SQLD is 0, or greater than the value of SQLN, no values are assigned to occurrences of SQLVAR.

If the value of SQLD is n, where n is greater than 0 but less than or equal to the value of SQLN, values are assigned to the first n occurrences of SQLVAR so that the first occurrence of SQLVAR contains a description of the first input parameter marker, the second occurrence of SQLVAR contains a description of the second input parameter marker, and so on. For information on the values assigned to SQLVAR occurrences, see Field descriptions in an occurrence of SQLVAR.

Notes

Allocating the SQL descriptor: Before the DESCRIBE INPUT statement is executed, the SQL descriptor must be allocated using the ALLOCATE DESCRIPTOR statement. The number of descriptor items allocated must not be less than the number of input parameter markers or an error is returned.

Allocating the SQLDA: Before the DESCRIBE INPUT statement is executed, the value of SQLN must be set to a value greater than or equal to zero to indicate how many occurrences of SQLVAR are provided in the SQLDA and enough storage must be allocated to contain SQLN occurrences. To obtain the description of the input parameter markers in the prepared statement, the number of occurrences of SQLVAR must not be less than the number of input parameter markers. Furthermore, if the input parameter markers include LOBs, the number of occurrences of SQLVAR should be two times the number of input parameter markers. See Determining how many SQLVAR occurrences are needed for more information.

If not enough occurrences are provided to return all sets of occurrences, SQLN is set to the total number of occurrences necessary to return all information. Otherwise, SQLN is set to the number of input parameter markers.

For a description of techniques that can be used to allocate the SQLDA, see Appendix D. SQLDA (SQL descriptor area).

Examples

Example 1: Allocate a descriptor called 'NEWDA' large enough to hold 20 item descriptor areas and use it on DESCRIBE INPUT.

  EXEC SQL ALLOCATE DESCRIPTOR 'NEWDA'
    WITH MAX 20;

  EXEC SQL DESCRIBE INPUT STMT1
    USING SQL DESCRIPTOR 'NEWDA';

Example 2: Execute a DESCRIBE INPUT statement with an SQLDA that has enough SQLVAR occurrences to describe any number of input parameters a prepared statement might have. Assume that five parameter markers at most will need to be described and that the input data does not contain LOBs.

  /* STMT1_STR contains INSERT statement with VALUES clause */
    char table_name[201];
  EXEC SQL  PREPARE STMT1_NAME
              FROM :STMT1_STR;

  ... /* code to set SQLN to 5 and to allocate the SQLDA */
  EXEC SQL  DESCRIBE INPUT  STMT1_NAME INTO  :SQLDA;

  .
  .
  .

This example uses the first technique described in Appendix D. SQLDA (SQL descriptor area).