Messages, QSYSOPR and the job log

On other systems you go looking for logs in a directory. Here messages end up in message queues: every job has one, every user has one, and the system has a few that concern everybody.

The advantage is that every message knows where it came from: which program, which job. The price is that you have to know which queue to look in.

The queues that matter

• QSYSOPR: the system operator's queue. It receives what the system wants whoever runs the machine to know.
• QSYSMSG: an optional queue for a specific list of serious messages. It does not exist until you create it in QSYS.
• The user's queue: one per profile, receiving messages addressed to that person.
• The job's queue: what the individual job's record, the job log, is built from.

DSPMSG MSGQ(QSYSOPR)
WRKMSGQ

QSYSMSG

When QSYSMSG exists and is not damaged, IBM sends certain serious messages there: some instead of QSYSOPR, some as well as QSYSOPR. One of the examples in the documentation is CPF0907, the serious storage condition. It is created like this, and from then on the system starts using it:

CRTMSGQ MSGQ(QSYS/QSYSMSG) TEXT('Serious system messages')

Messages waiting for a reply

Some messages are inquiry messages: the job that sent them stops until somebody replies. They show in DSPMSG and you reply on the line; the replies accepted are stated by the message itself.

Who replies when nobody is watching is decided by the job's INQMSGRPY attribute, set in the job description or with CHGJOB:

*SYSRPYL is the more controlled route, because it says which reply goes to which message and leaves every other one waiting. ADDRPYLE is shipped with public *EXCLUDE: QPGMR uses it, or whoever has been given *USE to the command.

ADDRPYLE SEQNBR(10) MSGID(RPG1241) RPY(G)
WRKRPYLE

It is the first example on IBM's page for the command: to every RPG1241 (record not found) sent by a job using the list, the system replies G without stopping. Message and reply have to be chosen for your own case, reading the message's second level.

The job log

Every job writes its own record. While the job is alive:

DSPJOBLOG JOB(123456/MROSSI/CHIUSURA)

In SQL, one row per message, there is QSYS2.JOBLOG_INFO. A job's first serious message:

SELECT MESSAGE_TIMESTAMP, MESSAGE_ID, SEVERITY, MESSAGE_TEXT, FROM_PROGRAM
  FROM TABLE(QSYS2.JOBLOG_INFO('123456/MROSSI/CHIUSURA'))
 WHERE SEVERITY >= 30
 ORDER BY ORDINAL_POSITION
 FETCH FIRST 1 ROW ONLY

ORDINAL_POSITION numbers the messages in the order they arrived. You need *JOBCTL special authority, or to be the job's user.

When the job has ended, the record becomes a spooled file, QPJOBLOG, in the job's output queue: that is why job logs are looked for in WRKSPLF. In SQL it is read by SYSTOOLS.SPOOLED_FILE_DATA, which IBM provides as an example built on CPYSPLF:

SELECT SPOOLED_DATA
  FROM TABLE(SYSTOOLS.SPOOLED_FILE_DATA(
       JOB_NAME          => '123456/MROSSI/CHIUSURA',
       SPOOLED_FILE_NAME => 'QPJOBLOG'))
 WHERE SPOOLED_DATA LIKE '%CPF%'

How much it writes, and when it writes nothing

The job description's LOG parameter has three parts: level (0-4), minimum severity, and text. The CRTJOBD default is LOG(4 0 *NOLIST).

That is why a job that ran fine often leaves no job log: it is not a fault, it is *NOLIST. If you always want one, put *SECLVL in the job description.

A second parameter, LOGOUTPUT, decides who produces the printout. Its value comes from the system value QLOGOUTPUT, which by default has the job produce it itself (*JOBEND); IBM recommends *JOBLOGSVR, the job log server. With *PND no printout is produced: the job log stays pending, can be seen with DSPJOBLOG and printed later with CHGJOB. IBM presents it as a way to save processor and storage on unneeded job logs.

Reading an error

Every message has a code, such as CPF9801 or MCH3601, and the code has a two-level explanation: the short text, and the second level giving cause and recovery. In DSPJOBLOG put the cursor on the line and press F1.

The first three letters say where it comes from. Some prefixes from the ADDMSGD documentation:

CPF, MCH, RNQ and SQL messages have a page per code under Errors.

Sources

• IBM: QSYSMSG message queue
• IBM: Creating message queue QSYSMSG for severe messages
• IBM: Create Job Description (CRTJOBD)
• IBM: Add Reply List Entry (ADDRPYLE)
• IBM: JOBLOG_INFO table function
• IBM: SPOOLED_FILE_DATA table function
• IBM: Produce printer output for job log (QLOGOUTPUT)
• IBM: Add Message Description (ADDMSGD)