05.2ダンプの書き出しとトレースの記録（SNAPとGTRACE）
プログラム（リージョン）のダンプを取得するにはDUMPオプション指定のABENDマクロを発行する方法があります。しかしABENDマクロではプログラムの実行はそこで終わってしまいます。プログラムを終わらせずにダンプを取るには自らストレージの内容を編集してデータセット（SYSOUT）に書き出すこともできますが、SNAPサービスを使えば簡単にダンプを取ることができます。またダンプはエラーが起きた時点でのスポットな診断情報ですが、エラーの内容によっては、プログラムの動きやデータの変化を時系列に記録したい場合があります。これはトレースと呼ばれます。トレースもGTRACEマクロで簡単に記録することができます。
プログラムの状態やストレージの内容をダンプする
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
OPEN (SNAPDCB,OUTPUT) OPEN SNAPDUMP DATASET
L R2,=F'10000' LOAD GETMAIN SIZE
GETMAIN R,LV=10000 OBTAIN WORKING STORAGE
LR R0,R1
LR R1,R2
L RF,=A(X'C8000000') LOAD PAD CHAR = C'H'
MVCL R0,RE INITIALIZE STORAGE AREA
?
SNAP DCB=SNAPDCB, DO STORAGE DUMP FOR OUR PROGRAM+
SDATA=(CB),PDATA=(PSW,REGS,SA,JPA)
?
SNAP DCB=SNAPDCB, DO STORAGE DUMP FOR OUR REGION +
SDATA=(LSQA,SWA,DM,CB,TRT,ERR,SUM), +
PDATA=(PSW,REGS,SA,JPA,SPLS)
?
LA R2,DATAAREA LOAD BEGIN STORAGE ADDRESS
LA R3,DATAAREA+L'DATAAREA-1 LOAD ENDED STORAGE ADDRESS
SNAP DCB=SNAPDCB, DO STORAGE DUMP FOR SPECIFIED +
STORAGE=((2),(3)) RANGE BY GR2 AND GR3
MVI DATA1,C'A'
MVC DATA1+1(L'DATA1-1),DATA1 PAD WORKAREA BY C'A'
MVI DATA1+24,C'Z'
MVI DATA1+64,C'Z'
MVI DATA1+104,C'Z'
MVI DATA2,C'B'
MVC DATA2+1(L'DATA2-1),DATA2 PAD WORKAREA BY C'B'
MVI DATA2+24,C'Z'
MVI DATA2+44,C'Z'
MVI DATA3,C'C'
MVC DATA3+1(L'DATA3-1),DATA3 PAD WORKAREA BY C'C'
MVI DATA3+24,C'Z'
MVI DATA3+54,C'Z'
MVI DATA3+80,C'Z'
SPACE ,
LA R1,STORLIST LOAD STORAGE LIST
LA R0,DATA1 LOAD SNAP AREA-1
ST R0,0(,R1) SET IT IN STORAGE LIST
LA R1,4(,R1) LOCATE TO NEXT ENTRY
LA R0,DATA1+L'DATA1-1 LOAD END OF SNAP AREA-1
ST R0,0(,R1) SET IT IN STORAGE LIST
LA R1,4(,R1) LOCATE TO NEXT ENTRY
SPACE ,
LA R0,DATA2 LOAD SNAP AREA-2
ST R0,0(,R1) SET IT IN STORAGE LIST
LA R1,4(,R1) LOCATE TO NEXT ENTRY
LA R0,DATA2+L'DATA2-1 LOAD END OF SNAP AREA-2
ST R0,0(,R1) SET IT IN STORAGE LIST
LA R1,4(,R1) LOCATE TO NEXT ENTRY
SPACE ,
LA R0,DATA3 LOAD SNAP AREA-3
ST R0,0(,R1) SET IT IN STORAGE LIST
LA R1,4(,R1) LOCATE TO NEXT ENTRY
LA R0,DATA3+L'DATA3-1 LOAD END OF SNAP AREA-3
ST R0,0(,R1) SET IT IN STORAGE LIST
OI 0(R1),X'80' INDICATE HERE IS LAST ENTRY
SPACE ,
?
SNAP DCB=SNAPDCB, DO STORAGE DUMP FOR SPECIFIED +
LIST=STORLIST,STRHDR=HDRLIST RANGE BY STORAGE LIST
CLOSE (SNAPDCB) CLOSE SNAPDUMP DATASET
:
:
*---------------------------------------------------------------------*
DS 0F
DATAAREA DC XL256'00' DATA AREA
DATA1 DC XL128'00' DATA AREA-1
DATA2 DC XL64'00' DATA AREA-2
DATA3 DC XL96'00' DATA AREA-3
*---------------------------------------------------------------------*
STORLIST DC 6A(0) SNAP STORAGE LIST
HDRLIST CALL ,(HDR1,HDR2,HDR3),VL, SNAP STORAGE TITLE LIST +
MF=L
HDR1 DC AL1(L'HDR1TXT)
HDR1TXT DC C'DATA AREA-1(TEST DATA AREA-1)'
HDR2 DC AL1(L'HDR2TXT)
HDR2TXT DC C'DATA AREA-2'
HDR3 DC AL1(L'HDR3TXT)
HDR3TXT DC C'DATA AREA-3: WORK AREA FOR PROCESSING.'
*---------------------------------------------------------------------*
SNAPDCB DCB DDNAME=SNAPDUMP, SNAP DATASET DCB +
DSORG=PS,MACRF=W, +
RECFM=VBA,BLKSIZE=1632,LRECL=125
必要なJCL DD文
//SNAPDUMP DD SYSOUT=*
SNAPマクロはストレージ・ダンプを取得します。ダンプリストはDCBパラメーターで指定したDD文で定義したデータセットに書き込まれます。サンプルではDD名SNAPDUMPとしていますが任意の名前でかまいません。SNAPマクロ発行前に出力先データセットはあらかじめOPENしておかなければなりません。ダンプの出力が終わったらCLOSEします。DCBはサンプルのように定義します。サンプルでは各マクロ命令のエラーをチェックしていませんが、必要に応じてエラー処理を組み込みます。
1番目のサンプルは自分のプログラム領域をダンプする例です。ただしGETMAINした領域はダンプされません。GETMAINした領域のダンプが必要な場合は、PDATAパラメーターにSPLSを追加します。
2番目のサンプルは自分のプログラム領域を含めリージョン全体をダンプする例です。OSのコントロールブロックはフォーマットされるだけでなく、割り当てられている領域自体も出力されます。SDATAおよびPDATAパラメーターはMVSの例です。MSPとVOS3では若干異なるのでマニュアルで確認して下さい。
3番目のサンプルは指定したストレージ領域をダンプする例です。ダンプしたい領域の開始および終了アドレスを指定しています。
4番目のサンプルも指定したストレージ領域をダンプする例です。ダンプしたい領域の開始および終了アドレスをパラメーターではなく、リストで指定しています。リストはダンプしたい領域の開始・終了アドレスのペアーを複数個並べたものです。（ラベルSTORLIST）この例では3つの領域をダンプするので開始・終了アドレス×3で6ワードを使います。SNAPルーチンが最後のエントリーを判別するため、最終エントリーの終了アドレスの先頭ビットを1に設定します。MVSではSTRHDRパラメーターでダンプする領域に対応する見出し文字列を指定することもできます。見出しは1バイトの長さ＋タイトル文字列で構成されます。
OSのスーパーバイザー・ルーチンや出口ルーチンなどでダンプを取る場合は、SNAPマクロではなく、SDUMPマクロを使いSYS1.DUMPnnデータセットにSVCダンプを書き出します。システムプログラムであっても起動JCLがあればDD文が定義できますから、SNAPマクロは利用されます。しかしOS出口ルーチンのように不特定の空間で動作するものやシステム空間で動作するものはDD文を定義できませんので、SDUMPサービスによるSVCダンプが使われます。SDUMPマクロはAPF許可プログラムやスーパーバイザーモードのプログラムでなければ利用できません。
GTFにトレースレコードを書き込む
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
LA R2,TRECORD1 LOAD TRACE RECORD ADDRESS
LA R3,L'TRECORD1 LOAD TRACE RECORD LENGTH
GTRACE ID=1023, PUT GTF RECORD VIA GTRACE MACRO+
DATA=(2),LNG=(3) MAX LENGTH = 8192(MVS) +
= 240(MSP) +
= 256(VOS3)
CH RF,=H'4' GTF IS NOT ACTIVE ?
BE GTFINACT YES, IGNORED TRACE RECORD
BH GTFERROR MAY BE GTF PARAMETER ERROR
:
:
LA R0,TRECORD2 LOAD GTF RECORD DATA ADDRESS
ST R0,GTFPARM+4 SET IT IN PLIST
LA R0,L'TRECORD2 LOAD GTF RECORD DATA LENGTH
STH R0,GTFPARM SET IT IN PLIST
LA R1,GTFPARM GR1 --> GTF PLIST
LA RF,4 PUT GTF NOT ACTIVE CODE IN GR15
MC 1023,X'0E' MONITOR CALL FOR GTRACE +
GR1 --> +00: AL2(LNG),AL2(FID) +
+04: A(TRACE DATA)
:
:
*
GTFPARM DS 0F 2WORD PLIST
DC AL2(0) DATA LENGTH
DC AL2(0) FID(FORMAT ID) = 0
DC A(0) DATA ADDRESS
*
TRECORD1 DC C'AAAAAAAAAAAAAAAAAAA' TEST GTF DATA1
TRECORD2 DC C'BBBBBBBBBBBBBBBBBBBBB' TEST GTF DATA2
GTRACEマクロはGTFトレースデータセットに、ユーザートレースレコードを書き込みます。OPENもCLOSEもDCBも必要ありませんし、ある意味QSAMより簡単です。書き込み可能なデータの長さはOSによって異なります。（サンプルコードを見て下さい）VOS3では正式なマクロ名はETRACEですが、GTRACEでも利用できます。
トレースレコードを書き込むにはEID（EVENT ID）を決める必要があります。ユーザープログラムでは0?1023が指定できます。特に規約などがなければ1023でいいでしょう。FIDと言う、レコードを編集するときの識別番号（編集するプログラムを決める識別子）もありますが省略してかまいません。（FID=0とする）この場合IPCSやPRDMPでフォーマットする際、レコード内容はダンプ形式に編集されます。文字で構成されたレコードなら、わざわざOSのユーティリティでフォーマットしなくても、GENERでSYSOUTにコピーしても判別することができます。
正しく書き込めればGR15に復帰コード0が返ります。復帰コード4はGTFが起動されていないことを示します。8以上は基本的にパラメーターエラーです。復帰コードが32の場合、書き込むデータがページアウトされていたことを示します。これを防止するにはパラメーターPAGEIN=YESを指定します。（MVSとVOS3のみ）トレースデータ領域がページアウトされていた場合、ページインして書き込めるまでリトライします。絶対にロストしたくないレコードならPAGEIN=YESを指定します。よほどページングがヘビーなシステムでなければGTRACEを発行する前に書き込むデータを作るか触るかしておけば大丈夫でしょうが、気になる方は指定して下さい。マクロの展開形を見ればわかりますが、復帰コードが32ならデータ領域を一旦参照して（ページインされる）から書き込みをリトライします。
GTFにレコードを書くのは実は簡単です。MC命令で直接書き込むことができます。（実際はプログラム割込み：モニターイベントを起こし、割込みハンドラー経由でGTF空間にトレース書き込みを依頼する）わざわざGTRACEマクロを使わなくても直接CPU命令で行ってもかまいません。2番目のサンプルがGTRACEを使わず直接命令で行うものです。問題プログラム状態で利用できます。MVSではGTRACEマクロはAPF許可プログラム用のAPIマニュアルに記載されていますが、実際はAPF許可は不要です。
GTFの起動方法は以下にサンプルを示します。USR=3FFの3FFはEID=1023の16進数指定です。GTFに関してはマニュアルあるいはGTFトレースの採取とフォーマットを参照して下さい。
S GTF.GTF
R nn,TRACE=USRP
R nn,USR=3FF,END
R nn,U