Effective Messaging, IBM’s Way
June 16, 2004 Hey, Ted
There is a major problem with using global Monitor Message (MONMSG) commands. If no one reads the job logs, the problem goes unnoticed and will not get fixed. Let me give you an example.
We had a standard date-handling program that had a global monitor message. During Y2K conversion, I removed the global MONMSG command, because I don’t believe in them. Guess what? We found a bug in this program that had gone unnoticed for years! Luckily there was no damage, because the buggy code was rarely executed.
My opinion of global monitor messages is that you should not use them unless you are going to do something with them when an error occurs, such as sending a message to QSYSOPR or to the user, retrying the command or program, or creating an error report.
–Vincent
I received several replies to the “Proper CL Error-Handling” tip, to which Vincent refers. Even though most of them offered their support of the importance of global MONMSG commands, some of their remarks reinforced what I have noticed when working in various shops: that many AS/400 programmers do not understand what messages are all about or how to use them. Today’s as good a day as any to revisit the topic.
Imagine that you’re running a Copy File (CPYF) command, when suddenly you see the Display Program Messages panel.The text reads, “Job 994858/SOMEUSER/SOMETUBE started on 06/16/04 at 15:35:56 in subsystem QINTER. CPF1234 received by QXYZ at 2500. (C D I R).” What would you do? The program that raised the error is IBM’s. You don’t have any source code. Even if you did, you couldn’t fix the problem. In other words, you’re in the same boat that the users are in when one of your programs comes across an unexpected error. If such an error occurred, would you be impressed? I don’t think so.
Watching the behavior of IBM’s programs is a good way to get an understanding of messaging. The fact that IBM’s programs rarely if ever present the Display Program Messages panel is a good indication that their programs include global message monitoring.
The problem with the date-handling program in Vincent’s shop was not that it included a global MONMSG, but that the program ignored it. To use this incident as evidence that global MONMSG commands are bad would be like arguing that smoke detectors are bad because one detected smoke from a fire, but the people who were present at the time ignored it, causing the building to burn down. The date-handling program should have taken some action, such as assuming a default behavior or sending an escape message to cancel the program.
Using the behavior of OS/400 as a guide, here are some principles that many shops would do well to implement.
As far as possible, prevent errors before they happen. It may seem impossible that a divisor could ever have a value of zero, but assuming that such will never happen has caused many a program to cancel. It’s better to check a divisor for zero before letting a divide operation take place. You can also use RPG’s MONITOR op code and CL’s MONMSG at the command level to catch expected errors.
All programs should include some sort of global message monitor to handle unexpected errors. In CL this is done with the global MONMSG command. In RPG, use the Program Status Subroutine (*PSSR) and the file exception/error subroutine, defined with the INFDS continuation keyword in the F-specs. You can find more information in the following articles:
Expected errors may be recoverable. If so, send an inquiry message and use the reply to control program continuation. Many OS/400 commands use this technique. For example, SAVOBJ sends inquiry message CPA4067 if you attempt to save to a save file that contains data. The following example sends an inquiry message, receives the reply, and tests the reply.
DCL VAR(&REPLY) TYPE(*CHAR) LEN(1)
SNDPGMMSG MSGID(CPF9897) MSGF(QCPFMSG) +
MSGDTA('File XYZ is not empty; enter G to continue, +
C to cancel.') TOPGMQ(*EXT) MSGTYPE(*INQ)
RCVMSG MSGTYPE(*RPY) MSG(&REPLY)
IF COND(&REPLY *EQ 'G' *OR &REPLY *EQ 'g') +
THEN(DO)
It’s imperative to let someone know when something goes wrong, but it’s also good to let the user know when things are copacetic. Send status messages during long running processes. Status messages pop up on the bottom of the display and report on the progress of an operation.
SNDPGMMSG MSGID(CPF9897) MSGF(QCPFMSG) +
MSGDTA('Step 1 in progress...') +
TOPGMQ(*EXT) +
MSGTYPE(*STATUS)
... omitted code
SNDPGMMSG MSGID(CPF9897) MSGF(QCPFMSG) +
MSGDTA('Step 2 in progress...') +
TOPGMQ(*EXT) +
MSGTYPE(*STATUS)
It can also be helpful to send a completion message to let the user know when a program completes normally. After all, don’t you feel reassured when you issue a Submit Job (SBMJOB) command and the system tells you that the command was submitted to batch?
SNDPGMMSG MSG('Payroll posting completed normally.') +
MSGTYPE(*COMP)
Messaging is an important part of OS/400, and it’s a shame that so many iSeries programmers don’t understand it.
Vincent also included a list of other standards that his shop uses. He had some good ideas, so I’ve presented them in another tip in this issue of Guru.
–Ted
