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
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 date and time data types, except SQL_TYPE_TIMESTAMP, 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
SQLParamData()
call
rather than at the time the SQLPutData()
is called.
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. |