Easytrieve FILE Statement

Statement Format

1
2
3
4
5
6
7
8
9
10
11
12
13
FILE file-name [file-type] [device-type] [record-format] [other-options]
 
* Common sequential example:
FILE PERSNL FB(150 1800)
 
* Indexed VSAM with update:
FILE MASTER INDEXED UPDATE
 
* Printer:
FILE ERRPRINT PRINTER
 
* Legacy VS keyword (compatibility):
FILE VSFILE VS (PASSWORD 'SECRET' UPDATE)

Broadcom documents a large parameter set. You pick only what your file needs. File-name must be unique in the program. The first three characters of file-name must differ from the site work dataset prefix (often EZT) in the Site Options Table so Easytrieve work files do not collide with your names.

File-Name Rules

File-name is mandatory immediately after FILE. All I/O statements refer to this name—not to the DSNAME in JCL. Duplicate file-names cause compile errors. On Windows platform indexed files, names may use letters, numbers, dollar signs, and underscores and must begin with a letter; SQL statement text is not allowed as a file name. SYSNAME maps the logical file to an external identifier when the Easytrieve name and the operating-system name differ—useful when one program template drives multiple datasets.

File Types Compared

Omitting type defaults to sequential. Specifying SEQUENTIAL explicitly also makes FILE-STATUS available for that file. INDEXED versus RELATIVE changes which key or RRN verbs make sense later. SQL files restrict which other FILE options are valid: only UPDATE, DEFER, and CODE among the usual set. IDMS FILE does not define ordinary fields on the FILE line—fields follow RECORD or ELEMENT-RECORD. DLI needs relative PCB position or DBD name and optional relative occurrence when duplicate DBD names exist in the PSB.

CREATE Versus UPDATE

CREATE loads a new file. On mainframe VSAM, RESET with CREATE overwrites an existing dataset that has the REUSE attribute; without RESET (or without REUSE), OPEN can fail. In CICS, RESET causes an execution error. On non-mainframe platforms, RESET deletes or overwrites before create; without RESET, new records append. UPDATE permits updating the file. For SQL, UPDATE on FILE means all columns defined for the file can be updated; without it, only columns marked UPDATE update. UPDATE is required to DELETE from or INSERT to an SQL file, and you need matching DBMS authority. Automatic JOB INPUT on VSAM with UPDATE issues GET HOLD (except CICS) so you can update the automatic input file in batch environments.

PASSWORD and NOVERIFY

PASSWORD supplies a literal or a field containing the VSAM (or platform) password at open time. NOVERIFY ignores VSAM open error 116 (X'74')—previous job did not close cleanly, or another CPU holds the file. Broadcom warns that indiscriminate NOVERIFY can lose records; use only when operations policy accepts the risk after investigating the open failure.

Device Types

On MVS, omitting CARD, PUNCH, and PRINTER lets JCL decide the device. PRINTER files commonly receive DISPLAY and REPORT output; you cannot CLOSE printer files the same way as user data files. Extended printer and spool options (EXTENDED, SPOOL CLASS, NODE, USERID, TERMINAL) route output through JES or online terminals when your site configures them.

Record Format Codes

Record format tells Easytrieve fixed versus variable, blocked versus unblocked, and lengths:

• F — fixed unblocked; optional record-length.
• V — variable unblocked; optional record-length.
• U — undefined; length or FULLTRK style sizing as documented.
• FB — fixed blocked; FB(record-length [block-length|FULLTRK]).
• VB — variable blocked; same parenthetical pattern.
• VBS — variable blocked spanned; for long or spanned records.

Classic sample FILE PERSNL FB(150 1800) means each logical record is 150 bytes and the physical block is 1800 bytes (twelve records per block). Wrong LRECL versus JCL causes open or I/O failures. FULLTRK asks for a full-track block size when the platform supports it. WORKAREA can allocate a work area length for the file when your processing needs a buffer independent of the default. BUFNO sets buffer count for performance tuning on sequential I/O.

1
2
3
4
5
6
7
8
9
FILE PERSNL FB(150 1800)
EMP#     9  5 N
NAME-LAST 17 20 A
PAY-GROSS 94 4 P 2
 
FILE OUTFILE FB(80 800)
OUT-REC 1 80 A
 
FILE ERRPRINT PRINTER

Field definitions typically follow the FILE statement (or come from a copy macro such as %PERSNL). Positions are relative to the record layout Easytrieve maps for that file.

EXIT, DEFER, ASA, CODE

EXIT (program-name [USING (...)] [MODIFY]) calls a user program on each Easytrieve operation for the file. EXIT is invalid for VFM, SQL, DL/I, and IDMS. MODIFY lets Easytrieve still perform I/O while the exit inspects or changes the record after input or before output. DEFER delays open until first use when you need postponed allocation. ASA marks ASA control-character printer streams. CODE selects EBCDIC, ASCII, or a DBCS code name when the file encoding must be stated explicitly—critical on mixed-platform Easytrieve sites.

VIRTUAL and TABLE Files

VIRTUAL ([RETAIN] [MEMORY|DISK]) creates Easytrieve Virtual File Manager work files for intermediate results. Without RETAIN, CLOSE can delete the virtual file; with RETAIN, data may survive for later activities—see CLOSE and virtual-file tutorials. TABLE [INSTREAM | max-entries] marks a file as table data for SEARCH. INSTREAM embeds table rows in the program; a numeric max sizes an external table. Table format rules are strict; misuse causes SEARCH failures rather than ordinary sequential GET loops.

Legacy VS Keyword

For compatibility with older Easytrieve Plus programs, FILE still accepts VS with ES, F, PASSWORD, CREATE, RESET, UPDATE, and NOVERIFY-style options. New programs should prefer SEQUENTIAL, INDEXED, RELATIVE, and the modern CREATE/UPDATE keywords, but shops migrating old source will still see VS in production libraries.

FILE Versus JOB INPUT and GET

FILE only declares the file. JOB INPUT file-name makes Easytrieve automatically GET each record for the activity loop. JOB INPUT NULL disables automatic input so you issue GET yourself—required when the same file would otherwise be both automatic and manually read. Secondary files are often GET while the primary remains automatic input. SQL automatic input can use JOB INPUT SQL with a following SELECT instead of a named SQL FILE in some patterns—see the JOB statement page.

Testing FILE Declarations

1. Match FB/VB lengths to JCL LRECL and BLKSIZE on a small test dataset.
2. Open INDEXED UPDATE against a disposable VSAM copy; verify WRITE path.
3. Compile SQL FILE with and without UPDATE; confirm INSERT authorization errors are clear.
4. Create VIRTUAL work file, CLOSE without RETAIN, confirm deletion behavior.
5. Intentionally mismatch file-name and DD name; document the failure mode for your site.

Common FILE Mistakes

• Reusing the same file-name twice in one program.
• Omitting UPDATE then wondering why rewrite or SQL INSERT fails.
• Wrong FB length versus copybook or COBOL FD.
• Treating IDMS FILE like a flat record layout with fields on the FILE line.
• Using NOVERIFY to silence every VSAM open 116 without ops review.
• Expecting GET on a file that is already automatic JOB INPUT.
• Naming files with the site EZT work prefix collision.

Explain It Like I'm Five

FILE is the label on a toy box. You write the name of the box and what kind of toys fit inside— same-size blocks (FB), stretchy bags (VB), or a special locked cabinet (INDEXED). CREATE means you are filling a new box. UPDATE means you are allowed to change toys already inside. The rest of the program says take a toy out (GET) or put one back (PUT) using the box name you wrote on the label. If the label is wrong, you open the wrong box even if the shelf (JCL) has the right carton.

Exercises

1. Write FILE for an 80-byte FB file blocked at 800 with three fields.
2. Explain when to choose INDEXED instead of default sequential.
3. List which FILE options remain valid on an SQL file.
4. Describe CREATE RESET risk on VSAM without REUSE.
5. Design a PRINTER file and a VIRTUAL work file for a two-step JOB.