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 Field Definition: Name, Position, Length, and Type

An Easytrieve report prints the wrong value when a field starts at the wrong byte. Field definitions tell Easytrieve where each value begins, how many bytes it occupies, and whether the data is alphanumeric, numeric, packed decimal, unsigned packed, or binary.

Define bytes first.

What is an Easytrieve field definition?

An Easytrieve field definition names one item inside a file record or a working storage area. For an input file, the definition normally gives the field name, start position, length, data type, and optional decimal positions. Report options such as HEADING and MASK can be added when the field is printed.

The field definition is usually coded below the FILE statement. Easytrieve uses it when the job reads the file, tests values, calculates totals, or prints report columns.

Basic syntax

field-name   start-location   field-length   data-type   [decimal-positions] +
             [HEADING 'literal'] [MASK 'edit-mask']

The old post listed the same parts, but the rewrite below shows how each part affects a real report.

Field definition parts

Part	Meaning	Example
field-name	The name used later in IF, MOVE, DISPLAY, LINE, and calculations.	PAY-NET
start-location	The byte position in the record, counted from position 1.	90
field-length	The number of bytes occupied by the field.	4
data-type	How Easytrieve should read and process the bytes.	P for packed decimal
decimal-positions	The implied number of decimal places for numeric fields.	2

Simple input file example

This example defines a fixed personnel record. The fields are then used in a report line.

FILE PERSNL FB(150 1800)
     DEPT        1   3 N
     EMPNO       9   5 N
     NAME       17  20 A
     PAY-NET    90   4 P 2

JOB INPUT PERSNL
    IF DEPT = 910
        PRINT PAYRPT
    END-IF

REPORT PAYRPT LINESIZE 100
    TITLE 1 'DEPARTMENT 910 NET PAY'
    LINE DEPT EMPNO NAME PAY-NET

If PAY-NET starts at byte 91 instead of byte 90, the report can show bad packed data or fail when Easytrieve tries to treat the wrong bytes as a packed amount.

Choosing field names

Use field names that match the business meaning of the data. PAY-NET is easier to read than FIELD-4. A field name also needs to be unique enough for the program. When two files contain the same field name, qualify it with the file name, such as PERSNL:DEPT.

Start location and length

The start location is counted from the first byte of the record. The length is the storage length, not the display width that appears on a printed report.

NAME       17  20 A
ADDRESS    37  39 A
PAY-NET    90   4 P 2

In this layout, NAME uses bytes 17 through 36. ADDRESS starts at byte 37. That clean byte boundary is what prevents fields from bleeding into each other.

Easytrieve data types

Type	Use it for	Practical note
A	Names, codes, descriptions, and other character data.	Best for values that should print exactly as stored.
N	Zoned/display numeric fields.	Common for readable numeric fields in flat files.
P	Packed decimal fields.	Common for money and quantity values from COBOL files.
U	Unsigned packed decimal fields.	Use only when the field is not signed.
B	Binary fields.	Broadcom notes that Easytrieve binary fields are defined as B fields and should be 4 bytes or less in the cited sample.

Decimal positions

Decimal positions are implied. They are not stored as a visible decimal point in the input record. In the next example, AMOUNT is a five-byte numeric field with two decimal positions.

AMOUNT     40   5 N 2

A stored value of 00123 represents 1.23 when the field is treated as having two decimal places. Use decimal positions only for fields that are really numeric quantities. Do not define account numbers, employee numbers, or product codes with decimal positions just because they contain digits.

HEADING for report columns

HEADING gives a better column title when the field prints on a report. You can define it with the field or in the report section.

FILE PERSNL FB(150 1800)
     EMPNO       9   5 N HEADING 'EMPLOYEE NUMBER'
     PAY-NET    90   4 P 2 HEADING 'NET PAY'

Broadcom documents report-level heading syntax as the field name followed by heading literals in parentheses. Keep the field name outside the parentheses.

REPORT PAYRPT
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING PAY-NET ('NET' 'PAY')
    LINE EMPNO PAY-NET

MASK for printed values

MASK controls how a value appears when it is printed. It is useful for commas, decimal points, signs, and leading zero suppression.

PAY-NET    90   4 P 2 HEADING 'NET PAY' MASK 'ZZZ,ZZ9.99'

Broadcom notes that MASK applies to fields printed through report output. It is not a general data conversion rule for every move to a non-printer file.

Working field definitions

You can also define working fields for calculations. These fields are not pulled directly from the input record position. They hold values created by the program.

DEFINE TAX-AMT    W  7 P 2
DEFINE NET-AFTER  W  7 P 2

JOB INPUT PERSNL
    TAX-AMT = PAY-NET * .20
    NET-AFTER = PAY-NET - TAX-AMT
    PRINT PAYRPT

Use working fields when a report needs a calculated value, a temporary total, or a reformatted copy of an input field.

Common mistakes

Using display length as storage length

A packed decimal amount may print as several characters but use fewer bytes in the record. Define the storage bytes, then use MASK for the printed look.

Defining identifiers as numeric quantities

A department code or employee number may contain only digits, but it is still an identifier. Avoid decimal positions and automatic totaling for identifier fields.

Putting the field name inside HEADING parentheses

For report-level headings, code HEADING EMPNO ('EMPLOYEE' 'NUMBER'). Coding HEADING (EMPNO 'EMPLOYEE') can produce a field-name expected error.

Copying a record layout without checking byte positions

A one-byte shift can damage every field after it. Check start position, length, and type against the copybook or file layout before using the field in production output.

Quick checklist

• Confirm the field starts at the correct byte position.
• Confirm the length is the storage length in bytes.
• Use A for text and identifiers that should not calculate.
• Use N, P, U, or B only when the field is truly numeric.
• Add decimal positions only when the value has implied cents, rates, quantities, or similar scale.
• Use HEADING for report column names.
• Use MASK for printed formatting, not as a substitute for the correct data type.

Related Easytrieve guides

For nearby topics, read Easytrieve Basic Reporting, Easytrieve Basic Report Edit Field Definition, Easytrieve Report Calculation, Easytrieve Basic Conditions, Easytrieve Sorting, and Easytrieve VSAM File Handling.

External references

Technical notes in this refresh were checked against Broadcom binary field guidance, Broadcom HEADING syntax guidance, Broadcom MASK parameter guidance, and Broadcom field heading notes.

FAQ

What are the required parts of an Easytrieve field definition?

The usual required parts are field name, start location, field length, and data type. Numeric fields can also include decimal positions.

What does the start location mean in Easytrieve?

The start location is the byte position where the field begins in the input record, counted from position 1.

When should I use HEADING in Easytrieve?

Use HEADING when the printed report needs a clearer column name than the field name.

What is MASK used for in Easytrieve?

MASK controls how a printed value appears, such as commas, decimal points, signs, and leading zero suppression.