Conformance
Version Introduced: ODBC 1.0
Standards Compliance: ISO 92
Summary
f90SQLPutData allows an application to send data for a parameter or column to the driver at statement execution time. This function can be used to send character or binary data values in parts to a column with a character, binary, or data source - specific data type (for example, parameters of the SQL_LONGVARBINARY or SQL_LONGVARCHAR types).
Syntax
| f90SQLPutData | (StatementHandle, DataPtr, StrLen_or_Ind, iRet) |
| integer(SQLHSTMT_KIND),intent(in):: | StatementHandle |
| integer(SQLPOINTER_KIND),intent(in):: | DataPtr |
| integer(SQLINTEGER_KIND),intent(in):: | StrLen_or_Ind |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
StatementHandle [Input]
Statement handle.
DataPtr [Input]
Pointer to a buffer containing the actual data for the parameter or column. The data must be in the Fortran data type specified in the ValueType argument of f90SQLBindParameter (for parameter data) or the TargetType argument of f90SQLBindCol (for column data).
StrLen_or_Ind [Input]
Length of *DataPtr. Specifies the amount of data sent in a call to f90SQLPutData. The amount of data can vary with each call for a given parameter or column. StrLen_or_Ind is ignored unless it is one of the following:
- SQL_NTS, SQL_NULL_DATA, or SQL_DEFAULT_PARAM
- The Fortran data type specified in f90SQLBindParameter or f90SQLBindCol is SQL_F_CHAR or SQL_F_BINARY.
- The Fortran data type is SQL_F_DEFAULT and the default Fortran data type for the specified SQL data type is SQL_F_CHAR or SQL_F_BINARY.
For all other types of Fortran data, if StrLen_or_Ind is not SQL_NULL_DATA or SQL_DEFAULT_PARAM, the driver assumes that the size of the *DataPtr buffer is the size of the Fortran data type specified with ValueType or TargetType and sends the entire data value. For more information, see " Converting Data from Fortran to SQL Data Types" in Appendix 3.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLPutData 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 f90SQLPutData 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.) |
| 01004 | String data, right truncated | String or binary data returned for an output
parameter resulted in the truncation of non-blank character or non-NULL binary data. If it
was a string value, it was right truncated. (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. |
| 07S01 | Invalid use of default parameter | A parameter value, set with f90SQLBindParameter, was SQL_DEFAULT_PARAM, and the corresponding parameter did not have a default value. |
| 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. |
| 22001 | String data, right truncation | The assignment of a character or binary value
to a column resulted in the truncation of non-blank (character) or non-null (binary)
characters or bytes. The SQL_NEED_LONG_DATA_LEN information type in f90SQLGetInfo was "Y" and more 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 more 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. |
| 22003 | Numeric value out of range | The data sent for a bound numeric parameter or
column caused the whole (as opposed to fractional) part of the number to be truncated when
assigned to the associated table column. Returning a numeric value (as numeric or string) for one or more input/output or output parameters would have caused the whole (as opposed to fractional) part of the number to be truncated. |
| 22007 | Invalid datetime format | The data sent for a parameter or column that
was bound to a date, time, or timestamp structure was, respectively, an invalid date,
time, or timestamp. An input/output or output parameter was bound to a date, time, or timestamp Fortran structure, and a value in the returned parameter was, respectively, an invalid date, time, or timestamp. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 22008 | Datetime field overflow | A datetime expression computed for an input/output or output parameter resulted in a date, time, or timestamp Fortran structure that was invalid. |
| 22012 | Division by zero | An arithmetic expression calculated for an input/output or output parameter resulted in division by zero. |
| 22015 | Interval field overflow | The data sent for an exact numeric or interval
column or parameter to an interval SQL data type caused a loss of significant digits. Data was sent for an interval column or parameter with more than one field, and was converted to a numeric data type, and had no representation in the numeric data type. The data sent for column or parameter data was assigned to an interval SQL type, and there was no representation of the value of the Fortran type in the interval SQL type. The data sent for an exact numeric or interval Fortran column or parameter to an interval Fortran type caused a loss of significant digits. The data sent for column or parameter data was assigned to an interval C structure, and there was no representation of the data in the interval data structure. |
| 22018 | Invalid character value for cast specification | The Fortran type was an exact or approximate
numeric, a datetime, or an interval data type; the SQL type of the column was a character
data type; and the value in the column or parameter was not a valid literal of the bound
Fortran type. The SQL type was an exact or approximate numeric, a datetime, or an interval data type; the Fortran type was SQL_F_CHAR; and the value in the column or parameter was not a valid literal of the bound SQL type. |
| 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. Then the function was 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. |
| HY009 | Invalid use of null pointer | (DM) The argument DataPtr was a null pointer and the argument StrLen_or_Ind was not 0, SQL_DEFAULT_PARAM, or SQL_NULL_DATA. |
| HY010 | Function sequence error | (DM) The previous function call was not a call
to f90SQLPutData or f90SQLParamData. (DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called. |
| 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. |
| HY019 | Non-character and non-binary data sent in pieces | f90SQLPutData was called more than once for a parameter or column and it was not being used to send character Fortran data to a column with a character, binary, or data source - specific data type or to send binary Fortran data to a column with a character, binary, or data source - specific data type. |
| HY020 | Attempt to concatenate a null value | f90SQLPutData was called more than once since the call that returned SQL_NEED_DATA, and in one of those calls, the StrLen_or_Ind argument contained SQL_NULL_DATA or SQL_DEFAULT_PARAM. |
| HY090 | Invalid string or buffer length | The argument DataPtr was not a null pointer and the argument StrLen_or_Ind was less than 0, but not equal to SQL_NTS or SQL_NULL_DATA. |
| 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 associated with the StatementHandle
does not support the function. If f90SQLPutData 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
f90SQLPutData 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.
When an application calls f90SQLParamData to determine which data it should send, the driver returns an indicator that the application can use to determine which parameter data to send, or where column data can be found. It also returns SQL_NEED_DATA, which is an indicator to the application that it should call f90SQLPutData to send the data. In the DataPtr argument to f90SQLPutData, the application passes a pointer to the buffer containing the actual data for the parameter or column.
When the driver returns SQL_SUCCESS for f90SQLPutData, the application calls f90SQLParamData again. f90SQLParamData returns SQL_NEED_DATA if more data needs to be sent, in which case the application calls f90SQLPutData again. It returns SQL_SUCCESS if all data-at-execution data has been sent. The application then calls f90SQLParamData again. If the driver returns SQL_NEED_DATA and another indicator in ValuePtrPtr, it requires data for another parameter or column, and f90SQLPutData is called again. If the driver returns SQL_SUCCESS, then all data-at-execution data has been sent, and the SQL statement can be executed or the f90SQLBulkOperations or f90SQLSetPos call can be processed.
Note: An application can use f90SQLPutData to send data in parts only when sending character Fortran data to a column with a character, binary, or data source - specific data type or when sending binary Fortran data to a column with a character, binary, or data source - specific data type. If f90SQLPutData is called more than once under any other conditions, it returns SQL_ERROR and SQLSTATE HY019 (Non-character and non-binary data sent in pieces).
Code Example
See Example 6.1 in Chapter 6.
Related Subroutines
| For information about | See |
| Binding a buffer to a parameter | f90SQLBindParameter |
| Canceling statement processing | f90SQLCancel |
| Executing an SQL statement | f90SQLExecDirect |
| Executing a prepared SQL statement | f90SQLExecute |
| Returning the next parameter to send data for | f90SQLParamData |