IBM Releases Updates to RPG’s SND-MSG Opcode
Deep Thought
Well-informed people know it is impossible to transmit the voice over wires and that, were it possible to do so, the thing would be of no practical value.
— Excerpt from an 1865 Boston Post editorial.
IBM Releases Updates to RPG’s SND-MSG Opcode
Every Spring and Fall IBM adds new features to RPG, and for Spring 2024, the new features include adding support for fields (aka variables) that can’t be changed, as well as extended support for sending program messages with the SND-MSG opcode. In this blog post, we’ll take a look at the latter.
Extended Support for SND-MSG
When the SND-MSG opcode was added to RPG in Spring 2022, it only supported two message types (*INFO and *ESCAPE) and two targets (*SELF and *CALLER). This has been greatly enhanced in Spring 2024, and it now provides most of the support that you’ll find in the system API for sending messages.
The options for message type are now:
- *INFO – (default) place an informational message on the call message queue (and the job log). (Released Spring 2022.)
- *ESCAPE – place a failure message on the call message queue and end the current routine. (typically used for fatal exceptions, released Spring 2022)
- *COMP – completion message, typically used to give a message when the program completes successfully (Spring 2024)
- *DIAG – diagnostic message, typically precedes an *ESCAPE message with additional information about the fatal error. (Spring 2024)
- *NOTIFY – notify the calling program of a exception, and wait for its response. If it responds to continue, your program will continue, if not (or if it doesn’t handle the exception) the program will halt. This is an uncommon message type; I’ve only seen it used in C programs. (Spring 2024)
- *STATUS – Send the program’s current status to target message queue and continue. Typically used with a target of *EXT to print the current status at the bottom of an interactive (5250) terminal. (Spring 2024)
The options for the target (specified with the %TARGET builtin function) are now:
- *SELF – (default) the current call-level message queue. (Spring 2022)
- *CALLER – the call-level message queue that called the current routine, typically used to notify the calling routine of an error. (Spring 2022)
- *CTLBDY – the ILE control boundary, which is the first call-stack entry in this activation group. In ILE exception handling model, you can only handle exceptions within the current activation group. (Spring 2024)
- *PGMBDY – the first call-stack entry in the current program or service program. Useful for causing the whole program to stop (regardless of which subprocedure you are in within the program) and sending an error the program’s caller. (Spring 2024)
- *EXT – The “external message queue”. This is typically the command-line in an interactive session, so if you want to send a message and be sure it appears on the 5250 display, you can send it to *EXT. Most commonly this is used with *STATUS messages to print the program’s current status at the bottom of the display. (Spring 2024)
Note: None of these options are exactly “new”, since CL’s SNDPGMMSG and the system API (QMHSNDPM) have had these since the start. But the ones marked with Spring 2024 are new to the RPG SND-MSG opcode.
SND-MSG Example
In this example, the program wants to update a customer’s balance, but it’s possible that another job has the record locked. So it uses a *STATUS message to notify the interactive user that the record is locked, and tries again. When the record is available, it’ll make the update and send a completion message letting the calling program (or the user if called from the command-line) know that the balance was updated.
**free
ctl-opt dftactgrp(*no);
dcl-f custfile disk keyed usage(*input: *update) usropn;
dcl-s custno packed(5: 0) inz(495);
dcl-s invtot packed(9: 2) inz(100.00);
dcl-pr QCMDEXC extpgm;
command char(32702) const options(*varsize);
cmdlen packed(15: 5) const;
igc char(3) const options(*nopass);
end-pr;
QCMDEXC(‘OVRDBF FILE(CUSTFILE) WAITRCD(1)’: 32);
open custfile;
chain(e) custno custfile;
dow %error = *on;
snd-msg *status ‘Customer ‘ + %char(custno) + ‘ is locked…’
%target(*ext);
chain(e) custno custfile;
enddo;
Balance += INVTOT;
update custfilef;
snd-msg *comp ‘Customer ‘ + %char(custno) + ‘ balance updated.’
%target(*pgmbdy: 1);
close *all;
QCMDEXC(‘DLTOVR FILE(CUSTFILE)’: 21);
*inlr = *on;
How Do I Get These Features?
These new features were released alongside the technology refreshes for the operating system and are available via PTF for IBM i 7.4 and 7.5. You can find the PTF numbers here: https://ibm.biz/rpg_cafe