SQLExtendedBind function (CLI) - Bind an array of columns

Binds an array of columns or parameters instead of using repeated calls to SQLBindCol() or SQLBindParameter().

Specification:

  • CLI 6

Syntax

SQLRETURN    SQLExtendedBind (    
                              SQLHSTMT          StatementHandle, /* hstmt */
                              SQLSMALLINT       fBindCol,
                              SQLSMALLINT       cRecords,
                              SQLSMALLINT *     pfCType,
                              SQLPOINTER  *     rgbValue,
                              SQLINTEGER  *     cbValueMax,
                              SQLUINTEGER *     puiPrecisionCType,
                              SQLSMALLINT *     psScaleCType,
                              SQLINTEGER  **    pcbValue,
                              SQLINTEGER  **    piIndicator,
                              SQLSMALLINT *     pfParamType,
                              SQLSMALLINT *     pfSQLType,
                              SQLUINTEGER *     pcbColDef,
                              SQLSMALLINT *     pibScale ) ;

Function arguments

Table 1. SQLExtendedBind() arguments
Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.
SQLSMALLINT fBindCol input If SQL_TRUE then the result is similar to SQLBindCol(), otherwise, it is similar to SQLBindParameter().
SQLSMALLINT cRecords input Number of columns or parameters to bind.
SQLSMALLINT * pfCType input Array of values for the application data type.
SQLPOINTER * rgbValue input Array of pointers to application data area.
SQLINTEGER * cbValueMax input Array of maximum sizes for rgbValue.
SQLUINTEGER * puiPrecisionCType input Array of decimal precision values. Each value is used only if the application data type of the corresponding record is SQL_C_DECIMAL_IBM.
SQLSMALLINT * psScaleCType input Array of decimal scale values. Each value is used only if the application data type of the corresponding record is SQL_C_DECIMAL_IBM.
SQLINTEGER ** pcbValue input Array of pointers to length values.
SQLINTEGER ** piIndicator input Array of pointers to indicator values. The piIndicator argument allows the constants SQL_UNASSIGNED and SQL_DEFAULT_PARAM to pass through the method, when extended indicator feature is enabled using the SQL_ATTR_EXTENDED_INDICATORS attribute.
SQLSMALLINT * pfParamType input Array of parameter types. Only used if fBindCol is FALSE.
Each row in this array serves the same purpose as the SQLBindParameter() argument InputOutputType. It can be set to:
  • SQL_PARAM_INPUT
  • SQL_PARAM_INPUT_OUTPUT
  • SQL_PARAM_OUTPUT
SQLSMALLINT * pfSQLType input Array of SQL data types. Only used if fBindCol is FALSE.

Each row in this array serves the same purpose as the SQLBindParameter() argument ParameterType.
SQLUINTEGER * pcbColDef input Array of SQL precision values. Only used if fBindCol is FALSE.

Each row in this array serves the same purpose as the SQLBindParameter() argument ColumnSize.
SQLSMALLINT * pibScale input Array of SQL scale values. Only used if fBindCol is FALSE.

Each row in this array serves the same purpose as the SQLBindParameter() argument DecimalDigits.

Usage

The argument fBindCol determines whether this function call is used to associate (bind):
  • parameter markers in an SQL statement (as with SQLBindParameter()) - fBindCol = SQL_FALSE
  • columns in a result set (as with SQLBindCol()) - fBindCol = SQL_TRUE

This function can be used to replace multiple calls to SQLBindCol() or SQLBindParameter(), however, important differences should be noted.

Depending on how the fBindCol parameter has been set, the input expected by SQLExtendedBind() is similar to either SQLBindCol() or SQLBindParameter() with the following exceptions:
  • When SQLExtendedBind() is set to SQLBindCol() mode:
    • targetValuePtr must be a positive integer that specifies in bytes, the maximum length of the data that will be in the returned column.
  • When SQLExtendedBind() is set to SQLBindParameter() mode:
    • ColumnSize must be a positive integer that specifies the maximum length of the target column in bytes, where applicable.
    • DecimalDigits must be set to the correct scale for the target column, where applicable.
    • ValueType of SQL_C_DEFAULT should not be used.
    • If ValueType is a locator type, the corresponding ParameterType should be a matching locator type.
    • All ValueType to ParameterType mappings should be as closely matched as possible to minimize the conversion that CLI must perform.

Each array reference passed to SQLExtendedBind() must contain at least the number of elements indicated by cRecords. If the calling application fails to pass in sufficiently large arrays, CLI may attempt to read beyond the end of the arrays resulting in corrupt data or critical application failure.

Each array passed to SQLExtendedBind() is considered to be a deferred argument, which means the values in the array are examined and retrieved at the time of execution. As a result, ensure that each array is in a valid state and contains valid data when CLI executes using the values in the array. Following a successful execution, if a statement needs to be executed again, you do not need to call SQLExtendedBind() a second time if the handles passed to the original call to SQLExtendedBind() still refer to valid arrays.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLExtendedBind() SQLSTATEs
SQLSTATE Description Explanation
07006 Invalid conversion. The conversion from the data value identified by a row in the pfCType argument to the data type identified by the pfParamType argument is not a meaningful conversion. (For example, conversion from SQL_C_TYPE_DATE to SQL_DOUBLE.)
07009 Invalid descriptor index The value specified for the argument cRecords exceeded the maximum number of columns in the result set.
40003 08S01 Communication link failure. The communication link between the application and data source failed before the function completed.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. Db2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY003 Program type out of range. A row in pfParamType or pfSQLType was not a valid data type or SQL_C_DEFAULT.
HY004 SQL data type out of range. The value specified for the argument pfParamType is not a valid SQL data type.
HY009 Invalid argument value. The argument rgbValue was a null pointer and the argument cbValueMax was a null pointer, and pfParamType is not SQL_PARAM_OUTPUT.
HY010 Function sequence error. The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation.

The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation.
HY013 Unexpected memory handling error. Db2 CLI was unable to access memory required to support execution or completion of the function.
HY021 Inconsistent descriptor information The descriptor information checked during a consistency check was not consistent.
HY090 Invalid string or buffer length. The value specified for the argument cbValueMax is less than 1 and the argument the corresponding row in pfParamType or pfSQLType is either SQL_C_CHAR, SQL_C_BINARY or SQL_C_DEFAULT.
HY093 Invalid parameter number. The value specified for a row in the argument pfCType was less than 1 or greater than the maximum number of parameters supported by the server.
HY094 Invalid scale value. The value specified for pfParamType was either SQL_DECIMAL or SQL_NUMERIC and the value specified for DecimalDigits was less than 0 or greater than the value for the argument pcbColDef (precision).

The value specified for pfParamType was SQL_C_TYPE_TIMESTAMP and the value for pfParamType was either SQL_CHAR or SQL_VARCHAR and the value for DecimalDigits was less than 0 or greater than 9.

The value specified for pfParamType was SQL_C_TIMESTAMP_EXT and the value for DecimalDigits was less than 0 or greater than 12.
HY104 Invalid precision value. The value specified for pfParamType was either SQL_DECIMAL or SQL_NUMERIC and the value specified by pcbColDef was less than 1.
HY105 Invalid parameter type. pfParamType is not one of SQL_PARAM_INPUT, SQL_PARAM_OUTPUT, or SQL_PARAM_INPUT_OUTPUT.
HYC00 Driver not capable. CLI recognizes, but does not support the data type specified in the row in pfParamType or pfSQLType.

A LOB locator C data type was specified, but the connected server does not support LOB data types.

Restrictions

None