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.
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.
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-IFCOPY 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.
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 BALANCESee 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
- Place all Library declarations before the first JOB or SORT activity.
- Match each physical file name to its JCL DD name.
- Verify RECFM, LRECL, and any block size against allocation data.
- Confirm that field endpoints stay within the logical record.
- Qualify fields duplicated through COPY.
- Use VIRTUAL for program-lifetime work data and RETAIN only when repeated reads are needed.
- 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.
