SQLGetEnvAttr Function
Conformance
Version Introduced: ODBC 3.0 Standards Compliance: ISO 92
Summary
SQLGetEnvAttr returns the current setting of an environment attribute.
Syntax
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
EnvironmentHandle
[Input] Environment handle.
Attribute
[Input] Attribute to retrieve.
ValuePtr
[Output] Pointer to a buffer in which to return the current value of the attribute specified by Attribute.
If ValuePtr is NULL, StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by ValuePtr.
BufferLength
[Input] If ValuePtr points to a character string, this argument should be the length of *ValuePtr. If *ValuePtr is an integer, BufferLength is ignored. If *ValuePtr is a Unicode string (when calling SQLGetEnvAttrW), the BufferLength argument must be an even number. If the attribute value is not a character string, BufferLength is unused.
StringLengthPtr
[Output] A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *ValuePtr. If the attribute value is a character string and the number of bytes available to return is greater than or equal to BufferLength, the data in *ValuePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLGetEnvAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_ENV and a Handle of EnvironmentHandle. The following table lists the SQLSTATE values commonly returned by SQLGetEnvAttr 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 *ValuePtr was truncated to be BufferLength minus the null-termination character. The length of the untruncated string value is returned in *StringLengthPtr. (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 SQLGetDiagRec 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. |
| HY010 | Function sequence error | (DM) SQL_ATTR_ODBC_VERSION has not yet been set via SQLSetEnvAttr. You do not need to set SQL_ATTR_ODBC_VERSION explicitly if you are using SQLAllocHandleStd. |
| 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. |
| HY117 | Connection is suspended due to unknown transaction state. Only disconnect and read-only functions are allowed. | (DM) For more information about suspended state, see SQLEndTran Function. |
| 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 SQLSetEnvAttr. There are no driver-specific environment attributes. If Attribute specifies an attribute that returns a string, ValuePtr must be a pointer to a buffer in which to return the string. The maximum length of the string, including the null-termination byte, will be BufferLength bytes.
SQLGetEnvAttr 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 SQLFreeHandle is called on the EnvironmentHandle with a HandleType of SQL_HANDLE_ENV. More than one environment handle can be allocated simultaneously in ODBC 3*.x*. 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 SQLGetEnvAttr is called, the ODBC 3*.x* Driver Manager always returns SQL_TRUE for this attribute. SQL_ATTR_OUTPUT_NTS can be set to SQL_TRUE only by a call to SQLSetEnvAttr.
Related Functions
| For information about | See |
|---|---|
| Returning the setting of a connection attribute | SQLGetConnectAttr Function |
| Returning the setting of a statement attribute | SQLGetStmtAttr Function |
| Setting a connection attribute | SQLSetConnectAttr Function |
| Setting an environment attribute | SQLSetEnvAttr Function |
| Setting a statement attribute | SQLSetStmtAttr Function |