Easytrieve Compiler Listings

What the Compile Listing Contains

Broadcom describes the compile listing as documentation of your program at compile time. At minimum you receive a header on each page, a numbered statement listing, diagnostics inserted near offending lines, and a compile summary. Depending on PARM DEBUG options and site defaults, you may also receive a cross-reference table, a program map, a data map, macro expansion detail, and file statistics at activity boundaries. Treat the listing as a bundle of related reports rather than a single narrative—you flip to the section that answers your current question.

Controlling Listing Content with PARM

The PARM statement, when present, must be the first statement in the program. It overrides site option defaults for that compile. DEBUG subparameters request optional diagnostic sections; LIST subparameters control FILE statistics and compile summary printing; ABEXIT controls abnormal termination handling at execution time but is often set during development compiles together with DEBUG. Broadcom's best-practices topic suggests a development-oriented combination such as DEBUG(PMAP DMAP STATE XREF LONG) with LIST FILE—your installation may publish a different standard, so compare against your options table.

1
2
3
4
5
6
7
8
9
PARM DEBUG(PMAP DMAP STATE XREF LONG) ABEXIT(SNAP) LIST FILE
FILE MASTER FB(80 800)
%MASTER
JOB INPUT MASTER NAME PAYLIST
  IF EOF MASTER
     STOP
  END-IF
  PRINT REPORT1
*

DEBUG PMAP produces a listing of executable program structure. DEBUG DMAP produces the data map—often the first place beginners look when numeric output shows garbage characters. DEBUG XREF with LONG expands cross-reference detail. DEBUG STATE adds information used when analyzing execution state after abnormal termination. DEBUG FLOW (documented separately under runtime tracing) maintains a rolling statement table at execute time; it may appear on PARM alongside listing options during integrated test compiles.

Listing Control Statements: LIST, NEWPAGE, SKIP

Beyond PARM, listing control statements format the physical listing. LIST ON prints subsequent source; LIST OFF suppresses it. LIST MACROS versus LIST NOMACROS controls whether macro library text appears inline. NEWPAGE forces the next source line to the top of a new page. SKIP n leaves blank lines for readability. PUSH saves current LIST settings; POP restores them—useful when you want macros hidden in one region but visible in another. These statements do not affect program logic and do not appear in runtime output; they only change the compile listing layout.

1
2
3
4
5
6
LIST ON MACROS
FILE EMPLOYEE FB(120 2400)
%EMPLOYEE
LIST OFF
JOB INPUT EMPLOYEE
  PRINT REPORT1

Reading Diagnostics in the Statement Listing

Errors and warnings are interleaved with your source. A dollar sign identifies a critical error; a plus sign begins a warning. The diagnostic usually points at the token most likely responsible— for example an invalid FILE subparameter or an undefined field in an IF condition. Fix critical errors before attempting execution; warnings may compile but indicate risky constructs such as implicit conversions or deprecated parameters. When multiple errors appear, start at the first critical error because later messages are sometimes cascaded noise from the same root mistake.

Common beginner compile errors visible on the listing

• Misspelled field names referenced before DEFINE in Library.
• FILE statement missing required organization for indexed access.
• PROC / END-PROC mismatch inside JOB or REPORT activities.
• Invalid REPORT mask or LINE syntax in Report section.
• Reserved word used as a field name without release migration review.

Using the DMAP (Data Map)

The data map lists every file and field with storage attributes: position within the record, length, data type, decimal places, and whether the field is file-linked or working storage. When your program reads a zoned decimal amount but DEFINE declared packed decimal, the DMAP shows the mismatch immediately. When two developers disagree about whether DEPT starts in column 98 or 99, the DMAP settles the argument without re-counting columns by hand. Cross-check DMAP output against your FILE copybook or layout document; if they differ, fix source before blaming the data.

How DMAP differs from your source FILE block

Your FILE statement describes logical organization and record format. DEFINE and FIELD statements within the file macro describe individual columns. The DMAP merges those definitions into a single offset table the runtime uses. Virtual fields and derived fields also appear with their computed lengths. If a field is missing from DMAP, the compiler did not recognize the definition—look for a typo in the macro name or a DEFINE outside the correct file scope.

Using the XREF (Cross-Reference)

The cross-reference section lists each symbol with line numbers where it is defined and where it is referenced. This is invaluable when refactoring large programs: you can see whether SALARY-TOTAL is referenced only in one REPORT procedure or scattered across three JOB activities. XREF LONG increases detail at the cost of listing volume. For maintenance programmers arriving mid-project, XREF is often faster than ISPF search because it reflects the compiled view including macro-expanded names.

The Compile Summary

The summary at the end counts errors and warnings, repeats compiler and execution options in effect, lists macro libraries searched, and reports generated code size. Always verify that the options shown match what you intended—especially DEBUG and ABEXIT flags before handing a load module to production scheduling. If you requested LIST FILE, file statistics for each activity may also print at activity boundaries when execution occurs in the same step as compile-and-go; batch shops that separate compile and execute still rely on the summary from the compile step alone.

Workflow: Listing-First Debugging

1. Compile with development PARM options approved by your site.
2. Resolve all critical ($) diagnostics; review warnings (+).
3. Scan DMAP for field positions against test file layout.
4. Execute with controlled test data; keep listing and load module together.
5. When SYSPRINT cites a statement number, open the listing to that line.
6. Escalate to tracing or dump analysis if logic error persists with clean compile.

Compile Listing Versus Runtime Output

Beginners sometimes confuse the compile listing with SYSPRINT runtime output. The listing is produced at compile time and describes static structure. SYSPRINT at execute time carries runtime messages, DISPLAY traces, file statistics (when enabled), and Error Analysis reports. Both documents may reference statement numbers, but only the listing shows DMAP and XREF. Store listings in the same change ticket as source updates so auditors can reproduce the compile environment months later.

Production Versus Development Listings

Verbose DEBUG options add compile time and listing bulk. Production compile procs often use LIST OFF, reduced DEBUG, and ABEXIT NO per Broadcom guidance to limit overhead. Development compiles favor full maps. Never assume production listings look like your personal test listing—compare PARM lines explicitly when a production abend arrives and the operations team sends a minimal listing bundle.

Explain It Like I'm Five

The compiler listing is like the answer key your teacher prints when you hand in homework. It shows every line you wrote with numbers down the side, circles the spelling mistakes, and includes a chart that says where each piece of information sits on your worksheet. When something breaks during the test run, you use those same numbers to find the line that caused trouble. Without the listing you are guessing; with it you can point to the exact sentence.

Exercises

1. Compile a program with an intentional typo in a field name; locate the $ diagnostic.
2. Request DEBUG DMAP and verify one numeric field offset against your FILE diagram.
3. Add LIST OFF after FILE definitions and confirm which sections still appear.
4. Generate XREF and list every reference to a working-storage counter field.
5. Compare compile summary options against your site options table defaults.
6. Pair a runtime statement number from SYSPRINT with the matching listing line.