DB2 Version 10.1 for Linux, UNIX, and Windows

sqleseti API - Set client information

Permits an application to set client information (by setting the fields in the sqle_client_info data structure) associated with a specific connection, provided a connection already exists.

In a TP monitor or 3-tier client/server application environment, there is a need to obtain information about the client, and not just the application server that is working on behalf of the client. By using this API, the application server can pass the client's user ID, workstation information, program information, and other accounting information to the DB2® server; otherwise, only the application server's information is passed, and that information is likely to be the same for the many client invocations that go through the same application server.

The application can elect to not specify an alias, in which case the client information will be set for all existing, as well as future, connections. This API will only permit information to be changed outside of a unit of work, either before any SQL is executed, or after a commit or a rollback. If the call is successful, the values for the connection will be sent at the next opportunity, grouped with the next SQL request sent on that connection; a successful call means that the values have been accepted, and that they will be propagated to subsequent connections.

This API can be used to establish values before connecting to a database, or it can be used to set or modify the values once a connection has been established.

Authorization

None

Required connection

None

API include file

sqlenv.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  sqleseti (
        unsigned short DbAliasLen,
        char * pDbAlias,
        unsigned short NumItems,
        struct sqle_client_info* pClient_Info,
        struct sqlca * pSqlca);

sqleseti API parameters

DbAliasLen: Input. A 2-byte unsigned integer representing the length in bytes of the database alias. If a value greater than zero is provided, pDbAlias must point to the alias name, and the settings will affect only the specified connection. If zero is specified, the settings will affect all existing and future connections.
pDbAlias: Input. A pointer to a string containing the database alias.
NumItems: Input. Number of entries being modified. The minimum value is 1.
pClient_Info: Input. A pointer to an array of NumItems sqle_client_info structures, each containing a type field indicating which value to set, the length of that value, and a pointer to the new value.
pSqlca: Output. A pointer to the sqlca structure.

Usage notes

If an alias name was provided, a connection to the alias must already exist, and all connections to that alias will inherit the changes. The information will be retained until the connection for that alias is broken. If an alias name was not provided, settings for all existing connections will be changed, and any future connections will inherit the changes. The information will be retained until the program terminates.

The field names represent guidelines for the type of information that can be provided. For example, a TP monitor application could choose to provide the TP monitor transaction ID along with the application name in the SQL_CLIENT_INFO_APPLNAM field. This would provide better monitoring and accounting on the DB2 server, where the DB2 transaction ID can be associated with the TP monitor transaction ID.

Currently this API will pass information to DB2 OS/390® Version 5 and higher, DB2 Universal Database Version 7 and higher, and DB2 i5/OS™ V6R1 and higher. All information (except the accounting string) is displayed on the DISPLAY THREAD command, and will all be logged into the accounting records.

The data values provided with the API can also be accessed by SQL special register. The values in these registers are stored in the database code page. Data values provided with this API are converted to the database code page before being stored in the special registers. Any data value that exceeds the maximum supported size after conversion to the database code page will be truncated before being stored at the server. These truncated values will be returned by the special registers. The original data values will also be stored at the server and are not converted to the database code page. The unconverted values can be returned by calling the sqleqryi API.

Calling the sqleseti API in a CLI program before a connection will not work. Calling the sqleseti API in a CLI program after a connection has been established may result in unpredictable behavior. It is recommended that the corresponding CLI functions SQLSetConnectAttr() or SQLSetEnvAttr() be used instead.

If the accounting string is set by this API, when changes are made to the client user ID or application name, the accounting string does not get updated. However, if the accounting string was set by the wlm_set_client_info procedure and the client user ID or application name is changed, then the accounting string will be updated.