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.