A context handle represents a single, valid login by a user onto the system. A successful call to EssLogin() returns a context handle, which can be passed to other API calls which require a context handle as an argument:
Using context handles in an application—Context handles are defined as type ESS_HCTX_T in C programs. In general, a context handle is valid for as long as the user remains logged in to that server (that is, until after a successful EssLogout() call). However, in case such as a server shutdown, a context handle can become invalid. Your program should therefore provide some way for the user to log back in during a session (for example, through a menu option or function key).
Note: | A context handle is specific to an instance of the API, and contains an implied reference to the resources and settings for the appropriate instance. |
Multiple context handles—A single instance of an API program may make multiple calls to EssLogin(), using the same user name or different user names on one or more Essbase servers. Each call to EssLogin() returns a unique context handle, and your program must keep track of each context handle returned. You may have up to 255 context handles per client application in use simultaneously, but if a program performs all its processing on a single server, in general it is easier to use only one context handle and to switch between different applications and/or databases as required, using either the EssSetActive() function or the EssAutoLogin() function.
Sharing context handles—In general, it is not advisable to share context handles between multiple programs, processes, or threads, unless such use is guaranteed to be exclusive. A better approach is to use the same instance handle and log in each process or thread separately.Essbase ensures that multiple logins using the same user name on the same server will only occupy one port on that server.
Local context handles—Operations on local objects and files (on the client) can use a local context handle (see Using Local Context Handles).
See also Local Contexts.