Call Level Interface Guide and Reference

SQLGetEnvAttr - Retrieve Current Environment Attribute Value

Purpose

Specification: DB2 CLI 2.1
ISO CLI

SQLGetEnvAttr() returns the current setting for the specified environment attribute.

These options are set using the SQLSetEnvAttr() function.

Syntax

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

Function Arguments

Table 107. SQLGetEnvAttr Arguments

Data Type Argument Use Description
SQLHENV EnvironmentHandle input Environment handle.
SQLINTEGER Attribute input Attribute to receive. Refer to Environment Attributes for the list of environment attributes and their descriptions.
SQLPOINTER ValuePtr output The current value associated with Attribute. The type of the value returned depends on 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 longth 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 DB2 CLI

Data Type	Argument	Use	Description
SQLHENV	EnvironmentHandle	input	Environment handle.
SQLINTEGER	Attribute	input	Attribute to receive. Refer to Environment Attributes for the list of environment attributes and their descriptions.
SQLPOINTER	ValuePtr	output	The current value associated with `Attribute`. The type of the value returned depends on `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 longth 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 DB2 CLI

If Attribute does not denote a string, then DB2 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.

For a list of valid environment attributes, refer to Environment Attributes.

Return Codes

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 108. 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.
HY092 Option type out of range. An invalid Attribute value was specified.

SQLSTATE	Description	Explanation
HY001	Memory allocation failure.	DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY092	Option type out of range.	An invalid `Attribute` value was specified.

Restrictions

None.

CLI Sample apinfo.c

(The complete sample apinfo.c is also available here .)

 
/* From the CLI sample APINFO.C */
/* ... */
 
    sqlrc = SQLGetEnvAttr( henv, SQL_ATTR_OUTPUT_NTS, &output_nts, 0, NULL ) ;
    ENV_HANDLE_CHECK( henv, sqlrc) ;

References

SQLSetEnvAttr - Set Environment Attribute

[ Top of Page | Previous Page | Next Page ]