Easytrieve File Copy Utility Pattern

Minimal Copy Loop

1
2
3
4
5
6
7
8
9
10
11
12
13
14
FILE SOURCE-FILE SEQUENTIAL
FILE TARGET-FILE SEQUENTIAL
 
JOB
PERFORM INIT-COPY
 
JOB INPUT SOURCE-FILE
  ADD 1 TO READ-COUNT
  WRITE TARGET-FILE
  ADD 1 TO WRITE-COUNT
END-JOB
 
PERFORM TERM-COPY
STOP

INIT-COPY zeros counters. JOB INPUT reads each source record into buffer; WRITE copies entire buffer to TARGET-FILE. When SOURCE-FILE reaches EOF, loop ends. TERM-COPY DISPLAY READ-COUNT and WRITE-COUNT—they should match for full copy. No transformation—byte-preserving when record layouts identical and LRECL matches.

COPY-FILE PROC Framework

1
2
3
4
5
6
7
8
9
INIT-COPY. PROC
  MOVE ZERO TO READ-COUNT WRITE-COUNT SKIP-COUNT
END-PROC
 
TERM-COPY. PROC
  DISPLAY 'COPY READ' READ-COUNT
  DISPLAY 'COPY WRITE' WRITE-COUNT
  DISPLAY 'COPY SKIP' SKIP-COUNT
END-PROC

Wrap loop body in PERFORM COPY-RECORD for filtered variants. Parameterize by setting COPY-MODE flag in INIT—'F' full, 'S' subset, 'M' mask sensitive fields. One utility JOB cataloged in proclib; operators supply DD names via JCL without recompiling when file names are external DD mapping only.

Filtered Copy

1
2
3
4
5
6
7
8
9
JOB INPUT SOURCE-FILE
  ADD 1 TO READ-COUNT
  IF REGION EQ 'EAST'
     WRITE TARGET-FILE
     ADD 1 TO WRITE-COUNT
  ELSE
     ADD 1 TO SKIP-COUNT
  END-IF
END-JOB

Selection on any field—date range, status code, amount threshold. Complex filters PERFORM EVALUATE-COPY-RULE setting COPY-YES flag. SKIP-COUNT documents how many records were read but not written—operations reconcile READ = WRITE + SKIP. Multiple output files require IF branches with different WRITE targets or separate JOB passes per region.

Transform During Copy

Copy is not always identical WRITE. MOVE masked account to OUT-ACCT, reformat dates with MASK, COMPUTE tax column before WRITE to enriched output. Pattern: READ into input buffer, MOVE to output work area, transform, WRITE output layout FILE. Separate FILE definitions when output LRECL differs from input—define OUT-RECORD in Library with new field list.

1
2
3
4
5
6
7
8
9
JOB INPUT SOURCE-FILE
  ADD 1 TO READ-COUNT
  MOVE IN-ACCT TO WORK-ACCT
  PERFORM MASK-ACCOUNT
  MOVE WORK-ACCT TO OUT-ACCT
  MOVE IN-AMT  TO OUT-AMT
  WRITE TARGET-FILE
  ADD 1 TO WRITE-COUNT
END-JOB

JCL and DD Mapping

VSAM and Indexed Files

Sequential JOB INPUT works on QSAM and many ESDS sequential traversals. KSDS selective copy by key range uses START and READ NEXT in a PROC loop instead of JOB INPUT when documentation requires keyed positioning. Pure physical copy of entire KSDS often remains an IDCAMS or utility job; Easytrieve copy utility targets logical record extraction with business filters. Declare FILE type correctly—INDEXED with key fields when using keyed READ. Mismatch causes status errors HANDLE-ENV-ERROR should catch at INIT.

Validation During Copy

PERFORM VALIDATE-RECORD before WRITE; on failure PERFORM HANDLE-VALIDATION-ERROR writing ERROR-FILE instead of TARGET. COPY-utility-plus-validation is common for feeds from external partners—only clean records land in TARGET. OK-COUNT and ERR-COUNT supplement READ/WRITE/SKIP in TERM-COPY DISPLAY.

Header and Trailer Records

Files with batch headers: IF RECORD-TYPE = 'H' PERFORM WRITE-HEADER or skip copying header to target depending on spec. Trailer validation compares READ-COUNT to trailer count field—integrate with error-handling hard stop. Do not blindly WRITE header/trailer without business rules—downstream may expect different control record layout.

Performance

• Full copy of billions of rows: evaluate IEBGENER or DFSORT COPY; Easytrieve adds interpreter overhead.
• Buffering: adequate BLKSIZE in JCL reduces EXCPs.
• Avoid per-record DISPLAY; use TERM summary.
• Single pass: filter and transform together—do not copy to temp then filter in second job unless necessary.

Copy Versus SORT

SORT activity can copy implicitly with GIVING when no keys specified on some platforms—still use explicit copy utility when no sort keys needed for clarity. SORT when output must be ordered; copy utility when order preserved from source. Combined pattern: COPY to work file, SORT work file, REPORT—three activities one JOB.

Testing

1. Empty source: WRITE-COUNT zero, no abend.
2. Two-record source full copy: compare TARGET with ISPF SUPERCE or compare utility.
3. Filter test: SKIP-COUNT + WRITE-COUNT = READ-COUNT.
4. Mask transform: verify sensitive field masked in output only.
5. Missing DD: INIT or first READ fails with LOG-FATAL.

Common Mistakes

• WRITE after loop without checking last EOF buffer state.
• LRECL mismatch between SOURCE and TARGET.
• No SKIP-COUNT when filtering—operations cannot reconcile.
• Using Easytrieve for terabyte clone when utility is faster.
• Indexed FILE declared SEQUENTIAL—wrong access mode.

Explain It Like I'm Five

Copying a notebook means writing each page into a new notebook. The file copy utility is a photocopier instruction sheet: read one page, put it in the new book, count pages, skip coloring pages if you only want math pages. When done, tell the teacher how many pages you copied and how many you skipped.

Exercises

1. Write full copy JOB with INIT-COPY and TERM-COPY.
2. Add REGION filter with SKIP-COUNT.
3. Design output FILE with one additional computed field.
4. When would you choose IEBGENER over this pattern? List three criteria.
5. Sketch TERM-COPY DISPLAY lines for operations run book.