通知ユーザー出口

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

目的

この出口を使用して、ヒストリー・ファイルへの障害の記録について、または、以前に発生した障害の重複発生について、インストール・システム固有の通知を行うことができます。例えば、出口を使用して、障害が発生したアプリケーションの担当者に E メールを送信できます。

出口が呼び出された理由は、NFY データ域フィールドの NFYTYPE フィールドに、以下のいずれかのように示されます。

C

障害が作成されました。

障害が記録されたヒストリー・ファイルの名前は ENV.HFZHIST データ域フィールドに提供され、記録された障害に割り当てられた障害 ID は、ENV.FAULT_ID データ域フィールドに示されます。

Z Abend Investigator は、割り当てられた障害 ID およびヒストリー・ファイルを示すメッセージ HFZ0003I を発行します。

リアルタイム・レポートの概要セクションのコピーは、NFY.SYNOPSIS データ域フィールドから使用可能です。SYNOPSIS の各行は、改行文字 (X'15') で区切られます。このフィールドに関する詳細については、NFY データ域を参照してください。

R

Recovery fault recording

この値は、Z Abend Investigator のリカバリー障害記録機能の結果として作成された障害を示します。(この機能の詳細については、リカバリー障害記録を参照してください。)

Z Abend Investigator は、割り当てられた障害 ID およびヒストリー・ファイルを示すメッセージ HFZ0126I を発行します。

N

通常重複。

この値は、NoDup(NORMAL) オプションの基準が現行障害に一致したため、ヒストリー・ファイル障害項目が書き込まれないことを示します。(NoDup(NORMAL) の詳細については、NoDupを参照してください。)

オリジナルのヒストリー・ファイル名と障害 ID は、ENV.HFZHIST および ENV.FAULT_ID データ域フィールドに示されます。

DUPCOUNT フィールドには 1 が設定されます。

F

高速重複 (CICS®)。

この値は、NoDup(CICSFAST) オプションの基準が現行障害に一致したため、分析が実行されなかったことを示します。(NoDup(CICSFAST) の詳細については、NoDupを参照してください。)

オリジナルのヒストリー・ファイル名と障害 ID が使用可能な場合は、それらは ENV.HFZHIST および ENV.FAULT_ID データ域フィールドに提供されます。

DUPCOUNT フィールドには、30 秒の記録期間内に発生した重複の数が設定されます。

呼び出されるタイミング

この出口は、Z Abend Investigator がヒストリー・ファイルへの障害の記録を完了した後に呼び出されます。

パラメーター

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

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

REXX

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

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

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

ロード・モジュール

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

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

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

REXX からの非 REXX ロギング・ルーチンの呼び出し

例えば、REXX で書かれていない外部ロギング・ルーチンの呼び出しなどを行う、REXX で書かれた通知ユーザー出口のために、2 つのステム変数が新たに追加されました。ステム変数は、すべての使用可能なデータ域値を外部ルーチンに渡すために使用できます。これらのステム変数は以下のとおりです。

ENV.RECORD
NFY.RECORD

これらのそれぞれが、単一 REXX 変数内に ENV または NFY データ域全体を含んでいます。それぞれが表すものはデータ域全体であり、それは既に提供されているため、これらの変数は、非 REXX 出口の対応するデータ域の中に、フィールドとして存在しません。

これらの変数を外部の非 REXX ルーチンに対する引数リストの中に使用することで、REXX 出口では、将来発生する可能性のあるこれらのデータ域の変更について配慮する必要がなくなります。

外部ルーチンは、データ値へのアクセスに、提供される言語依存データ域マッピングを使用する必要があります (ロード・モジュール出口を参照してください)。ENV.RECORD および NFY.RECORD 変数内の値はすべて読み取り専用と見なされるので、外部ルーチンで更新することはできません。更新が必要な場合は、REXX 出口そのものを使って、適切なデータ・フィールド・ステム変数を更新しなければなりません。

例 1

以下は、REXX で書かれた通知ユーザー出口の例です。TSO SEND メッセージを発行します。

図 1. サンプル REXX 通知ユーザー出口 1

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Issue SEND command via TSO batch job */
queue "//NOTIFY   JOB  MSGCLASS=Z"
queue "//TSOBATCH EXEC PGM=IKJEFT01"
queue "//SYSTSPRT DD   SYSOUT=*"
queue "//SYSTSIN  DD   *"
/* Split the TSO SEND command over three data records that must
   each be padded with blanks to 80 bytes */
rec = "SEND 'Fault ID" ENV.FAULT_ID "assigned in history file -"
queue left(rec,80)
rec = strip(ENV.HFZHIST)||"' -"
queue left(rec,80)
rec = "USER("||strip(ENV.USER_ID)||") LOGON"
queue left(rec,80)
queue '/*'
/* 'Submit' the stacked TSO batch job */
n = queued()
if rc = 0 then do
   address mvs "EXECIO" n "DISKW DD1 (FINIS"
   "HFZFREE DD(DD1)"
end
exit 0

上記のサンプル出口がデータ・セット X.Y.Z のメンバー ABC として存在する場合、HFZCNFxx 構成メンバーまたは HFZOPTS ユーザー・オプション・ファイルのいずれかに次のオプションを指定すると、このサンプル出口が呼び出されます。

DataSets(HFZEXEC(X.Y.Z))
Exits(NOTIFY(REXX(ABC)))

例 2

以下は、REXX で書かれた通知ユーザー出口の例です。この出口は、SMTP 経由で E メール・メッセージを送信します。

図 2. サンプル SMTP REXX 通知ユーザー出口 2

/* REXX *
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Issue SMTP message via SMTP batch interface */
user = strip(ENV.USER_ID)
queue "helo pthmvs8.hcl.com"
queue "mail from:<"user"@pthmvs8.hcl.com>"
queue "rcpt to:<"user"@hcl.com>"
queue "data"
queue "Date: " date('N') time('C')
queue "From:<"user"@pthmvs8.hcl.com>"
queue "To:<"user"@hcl.com>"
queue "Subject: Batch job "strip(ENV.JOB_NAME)" abend "ENV.ABEND_CODE
queue " "
queue "Fault ID "ENV.FAULT_ID" assigned in history file"
queue strip(ENV.HFZHIST)" for job "ENV.JOB_NAME
queue "program "ENV.EXEC_PGM_NAME" module "ENV.ABEND_MODULE_NAME"."
queue ""
n = queued()
"HFZALLOC DD(DD1) SYSOUT(A) DEST(PTHMVS8.SMTP)"
address mvs "EXECIO" n "DISKW DD1 (FINIS"
"HFZFREE DD(DD1)"
exit

この出口を機能させるには、システムが MVS™ TCP/IP SMTP 環境を使用できなければなりません。

上に示されているサンプル出口は、IBM® Communications Server 製品に提供されている IBM® SMTP サーバーのバッチ・インターフェースを使用して検査されています。

サンプル・メッセージが正常に送達されるかどうかは、IBM® CS TCP/IP サービスと SMTP サーバーの構成、および出口が実行されているシステムで使用できる適切な TCP/IP ネットワーク・インフラストラクチャーによって決まります。

中間ネットワーク・ノードにファイアウォール、セキュリティー・ソフトウェア、およびメッセージ・フィルター・ソフトウェアが存在するなどの要因が、メッセージの正常な送達に影響を及ぼす可能性があります。

上記のサンプル出口がデータ・セット TEST.EXEC.PDS のメンバー NOTIFY1 として存在する場合、HFZCNFxx 構成メンバーまたは HFZOPTS ユーザー・オプション・ファイルのいずれかに次のオプションを指定すると、このサンプル出口が呼び出されます。

DataSets(HFZEXEC(TEST.EXEC.PDS))
Exits(NOTIFY(REXX(NOTIFY1)))

例 3

以下は、REXX で書かれた通知ユーザー出口の例です。この出口は、収集されたリアルタイム概要のすべての行を抽出し、表示します。

図 3. サンプル SMTP REXX 通知ユーザー出口 3

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Show synopsis */
rest = NFY.SYNOPSIS
do while rest<>''
  parse var rest nextline '15'x rest
  say nextline
end
exit 0

例えばこの例は、上記の例 2 と結合でき、E メール・メッセージに概要を取り入れることができます。

上記のサンプル出口がデータ・セット TEST.EXEC.PDS のメンバー FRED として存在する場合、HFZCNFxx 構成メンバーまたは HFZOPTS ユーザー・オプション・ファイルのいずれかに次のオプションを指定すると、このサンプル出口が呼び出されます。

DataSets(HFZEXEC(TEST.EXEC.PDS))
Exits(NOTIFY(REXX(FRED)))

例 4

次の例は、REXX で作成された通知ユーザー出口です。これを使用して、バッチ再分析ジョブを実行依頼し、DeferredReport 障害項目の保管レポートを生成し、オプションで、LangxCapture オプションによって使用されるサイド・ファイルを保管します。

図 4. REXX 通知ユーザー出口 4 の例

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
queue "//GENREP   JOB  MSGCLASS=X"
queue "//FA       EXEC PGM=HFZDA,"
queue "// PARM=('/FAULTID("ENV.FAULT_ID")',"
queue "//       'GenerateSavedReport',"
queue "//      )"
queue "//HFZHIST  DD   DISP=SHR,DSN="ENV.HFZHIST
queue "//SYSPRINT DD   SYSOUT=*"
/* 'Submit' the stacked batch reanalysis job */
n = queued()
"HFZALLOC DD(DD1) SYSOUT PGM(INTRDR)"
if rc = 0 then do
   address mvs "EXECIO" n "DISKW DD1 (FINIS"
   "HFZFREE DD(DD1)"
end
exit 0

DataSets(HFZEXEC(X.Y.Z))
Exits(NOTIFY(REXX(ABC)))