Conformance
Version Introduced: ODBC 3.0
Standards Compliance: ISO 92
Summary
f90SQLGetConnectAttr returns the current setting of a connection attribute.
Syntax
| f90SQLGetConnectAttr | (ConnectionHandle, Attribute, Value, iRet) |
| integer(SQLHDBC_KIND),intent(in):: | ConnectionHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| integer(SQLUINTEGER_KIND),intent(out):: | Value |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
| f90SQLGetConnectAttr | (ConnectionHandle, Attribute, Value, ValueStringLength, iRet) |
| integer(SQLHDBC_KIND),intent(in):: | ConnectionHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| character(len=*),intent(out):: | Value |
| integer(SQLINTEGER_KIND):: | ValueStringLength |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
ConnectionHandle [Input]
Connection handle.
Attribute [Input]
Attribute to retrieve.
Value [Output]
Variable in which to return the current value of the attribute specified by Attribute. Value must be a SQLUINTEGER_KIND or a character string, depending on Attribute.
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, and the number of bytes available to return is greater than Len(Value) minus the length of the null-termination character, the data in Value is truncated to Len(Value) minus the length of the null-termination character and is null-terminated by the driver.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLGetConnectAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained from the diagnostic data structure by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_DBC and a Handle of ConnectionHandle. The following table lists the SQLSTATE values commonly returned by f90SQLGetConnectAttr 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.) |
| 08003 | Connection does not exist | (DM) An Attribute value that required an open connection was specified. |
| 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. |
| 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 from the diagnostic data structure by the argument MessageText in f90SQLGetDiagField 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) f90SQLBrowseConnect was called for the ConnectionHandle and returned SQL_NEED_DATA. This function was called before f90SQLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS. |
| 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. |
| HYC00 | Optional feature not implemented | The value specified for the argument Attribute was a valid ODBC connection 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 ConnectionHandle does not support the function. |
Comments
For a list of attributes that can be set, see f90SQLSetConnectAttr. Note that if Attribute specifies an attribute that returns a string, Value must a string buffer. The maximum length of the returned string, including the null-termination character, will be Len(Value) bytes.
Depending on the attribute, an application does not need to establish a connection prior to calling f90SQLGetConnectAttr. However, if f90SQLGetConnectAttr is called and the specified attribute does not have a default and has not been set by a prior call to f90SQLSetConnectAttr, f90SQLGetConnectAttr will return SQL_NO_DATA.
If Attribute is SQL_ATTR_ TRACE or SQL_ATTR_ TRACEFILE, ConnectionHandle does not have to be valid, and f90SQLGetConnectAttr will not return SQL_ERROR or SQL_INVALID_HANDLE if ConnectionHandle is invalid. These attributes apply to all connections. f90SQLGetConnectAttr will return SQL_ERROR or SQL_INVALID_HANDLE if another argument is invalid.
While an application can set statement attributes using f90SQLSetConnectAttr, an application cannot use f90SQLGetConnectAttr to retrieve statement attribute values; it must call f90SQLGetStmtAttr to retrieve the setting of statement attributes.
Both SQL_ATTR_AUTO_IPD and SQL_ATTR_CONNECTION_DEAD connection attributes can be returned by a call to f90SQLGetConnectAttr, but cannot be set by a call to f90SQLSetConnectAttr.
Related Subroutines
| For information about | See |
| Returning the setting of a statement attribute | f90SQLGetStmtAttr |
| Setting a connection attribute | f90SQLSetConnectAttr |
| Setting an environment attribute | f90SQLSetEnvAttr |
| Setting a statement attribute | f90SQLSetStmtAttr |