出口点、API、環境変数
対話式ジョブで照会メッセージと応答メッセージを制御する - このようにします！
IBM はリリースごとに IBM i オペレーティング・システムへの出口点をさらに追加しています。こうした出口点により、出口点に関連するイベントが発生するたびにシステムが呼び出す出口プログラムを作成できます。ただし、いつ出口プログラムを実行するか、さらに制御を細分化しなければならない場合があります。選択肢として、個々のジョブ・レベルで環境変数を指定することがあります。環境変数は、ジョブで実行しているどのプログラムでもパラメーターや呼び出しレベルに関係なく、その設定にアクセスできるような、グローバル設定をジョブに行います。一部の環境変数を作成して使用するシステム・コンポーネントもありますが、必要な場合は環境変数を定義して、追加することができます。
ジョブの環境変数を追加し、取得するには、適切な環境変数の CL コマンドと API を使用します。この記事では、その方法を、例を示して説明します。関連する出口点については、照会処理出口点 (QIBM_QMH_HDL_INQEXT) と応答処理出口点 (QIBM_QMH_REPLY_INQ) を利用しています。
照会メッセージへの応答を制御する
ジャーナル項目を抽出して、それらのレコードを元のファイルに復元する新しいユーティリティーを開発中に、CPA32B2 照会メッセージ ("Change of file &1 may cause data to be lost": ファイル &1 を変更するとデータが失われるおそれがあります) に出くわしました。これによって、照会処理出口点と応答処理出口点に注目しました。この開発では必然的に、テーブルのいずれかのフィールドを削除するのに必要だった SQL ステートメント ALTER TABLE DROP COLUMN を実行するため、新しい Run SQL Statements (RUNSQL) コマンドを CL プログラムで使う必要が生じました。
ジョブを対話式に実行している場合、CPA32B2 メッセージがジョブの外部プログラム・キューに送信されます。デフォルトの照会メッセージ処理 (INQMSGRPY) ジョブ属性の *RQD では、強制的にメッセージに返信しなければなりません。バッチ・ジョブについては、メッセージはデフォルトで自動的に返信されます。ジョブの照会メッセージ処理属性を *SYSRPYL に設定すると、(定義されている場合) CPA32B2メッセージのシステム応答リスト・エントリーで指定された応答を返します。
ここで私の目的は、列をドロップし、ユーザーに応答を求めない照会メッセージの応答に対して「I」という応答値を使って、対話式ジョブにおけるこの動作を制御することでした。バッチ・ジョブで照会メッセージを処理するため、デフォルトの応答値「C」を代行受信し、応答値「I」と置き換えたかったのです。これこそ正に、照会処理出口点と応答処理出口点が可能な処理内容です。
照会処理出口点パラメーター
照会処理出口プログラムは、照会メッセージがジョブの *EXT メッセージ・キューに送信され、Display Program Messages 画面がジョブに割り込み、応答を取得しようとしている場合に、対話式ジョブで呼び出されます。その後、出口プログラムは応答を紹介メッセージに送信し、対話式ユーザーは応答する必要がなくなります。照会処理出口点は、図1 でその出口プログラムに対するインターフェースを定義します。
この図では、Type of call パラメーターの値は常に「I -Inquiry needs reply」になります。同様に、パラメーター Qualified message queue name は常に値 *EXT を含んでいなければなりません。出口点の現在の実装に対する、他の選択肢はありません。Message key パラメーターは、外部メッセージ・キューに保持されているメッセージの一意の ID を提供します。最後の Message identifier パラメーターでは、メッセージ ID 値を照会することで、代行受信されている照会メッセージが出口プログラムに関連しているかどうか簡単に評価できます。照会メッセージを代行受信する場合、照会メッセージに応答を送信することで、その処理を行う必要があります。これを行うには、Send Reply Message (QMHSNDRM) API を使用して、選択した応答値を送信します。これにより照会メッセージが表示されず、ユーザーからの応答は必要なくなります。
出口プログラムが無事代行受信し、照会メッセージに応答すると、情報メッセージ (この場合は CPI2516: "Reply sent by inquiry handling exit program": 照会処理出口プログラムにより返信されました) が、照会メッセージが発行されたジョブのジョブ・ログに記録されます。さらにイベントを文書化するため、CPI2516 の第 2 レベル・メッセージ・テキストには、照会メッセージ、出口点、出口プログラムの詳細がすべて入っています。
CPA32B2 照会メッセージがバッチ・ジョブで発行されている場合、上記の手法は効果がありません。これを受けて、QIBM_QMH_REPLY_INQ 出口点を使用する必要があります。この出口点は、登録された出口プログラムを照会メッセージが応答を受信した時点で呼び出します。すでに説明したように、メッセージ・システム・コンポーネントのデフォルト応答メカニズムは通常は、照会に応答します。例えば、CPA32B2 メッセージの応答値は結果的に C となり、ALTER TABLE SQL ステートメントは失敗します。確実に応答値 I が返されるようにするためには、出口点 QIBM_QMH_REPLY_INQ に出口プログラムを登録し、出口プログラムに応答値をデフォルト応答値と置き換えさせることができます。
応答処理出口点パラメーター
図2 は応答処理出口点で採用されているパラメーターを示します。Type of call パラメーターは、出口プログラムを呼び出す理由を定義しています。サポートされている値は図3 をご覧ください。Qualified message queue name パラメーターは、照会メッセージを含むメッセージ・キューの修飾名を指定し、Message key パラメーターは応答が必要な、そのメッセージ・キュー内の特定の照会メッセージを特定します。Message identifier は、照会メッセージがメッセージ・ファイルに保存された事前定義されたメッセージとして送信されている場合、そのメッセージ ID の7文字を保持し、(例: Send Break Message - SNDBRKMSG - コマンドの場合同様) 即時メッセージの場合空白が入ります。
Reply パラメーターは、処理された照会メッセージの応答値を規定します。出口プログラムはこのパラメーターを使用して、入力値を新しい値と置き換えることで、提供された応答値をオーバーライドします。Length of reply と CCSID of reply という、次の 2つのパラメーターも入出力です。出口プログラムは、応答を拒否、承認、または置き換えるかどうかを示す Reply action return code パラメーターを定義しています。
QIBM_QMH_REPLY_INQ 出口プログラムが応答値を置き換えるよう要求した場合、CPD2479 診断メッセージ ("Reply handling exit program requested to replace a reply value": 応答処理出口プログラムが応答値の置き換えを要求しました) が、照会メッセージを生成しているジョブに記録されます。応答値が正常に置き換わった後、CPF2458 診断メッセージ ("Reply replaced by reply handling exit program": 応答処理出口プログラムにより応答が置き換えられました) がジョブ・ログに追加されます。両方のメッセージは、その第 2 レベル・メッセージ・テキストのイベントに関する詳しい情報を提供しています。
明快な実装
両方の出口点に対する出口プログラムの実装は、シンプルです。すでにお話ししたように、CPA32B2 照会メッセージのオーバーライドは、照会メッセージが発行されているジョブに、特定の環境変数を定義した場合のみ発生するはずです。このため、私は SQL_VFY_ALTER_IGNORE という環境変数を定義しました。この変数が存在し値 Y がある場合、ALTER TABLE DROP COLUMN SQL ステートメントが正常に処理され、完了するよう、両方の出口プログラムは、 CPA32B2 照会メッセージの応答値を値 I にオーバーライドして変更します。
QIBM_QMH_HDL_INQEXT 出口プログラム CBX2611 は次のステップを実行します。
- type of callパラメーターが Inquiry needs replyかどうか確認します。
- メッセージ IDがCPA32B2かどうか確認します。
- 環境変数 SQL_VFY_ALTER_IGNORE が定義されており、値が Y かどうか確認します。
- メッセージがシステム・モジュール QDBCHGFI およびプロシージャー VFYALTER により、送信されたかどうか確認します。これらの事項が確認されたら、出口プログラムは 値 I の応答メッセージを送信します。
図4 はこのアウトラインを採用した RPG IV コード・スニペットを示しています。
QIBM_QMH_REPLY_INQ 出口プログラム CBX2612 は、次の 5つのステップを実行します。 - type of call パラメーターが Default reply notification かどうか確認します。
- メッセージ ID が CPA32B2 かどうか確認します。
- 応答長がゼロより大きく、応答値が C かどうか確認します。
- 環境変数 SQL_VFY_ALTER_IGNORE が定義されており、値が Y かどうか確認します。
- これらの事項が確認されたら、出口プログラムは応答値を値Iに置き換えます。
図5では、このアウトラインを実装する RPG IV コード・スニペットを確認できます。
出口プログラムを問題なく(この例ではライブラリーQGPLに)作成したら、次の2つのコマンドを使用して、それらの出口プログラムを、それぞれの出口点に追加できます。
出口プログラムのアウトラインで示しているように、出口プログラムは、環境変数 SQL_VFY_ALTER_IGNORE を現在のジョブに追加し、値Yを指定した場合のみ、 CPA32B2 照会メッセージを処理します。現在のジョブの新しい出口プログラムを起動するには、CPA32B2 照会メッセージを生成している RUNSQL ステートメントを実行する直前に、次のコマンドを実行します。
RUNSQL ステートメントが完了したら、次のコマンドを使用して、現在のジョブの新しい出口プログラムをすぐに非アクティブにします。
図6 は、CL プログラムで CPA32B2 照会メッセージを抑制する方法の例を示しています。
すでに説明した RUNSQL シナリオの他に、CPA32B2 照会メッセージは、CHGPF コマンド経由で変更した DDS 定義の物理ファイルが原因で発行される場合があります。CPA32B2 は、CHGPF コマンドが SRCFILE パラメーターと SRCMBR パラメーターを指定し、ポイントされているソース・メンバーが、省略されているフィールドまたは変更されたフィールド属性という点で、現在のレコード・フォーマットと互換性がないレベルまで物理ファイルを変更した場合にも発行されます。
さらに続く
RUNSQLシナリオは、 Example列によって、来たるべきAPIの開始点を形成します。その記事では、ここで説明した技法を実践的に使用する新しい Extract Journal Data (EXTJRNDTA)コマンドを紹介します。では、そのときまで！
