SQLSetEnvAttr function (CLI) - Set environment attribute

SQLSetEnvAttr() sets an environment attribute for the current environment.

Specification:

  • CLI 2.1
  • ISO CLI

Syntax

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

Function arguments

Table 1. SQLSetEnvAttr arguments
Data type Argument Use Description
SQLHENV EnvironmentHandle Input Environment handle.
SQLINTEGER Attribute Input Environment attribute to set; refer to the list of CLI environment attributes for descriptions.
SQLPOINTER ValuePtr Input Value for the Attribute.
SQLINTEGER StringLength Input Length of ValuePtr in bytes if the attribute value is a character string; if Attribute does not denote a string, then CLI ignores StringLength.

Usage

Once set, the attribute's value affects all connections under this environment.

The application can obtain the current attribute value by calling SQLGetEnvAttr().

Refer to the list of CLI environment attributes for the attributes that can be set with SQLSetEnvAttr().

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLSetEnvAttr SQLSTATEs
SQLSTATE Description Explanation
HY011 Operation invalid at this time. Applications cannot set environment attributes while connection handles are allocated on the environment handle.
HY024 Invalid attribute value Given the specified Attribute value, an invalid value was specified in *ValuePtr.
HY090 Invalid string or buffer length The StringLength argument was less than 0, but was not SQL_NTS.
HY092 Option type out of range. An invalid Attribute value was specified.
HYC00 Driver not capable. The specified Attribute is not supported by CLI.

Given specified Attribute value, the value specified for the argument ValuePtr is not supported.

Restrictions

None.

Example

  /* set environment attribute */
  cliRC = SQLSetEnvAttr(henv, SQL_ATTR_OUTPUT_NTS, (SQLPOINTER) SQL_TRUE, 0);