ホスト・アクセス・クラス・ライブラリー (HACL) は、アプリケーション・プログラマーが簡単かつ迅速にホスト・アプリケーションにアクセスするための オブジェクトのセットです。IBM® パーソナル・コミュニケーションズは、多種多様のプログラム言語および環境をサポートします。 そのために、C++ オブジェクト、Java™ オブジェクト、Microsoft® COM ベースの自動化テクノロジー (OLE)、および LotusScript Extension (LSX) という数種類の HACL 層をサポートします。 どの層も同様な機能性を提供しますが、個々の 環境別の構文および機能の相違に応じて、それぞれの層ごとに若干の相違があります。 機能性および柔軟性の最も高い層は C++ 層であり、この層は他のすべての層の基盤を提供します。
このような階層化の概念によって、Java、Microsoft Visual Basic、Visual Basic for Applications、Lotus® Notes®、Lotus WordPro、および Visual C++ を含め、多種多様なプログラミング環境で基本的な HACL 関数を使用することができます。 次の図は、各 HACL 層を示しています。
この C++ クラス・ライブラリーは、ホスト接続をオブジェクト指向によって抽象化したものを 完全な形で提供します。それには、ホスト表示スペース (画面) での 読み書き、画面上のフィールドのエミュレーション、状況情報についての オペレーター標識域 (OIA) の読み取り、ビジュアル・エミュレーター・ウィンドウ に関する情報のアクセスと更新、ファイルの転送、および重要イベントの 非同期通知の実行が含まれます。
C++ オブジェクトの詳細については、ホスト・アクセス・クラス・ライブラリー C++を参照してください。
パーソナル・コミュニケーションズ バージョン 6.0 は、次の HACL C++ メソッドで、ユニコード・セッションの日本語コード・ページ 1390/1399 をサポートしています。
これらのメソッドの詳細については、ホスト・アクセス・クラス・ライブラリー C++の対応するセクションを参照してください。
Java オブジェクトは、Host-on-Demand バージョン 3 に類似する HACL 関数すべてに対して Java ラッピングを 提供します。HACL Java クラスの詳細については、Java 用ホスト・アクセス・クラス・ライブラリーを参照してください。
ホスト・アクセス・クラス・ライブラリーの自動化オブジェクトを使用すると、パーソナル・コミュニケーションズは、Microsoft COM ベースのオートメーション技術 (以前は、OLE オートメーションと呼ばれていました) をサポートできます。 HACL 自動化オブジェクトは、一連の自動化サーバーであり、これを使用することによって、自動化コントローラー (Microsoft Visual Basic など) が、プログラマチックにパーソナル・コミュニケーションズのデータおよび機能にアクセスすることができます。 言い替えると、自動化プロトコルを制御できるアプリケーション (自動化コントローラー) は、パーソナル・コミュニケーションズの操作の一部 (自動化サーバー) を制御することができます。
自動化オブジェクト層の詳細については、ホスト・アクセス・クラス・ライブラリーの自動化オブジェクトを参照してください。
ホスト・アクセス・クラス・ライブラリーの LotusScript Extension (LSX) は、LotusScript (Lotus Notes およびすべての Lotus SmartSuite® プロダクト用のスクリプト作成およびマクロ言語) 用の言語拡張モジュールです。 この LSX によって Lotus プロダクトのユーザーは、使いやすいスクリプト機能を介して HACL 関数にアクセスすることができます。
LotusScript 層の詳細については、ホスト・アクセス・クラス・ライブラリー LotusScript Extensionを参照してください。
以下のセクションで、エミュレーター・クラス・ライブラリー (ECL) の いくつかの基本概念について説明します。これらの概念を理解すれば、ライブラリーを有効に使用するのに役立ちます。
ECL に関するかぎり、接続とはパーソナル・コミュニケーションズの単一かつ固有の エミュレーター・ウィンドウのことです。 エミュレーター・ウィンドウは、ホストに実際に接続されていることも接続されていないこともあり、また、画面に表示されることも表示されないこともあります。 例えば、パーソナル・コミュニケーションズのウィンドウが切断状態に ある場合もあります。各接続は、接続ハンドルまたは接続名によって区別されます。 大半の HACL オブジェクトは、特定の接続に関連があります。 通常、オブジェクトは、オブジェクトのコンストラクター上のパラメーターとして、接続ハンドルまたは接続名をとります。Visual Basic などの、コンストラクター上のパラメーターをサポートしない 言語では、関連付けを行うためにメンバー関数が提供されます。 オブジェクトは、その作成後に他の接続に関連付けることはできません。 例えば、接続 'B' に関連付けられた ECLPS (表示スペース) オブジェクトを作成するには、次のようなコードを使用します。
C++
ECLPS *PSObject;
PSObject = new ECLPS('B');
Visual Basic
Dim PSObject as Object
Set PSObject = CreateObject("PCOMM.autECLPS")
PSObject.SetConnectionByName("B")
LotusScript Extension
dim myPSObj as new lsxECLPS("B")
HACL 接続名は、A から Z、または a から z の単一の文字から成ります。接続名の最大数は 52 であり、現在、パーソナル・コミュニケーションズでの同時接続は 52 までに制限されています。 接続名は、EHLLAPI 短縮セッション ID と、パーソナル・コミュニケーションズのウィンドウ・タイトル および OIA に示されるセッション ID と同じです。
HACL ハンドルは、単一の接続を表す固有の 32 ビット番号です。 接続名とは異なり接続ハンドルは 52 までの値に限定されておらず、値そのものには、アプリケーションに対する意味はありません。1 つの接続ハンドルを使用して、複数のスレッドおよびプロセスにおいて 同一の接続を参照することができます。
今後の拡張に備えて、アプリケーションでは可能な限り接続ハンドルを使用するようにしてください。たいていの HACL オブジェクトは、接続の識別の必要があるときに ハンドルまたは名前を受け入れます。基本 HACL クラスには、ハンドルから名前へ、また名前からハンドルへ変換するのに使用できる関数があります。これらの関数は、どの HACL オブジェクトからでも使用できます。
ECL に関して言えば、セッション・オブジェクト (ECLSession) とは、他のすべての接続固有オブジェクト用の単なるコンテナーです。 これは、特定の接続用の完全なセットの HACL オブジェクトを、アプリケーション で作成するためのショートカットを提供します。セッション という用語は、パーソナル・コミュニケーションズ の概念と混同してはなりません。パーソナル・コミュニケーションズ のセッションとは、画面上の物理エミュレーション・ウィンドウを指します。
ECLSession オブジェクトを作成または破棄しても、パーソナル・コミュニケーションズ のセッション (ウィンドウ) は影響を受けません。アプリケーションでは、1 つまたは複数の 接続を参照する ECLSession オブジェクトをいくつでも作成することができます。
HACL クラスによっては、他のオブジェクトのコンテナーとして 働くものもあります。例えば、ECLSession オブジェクトは、ECLPS、ECLOIA、ECLWinMetrics、および ECLXfer オブジェクトのインスタンスを収容します。 コンテナーは、収容されたオブジェクトを指すポインターを戻すメソッドを提供します。 例えば、ECLSession オブジェクトには GetOIA メソッドがありますが、これは OIA オブジェクトを指すポインターを戻します。 収容されたオブジェクトは、そのコンテナーのクラスの共用メンバーとして実装されるのではなく、メソッドを通してのみアクセスされます。
パフォーマンス上の理由または他の理由から、コンテナー・オブジェクトの作成時に 収容オブジェクトは作成されることも作成されないこともあります。 クラスの実装において、収容オブジェクトを指すポインターをアプリケーションが最初に 要求するまで、そのオブジェクトの作成を延期することもできます。 アプリケーションでは、収容されるオブジェクトはそのコンテナーと 同時に作成されると見なしてはなりません。 例えば、ECLSession オブジェクトの作成時に ECLPS オブジェクト のインスタンスは作成されないことがあります。 そのような場合、GetPS メソッドが最初に呼び出される まで、ECLSession クラスは ECLPS オブジェクトの作成を延期することができます。
コンテナー・クラスが破棄されると、そこに収容されているすべてのインスタンスも破棄されます。 アプリケーションに戻されたすべてのポインターは無効になるので、使用してはなりません。
HACL クラスのいくつかは、リスト反復機能を提供します。 例えば、ECLConnList クラスは接続のリストを管理します。ECL リスト・クラスは、リスト内容の変更を反映するよう非同期で更新されることはありません。 アプリケーションは、リストの内容を更新するためには 明示的に Refresh メソッドを呼び出さなければなりません。 それによって、反復中にリストが変更されたかどうかを心配せずに、アプリケーションでリストを反復することができます。
HACL は、特定のイベントを非同期通知する機能を備えています。 アプリケーションは、特定のイベントが起きたときに通知を受けるかどうかを 選ぶことができます。 例えば、アプリケーションは、パーソナル・コミュニケーションズの新しい接続が開始したら通知を受けるようにする ことができます。 現在、HACL は次のようなイベントの通知をサポートします。
イベントの通知は、ECLNotify 抽象基本クラスによって実装されます。 イベント・タイプごとに別々のクラスが存在します。 アプリケーションは、イベントの通知を受けられるようにする には、ECLNotify 抽象基本クラスのいずれかから派生したオブジェクト を定義および作成しなければなりません。 次に、適切な HACL 登録関数を呼び出して、そのオブジェクトを登録しなければなりません。 アプリケーション・オブジェクトを登録すると、その後該当イベントが発生する度に、NotifyEvent メソッドが呼び出されます。
C++ 層では、HACL は C++ の構造化例外処理を使用します。 一般に、ECLErr オブジェクトをもった C++ 例外を送り出す ことによって、アプリケーションにエラーが示されます。 アプリケーションがエラーを catch するには、次のように HACL オブジェクトの呼び出しを try/catch ブロック内に入れる必要があります。
try {
PSObj = new ECLPS('A');
x = PSObj->GetSize();
//...more references to HACL objects...
} catch (ECLErr ErrObj) {
ErrNumber = ErrObj.GetMsgNumber();
MessageBox(NULL, ErrObj.GetMsgText(), "ECL Error");
}
HACL エラーが catch されたとき、アプリケーションから ECLErr オブジェクトの メソッドを呼び出せば、エラーの正確な原因を判別することができます。また、ECLErr オブジェクトを呼び出して、完全な言語依存のエラー・メッセージを作成することもできます。
自動化オブジェクト層および LotusScript Extension 層のどちらでも、実行時エラーは、該当するスクリプト・エラーが作成される原因になります。 アプリケーションは、On Error ハンドラーを使用して、エラーを捕そくしてエラーについての 追加情報を照会し、適切なアクションをとることができます。
HACL には、ホスト表示スペースにおいて 点 (文字位置) をアドレッシングする方法が 2 つあります。アプリケーションは、行/列の 番号を使用するか、または単一の線形位置の値を使用して文字をアドレッシングすることができます。 表示スペースのアドレッシングの場合、使用するアドレッシング方式に関係なく、常に 1 をベースにします (0 ベースではありません)。
行/列のアドレッシング方式が有用なのは、ホスト・データの物理画面表示に直接関係したアプリケーションの場合です。 長方形の座標システム (左上隅が行 1 桁 1) を使用するのが、画面で点をアドレッシングする本来の方法です。 線形定位置アドレッシング法 (左上隅を位置 1 とし、左から右へ、上から下へ進む方法) が 便利なのは、表示スペース全体を単一のデータ要素配列として表示する アプリケーションの場合、または、このアドレッシング法を使用する EHLLAPI インターフェースから 移植されたアプリケーションの場合です。
C++ 層では、同じメソッドでも、呼び出すシグニチャーが異なると、選択するアドレッシング方式も異なります。 例えば、アプリケーションで、ホスト・カーソルを指定の画面座標に移動するには、 次に示す 2 つのシグニチャーのどちらかで ECLPS::SetCursorPos メソッドを呼び出します。
PSObj->SetCusorPos(81); PSObj->SetCursorPos(2, 1);
ホスト画面が行あたり 80 桁で構成されている場合、上記のステートメントはどちらも同じ結果を生じます。 またこの例は、アドレッシング方式における若干の相違も示します。 つまり、表示スペースの行あたりの文字数についてアプリケーションに 前提条件がある場合、線形位置メソッドでは予期しない結果を生じることがあります。 例えば、この例のコードの 1 行めは、132 桁に構成された 表示スペースの行 1 の桁 81 にカーソルを置きます。 コードの 2 行目は、表示スペースの構成に関係なく、行 2 桁 1 にカーソルを置きます。
現在、エミュレーター高水準言語 API (EHLLAPI) 用に 書かれているアプリケーションは、ホスト・アクセス・クラス・ライブラリー を使用できるよう修正することができます。一般に、EHLLAPI から HACL に移行するには、 大幅なソース・コードの変更やアプリケーションの再構築が必要です。HACL は、EHLLAPI とは異なるプログラミング・モデルを提供するので、一般に、有効に働くには異なるアプリケーション構造を必要とします。
以下のセクションは、EHLLAPI に慣れたプログラマーが、HACL と EHLLAPI との 類似点および相違点を理解するのに役立ちます。以下の情報を使用すれば、HACL を 使用できるよう個々のアプリケーションを修正する方法を理解することができます。
最も基本的なレベルでは、EHLLAPI と HACL には、アプリケーション・プログラムからの API の呼び出し方のメカニズムにおける違いがあります。
EHLLAPI は、複数用途のパラメーターを使用する単一の呼び出し点インターフェースとして、実装されています。DLL 内の 1 つのエントリー・ポイント (hllapi) が、4 つのパラメーターの規定セットをベースとしてすべての関数を提供します。 パラメーターのうちの 3 つは、4 つ目のパラメーターの値に応じて 異なる意味をとります。 この単純なインターフェースによって、さまざまなプログラミング環境や言語から 容易に API を呼び出すことが可能になります。 その欠点は、1 つの関数と 4 つのパラメーターに多くの複雑さが パックされていることです。
HACL は、明示的なエントリー・ポイントまたは関数の代わりに、一連のプログラミング・オブジェクトを提供するオブジェクト指向インターフェースです。オブジェクトには、ホスト接続を操作するのに使用できる プロパティーおよびメソッドがあります。 構造のパッキングやパラメーター・コマンド・コードの詳細について配慮する必要はなく、アプリケーション機能に注意を集中できます。HACL オブジェクトは、サポートされている HACL 層環境 (C++、自動化オブジェクト、または LotusScript) のいずれからでも使用できます。 この 3 つの層は、Microsoft Visual C++、Visual Basic、および Lotus SmartSuite アプリケーションといった最新鋭のプログラミング環境にアクセスすることができます。
高レベルでは、HACL は、EHLLAPI レベルでは使用できない多数の機能を 提供します。また、現在どの HACL クラスでも実装されていない EHLLAPI 機能も いくつかあります。
HACL に固有の機能には、次のものがあります。
HACL でまだ実装されていない EHLLAPI 機能には、次のものがあります。
HACL 体系は、52 個のセッションに限定されていません。 したがって、EHLLAPI で使われるような単一の文字セッション ID は適していません。HACL では、アプリケーションに対して 特定の意味をもたない単純な 32 ビット値である接続ハンドルの概念を使用しています。接続ハンドルは、個々の接続 (セッション) を固有に識別します。1 つの接続ハンドルを使用して、複数のスレッドおよびプロセスにおいて 同一の接続を参照することができます。
特定の接続を参照する必要のあるすべての HACL オブジェクトおよび メソッドは、接続ハンドルを受け入れます。さらに、後方互換性のためと、エミュレーター・ユーザー・インターフェース (ハンドルを表示しません) から 参照できるようにするため、一部のオブジェクトとメソッドは 従来のセッション ID も受け入れます。 アプリケーションは、ECLConnList オブジェクトとの接続を列挙することによって 接続ハンドルを取得できます。それぞれの接続は、ECLConnection オブジェクトによって 表されます。ECLConnection::GetHandle メソッドを使用すると、個々の接続に関連した ハンドルを取り出すことができます。
アプリケーションで、接続名 (EHLLAPI 短縮セッション ID) の代わりに 接続ハンドルを使用することを強くお勧めします。HACL の将来の設定では、接続名を使用するアプリケーションは、52 個を超えるセッションにアクセスできなくなる場合があります。 場合によっては、名前を使用する必要があるかもしれません。例えば、アプリケーションが利用する 特定のセッションの名前を入力する必要があるときなどです。 以下の C++ の例では、セッション名を入力します。 するとアプリケーションは、接続リスト内でその接続を検出してから、そのセッション用の PS および OIA オブジェクトを作成します。
ECLConnList ConnList; // Connection list
ECLConnection *ConnFound; // Ptr to found connection
ECLPS *PS; // Ptr to PS object
ECLOIA *OIA; // Ptr to OIA object
char UserRequestedID;
//... user inputs a session name (A-Z or a-z) and it is put
//... into the UserRequesteID variable. Then...
ConnList.Refresh(); // Update list of connections
ConnFound = ConnList.FindConnection(UserRequestedID);
if (ConnFound == NULL) {
// Session name given by user does not exist...
}
else {
// Create PS and OIA objects using handle of the
// connection just found:
PS = new ECLPS(ConnFound.GetHandle());
OIA= new ECLOIA(ConnFound.GetHandle());
// The following would also work, but is not the
// preferred method:
PS = new ECLPS(UserRequestedID);
OIA= new ECLOIA(UserRequestedID);
}
例に示された、PS および OIA オブジェクトを作成する第 2 の方法は 望ましくありません。ハンドルではなくセッション名を使用するからです。この場合、このコード・セクションに暗黙の 52 個のセッション制限が設定されます。上記の第 1 の例を使用すると、そのコード・セクションを さまざまなセッションに使用することができます。
HACL の表示スペース・モデルは、EHLLAPI の ものより簡単に使用することができます。HACL 表示スペースは、おのおのが 1 つのデータ型を含むいくつかのプレーンで構成されます。プレーンには、次のタイプがあります。
プレーンは、すべて同サイズであり、ホスト表示スペース内の 各文字位置につき 1 バイトずつを含んでいます。 アプリケーションは、ECLPS::GetScreen メソッドを使用して、必要な任意のプレーンを取得できます。
このモデルは、バッファー内で表示スペースのテキストおよび 非テキストのデータがしばしばインターリーブされる EHLLAPI とは異なります。 アプリケーションは、どの型のデータを取り出すかを指定 する EHLLAPI セッション・パラメーターを設定してから、次にそのデータをバッファーにコピーするために別の呼び出しを行わなければなりません。HACL モデルを使用すると、アプリケーションは、1 回の呼び出しで必要なデータを取得する ことができ、1 つのバッファー内で別々のデータ型が混ざり合うことはありません。
ホストにキー・ストロークを 送信する HACL メソッド (ECLPS::Sendkeys) は、EHLLAPI の SendKey 関数に似ています。 ただし、EHLLAPI では、Enter、PF1、および Backtab などの非テキスト・キーを表すのに 暗号エスケープ・コードが使われます。ECLPS オブジェクトは、そのようなキー・ストロークを表すのに、ブラケットで囲んだキーワードを使用します。 例えば、次に示す C++ サンプルでは、現行カーソル位置に ABC の文字を 入力し、その後に Enter キーが続きます。
ECLPS *PS;
PS = new ECLPS('A'); // Get PS object for "A"
PS->SendKeys("ABC[enter]"); // Send keystrokes
EHLLAPI には、特定のイベントについてアプリケーションが 非同期通知を受け取るためのいくつかの手段が備わっています。 しかし、イベント・モデル相互に一貫性はない (セマフォーを使用する イベントもあれば、ウィンドウ・システム・メッセージを使用する イベントもある) ため、アプリケーションは責任をもって イベント・スレッドをセットアップして管理しなければなりません。HACL では、すべてのイベント処理が単純化され、すべてのイベント・タイプを通して一貫性が保たれます。 アプリケーションは、明示的に複数の実行スレッドを作成する 必要はなく、HACL が内部でスレッド化を処理します。
ただし、別の実行スレッドでイベント・プロシージャーが呼び出されることに 留意していなければなりません。 イベント・プロシージャーからのアクセス時には、ダイナミック・アプリケーション・データへのアクセスを同期化しなければなりません。 イベント・スレッドは、アプリケーションがイベントを登録すると生成され、 イベントが登録抹消されると終了します。
EHLLAPI アプリケーションは、別々のセッションへの接続を 管理するには、ConnectPS および DisconnectPS EHLLAPI 関数を呼び出さなければなりません。 アプリケーションは、セッションに際限なく接続されたままにならないように するため、慎重にコーディングしなければなりません。 セッションは、すべての EHLLAPI アプリケーションで共有しなければならないからです。 また、使用する他の EHLLAPI 関数によっては、アプリケーションがセッションに 接続されていることも事前に確認しなければなりません。
HACL では、アプリケーションが明示的にセッションを接続または切断する必要は ありません。すべての HACL オブジェクトは、その作成時に特定の接続 (セッション) に関連付けられています。アプリケーションが、別の接続にアクセスするには、それぞれのためのオブジェクトを作成するだけでよいのです。 例えば、次に示す例は、キー・ストローク ABC をセッション A に送ってから、次に DEF をセッション B に、さらに次に Enter キーをセッション A に送ります。 EHLLAPI プログラムでは、アプリケーションは、セッションを 1 つずつ接続/切断しなければなりません。 一度に 1 つのセッションとしか対話できないからです。HACL アプリケーションは、次のように必要な任意の順序でオブジェクトを使用することができます。
ECLPS *PSA, *PSB;
PSA = new ECLPS('A');
PSB = new ECLPS('B');
PSA->Sendkeys("ABC");
PSB->Sendkeys("DEF");
PSA->Sendkeys("[enter]");
複数の接続 (セッション) と対話するアプリケーションの場合、これによって、複数の接続を管理するのに必要なコードを大幅に単純化することができます。
また EHLLAPI では、作業セッションは 1 つずつである他に、アプリケーションのマルチスレッド特性に対する制約もあります。EHLLAPI インターフェースを 呼び出すスレッドが複数あるアプリケーションの場合、表示スペースへの接続と 切断は慎重に管理する必要があり、複数のスレッドがあってもアプリケーションは一度に 1 つの セッションとしか対話できません。
ECLPS では、マルチスレッド化に関してアプリケーションは特に制約を受けません。アプリケーションは、さまざまなスレッド上でさまざまなセッションと並列対話する ことができます。