Environment attributes (CLI) list

This attribute is not supported when accessing the Informix® database server.

• SQL_CONCURRENT_TRANS: The application can have concurrent multiple connections to any one database or to multiple databases. Each connection has its own commit scope. No effort is made to enforce the coordination of the transaction. If an application issues a commit by using the environment handle on SQLEndTran() and not all of the connections commit successfully, the application is responsible for recovery. This is the default.
• SQL_COORDINATED_TRANS: The application can coordinate commit and rollbacks among multiple database connections. This option setting corresponds to the specification of the Type 2 CONNECT in embedded SQL. In contrast to the SQL_CONCURRENT_TRANS setting that was previously described, the application is permitted only one open connection per database.
  Note: This connection type results in the default for the SQL_ATTR_AUTOCOMMIT connection option to be SQL_AUTOCOMMIT_OFF.

If you change this attribute from the default, you must set it before any connections are established on the environment handle.

Application typically set this attribute as an environment attribute with a call to SQLSetEnvAttr() function. The SQLSetEnvAttr() function is called as soon as the environment handle is allocated. However, because ODBC applications cannot access SQLSetEnvAttr() function, ODBC applications must set this attribute using SQLSetConnectAttr() function after each connection handle is allocated, but before any connections are established.

All connections on an environment handle must have the same SQL_ATTR_CONNECTTYPE setting. An environment cannot have both concurrent and coordinated connections. The type of the first connection determines the type of all subsequent connections. SQLSetEnvAttr() returns an error if an application attempts to change the connection type while there is an active connection.

You can also set the default connect type by using the ConnectType CLI/ODBC configuration keyword.

The SQL_ATTR_CONNECTTYPE attribute is an IBM® defined extension.

This attribute is not supported when accessing the Informix database server.

Description

A 32-bit integer value that allocates the DB2 trace facility buffer in MB.

Values

The SQL_ATTR_DB2TRC_STARTUP_SIZE value must be in the range of 1-1024 MB and in power of 2. If the SQL_ATTR_DB2TRC_STARTUP_SIZE value is not set to a value in power of 2, the specified SQL_ATTR_DB2TRC_STARTUP_SIZE value is rounded down to the closest power of 2 value.

Usage notes

The SQL_ATTR_DB2TRC_STARTUP_SIZE value only takes effect if the following conditions are met:

• No environment handle is allocated by the process that uses DB2 libraries.
• A trace buffer is not allocated before setting the value.

Once set, the trace facility buffer allocated by the SQL_ATTR_DB2TRC_STARTUP_SIZE cannot be changed while DB2 libraries are still loaded in the operating system.

The trace facility buffer is de-allocated when all running processes that use DB2 libraries exits.

If the trace facility buffer is already allocated, setting the SQL_ATTR_DB2TRC_STARTUP_SIZE attribute has no effect. The trace facility buffer can be allocated by:

• Issuing the db2start command on the IBM Data Server product.
• Issuing the db2trc on or db2trc alloc command.
• Setting the db2trcStartupSize keyword in the db2dsdriver.cfg file.
• Setting the SQL_ATTR_DB2TRC_STARTUP_SIZE environment attribute.

Description

A 32-bit integer value which represents the diagnostic level. This is equivalent to the database manager DIAGLEVELparameter.

Values

Valid values are: 0, 1, 2, 3, or 4. (The default value is 3.)

For details about these values, see diaglevel - Diagnostic error capture level configuration parameter.

Usage notes

You must set this attribute before any connection handles are created.

Description

A pointer to a null-terminated character string that contains the name of the directory where diagnostic data is to be placed. The SQL_ATTR_DIAGPATH is equivalent to the database manager DIAGPATH parameter.

Values

The default value is the db2dump directory on UNIX and Linux operating systems, and the db2 directory on Windows operating systems.

Usage notes

You must set this attribute before any connection handles are created.

Description

A pointer to a null-terminated character string that is used to identify the client accounting string that is sent to a database.

Values

Some servers might not be able to handle the entire length of the value and might truncate it. Note the following conditions:

• DB2 for z/OS® Version 10 and earlier servers support a length of up to 200 characters.
• CLI applications can set the SQL_ATTR_INFO_ACCTSTR attribute on DB2 for i V6R1 and later servers. DB2 for i servers support a length of up to 255 characters.

To ensure that the data is converted correctly when transmitted to a host system, use only the characters A - Z and 0-9 and the underscore (_) or period (.).

The SQL_ATTR_INFO_ACCTSTR attribute is an IBM defined attribute.

Description

A pointer to a null-terminated character string that is used to identify the client application name that is sent to a database.

Values

Some servers might not be able to handle the entire length of the value and might truncate it. Note the following conditions:

• DB2 for z/OS Version 10 and earlier servers support a length of up to 32 characters.
• CLI applications can set the SQL_ATTR_INFO_APPLNAME attribute on DB2 for i V6R1 and later servers. DB2 for i servers support a length of up to 255 characters.

To ensure that the data is converted correctly when transmitted to a host system, use only the characters A - Z and 0 - 9 and the underscore (_) or period (.).

The SQL_ATTR_INFO_APPLNAME attribute is an IBM defined extension.

If you change the client application name and the accounting string is set by the WLM_SET_CLIENT_INFO procedure, the accounting string stored on the server is updated with the value of the accounting string from the client information.

The SQL_ATTR_INFO_APPLNAME attribute is an IBM defined attribute.

Description

A pointer to a null-terminated character string that is used to identify the client user ID that is sent to a database.

Values

Do not confuse the client user ID with the authentication user ID. The client user ID is for identification purposes only and is not used for any authentication.

Some servers might not be able to handle the entire length of the value and might truncate it. Note the following conditions:

• DB2 for z/OS Version 10 and earlier servers support a length of up to 16 characters.
• CLI applications can set the SQL_ATTR_INFO_USERID attribute on DB2 for i V6R1 and later servers. DB2 for i servers support a length of up to 255 characters.

To ensure that the data is converted correctly when transmitted to a host system, use only the characters A - Z and 0 - 9 and the underscore (_) or period (.).

The SQL_ATTR_INFO_USERID attribute is an IBM defined extension.

If you change the client user ID and the accounting string is set by the WLM_SET_CLIENT_INFO procedure, the accounting string stored on the server is updated with the value of the accounting string from the client information.

The SQL_ATTR_INFO_USERID attribute is an IBM defined attribute.

Description

A pointer to a null-terminated character string that is used to identify the client workstation name that is sent to a database.

Values

Some servers might not be able to handle the entire length of the value and might truncate it. Note the following conditions:

• DB2 for z/OS Version 10 and earlier servers support a length of up to 18 characters.
• CLI applications can set the SQL_ATTR_INFO_WRKSTNNAME attribute on DB2 for i V6R1 and later servers. DB2 for i servers support a length of up to 255 characters.

To ensure that the data is converted correctly when transmitted to a host system, use only the characters A - Z and 0 - 9 and the underscore (_) or period (.).

If the SQL_ATTR_INFO_WRKSTNNAME attribute is not specified, a default value that consists of the host name is used. The host name is obtained by calling the gethostname() function. If the host name is not configured or an error is encountered during the gethostname() function call, no value for the SQL_ATTR_INFO_WRKSTNNAME attribute is sent to the server.

The SQL_ATTR_INFO_WRKSTNNAME attribute is an IBM defined attribute.

This attribute is not supported when accessing the Informix database servers.

Description

A 32-bit integer value that represents the notification level. This is equivalent to the database manager NOTIFYLEVEL parameter.

Values

Valid values are: 0, 1, 2, 3, or 4. (The default value is 3.)

For details about these values, see notifylevel - Notify level configuration parameter.

Usage notes

You must set this attribute value before any connection handles are created.

This attribute is not supported when accessing the Informix database servers.

Description

A 32-bit integer that determines whether certain functionality exhibits ODBC 2.x (CLI v2) behavior or ODBC 3.0 (CLI v5) behavior. ODBC applications must set this environment attribute before calling any function that has an SQLHENV argument, or the call will return SQLSTATE HY010 (Function sequence error.).

Values

The listed values are used to set the value of this attribute:

• SQL_OV_ODBC3: Causes the listed ODBC 3.0 (CLI v5) behavior:
  • CLI returns and expects ODBC 3.0 (CLI v5) codes for date, time, and timestamp.
  • CLI returns ODBC 3.0 (CLI v5) SQLSTATE codes when SQLError(), SQLGetDiagField(), or SQLGetDiagRec() functions are called.
  • The CatalogName argument in a call to SQLTables() function accepts a search pattern.
• SQL_OV_ODBC2: Causes the listed ODBC 2.x (CLI v2) behavior:
  • CLI returns and expects ODBC 2.x (CLI v2) codes for date, time, and timestamp.
  • CLI returns ODBC 2.0 (CLI v2) SQLSTATE codes when SQLError(), SQLGetDiagField(), or SQLGetDiagRec() functions are called.
  • The CatalogName argument in a call to SQLTables() function does not accept a search pattern.
• SQL_OV_ODBC3_80: Causes the listed ODBC 3.0 (CLI v5) behavior:
  • CLI returns and expects ODBC 3.x codes for date, time, and timestamp.
  • CLI returns ODBC 3.x SQLSTATE codes when SQLError(), SQLGetDiagField(), or SQLGetDiagRec() functions are called.
  • The CatalogName argument in a call to SQLTables() function accepts a search pattern.

Description

A 32-bit integer value that controls the use of null-termination in output arguments.

Values

The possible values are:

• SQL_TRUE: CLI uses null termination to indicate the length of output character strings (default).
• SQL_FALSE: CLI does not use null termination in output character strings.

The CLI functions that are affected by this attribute are all of the functions that are called for the environment (and for any connections and statements that are allocated under the environment) that have character string parameters.

You can set this attribute only when there are no connection handles that are allocated under this environment.

Description

A 32-bit mask that sets process-level attributes, which affect all environments and connections for the process. You must set this attribute before the environment handle is allocated.

The call to SQLSetEnvAttr() must have the EnvironmentHandle argument set to SQL_NULL_HANDLE. The settings remain in effect for the duration of the process. Generally, use this attribute only for performance sensitive applications, where large numbers of CLI function calls are being made. Before setting any of these bits, ensure that the application, and any other libraries that the application calls, comply with the restrictions that are listed.

Values

You can combine the listed values to form a bit mask:

• SQL_PROCESSCTL_NOTHREAD - This bit indicates that the application does not use multiple threads, or if it does use multiple threads, guarantees that all DB2 calls are serialized by the application. If set, CLI does not make any system calls to serialize calls to CLI, and sets the DB2 context type to SQL_CTX_ORIGINAL.
• SQL_PROCESSCTL_NOFORK - This bit indicates that the application will never fork a child process. By default, CLI does not check to see if an application forks a child process. However, if the CheckForFork CLI/ODBC configuration keyword is set, CLI checks the current process ID for each function call for all applications that are connecting to the database for which the keyword is enabled. You can set this attribute so that CLI does not check for forked processes for that application.

The SQL_ATTR_PROCESSCTL attribute is an IBM defined extension.

Description

A 32-bit unsigned integer value that specifies whether the ODBC Driver Manager notifies the ODBC drivers that a connection has been placed in the connection pool on Windows operating systems. If the SQL_ATTR_ODBC_VERSION environment attribute is set to SQL_OV_ODBC3_80, the ODBC Driver Manager sets this attribute before placing a connection in the connection pool so that the driver can reset the other connection attributes to their default values.

Values

The only possible value is:

• SQL_RESET_CONNECTION_YES (default): The ODBC Driver Manager notifies the ODBC drivers that a connection has been placed in the connection pool.

This attribute is not supported when accessing the Informix database servers.

Description

A pointer to a null-terminated character string that is used to turn on the CLI/ODBC trace facility.

Values

The string must include the CLI keywords TRACE and TRACEPATHNAME. For example:

"TRACE=1; TRACEPATHNAME=<dir>;"

Usage notes

This attribute is not supported when accessing the Informix database servers.

Description

A 32-bit integer value that specifies whether header information is included in the CLI trace file.

Values

The possible values are:

• 0 - Header information is included in the CLI trace file.
• 1 - No header information is included in the CLI trace file.

You can use the SQL_ATTR_TRACENOHEADER attribute with an SQL_NULL_HANDLE or with a valid environment handle.

This attribute is not supported when accessing the Informix database servers.

Description

This attribute is used only when authenticating a user on a server that is using an identity mapping service.

Values

The SQL_ATTR_USER_REGISTRY_NAME attribute is set to a user defined string that names an identity mapping registry. The format of the name varies depending on the identity mapping service. By providing this attribute you tell the server that the user name that is provided can be found in this registry.

After setting this attribute, the value is used on subsequent attempts to establish a normal connection, establish a trusted connection, or switch the user ID on a trusted connection.

Usage notes

This attribute is not supported when accessing the Informix database servers.

This attribute is not supported when accessing the Informix database servers.