DESCRIBE INPUT

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

The statement can be executed if the privilege set for PREPARE includes the EXPLAIN privilege.

Description

statement-name

Identifies the prepared statement. When the DESCRIBE INPUT statement is executed, the name must identify a statement that has been prepared by the application process at the current server.

INTO descriptor-name

Identifies an SQL descriptor area (SQLDA), which is described in SQL descriptor area (SQLDA). See Identifying an SQLDA in C or C++ for how to represent descriptor-name in C. The information returned in the SQLDA describes the parameter markers.

Before the DESCRIBE INPUT statement is executed, the user must set the SQLN field in the SQLDA and the SQLDA must be allocated. Considerations for initializing and allocating the SQLDA are similar to those for the DESCRIBE statement (see DESCRIBE). An occurrence of an extended SQLVAR is needed for each parameter in addition to the required base SQLVAR only if the input data contains LOBs.

For REXX: The SQLDA is not allocated before it is used.

After the DESCRIBE INPUT statement is executed, all the fields in the SQLDA except SQLN are either set by DB2® or ignored. The SQLDA contents are similar to the contents returned for the DESCRIBE statement (see The SQLDA contents returned after DESCRIBE) with these exceptions:

• In the SQLDAID, DB2 sets the value of the seventh byte only to the space character or '2'. A value of '3' is never used. The value '2' indicates that two SQLVAR entries (an occurrence of both a base SQLVAR and an extended SQLVAR) are required for each parameter because the input data contains LOBs. The seventh byte is a space character when either of the following conditions is true:
  • The input data does not contain LOBs. Only a base SQLVAR occurrence is needed for each parameter.
  • Only a base SQLVAR occurrence is needed for each column of the result, and the SQLDA is not large enough to contain the returned information.
• The SQLD field is set to the number of parameter markers being described. The value is 0 if the statement being described does not have input parameter markers.
• The SQLNAME field is not used.
• The SQLDATATYPE is set to a nullable, regardless of the usage of the parameter markers in the prepared statement.
• The SQLDATATYPE-NAME is not used if an extended SQLVAR entry is present. DESCRIBE INPUT does not return information about distinct types.

For complete information on the contents of the fields, see SQL descriptor area (SQLDA).

Notes

Preparing the SQLDA for OPEN or EXECUTE: This note is relevant if you are applying DESCRIBE INPUT to a prepared statement and you intend to use the SQLDA in an OPEN or EXECUTE statement. To prepare the SQLDA for that purpose:

• Set SQLDATA to a valid address.
• If SQLTYPE is odd, set SQLIND to a valid address.

For the meaning of those fields in that context, see SQL descriptor area (SQLDA).

Support for extended dynamic SQL in a distributed environment: Unlike the DESCRIBE statement, which can be used in a distributed environment to describe static SQL statements generated by extended dynamic SQL, you cannot describe host variables in static SQL statements that are generated by extended dynamic SQL. A DESCRIBE INPUT statement issued against such static SQL statements always fails.

For information on how the DESCRIBE statement supports extended dynamic SQL, see Support for extended dynamic SQL in a distributed environment.

Using host variables: If the DESCRIBE INPUT statement contains host variables, the contents of the host variables are assumed to be in the encoding scheme that was specified in the ENCODING parameter when the package or plan that contains the statement was bound.

Example

      /* STMT1_STR contains INSERT statement with VALUES clause  */
   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 Allocating the SQLDA to allocate the SQLDA.