Hitachi

Hitachi Advanced Database Application Development Guide


19.4.7 a_rdb_SQLDescribeParams() (acquire dynamic parameter information)

Organization of this subsection

(1) Function

This CLI function acquires an SQL statement's dynamic parameter information. The information that is acquired includes the following:

(2) Format

signed short a_rdb_SQLDescribeParams
(
  void                          *ConnectionHandle,   /* In  */
  void                          *StatementHandle,    /* In  */
  unsigned short                 ParameterCount,     /* In  */
  a_rdb_SQLParameterInfo_t      *ParameterInfo,      /* Out */
  void                          *Option              /* In  */
)

(3) Arguments

ConnectionHandle

Specifies a connection handle.

StatementHandle

Specifies a statement handle.

ParameterCount

Specifies the number of dynamic parameters for which information is to be acquired.

Specify the number of dynamic parameters acquired by a_rdb_SQLNumParams().

ParameterInfo

Specifies the start address of the parameter information area in which the addresses of the various parameter information acquisition areas are to be set.

Provide an area in which as many a_rdb_SQLParameterInfo_t structures as is specified for ParameterCount can be placed consecutively.

For details about the a_rdb_SQLParameterInfo_t structure, see 19.7.5 a_rdb_SQLParameterInfo_t structure (parameter information).

Option

Specifies NULL.

(4) Return value

  1. If a_rdb_SQLDescribeParams() terminates normally, a_rdb_RC_SQL_SUCCESS is returned.

  2. If dynamic parameter information is acquired successfully, but the disk containing client message log files has become full, a_rdb_RC_SQL_WARNING is returned.

  3. If an error occurs while messages cannot be output to the client message log file, the error cause code is returned. For details about the error cause code, see 19.8 Return values of the CLI functions.

(5) Notes

  1. Codes assumed by HADB (data type codes) indicating the data types of the dynamic parameters are acquired in the data type code storage area of the a_rdb_SQLDataType_t structure. For details about the data type code for each data type, see List of data types in the manual HADB SQL Reference.

  2. The maximum number of elements in a dynamic parameter is acquired in the maximum elements count storage area of the a_rdb_SQLDataType_t structure. The maximum number of elements in a dynamic parameter is always 1.

  3. Information about the data length of a dynamic parameter is stored in the parameter length storage area and the parameter attribute storage area of the a_rdb_SQLDataType_t structure. The value to be acquired in each area depends on the data type of the dynamic parameter assumed by HADB, as shown in the following table.

    Table 19‒5: Parameter length and parameter length attribute

    No.

    Data type

    Parameter length

    Parameter length attribute

    1

    INTEGER

    8

    0

    2

    SMALLINT

    4

    0

    3

    DECIMAL(m,n)#1

    m

    n

    4

    DOUBLE PRECISION

    8

    0

    5

    CHAR(n)

    n

    0

    6

    VARCHAR(n)

    n

    0

    7

    DATE

    4

    0

    8

    TIME(p)#2

    3 + ↑p ÷ 2↑

    p

    9

    TIMESTAMP(p)#2

    7 + ↑p ÷ 2↑

    p

    10

    BINARY(n)

    n

    0

    11

    VARBINARY(n)

    n

    0

    12

    ROW

    row-length

    0

    Legend:

    m, n, p: Positive integer

    #1

    If the data type is DECIMAL, the precision is set as the parameter length and the scaling is set as the parameter length attribute.

    #2

    If the data type is TIME or TIMESTAMP, the data length is set as the column length and the length of the fractional seconds is set as the column length attribute.

  4. a_rdb_SQLDescribeParams() cannot be executed in the following cases:

    • Connection has not been established.

    • An invalid statement handle is specified.

    • The specified number of dynamic parameters is not the value acquired by a_rdb_SQLNumParams().