IDIUTIL ListHF ユーザー出口

IDIUTIL ListHF ユーザー出口について、以下で説明します。

目的

この出口は、LISTHF 制御ステートメントを使用して IDIUTIL バッチ・ユーティリティーを実行し、ヒストリー・ファイルの管理で障害項目のリストを制御できます (詳しくは、LISTHF 制御ステートメントを参照してください)。この制御は、データ域フィールド UTL.PERFORM_ACTION を「Y」(項目をリストする場合) または「N」(項目をリストしない場合) に設定することによって行われます。フィールド UTL.PERFORM_ACTION は、出口を呼び出す前に「Y」に設定されます。UTL データ域の詳細については、UTL - IDIUTIL バッチ・ユーティリティー・ユーザー出口パラメーター・リストを参照してください。

ユーザー出口が呼び出される対象の障害項目は、指定された LISTHF 制御ステートメント基準に一致する障害項目です。

呼び出されるタイミング

LISTHF 制御ステートメントを使用して IDIUTIL バッチ・ユーティリティーが実行される場合は常に、この出口はヒストリー・ファイル内の障害項目ごとに 1 回呼び出されます。

パラメーター

パラメーターがどのように出口に渡されるかは、出口タイプ (REXX またはロード・モジュール) によって異なります。

Fault Analyzer は、IDIUTIL ListHF ユーザー出口を呼び出す前に、特定の障害および有効な処理オプションの現行値を使用してパラメーター・リストを初期化します。

REXX

出口は、以下の 2 つのステムを使用できます。

ENV.
ENV データ域内のすべてのフィールドに対して定義されたシンボルが含まれます (ENV - 共通出口環境情報を参照してください)。
UTL.
UTL データ域内のすべてのフィールドに対して定義されたシンボルが含まれます (UTL - IDIUTIL バッチ・ユーティリティー・ユーザー出口パラメーター・リストを参照してください)。

定義された変数名は、フィールド名と同じです。例えば、ENV データ域のフィールド VERSION にアクセスするには、REXX 変数 ENV.VERSION を使用します。

ロード・モジュール

この出口へのエントリーで、R1 には以下の 2 つのフルワードを構成するパラメーター・リストの 31 ビット・アドレスが含まれます。

word 1 の 31 ビット ENV アドレス。
ENV データ域のアドレス (ENV - 共通出口環境情報を参照してください)。
word 2 の 31 ビット UTL アドレス。
UTL データ域のアドレス (UTL - IDIUTIL バッチ・ユーティリティー・ユーザー出口パラメーター・リストを参照してください)。

注: このパラメーターが渡される最後のパラメーターあることを示すため、高位ビットがオンになります。

例 1: IDIUTIL ListHF ユーザー出口の呼び出し

以下は、REXX で書かれた IDIUTIL ListHF ユーザー出口の例です。

図 1. REXX IDIUTIL ListHF ユーザー出口 1 の例

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if UTL.VERSION <> 2 then
  say 'Note: UTL data area version change - field usage review required!'
UTL.PERFORM_ACTION = 'Y'  /* List current entry */

上記のサンプル出口がデータ・セット X.Y.Z のメンバー ABC として存在する場合、JCL DD ステートメント

//IDIEXEC DD DISP=SHR,DSN=X.Y.Z

および IDIUTIL バッチ・ユーティリティー制御ステートメント

Exits(LISTHF(REXX(ABC)))

を IDIUTIL バッチ・ユーティリティー・ヒストリー・ファイル管理ジョブに指定すると、出口が呼び出されます。

例 2: IDIUTIL ListHF ユーザー出口を用いた障害項目のカスタム・レポートおよび CSV ファイルの作成

以下は、REXX で書かれた IDIUTIL ListHF ユーザー出口の例です。

この出口の例は、カスタマイズ・レポートの作成方法や、スプレッドシート・アプリケーションへの入力として使用できるコンマ区切りファイルの作成方法を示しています。

使用されているフィールドに加えて、ENV または UTL データ域で使用可能なフィールドであれば、すべて組み込むことができます。

提供されているサンプルによって作成されたレポートには、以下の列が含まれています。

Fault ID
日付
時刻
ロック
ユーザー名
ユーザー・タイトル
CPU Sec

列データの説明については、選択可能な列を参照してください。ただし「CPU Sec」を除きます。これは、ENV.CPU_HSECONDS を基に Fault Analyzer で使用された合計 CPU 時間です。この値の詳細については、「ENV - 共通出口環境情報」の『CPU_HSECONDS』を参照してください。

カスタマイズされたレポートは、DDname MYREP に書き込まれます。MYREP DD ステートメントは、この出口を呼び出す IDIUTIL ジョブに組み込みます。例えば、以下のようにします。

//MYREP DD SYSOUT=*

コンマ区切りファイルは DDname COMMA に書き込まれます。COMMA DD ステートメントは、この出口を呼び出す IDIUTIL ジョブに組み込みます。例えば、以下のようにします。

//COMMA DD SYSOUT=*

永続ユーザー・フィールド ENV.USER_1 は、レポート・ヘッダーの書き込みが完了したという事実を記録するために使用されます。

図 2. REXX IDIUTIL ListHF ユーザー出口 2 の例

/* First ensure that the current data area versions match the         */
/* versions as at the time of coding the exit.                        */
If ENV.VERSION <> 5 Then
  Say 'Note: ENV data area version change - field usage review',
      'required!'
If UTL.VERSION <> 2 then
  Say 'Note: UTL data area version change - field usage review',
      'required!'
If ENV.USER_1='' Then Do
  /* Write report header */
  out.1="Fault ID Date       Time     Lock Username",
        "User Title                               CPU Sec"
  out.2="-------- ---------- -------- ---- --------",
        "---------------------------------------- -------"
  ADDRESS MVS "EXECIO 2 DISKW MYREP (STEM out."
  /* Write comma-delimited file header */
  out.1="Fault ID,Date,Time,Lock,Username,User Title,CPU Sec"
  ADDRESS MVS "EXECIO 1 DISKW COMMA (STEM out."
  ENV.USER_1='done'     /* Flag header done.                          */
End
/* The fault ID value is placed right-aligned in a work field.        */
fault_id=COPIES(' ',8-length(ENV.FAULT_ID))||ENV.FAULT_ID
/* The following lines use the REXX INSERT command to ensure that the */
/* work fields for each value are padded with blanks to fit the       */
/* report column width.                                               */
/* For information about the maximum with of any field, refer to the  */
/* User's Guide and Reference "Data Areas" chapter.                   */
abend_date=INSERT(ENV.ABEND_DATE,'',,10)
abend_time=INSERT(ENV.ABEND_TIME,'',,8)
lock_flag =INSERT(ENV.LOCK_FLAG,'',,4)
user_name =INSERT(ENV.USER_NAME,'',,8)
user_title=INSERT(ENV.USER_TITLE,'',,40)
/* If available, the CPU time in 1/100s of a second is changed to a   */
/* number of seconds with two decimal digits.                         */
if ENV.CPU_HSECONDS='' then cpu_sec=''
else cpu_sec=FORMAT(ENV.CPU_HSECONDS/100,4,2)
/* Write report line for this fault entry.                            */
out.1=fault_id abend_date abend_time lock_flag user_name user_title,
      cpu_sec
ADDRESS MVS "EXECIO 1 DISKW MYREP (STEM out."
/* Write comma-delimited line for this fault entry.                   */
out.1=fault_id","abend_date","abend_time","lock_flag","user_name,
      ","user_title","cpu_sec
ADDRESS MVS "EXECIO 1 DISKW COMMA (STEM out."
UTL.PERFORM_ACTION='N'  /* Optionally, suppress the standard report.  */
Exit 0

上図に示すサンプル出口は、IDI.SIDISAM1 データ・セット内のメンバー IDISUTL1 として提供されます。

サンプルの実行には、以下の JCL を使用できます。

//IDIUTIL  JOB parms
//RUNUTIL  EXEC PGM=IDIUTIL
//SYSPRINT DD SYSOUT=*
//MYREP    DD SYSOUT=*
//COMMA    DD SYSOUT=*
//IDITRACE DD SYSOUT=*       (Optional)
//IDIEXEC  DD DISP=SHR,DSN=IDI.SIDISAM1
//SYSIN    DD  *
Exits(LISTHF(REXX(IDISUTL1)))
FILES(my.histfile)
LISTHF
/*

例 3: IDIUTIL ユーザー出口を使用した今後実行する統計分析向けの異常終了データの収集

ヒストリー・ファイルは動的です。障害項目をヒストリー・ファイルから明示的に削除したり、自動のスペース管理を使用して削除したりすることが可能です。障害項目データを分析アプリケーションへの入力として使用したいと考えている場合、障害項目データをヒストリー・ファイルの外部で収集して保持することが必要になる可能性があります。IDI.SIDISAM1 データ・セットの IDISUTL2 メンバーは、この目的のために定期的に実行できる REXX プログラムのサンプルです。

IDISUTL2 メンバーの最後のサンプル JCL では RUNUTIL ステップと MERGE ステップを実行します:

RUNUTIL ステップでは、IDISUTL2 を IDIUTIL LISTHF ユーザー出口として実行し、1 つ以上のヒストリー・ファイル・データ・セットから障害項目の CSV 形式ファイルを生成します。(このステップについては、例 2 で説明しています。)
MERGE ステップでは、ALLDATA DD ステートメントによって指定された累積ファイルに、RUNUTIL ステップで収集した CSV データを付け足します。