SQLPutData - Pass data value for a parameter

SQLPutData() is called following an SQLParamData() call returning SQL_NEED_DATA to supply parameter data values. This function can be used to send large parameter values in pieces.

Syntax

SQLRETURN SQLPutData  (SQLHSTMT     hstmt,
                       SQLPOINTER   rgbValue,
                       SQLINTEGER   cbValue);

Function arguments

Table 1. SQLPutData arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle.
SQLPOINTER	rgbValue	Input	Pointer to the actual data, or portion of data, for a parameter. The data must be in the form specified in the `SQLBindParam()` call that the application used when specifying the parameter.
SQLINTEGER	cbValue	Input	Length of rgbValue. This specifies the amount of data sent in a call to `SQLPutData()`. The amount of data can vary with each call for a given parameter. The application can also specify SQL_NTS or SQL_NULL_DATA for cbValue. cbValue is ignored for all date, time, timestamp data types, and all numeric data types except SQL_NUMERIC and SQL_DECIMAL. For cases where the C buffer type is SQL_CHAR or SQL_BINARY, or if SQL_DEFAULT is specified as the C buffer type and the C buffer type default is SQL_CHAR or SQL_BINARY, this is the number of bytes of data in the rgbValue buffer.

Usage

The application calls SQLPutData() after calling SQLParamData() on a statement in the SQL_NEED_DATA state to supply the data values for an SQL_DATA_AT_EXEC parameter. Long data can be sent in pieces through repeated calls to SQLPutData(). After all the pieces of data for the parameter have been sent, the application again calls SQLParamData(). SQLParamData(). proceeds to the next SQL_DATA_AT_EXEC parameter, or, if all parameters have data values, executes the statement.

SQLPutData() cannot be called more than once for a fixed length parameter.

After an SQLPutData() call, the only legal function calls are SQLParamData(), SQLCancel(), or another SQLPutData() if the input data is character or binary data. As with SQLParamData(), all other function calls using this statement handle fail. In addition, all function calls referencing the parent hdbc of hstmt fail if they involve changing any attribute or state of that connection. For a list of these functions, see the Usage section for SQLParamData - Get next parameter for which a data value is needed.

If one or more calls to SQLPutData() for a single parameter result in SQL_SUCCESS, attempting to call SQLPutData() with cbValue set to SQL_NULL_DATA for the same parameter results in an error with SQLSTATE of HY011. This error does not result in a change of state; the statement handle is still in a Need Data state and the application can continue sending parameter data.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Some of the following diagnostics conditions might be reported on the final SQLParamData() call rather than at the time the SQLPutData() is called.

Table 2. SQLPutData SQLSTATEs
SQLSTATE	Description	Explanation
22001	Too much data	The size of the data supplied to the current parameter by `SQLPutData()` exceeds the size of the parameter. The data supplied by the last call to `SQLPutData()` is ignored.
01004	Data truncated	The data sent for a numeric parameter is truncated without the loss of significant digits. Timestamp data sent for a date or time column is truncated. Function returns with SQL_SUCCESS_WITH_INFO.
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	The argument rgbValue is a null pointer. The argument rgbValue is not a NULL pointer and the argument cbValue is less than 0, but not equal to SQL_NTS or SQL_NULL_DATA.
HY010	Function sequence error	The statement handle hstmt must be in a need data state and must have been positioned on an SQL_DATA_AT_EXEC parameter through a previous `SQLParamData()` call.