SQLGetEnvAttr function (CLI) - Retrieve current environment attribute value

Returns the current setting for the specified environment attribute. These options are set using the SQLSetEnvAttr() function.

Specification:

  • CLI 2.1
  • ISO CLI

Syntax

SQLRETURN   SQLGetEnvAttr    (
               SQLHENV           EnvironmentHandle,  /* henv */
               SQLINTEGER        Attribute,
               SQLPOINTER        ValuePtr,           /* Value */
               SQLINTEGER        BufferLength,
               SQLINTEGER        *StringLengthPtr);  /* StringLength */

Function arguments

Table 1. SQLGetEnvAttr arguments
Data type Argument Use Description
SQLHENV EnvironmentHandle input Environment handle.
SQLINTEGER Attribute input Attribute to receive. Refer to the list of environment attributes and their descriptions.
SQLPOINTER ValuePtr output A pointer to memory in which to return the current value of the attribute specified by Attribute.
SQLINTEGER BufferLength input Maximum size of buffer pointed to by ValuePtr, if the attribute value is a character string; otherwise, ignored.
SQLINTEGER * StringLengthPtr output Pointer to a buffer in which to return the total number of bytes (excluding the number of bytes returned for the null-termination character) available to return in ValuePtr. 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 null-termination character and is null-terminated by CLI.

If Attribute does not denote a string, then CLI ignores BufferLength and does not set StringLengthPtr.

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

  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLGetEnvAttr SQLSTATEs
SQLSTATE Description Explanation
HY001 Memory allocation failure. Db2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY092 Option type out of range. An invalid Attribute value was specified.

Restrictions

None.

Example

  /* retrieve the current environment attribute value */
  cliRC = SQLGetEnvAttr(henv, SQL_ATTR_OUTPUT_NTS, &output_nts, 0, NULL);