SQLGetEnvAttr() - Return current setting of an environment attribute

SQLGetEnvAttr() returns the current setting for an environment attribute. You can also use the SQLSetEnvAttr() function to set these attributes.

ODBC specifications for SQLGetEnvAttr()

Table 1. SQLGetEnvAttr() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
3.0 Yes Yes

Syntax

SQLRETURN  SQLGetEnvAttr (SQLHENV           EnvironmentHandle,
                          SQLINTEGER        Attribute,
                          SQLPOINTER        ValuePtr,
                          SQLINTEGER        BufferLength,
                          SQLINTEGER        *StringLengthPtr);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLGetEnvAttr() arguments
Data type Argument Use Description
SQLHENV EnvironmentHandle input Specifies the environment handle.
SQLINTEGER Attribute input Specifies the attribute to retrieve. The list of environment attributes and their descriptions are described under the function SQLSetEnvAttr().
SQLPOINTER ValuePtr output Points to the buffer in which the current value associated with the Attribute argument is returned. The type of value that is returned depends on what the Attribute argument specifies.
SQLINTEGER BufferLength input Specifies the maximum size of buffer to which the ValuePtr argument points. The following conditions apply to this argument:
  • If ValuePtr points to a character string, this argument should specify the length, in bytes, of the buffer or the value SQL_NTS for nul-terminated strings. If you specify SQL_NTS, the driver assumes that the length of the string that is returned is SQL_MAX_OPTIONS_STRING_LENGTH bytes (excluding the nul-terminator).
  • If ValuePtr points to an integer, the BufferLength argument is ignored.
SQLINTEGER * StringLengthPtr output Points to a buffer that contains the total number of bytes that are associated with the ValuePtr argument. This number does not include the number of bytes for nul-termination characters. If ValuePtr 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 BufferLength, the data in ValuePtr is truncated to BufferLength minus the length of a nul-termination character. Db2 ODBC then nul-terminates this value.

If the Attribute argument does not denote a string, then Db2 ODBC ignores the BufferLength argument and does not set a value in the buffer to which StringLengthPtr points.

Usage

SQLGetEnvAttr() can be called at any time between the allocation and freeing of the environment handle. It obtains the current value of the environment attribute.

Return codes

After you call SQLGetEnvAttr(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLGetEnvAttr() SQLSTATEs
SQLSTATE Description Explanation
HY001 Memory allocation failure. Db2 ODBC is not able to allocate memory that is required to support execution or completion of the function.
HY092 Option type out of range. An invalid value for the Attribute argument is specified.

Example

The following example prints the current value of an environment attribute. SQLGetEnvAttr() retrieves the current value of the attribute SQL_ATTR_OUTPUT_NTS. 
SQLINTEGER output_nts,autocommit;
rc = SQLGetEnvAttr(henv, SQL_ATTR_OUTPUT_NTS, &output_nts, 0, 0);
CHECK_HANDLE( SQL_HANDLE_ENV, henv, rc );
printf("\nNull Termination of Output strings is: ");
if (output_nts == SQL_TRUE)
 printf("True\n");
else
 printf("False\n");