第 12 章 : 要求ハンドラのユーザ出口プログラム

ここでは、Micro Focus MFRHSOAP 要求ハンドラの動作のカスタマイズを可能にする、ユーザの出口プログラムの作成方法について説明します。

はじめに

Micro Focus MFRHSOAP 要求ハンドラにはユーザの出口点がいくつか用意されているため、入力パラメータと出力パラメータの追加処理を実行するユーザの出口プログラムを提供することができます。

必要なすべてのコードを要求ハンドラ自体にインクルードするよりもユーザの出口プログラムを提供した方が利点がある場合には、カスタム要求ハンドラとともに使用するユーザ出口プログラムを利用できます。

ユーザ出口プログラムと、このプログラムを要求ハンドラがインターフェイスマッピング処理の一環で実行時に呼び出す出口点を指定します。この方法は、『分散コンピューティング』の『Interface Mapping Toolkit を使用した COBOL Web サービス』の章を参照してください。指定したユーザ出口プログラムの名前とその出口点は、マッピングされたサービスに関連付けられたインターフェイス定義テーブル (interface definition table; IDT) に組み込まれます。

提供されているユーザ出口点

図 12-1 に、要求ハンドラ、アプリケーションコンテナ、およびランタイムインターフェイスマッパーの相互関係を示します。

図 12-1 ：要求ハンドラの出口点

ユーザ出口点は、1 ～ 9 の番号がついた四角で表しています。次の表に、それぞれの出口点の名前と使用目的を示します。

番号	名前	説明
1	外部データ値変更 (入力パラメータ)	要求ハンドラのパラメータのデフォルトマッピングが行われる前に、クライアント要求で指定した外部データ値を変更できます。この出口点は、IDT で指定された外部-内部入力パラメータごとに呼び出されます。
2	内部データ値変更 (入力パラメータ)	要求ハンドラのパラメータのデフォルトマッピングで作成された内部データ値を無効にできます。この出口点は、IDT で指定された外部-内部入力パラメータごとに呼び出されます。
3	マップされない名前付き外部入力パラメータ	IDT 内で定義された入力パラメータマッピングに関連付けられていない入力パラメータを処理できます。この出口点は、マップされない名前付き入力パラメータごとに呼び出されます。
4	入力要求処理の終了	クライアント要求で指定された外部パラメータ以外のパラメータ値を設定できます。また、出口点 1 ～ 3 に割り当てられたリソースを解放できます。
5	応答処理の開始	クライアント応答をビルドするデフォルトマッピングを完全にバイパスできます。出口プログラムは、アプリケーションコンテナによってクライアントに返される応答を作成します。
6	内部データ値変更 (出力パラメータ)	要求ハンドラのパラメータのデフォルトマッピングが行われる前に、ユーザアプリケーションが作成した内部データ値を変更できます。この出口点は、IDT で指定された内部-外部出力パラメータごとに呼び出されます。
7	外部データ値変更 (出力パラメータ)	要求ハンドラのパラメータのデフォルトマッピングで作成された外部データ値を無効にできます。この出口点は、IDT で指定された内部-外部出力パラメータごとに呼び出されます。
8	応答処理の終了	デフォルトマッピングで生成された応答を変更できます。
9	要求処理の終了	出口点 1 ～ 8 に割り当てられたリソースを開放できます。

構造体定義と型定義

COBOL プログラマと C プログラマのために、Enterprise Server には COBOL コピーブック (cbltypes.cpy) と C ヘッダーファイル (svext.h) が用意されています。これらのファイルでは、ユーザ出口プログラムとカスタム要求ハンドラの作成に必要な構造体とインターフェイスが定義されています。

各出口点で処理を行う出口ルーチンで必要になる情報を渡すために使用する IDP_EXIT_INFO 構造体が定義されています。この構造体へのポインタは、出口点識別子とともにそれぞれの出口ルーチンに渡されます。渡される情報と返される情報は、出口点によって異なります。

各出口点で渡される情報の定義は、ヘルプトピックの『出口点』を参照してください。

サポート関数の定義は、ヘルプトピックの『関数』を参照してください。

構造体の定義は、ヘルプトピックの『構造体』を参照してください。

連絡節のフィールド名

いくつかの出口点が提供されているため、入力フィールドまたは出力フィールドを操作できます。出口インターフェイスにフィールド名を渡す方法は、サービスを提供するプログラム内でフィールドを渡す方法が連絡節でどのように定義されているかによって異なります。次の 2 つの方法があります。

項目がレベル-01 で定義される。この場合は、出口インターフェイスに渡されるフィールド名は、連絡節のフィールド名と同じです。
項目がレベル-01 の下位レベルで定義される。この場合は、出口インターフェイスに渡されるフィールド名には、そのフィールドが属する集団項目の名前がプリフィックスとして付きます。それぞれの名前は、ピリオド文字 (.) で区切ります。たとえば、次のレコードのフィールド「e」は「a.b.c.e」として一意に識別されます。
```
01 a.
   03 b.
      05 c.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
```
フィールド自体またはフィールドが属するどれかの集団項目が表の場合は、名前に「(n)」を追加することで、対応するテーブルインデックスを指定できます。n は表内のフィールドまたは項目の位置を表します。たとえば、次のレコードで「c」の 4 番目のフィールド「f」は、「a.b.c(4).f」として一意に識別されます。
```
01 a.
   03 b.
      05 c occurs 10.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
```

ユーザ出口プログラムのディプロイ

.int ファイル形式または .gnt ファイル形式にコンパイルされたユーザ出口プログラムをディプロイするには、$COBPATH のディレクトリにプログラムをコピーします。呼び出し可能な共有オブジェクト形式にコンパイルされたユーザ出口プログラムをディプロイするには、$LD_LIBRARY_PATH (AIX システムの場合は $LIBPATH、HP PA-RISC システムの場合は $SHLIB_PATH) のディレクトリにプログラムをコピーします。