Easytrieve Modular Design

Why Modularity Beats Monoliths

Monolithic Easytrieve programs duplicate FILE blocks, embed fifty-line IF ladders, and mix report layouts with one-off business rules. They compile and run until the day a field moves—and then every duplicate drifts differently. Modular programs treat FILE definitions as imports, logic as services, and main members as orchestration. Testing narrows to the changed module plus integration jobs. Onboarding improves: new developers learn PAYROLL-FILE-MAC once, then read thin JOB logic. Migration grep scans find reserved word collisions in macros first, clearing hundreds of programs in one fix.

FILE Macro Modules

A FILE macro encapsulates FILE statement, field lines, and related DEFINE defaults for a physical dataset. Application source begins Library with %INCLUDE PAYROLL-FILE-MAC or MACRO expansion from SYSLIB DD. Macro header documents copybook equivalence, version, and effective date. Version suffix macros (-V2) support parallel migration when old and new layouts coexist during cutover week.

1
2
3
4
5
6
7
8
9
* PAYROLL-FILE-MAC — layout version 2026-01
FILE PAYROLL FB(150 1800)
  EMPNAME  17  8  A
  EMP-NBR   9  5  N
  DEPT     98  3  N
  PAY-GROSS 94  4  P  2
 
* Application program:
%INCLUDE PAYROLL-FILE-MAC

REPORT Template Macros

Standard report shells—headers, column titles, footing— belong in macros when multiple jobs share corporate branding. Parameterize report name and title text if needed. Avoid over-parameterizing: a macro with twenty arguments is harder to use than a small family of named report macros (PAY-HDR-MAC, GL-HDR-MAC). REPORT macros pair with FILE macros so column fields exist in scope after expansion.

PROC Libraries and PERFORM

PROC blocks encapsulate runtime logic: VALIDATE-DEPT, ACCUM-TOTALS, FORMAT-DATE-FOR-RPT. Store common PROCs in members expanded or included into Library, then PERFORM from JOB or SCREEN activities. Document preconditions in comments—which FILE fields must be populated, which WS- totals RESET clears. Online and batch can share validation PROC if field names align via shared DEFINE macros.

Macro Parameters

Macro arguments let one template emit FILE PAYROLL versus FILE BONUS by passing name and DD label. Follow macro-syntax page rules for argument lists and defaults. Parameterize only what varies—keep field positions in one macro per physical layout, not one mega-macro with hundreds of positional parameters. Test expansion listings after macro changes to verify generated FILE statements match JCL DD expectations.

Library and Activity Separation

Structural modularity splits declaration from execution. Library aggregates includes: FILE macros, DEFINE groups, REPORT layouts, shared PROC declarations if your convention places them in Library. Activity contains JOB and SCREEN blocks that PERFORM procedures and PRINT reports. Crossing the boundary arbitrarily—FILE definitions mid-JOB—breaks readability and macro expansion order. Standards document whether PROCs live entirely in Library or may appear before first JOB only.

Nesting and Composition

PROC A may PERFORM PROC B; macros may include other macros for layered layouts (BASE-FILE-MAC plus EXTENSION-FIELDS-MAC). Limit depth: if understanding flow requires a stack diagram, split into clearer modules. Nested PROCs suit control-break templates—BEFORE-LINE PERFORMs FORMAT-DETAIL which PERFORMs MASK-AMOUNT—when each layer has one job. Design patterns section shows full frameworks built from these layers.

Thin Application Programs

Target application members under two hundred lines: include macros, define job-specific filters, PERFORM shared logic, PRINT reports. Complex business rules move to named PROC or external CALL. Thin programs ease code review and scheduling—operations see clear input-output mapping in header comments. When a program grows, split by report or by input file into separate schedulable jobs linked by GDG or workflow scheduler dependencies.

1
2
3
4
5
6
7
8
9
10
%INCLUDE PAYROLL-FILE-MAC
%INCLUDE PAY-REPORT-MAC
%INCLUDE PAY-VALIDATION-PROCS
 
JOB INPUT PAYROLL
  PERFORM VALIDATE-PAY
  IF FLG-VALID EQ 'Y'
     PERFORM ACCUM-TOTALS
     PRINT PAY-RPT
  END-IF

Shared Library Governance

Assign macro library owners in data governance forum. Promotion requires impact list: all members expanding macro X. Automate compile-all against macro library after each macro change in test LPAR. Version control macros in Git or SCLM like application source—never only in personal datasets. STEPLIB/SYSLIB DD order in compile JCL must resolve production macro libraries, not ad hoc test copies.

Testing Modular Changes

1. Expand macro in listing; verify FILE positions and names.
2. Compile pilot programs representing each macro consumer pattern.
3. Execute integration jobs with frozen test data.
4. Compare output to baseline when layout or calculation PROC changed.
5. Promote macro and dependent load modules in coordinated change window.

Modular Design Anti-Patterns

• Copy-paste FILE block with one field renamed—use macro instead.
• Macro that generates entire JOB hiding all logic from reviewer.
• PROC with hidden side effects on global WS- fields without documentation.
• Circular PERFORM between PROCs without exit conditions.
• Multiple macro library versions on different LPARs without sync.

Explain It Like I'm Five

Modular design is using the same LEGO instruction booklet for every castle that needs red walls, instead of rebuilding wall instructions from scratch each time. If the wall piece changes, you update the booklet once and everyone builds the new wall correctly. PROCs are helpers everyone calls; macros are prefabricated wall sections the compiler snaps in before the castle runs.

Exercises

1. Sketch macro library structure for PAYROLL, GL, and HR files.
2. Split a monolithic IF ladder into VALIDATE and CALC PROCs on paper.
3. Write macro header fields required before promotion.
4. List programs to recompile when PAYROLL-FILE-MAC changes.
5. Decide macro versus PROC for a shared date-formatting routine—justify.