Macros are Easytrieve's compile-time reuse mechanism. Instead of typing the same FILE block, DEFINE fields, or REPORT skeleton in every program, you define the pattern once in a macro library and invoke it with a single percent line. The preprocessor expands the macro body into your source before the compiler sees the program—parameter values replace ampersand references in the model statements. A personnel master file might appear in dozens of batch reports; when HR adds a new column, one macro edit and recompile fixes every dependent program. Beginners often confuse macros with PROC modules or JCL procedures; macros never execute at runtime—they only generate source text. PROC handles runtime PERFORM logic. This section overview maps the macro learning path: syntax and prototype rules, positional and keyword arguments, how expansion appears in compiler listings, and governance for shared libraries in regulated mainframe shops. You will also see when macros beat COPY-style duplication and when PROC or inline code is the better choice.
Easytrieve compilation has a preprocessor phase before language analysis. When the scanner encounters %MACRONAME, it loads the macro definition from your instream source or from a site macro library, substitutes invocation parameters into the body, and inserts the resulting statements in place of the invocation line. The expanded source then flows through DEFINE validation, activity parsing, and code generation as if you had typed every line manually. That means a typo in a shared macro breaks compile for every caller until the library is corrected—powerful for consistency, dangerous without change control.
123456789101112131415* Before expansion — your program %PERSNL JOB INPUT PERSNL PRINT PAY-RPT * After expansion — preprocessor output (conceptual) 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 PRINT PAY-RPT
| Element | Purpose | Typical location |
|---|---|---|
| MACRO prototype | Opens definition, declares parameters | Macro library member or instream MSTART block |
| Macro body | Model statements with &PARAMETER substitution | Between MACRO and MEND |
| MEND | Terminates macro definition | End of macro source |
| % invocation | Requests expansion at compile time | Library section of invoking program |
| Tool | When to use | When it takes effect |
|---|---|---|
| MACRO / % | Identical or parameterized source patterns (FILE, DEFINE, REPORT lines) | Compile-time expansion |
| PROC / PERFORM | Executable logic reused within one activity at runtime | Runtime call and return |
| CALL external module | Logic shared across programs as compiled load module | Runtime LINK or equivalent |
| Manual copy-paste | One-off prototype never shared—avoid for production layouts | Immediate but unmaintainable |
Broadcom tutorials use PERSNL as the teaching file. A macro might encapsulate the FILE statement and field definitions so every filtered report program starts with %PERSNL instead of fifteen lines of offsets. When DEPT moves from column 98 to 100 in the physical record, analysts update the macro once; every program picking up the new library member gets correct offsets on compile. Without macros, teams grep through hundreds of sources and miss one program—producing silent wrong totals in production.
1234567MACRO FILE PERSNL FB(150 1800) EMPNAME 17 8 A EMP# 9 5 N DEPT 98 3 N GROSS 94 4 P 2 MEND
Production macros reside in libraries your data center catalogs—Panvalet, Endevor, or the Easytrieve macro facility. Compile JCL or IDE profiles point the preprocessor at those libraries. Developers prototyping new layouts may code macros instream between MSTART and MEND, test expansion locally, then promote the member to the shared library after review. Never leave production programs depending on instream-only macros that never reached the library; the next developer without your test block gets compile errors.
Invocations usually sit in the Library section alongside FILE and DEFINE—before JOB, REPORT, or SCREEN activities. Expanded content becomes part of the library the compiler binds to activities. Some macros generate REPORT TITLE and LINE templates inside the Report section when parameters supply report names. Match macro output to valid Easytrieve syntax for the target section; a macro that emits JOB statements into the library section is valid, one that emits REPORT lines mid-JOB is not.
If one program skips recompile after a macro change, it runs with old offsets baked into the load module. Mitigation: regression-compile representative programs after macro updates; track macro version in release notes.
Wrapping single-line statements in macros adds indirection without benefit. Reserve macros for blocks repeated at least three times or requiring parameterized variation.
Adding a required positional parameter without updating every invocation fails compile—good. Changing keyword defaults silently changes generated DEFINE sizes—document defaults in comments.
You studied FILE and DEFINE in the library section tutorials—macros package those statements. Compile process explains where expansion fits in the full build. Procedures overview covered PERFORM; remember macros are not procedures. Report section tutorials show LINE and TITLE targets macro bodies often generate. When you reach debugging, compiler listings reveal expanded macro text for troubleshooting.
Imagine building with LEGO. A macro is a pre-built wall piece your dad made once. When you need that wall, you snap the piece in—you do not rebuild every brick. %PERSNL is asking for the pre-built wall. PROC is calling your friend to help while you are already playing—that happens later during the game, not when you open the LEGO box.
1. Easytrieve macros run at:
2. Invoke a stored macro named PERSNL with:
3. Macros are best for:
4. PROC modules differ from macros because PROC:
5. Production macros typically live in: