Understanding DFSORT Messages

The ICE Message Prefix

DFSORT (and related IBM sort products) use the message prefix ICE. So every message from the sort step starts with ICE, then a three-digit number (e.g. 000, 001, 201), then a single letter that indicates severity. For example, ICE000I is an informational message, ICE201A might be a critical error. The number identifies the specific message; the letter tells you at a glance whether it is normal (I), a warning (W), or a severe error (A). When you see ICE in your job output, you know the message came from the DFSORT step, not from JCL or another program.

Severity Suffixes: I, W, A

In IBM mainframe message conventions, the last character of the message ID indicates severity. I means informational: the step is reporting status or completion (e.g. control statements listed, number of records read and written). These are normal. W means warning: something unexpected or potentially wrong occurred, but the step may have continued (e.g. a field overflow that was handled). You should review the condition. A means abend or critical: a severe error occurred and the program typically terminates. When you get an A-level message, the step fails and you must fix the cause before the job can succeed. Not every ICE message uses these exact letters; refer to the IBM Messages and Codes guide for the exact meaning of each ID.

Where Messages Appear

By default, DFSORT writes all of its messages to SYSOUT—the default output stream for the step. In JCL that is usually the step's SYSOUT DD or the job's default message class. So when you look at the job output (e.g. in SDSF, the JES spool, or your site's log viewer), you open the sort step's output and scroll to see the ICE messages. They typically appear at the beginning of the step (e.g. ICE000I with control statements and product version) and at the end (e.g. record counts and completion). If you want messages in a separate dataset, you can use OPTION MSGDDN=ddname and allocate a DD with that name; DFSORT will write messages there instead of the default SYSOUT. The amount of message output can be controlled with OPTION MSGPRT (e.g. suppress some informational messages); see the MSGPRT tutorial.

Looking Up a Message

IBM publishes the z/OS DFSORT Messages, Codes and Diagnosis Guide (often referenced by document number, e.g. icem100). In that manual, messages are listed by message ID (e.g. ICE000I, ICE001A). For each message you get: a short explanation of what the message means, the typical cause (e.g. control statement error, resource problem), what action the system took (e.g. terminate), and what the programmer should do (e.g. correct the continuation column, increase sort work space). Your installation may have this manual online (e.g. IBM Knowledge Center, PDF) or in a shared library. When you encounter an unfamiliar ICE message, note the full ID and message text and look it up in this guide to get the exact explanation and recommended action.

Common Message Patterns

At the start of a run you often see ICE000I (or similar): an informational message that echoes the control statements read from SYSIN and identifies the DFSORT product and version. That confirms the step started and which options were in effect. At the end you may see messages that report how many records were read, written, or dropped (e.g. by INCLUDE/OMIT or SUM). If there is a syntax error in SYSIN, you may get an A-level message pointing to the offending statement (e.g. wrong column, invalid keyword). If there is a resource or data problem (e.g. sort work full, open failure), the message usually describes the condition. Using these patterns helps you quickly tell success from failure and where to look in the manual for details.

Using Messages for Diagnosis

When a sort step fails, the first thing to do is read the ICE messages in the step's SYSOUT. The last message (or the first A-level message) usually indicates why the step ended. Note the message ID and the text. Look up the ID in the diagnosis guide and follow the programmer response. For example, if the message says text began in the wrong column, fix the continuation of your control statement. If the message says sort work space is insufficient, add more SORTWKnn datasets or increase their space. If the message references a specific control statement (e.g. REFORMAT), check that statement and the positions and formats you specified. Often the message text and the guide are enough to correct the problem without needing to search the whole codebase.

Explain It Like I'm Five

When the sort program runs, it talks to you by printing little notes. Each note has a name like ICE000I or ICE201A. The ICE part means "this note is from the sort program." The number is like a topic (000, 201, etc.). The last letter tells you if it's just saying "everything is fine" (I), "watch out for something" (W), or "something went wrong and I stopped" (A). You can look up each note in a big book (the IBM message guide) to see exactly what it means and what to do. So when your job fails, find the note that says something went wrong (the A note), look it up, and do what the book says.

Exercises

1. Your sort step failed. In SYSOUT you see ICE001A and the text "TEXT BEGINS IN WRONG COLUMN." What does the A mean, and what should you check first?
2. Where would you look to find the exact meaning and programmer response for ICE201W?
3. You want to keep a copy of all DFSORT messages in a separate dataset. What OPTION can you use and what JCL do you need?