Easytrieve MACRO Statement

MACRO Prototype Format

1
2
3
4
MACRO [positional-count] positional-parameters... keyword-parameters...
 
  * macro body statements with &PARAMETER substitution
MEND

MACRO must be the first word on the prototype line. Positional-count is required when you mix keyword parameters—it tells the preprocessor how many positional values to expect on invocation. When only keyword parameters appear, positional-count is zero.

Macro Structure

Cube Calculation Example

1
2
3
4
5
MACRO 2 NUMBER RESULT
  DEFINE CUBE_NUMBER_ S 6 N VALUE 000000
  CUBE_NUMBER_ = &NUMBER * &NUMBER * &NUMBER
  &RESULT = CUBE_NUMBER_
MEND

Broadcom Define Macros example declares two positional parameters NUMBER and RESULT. The body computes cube into working storage then assigns to the field name passed as RESULT. Invocation %CUBE 5 CUBE-OUT expands with NUMBER=5 and RESULT=CUBE-OUT.

Positional Versus Keyword Parameters

Positional parameters appear in fixed order on both prototype and invocation—frequently used values belong here because callers pass only values without names. Keyword parameters use name default-value pairs on the prototype; invocation supplies KEYWORD=value to override default. When both types exist, invocations must list all positional values before any keyword pair. Positional-count on MACRO documents how many positionals the invocation must supply.

1
2
3
4
5
MACRO 1 POS1 KEY1 VALUE1
  * body uses &POS1 and &KEY1
MEND
 
%MYMAC 100 KEY1=OVERRIDE

Percent Invocation

1
%PERSNL

A single line invokes macro PERSNL expanding stored FILE and DEFINE layout into the program. Classic tutorials place personnel file definitions in %PERSNL so every payroll program shares one maintained copy. Panvalet and Endevor libraries may allow macro names up to ten characters; default limit is eight.

Parameter Substitution Rules

Ampersand before parameter name in the body marks substitution points. The preprocessor replaces &NUMBER with invocation text before compile continues. Nested macros and quoting follow Macro Facility chapter rules—special characters in actual parameters may require continuation or escape per release. LIST NOMACROS on PARM suppresses macro expansion listing when listings grow large.

Stored Macros Versus Instream Testing

Production macros reside in libraries your data center maintains—changes propagate to all invoking programs on next compile. Developers testing new macro bodies may use MSTART and MEND bounds for instream definitions before promoting to the shared library. Version macro libraries with application releases; breaking a shared FILE macro breaks every dependent program at compile.

MACRO Versus PROC

Common Macro Use Cases

• Standard FILE and DEFINE blocks for enterprise master files.
• Repeated REPORT TITLE and LINE templates for audit layouts.
• Site-standard working storage counters and flags.
• SQL INCLUDE field bundles for Db2 tables accessed widely.
• Compile-time constants parameterized by application ID.

Governance and Change Control

Treat macro libraries as production source. Require code review for macro edits affecting field offsets—silent layout changes corrupt every invoking program. Document parameter contracts on the prototype comment block. Regression-compile representative programs after macro updates. Endevor or equivalent change packages should include macro elements alongside application sources.

Debugging Macro Expansion

Compile listings with macro expansion show generated statements—use when invocation parameters produce invalid DEFINE syntax. Compare expanded FILE against working program when offsets drift. NOMACROS listings hide expansion; enable full list when diagnosing parameter substitution errors.

Common MACRO Mistakes

• MACRO not first statement in definition.
• Missing positional-count when keyword parameters used.
• Keyword values before positional values on invocation.
• Expecting runtime PERFORM behavior from % invocation.
• Unversioned shared macro change without regression compile.
• Ampersand typo in body producing invalid field names.

Explain It Like I'm Five

A macro is a cookie cutter. You press it into dough once and get the same shape every time. MACRO draws the cutter shape with holes labeled NUMBER and RESULT. %CUBE is pressing the cutter—your numbers fill the holes and the full cookie appears in the program. PROC is a helper you call during baking; MACRO happens when you make the recipe card before baking starts.

Exercises

1. Write MACRO with two positional parameters and body assigning &RESULT = &INPUT.
2. Invoke with %MACRONAME value fieldname.
3. List three differences between MACRO and PROC.
4. Design FILE layout macro parameters for record length and DD name.
5. Document change-control steps when editing a shared PERSNL macro.