サーバーへのログオン

APIが初期化された後、プログラムは、サーバーでアクションを実行するためには、Essbaseサーバーにログインする必要があります。一般には、具体的なアクション(通常は、データベース接続操作)がユーザーによって要求された場合のみ、ログインを実行する必要があります。サーバーへのログインは、そのサーバー上の特定のアプリケーションまたはデータベースへの接続を必ずしも意味しないことに注意してください。管理操作には、特定のデータベースへの接続を必要としないものや、サーバーへの接続さえ必要としないものがあります。

ログインはEsxLogin()を使用して実行できます。Microsoft Windowsのみについては、カプセル化されたログイン・ダイアログ関数(EsxAutoLogin())が利用可能です。この関数が表示するダイアログ・ボックスは、管理サービス・コンソールまたはSmart Viewが使用するものに似ています。オプションで、そのダイアログ・ボックスを使用して、接続するアプリケーションおよびデータベースを選択できます(データベースへの接続を参照)。また、ユーザーは、パスワードを変更するなど、他の操作を実行できます。

      /* 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)
   

次は、ログインの類似した例です。ここでは、EsxAutoLogin()を使用します。この関数を使用するとき、ユーザーは、すべての関連情報(サーバー名、ユーザー名、パスワード、アプリケーション名およびデータベース名)をダイアログ・ボックスの適切なフィールドへ入力することによって提供します:

      /* 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)
   

EssLogin、EsbLogin、EssAutoLoginおよびEsbAutoLoginを参照してください。

ESX_NULLのかわりに、ユーザー入力パラメータとして文字列変数を関数に渡すと、関数から戻るときには、ユーザーがログイン・ダイアログ・ボックスに入力した値が、これらの文字列変数に入ります。

通常、プログラムは(ユーザー・セッションの最初に)1度ログインする必要があります。ただし、未使用のサーバー・ポートの拘束が大きな問題である場合、各操作の最初にログインし、各操作の終わりにログアウトすることを検討してください(ログアウトを参照)。ただし、このプロセスによって、ユーザー応答時間が著しく遅くなる場合があることに注意してください。

EsxLogin()またはEsxAutoLogin()を使用すると、戻されたログイン・コンテキスト・ハンドル(hCtx)は、以後のAPI呼出しのためにプログラム内で保存する必要があります。このログイン・コンテキスト・ハンドルは、APIに対するその特定のログインを一意に識別します。

ローカル・コンテキスト・ハンドルの使用

クライアント・マシン上でAPIの管理操作(ファイル操作など)を実行している場合、APIへのローカル・ログインを表すために、ダミーのログイン・コンテキスト・ハンドルを使用できます。ダミーのハンドルは、サーバー・コンテキスト・ハンドルと同様に使用できますが、サーバー特有およびデータベース特有の操作はほとんど実行できません。ローカル・コンテキスト・ハンドルを作成するためには、EsxCreateLocalContext()を使用します。次の例を検討してください:

      /* 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)