IBM i Job Log and CPF Messages Reference

When an IBM i job fails, the explanation is usually in its job log. This page is a lookup for the developer who has a failed job or a message ID and needs to find the log, read the message, and decide what to monitor for. It covers the commands, the message types and prefixes, and the order in which to read the messages.

It is a reference, not a message catalogue. Message text changes with the release, so look up the exact text on your own system. For the design of message files and SNDPGMMSG, read IBM i Message Files and Exception Handling in CL.

Where the job log is

DSPJOBLOG shows the commands and messages of a job that is still active and whose job log has not been written. A job log written to a spooled file is a snapshot and does not change. IBM documents that at the end of a job the job log can be written to a spooled file named QPJOBLOG. Whether that happens depends on the job’s log output setting, so if there is no such file in the spooled files of the job, the log was not written there.

DSPJOBLOG
DSPJOBLOG JOB(123456/MYUSER/MYJOB) OUTPUT(*PRINT)
WRKJOB JOB(123456/MYUSER/MYJOB) OPTION(*JOBLOG)

JOB takes the job number, user and name. OUTPUT(*) shows the log on the display and OUTPUT(*PRINT) sends it to a spooled file. WRKJOB can show many other things about the job, such as *SPLF for its spooled files and *PGMSTK for its call stack.

Read a message

Every message has a seven-character ID, such as CPF9801. The first letters are the prefix, and they say which component sent the message. Work in this order:

1. Note the message ID.
2. Put the cursor on the message and press F1 for the cause and recovery text.
3. Press F9 from that display for the message details, which show the sending program and the instruction.
4. Look at the messages before it. IBM’s guidance on message analysis points out that a cascaded message is often the one you see first, and the cause is an earlier message.

Typical details to note are the message ID, the type, the severity, the sending program and the receiving program.

Look up a message with DSPMSGD

DSPMSGD shows a message description from a message file, without needing the job log.

DSPMSGD RANGE(CPF9801) MSGF(QSYS/QCPFMSG)
DSPMSGD RANGE(CPF9801 CPF9810) MSGF(QSYS/QCPFMSG)

Because MSGF defaults to QCPFMSG, an ID that lives in another message file needs that file named. The SQL messages are in QSQLMSG, and the message ID for an SQLCODE is built from it: the absolute value of -204 becomes SQL0204.

Message prefixes

The ID in the job log is the one to use. If DSPMSGD cannot find it, the message is in another file, so read the message details with F1 and F9.

Message types

The type tells you what the program that sent the message was doing, and which messages a monitor can see.

When a command fails, the usual pattern is one or more diagnostic messages that describe the detail, then an escape message that ends the command. In a job log, read the diagnostics above the escape message.

MONMSG and message IDs

In a CL program, MONMSG handles a message by ID. It can monitor escape, notify and status messages. Completion and diagnostic messages cannot be monitored.

CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)
MONMSG MSGID(CPF9801) EXEC(DO)
  /* the object was not found */
ENDDO

The documented escape messages of CHKOBJ include CPF9801 (object not found in the library), CPF9802 (not authorized to the object), CPF9810 (library not found) and CPF9815 (member not found). A MONMSG placed straight after a command applies to that command only. One placed at the start of the program applies to every command in it, and the command-level MONMSG wins when both match.

A message ID with zeros in the last two or all four positions is generic. CPF9800 matches the messages from CPF9801 to CPF9899, and CPF0000 matches every CPF message. Monitor a specific ID when you can, and a generic one only when you mean to catch every error of that kind.

For the full set of options, read CL Error Handling with MONMSG. In RPG, the equivalent is the monitor group, described in the RPGLE Control-Flow Opcodes Reference. An unhandled RPG error appears in the job log with an RNQ or RNX message ID.

What goes into the job log

How much a job log contains is set on the job, with CHGJOB or the job description.

If a log is missing the commands or help text you need, raise the logging level for the next run. Level 4 with *SECLVL gives the most detail. See Debugging on IBM i for the next step when the log is not enough.

Common mistakes

• Reading only the last message. The cause is often earlier in the log.
• Searching for a message in the wrong message file. DSPMSGD defaults to QCPFMSG.
• Using a generic MONMSG such as CPF0000 and hiding errors the program should stop on.
• Trying to monitor a diagnostic message. Monitor the escape message that follows it.
• Looking for the log of an ended job with DSPJOBLOG and not in its spooled files.
• Assuming the message text is the same on every release.

FAQ

What does CPF mean?

The CPF prefix marks messages from the IBM i operating system and its commands. The four characters after it identify the message.

How do I find the text of a message ID?

Press F1 on the message in the job log, or run DSPMSGD RANGE(id) MSGF(QSYS/QCPFMSG) and change the message file for IDs that are not in QCPFMSG.

Where is the job log of a job that ended?

When the log was written to a spooled file, it is in the spooled files of that job as QPJOBLOG. Use WRKSPLF or WRKJOB with OPTION(*SPLF).

Summary

• Use DSPJOBLOG or WRKJOB OPTION(*JOBLOG) for a job that is running, and the QPJOBLOG spooled file for one that ended.
• Read the messages from the earlier ones forward, and use F1 and F9 for the cause and the sender.
• DSPMSGD looks up a message in QCPFMSG by default, so name the file for other prefixes.
• MONMSG sees escape, notify and status messages, not diagnostic or completion messages. The design side is in IBM i Error Handling and Message Control Explained.