With the release of 7.5 in Spring 2022, IBM added new opcodes to RPG that make it very easy to send and monitor for errors. At that time, they also provided PTFs to enable this support on 7.3 and 7.4.

The new opcodes are:

• SND-MSG = sends a program message (similar to the SNDPGMMSG command in CL)
• ON-EXCP = can be used with the MONITOR opcode to monitor for errors (similar to the MONMSG command in CL.)

The reason these are exciting is that they make it easier to send messages and do error handling than we’ve ever had before in RPG.  Previously, if you wanted to send a message, you would have to either call a system API such as QMHSNDPM, or call a CL program.  To monitor for messages, you would have to use the MONITOR opcode with ON-ERROR set to catch every possible error! This means that you’d handle all errors regardless of whether you expected them or not.

In it’s simplest form, the SND-MSG opcode sends an informational (*INFO) message to the current program.  You can use this to log extra information into the job log, or to send it to a message subfile.

For example:

Notice first how simple it is. It is just SND-MSG followed by a character string!  Next, notice that the message can be very long, which makes it much more useful than the DSPLY opcode, which is limited to only 52 characters.

SND-MSG defaults to sending messages to the current program call stack, however, the %TARGET built-in function can be used to direct it to other call stack entries if needed. This is especially useful for message subfiles, since they always read messages from a designated queue.

In the following example, I’m retrieving the program name from the program status data structure (PSDS) and using the %TARGET built-in function to send a message to that queue.

In the DDS for my display, I read the message subfile from the same queue (using the same variable) so that I know it’ll read the message I just wrote.

The preceding example sends an “impromptu” message rather than one from a message file.  However, with the %MSG built-in function, we can opt to use a message file instead.

The preceding example sends the IBM-supplied message CPF2105 from the QCPFMSG message file. This message is used to report when an object isn’t found, and contains fill-In fields for the object, library and object type. The resulting message in the job log (or a message subfile) reads as follows:

You can also use SND-MSG to send *ESCAPE messages by putting *ESCAPE after the SND-MSG opcode. Escape messages are error messages, and if not monitored for, they will halt your program.  Programmers who used the old halt indicators (H1, H2, H3, etc.) will find this is a better approach, because you can control the text of the message you send.

For example:

In this example, the program will halt immediately with the message ‘Fatal Error’ unless the calling program monitors for the message.  If you want your program to halt and end in error, this is the best way to do it, since it’s the way the operating system was meant to work!

Complementing this feature is the ON-EXCP opcode, which works together with the MONITOR opcode.  You can use this to monitor for specific error messages using their message id.  For example:

Naturally, ON-EXCP isn’t limited to errors that are sent with SND-MSG, it can be used to capture any exceptions sent to your program.  For example, if you call the IBM-supplied QCMDEXC API with the CHKOBJ command to check if a file exists, you may want to catch the error that the file wasn’t found.

It’s also possible to monitor for more than one message id by separating them with colons.

Alternately, you can use a separate ON-EXCP for each message you wish to monitor for, which is useful if you want to run different code for different errors.

As you can see, these new message-handling features are both powerful and easy to use.  The only thing that is lacking is that they only support the *INFO and *ESCAPE message types.  I hope IBM supports others such as *DIAG and *STATUS in the future, but this is a great start!

 

---

Scott Klement
Midrange Dynamics Development & Solutions Architect

Scott Klement is an IT professional with a passion for both programming and mentoring. He joined Midrange Dynamics at the beginning of October 2022. He formerly was the Director of Product Development and Support at Profound Logic and the IT Manager and Senior Programmer at Klement’s Sausage Co., Inc. Scott also serves on the Board of Directors of COMMON, where he represents the Education, Innovation, and Certification teams. He is an IBM Champion for Power Systems.

Subscribe to our newsletter and join us next month to see what is happening in Scott’s Corner. Add a great dad joke to your arsenal and gain an even better IT insight from this recognized industry expert as he continues his quest to educate and support the IBM i community.