Administrative API Reference

sqleseti - Set Client Information

Permits an application to set client information 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 prior to 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

Version

sqlenv.h

C API Syntax 



/* File: sqlenv.h */
/* API: Set Client Information */
/* ... */
SQL_API_RC SQL_API_FN
  sqleseti (
    unsigned short DbAliasLen,
    char * pDbAlias,
    unsigned short NumItems,
    struct sqle_client_info* pClient_Info,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlenv.h */
/* API: Set Client Information */
/* ... */
SQL_API_RC SQL_API_FN
  sqleseti (
    unsigned short DbAliasLen,
    char * pDbAlias,
    unsigned short NumItems,
    struct sqle_client_info* pClient_Info,
    struct sqlca * pSqlca);
/* ... */

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. For more information about this structure, see SQLE-CLIENT-INFO.

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

Sample Programs

C
\sqllib\samples\c\cli_info.c

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 only pass information to DB2 OS/390 Version 5 and higher. All information (except the accounting string) is displayed on the DISPLAY THREAD command, and they will all be logged into the accounting records.

See Also

sqleqryi - Query Client Information

sqlesact - Set Accounting String

sqlesetc - Set Client.

[ Top of Page | Previous Page | Next Page ]