Logging On to a Server

After the API is initialized, a program must log in to an Essbase Server in order to perform any actions on that server. Generally, a login only needs to be performed when a specific action is requested by the user (typically a database connect operation). Note that a login to a server does not necessarily imply a connection to a specific application or database on that server; some administration operations do not require a connection to a particular database, and some do not even require connection to a server.

A login can be performed using EsxLogin(). For Microsoft Windows only, an encapsulated login dialog function, EsxAutoLogin(), is available. The dialog box displayed by this function is similar to the one used by the Administration Services Console and Spreadsheet Add-in interfaces. Optionally, the user can use the dialog box to select an application and a database to connect to (see Connecting to a Database). The user can also perform other operations, such as changing a password.

/* C Example of a login using the EssLogin function */
ESS_STS_T       sts;
ESS_HINST_T     hInst;
ESS_SVRNAME_T   Server = "Larch";
ESS_USERNAME_T  Username = "Joe User";
ESS_PASSWORD_T  Password = "secret";
ESS_ACCESS_T    Access;
ESS_HCTX_T      hCtx = ESS_INVALID_HCTX;
sts = EssLogin (hInst, Server, Username, Password, &Access, &hCtx);

' VB Example of a login using the EsbLogin function
Dim     sts as ESB_STS_T
Dim     hInst as ESB_HINST_T
Dim     Server as ESB_SVRNAME_T
Dim     Username as ESB_USERNAME_T
Dim     Password as ESB_PASSWORD_T
Dim     Access as ESB_ACCESS_T
Dim     hCtx as ESB_HCTX_T
Server = "Larch"
Username = "Joe User"
Password = "secret"
hCtx = ESB_INVALID_HCTX
sts = EsbLogin (hInst, Server, Username, Password, Access, hCtx)

The following is a similar example of logging in, this time using EsxAutoLogin(). When using this function, the user supplies all the relevant information (server name, user name, password, application, and database names) by entering the information into the appropriate fields of the dialog box:

/* C Example of a login using the EssAutoLogin function */
ESS_STS_T               sts;
ESS_HINST_T             hInst;
ESS_ACCESS_T            Access;
ESS_HCTX_T              hCtx = ESS_INVALID_HCTX;
sts = EssAutoLogin (hInst, ESS_NULL, ESS_NULL, ESS_NULL, ESS_NULL,
        ESS_NULL, AUTO_DEFAULT, &Access, &hCtx);
        
' VB Example of a login using the EsbAutoLogin function
Dim     sts as ESB_STS_T
Dim     hInst as ESB_HINST_T
Dim     Access as ESB_ACCESS_T
Dim     hCtx as ESB_HCTX_T
hCtx = ESB_INVALID_HCTX
sts = EsbAutoLogin (hInst, ESB_NULL, ESB_NULL, ESB_NULL, ESB_NULL,
        ESB_NULL, ESB_AUTO_DEFAULT, Access, hCtx)

See EssLogin, EsbLogin, EssAutoLogin, and EsbAutoLogin.

Note that, if string variables, instead of ESX_NULL, are passed to the function as the user-entered parameters, on return from the function those variables contain the values entered into the login dialog box by the user.

Your program should normally login once (at the start of a user session). However, if tying up unused server ports is a big issue, consider logging in at the start of each operation, and logging out at the end of each operation (see Logging Out). Note, however, that this process can slow down user response time significantly.

When using either EsxLogin() or EsxAutoLogin(), the returned login context handle (hCtx) should be saved within your program for subsequent API calls. The login context handle uniquely identifies that particular login to the API.

Using Local Context Handles

If you are performing API administrative operations (such as file operations) on the client machine, you can use a dummy login context handle to represent a local login to the API. The dummy handle can be used like a server context handle, except that most server-specific and database-specific operations cannot be performed. Use EsxCreateLocalContext() to create a local context handle. Consider the following example:

/* C Example of creating a local context handle */
ESS_STS_T       sts;
ESS_HINST_T     hInst;
ESS_HCTX_T      hLocalCtx = ESS_INVALID_HCTX;
sts = EssCreateLocalContext (hInst, ESS_NULL, ESS_NULL, &hLocalCtx);

' VB Example of creating a local context handle
Dim     sts as ESB_STS_T
Dim     hInst as ESB_HINST_T
Dim     hLocalCtx as ESB_HCTX_T
hLocalCtx = ESB_INVALID_HCTX
sts = EsbCreateLocalContext (hInst, ESB_NULL, ESB_NULL, hLocalCtx)