コンパイラー・リスト読み取りユーザー出口

コンパイラー・リスト読み取りユーザー出口について、以下で説明します。

目的

この出口は、通常の IDI データ・セット (IDILANGXIDILCOBIDILPLI など) にメンバーとして保管されているコンパイラー・リストまたは Fault Analyzer サイド・ファイル以外のソースからソース・コード情報を取得する場合に使用できます。例えば、圧縮フォーマットで保管されているか、または所有者独自のアクセス方式でのみ アクセス可能なコンパイラー・リストなどです。

Fault Analyzer がソース・コード情報を要求する場合、常に、コンパイラー・リストまたはサイド・ファイルの検索に示すステップが実行されます。Compiler Listing Readユーザー出口の呼び出しは、すべての指定された使用可能な出口の 呼び出しを暗黙指定します。すなわち、最初にすべての出口がサイド・ファイルを準備するために呼び出され、 必要な場合は、その後でコンパイラー・リストを準備するために、すべての出口が呼び出されます。出口から最後に提供されたサイド・ファイルまたはコンパイラー・リストのみが使用されます。

Fault Analyzer は必須ソース・コード情報について、以下の情報を Compiler Listing Read ユーザー出口に提供します。
  • ロード・モジュール名。この名前は LST.MODULE_NAME データ域フィールドに示されます。LST データ域の参照については、パラメーターを参照してください。
  • LST.LOAD_MODULE_DSN データ域フィールド内のロード・モジュール・データ・セット名。
  • CSECT 名。この名前は LST.CSECT_NAME データ域フィールドに示されます。
  • エントリー・ポイント名。この名前は LST.EP_NAME データ域フィールドに示され、最大 256 文字で切り捨てられます。切り捨てられる場合、エントリー・ポイント名の最初の 254 文字の後に、波形記号 (~) および切り捨てられていないエントリー・ポイント名の最後の文字が付けられます。
  • コンパイル・データ。この日付は LST.COMPILE_DATE データ域フィールドに YYYY/MM/DD 形式で示されます。
  • コンパイル時間。この時間は LST.COMPILE_TIME データ域フィールドに HH:MM:SS 形式で示されます。
  • リスト・タイプ。このタイプは LST.LISTING_TYPE データ域フィールドに以下のいずれかで示されます。
    L
    コンパイラー・リスト またはアセンブラー SYSADATA ファイル
    S
    Fault Analyzer サイド・ファイル

    Fault Analyzer に渡されるソース・コード情報は、このフィールドに指定されたタイプである必要があります。

  • 言語タイプ。このタイプは LST.LANGUAGE_TYPE データ域フィールドに以下のいずれかで示されます。
    • アセンブラー
    • C/C++
    • COBOL
    • OS/VS COBOL
    • PL/I
  • 出口により提供されるリストまたはサイド・ファイルの予期されるレコード・フォーマット。このフォーマットは LST.RECFM データ域フィールドに V、VB、VBA、F、FB、FBA などとして示されます。
  • 出口により提供されるリストまたはサイド・ファイルの予期される論理レコード長。この長さは、LST.LRECL データ域フィールドに 10 進数文字フォーマットで示されます。
上記の情報に基づいて、ユーザー出口は要求されたリストまたはサイド・ファイルを提供できます。このプロビジョンは、以下のいずれかの方法で行われます。
  • LST データ域を介して 1 回に 1 つのレコードを Fault Analyzer に渡す。
    • リスト・レコードを含む変数の名前が REXX EXEC の IDIWRITE コマンドで渡されない限り、リストまたはサイド・ファイル・データ・レコードを DATA_BUFFER フィールドに指定する必要があります。
    • 可変長レコードの場合、DATA_BUFFER のレコードの長さを DATA_LENGTH フィールドに 10 進文字フォーマットで指定する必要があります。この長さは、可変長レコード記述子語を含まず、LRECL フィールドの値から 4 バイトを 引いたものより小さいか等しくなければなりません。
    • 固定長レコードの場合、DATA_BUFFER のレコードの長さが LRECL フィールドと一致することが予期されます。「DATA_LENGTH」フィールドで指定された値は無視されます。
    または
  • 順次データ・セットまたは PDS あるいは PDSE の名前をメンバー指定とともに「DATA_BUFFER」フィールドに指定し、DATA_BUFFER_DSN を「Y」に設定する。データ・セット名は、大文字で、「DATA_BUFFER」フィールドへのオフセット・ゼロから開始し、完全修飾名でなければならず、引用符で囲むことはできません。有効なデータ・セット名の例は、次のとおりです。
    MY.SEQ.DS
    MY.PDS.DS(MBR)

    データ・セット名の後に、ブランク以外の文字を指定しないでください (ユーザー出口が呼び出される前に、DATA_BUFFER フィールドはブランクに初期化されます)。

データ・セット名を指定しないで、代わりに個々のデータ・レコードを返す場合、LST データ域をデータ・レコード情報で更新した後、出口タイプに応じて Fault Analyzer にデータを渡すために 2 つの異なる方法を使用できます。
REXX
Fault Analyzer 環境 IDIWRITE コマンドが使用されます。このコマンドを使用するには、REXX ステートメントを次のようにコーディングしてください。
ADDRESS FAULTA 'IDIWRITE [var-name]'

IDIWRITE コマンドの正常終了は、ゼロの戻りコードで示されます。

IDIWRITE コマンドの詳細情報については、IDIWRITE コマンドを参照してください。

ロード・モジュール
書き込みルーチンのアドレスは、ENV.WRITE_ROUTINE_EP データ域フィールドに 16 進数 31 ビット・アドレスで示されます。

このルーチンは、ENV データ域のアドレスを含むフルワードをポイントする R1 で 呼び出す必要があります。例えば、さまざまなプログラム言語で作成された以下のユーザー出口の コードを使用して、書き込みルーチンを呼び出すことができます。

アセンブラー:
ASMEXIT  CSECT
         …
         L     R2,0(,R1)
         USING ENV,R2
         L     R3,4(,R1)
         USING LST,R3
         …
         L     R15,ENV_WRITE_ROUTINE_EP
         LA    R1,ENV_VERSION
         ST    R1,*+8
         BAL   R1,*+8
         DC    F'0'
         BALR  R14,R15
         …
         COPY  IDISXPLA
         …
C:
#include "SAMPLES(IDISXPLC)"
typedef void WRTN(ENV *pENV);
#pragma linkage(WRTN,OS)
int cexit(ENV *pENV, LST *pLST) {
  …
  WRTN *write_rtn;
  write_rtn = (WRTN *)pENV->WRITE_ROUTINE_EP;
  write_rtn(pENV);
  …
}
COBOL:
       …
       PROGRAM-ID. COBEXIT
       …
       LINKAGE SECTION.
           COPY IDISXPLB IN LIB.
       PROCEDURE DIVISION USING ENV, LST.
       MAIN SECTION.
             …
             CALL WRITE-ROUTINE-EP USING ENV.
             …
       END PROGRAM COBEXIT.
PL/I:
 PLIEXIT: PROC (ENVPTR,LSTPTR)  OPTIONS(BYVALUE,FETCHABLE) ;
 Dcl (Envptr,Lstptr)     Pointer ;
 %include syslib(IDISXPLP) ;
 Dcl IDIWRITE         Entry Variable Options(Asm Byaddr) ;
   …
   Entryaddr(IDIWRITE) = Envptr->Write_Routine_EP ;
   Call IDIWRITE (Envptr->Env) ;
   …
 End PLIEXIT ;

書き込みルーチンからの戻りコードは、RC=8 (構文エラー) が戻されないことを除いて、IDIWRITE REXX コマンドからの戻りコードと同じです。IDIWRITE コマンドを参照してください。

ユーザー出口により提供されているリストまたはサイド・ファイルの使用をキャンセルするために使用できるインディケーターは、LST データ域フィールド DISREGARD_EXIT_LISTING に示されます。このフィールドが「Y」に設定されている場合、ユーザー出口から Fault Analyzer に渡された可能性のあるデータ・レコードが廃棄されます。このインディケーターによって、ユーザー出口は、データ・レコードの提供中にエラーが発生した場合に Fault Analyzer による部分リストの使用を防ぐことができます。

呼び出されるタイミング

この出口は、任意の Fault Analyzer 実行モードでソース・コード情報が 要求される場合は常に呼び出されます。

パラメーター

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

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

REXX

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

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

ロード・モジュール

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

以下は、REXX で書かれたCompiler Listing Readユーザー出口の例です。区分データ・セット myid.LISTING.TERSE には、IBM® AMATERSE ユーティリティーによって作成された圧縮コンパイラー・リストが含まれます。

Fault Analyzer がコンパイラー・リスト・ファイルを要求するときに、この出口は myid.LISTING.TERSE PDS を検索して、モジュール名と一致するメンバー名を探します。一致するメンバーが検出されると、出口はそのメンバーを作業データ・セットに解凍し、IDIWRITE コマンドを使用して Fault Analyzer に渡します。
1. REXX コンパイラー・リスト読み取りユーザー出口の例
/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if LST.VERSION <> 1 then
  say 'Note: LST data area version change - field usage review required!'
if LST.LISTING_TYPE = 'L' then do
  modnm = strip(LST.MODULE_NAME)
  "IDIALLOC DD(INFILE) DSN(myid.LISTING.TERSE("||modnm||")) SHR"
  if rc = 0 then do
    recfm = strip(LST.RECFM)
    lrecl = strip(LST.LRECL,L,0)
    "IDIALLOC DD(OUTFILE) DSN(myid.TEMP) NEW CATALOG SPACE(1,1) ",
             "RECFM("||recfm||") LRECL("||lrecl||") UNIT(SYSALLDA)"
    address linkmvs "amaterse unpack"
    address mvs "execio * diskr outfile (finis"
    do while queued() <> 0
      parse pull rec
      LST.DATA_LENGTH = length(rec)
      LST.DATA_BUFFER = rec
      "IDIWRITE"
    end
    "IDIFREE DD(INFILE,OUTFILE)"
  end
end
exit 0
前述のサンプル出口がデータ・セット X.Y.Z のメンバー ABC として存在する場合、IDICNFxx 構成メンバーまたは IDIOPTS ユーザー・オプション・ファイルのいずれかで次のオプションを使用すると、このサンプル出口が呼び出されます。
DataSets(IDIEXEC(X.Y.Z))
Exits(LISTING(REXX(ABC)))