Easytrieve Macro Sample Program: Parameters, % Invocation, and Report Example

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.

Macro code expands first.

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 516

The 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-PAY

The 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 516

Invoke 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 520

Keep 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 516

Common 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 & parameter 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.