Obtain input-parameter information

From a statement descriptor, you can obtain information about an input parameter once an SQL statement has been prepared. An input parameter indicates a value that is provided when the prepared statement executes.

The following table lists the accessor functions that obtain input-parameter information from the statement descriptor.
Table 1. Input-parameter information in the statement descriptor
Column information accessor function
The number of input parameters in the prepared statement mi_parameter_count()
The precision (total number of digits) of the column associated with an input parameter mi_parameter_precision()
The scale of a column that is associated with the input parameter mi_parameter_scale()
Whether the column associated with each input parameter was defined with the NOT NULL constraint mi_parameter_nullable()
The type identifier of the column that is associated with the input parameter mi_parameter_type_id()
The type name of the column that is associated with the input parameter mi_parameter_type_name()
Restriction: To modules, the input-parameter information in the statement descriptor (MI_STATEMENT) is part of an opaque C data structure. Do not access the internal fields of this structure directly. The internal structure of the MI_STATEMENT structure might change in future releases. Therefore, to create portable code, always use these accessor functions to obtain input-parameter information.
Input-parameter information is available only for the INSERT and UPDATE statements. Support for the UPDATE statement includes the following forms of UPDATE:
  • UPDATE with or without a WHERE clause
  • UPDATE WHERE CURRENT OF

If you attempt to request input-parameter information for other SQL statements, the input-parameter functions in Input-parameter information in the statement descriptor raise an exception.

The statement descriptor stores input-parameter information in several parallel arrays.
Input-parameter array Contents
Parameter-type ID array Each element is a pointer to a type identifier (MI_TYPEID) that indicates the data type of the input parameter.
Parameter-type name array Each element is a pointer to the string name of the data type for each input parameter.
Parameter-scale array Each element is the scale of the column associated with the input parameter.
Parameter-precision array Each element is the precision of the column associated with the input parameter.
Parameter-nullable array Each element is either MI_FALSE or MI_TRUE:
  • MI_FALSE indicates that the input parameter is associated with a column that cannot contain SQL NULL values.
  • MI_TRUE indicates that the input parameter is associated with a column that can contain SQL NULL values.

All of the input-parameter arrays in the statement descriptor have zero-based indexes. Within the statement descriptor, each input parameter in the prepared statement has a parameter identifier, which is the zero-based position of the input parameter within the input-parameter arrays. When you need information about an input parameter, specify its parameter identifier to one of the statement-descriptor accessor functions in Input-parameter information in the statement descriptor.

The following figure shows how the information at index position 1 of these arrays holds the input-parameter information for the second input parameter of a prepared statement.
Figure 1. Input-parameter arrays in the statement descriptor
To access information for the nth input parameter, provide an index value of n-1 to the appropriate accessor function in Input-parameter information in the statement descriptor. The following calls to the mi_parameter_type_id() and mi_parameter_nullable() functions obtain from the statement descriptor that stmt_desc identifies the type identifier (param_type) and whether the column is nullable (param_nullable) for the second input parameter:
MI_STATEMENT *stmt_desc;
MI_TYPEID *param_type;
mi_integer param_nullable;
...
param_type = mi_parameter_type_id(stmt_desc, 1);
param_nullable = mi_parameter_nullable(stmt_desc, 1);

To obtain the number of input parameters in the prepared statement (which is also the number of elements in the input-parameter arrays), use the mi_parameter_count() function.