Locating compiler listings or side files

Z Abend Investigator chooses a matching compiler listing or side file from the first of the following possible sources:

  1. TEST option data:
    • If the program was compiled with the TEST option, other than TEST(SEPARATE) for COBOL or Enterprise PL/I, a temporary Z Abend Investigator side file is generated from debug information contained in the load module.
    • If a COBOL V4 or Enterprise PL/I program, that was compiled with TEST(SEPARATE), the associated SYSDEBUG side file data set name is obtained from debug information that was created by the compiler and placed in the load module.

      See TEST option considerations for recommended language-dependent suboptions.

    • If a COBOL V4 program compiled with TEST(SEPARATE), the SYSDEBUG side file data set name is used as input to the optional COBOL IGZIUXB exit. This exit might return a different side file data set name.
    • If a COBOL V6 program compiled with TEST(SEPARATE), the SYSDEBUG side file data set name is obtained from the HFZSYSDB concatenation, the Compiler Listing Read user exit, COBOL IGZIUXB exit, or EQAUEDAT.
      Note: Under CICS®, the batch form of EQAUEDAT is used as Z Abend Investigator runs in an attached TCB without CICS command access.
  2. The z/OS® Debugger EQAUEDAT exit (optional).

    Refer to IBM® z/OS Debugger Customization Guide for details about the EQAUEDAT exit.

    If a COBOL or Enterprise PL/I program compiled with TEST(SEPARATE), then the SYSDEBUG side file data set name from the load module is used as input to the EQAUEDAT exit.

    No input side file name is provided when searching for HFZLANGX or compiler listings.

    This exit might return a different side file data set name.

    Note: Under CICS, the batch form of EQAUEDAT is used as Z Abend Investigator runs in an attached TCB without CICS command access.
  3. If a COBOL or Enterprise PL/I program, then any SYSDEBUG data sets provided via the HFZSYSDB DDname are searched. For XL C/C++ programs, MDBG data sets provided via the HFZSYSDB DDname are searched. The data sets are searched individually, that is, they are not treated as a logical concatenation.
  4. Z Abend Investigator side files:
    1. Compiler Listing Read user exit called with request for Z Abend Investigator side file.
    2. Z Abend Investigator side file data sets provided via the HFZLANGX DDname are searched. The data sets are searched individually, that is, they are not treated as a logical concatenation.
  5. Compiler listings:
    1. Compiler Listing Read user exit called with request for compiler listing (or an Assembler SYSADATA file).
    2. Language-specific compiler listing data sets provided via the appropriate DDname are searched (for example, HFZLCOB). The data sets are searched individually, that is, they are not treated as a logical concatenation.
The determination of whether a compiler listing or side file is satisfactory for use by Z Abend Investigator to map a program depends on a number of things:
  • If the NOTEST compiler option is used
    When Z Abend Investigator finds a compiler listing or LANGX side file for a program, a number of tests are performed, subject to the programming language used, to verify that the file matches the load module:
    • All languages

      From the Assembler listing section of any compiler output, Z Abend Investigator extracts the last few assembler instructions and compares them against the load module, and these assembler instructions must be at the correct offset in the load module according to the listing. If any of these instructions are not found at the correct offset in the load module, then this check fails, and the compiler listing or side file is not used to provide source-level information.

    • COBOL-specific tests (excluding OS/VS COBOL)
      For COBOL, four more length values are extracted from the listing. These are the TGT length, WORKING-STORAGE length, number of Data Division statements, and number of Procedure Division statements from the following four lines found in the compiler listing:
      TGT      WILL BE ALLOCATED FOR nnnnnnnn BYTES
      WRK-STOR WILL BE ALLOCATED FOR nnnnnnnn BYTES
      Data Division statements = nnnnnn
      Procedure Division statements = nnnnnn
      These four values are compared to those found in the load module, and if either do not match, then the compiler listing or side file is not used to provide source-level information.
  • If the TEST compiler option is used

    For COBOL SYSDEBUG files, the date and time comparisons are replaced with a 'signature' check, allowing an unchanged program to be recompiled. The SYSDEBUG file can still be used during interactive reanalysis if the signature check fails by following the compiler listing mismatch pop-up displays.

    For COBOL programs, up to and including Enterprise COBOL V4, but excluding VS COBOL II, the compiler listing data set name is obtained from debug information in the load module, placed there by the compiler. In this case, the date and time in the listing are checked against the compile date and time in the load module. If the compiler listing file has been moved (or it is VS COBOL II), then a compiler listing can be specified by way of the HFZLCOB DD, EQAUEDAT or the Compiler Listing Read user exit.

    For Enterprise COBOL V5 programs (or later) compiled with TEST(NOSOURCE) or NOTEST(DWARF), no source information is included in the program object and no compiler listing data set name is available in the DWARF. However, compiler listings for these programs can be specified by way of the HFZLCOB DD, EQAUEDAT or the Compiler Listing Read user exit.

    For Enterprise PL/I SYSDEBUG files, the date and time comparisons are replaced with a set of 'integrity' checks, which determine whether the SYSDEBUG file can be used with the load module in storage. If any of the integrity checks fail, then the SYSDEBUG file cannot be used.

The reason why Z Abend Investigator performs these checks before using the data is that an incorrect compiler listing or side file might produce very misleading report information.

If no satisfactory compiler listing or side file was found for a COBOL, PL/I, C/C++, or assembler program during interactive fault reanalysis, Z Abend Investigator prompts the user to optionally supply the location of a compiler listing, Z Abend Investigator side file, or COBOL SYSDEBUG side file. For more details on this prompt, see Prompting for compiler listing or side file.