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 Reporting: FILE, JOB, REPORT, and LINE

A small Easytrieve report can read a personnel file, select the records you want, and print a clean listing with just a few statements. The core flow is FILE, field definitions, JOB INPUT, PRINT, REPORT, and LINE.

One file, one report.

What is Easytrieve basic reporting?

Easytrieve basic reporting means reading input records and sending selected fields to a report layout. It is often used for quick batch listings, reconciliation reports, extract checks, and one-time analysis jobs where a full COBOL program would take longer to write.

The report definition controls how the output looks. The job activity controls what records are read and when the report is printed.

Basic Easytrieve report flow

Part	Purpose
FILE	Names the input file and describes the physical record.
Field definitions	Define field name, starting position, length, and data type.
JOB INPUT	Reads the input file automatically for the job activity.
PRINT	Sends the current record to a named report.
REPORT	Starts the report layout definition.
TITLE, HEADING, LINE	Define headings and printed report fields.

Define the input file

The FILE statement names the file used by the program. The fields below it describe positions inside each input record. In this example, PERSNL is a fixed-length personnel file.

FILE PERSNL FB(150 1800)
     EMPNO       9   5 N
     DEPT        1   3 N
     NAME       17  20 A
     GROSS      94   4 P 2

The format depends on your site standards and product release, but the idea is stable: Easytrieve must know where each field starts and how to treat the data.

JOB INPUT and PRINT

JOB INPUT PERSNL tells Easytrieve to read the input file for the job activity. The PRINT statement prints the current record using the report definition named after it.

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

This example prints only department 910. Without the IF, every input record would be printed.

REPORT, TITLE, and LINE example

The REPORT statement starts the layout. TITLE prints report titles. LINE lists the fields that should appear on each detail line.

REPORT DEPTRPT LINESIZE 80
    TITLE 1 'DEPARTMENT 910 REPORT'
    LINE DEPT EMPNO NAME GROSS

Broadcom examples use this same report pattern: read input, issue PRINT, define REPORT, add a TITLE, and place fields on the LINE statement.

Use HEADING for readable columns

Default column headings are not always friendly. Use HEADING to print useful column names. Broadcom documents the syntax as a field name followed by one or more heading literals.

REPORT DEPTRPT LINESIZE 80
    TITLE 1 'DEPARTMENT 910 REPORT'
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING GROSS ('GROSS' 'PAY')
    LINE DEPT EMPNO NAME GROSS

Keep the field name outside the parentheses. Putting the field name inside the parentheses is a common syntax error.

LINESIZE and line overflow

LINESIZE controls the maximum report line width. If the fields on a LINE statement exceed the report width, Easytrieve can issue a line overflow error. Broadcom has a DB2 sample where long fields caused a report line overflow, and the fix was to reduce field sizes or increase the report line size to match the report design.

REPORT DEPTRPT LINESIZE 132
    TITLE 1 'WIDER PERSONNEL REPORT'
    LINE DEPT EMPNO NAME GROSS

For printed batch output, choose a line size that matches the report destination. Do not make every report 300 columns wide unless the output target can use it.

Full beginner report example

This example pulls the basic pieces together. It reads a personnel file, selects one department, and prints a short detail report.

FILE PERSNL FB(150 1800)
     DEPT        1   3 N
     EMPNO       9   5 N
     NAME       17  20 A
     GROSS      94   4 P 2

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

REPORT DEPTRPT LINESIZE 100
    TITLE 1 'DEPARTMENT 910 EMPLOYEE LIST'
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING GROSS ('GROSS' 'PAY')
    LINE DEPT EMPNO NAME GROSS

Syntax notes from the original post

The original post listed syntax characters. These are still useful when reading Easytrieve code.

• A blank separates statement parts.
• Parentheses group heading literals and sub-parameters.
• A colon qualifies a non-unique field name, such as PERSNL:NAME.
• A comma is optional in many report lists and is often used for readability.
• Single quotation marks enclose literals, such as 'TEXAS'.
• An asterisk in the first non-blank position marks a comment.
• A plus sign can continue a long statement to the next line.

Common mistakes

Printing before fields are defined

If a field is not defined correctly under the input file, the report may print blanks, wrong values, or data from the wrong byte position.

Letting identifier fields total or wrap

Employee number, department number, and account code may be numeric, but they are identifiers. Keep them as display fields and review report width before adding more columns.

Ignoring output width

A report that looks fine in source can fail or wrap badly when the output file has a smaller line size. Check LINESIZE with the fields on the LINE statement.

Related Easytrieve guides

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

External references

Technical notes in this refresh were checked against Broadcom Easytrieve report sample code, Broadcom report line overflow guidance, Broadcom HEADING syntax guidance, and Broadcom FILE and JOB INPUT notes.

FAQ

What statements are needed for a basic Easytrieve report?

A small report usually needs a FILE statement, field definitions, JOB INPUT, PRINT, REPORT, TITLE, and LINE.

What does JOB INPUT do in Easytrieve?

JOB INPUT names the automatic input file for the job activity. Easytrieve reads that file and runs the job logic for each record.

What does LINE do in an Easytrieve report?

LINE lists the fields and spacing that should print on each report detail line.

How do I avoid Easytrieve report line overflow?

Set a suitable LINESIZE, limit the number of fields on the LINE statement, and shorten fields that are wider than the report destination can hold.

Easytrieve VSAM File Handling: FILE, PUT, STATUS, and FILE-STATUS

An Easytrieve job that loads a VSAM file needs three things to be readable in production: a clear FILE definition, one obvious PUT path, and a status check after the write. If the program only says PUT OUTMAST FROM MASTER and never checks the result, a duplicate key or allocation problem can hide until the next batch step fails.

Check status after each write.

What this Easytrieve file handling example covers

The original post showed a short VSAM loading example. This refreshed version keeps that search intent and expands it into a practical guide for FILE, PUT, STATUS, and FILE-STATUS. It is not a full Easytrieve course; it is a focused checklist for creating or loading a VSAM output file safely.

Easytrieve FILE statement role

The FILE statement describes an input or output file to Easytrieve. For a sequential input file, the statement gives the record format and length. For a VSAM output file, it identifies the file as VSAM and can include file handling options such as CREATE and RESET, depending on site standards and the target file.

FILE MASTER FB(150 1800)
     EMPNO      9    5 N
     NAME      17   16 A
     GROSS     94    4 P 2
FILE OUTMAST VS(CREATE RESET)

The input definition tells Easytrieve where fields live in the record. The output definition tells Easytrieve that OUTMAST is the VSAM target. Your JCL still needs the correct DD names and data set allocation rules for the environment.

PUT statement for VSAM output

PUT writes an output record. In a load job, a common pattern is to read each input record, build or reuse an output record layout, write it to the VSAM file, and immediately test the status.

JOB INPUT MASTER NAME LOAD-VSAM
    PUT OUTMAST FROM MASTER STATUS
    IF OUTMAST:FILE-STATUS NE 0
       DISPLAY 'VSAM LOAD ERROR. STATUS: ' +
               OUTMAST:FILE-STATUS
       STOP
    END-IF
    PRINT RPT1

The sample uses STATUS so the program can test the result of the VSAM I/O operation. Do not let a file load continue blindly after a failed write.

What FILE-STATUS tells you

FILE-STATUS is a system-defined status field associated with the file. After a VSAM operation, test it before assuming the record was written. A zero status normally means the operation completed successfully. Non-zero status needs handling, logging, or a controlled stop.

Check	Why it matters
OUTMAST:FILE-STATUS = 0	The write completed successfully and the job can continue.
OUTMAST:FILE-STATUS NE 0	The program should display or report the status and stop or route the record to error handling.
Status not checked	The next step may fail with poor evidence, making production support slower.

Complete Easytrieve VSAM load example

This example keeps the program small. It reads MASTER, writes the record to OUTMAST, checks status, and prints a simple report line.

FILE MASTER FB(150 1800)
     EMPNO      9    5 N
     NAME      17   16 A
     GROSS     94    4 P 2
FILE OUTMAST VS(CREATE RESET)
JOB INPUT MASTER NAME LOAD-VSAM
    PUT OUTMAST FROM MASTER STATUS
    IF OUTMAST:FILE-STATUS NE 0
       DISPLAY 'LOAD ERROR. FILE STATUS: ' +
               OUTMAST:FILE-STATUS
       STOP
    END-IF
    PRINT RPT1
REPORT RPT1
    LINE 1 EMPNO NAME GROSS

Use the exact file names, field names, and VSAM options used at your site. The pattern is more important than the sample names: define, write, check, report.

CREATE and RESET in a load job

CREATE and RESET are often seen in examples that load or recreate output. Before using them, confirm whether the VSAM cluster is newly allocated, reusable, or managed by a delete/define step in JCL. A production load should not accidentally replace a file that another application expects to keep.

If the cluster is created with IDCAMS before the Easytrieve step, keep the JCL and Easytrieve file options consistent. For VSAM definition examples, see the Mainframe Forum DEFINE CLUSTER guide.

Empty input and empty output handling

An empty input file should still produce predictable job behavior. Broadcom notes that automatic input processing can handle open, end-of-file, and read logic for the input activity. For output-only or empty-output cases, the file may need an explicit CLOSE pattern depending on platform and file definition.

JOB INPUT NULL NAME CLOSE-OUTPUT
    CLOSE OUTMAST
    STOP

Do not rely on accidental file creation behavior. If an empty output file must exist for the next job step, test that case in lower environments.

Report work files and large reports

File handling also matters when Easytrieve creates large reports. Broadcom documents REPORT work files for large sequenced or multiple reports. Those work files are separate from ordinary input and output business files. If a report step spills to work files, make sure the JCL or site options provide enough space.

Common mistakes

Skipping STATUS on the PUT

A failed VSAM write should be visible in the same step. Use STATUS and test file-name:FILE-STATUS after the operation.

Using unclear file names

Names such as INFILE and OUTFILE are fine in a small example, but production jobs are easier to support when names show business meaning: CUSTIN, PAYMST, or ERRRPT.

Not testing duplicate-key cases

A VSAM load can fail because the target key already exists or the file definition is wrong. Test duplicate, missing, and maximum-value records before moving the job to production.

Quick checklist before running the job

• Confirm the input DD name matches the Easytrieve FILE name.
• Confirm the VSAM output file exists or is created by the planned step.
• Check record length and field positions before the first load run.
• Use STATUS on the write and test FILE-STATUS.
• Keep a report or display message that shows the failing status value.
• Test empty input, duplicate key, and normal load paths.

Related Mainframe Forum guides

For the surrounding topics, read Easytrieve introduction, Easytrieve program structure, Easytrieve basic reporting, VSAM IDCAMS guide, and JCL DD statement examples.

External references

Broadcom support notes describe Easytrieve FILE statement and empty output handling, REPORT work files, and Virtual File Manager usage.

FAQ

How do you write to a VSAM file in Easytrieve?

Define the VSAM output with a FILE statement, write records with PUT, use STATUS, and test file-name:FILE-STATUS after the write.

What does FILE-STATUS mean in Easytrieve?

FILE-STATUS is the status value returned for a file operation. A zero value normally means success; a non-zero value should be handled or reported.

Should an Easytrieve load job use CREATE RESET?

Use CREATE or RESET only when it matches the site file handling standard and the VSAM cluster lifecycle. Confirm this before replacing production data.

What should I test before a VSAM load job goes live?

Test normal records, empty input, duplicate keys, bad field positions, and non-zero file status handling.

Easytrieve Advance Topic Activity

CALL Statement

The CALL statement invokes an external subprogram. Usually, the CALLed program is an existing program in another language that performs an unsupported function.

CALL program-name [NR] USING ( field-name … )

MOVE Statement

You use the MOVE statement to transfer data from one location to another. MOVE is useful for moving data without conversion and for moving character strings with variable lengths.

• You can move a field or a literal to a field or move a file to a file.
• A sending field longer than a receiving field is truncated on the right.
• A longer receiving field is padded on the right with spaces or an alternate fill character.
• Spaces or zeroes can be moved to one or many fields.

MOVE NAME 20 TO HOLD-NAME
MOVE NAME CTR TO HOLD-NAME FILL ‘*’
MOVE SPACES TO NAME, HOLD-NAME, HOLD-DIV

MOVE LIKE file-name-1 TO file-name-2

MOVE LIKE

MOVE LIKE moves the value of fields with identical names from one file to another while converting numeric data-types from one format to another.

• The rules for the assignment statement also apply to MOVE LIKE.
• Because the same field-name can be used in more than one file, you must qualify duplicate field-names by prefixing the field-name with the file-name and a colon.

User Procedures (PROCs)

A user PROC is a group of user-written EASYTRIEVE PLUS statements designed to accomplish a task. You use a user PROC when identical logic is needed in several places in the activity.

A user PROC must be invoked in the activity with a PERFORM statement.

PERFORM proc-name

 proc-name. PROC
       ** Logic **
END-PROC

Proc-name

Proc-name is the same name as in the PERFORM statement and is followed by a period, a space, and the keyword PROC.

END-PROC

Every PROC must have an END-PROC. At END-PROC, control returned to the statement following the PERFORM statement that invoked the PROC

START / FINISH parameters

You use the optional START and FINISH parameters of the JOB statement to automatically incorporate procedures into processing activities.

JOB input file-name [ NAME job-name ] + [ START proc-name ] [FINISH proc-name]

START parameter

You use START to identify a procedure to be executed during initiation of the JOB activity.

• The procedure is invoked automatically after the file are opened and prior to the first input record.
• A typical START procedure might initialize working storage fields or establish a position in a keyed sequenced file.

FINISH parameter

You use FINISH to identify a procedure to be executed during the normal termination of the JOB activity.

• The procedure is invoked after the last input record is processed and before the files are closed.
• A typical FINISH procedure displays control information accumulated during execution of the JOB activity.
• A FINISH proc is invoked if a STOP is encountered but it is not invoked if a STOP EXECUTE is encountered.

GOTO Statement

You use the GOTO statement to modify the natural top-to-bottom logic flow in a program.

GOTO JOB transfers control to the top of current JOB activity.

Example

JOB INPUT PERSNL NAME DIV-LIST
     IF DIV = ‘A’
  ---->          GOTO JOB
    END-IF
    IF DIV = ‘B’
  ---->         GOTO CHECK-REG-RTN
     END-IF
       ** Logic **
   CHECK-REG-RETURN

DO WHILE / END-DO Statements

You use the DO WHILE and END-DO statements to provide a controlled loop for repetitive program logic.

• The logic between DO WHILE and END-DO is executed until the conditional expression on the DO WHILE statement is false.
• Conditional expressions follow the rules of IF statements.

JOB INPUT PERSNL NAME DO-EX-1
CTR = 0
DO WHILE CTR LT 10
           CTR = CTR + 1
            ** Logic **
END-DO
IF …

Nesting Example

You can nest DO WHILE statements. (The inner logic loop must be completely within the outer logic loop.)

Easytrieve Plus Tutorial: FILE, JOB, REPORT, and JCL

FILE, JOB, PRINT, REPORT, and LINE are enough to build a useful Easytrieve Plus report. A short program can read a fixed-length file, select records, and format a listing without the amount of source normally required for the same report in COBOL.

Define the file, process records, then format the output.

What is Easytrieve Plus?

Easytrieve Plus is a mainframe data-processing and report-generation language. Teams use it for batch listings, extracts, reconciliations, file maintenance, summaries, and small conversion jobs. It combines record definitions, procedural logic, and report formatting in one source member.

The product is often called Easytrieve, Easytrieve Plus, or Easytrieve Report Generator. Product names and available features vary by release, so check the procedure and manuals installed at your site before copying syntax into production.

Good first use case: read a personnel file, select one department, and print employee number, name, and gross pay. That exercise covers the main program flow without hiding the logic inside a large example.

Where Easytrieve fits on a mainframe

Easytrieve is strongest when the work is record-oriented and the result is a report or extract. Broadcom examples show automatic input processing for flat files and VSAM, and an optional interface can read Db2 tables. Easytrieve also handles working fields, conditional logic, sorting, control breaks, totals, and formatted report columns.

Requirement	Easytrieve fit	Reason
Daily exception report	Strong	Record selection and report formatting stay in a compact program.
One-time file reconciliation	Strong	Input layouts, comparisons, and printed differences can be coded together.
VSAM or Db2 extract	Site dependent	The required access method or licensed interface must be available.
Large online transaction application	Usually weak	COBOL and CICS normally provide the structure and operational model needed for long-lived transaction code.

Easytrieve program flow

A beginner program normally has three logical parts. The library section defines files and fields. The job activity reads records and applies processing rules. The report section formats the records selected by PRINT.

1. Define the input file and fields

The FILE statement names the input source. Field definitions identify the starting position, length, and data type inside each record.

FILE PERSNL F(150)
     DEPT        1   3 N
     EMPNO       9   5 N
     NAME       17  20 A
     GROSS      94   4 P 2

A defines an alphanumeric field, N defines numeric display data, and P defines packed decimal data. The final 2 on GROSS supplies the number of decimal positions. Confirm every offset against the real copybook or file layout; a one-byte error can make valid EBCDIC data look corrupt.

2. Process records in the JOB activity

JOB INPUT PERSNL requests automatic input processing. Easytrieve reads each record from PERSNL and runs the statements in the activity. This example prints only department 910.

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

The PRINT statement does not define the layout. It sends the current record to the named report. Keep the report name consistent or the source will fail during syntax checking.

3. Format the report

The REPORT statement begins the layout. TITLE defines the report title, HEADING replaces default field headings, and LINE lists the fields printed on each detail line.

REPORT DEPTRPT LINESIZE 100
    TITLE 1 'DEPARTMENT 910 EMPLOYEES'
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING GROSS ('GROSS' 'PAY')
    LINE DEPT EMPNO NAME GROSS

Broadcom publishes the same core pattern in its Easytrieve examples: define the input, run a JOB activity, issue PRINT, and describe the report with REPORT, TITLE, and LINE.

Complete Easytrieve Plus example

The following source combines the definitions, record selection, and report layout. Replace positions and lengths with the values used by your input file.

FILE PERSNL F(150)
     DEPT        1   3 N
     EMPNO       9   5 N
     NAME       17  20 A
     GROSS      94   4 P 2

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

REPORT DEPTRPT LINESIZE 100
    TITLE 1 'DEPARTMENT 910 EMPLOYEES'
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING GROSS ('GROSS' 'PAY')
    LINE DEPT EMPNO NAME GROSS

For a closer explanation of library, activity, and report sections, use the Easytrieve program structure tutorial. The separate Easytrieve basic reporting guide covers report statements in more detail.

Run Easytrieve from JCL

Many sites provide a cataloged procedure that runs the Easytrieve translator and runtime. The procedure name, program name, load libraries, source DD name, and work files are installation choices. Do not assume that a sample procedure from another company will run unchanged.

//EZTRPT   JOB ...
//STEP1    EXEC PROC=your-site-easytrieve-proc
//PERSNL   DD  DSN=your.input.personnel,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  ... Easytrieve source here ...
/*

If your procedure expects the source on a DD name other than SYSIN, follow the installed procedure. The PERSNL DD name must match the FILE PERSNL definition. Review SYSPRINT after every test for syntax messages, file allocation failures, and the final return code.

Production check: inspect the expanded JCL in JES before changing STEPLIB, source, or work-file DD statements. The cataloged procedure tells you which runtime your job actually uses.

Files and databases Easytrieve can process

Broadcom states that Easytrieve can read, write, and update standard IBM flat files, VSAM, and several database sources on the mainframe. Db2 access requires the appropriate licensed interface. A job that reads VSAM also needs the correct file organization, key definition, DISP, and sharing options.

Use the Easytrieve VSAM file handling guide for PUT, STATUS, and FILE-STATUS patterns. For field positions and data types, see Easytrieve field definitions.

Easytrieve Plus and COBOL compared

Choose Easytrieve when a small team needs a clear report, extract, or file check and the language is supported at the site. Its automatic input and report facilities remove much of the control code required for a simple batch listing.

Choose COBOL when the application contains many modules, shared copybooks, complex recovery rules, long-lived business logic, or online CICS processing. Maintainability depends more on local skills, tests, and standards than on source-line count.

Common Easytrieve beginner errors

• Wrong field position: output shows unexpected characters because a definition starts one byte early or late.
• Wrong data type: packed, binary, zoned, and alphanumeric data are not interchangeable.
• Missing DD statement: the FILE name exists in the source but the JCL does not allocate the matching DD name.
• Unknown report name: PRINT DEPTRPT points to a missing or differently spelled REPORT.
• Line overflow: the fields on LINE need more print positions than LINESIZE permits.
• Site-specific syntax: a statement copied from another release or compatibility mode is not accepted by the installed runtime.

Easytrieve Plus learning path

1. Run one fixed-file listing with no selection logic.
2. Add an IF condition and confirm the record count.
3. Add headings, masks, totals, and a control break.
4. Move reusable definitions into the site library only after the standalone source works.
5. Study Easytrieve report calculations and Easytrieve macros after the basic report is stable.

Official Easytrieve references

• Broadcom: Accessing Db2 with Easytrieve Plus Report Generator
• Broadcom: Easytrieve Plus and EBCDIC data files
• Broadcom: Easytrieve Plus report example
• Broadcom: REPORT LINESIZE rules

Easytrieve Plus FAQ

What is Easytrieve Plus used for?

Easytrieve Plus is used for batch reporting, file selection, extracts, summaries, data checks, and small file-processing jobs on mainframe systems.

Does Easytrieve Plus replace COBOL?

No. Easytrieve is a good fit for compact reporting and data-processing jobs. COBOL is usually a better choice for large applications, complex transaction logic, and code that needs extensive modular design.

Can Easytrieve read VSAM and Db2 data?

Easytrieve can process flat files and VSAM. Db2 access depends on the licensed interface and the standards installed at your site.

How is an Easytrieve program run in JCL?

Sites normally provide a cataloged procedure or execution step that points to the Easytrieve runtime libraries. Supply the source through the DD name required by that procedure and add DD statements for every input and output file.

Start with one real input layout and make the first report match its record positions exactly; every later Easytrieve feature depends on that definition being correct.