An Easytrieve report program often repeats the same control break, title, and line layout in more than one job. A macro lets you keep that repeated code in one place and pass values into it when the program is compiled. The sample below shows a small report macro that accepts a control field and builds a report around it.
What is an Easytrieve macro?
An Easytrieve macro is reusable source code. You define the macro once, usually in a shared macro library, and invoke it from a program with a percent sign. Broadcom notes that macros are invoked with %macroname, not with the Easytrieve CALL statement.
%CNTLRPT REGION 516The macro is expanded before the report runs. That is why a macro is useful for repeated source patterns, such as standard file layouts, common report sections, date handling, or site-approved control-break layouts.
Macro sample: control report
This sample macro is named CNTLRPT. It accepts a control field, a starting value, an optional range word, and a high value. The ampersand prefix marks values that Easytrieve substitutes from the macro invocation.
MACRO 2 CNTL-FLD VALUE RANGE ' ' HIGH-VALUE ' '
*
IF &CNTL-FLD = &VALUE &RANGE &HIGH-VALUE
PRINT RPT1
END-IF
*
REPORT RPT1
SEQUENCE &CNTL-FLD NAME
CONTROL &CNTL-FLD NEWPAGE
TITLE 1 'CONTROL REPORT BY &CNTL-FLD'
LINE 1 &CNTL-FLD NAME GROSS-PAY NET-PAYThe first two values are positional in this example. CNTL-FLD receives the field name, and VALUE receives the comparison value. RANGE and HIGH-VALUE have default blank values, so the same macro can support an exact match or a range check.
Invoke the macro for one value
The simplest invocation prints a report when REGION equals 516. The source stays short, and the repeated report code remains in the macro member.
%PAYLIB
JOB INPUT PAYFILE NAME REGPROG
%CNTLRPT REGION 516Invoke the macro for a range
If the macro supports a range, pass the range word and the high value. The expanded condition behaves like a normal Easytrieve condition after substitution.
%PAYLIB
JOB INPUT PAYFILE NAME REGPROG
%CNTLRPT REGION 516 RANGE THRU HIGH-VALUE 520Keep range examples easy to read. A future support analyst should be able to tell whether the report is selecting one region, a range of regions, or a list handled by a different macro.
Parameter substitution rules to remember
| Item | Rule | Example |
|---|---|---|
| Macro invocation | Use percent sign before the macro name. | %CNTLRPT REGION 516 |
| Parameter reference | Use ampersand before the parameter name inside the macro body. | &CNTL-FLD |
| Default value | Provide a default when a parameter can be omitted. | RANGE ' ' |
| Readable naming | Use names that show intent. | HIGH-VALUE |
Where the macro library is found
At many sites, Easytrieve macro members are stored in a PDS or managed source library. Broadcom notes that the DD name can be controlled by the MACDDN option, with PANDD commonly used as the default. If a job cannot find a macro, check the macro library DD before changing the source.
//PANDD DD DISP=SHR,DSN=PROD.EASYTRIEVE.MACLIB
//SYSIN DD *
%CNTLRPT REGION 516Common mistakes
Trying to CALL a macro
An Easytrieve macro is not invoked with CALL. Use %MACRONAME. The CALL statement is for invoking external programs, such as COBOL or assembler routines.
Putting ampersands in the wrong place
Use the ampersand before parameter names in the macro body. Broadcom also notes that a literal ampersand inside a macro may need special handling, so avoid clever parameter names and test expansion output when changing shared macros.
Changing a shared macro without impact review
One macro can be used by many jobs. Before editing a shared macro member, search for every program that invokes it and confirm the parameter order still matches.
Review checklist
- Confirm the macro member name and library DD, such as
PANDD. - Check whether the macro uses positional parameters, keyword parameters, or both.
- Confirm every
¶meter in the body is declared on the macro prototype. - Keep the invocation readable, especially when more than two values are passed.
- Compile a test job and review the expanded source or compiler messages.
- Search for other programs that invoke the same macro before changing it.
Related Mainframe Forum guides
For nearby Easytrieve topics, read Easytrieve Macros, Creating Easytrieve Macros, Easytrieve Library, Easytrieve Basic Reporting, Easytrieve Program Structure, and Easytrieve Report Calculation.
External references
Broadcom provides related support notes on how to invoke Easytrieve macros, ampersand references in macro definitions, and coding the PANDD macro library DD.
FAQ
How do you invoke an Easytrieve macro?
Invoke an Easytrieve macro with a percent sign followed by the macro name, such as %CNTLRPT REGION 516.
What does the ampersand mean in an Easytrieve macro?
The ampersand marks a parameter substitution reference inside the macro body, such as &CNTL-FLD.
Is an Easytrieve macro the same as CALL?
No. A macro expands source code before execution. CALL invokes an external program.
What should I check when Easytrieve cannot find a macro?
Check the macro name, macro library DD, MACDDN option, and whether the JCL points to the correct macro library.
