Conformance
Version Introduced: ODBC 3.0
Standards Compliance: ISO 92
Summary
f90SQLGetEnvAttr returns the current setting of an environment attribute.
Syntax
| f90SQLGetEnvAttr | (EnvironmentHandle, Attribute, Value, iRet) |
| integer(SQLHENV_KIND),intent(in):: | EnvironmentHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| integer(SQLINTEGER_KIND),intent(out):: | Value |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
| f90SQLGetEnvAttr | (EnvironmentHandle, Attribute, Value, ValueStringLength, iRet) |
| integer(SQLHENV_KIND),intent(in):: | EnvironmentHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| character(len=*),intent(out):: | Value |
| integer(SQLINTEGER_KIND):: | ValueStringLength |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
EnvironmentHandle [Input]
Environment handle.
Attribute [Input]
Attribute to retrieve.
Value [Output]
Buffer in which to return the current value of the attribute specified by Attribute. Depending on Attribute, Value must be a 32-bit integer or a character string.
ValueStringLength [Output]
Buffer in which to return the total number of bytes (excluding the null-termination character) available to return in Value. If Value is a null pointer, no length is returned. If the attribute value is a character string, and 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_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLGetEnvAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_ENV and a Handle of EnvironmentHandle. The following table lists the SQLSTATE values commonly returned by f90SQLGetEnvAttr 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 null-termination character. The length of the untruncated string value is returned in ValueStringLength. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 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. |
| 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. |
| 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 environment attribute for the version of ODBC supported by the driver, but was not supported by the driver. |
| IM001 | Driver does not support this function | (DM) The driver corresponding to the EnvironmentHandle does not support the function. |
Comments
For a list of attributes, see f90SQLSetEnvAttr. There are no driver-specific environment attributes. Note that if Attribute specifies an attribute that returns a string, Value must be a character buffer in which to return the string. The maximum length of the string, including the null-termination byte, will be Len(Value) bytes.
f90SQLGetEnvAttr can be called at any time between the allocation and the freeing of an environment handle. All environment attributes successfully set by the application for the environment persist until f90SQLFreeHandle is called on the EnvironmentHandle with a HandleType of SQL_HANDLE_ENV. More than one environment handle can be allocated simultaneously in ODBC 3.0. An environment attribute on one environment is not affected when another environment has been allocated.
Note: The SQL_ATTR_OUTPUT_NTS environment attribute is supported by standards-compliant applications. When f90SQLGetEnvAttr is called, the ODBC 3.0 Driver Manager always returns SQL_TRUE for this attribute. SQL_ATTR_OUTPUT_NTS can only be set to SQL_TRUE by a call to f90SQLSetEnvAttr.
Related Subroutines
| For information about | See |
| Returning the setting of a connection attribute | f90SQLGetConnectAttr |
| Returning the setting of a statement attribute | f90SQLGetStmtAttr |
| Setting a connection attribute | f90SQLSetConnectAttr |
| Setting an environment attribute | f90SQLSetEnvAttr |
| Setting a statement attribute | f90SQLSetStmtAttr |