DB2 10.5 for Linux, UNIX, and Windows

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