Easytrieve Macros: MACRO Parameters and % Invocation

An Easytrieve shop can have fifty reports that define the same customer layout, title lines, and total fields. A macro keeps that repeated source in one member and expands it into each program at compile time. That makes the report code shorter, but it also means a shared macro must be tested like shared production code.

Macro expands first.

What is an Easytrieve macro?

An Easytrieve macro is reusable source text. It can define file fields, report headings, common calculations, selection rules, or repeated report code. The macro is expanded before the Easytrieve program runs, so it is not the same as a runtime CALL.

Broadcom notes that Easytrieve macros are invoked with a percent sign, such as %MACRONAME. A CALL statement is used for COBOL or assembler subprograms, not for invoking Easytrieve macros.

Macro, copybook, and CALL at a glance

Item	When it is used	Typical purpose
Easytrieve macro	Compile time	Expands reusable Easytrieve source with optional parameters.
Copy/include member	Compile time	Brings in shared source text without macro substitution logic.
CALL	Run time	Runs a COBOL, assembler, or other external subprogram.

Basic macro structure

A macro usually starts with a prototype statement. The body contains the source lines that will be expanded. Parameter names in the body use an ampersand prefix. The exact coding style can vary by site and product release, but the idea is the same: pass values into reusable source text.

MACRO FNAME PREFIX
FILE &FNAME
&PREFIX-ID      1  8  N
&PREFIX-NAME    9 20  A
&PREFIX-AMT    29  7  P 2

When the macro is invoked, Easytrieve substitutes the values from the invocation line into the macro body.

%CUSTLAY CUSTIN CUST

After expansion, the generated source acts as if the field definitions had been typed directly into the program.

How ampersand substitution works

Within the body of a macro, an ampersand marks a parameter substitution word. Broadcom notes that parameter substitution words must match their prototype names, except for the leading ampersand. If the prototype has PREFIX, the macro body uses &PREFIX.

This is where many small compile errors start. A misspelled parameter name, a missing delimiter, or an ampersand placed in the wrong part of the macro can make the expanded source invalid.

How to invoke a macro

Invoke a macro with the percent sign followed by the macro name. Broadcom is explicit on this point: macros use %macroname, while CALL is for subprograms.

FILE CUSTOMER-FILE FB(80 0)
%CUSTLAY CUSTOMER-FILE CUST

JOB INPUT CUSTOMER-FILE
  IF CUST-AMT > 0
     DISPLAY CUST-ID CUST-NAME CUST-AMT
  END-IF

The macro expansion happens before the report runs. If the generated field name or file name is wrong, fix the macro invocation or the macro body, then recompile.

Where PANDD and MACDDN fit

Stored macros usually live in a macro library. Broadcom documents PANDD as the default DD name used to point to the PDS where macros reside when MACDDN is set to PANDD. Your site may use a different DD name, so check the Easytrieve option file and compile JCL.

//PANDD    DD  DISP=SHR,DSN=SITE.EASYTRIEVE.MACLIB
//SYSIN    DD  DISP=SHR,DSN=SITE.EASYTRIEVE.SOURCE(REPT001)

If the macro member cannot be found, verify the macro library DD statement, member name, and option-table setting before changing the program logic.

Good uses for Easytrieve macros

• Shared file layouts used by several reports.
• Standard report title and heading blocks.
• Common date, amount, and code-description formatting.
• Reusable selection code that is stable and well tested.
• Report skeletons used by a team with consistent naming rules.

When not to use a macro

Do not hide business rules inside a macro just to make the program shorter. If the rule changes often or needs runtime decisions, keep it visible in the program or move it to a callable routine where that fits the design.

Also avoid one large macro that builds most of the report. That makes compile errors harder to trace and turns a small library change into a risky shared-code release.

Common mistakes

Calling a macro with CALL

CALL is for subprograms. Use the percent-sign form to invoke a macro.

Changing a shared macro without impact review

A macro can be used by many jobs. Search the source library for every %MACRONAME reference before changing a shared member.

Forgetting the macro library DD

If the compile cannot resolve the macro, check PANDD, MACDDN, and the macro member name first.

Review checklist

• Confirm the macro name and invocation line use the percent sign.
• Check that every ampersand parameter has a matching prototype name.
• Verify PANDD or the site macro DD points to the correct library.
• Review the expanded compile listing when debugging macro-generated code.
• Search for all users before changing a shared macro.
• Keep comments near the macro prototype so users know the expected parameters.

Related Mainframe Forum guides

For connected Easytrieve topics, read Easytrieve Macro Sample Program, Creating Easytrieve Macros, Easytrieve Library, Easytrieve Basic Reporting, Easytrieve Basic Conditions, and Easytrieve Basic Report Calculation.

External references

Broadcom documents how to invoke Easytrieve macros, ampersand substitution in macro bodies, and PANDD and MACDDN library setup.

FAQ

How do you invoke an Easytrieve macro?

Use the percent sign followed by the macro name, such as %CUSTLAY. Do not use CALL for an Easytrieve macro.

What does an ampersand mean in an Easytrieve macro?

An ampersand marks a parameter substitution word in the macro body. The name must match a parameter on the macro prototype.

What is PANDD in Easytrieve?

PANDD is commonly used as the DD name for the macro library when the option-table MACDDN value points to it.

Are Easytrieve macros runtime routines?

No. Macros expand into source before the report runs. Runtime routines are called with statements such as CALL.

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.

Easytrieve Basic Report Edit Field Definition.

Easytrieve Basic Report Edit Field Definition

HEADING Parameter

You use the HEADING parameter to specify an alternative column heading for a field. (The default column heading is the field-name.)

• Place the alternate column heading within single quotation marks. For example,

CL-NAME               5       20       A      HEADING ‘CLIENT NAME’

Produce the column heading
          
  CLIENT NAME    

MASK

An edit mask is a pattern of characters specifying how non-alphanumeric data is to be printed. Alphanumeric fields cannot be edited. An edit mask is created using combinations of the following characters:

9     Formats digits.
Z     Suppresses Leading zeroes.
*     Replaces leading zeroes with an asterisk.
-     Prints a minus sign prior to the first non-zero digit of a
      negative number
$    Prints a currency symbol prior to the first non-zero digit.

Each digit in the field must be designated in the mask. Any character which follows the last character of the edit mask is printed if the field is negative.

Example
              Mask             Field         Result
              ------------ ------------ ------------
              $$, $$9        01234       $1,234

Defining Edit Masks

You can define standard edit masks when your system is installed.

       MASK                                     USE
 ‘(999) 999-9999’                 Telephone Number
 ‘999-99-9999’                    Social Security number

 ‘Z9 / 99 / 99’                   Date
 ‘$$, $$$, $$9.99                 CREDIT’ Money (with floating $)

 ‘*, ***, ***, 999.99-‘           Protected Check Amount
 ‘--, ---, -9.99’                 Negative Number

Syntax

[     MASK   [letter]   [BWZ]    [‘literal’]       ]

• MASK is the EASYTRIEVE PLUS keyword.
• Letter names the edit mask to follow. Once a mask is defined, it need not be defined again; simply use the letter.
• BWZ (blank when zero) specifies that a field should not be printed if the entire field contains zeroes. BWZ must be coded whenever needed.
• Literal is the format of the mask using the characters indicated on the previous page.

Redefining a Field

Sometimes it is necessary to break a field into several parts in order to get the exact information for your report. A birth date, for example, may have been originally entered as one field in a record. Now you want to access this information by either the month, day, or year. With EASYTRIEVE PLUS you can redefine that field in the following manner:

DATE-OF-BIRTH             103         6            N
    MONTH                 103         2            N
    DAY                   105         2            N
    YEAR                  107         2            N

DATE-OF-BIRTH | _ | 0 | 2 | 1 | 0 | 5 | 5 | _ | _ | _ | _ |
 position 103 105 107

 Start-location of New Fields

In this exhibit, the MONTH (02) starts in position 103 and occupies position 103 and 104. The DAY starts in 105 and occupies positions 105 and 106. Finally, YEAR starts in 107 and occupies 107 and 108.lves setting aside as an area of storage as a place to keep calculations or other information that is to be created during the running of an EASYTRIEVE PLUS program.

• Define working storage by specifying W as the start location.
• The values stored in this field are associated with each individual record.

Example

GROSS          30         4     N   2
NET            34         4     N   2
WORK-DEDUCT    W          4     N   2  HEADING ‘DEDUCTIONS’