Easytrieve Macro Expansion

Expansion Pipeline Step by Step

1. Scanner reads invoking program source until it finds %MACRONAME.
2. Preprocessor resolves macro from instream MSTART block or cataloged library member.
3. Invocation tokens parse into positional and keyword actuals using positional-count.
4. Each model statement copies to output buffer with &PARAMETER replacements applied.
5. Expanded text replaces the invocation line (or inserts at correct section boundary).
6. Compiler parses combined source—library plus generated statements plus activities.

Before and After Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
* Source you maintain
%PERSNL
 
JOB INPUT PERSNL
  IF DEPT = 911
     PRINT PAY-RPT
  END-IF
 
* Conceptual post-expansion fragment
FILE PERSNL FB(150 1800)
  EMPNAME  17  8  A
  EMP#      9  5  N
  DEPT     98  3  N
  GROSS    94  4  P  2
 
JOB INPUT PERSNL
  IF DEPT = 911
     PRINT PAY-RPT
  END-IF

Compiler Listings and Macro Sections

Compile listings vary by installation, but macro-aware listings show which invocations expanded, sometimes repeating generated lines with sequence numbers for error correlation. When error messages cite statement 000045, scroll the listing to that line in the post-expansion view—often the bug is a substituted token producing invalid syntax, not your original JOB logic.

LIST NOMACROS

Large programs invoking many layout macros generate listings thousands of lines long. Production compile procedures often specify LIST NOMACROS on the compile PARM to archive slimmer output. Turn NOMACROS off when diagnosing parameter errors—without expansion text you only see the percent line and cryptic downstream syntax errors.

1
PARM='LIST NOMACROS'

Nested Macro Expansion

A macro body may contain %OTHERMAC invocations. Preprocessor typically expands inner macros first so outer & substitutions see resolved text or inner-generated lines depending on facility rules. Deep nesting increases compile cost; flatten occasionally by merging stable inner macros into outer bodies after review.

1
2
3
4
MACRO
%STD-HEADER
  LINE 01 DEPT EMPNAME
MEND

Diagnosing Substitution Errors

Invalid field name after expansion

Actual parameter included special character illegal in identifiers—listing shows DEFINE with bad name. Fix invocation quoting or macro body literal placement.

Wrong offset in FILE

Keyword default changed or wrong RECLEN passed—compare expansion listing to data dictionary. Not a runtime bug; regenerated source carries wrong numbers until recompile with corrected invocation or macro default.

Missing positional value

Preprocessor error before compile—positional-count expects three values, invocation supplied two. Error references macro invocation line in pre-expansion source.

Expansion Versus Runtime Behavior

Expanded code is fixed in the load module until next compile. Changing a macro library member does not affect already-linked programs. Operations teams must track which load modules were built against which macro library level—parallel to copybook level tracking in COBOL shops.

Performance and Size Considerations

• Many expansions increase compile CPU and listing storage.
• Identical % invocations in one program expand separately—duplicate generated text unless optimizer merges (do not rely on merge).
• Very large macro bodies approach copybook size limits—split into composable macros.
• NOMACROS reduces I/O archiving listings in mass nightly compiles.

Verification Checklist After Macro Library Change

1. Recompile pilot program with full macro listing enabled.
2. Verify FILE offsets against enterprise data dictionary PDF.
3. Confirm DEFINE names match activity references (JOB, REPORT).
4. Run regression test job comparing output to baseline.
5. Promote library member only after sign-off; document in release notes.

Relationship to Compile Process Tutorial

The compile process page places preprocessor expansion before syntactic and semantic analysis. Macro expansion errors surface in preprocessor or compiler phases depending on failure type. Debugging overview in the next section covers broader listing interpretation including non-macro errors.

Explain It Like I'm Five

Expansion is like a printer copying a stencil. You hold up the stencil (%MACRO), the printer sprays ink through the holes (arguments), and a full picture appears on the paper (your program). NOMACROS is telling the printer not to show the stencil outline in the instruction manual—fine when you trust the stencil, bad when the picture looks wrong and you need to see which hole was blocked.

Exercises

1. Sketch the six expansion pipeline steps from memory.
2. Explain when you would enable versus disable NOMACROS.
3. Describe how you would find a bad DEPT offset after macro change using listings.
4. Write a nested macro example and predict expansion order.
5. List three differences between expansion-time and runtime errors.