「イベント・ファイル」形式

「イベント・ファイル」には、エディターが、メッセージを送出する原因となるトークンまたは行をソース・ファイルで検出することができ、展開したソースを参照するメッセージを、指定したソース・ファイル内の対応する位置と関連付けることができる情報が含まれています。「イベント・ファイル」は、特定のクラスのツールに役立つ機械可読情報を提供するよう意図されています。一方、プロセッサーのリスト・ファイルは、人が読むよう意図されています。「イベント・ファイル」の形式がすべてのプロセッサーで共通しているため、ツールは、必要な情報を取得するためにプロセッサー特有のコードを書き込む必要がありません。

「イベント・ファイル」は順次作成されます。各プロセッサーは、新規レコードを「イベント・ファイル」に追加します。重要なイベントが発生すると、レコードが「イベント・ファイル」に書き込まれます。

現在、以下のレコード・タイプが定義されています。
  • タイム・スタンプ・レコード
  • プロセッサー・レコード
  • ファイル ID レコード
  • ファイル終了レコード
  • エラー情報レコード
  • プログラム・レコード
  • マップ定義レコード
  • マップ開始レコード
  • マップ終了レコード
  • フィードバック・コード・レコード

異なるタイプのレコードがこの 1 ファイルに組み込まれるため、各レコードの最初の語によってレコード・タイプが識別されます。構文図では、各トークンは確実に 1 ブランクで区切られていなければなりません。

タイム・スタンプ・レコード

このレコードは、「イベント・ファイル」がいつ作成されたかを示しています。これによりアプリケーションは、「イベント・ファイル」が最新かどうかを判別することができます (タイム・スタンプがファイル ID レコードに示されたファイルより古い場合には、「イベント・ファイル」はそのファイルに対しては正しくないファイルである可能性があります)。このレコードは、常に「イベント・ファイル」の最初のレコードです。

注: このレコードは、プロセッサーによって書き込まれるのではなく、最初のプロセッサーの呼び出し元によって書き込まれます。これにより各プロセッサーは、ファイルが存在するかどうかを判別せずに「イベント・ファイル」に付加することができます。

レコードは次のように定義されます。

**––– TIMESTAMP ––– version ––– timestamp ––––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
timestamp
「イベント・ファイル」が yyyymmddhhmmss 形式で作成された日時。

プロセッサー・レコード

このレコードは、新規プロセッサーが起動されていることを示します。1 つは常に「イベント・ファイル」内のタイム・スタンプ・レコードの後ろにあります (複数ある場合もあります)。

プロセッサー・レコードは次のように定義されます。

**––– PROCESSOR ––– version ––– output-id ––– line-class –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
output-id
このプロセッサーによって作成される出力ファイルのファイル ID。このプロセッサーの出力が、別のプロセッサーに対する入力として使用されるよう意図されている場合には、このファイル ID はそのファイルを表して、そのファイルのファイル ID レコードがこのレコードの後ろに付きます。これが、エディターがメッセージを表示するよう予期されて起動された最後のプロセッサーの場合には、ファイル ID は 0 です。
line-class
行に番号を付けるのに使用されるメソッド。展開したソース表記を含む一時ファイルまたは内部ファイルが使用されている場合には、0 を指定します。 行番号は、展開したソースの行番号を表しています。行番号が「ソース・ファイル ID」フィールドに示されたソース・ファイル内の物理的な行番号を表している場合には、1 を指定します。
注: あるプロセッサーの出力が別のプロセッサーの入力として意図されている場合には、その出力の FILEID レコードには、出力が実ファイルに出力されていない場合でも名前が含まれていなければなりません。これと同じ名前が、出力を使用したプロセッサーの入力 FILEID レコードで使用されます。

ファイル ID レコード

このレコードには、処理されるソース・ファイルのフルネームが含まれ、整数がファイル名と関連付けられます。 処理される各ソース・ファイル (組み込まれたソース・ユニット (copylib メンバー) とマクロ、およびメイン・ソース・ファイル) には、このタイプのレコードが 1 つなければなりません。

注: ファイルが処理中に何度か組み込まれる場合には、ファイル ID レコードが各組み込みで書き込まれなければなりません。

ファイル ID レコードは次のように定義されます。

**––– FILEID ––– version ––– source-id ––– line ––– length ––––*
 *––– filename ––– sourcefile timestamp ––– temp flag ––*|

ファイル ID がイベント・ファイルのレコード長に許可された長さを超えた場合 (IFS ファイルのコンパイル時に起こる可能性があります) は、ファイル ID レコードには、以下の形式の連続した 1 個以上のファイル ID レコードが後ろに付きます。

**––– FILEIDCONT ––– version ––– source-id ––– line ––– length ––––*
 *––– filename ––– sourcefile timestamp ––– temp flag ––*|

たとえば、以下のとおりです。

FILEID     0 001 000000 383 /home/USER/directory/directory2/directory3/directory4asdfjkaskldjfhakjsdf haslkdjf alksjdfh laksjdf/directory5/dir9 askdjfhaksdjfhkalsjdfhlkajsdfhlajdshflkajshdflkajshdflkjahsdflkjhasdlfkjhaslkdfhalksdjfhalksdhfklashdfkashdflkahsdflkjhasdlkfhalskdfjha
FILEIDCONT 0 001 000000 000 lskfhalskdfhalsdhfalksdjfhlaksfhlasasdkjfhaksdjfhlkasjdfhlkajshdflkajshdfkjashdflkjhasdlkfhsadjkfdfhlakdshflkhs/REM1C01501.RPGLE 20030404130518 0

上記の例で表示されているとおり、IFS ファイル名の間にはスペースが入っている場合があるので、長さは常にファイル名を判別するのに使用されます。

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
source-id
文字ベースのファイル名を使用せずに、エラー・レコードをそれが見つかったソース・ファイルと相関させるため、ファイル名の代わりに使用される整数として表示されるファイル ID。ユーザー出口からの入力など、入力ファイルが不明な場合には、0 を使用します。
line
新規ファイルに参照されるソース・ファイル行番号。あるいは、そのファイルがファイルから参照されなかった場合には、0。
length
ファイル名の長さ。最大長は 255 です。FILEIDCONT レコードでは、長さはファイル ID レコードによってのみ決定されるため、これはつねに 0 となります。
filename
名前は完全修飾の物理ファイル名でなければなりません。これが存在しない場合 (たとえば、ユーザーからテキストを取得中の場合)、あるいは名前が判別できない場合には、ここにはヌル・ストリングが入ります。

名前には servername を入れることができます。

sourcefile timestamp
これは、ソース・ファイルのタイム・スタンプです。
temp flag
このフィールドは、ソースが一時ファイルであることを示す場合は 1 に設定されます。その他の場合は、これは 0 に設定されます。一時ソース・ファイルは参照モードでのみ開くことができます。現在一時フラグは、SQL プリプロセッサーによって生成された出力を参照するのに使用されます。

ファイル終了レコード

このレコードは、組み込まれたファイルが終了中であることを示します。これは、組み込みファイルのネストを判別するメソッドを提供するので、プログラムは組み込みチェーンのバックアップをナビゲートすることができます。これは、組み込まれたファイルにエラーの原因を判別するのに充分な情報が含まれていない時に便利です。

ファイル終了レコードは次のように定義されます。

**––– FILEEND ––– version ––– file-id ––– expansion –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
file-id
このファイルのファイル ID。
expansion
このファイルで展開したソース行の番号。ネストされた組み込みおよびマクロ展開を含みます。
注: すべてのファイル ID レコードには、対応するファイル終了レコードがなければなりません (出力ファイルを定義するプロセッサー・レコードの後ろにあるファイル ID を除く)。

エラー情報レコード

このタイプのレコードには、メッセージ自身が表示されるのに十分な情報のほか、ソース・ファイルのメッセージが出力される原因となるトークンまたは行を検出するのに必要な情報が含まれています。 この情報には、位置情報 (エラーが起こったファイルと行など) およびエラー自身と関連した情報 (メッセージの番号、テキスト、および重大度) が含まれます。

エラー情報レコードは次のように定義されます。

**––– ERROR ––– version ––– file-id ––– annot-class –––*
 *––– stmt-line ––– start-err-line ––– token-start ––– end-err-line ––– token-end –––*
 *––– msg-id ––– sev-char ––– sev-num ––– length ––– msg –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
file-id
このエラーを含むソース・ファイルのファイル ID 番号。
annot-class
メッセージのリストで、「イベント・ファイル」が「エラー・リスト」ウィンドウでロードされる時にこのメッセージが入る場所を示します。この位置は、次のように定義されます。
0
リストの最上部。通常、ファイルの特定行とは実際には関連していない、たいへん重要なメッセージに使用されます。このタイプのメッセージの複数インスタンスのソート順は定義されません。テキストは通常このタイプのエラーと対応していないため、編集ウィンドウに入れることはできません。
1
リストの中間部。通常、単一行またはトークンと関連したメッセージに使用されます。このタイプの複数のメッセージは、行および桁番号によってソートされます。
2
リストの最下部。通常、ファイルの特定行とは実際には関連していないあまり重要ではないメッセージに使用されます。このタイプのメッセージの複数インスタンスのソート順は定義されません。テキストは通常このタイプのエラーと対応していないため、編集ウィンドウに入れることはできません。
stmt-line
エラーを含むステートメントの最初の行の (上記のソース・ファイル ID 番号と関連したソース・ファイルの) 行番号。エラーがステートメントの最初の行で発生していない場合は、これが必要です。この番号は、line class フィールドを使用して解釈されます。
start-err-line
エラーの開始を含む (上記のソース・ファイル ID 番号と関連したソース・ファイルの) 行番号。この番号は、line class フィールドを使用して解釈されます。
token-start
エラー状態のトークンの開始の桁 (または行の文字)。この情報が使用できない場合は、ここに記述された 0 により、行全体にエラーとしてフラグが立てられることになります。
end-err-line
エラーの終了を含む (上記のソース・ファイル ID 番号と関連したソース・ファイルの) 行番号。この番号は、line class フィールドを使用して解釈されます。
token-end
エラー状態のトークンの終了の桁 (または行の文字)。この情報が使用できない場合は、ここに記述された 0 により、行全体にエラーとしてフラグが立てられることになります。
msg-id
メッセージ ID (たとえば、AMPX999)。
sev-char
重大度コード文字 (IWES、あるいはT)。
sev-num
重大度レベル番号。一部のシステムでは、これは重大度コード文字と関連した戻りコード (たとえば、I=0W=4E=8S=12T=16) となります。
length
メッセージ・テキスト (次のフィールド) の実際の長さ。最大長は 1024 バイトです。
msg
エラー・メッセージのメッセージ・テキスト。フィールドの置換はすでに完了しているはずです。
注: エラー・レコードには file-id は 1 つしか指定できないため、複数のファイルに及ぶエラーには、適切にフラグが立てられない場合があります。

プログラム・レコード

このレコードは、同じソース・ファイルで新規プログラムがコンパイルされていることを示します。これは、複数のプログラムが 1 つのファイルに含まれているときに使用されます。このレコードが書き込まれる時に、展開したソース行は 1 からやり直しになるよう想定されています。ファイルの最初のプログラムを示す必要はありません。

注: プログラムのすべての ERROR レコードは、そのプログラムのPROGRAM レコードの後、および別のプログラムの PROGRAM レコードの前に来なければなりません。

プログラム・レコードは次のように定義されます。

**––– PROGRAM ––– version ––– line –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
line
このプログラムが開始されるファイルの位置。

マップ定義レコード

このレコードは、マクロが定義されていることを示します。これは、マクロが使用される場所の代わりに、エラーをマクロ定義に反映し直すようにするために使用されます。

マップ定義レコードは次のように定義されます。

**––– MAPDEFINE ––– version ––– macro-id ––– line ––– length ––– macro-name –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
macro-id
このマクロ定義を表す整数。これは、特定ファイル内で順次増分します。
line
マクロ定義が開始される現行ファイルの物理行。
length
マクロ名の長さ。
macro-name
定義されているマクロの名前。

マップ開始レコード

このレコードは、ソース拡張が開始されていることを示します。テキストの置換が行なわれている場所で使用されます。

マップ開始レコードは次のように定義されます。

**––– MAPSTART ––– version ––– macro-id ––– line –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
macro-id
マップ定義レコードに指定されたマクロの ID。
line
展開 (たとえば、マクロの起動) が開始される現行ファイルの物理行。

マップ終了レコード

このレコードは、ソース展開が完了していることを示します。これは、作成された行数を表示するためテキスト置換の終わりで使用されます。

マップ開始レコードは次のように定義されます。

**––– MAPEND ––– version ––– macro-id ––– line ––– expansion –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
macro-id
マップ定義レコードに指定されたマクロの ID。
line
展開 (たとえば、マクロの起動) が開始される現行ファイルの物理行。
expansion
ネストされた展開を含む、このマクロの展開後の行数。

フィードバック・コード・レコード

このレコードには、コンパイルが停止した時点での戻りコードおよび理由コードが含まれます。

フィードバック・コード・レコードは次のように定義されます。

**––– FEEDBACK ––– version ––– return-code ––– reason-code –––*|

version
上位互換性に使用されるこのレコードの改訂。現行バージョンは「1」です。
return-code
戻りコードがプロセッサーから戻されます。
reason-code
理由コードがプロセッサーから戻されます。