REXX チェックの基本事項

System REXX サービスを使用すると、インストール情報を収集して問題点を探すための REXX チェックを作成できます。このチェックでは、データ・セットを読み取り、AXRCMD 関数を使用してシステム・コマンドを発行し、その出力を調べてチェック結果をメッセージに出力するのが一般的です。また、IBM Health Checker for z/OS はチェック例外メッセージを WTO として作成することもできます。

REXX チェックは、System REXX で定義されている APF 許可の環境での System REXX アドレス・スペース内で実行します。

TSO 環境および非 TSO 環境用 REXX チェックを作成できます。 TSO 環境用のチェックを作成すると、動的な TSO 作業環境が得られます。また、これによってチェック・ルーチン自体が確実に単一アドレス・スペースで実行されるようになるため、非常にセキュアです。 SYS1.SAMPLIB のサンプルの HZSSXCHK に、TSO 環境用および非 TSO 環境用両方のチェックのコードを示しています。

z/OS® での REXX exec の作成および実行について詳しくは、「z/OS MVS Programming: Authorized Assembler Services Guide」の『System REXX』を参照してください。

REXX チェックはできるだけ単純なものにすることをお勧めします。概略的に言えば、REXX チェックは次のステップで構成されます。

HZSLSTRT 関数を呼び出して、exec が実行を開始済みであることを示し、HZSPQE データ域の一部のチェック情報を REXX 変数に配置します。
チェック定義の IBM® Health Checker for z/OS で設定されている HZS_PQE_ENTRY_CODE REXX 変数を参照し、exec が複数の REXX チェックを含む場合に呼び出される REXX チェックを識別します。
REXX チェックの処理を開始します。
必要に応じて、IBM Health Checker for z/OS で設定される機能コード (HZS_PQE_FUNCTION_CODE にある) を調べます。この機能コードが、REXX チェックの初回の反復であることを表す INITRUN である場合、REXX チェックは HZS_PQE_CHKWORK フィールドを NULL に設定します。また、REXX チェックでは、必要なセットアップがある場合は実行する必要があります。
REXX チェックでは、システムがパラメーター・データが変更されたことを示したときに、REXX チェック用の入力パラメーターがある場合はそれを確認する必要があります。 HZSLSTRT REXX 関数の出力変数 HZS_PQE_LOOKATPARMS を使用して、REXX チェックが前回実行されてからチェック・パラメーターが変更されたかどうかを確認します。 (チェック・パラメーターは、HZSLSTRT 出力変数 HZS_PQE_PARMAREA に含まれています。) HZS_PQE_LOOKATPARMS 変数が ON に設定されている場合、REXX チェックが前回実行されてからチェック・パラメーターが変更されたことを示します。 HZSLFMSG REXX 関数の入力変数を使用して、REXX チェックが検出したパラメーター・エラーを報告します。 HZSLFMSG 関数を参照してください。
ここからが REXX チェックの中心部分、つまり、システム上の潜在的問題の検査です。
HZSLFMSG 関数を使用して、メッセージを出すか、またはパラメーターおよび REXX チェックで発生するその他のエラーを処理します。 HZSLFMSG は、HZSFMSG マクロに対するインターフェースです。 HZSFMSG マクロ - フォーマット済みチェック・メッセージの発行を参照してください。さらに HZSLFMSG では、REXX チェックの状況を設定または変更します。
HZSLSTOP 関数を呼び出し、REXX チェックの実行が完了したことを示します。

REXX チェックは System REXX が稼働中である場合のみ実行: これらのチェックは System REXX アドレス・スペースで実行されているため、System REXX が使用可能でない場合、REXX チェックは実行されません。 REXX チェックを追加するには、IBM Health Checker for z/OS に対する REXX チェックの定義を参照してください。

REXX チェックの環境の定義: REXX チェックは System REXX で定義され制御されている環境の System REXX アドレス・スペースで実行されます。 IBM Health Checker for z/OS は、AXREXX サービスを使用して REXX チェックを実行します。 REXX チェックは、IBM Health Checker for z/OS のプロシージャー hzsproc に割り当てられているセキュリティーのもとで実行されます。詳細については、「z/OS MVS Programming: Authorized Assembler Services Guide」の『System REXX』を参照してください。

システムは、REXX チェックのメッセージ・テーブルを IBM Health Checker for z/OS アドレス・スペースにロードします。

すべての REXX チェックが開始時に使用する情報: IBM Health Checker for z/OS が REXX チェックを呼び出す場合、REXX チェックが使用する次の HZSLSTART 関数変数を設定します。

HZS_HANDLE。REXX チェックと IBM Health Checker for z/OS の間で処理を同期するために、リモート REXX チェックを識別します。REXX チェックはリモート・チェックで、System REXX アドレス・スペース内で実行されるため、これは重要です。システムは、HZSLSTRT、 HZSLFMSG、および HZSLSTOP 関数内でこのハンドルを入力として使用します。 REXX チェックで、このフィールドを変更してはなりません。また、プロシージャーでこれらの関数への呼び出しをカプセル化する場合を除き、おそらくは参照する必要さえありません。この場合、必ず REXX EXPOSE ステートメントを使用してプロシージャー内での HZS_HANDLE の使用を許可するようにしてください。これにより、ABEND 290 RSN=858 (HZS_HANDLE が無効) を回避することができます。
HZS_PQE_ENTRY_CODE。複数のチェックを含む REXX チェックに対して呼び出されるチェックを識別します。
HZS_PQE_FUNCTION_CODE。REXX チェックの呼び出しが初回であるか (INITRUN)、初回以降の反復であるか (RUN) を示します。

REXX チェックでは、1 つの設定または 1 つの潜在的問題のみを調べるように限定してください。 REXX チェックの有効範囲を限定すれば、インストール先で REXX チェックを使用して、次のことを簡単に行うことができるようになります。

REXX チェックが検出したすべての例外について、その例外の修正、設定のオーバーライド、または REXX チェックの非アクティブ化を行うことによって解決する。
REXX チェックのデフォルト値 (重大度またはインターバルなど) に対する適切なオーバーライド値を設定する。

REXX チェックに戻りコードを設定してはならない: IBM Health Checker for z/OS は、REXX チェックで設定されるいかなる戻りコードも無視します。 HZSLFMSG 関数を使用する場合、システムは RESULT 変数および HZSLFMSG_RSN 変数に情報を返します。

2K チェック作業域の使用: 2K チェック作業域 (HZSLSTRT 関数によって使用可能になる HZS_PQE_CHKWORK 変数) は、REXX チェックの存続期間中のすべてのチェック反復にわたって保存しておきたいデータを保持するために使用してください。システムは、INITRUN 機能コード呼び出しの前に 2K 作業域を NULL に設定します。 HZS_PQE_CHKWORK 変数は、REXX チェックが書き込みを行う必要のある唯一の HZSLSTRT 変数です。 REXX チェックが HZSLSTOP System REXX 関数を呼び出す場合、システムは HZS_PQE_CHKWORK の内容を保存します。また、次のいずれかが発生した場合は、その領域を NULL に設定します。

REXX チェックが初めて実行される
チェックが REFRESH (リフレッシュ) される
無効なパラメーター以外の何らかの理由で、チェックが INACTIVE (非アクティブ) または DISABLED (使用不可) のいずれかの状態になる

例えば、データ・セットの割り振りなど REXX チェックで追加のリソースを取得する場合、REXX チェックは完了する前にこれらのリソースを解放する必要があります。 REXX チェックは、ローカル・チェックと異なり、クリーンアップまたは削除のために呼び出されることはありません。したがって、REXX チェックを再度実行する場合、そのアドレス・スペースまたは同一のタスクで実行される保証はありません。また、REXX チェックはタイムアウトまたは取り消しなどの例外以外の状態が発生したときにもリソースを解放する必要があります。

IBM Health Checker for z/OS の System REXX 関数の使用: 次に示す System REXX 関数を REXX チェックで使用します。いずれかの HZSLxxxx 関数が戻りコード 8 以上で失敗した場合、チェックはエラーとしてマークされることに注意してください。エラーの原因を判別するには、IBM Health Checker for z/OS の System REXX 関数の個々の HZSLxxxx 関数からの戻りコードを参照してください。

REXX チェックの実行が開始したことを示す HZSLSTRT を呼び出します。この関数は、チェック定義値などの REXX チェックの HZSPQE 情報を含む REXX 変数を設定します。この関数は、REXX チェックがまさに開始されたときに使用されます。 HZS_PQE_CHKWORK 作業域を除き、いずれの HZSLSTRT 変数も変更しないでください。 REXX チェックでユーザーが使用する最も重要な HZSLSTRT 変数の一部には、以下があります。

表 1. REXX チェックで使用する HZSLSTRT 変数の重要な HZSPQE 情報
フィールド名	意味
HZS_PQE_FUNCTION_CODE	REXX チェックの機能コードを含みます。 REXX チェックは、RUN または INITRUN のいずれかの機能コードに応じて制御を受け取ります。システムは REXX チェックに入るときに、このフィールドを設定します。
HZS_PQE_ENTRY_CODE	チェック定義内で REXX チェックに割り当てられている ID (入り口コード) が含まれています。入り口コードは、REXX exec に複数のチェックが含まれている場合に使用されます。システムは REXX チェックに入るときに、このフィールドを設定します。
HZS_HANDLE	REXX チェックと IBM Health Checker for z/OS の間で処理を同期するために、リモート REXX チェックを識別します。 REXX チェックはリモート・チェックで、System REXX アドレス・スペース内で実行されるため、これは重要です。REXX チェックは、HZSLSTRT、 HZSLFMSG、および HZSLSTOP 関数への入力としてこのハンドルを使用します。システムは REXX チェックに入るときに、このフィールドを設定します。
HZS_PQE_LOOKATPARMS	パラメーターが変更されたことを示すビット。このビットが ON の場合は、REXX チェックは HZS_PQE_PAREMAREA および HZS_PQE_PARMLEN 変数を読み取る必要があります。
HZS_PQE_VERBOSE	REXX チェックが冗長モードかどうかを示すバイト。
HZS_PQE_DEBUG	REXX チェックがデバッグ・モードであるかどうかを示すバイト。
HZS_PQE_PARMAREA	ユーザー・パラメーターを含む領域。オペレーター・コマンドまたは HZSPRMxx ステートメントで PARMS 値を囲む引用符は含まれません。
HZS_PQE_CHKWORK	必要に応じて REXX チェックによって使用されマップされる 2K チェック作業域。システムは、機能コード RUN を使用して REXX チェックを呼び出す前に、2K チェック作業域をゼロにリセットします。 REXX チェックは、このフィールドへの書き込み、およびこのフィールドからの読み取りの両方を行うことができ、システムは、以後のチェックの呼び出しのために、その情報を保存しておきます。その他の任意の変数に対する変更は、関数呼び出しを越えては保存されません。
HZS_PQE_DOM_CHECK	チェックが IBM Health Checker for z/OS に追加されたときに DOM(SYSTEM \| CHECK) パラメーターがどのように設定されていたかを示します。値が 1 の場合、チェックには DOM(CHECK) が指定されていました。値が 0 の場合、チェックには DOM(SYSTEM) が指定されていました。 DOM=CHECK および HZSFMSG REQUEST=DOM/ HZSLFMSG_REQUEST=DOM がどのように動作するかについて詳しくは、チェックの例外メッセージ WTO およびその自動化が及ぼす影響の制御を参照してください。

返されるすべての REXX 変数については、HZSLSTRT 関数を参照してください。

以下を実行するために、HZSLFMSG を呼び出します。
- REXX チェック・メッセージおよび IBM Health Checker for z/OS メッセージを発行します。この関数を複数回、REXX チェックが呼び出します。 HZSLFMSG 関数を使用した REXX チェックからのメッセージの発行を参照してください。
- チェックに関する問題を報告します。つまり、HZSLFMSG を使用して、問題を報告し、チェックの状態を変更します。また、チェックに対して不正なパラメーターや不適切な環境などのエラーが検出された場合は、REXX チェックを停止することもできます。
REXX チェックが反復を完了したことを示す HZSLSTOP を呼び出します。 REXX チェックは REXX チェックの最後にこの関数を呼び出します。この関数は REXX チェックの次の反復のために、HZS_PQE_CHKWORK を保存します。

すべての REXX 関数は戻りコード (RESULT 変数) および理由コード (HZSLnnnn_RSN 変数) を返します。また、これらの関数は他の多くの役立つ入力変数および出力変数を含みます。これらの関数に関する詳細説明については、IBM Health Checker for z/OS の System REXX 関数を参照してください。

グループ化された REXX チェックに対する個々の入り口コードの提供: 複数の REXX チェックが単一の REXX exec を使用することができます。これを実行する場合でも、個々の REXX チェックは独自の HZSPQE 領域を取得します。そのため、個々のチェックに対する固有の入り口コードを定義する必要があります。これにより、各 REXX チェックの REXXIN および REXXOUT データ・セットが固有になります。つまり、システムがデータ・セット名の接尾辞で入り口コードを使用します。 REXX チェックが HZSLSTART 関数の HZS_PQE_ENTRY_CODE 変数に入れて渡される入り口コードを見つけて、そこに示されている REXX チェックの処理に制御を渡すように、コーディングしてください。 HZSADDCK 呼び出しまたは HZSPRMxx parmlib メンバーにおけるチェック定義の ENTRYCODE パラメーターを使用して各 REXX チェックの入り口コードを定義します。IBM Health Checker for z/OS は、ユーザーが REXX チェックに対して定義する入り口コードの固有性を検査しないということに注意してください。

次の例では、REXX チェックが入り口コードを使用して個々のチェックに制御を渡す方法を示します。

/*********************************************************************/
/* Check the entry code to determine which check to process          */
/*********************************************************************/
 IF HZS_PQE_ENTRY_CODE = 1 THEN
   DO
     Call Process_HZS_SAMPLE_REXXIN_CHECK
   END
 IF HZS_PQE_ENTRY_CODE = 2 THEN
   DO
     Call Process_HZS_SAMPLE_REXXTSO_CHECK
   END
 EXIT

HZSADDCHECK 出口ルーチンを使用してシステムに REXX チェックを追加する場合も、1 つの出口ルーチンを使用して、関係する複数のチェックをシステムに追加するようにしてください。 IBM Health Checker for z/OS に対する REXX チェックの定義を参照してください。

個々の REXX チェック間で通信を行おうとしないでください。すべての REXX チェックを同じ exec に入れた場合でも、それらのチェック間の通信に依存することがないようにしてください。各 REXX チェックは独立して機能することを目的としており、固有の重大度、理由、パラメーター、HZSPQE データ域および入り口コードを持っています。