16.7.2 SQLBindParameter

Organization of this subsection

(1) Function
(2) Format
(3) Arguments
(4) Return value
(5) SQLSTATE
(6) Notes

(1) Function

This ODBC function binds a buffer to a dynamic parameter in an SQL statement.

(2) Format

SQLRETURN SQLBindParameter
(
  SQLHSTMT         StatementHandle,    /* In */
  SQLUSMALLINT     ParameterNumber,    /* In */
  SQLSMALLINT      InputOutputType,    /* In */
  SQLSMALLINT      ValueType,          /* In */
  SQLSMALLINT      ParameterType,      /* In */
  SQLULEN          ColumnSize,         /* In */
  SQLSMALLINT      DecimalDigits,      /* In */
  SQLPOINTER       ParameterValuePtr,  /* In */
  SQLLEN           BufferLength,       /* In */
  SQLLEN         * StrLen_or_IndPtr    /* In */
)

To Page Top

(3) Arguments

StatementHandle

Specifies a statement handle.

ParameterNumber

Specifies a parameter number. Parameter numbers are assigned in ascending order, beginning with 1.

InputOutputType

Specifies the type of the parameter:

SQL_PARAM_INPUT

Input parameter.
SQL_PARAM_INPUT_OUTPUT

Input/output parameter.

Note that input/output parameters are not supported. If SQL_PARAM_INPUT_OUTPUT is specified, the driver assumes that SQL_PARAM_INPUT is specified.

ValueType

Specifies the C data type of the parameter, or specifies SQL_C_DEFAULT.

If SQL_C_DEFAULT is specified, the driver assumes the default C data type.

For details about the supported data types, see 15.3.2 Correspondence between ODBC's SQL data types and C data types. If an unsupported C data type is specified, an error results.

ParameterType

Specifies the ODBC SQL data type of the parameter.

For details about the supported data types, see 15.3.1 Correspondence between ODBC's SQL data types and HADB's data types. If an unsupported ODBC SQL data type is specified, an error results.

ColumnSize

Specifies in bytes the size of the data of the corresponding dynamic parameter.

If ParameterType is SQL_CHAR, SQL_VARCHAR, SQL_DECIMAL, or SQL_DOUBLE, the value of ColumnSize is used.

For any other data type, this argument is ignored.

DecimalDigits

Specifies the number of decimal places of the column or expression of the corresponding dynamic parameter.

If ParameterType is SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_DECIMAL, or SQL_DOUBLE, the value of DecimalDigits is used.

For any other data type, this argument is ignored.

ParameterValuePtr

Specifies a pointer to the buffer for the parameter data. The data type must be in the format specified by ValueType. If *StrLen_or_IndPtr is SQL_NULL_DATA or SQL_DATA_AT_EXEC, a null pointer can be specified.

If *StrLen_or_IndPtr is the result of the SQL_LEN_DATA_AT_EXEC(length) macro or SQL_DATA_AT_EXEC, ParameterValuePtr is an application-defined 32-bit value that is associated with the parameter.

BufferLength

For character-type C data, this argument specifies in bytes the length of the ParameterValuePtr buffer. For any other C data, this argument is ignored.

StrLen_or_IndPtr

Specifies a pointer to the buffer that stores one of the following values:

Length of the parameter value stored in *ParameterValuePtr

This value is not used for data other than character-type C data.
SQL_NTS

The parameter value is a null terminating character.
SQL_NULL_DATA

The parameter value is NULL.
Result of the SQL_LEN_DATA_AT_EXEC(length) macro

SQLPutData is used. For length, specify 0 or an integer.
SQL_DATA_AT_EXEC

SQLPutData is used.

If StrLen_or_IndPtr is a null pointer, the driver assumes that all input parameter values are not NULL and that character string data is null-terminated.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

To Page Top

(5) SQLSTATE

This ODBC function returns one of the following SQLSTATE values:

SQLSTATE	Description	Remarks	Returned
`01000`	General warning	--	N
`07006`	Restricted data type attribute violation		N
`07009`	Invalid descriptor index		Y
`HY000`	General error		N
`HY001`	Memory allocation error	The memory required to execute or complete the function has not been allocated for the driver.	Y
`HY003`	Invalid application buffer data type	--	Y
`HY004`	Invalid SQL data type		Y
`HY009`	Invalid use of null pointer		Y
`HY010`	Function sequence error		Y
`HY013`	Memory management error		N
`HY021`	Inconsistent descriptor information		N
`HY090`	Invalid string or buffer length	The value specified in `BufferLength` is less than `0`. A null pointer is specified for `SQLBindParameter`, but the parameter length does not match `0`, or `SQL_NULL_DATA`, or `SQL_DATA_AT_EXEC`, or the parameter length is greater than `SQL_LEN_DATA_AT_EXEC_OFFSET`.	Y
`HY104`	Invalid precision or scale value	--	N
`HY105`	Invalid parameter type	The value specified in `InputOutputType` is invalid.	Y
`HY117`	Connection suspended	--	N
`HYC00`	Optional feature not implemented	The value of `ValueType` does not match the value of `ParameterType`.	Y
`HYT01`	Connection timeout expired	--	N
`IM001`	Driver does not support this function	--	N

Legend:

Y: This SQLSTATE might be returned by the HADB ODBC driver.

N: This SQLSTATE is not returned by the HADB ODBC driver.

--: None

To Page Top

(6) Notes

The bound values are in effect until any of the following occurs:
- SQLBindParameter with the same ParameterNumber specified is called again
- SQLFreeStmt with the SQL_RESET_PARAMS option specified is called
- SQLSetDescField is called and 0 is set in the SQL_DESC_COUNT header field of an APD
Rebinding with offsets is not supported.

To Page Top