Tracing Control Statements

How DFSORT Reads SYSIN

DFSORT reads the SYSIN dataset (or in-stream data) once at the start of the step. It treats each line as a fixed-format record: specific columns have specific meanings. Content that is part of a control statement must appear in the allowed area (typically columns 8–71 for the main content). A non-blank character in column 72 means "this statement continues on the next line"; the next line is then appended logically to the current one before parsing. So the parser sees a stream of logical lines, each of which may have been built from one or more physical lines. Understanding these rules is essential when you trace: if something is in the wrong column, the parser may treat it as a new statement, truncate a keyword, or signal "TEXT BEGINS IN WRONG COLUMN."

Column Rules for Control Statements

Different DFSORT products and JCL conventions use slightly different column layouts; the following is a common one. Columns 1–6 are often used for sequence numbers (and may be ignored by the sort). Column 7 is sometimes used as an indicator (e.g. for continuation in some systems). The main content of a statement goes in columns 8–71. Column 72 is the continuation column: if any character there is non-blank, the next physical line is treated as part of the same statement. So when you write a long SORT FIELDS= or OUTFIL BUILD=, you break the line before column 72 and put a character (e.g. a comma or X) in column 72 of the first line; the next line should then start in the proper area (e.g. column 16 or as required) so the parser recognizes it as continuation and not a new statement.

ICE000I: Your First Trace

The first message DFSORT prints is ICE000I. It includes the product and version and, importantly, the control statements as read from SYSIN. So the lines that appear after the header in ICE000I are exactly what the parser read—including any continuations as they were assembled. When you trace, open SYSOUT (or MSGDDN), find ICE000I, and compare those lines to the SYSIN you intended. If you used a PROC, the echoed lines are what the PROC (and any overrides) produced. If you concatenated datasets to SYSIN, the echo shows the combined content. So ICE000I answers: "What did this step actually use?" If the echo matches your expectations and the step still fails, the problem may be in the data or in a later phase; if the echo does not match, fix the SYSIN source or the PROC.

Using DEBUG for Deeper Tracing

ICE000I shows the raw lines; it does not show the internal parsed form (e.g. how SORT FIELDS was expanded into key positions and formats). When you need that level of detail, add the DEBUG control statement to SYSIN. DEBUG tells DFSORT to produce additional diagnostic output. The exact format and content depend on your product and version: you may see parsed control statements, field lists, or record counts at various stages. Run the job and look at the same SYSOUT (or MSGDDN) for the extra lines. Use DEBUG only while diagnosing; remove it for production to avoid extra output and overhead. The DEBUG statement tutorial has more on syntax and options.

Common Parsing Errors

ICE001A "TEXT BEGINS IN WRONG COLUMN" is one of the most common. It usually means the parser saw text where it did not expect it. Typical causes: (1) A continuation line that did not have a non-blank in column 72 on the previous line, so the next line was treated as a new statement and its first character was in the "wrong" column. (2) A new statement that started past the allowed start column (e.g. past column 16). (3) Leading spaces or tabs that pushed keyword text into an invalid column. Fix by ensuring continuation is in column 72 and that each new statement starts in the correct columns; use the ICE000I echo to see exactly what was read. Another common error is an invalid or misspelled keyword (e.g. SORT FEILDS= instead of SORT FIELDS=); the message may be something like "INVALID KEYWORD" and the echoed line in ICE000I will show the typo.

Continuation example

To continue a long statement, end the first line with a non-blank in column 72 (e.g. a comma or the letter C). The next line should start in the continuation area (e.g. column 16). Wrong: putting the continuation character in column 71 or 73, or starting the next line in column 1 with a keyword—the parser may treat it as a new statement and fail.

1
2
  SORT FIELDS=(1,20,CH,A,21,8,PD,D),EQUALS                    X
  OPTION COPY

Here, the X in column 72 (approximate) marks continuation; the next line continues the SORT FIELDS. If the X were in column 71, the parser might not recognize continuation and could issue ICE001A or misinterpret OPTION COPY.

Verifying What Was Parsed

After a failure, verify in this order: (1) Open the step SYSOUT and find ICE000I. (2) Compare the echoed statements to your SYSIN (or PROC output). (3) If they match and you still need more detail, add DEBUG and re-run; then look at the DEBUG output for parsed form or field interpretation. (4) If they do not match, fix the SYSIN source (dataset, PROC, or in-stream data) so that the correct statements are supplied. (5) Pay special attention to any line that shows a truncated keyword or an unexpected keyword—that often indicates a continuation or column error. Once the echoed statements are correct and the step still fails, the cause is likely in the data (e.g. wrong format or position) or in the logic (e.g. wrong key); use the debugging techniques and SYSOUT analysis tutorials to narrow it down.

Explain It Like I'm Five

The sort program reads your instructions from a piece of paper (SYSIN). It has a rule: if there's a mark in a special box at the end of a line (column 72), the next line is still part of the same instruction. When it starts, it says "here are the instructions I read"—that's ICE000I. So you can check: did it read the right instructions? If you need to see exactly how it understood each line, you turn on DEBUG and it prints more details. If it says "something is in the wrong box," you fix the line so the mark is in the right box (column 72) or so the next line starts in the right place.

Exercises

1. Run a sort step with a continued SORT FIELDS= line. In ICE000I, confirm that both lines appear as one logical statement. Move the continuation character to column 71 and re-run; what message do you get?
2. Intentionally misspell a keyword (e.g. INCLUDE as INCLD). Run the step and find the error message. Then look at ICE000I—does it show the misspelling?
3. Add DEBUG to a step that uses INREC and OUTFIL. In SYSOUT, locate the extra DEBUG output. What additional information does it provide beyond ICE000I?
4. Your step uses a PROC that supplies SYSIN. The step fails. Where do you look first to see what control statements were actually used, and why is that useful?