Easytrieve Appending Records

PUT Versus WRITE for Append

Activity Input and Output documentation lists PUT for sequential output and WRITE for indexed or relative maintenance. If your goal is a brand-new QSAM extract, PUT is the primary tool. If your goal is insert a master record when READ shows FILE-STATUS not found, WRITE ADD is correct.

PUT Statement Format

1
PUT output-file-name [FROM {input-file-name | input-record-name}] [STATUS]

FROM copies the current record from the named input file or record into the output buffer before write. When FROM names a file, output length follows output-file RECORD-LENGTH; if output is longer than input, excess bytes are not initialized—MOVE or clear fields explicitly. FROM does not refresh the output data area beyond the copied portion when lengths differ; beginners who omit MOVE FILL or SPACES see garbage in trailing columns. STATUS sets FILE-STATUS for the operation—use it on production append jobs.

Sequential CREATE and Append

1
2
3
4
5
6
7
8
9
10
11
12
FILE INFILE FB(100 500)
%INREC
FILE OUTFILE FB(100 500) CREATE
 
JOB INPUT INFILE NAME BUILD-EXTRACT
  IF SELECT-CODE = 'Y'
     PUT OUTFILE FROM INFILE STATUS
     IF OUTFILE:FILE-STATUS NE 0
        DISPLAY 'PUT FAILED'
        STOP
     END-IF
  END-IF

CREATE on OUTFILE tells Easytrieve you are building a new sequential dataset through PUT. JCL must allocate the DD with DISP appropriate for new or extend—Easytrieve does not replace JCL standards. Each successful PUT adds one record at the end of the output file during the JOB pass. Filter logic in JOB body controls which input rows append.

Simple Field-Level Append

1
2
3
4
5
6
7
FILE INFILE
FIELD 1 5 A
FILE OUTFILE FB(100 500)
FIELD 1 5 A
 
JOB INPUT INFILE NAME MYPROG
  PUT OUTFILE FROM INFILE

Broadcom sequential files example copies a five-byte field through matching FIELD definitions on input and output. Expand with full COPY or percent-record layouts when structures match. When output layout adds trailer fields, MOVE defaults into output working areas before PUT without FROM, or build output buffer fields explicitly.

Variable-Length Append

VB files require RECORD-LENGTH before each PUT. After JOB INPUT reads a variable record, input RECORD-LENGTH holds actual byte count. Copy to output before PUT:

1
2
3
4
5
6
FILE VIN VB(20 200)
FILE VOUT VB(20 200) CREATE
 
JOB INPUT VIN
  VOUT:RECORD-LENGTH = VIN:RECORD-LENGTH
  PUT VOUT FROM VIN STATUS

Failing to set output RECORD-LENGTH writes wrong physical record sizes—downstream readers misparse fields or abend. When transforming VB content, recompute RECORD-LENGTH from actual data length after edits, not from stale input value if fields shrank or grew.

WRITE ADD on Indexed Files

1
2
3
4
5
6
7
8
9
10
11
FILE TRANS
  EMP-NO  1  3 N
FILE PAYVS INDEXED UPDATE
  EMP-NO  1  3 N
 
JOB INPUT TRANS NAME UPDATE-PGM
  READ PAYVS KEY EMP-NO STATUS
  IF PAYVS:FILE-STATUS NE 0
     WRITE PAYVS ADD FROM TRANS STATUS
     GOTO JOB
  END-IF

When READ reports not found, WRITE ADD inserts a new master from transaction layout. UPDATE on FILE is mandatory. ADD is explicit; omitting ADD defaults to UPDATE which requires an existing current record. Always PERFORM or inline FILE-STATUS checks after WRITE—silent failures corrupt reconciliation.

VSAM ESDS Load (Append-Style)

Loading ESDS uses sequential FILE with CREATE, PUT from source, STATUS guard, STOP on failure. Broadcom shows reloading fixed-length ESDS by PUT from PERSNL through esds-filename. Second activity may reference same cluster with different FILE name and JCL pointing at same VSAM—pattern for sort then reload validation in one execution.

PUT Mass Insert on VSAM Indexed

PUT on INDEXED with UPDATE can exploit VSAM mass sequential insertion when adding consecutive records at the same insertion point—useful in bulk load scenarios documented in PUT statement chapter. Random scattered WRITE ADD remains correct for transactional one-off inserts during online/batch maintenance. Pick pattern based on load volume and key clustering operations approves.

JCL and Operational Append

Appending to an existing generation may need DISP=MOD on QSAM or IDCAMS REPRO in operations playbook—not always pure Easytrieve. GDG (+1) append is common: each run writes new generation via CREATE PUT while JCL catalogs relative generation. Document whether append means extend same dataset or add generation—Easytrieve PUT always emits records; catalog semantics are site JCL.

STATUS and Error Handling

PUT STATUS and WRITE STATUS populate FILE-STATUS. Test NE 0 branches with DISPLAY hex dump of source buffer in development, STOP or exception file in production. Without STATUS, Easytrieve may diagnostic on failure but your job might not log business context (employee number, record key) needed for support.

Common Append Mistakes

• Sequential append with WRITE ADD—wrong verb.
• Missing CREATE on new sequential OUTFILE.
• Missing UPDATE on indexed FILE before WRITE ADD or PUT mass insert.
• VB PUT without RECORD-LENGTH assignment.
• Assuming FROM initializes entire output record when input is shorter.
• No FILE-STATUS check after PUT in production.

Testing Append Jobs

1. Empty input—confirm zero-length output or no PUT as designed.
2. Compare input/output record counts after filtered append.
3. VB round-trip—read output back with JOB INPUT and DISPLAY lengths.
4. Simulate STATUS failure path—confirm STOP and message.
5. Indexed ADD—verify READ not-found branch inserts once only.

Explain It Like I'm Five

Appending is adding new lines to the bottom of a notebook. PUT is the pencil that writes the next line on a brand-new notebook page stack (CREATE). WRITE ADD is slipping a new card into a box of cards sorted by number when you discovered the number was missing. Variable-length pages need you to say how long the line is (RECORD-LENGTH) before you write, or the notebook rips (bad data). Always check the teacher's OK stamp (FILE-STATUS) after each write so you know the line really stuck.

Exercises

1. Write JOB that PUTs filtered records to CREATE OUTFILE with STATUS check.
2. Add VB RECORD-LENGTH copy before PUT between two VB files.
3. Sketch READ/WRITE ADD not-found branch for indexed master.
4. List when PUT is correct vs WRITE ADD in two sentences each.
5. Describe JCL vs Easytrieve responsibilities for GDG append.