Call Level Interface Guide and Reference

SQLExtendedBind - Bind an Array of Columns

Purpose

Specification: DB2 CLI 6

SQLExtendedBind() is used to bind an array of columns instead of using repeated calls to SQLBindCol() or SQLBindParameter().

Syntax

SQLRETURN    SQLExtendedBind (    
                              SQLHSTMT          StatementHandle,
                              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 61. SQLExtendedBind() Arguments

Data Type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.
SQLSMALLINT fBindCol input If SQL_TRUE then this output information similar to SQLBindCol(), otherwise, it is similar to SQLBindParameter().
SQLSMALLINT cRecords input Number of columns 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 Decimal precision of record. Only used if the application data type is SQL_C_DECIMAL_IBM.
SQLSMALLINT psScaleCType input Decimal scale of record. Only used if the application data type is SQL_C_DECIMAL_IBM.
SQLINTEGER pcbValue input Array of pointers to length values.
SQLINTEGER piIndicator input Array of pointers to indicator values.
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.

Data Type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Statement handle.
SQLSMALLINT	fBindCol	input	If SQL_TRUE then this output information similar to `SQLBindCol()`, otherwise, it is similar to `SQLBindParameter()`.
SQLSMALLINT	cRecords	input	Number of columns 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	Decimal precision of record. Only used if the application data type is SQL_C_DECIMAL_IBM.
SQLSMALLINT	psScaleCType	input	Decimal scale of record. Only used if the application data type is SQL_C_DECIMAL_IBM.
SQLINTEGER	pcbValue	input	Array of pointers to length values.
SQLINTEGER	piIndicator	input	Array of pointers to indicator values.
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

This function is used to replace multiple calls to SQLBindCol() or SQLBindParameter().

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

For more information (including allowed argument values), see SQLBindCol - Bind a Column to an Application Variable or LOB Locator and SQLBindParameter - Bind A Parameter Marker to a Buffer or LOB Locator

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 62. 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_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.
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_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 6.
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. DB2 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.

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_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.
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_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 6.
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.	DB2 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.

Example

See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.

References

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]