DB2 10.5 for Linux, UNIX, and Windows

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);