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.
SQLRETURN SQLPutData (SQLHSTMT hstmt,
SQLPOINTER rgbValue,
SQLINTEGER cbValue);
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLHSTMT | hstmt | Input | Statement handle. |
| SQLINTEGER | cbValue | Input | Length of rgbValue. 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. |
| 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. |
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.
| 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. |