OUTFIL Statement

What OUTFIL Does

OUTFIL (Output File) runs in the output phase. After records have been sorted or merged (and optionally processed by SUM), DFSORT writes them to SORTOUT and to any datasets named in OUTFIL statements. Each OUTFIL defines one (or more, via FNAMES=) output stream. You can have several OUTFIL statements: for example, one that writes only records where department is DEPT1, another for DEPT2, and another with SAVE that receives all records not already written by the previous OUTFILs. So one sort step can produce multiple filtered or reformatted files without running the sort again.

OUTFIL does not change the order of records—that was determined by SORT or MERGE. It only controls where each record is written and how it is formatted for that particular output. Each OUTFIL is independent: different INCLUDE/OMIT, different BUILD, different DD name.

OUTFIL FNAMES=

FNAMES= specifies the DD name of the dataset(s) to which this OUTFIL will write. You must have a corresponding DD statement in your JCL. For example:

1
  OUTFIL FNAMES=OUT1,BUILD=(1,80)

This OUTFIL writes to the dataset allocated to DD name OUT1. Your JCL must include something like //OUT1 DD DSN=MY.OUTPUT.FILE1,DISP=(NEW,CATLG),.... You can give multiple names: FNAMES=OUT1,OUT2 writes the same record stream to both datasets. Typically each OUTFIL has its own FNAMES= so that different outputs go to different files (e.g. OUT1 for dept1, OUT2 for dept2).

OUTFIL INCLUDE= and OMIT=

Each OUTFIL can have INCLUDE=(condition) or OMIT=(condition). The condition uses the same syntax as the INCLUDE/OMIT control statements: (position,length,format,operator,value). Only records that satisfy the condition (for INCLUDE) or do not satisfy it (for OMIT) are written to that OUTFIL. So you can split one sorted stream into multiple files by value:

1
2
3
4
  SORT FIELDS=(1,10,CH,A)
  OUTFIL FNAMES=DEPT1,INCLUDE=(30,5,CH,EQ,C'DEPT1'),BUILD=(1,50)
  OUTFIL FNAMES=DEPT2,INCLUDE=(30,5,CH,EQ,C'DEPT2'),BUILD=(1,50)
  OUTFIL FNAMES=OTHER,SAVE,BUILD=(1,50)

Records with bytes 30–34 equal to DEPT1 go to DEPT1; records with DEPT2 go to DEPT2; all other records go to OTHER because of SAVE. BUILD=(1,50) shortens each output to 50 bytes. The positions in INCLUDE= refer to the record at output time (after INREC if used, and after sort).

OUTFIL BUILD=

BUILD= on OUTFIL specifies how to reformat the record for this OUTFIL output only. The syntax is the same as OUTREC FIELDS= or BUILD=: (position,length) to copy from the record, constants C'...', nX, nZ. So one OUTFIL can write a 20-byte summary while another writes the full 80-byte record. The record length written to that OUTFIL's dataset is the length of the built record; the DD for that file must have the correct LRECL.

SAVE: Capturing Unselected Records

SAVE on an OUTFIL means: write to this OUTFIL any record that has not been written by a previous OUTFIL in the same step. So you use SAVE when you have several OUTFILs with INCLUDE (or OMIT) and you want a "catch-all" file for records that did not match any of the earlier conditions. The OUTFIL with SAVE is usually coded last. Without SAVE, records that do not match any OUTFIL's INCLUDE/OMIT are not written to any OUTFIL (they may still go to SORTOUT if you have a primary SORTOUT).

SPLITBY: Splitting by Record Count

SPLITBY=n splits the output into multiple datasets by record count. You code multiple OUTFILs with the same or sequential FNAMES= and SPLITBY=n on the first. For example, the first 1000 records go to the first file, the next 1000 to the second, and so on. This is useful when you need to break a large output into fixed-size chunks (e.g. for transmission or for downstream limits). The exact syntax (e.g. one OUTFIL with SPLITBY=1000 and FNAMES=OUT1,OUT2,...) depends on your DFSORT version; see your product documentation.

OUTFIL vs SORTOUT

SORTOUT is the single primary output. If you do not use OUTFIL, all records go to SORTOUT (after OUTREC if specified). When you add OUTFIL:

• Records that match an OUTFIL are written to that OUTFIL's dataset(s). They can also go to SORTOUT unless you configure otherwise.
• You can use OUTFIL FNAMES=SORTOUT to redirect the main output through OUTFIL (e.g. to apply INCLUDE or BUILD only to the main output). In that case, the OUTFIL definition controls what goes to SORTOUT.
• Typically you use SORTOUT for the main sorted file and OUTFIL for additional files (splits, filtered copies, or reports).

Order of OUTFIL Processing

DFSORT evaluates each record against OUTFILs in the order they appear in SYSIN. The first OUTFIL whose INCLUDE/OMIT (if any) is satisfied can receive the record. If you use SAVE, the last OUTFIL with SAVE gets any record not yet written to a prior OUTFIL. So the order of OUTFIL statements matters when you have overlapping conditions or SAVE.

Report Options (Brief)

OUTFIL can generate reports with HEADER1, TRAILER1, SECTIONS, and related parameters—fixed header and trailer lines, control-break sections, and so on. Those are covered in the Report Generation and OUTFIL Advanced Output Control tutorials. For a first step, FNAMES=, INCLUDE/OMIT, BUILD=, and SAVE are enough to split and reformat output to multiple files.

Explain It Like I'm Five

Imagine you have one big sorted stack of cards and three boxes. OUTFIL is the rule for each box: "Box 1: only put cards that say DEPT1 here. Box 2: only put cards that say DEPT2 here. Box 3: put everything that's left here." So you go through the stack once and drop each card into the right box. You don't sort again—you just decide which box each card goes into. You can also say "when you put a card in box 1, only copy the first 50 characters onto a new slip"—that's BUILD= for that OUTFIL. So OUTFIL = multiple boxes (files) and rules (INCLUDE/OMIT/BUILD) for each box.

Exercises

1. Write two OUTFILs: one that writes records where byte 1 is 'A' to DD name FILEA, and one that writes records where byte 1 is 'B' to DD name FILEB. What happens to records where byte 1 is 'C'?
2. Add a third OUTFIL with SAVE that writes to DD name FILEREST. Now where do records with byte 1 = 'C' go?
3. You want one OUTFIL to write a 20-byte record (bytes 1–20 only) and another to write the full 80-byte record. Write the two OUTFIL statements with BUILD=.
4. Why would you use OUTFIL with INCLUDE instead of running two separate sort steps with INCLUDE?