Easytrieve Macro Reuse

Shared Library Architecture

Enterprise installations catalog macro libraries in compile JCL or IDE host profiles. Preprocessor search order may include application-private macros first, then department standard library, then site-wide layout library. Document search order so a duplicate macro name in two libraries does not surprise developers with wrong expansion.

Composable Macro Design

Instead of one MEGA-LAYOUT macro emitting FILE, fifty DEFINE fields, REPORT headers, and working storage, split responsibilities. Callers compose invocations in library section order matching valid Easytrieve structure.

1
2
3
4
5
6
%PERSNL-FILE
%PERSNL-WORK
%STD-PAGE-HDR PAY-RPT
 
JOB INPUT PERSNL
  PRINT PAY-RPT

• PERSNL-FILE — FILE and record fields from data dictionary.
• PERSNL-WORK — working storage DEFINE used across payroll programs.
• STD-PAGE-HDR — parameterized REPORT TITLE/LINE with report name argument.

Naming Conventions

Eight-character default limit forces abbreviations—publish a site dictionary mapping abbreviations to full file names.

Change-Control Workflow

1. Analyst requests layout change with data dictionary reference.
2. Developer edits macro member in test library; full expansion listing attached to ticket.
3. Regression-compile pilot programs from each invoking application family.
4. QA compares job output to baseline files for key reports.
5. Endevor promotion to production library with release note listing macro level.
6. Application teams schedule recompile of dependent programs in same or follow-on release.

Parameter Contract Documentation

Header comment block on each macro member should list positional order, keyword defaults, invoking example, owning team, and last data dictionary version. Future maintainers should not reverse-engineer invocation from body alone.

1
2
3
4
5
6
* MACRO: PERSNL-F  OWNER: HR-DATA  DICT: 2026-03
* POS: none  KEY: RECLEN default 150  BLKSIZE default 1800
* EXAMPLE: %PERSNL-F RECLEN=200
MACRO 0 RECLEN 150 BLKSIZE 1800
  ...
MEND

Reuse Patterns by Domain

Master file layouts

Single source for FILE offsets—highest reuse value. Pair with data dictionary automation where available.

Report cosmetics

TITLE and LINE macros enforce audit headers (date, page, department name) consistently across regulated reports.

SQL field bundles

Db2 table macros generate INCLUDE field sets for programs accessing same tables—reduce drift between online and batch Easytrieve SQL.

Site constants

Parameterized DEFINE VALUE blocks for application ID or company code in multi-tenant batch streams.

Anti-Patterns

• Instream-only macros in production programs—breaks when member copied without test block.
• Macro containing JOB logic tied to one program—belongs in source not shared library.
• Undocumented positional reorder breaking fifty callers silently until recompile.
• Over-parameterizing rarely changed values—adds invocation errors without maintenance win.
• Skipping regression because change looks small—one-byte offset shift corrupts totals.

Migration and Versioning Strategies

Breaking changes need explicit strategy. Parallel macro name (PERSNL2) lets teams migrate program-by-program. Big-bang migration updates all invocations in one release window with full regression suite. Never change production macro in place without caller inventory—grep source libraries for %MACRONAME before edit.

Inventory and Impact Analysis

Before any shared macro edit, run source search across PDS libraries for % invocations. Endevor impact analysis may list elements including macro references in compile control cards. Maintain spreadsheet of top invoking programs for quick regression subset.

Training New Developers

Onboarding should include: where macro libraries live, how to read expansion listings, parameter header comments, and who approves site-wide changes. Junior developers invoke macros first; senior owners edit library members after review.

Explain It Like I'm Five

Reuse is sharing one good recipe card in the school kitchen instead of every kid writing their own. If the recipe card gets a typo fix, every kid who uses the card gets the fix next time they cook—but only if they pick up the new card. The library is the recipe box; change control is the teacher approving recipe edits.

Exercises

1. Design three composable macros for a payroll report program.
2. Write a six-step change-control workflow for a DEPT offset change.
3. List programs you would include in regression after PERSNL macro edit.
4. Propose naming convention for your site with eight-character limit.
5. Describe parallel macro versioning versus big-bang migration tradeoffs.