SYSIN Control Statements

What Is SYSIN?

SYSIN is the DD name in your JCL that points to the source of control statements. It does not hold your data records—it holds the commands that tell DFSORT what to do with the data in SORTIN (or SORTIN01, SORTIN02, …). DFSORT reads SYSIN once at the beginning of the step, before it opens SORTIN or SORTOUT. It parses each line (or record) as control statement text. Anything that is not a valid control statement may be ignored or cause an error, depending on the content. After SYSIN is read, DFSORT knows the operation (SORT or MERGE), the keys, the filters (INCLUDE/OMIT), the reformatting (INREC, OUTREC), and the options. It then runs the input, sort/merge, and output phases using that information.

How to Supply SYSIN: In-Stream vs Dataset

In-stream data (DD * or DD DATA)

You can put the control statements directly in the JCL using in-stream data. You code //SYSIN DD * (or DD DATA). The next lines in the JCL are treated as the content of the SYSIN dataset until DFSORT (or the system) sees a line that contains only /*. So you type your control statements line by line, then a line with /* to stop. This is convenient for small jobs or examples. The statements are in the same member as your JCL, so there is no separate dataset to create or maintain.

1
2
3
4
5
//SYSIN    DD *
  SORT FIELDS=(1,20,CH,A)
  INCLUDE COND=(5,2,CH,EQ,C'NY')
  OUTREC FIELDS=(1,30,35,20)
/*

The space (or comma) after the // and the indentation of the control statements are for readability; DFSORT typically allows leading blanks. The /* must appear on a line by itself (or as the first token on the line, depending on the system) to end the in-stream data.

SYSIN as a cataloged dataset

Instead of in-stream data, you can point SYSIN to a cataloged dataset. For example, a sequential dataset or a member of a PDS:

1
//SYSIN   DD DSN=MY.PROCS(SORT1),DISP=SHR

The dataset (or member) must exist and contain the same kind of control statement text you would have put after DD *. One advantage is reuse: many jobs can reference the same member. Another is length: long or complex control statement sets are easier to maintain in a separate member. The dataset can be fixed- or variable-length; DFSORT reads record by record and parses each as control statement input.

When SYSIN Is Read and Parsed

DFSORT reads SYSIN at step initiation, before any data is read from SORTIN. The order of operations is roughly: (1) Step starts; (2) SYSIN is opened and read to end (or to /* for in-stream); (3) All control statements are parsed and validated; (4) SORTIN (or SORTIN01/02/…) and SORTOUT are opened; (5) Input phase runs (read, INREC, INCLUDE/OMIT); (6) Sort or merge phase; (7) Output phase (OUTREC, write). So by the time the first record is read from SORTIN, DFSORT has already processed the entire SYSIN. If there is a syntax error in a control statement, DFSORT may fail during this initial parse, before any data is processed.

Main Control Statement Types

The following are the main kinds of control statements you put in SYSIN. They are summarized here; each has its own tutorial page for full syntax and examples.

• SORT FIELDS= — Tells DFSORT to sort the input by the specified keys. You give position, length, format (CH, PD, BI, etc.), and direction (A ascending, D descending). Multiple keys can be specified. This is the primary statement for a SORT step.
• MERGE FIELDS= — Tells DFSORT to merge two or more pre-sorted inputs (SORTIN01, SORTIN02, …) by the same keys. Syntax is similar to SORT FIELDS. Use MERGE when you have multiple sorted streams to combine.
• INCLUDE — Keeps only records that satisfy the given condition. Records that do not match are dropped before the sort. Reduces the number of records that get sorted.
• OMIT — Drops records that satisfy the given condition. Records that match are removed; all others are kept. Opposite of INCLUDE. You use either INCLUDE or OMIT, not both (for the same purpose).
• INREC — Reformats each record before the sort/merge. You can reorder fields, shorten the record, add constants, convert dates, or build new keys. The result of INREC is what the sort phase sees.
• OUTREC — Reformats each record after the sort/merge, when writing to SORTOUT. You can reorder fields, add spaces, edit numbers, add sequence numbers, or use FINDREP. The result of OUTREC is what is written.
• OUTFIL — Writes additional or alternative outputs. You can split output to multiple datasets (FNAMES=), build reports, add headers/trailers, or apply different INCLUDE/OMIT or reformatting per output. Each OUTFIL can have its own build and filters.
• SUM — Collapses records with the same key (and optionally sums, min, or max numeric fields). Used for de-duplication or simple aggregation. Records must be in key order (so SUM runs after the sort/merge).
• OPTION — Various options: COPY (no sort), EQUALS/NOEQUALS, SKIPREC, STOPAFT, VLSHRT, SIZE, and others. Affects how the sort/merge and I/O behave.
• RECORD, DEBUG, ALTSEQ, MODS, JOINKEYS, REFORMAT — Additional statements for record type, debugging, alternate collating sequence, user exits, join operations, and join reformatting. See their dedicated pages.

Order and Continuation

Control statements can usually appear in a logical order. A typical sequence is: OPTION (if any); SORT FIELDS= or MERGE FIELDS=; INCLUDE or OMIT (if any); INREC (if any); SUM (if any); OUTREC (if any); OUTFIL (if any). Some statements can be in different orders; the documentation for each statement describes any restrictions. Long statements can often be continued by putting a comma at the end of a line and continuing on the next line. Blanks and case (uppercase/lowercase) for keywords are often flexible, but keywords and positional values must be correct.

If you use both INCLUDE and OMIT, only one is usually meaningful for a given record (e.g. INCLUDE keeps matches, OMIT drops matches). Using both in the same job can be confusing; prefer one or the other for clarity.

Comments and Invalid Lines

DFSORT allows comment lines in SYSIN. A line that starts with /* (or in some contexts // in column 1) may be treated as a comment. Blank lines are often ignored. Lines that do not look like any known control statement may be ignored or may cause a warning. To avoid errors, keep SYSIN to valid control statements and comments as documented for your DFSORT level.

Example: Full SYSIN for a Sort with Filter and Reformat

1
2
3
  SORT FIELDS=(10,20,CH,A,1,9,CH,A)
  INCLUDE COND=(30,1,CH,EQ,C'A')
  OUTREC FIELDS=(1,39,40,20, C'|')

This sorts by positions 10–29 (character, ascending) then by positions 1–9 (character, ascending). It keeps only records where position 30 is 'A'. The output record is built from positions 1–39, then 40–59, then a literal '|'. So SYSIN defines the whole operation in a few lines.

Explain It Like I'm Five

SYSIN is like a recipe card you give to DFSORT. The card says: "Sort the pile by the first 20 letters," "Throw away any card that doesn't have an A in spot 30," and "When you write the answer, only copy these parts of each card and add a line." DFSORT reads the recipe card once at the start, then follows it step by step. You can write the recipe on a piece of paper and hand it over (in-stream DD *) or point to a file where the recipe is stored (SYSIN as a dataset). Either way, the recipe is the control statements, and SYSIN is where DFSORT finds them.

Exercises

1. Write a SYSIN (in-stream) that sorts by positions 1–10 character ascending and has no INCLUDE, OMIT, INREC, or OUTREC.
2. What is the difference between supplying control statements with DD * versus a dataset name for SYSIN? When might you use each?
3. Name three control statements that affect the input phase and two that affect the output phase.
4. When in the step does DFSORT read SYSIN? Why must it be read before SORTIN?