SQLBindParam - Bind a buffer to a parameter marker

Purpose

SQLBindParam() has been deprecated and replaced by SQLBindParameter(). Although this version of DB2^® UDB CLI continues to support SQLBindParam(), it is recommended that you begin using SQLBindParameter() in your DB2 UDB CLI programs so that they conform to the latest standards.

SQLBindParam() binds an application variable to a parameter marker in an SQL statement. This function can also be used to bind an application variable to a parameter of a stored procedure CALL statement where the parameter can be input or output.

Syntax

SQLRETURN SQLBindParam (SQLHSTMT    hstmt,
                        SQLSMALLINT ipar,
                        SQLSMALLINT fCType,
                        SQLSMALLINT fSqlType,
                        SQLINTEGER  cbParamDef,
                        SQLSMALLINT ibScale,
                        SQLPOINTER  rgbValue,
                        SQLINTEGER  *pcbValue);

Function arguments

Table 1. SQLBindParam arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle.
SQLINTEGER *	pcbValue	Input (deferred), or output (deferred), or both	A variable whose value is interpreted when the statement is processed: If a null value is used as the parameter, pcbValue must contain the value SQL_NULL_DATA. If the dynamic argument is supplied at execute-time by calling `ParamData()` and `PutData()`, pcbValue must contain the value SQL_DATA_AT_EXEC. If fcType is SQL_CHAR and the data in rgbValue contains a null-terminated string, pcbValue must either contain the length of the data in rgbValue or contain the value SQL_NTS. If fcType is SQL_CHAR and the data in rgbValue is not null-terminated, pcbValue must contain the length of the data in rgbValue. If fcType is an LOB type, pcbValue must contain the length of the data in rgbValue. This length value must be specified in bytes, not the number of double byte characters. Otherwise, pcbValue must be zero.
SQLINTEGER	cbParamDef	Input	Precision of the corresponding parameter marker. If fSqlType denotes a single-byte character string (for example, SQL_CHAR), this is the maximum length in bytes sent for this parameter. This length includes the null-termination character. If fSqlType denotes a double-byte character string (for example, SQL_GRAPHIC), this is the maximum length in double-byte characters for this parameter. If fSqlType denotes SQL_DECIMAL or SQL_NUMERIC, this is the maximum decimal precision. Otherwise, this argument is unused.
SQLPOINTER	rgbValue	Input (deferred) or output (deferred)	At processing time, if pcbValue does not contain SQL_NULL_DATA or SQL_DATA_AT_EXEC, then rgbValue points to a buffer that contains the actual data for the parameter. If pcbValue contains SQL_DATA_AT_EXEC, then rgbValue is an application-defined 32-bit value that is associated with this parameter. This 32-bit value is returned to the application through a later `SQLParamData()` call.
SQLSMALLINT	fCType	Input	Application data type of the parameter. The following types are supported: SQL_BIGINT SQL_BINARY SQL_BLOB SQL_BLOB_LOCATOR SQL_CHAR SQL_CLOB SQL_CLOB_LOCATOR SQL_DATETIME SQL_DBCLOB SQL_DBCLOB_LOCATOR SQL_DECIMAL SQL_DOUBLE SQL_FLOAT SQL_GRAPHIC SQL_INTEGER SQL_NUMERIC SQL_REAL SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARBINARY SQL_VARCHAR SQL_VARGRAPHIC SQL_WCHAR SQL_WVARCHAR Specifying SQL_DEFAULT causes data to be transferred from its default application data type to the type indicated in fSqlType.
SQLSMALLINT	fSqlType	Input	SQL data type of the parameter. The supported types are: SQL_BIGINT SQL_BINARY SQL_BLOB SQL_BLOB_LOCATOR SQL_CHAR SQL_CLOB SQL_CLOB_LOCATOR SQL_DATETIME SQL_DBCLOB SQL_DBCLOB_LOCATOR SQL_DECIMAL SQL_DOUBLE SQL_FLOAT SQL_GRAPHIC SQL_INTEGER SQL_NUMERIC SQL_REAL SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARBINARY SQL_VARCHAR SQL_VARGRAPHIC SQL_WCHAR SQL_WVARCHAR
SQLSMALLINT	ibScale	Input	Scale of the corresponding parameter if fSqlType is SQL_DECIMAL or SQL_NUMERIC. If fSqlType is SQL_TIMESTAMP, this is the number of digits to the right of the decimal point in the character representation of a timestamp (for example, the scale of yyyy-mm-dd hh:mm:ss.fff is 3). Other than for the fSqlType values mentioned here, ibScale is unused.
SQLSMALLINT	ipar	Input	Parameter marker number, ordered sequentially left to right, starting at 1.

Usage

When SQLBindParam() is used to bind an application variable to an output parameter for a stored procedure, DB2 UDB CLI provides some performance enhancement if the rgbValue buffer is placed consecutively in memory after the pcbValue buffer.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLBindParam SQLSTATEs
SQLSTATE	Description	Explanation
07006	Restricted data type attribute violation	Same as `SQLSetParam()`.
40003 *	Statement completion unknown	The communication link between the CLI and the data source fails before the function completes processing.
58004	System error	Unrecoverable system error.
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY003	Program type out of range	Same as `SQLSetParam()`.
HY004	SQL data type out of range	Same as `SQLSetParam()`.
HY009	Argument value that is not valid	Both rgbValue and pcbValue are null pointers, or ipar is less than one.
HY010	Function sequence error	Function is called after `SQLExecute()` or `SQLExecDirect()` has returned SQL_NEED_DATA, but data has not been sent for all data-at-execution parameters.
HY013 *	Memory management problem	The driver is unable to access memory required to support the processing or completion of the function.
HY014	Too many handles	The maximum number of handles has been allocated.
HY021	Internal descriptor that is not valid	The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.