Conformance
Version Introduced: ODBC 3.0
Standards Compliance: ISO 92
Summary
f90SQLGetStmtAttr returns the current setting of a statement attribute.
Syntax
| f90SQLGetStmtAttr | (StatementHandle, Attribute, Value, iRet) |
| integer(SQLHENV_KIND),intent(in):: | StatementHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| integer(SQLINTEGER_KIND),intent(out):: | Value |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
| f90SQLGetStmtAttr | (StatementHandle, Attribute, Value, ValueStringLength, iRet) |
| integer(SQLHENV_KIND),intent(in):: | StatementHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| character(len=*),intent(out):: | Value |
| integer(SQLINTEGER_KIND):: | ValueStringLength |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
StatementHandle [Input]
Statement handle.
Attribute [Input]
Attribute to retrieve.
Value [Output]
Buffer in which to return the value of the attribute specified in Attribute. Depending on the Attribute, Value must be a 32-bit integer or a character string.
When f90SQL Point-Format version of this subroutine is used (See Appendix 2), and if Attribute is a driver-defined attribute, the application indicates the nature of the attribute to the Driver Manager by setting the ValueBufferLength argument. ValueBufferLength can have the following values:
- If ValuePtr is a pointer to a character string, then ValueBufferLength is the length of the string or SQL_NTS.
- If ValuePtr is a pointer to a binary buffer, then the application places the result of the f90SQLLenBinaryAttr(length) function in ValueBufferLength. This places a negative value in ValueBufferLength.
- If ValuePtr is a pointer to a value other than a character string or a binary string, then ValueBufferLength should have the value SQL_IS_POINTER.
If ValuePtr contains a fixed-length value, then ValueBufferLength is either SQL_IS_INTEGER or SQL_IS_UINTEGER, as appropriate.
ValueStringLength [Output]
Buffer in which to return the total number of bytes (excluding the null-termination character) available to return in Value, if the attribute value is a character string. If the number of bytes available to return is greater than or equal to Len(Value), the data in Value is truncated to Len(Value) minus the length of a null-termination character and is null-terminated by the driver.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLGetStmtAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may 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 f90SQLGetStmtAttr 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 | The data returned in Value was truncated to be Len(Value) minus the length of a null-termination character. The length of the untruncated string value is returned in ValueStringLength. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 24000 | Invalid cursor state | The argument Attribute was SQL_ATTR_ROW_NUMBER and the cursor was not open, or the cursor was positioned before the start of the result set or after the end of the result set. |
| 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 argument MessageText 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. |
| HY010 | Function sequence error | (DM) An asynchronously executing function was
called for the StatementHandle and was still executing when this function was
called. (DM) f90SQLExecute, f90SQLExecDirect, f90SQLBulkOperations, or f90SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. This function 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. |
| HY090 | Invalid string or buffer length | (DM) Value is a character string, and Len(Value) was less than zero, but not equal to SQL_NTS. |
| HY092 | Invalid attribute/option identifier | The value specified for the argument Attribute was not valid for the version of ODBC supported by the driver. |
| HY109 | Invalid cursor position | The Attribute argument was SQL_ATTR_ROW_NUMBER and the row had been deleted or could not be fetched. |
| HYC00 | Optional feature not implemented | The value specified for the argument Attribute was a valid ODBC statement attribute for the version of ODBC supported by the driver, but was not supported by the driver. |
| 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 corresponding to the StatementHandle does not support the function. |
Comments
A call to f90SQLGetStmtAttr returns in Value the value of the statement attribute specified in Attribute. That value can either be a 32-bit value or character string. If the value is a string, the maximum length of that string in the Len(Value) argument, and the driver returns the length of that string in the ValueStringLength buffer. If the value is a 32-bit value, ValueStringLength arguments is not used.
The following statement attributes are read-only, so can be retrieved by f90SQLGetStmtAttr, but not set by f90SQLSetStmtAttr. For a list of attributes that can be set and retrieved, see f90SQLSetStmtAttr.
| SQL_ATTR_IMP_PARAM_DESC | SQL_ATTR_ROW_NUMBER |
| SQL_ATTR_IMP_ROW_DESC |
Related Subroutines
| For information about | See |
| Returning the setting of a connection attribute | f90SQLGetConnectAttr |
| Setting a connection attribute | f90SQLSetConnectAttr |
| Setting a statement attribute | f90SQLSetStmtAttr |