Conformance
Version Introduced: ODBC 1.0
Standards Compliance: ISO 92
Summary
f90SQLParamData is used in conjunction with f90SQLPutData to supply parameter data at statement execution time.
Syntax
| f90SQLParamData | (StatementHandle, ValuePtrPtr, iRet) |
| integer(SQLHSTMT_KIND),intent(in):: | StatementHandle |
| integer(SQLPOINTER_KIND),intent(out):: | ValuePtrPtr |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
StatementHandle [Input]
Statement handle.
ValuePtrPtr [Output]
Buffer in which to return the address of the ParameterValuePtr buffer specified in f90SQLBindParameter (for parameter data) or the address of the TargetValuePtr buffer specified in f90SQLBindCol (for column data), as contained in the SQL_DESC_DATA_PTR descriptor record field.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLParamData returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by f90SQLParamData and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
| SQLSTATE | Error | Description |
| 01000 | General warning | Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 07006 | Restricted data type attribute violation | The data value identified by the ValueType
argument in f90SQLBindParameter for the bound
parameter could not be converted to the data type identified by the ParameterType argument
in f90SQLBindParameter. The data value returned for a parameter bound as SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT could not be converted to the data type identified by the ValueType argument in f90SQLBindParameter. (If the data values for one or more rows could not be converted, but one or more rows were successfully returned, this function returns SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communication link failure | The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
| 22026 | String data, length mismatch | The SQL_NEED_LONG_DATA_LEN information type in
f90SQLGetInfo was "Y" and less data was sent for
a long parameter (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or a long, data
source - specific data type) than was specified with the StrLen_or_IndPtr
argument in f90SQLBindParameter. The SQL_NEED_LONG_DATA_LEN information type in f90SQLGetInfo was "Y" and less data was sent for a long column (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or a long, data source - specific data type) than was specified in the length buffer corresponding to a column in a row of data that was added or updated with f90SQLBulkOperations, or updated with f90SQLSetPos. |
| 40001 | Serialization failure | The transaction was rolled back due to a resource deadlock with another transaction. |
| 40003 | Statement completion unknown | The associated connection failed during the execution of this function, and the state of the transaction cannot be determined. |
| HY000 | General error | An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by f90SQLGetDiagRec in the MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation error | The driver was unable to allocate memory required to support execution or completion of the function. |
| HY008 | Operation canceled | Asynchronous processing was enabled for the StatementHandle.
The function was called and, before it completed execution, f90SQLCancel
was called on the StatementHandle; the function was then called again on the StatementHandle. The function was called and, before it completed execution, f90SQLCancel was called on the StatementHandle from a different thread in a multithread application. |
| HY010 | Function sequence error | (DM) The previous function call was not a call
to f90SQLExecDirect, f90SQLExecute,
f90SQLBulkOperations, or f90SQLSetPos
where the return code was SQL_NEED_DATA, or the previous function call was a call to f90SQLPutData. The previous function call was a call to f90SQLParamData. (DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called. f90SQLExecute, f90SQLExecDirect, f90SQLBulkOperations, or f90SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. f90SQLCancel was called before data was sent for all data-at-execution parameters or columns. |
| HY013 | Memory management error | The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions. |
| HYT01 | Connection timeout expired | The connection timeout period expired before the data source responded to the request. The connection timeout period is set through f90SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver does not support this function | (DM) The driver that corresponds to the StatementHandle does not support the function. |
If f90SQLParamData is called while sending data for a parameter in an SQL statement, it can return any SQLSTATE that can be returned by the function called to execute the statement (f90SQLExecute or f90SQLExecDirect). If it is called while sending data for a column being updated or added with f90SQLBulkOperations, or updated with f90SQLSetPos, it can return any SQLSTATE that can be returned by f90SQLBulkOperations or f90SQLSetPos.
Comments
f90SQLParamData can be called to supply data-at-execution data for two uses: parameter data to be used in a call to f90SQLExecute or f90SQLExecDirect, or column data to be used when a row is updated or added by a call to f90SQLBulkOperations or updated by a call to f90SQLSetPos. At execution time, f90SQLParamData returns to the application an indicator of which data the driver requires.
When an application calls f90SQLExecute, f90SQLExecDirect, f90SQLBulkOperations, or f90SQLSetPos, the driver returns SQL_NEED_DATA if it needs data-at-execution data. An application then calls f90SQLParamData to determine which data it should send. If the driver requires parameter data, the driver returns in the ValuePtrPtr output buffer the value that the application placed in the rowset buffer. The application can use this value to determine which parameter data the driver is requesting. If the driver requires column data, the driver returns in the ValuePtrPtr buffer the address that the column was originally bound to, in the following manner:
Bound Address + Binding Offset + ((Row Number) x Element Size)
where:
| Variable | Description |
| Bound Address | The address specified with the TargetValuePtr argument in f90SQLBindCol. |
| Binding Offset | The value stored at the address specified with the SQL_ATTR_ROW_BIND_OFFSET_PTR statement attribute. |
| Row Number | The 1-based number of the row in the rowset. For single-row fetches, which are the default, this is 1. |
| Element Size | The value of the SQL_ATTR_ROW_BIND_TYPE statement attribute for both data and length/indicator buffers. |
It also returns SQL_NEED_DATA, which is an indicator to the application that it should call f90SQLPutData to send the data.
The application calls f90SQLPutData as many times as necessary to send the data-at-execution data for the column or parameter. After all of the data has been sent for the column or parameter, the application calls f90SQLParamData again. If f90SQLParamData again returns SQL_NEED_DATA, data needs to be sent for another parameter or column, so the application again calls f90SQLPutData. If all data-at-execution data has been sent for all parameters or columns, then f90SQLParamData returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, the value in ValuePtrPtr is undefined, and the SQL statement can be executed or the f90SQLBulkOperations or f90SQLSetPos call can be processed.
If f90SQLParamData supplies parameter data for a searched update or delete statement that does not affect any rows at the data source, the call to f90SQLParamData returns SQL_NO_DATA.
Code Example
See f90SQLPutData.
Related Subroutines
| For information about | See |
| Binding a buffer to a parameter | f90SQLBindParameter |
| Canceling statement processing | f90SQLCancel |
| Returning information about a parameter in a statement | f90SQLDescribeParam |
| Executing an SQL statement | f90SQLExecDirect |
| Executing a prepared SQL statement | f90SQLExecute |
| Sending parameter data at execution time | f90SQLPutData |