Easytrieve Library Section: FILE, VFM, COPY, and EXIT

Easytrieve file declarations

FILE CUSTIN FB(120 1200) tells Easytrieve how a data set is organized before a JOB reads it. If the record format or length disagrees with the DD statement or catalog entry, the program can fail before its business logic processes a record. The Easytrieve Library section is where that contract, the record layout, and program work fields are declared.

A physical file links a JCL DD to a FILE declaration and record layout; a VIRTUAL work file needs no matching DD.

Scope: this page covers Library-section declarations. For the order of Environment, Library, and Activity source, see Easytrieve program structure.

What the Easytrieve Library section does

The Library section sits after optional Environment-section PARM statements and before the first JOB or SORT activity. It describes the data that executable statements will use. Typical entries include input and output FILE statements, fields associated with those files, working-storage fields, COPY statements, and optional file-exit information.

Declaration	Purpose	Operational check
FILE	Names a file and can describe organization, record format, length, and processing attributes.	For a physical z/OS file, confirm that the file name matches the JCL DD name and that DCB attributes agree.
File fields	Map names to positions, lengths, data types, and decimal places in a record.	Ensure that the last field does not extend beyond the record length.
Working storage	Defines counters, switches, totals, and other fields not read directly from a file record.	Choose a type and length that suit the calculation or comparison.
COPY	Duplicates the field layout of a file already declared in the source.	Qualify duplicated field names when both files are referenced.
EXIT	Calls a user routine around supported file I/O.	Verify the interface, parameters, supported file type, and installation conventions.

Easytrieve FILE statement and record layout

A simple disk-file definition can carry explicit record attributes, or it can rely on attributes available through allocation. Site standards differ, so treat the JCL, catalog entry, and Easytrieve source as one definition. Do not copy an FB or VB declaration from another job without checking the real data set.

FILE CUSTIN FB(120 1200)
  CUSTOMER-ID       1   10 A
  CUSTOMER-NAME    11   30 A
  REGION-CODE      41    3 A
  BALANCE          44    9 P 2

WS-SELECTED        W     7 N 0
WS-HIGH-BALANCE    W     9 P 2

Here, CUSTIN is the file name used by later Easytrieve statements. The file fields describe bytes within its logical record. The W fields are program storage rather than part of CUSTIN. For the full rules behind position, length, type, masks, and redefinitions, use the separate Easytrieve field-definition guide.

When can the FILE statement omit attributes?

Some z/OS input files can obtain record information from the allocated data set. Coding only FILE CUSTIN may therefore work at one installation. It also removes a useful compile-time check. Broadcom documents B055 cases where defined fields extend beyond the FILE length; removing the length suppresses that comparison but does not correct an inaccurate layout. The safer response is to verify the record definition and update the length when the source is wrong.

F versus FB and compiler message B049

F(80) describes fixed-length records with a logical record length. If a second numeric value is supplied for block size, the format must support blocking. Broadcom's B049 example changes F(730 13870) to FB(730 13870). Make that change only when it matches the data set's actual RECFM and sizes.

Production check: compare Easytrieve FILE attributes with the allocation shown in the job log, catalog, or data-set listing. A syntactically valid declaration can still describe the wrong bytes.

VFM and VIRTUAL work files

Virtual File Manager (VFM) provides sequential work files during an Easytrieve execution. Code VIRTUAL on the FILE statement; the work file does not require a matching JCL DD. A common use is to hold sorted or selected records for a later activity in the same program.

FILE SORTWK VIRTUAL FB(80 800)
  WK-ACCOUNT        1   10 A
  WK-NAME          11   30 A
  WK-AMOUNT        41    9 P 2

SORT CUSTIN TO SORTWK USING (REGION-CODE CUSTOMER-ID)

JOB INPUT SORTWK
  PRINT REGION-RPT

The SORT activity and its exact syntax belong on the Easytrieve sorting page; the example here shows why the Library declaration exists. VFM uses configured memory and can spill excess work data to an installation-defined disk area. Large sorts or multiple sequenced reports can therefore create real DASD activity even though the source says VIRTUAL.

Use RETAIN only when another read is required

Without RETAIN, a VIRTUAL file is normally consumed and released after it is read. Add RETAIN when later activities must read the same VFM file again during the program execution.

FILE SELECTED VIRTUAL RETAIN FB(80 800)

RETAIN does not turn the work file into a permanent cataloged data set. Broadcom states that the retained VFM file lasts until the Easytrieve program ends. For a persistent output consumed by another job, define a physical output file and allocate it in JCL.

COPY a record layout without repeating every field

The Easytrieve COPY statement duplicates field definitions from a previously declared file. It is useful when an input and output record share the same layout.

FILE FILEA FB(80 800)
  ACCOUNT-NO        1   10 A
  ACCOUNT-NAME     11   30 A
  STATUS-CODE      41    1 A

FILE FILEB FB(80 800)
  COPY FILEA

JOB INPUT FILEA
  IF FILEA:STATUS-CODE EQ 'A'
     MOVE FILEA:ACCOUNT-NO TO FILEB:ACCOUNT-NO
     PUT FILEB
  END-IF

COPY creates the same field names under both files. When a statement could refer to either copy, prefix the field with its file name, as in FILEA:ACCOUNT-NO. Broadcom identifies an unqualified duplicate as a cause of ambiguity message B039. IBM also documents file qualification for COPY-generated names.

COPY boundary: this statement reuses a record layout inside Easytrieve source. It is separate from Easytrieve macros, which are covered in the Easytrieve macro guide.

FILE EXIT for specialized I/O

An EXIT parameter associates a user routine with supported file I/O. The routine can adapt data that normal Easytrieve processing does not handle directly. IBM's Migration Utility documentation shows a non-MODIFY sequential-file form such as:

FILE FILE01 DISK F(80) EXIT (FSYTIXIT)

A non-MODIFY exit receives the file-record address and a request code, followed by fields named in USING when present. With MODIFY, the exit can inspect or change a record after input or before output. The exact interface and linkage rules are product- and installation-sensitive; start from a supplied sample and confirm them with the Easytrieve administrator.

IBM documents FILE EXIT support for sequential and VSAM files in this context and notes that Easytrieve Plus does not support it for DLI/IMS, IDMS, or Db2. For ordinary keyed-file logic, use the Easytrieve VSAM file-handling guide rather than adding a custom exit.

How Library declarations connect to an activity

The Library section defines names and layouts; a JOB or SORT later opens or processes them. In automatic input, the JOB names the input file. REPORT and LINE definitions then describe presentation rather than storage.

FILE CUSTIN FB(120 1200)
  CUSTOMER-ID       1   10 A
  CUSTOMER-NAME    11   30 A
  BALANCE          44    9 P 2

JOB INPUT CUSTIN NAME CUSTOMER-LIST
  IF BALANCE GT 0
     PRINT CUST-RPT
  END-IF

REPORT CUST-RPT
  TITLE 1 'CUSTOMERS WITH A BALANCE'
  LINE 1 CUSTOMER-ID CUSTOMER-NAME BALANCE

See the Easytrieve JOB statement for automatic input options and the Easytrieve reporting guide for REPORT, TITLE, and LINE behavior.

Common Library-section errors

Symptom	Likely cause	Check
B049 parameter ignored	Two size values were coded with F rather than a compatible blocked format.	Verify RECFM, LRECL, and block size; use FB only when it matches the data set.
B055 field exceeds file	The record layout extends beyond the FILE length.	Find the last defined byte and reconcile it with the real LRECL instead of merely removing the length.
B039 ambiguous name	COPY or repeated layouts created the same field name in multiple files.	Use a qualifier such as FILEA:FIELD1.
File-not-found or open failure	A physical FILE name has no matching DD, or the allocation is unsuitable.	Compare the FILE name with the execution JCL and review allocation messages.
Unexpected values	A field position, length, or type does not match the incoming record.	Inspect sample bytes and compare the layout with the producer's copybook.
VFM space problem	A work file or sequenced report exceeded configured VFM memory and spill resources.	Review EZTVFM allocation and VFM settings with the Easytrieve administrator.

Library-section review checklist

1. Place all Library declarations before the first JOB or SORT activity.
2. Match each physical file name to its JCL DD name.
3. Verify RECFM, LRECL, and any block size against allocation data.
4. Confirm that field endpoints stay within the logical record.
5. Qualify fields duplicated through COPY.
6. Use VIRTUAL for program-lifetime work data and RETAIN only when repeated reads are needed.
7. Treat EXIT routines as a controlled interface with documented linkage and return behavior.

Official references

• IBM Migration Utility: COPY statement
• IBM Migration Utility: Non-MODIFY file exits
• IBM Migration Utility: Defining VSAM files and EXIT restrictions
• Broadcom: Easytrieve Plus VFM files
• Broadcom: COPY, qualification, and ambiguous fields
• Broadcom: Resolving B049 on a FILE statement
• Broadcom: B055 and FILE length checks

Frequently asked questions

What belongs in the Easytrieve Library section?

The Library section contains FILE declarations, file-associated record fields, and working-storage definitions used by later JOB or SORT activities. It follows optional PARM settings and precedes the Activity section.

Does an Easytrieve VIRTUAL file need a JCL DD statement?

No. VFM creates a VIRTUAL work file for the program, so it does not need a matching JCL DD statement. A spill data set may still be used internally when the configured VFM memory is exhausted.

Why does COPY create ambiguous Easytrieve field names?

COPY duplicates another file's field definitions. When both files participate in the same activity, qualify a duplicated name with its file, such as FILEA:ACCOUNT and FILEB:ACCOUNT, to avoid ambiguity errors.

What causes Easytrieve B049 on a FILE statement?

A common cause is coding two numeric values with record format F. If block size is supplied as the second value, use FB when that matches the real data set attributes, and verify the declaration against the JCL or catalog DCB.

Working rule: when a file fails, compare the Library declaration, field endpoints, JCL DD, and catalog attributes before changing the JOB logic.

Easytrieve Program Structure: Environment, Library, Activity

PARM, FILE, and JOB do not belong in interchangeable positions. An Easytrieve source member follows a defined order: optional Environment settings, Library declarations, and then one or more processing activities.

Easytrieve reads program-wide settings first, data declarations second, and executable activities last.

Easytrieve program structure at a glance

The Easytrieve program structure has three sections. Environment is optional. Library is technically optional but appears in most file-processing and reporting programs. Activity is required because it contains the work the program performs.

Section	Typical statements	Purpose
Environment	PARM	Changes compiler or runtime options for this program.
Library	FILE, field declarations, DEFINE	Describes input, output, record layouts, and working fields.
Activity	JOB, SORT, executable statements, procedures, REPORT	Reads and processes data, writes files, sorts records, and produces reports.

Source order matters: a field must be declared before activity logic can reference it, and a procedure or report definition must remain inside the region where Easytrieve expects it.

The Easytrieve Plus tutorial owns the general introduction, execution JCL, and first report. This page concentrates on source layout and statement placement.

Canonical statement order

A batch report normally follows this outline. Bracketed lines are optional; they show placement rather than literal Easytrieve syntax.

[PARM ...] * Environment FILE input-file ... * Library field definitions ... DEFINE work-fields ... JOB INPUT input-file * Activity executable statements ... [job procedures ...] [REPORT definitions ...] [report procedures ...] [SORT activity ...]

One source member can contain multiple JOB and SORT activities. They share the declarations that precede them, but each activity has its own input choice, statements, procedures, and optional reports.

Environment section: optional PARM settings

The Environment section begins with a PARM statement and must come first when used. PARM changes options for the source member, such as listing, debugging, linking, work-space, or interface behavior supported by the installed release.

PARM LIST (PARM FILE)

This example requests listing information on systems that support those operands. Option names and defaults can be controlled by the site's Easytrieve release and option table, so copy the PARM syntax from the documentation and procedures installed at the shop.

Do not copy the old typo: the keyword is PARM, not PRAM. A PARM statement placed after FILE or JOB is also in the wrong section.

Library section: files, fields, and working storage

The Library section is the program's data-definition area. A FILE statement names an input or output file and supplies file attributes. Field declarations map bytes in that record. DEFINE statements create working-storage fields or define fields independently from a file layout.

FILE PERSNL FB(150 1800) EMP-NO 9 5 N EMP-NAME 17 20 A GROSS 94 4 P 2 DEPT 98 3 N DEFINE WS-SELECTED W 6 N 0

EMP-NAME begins at position 17 and occupies 20 alphanumeric bytes. GROSS is a four-byte packed field with two decimal positions. The Easytrieve field-definition guide explains position, length, type, decimals, headings, and masks.

The FILE name normally maps to a JCL DD name on z/OS. If the source says FILE PERSNL, the execution step usually needs a PERSNL DD unless the site uses another mapping rule. For keyed data, the Easytrieve VSAM guide covers file definition, status handling, and I/O statements.

Activity section: JOB and SORT

The Activity section contains executable processing. A JOB activity can read files, test and change data, write output files, and initiate reports. A SORT activity creates an ordered output file from sequentially processable input.

JOB INPUT PERSNL NAME DEPT-REPORT IF DEPT = 911 WS-SELECTED = WS-SELECTED + 1 PRINT PAY-RPT END-IF

With automatic input, Easytrieve handles the ordinary open, read, end-of-file, and close cycle. The statements below JOB run for each available record. The Easytrieve JOB statement guide covers automatic input, INPUT NULL, activity names, STOP, and FINISH. Condition syntax belongs to the Easytrieve IF and ELSE guide.

Where procedures belong

A procedure begins with a named PROC statement and ends with END-PROC. JOB procedures are coded after the JOB's executable statements and before its report subactivities. Report procedures belong with the report they serve.

JOB INPUT PERSNL NAME DEPT-REPORT IF DEPT = 911 PERFORM COUNT-ROW PRINT PAY-RPT END-IF COUNT-ROW. PROC WS-SELECTED = WS-SELECTED + 1 END-PROC REPORT PAY-RPT LINESIZE 80 TITLE 1 'DEPARTMENT 911 PERSONNEL' LINE 1 EMP-NAME EMP-NO GROSS

Broadcom documents error EZTC0168E when a label is coded after Easytrieve's implied return to JOB and therefore sits in an invalid location. Keep procedures and labels inside the valid activity region; add an explicit GO TO JOB only when the program's intended control flow requires it.

REPORT is part of the Activity section

REPORT PAY-RPT begins a report subactivity. It follows the JOB statements and any JOB procedures that feed it. TITLE, LINE, SEQUENCE, CONTROL, and report-specific procedures describe how records selected by PRINT are formatted.

Do not repeat JOB INPUT on a REPORT line. The old version of this post blended JOB and REPORT syntax into a duplicate line, which obscured the actual boundary between processing logic and report definition.

For detailed report syntax, use the Easytrieve basic reporting guide. The reporting page owns TITLE, LINE, headings, and output layout; this page owns where the REPORT block sits in the source member.

Complete annotated program skeleton

This small program reads PERSNL, selects department 911, and formats one report. It omits Environment settings because none are required for the example.

* ---------- LIBRARY SECTION ---------- FILE PERSNL FB(150 1800) EMP-NO 9 5 N EMP-NAME 17 20 A GROSS 94 4 P 2 DEPT 98 3 N DEFINE WS-SELECTED W 6 N 0 * ---------- ACTIVITY SECTION --------- JOB INPUT PERSNL NAME DEPT-REPORT IF DEPT = 911 WS-SELECTED = WS-SELECTED + 1 PRINT PAY-RPT END-IF REPORT PAY-RPT LINESIZE 80 TITLE 1 'DEPARTMENT 911 PERSONNEL' LINE 1 EMP-NAME EMP-NO GROSS

The Library section supplies every field referenced by the JOB and REPORT. PRINT transfers the selected detail data to PAY-RPT, and the REPORT declaratives determine its presentation. Compile this sample against the site's record layout before using it with production data.

How source sections map to execution

Source element	Compile-time role	Runtime effect
PARM	Selects supported program options.	Can affect listing, debugging, work files, linking, or interfaces.
FILE and fields	Build the data descriptions used to validate later references.	Connect source names to input, output, and record storage.
JOB INPUT PERSNL	Defines an activity and its input method.	Runs activity statements for the automatic-input record cycle.
PRINT PAY-RPT	Associates selected data with a named report.	Passes a report detail occurrence for later formatting.
REPORT PAY-RPT	Defines the report subactivity.	Formats titles, lines, control breaks, totals, and sequence as coded.

Report processing can use Easytrieve's Virtual File Manager when sequencing or multiple-report handling requires work storage. The execution JCL must provide the DD names and work resources required by the site's cataloged procedure.

Multiple activities in one source member

A program can contain more than one JOB or SORT activity. This allows one set of Library declarations to support several passes or outputs, but it also makes source boundaries more important.

• Give each JOB a meaningful NAME when diagnostics or references benefit from it.
• Keep each JOB's procedures and reports adjacent to that activity.
• Remember that STOP ends the current activity through normal termination processing, while STOP EXECUTE ends execution immediately and can prevent deferred reports from being produced.
• Define every output file in Library and supply its corresponding DD statement.

Broadcom examples show multiple JOB activities writing separate outputs in one program. The Easytrieve macros guide is useful when repeated definitions or statement patterns should be maintained once and invoked consistently.

Common structure and placement errors

Symptom	Likely structural cause	Check
PARM is rejected	It appears after Library or Activity source, or contains a typo or unsupported operand.	Place PARM first and check the installed reference.
Field name is undefined	The field is absent, misspelled, or declared after the activity that references it.	Move or correct the declaration in Library.
Label not defined	The label is outside the valid JOB region after an implied activity return.	Review procedure placement and control flow.
Report name is undefined	PRINT names a report that has no matching REPORT subactivity.	Match the names exactly and place REPORT after JOB logic.
Input file does not open	The FILE name and JCL DD name or attributes do not agree.	Compare source declarations with execution JCL and catalog data.
Deferred report is missing	STOP EXECUTE terminated before report processing completed.	Use STOP for normal activity termination when appropriate.

Official references

• IBM Migration Utility: Structure of Easytrieve programs
• IBM Migration Utility: Order of statements in an Easytrieve program
• Broadcom: EZTC0168E label placement
• Broadcom: Multiple output files and JOB activities
• Broadcom: STOP and STOP EXECUTE behavior

Frequently asked questions

What are the three sections of an Easytrieve program?

The sections are Environment, Library, and Activity, in that order. Environment holds optional PARM settings, Library describes files and fields, and Activity contains JOB or SORT processing plus related procedures and reports.

Is the Easytrieve Environment section required?

No. It is optional. If PARM settings are needed, the Environment section must appear before Library and Activity source.

Where is an Easytrieve REPORT definition coded?

A REPORT definition is a subactivity within the Activity section. For a JOB, code executable statements and job procedures before the associated REPORT definition and its report procedures.

Can one Easytrieve program contain multiple JOB activities?

Yes. A source member can contain multiple JOB and SORT activities. Each activity has its own input, processing logic, procedures, and optional report definitions, while sharing Library declarations.

Working rule: declare data before using it, then keep JOB statements, procedures, and REPORT definitions in their documented Activity-section order.