05.2 ダンプの書き出しとトレースの記録（SNAPとGTRACE）

プログラム（リージョン）のダンプを取得するには、DUMPオプション指定のABENDマクロを発行する方法があります。しかし、ABENDマクロではプログラムの実行はそこで終わってしまいます。プログラムを終わらせずにダンプを取るには、自ら記憶域の内容を編集してデータセット（SYSOUT）に書き出すこともできますが、SNAPサービスを使えば簡単にダンプを取ることができます。また、ダンプはエラーが起きた時点でのスポットな診断情報ですが、エラーの内容によってはプログラムの動きやデータの変化を時系列に記録したい場合があります。これはトレースと呼ばれます。トレースもGTRACEマクロで簡単に記録することができます。

プログラムの状態や記憶域の内容をダンプする

SNAPマクロは、記憶域ダンプを取得します。ダンプ・リストは、DCBパラメーターで指定したDDステートメントに定義したデータセットに書き込まれます。サンプルでは、DD名SNAPDUMPとしていますが任意の名前でかまいません。SNAPマクロ発行前に、出力先データセットは予めOPENしておかなければなりません。ダンプの出力が終わったらCLOSEします。DCBは、サンプルのように定義します。サンプルでは、各マクロ命令のエラーをチェックしていませんが必要に応じてエラー処理を組み込みます。

1番目のサンプルは、自分のプログラム領域をダンプする例です。ただし、GETMAINした領域はダンプされません。GETMAINした領域のダンプが必要な場合は、PDATAパラメーターにSPLSを追加します。
2番目のサンプルは、自分のプログラム領域を含めリージョン全体をダンプする例です。OSのコントロール・ブロックは、フォーマットされるだけでなく割り当てられている領域自体も出力されます。
3番目のサンプルは、指定した記憶域をダンプする例です。ダンプしたい領域の開始および終了アドレスを指定します。
4番目のサンプルも、指定した記憶域をダンプする例です。ダンプしたい領域の開始および終了アドレスを、パラメーターではなくリストで指定しています。リストは、ダンプしたい領域の開始アドレスと終了アドレスの対を複数個並べたものです（ラベルSTORLIST）。この例では、3つの領域をダンプするので開始と終了アドレス×3で6ワードを使います。SNAPルーチンが最後のエントリーを判別するため、最終エントリーの終了アドレスの先頭ビットを1に設定します。STRHDRパラメーターで、ダンプする領域に対応する見出し文字列を指定することもできます。見出しは、1バイトの長さ＋タイトル文字列で構成されます。

OSのスーパーバイザー・ルーチンや出口ルーチンなどでダンプを取る場合は、SNAPマクロではなくSDUMPマクロを使いSYS1.DUMPnnデータセットにSVCダンプを書き出します。システム系のプログラムであっても、起動JCLがあるならDDステートメントが定義できますからSNAPマクロは利用できます。しかし、OS出口ルーチンのように不特定の空間で動作するものやシステム空間で動作するものはDDステートメントを定義できませんので、SDUMPサービスによるSVCダンプが使われます。SDUMPマクロは、APF許可プログラムやスーパーバイザー・モードのプログラムでなければ利用できません。

GTFにトレースレコードを書き込む

GTRACEマクロは、GTFトレース・データセットにユーザー・トレース・レコードを書き込みます。OPENもCLOSEもDCBも必要ありませんし、ある意味QSAMより簡単です。
トレース・レコードを書き込むには、EID（EVENT ID）を決める必要があります。ユーザー・プログラムでは、0～1023が指定できます。特に規約などがなければ1023でいいでしょう。FIDというレコードを編集するときの識別番号（編集するプログラムを決める識別子）もありますが、省略してかまいません（FID=0とする）。この場合、IPCSでフォーマットする際にレコード内容はダンプ形式に編集されます。文字で構成されたレコードなら、わざわざOSのユーティリティでフォーマットしなくてもGENERでSYSOUTにコピーしても判別することができます。
GTRACEマクロでは、データが正しく書き込めればGR15に復帰コード0が返ります。復帰コード4は、GTFが起動されていないことを示します。8以上は基本的にパラメーター・エラーです。復帰コードが32の場合、書き込むデータがページ・アウトされていたことを示します。これを防止するには、パラメーターPAGEIN=YESを指定します。トレースデータ領域がページ・アウトされていた場合、ページ・インして書き込めるまでリトライします。絶対にロストしたくないレコードならPAGEIN=YESを指定します。よほどページングがヘビーなシステムでなければ、GTRACEを発行する前に書き込むデータを作るか触るかしておけば大丈夫でしょうが気になる方は指定して下さい。マクロの展開形を見ればわかりますが、復帰コードが32ならデータ領域を一旦参照して（ページインされる）から書き込みをリトライします。

GTFにレコードを書くのは実は簡単です。MC命令(*1)で直接書き込むこともできます。わざわざGTRACEマクロを使わなずに、直接CPU命令で行ってもかまいません。2番目のサンプルが、GTRACEを使わず直接命令で行うものです。問題プログラム状態でも利用できます。MVSでは、GTRACEマクロはAPF許可プログラム用のAPIマニュアルに記載されていますが、利用に際してAPF許可は不要です。
GTFの起動方法は以下にサンプルを示します。USR=3FFの3FFは、EID=1023の16進数指定です。GTFに関してはマニュアルあるいはGTFトレースの採取とフォーマットを参照して下さい。