Part 1 investigated message queues and types of messages. Now we'll look at the CL commands that send messages.
Editor's note: This article is an excerpt from Chapter 16, "Advanced Message Handling," of Control Language Programming for IBM i. See Part 1 here.
Four major CL commands are used to send messages:
- SNDMSG (Send Message)
- SNDBRKMSG (Send Break Message)
- SNDPGMMSG (Send Program Message)
- SNDUSRMSG (Send User Message)
We discuss each of these commands individually.
The SNDMSG Command
The SNDMSG (Send Message) command sends immediate messages to one or more message queues. The term "immediate" refers to a message that is not predefined as a message in a message file. An immediate message is sometimes called an impromptu message. This command provides flexibility in specifying the message queue to which the message is sent and also lets you specify a message queue that will receive the reply to the message, if one is requested. The SNDMSG command takes the following form:
SNDMSG MSG(message-text) +
TOUSR(to-user-profile) +
TOMSGQ(message-queue-name) +
MSGTYPE(message-type) +
RPYMSGQ(message-queue-for-reply)
The MSG parameter lets you enter text for an impromptu message. The TOUSR and TOMSGQ parameters are mutually exclusive; you must specify one of the two, but not both.
The allowable values for the TOUSR parameter are *SYSOPR, *REQUESTER, *ALLACT, or a user profile name. If you specify *SYSOPR, the message is sent to the QSYSOPR message queue. If you specify *REQUESTER, the message is sent to the user message queue of the user running an interactive job or to QSYSOPR if the command is used in a batch job. To send the message to the message queue of all users currently signed on to the system, specify *ALLACT. If a user profile name is specified, the message is sent to the message queue specified in that user's user profile. If you do not enter the TOUSR parameter, you must specify the TOMSGQ parameter. The allowable values for TOMSGQ are *SYSOPR or the qualified names of up to 50 message queues. You can specify TOMSGQ(QHST) to send the message to the QHST message queue for inclusion in the system's history log.
The MSGTYPE parameter specifies the message as either an *INFO (informational) message or an *INQ (inquiry) message. If it is an *INQ message, you can specify only one message queue in the TOUSR or TOMSGQ parameter. The default value for the MSGTYPE parameter is *INFO. If the message is an *INQ message type, you can specify in the RPYMSGQ parameter the name of the message queue to which the reply to the message will be sent. The default value of the parameter is *WRKSTN; however, you can specify the name of any permanent message queue. When *WRKSTN is used, the reply is sent to the workstation message queue of the user running the interactive program; if the job is a batch job, the reply is sent to the QSYSOPR message queue.
The following command sends a message to all users currently signed on to the system:
SNDMSG MSG('The system will power down in 5 minutes') +
TOUSR(*ALLACT)
The next example sends an inquiry message; a reply will be sent to the workstation message queue of the user running the command interactively.
SNDMSG MSG('How about lunch today?') +
TOMSGQ(BOB) +
MSGTYPE(*INQ)
The SNDBRKMSG Command
The SNDBRKMSG (Send Break Message) command, although similar to the SNDMSG command, has a few notable differences. You can use this command to send immediate messages only to workstation message queues. When you use SNDBRKMSG to send a message, the message is displayed immediately at its destination workstation. If the workstation to which the message is sent is currently active, the user will be interrupted. The SNDBRKMSG command takes the following form:
SNDBRKMSG MSG(message-text) +
TOMSGQ(to-message-queue) +
MSGTYPE(message-type) +
RPYMSGQ(reply-message-queue)
The MSG parameter lets you enter text for an impromptu message. The TOMSGQ parameter can contain the names of up to 50 workstation message queues or the value *ALLWS. If *ALLWS is specified, the message is sent to all the workstation message queues defined on the system, whether or not they are currently active.
The MSGTYPE parameter can be specified as *INFO or *INQ. If you specify *INQ, you can name only one message queue on the TOMSGQ parameter. Also, if you specify *INQ, you can enter the name of the message queue that will receive the reply to the message in the RPYMSGQ parameter; the default for this parameter is to send the reply to the QSYSOPR message queue.
The SNDPGMMSG Command
The SNDPGMMSG (Send Program Message) command is quite flexible, but it can be used only within a CL program; it cannot be entered on a command line. You can use this command to send an immediate message or a predefined message from a CL program to any type of message queue on the system, including call stack entry message queues and the job's external message queue. The SNDPGMMSG command takes the following form for immediate messages:
SNDPGMMSG MSG(message-text) +
TOUSR(to-user-message-queue) +
TOMSGQ(to-message-queue) +
TOPGMQ(to-program-message-queue) +
MSGTYPE(message-type) +
RPYMSGQ(reply-message-queue) +
KEYVAR(key-variable-name)
For predefined messages, SNDPGMMSG takes this form:
SNDPGMMSG MSGID(message-identifier) +
MSGF(qualified-message-file-name) +
MSGDTA(message-substitution-data) +
TOUSR(to-user-message-queue) +
TOMSGQ(to-message-queue) +
TOPGMQ(to-program-message-queue) +
MSGTYPE(message-type) +
RPYMSGQ(reply-message-queue) +
KEYVAR(key-variable-name)
For immediate messages, you would specify the text in the MSG parameter. For predefined messages, use the MSGID, MSGF, and MSGDTA parameters. The MSG parameter cannot be specified if the MSGID, MSGF, or MSGDTA parameters are specified. Certain message types can be sent only using predefined messages; we talk about this restriction later when we discuss the MSGTYPE parameter.
When you send a predefined message, you specify the identifier of the message to be sent as well as the message file in which the message is defined. For example, to send the message CPF9871 from the QCPFMSG message file, you would specify
SNDPGMMSG MSGID(CPF9871) MSGF(QCPFMSG)
This command would send the message "Error occurred while processing."
Some messages let you specify message substitution data, using the MSGDTA parameter. CPF9898 is a special blank message provided by IBM; the text consists solely of whatever is in the message data. Consider the following example:
SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) +
MSGDTA('Cannot find tax rate file')
In this example, we send message CPF9898 with the data specified on the MSGDTA parameter.
You can specify either the TOUSR parameter or the TOMSGQ parameter on the SNDPGMMSG command, but not both. The allowable values for the TOUSR parameter are *SYSOPR, *REQUESTER, *ALLACT, or a user profile name. The rules for the TOUSR parameter are the same as those used on the SNDMSG command. The allowable values for the TOMSGQ parameter are *TOPGMQ (the default), *SYSOPR, or a list of up to 50 qualified message queue names. When *TOPGMQ is specified, the message is sent to the call message queue named on the TOPGMQ parameter.
The TOPGMQ parameter is used to specify the call stack message queue to which the message will be sent; by default, it directs messages to the calling program's (or procedure's) message queue. This parameter has two elements that can be specified. The first element specifies a relationship, and the second element specifies a program used for the relationship. (Because the TOPGMQ parameter can be confusing, the sidebar "The TOPGMQ Parameter" offers additional explanation.)
The MSGTYPE parameter lets you specify which message type is to be sent to the message queue. The allowable values are *INFO (the default), *INQ, *COMP, *DIAG, *NOTIFY, *ESCAPE, *RQS, and *STATUS.
You need to be aware of certain restrictions, depending on the type of message you are sending. An *INQ (inquiry) message cannot be sent to a call stack entry message queue. If an *INQ type message is sent, the reply can only be accessed using the RCVMSG (Receive Message) command. *COMP, *DIAG, *ESCAPE, *NOTIFY, and *STATUS messages can be sent only to a call message queue or to a job's *EXT (external) message queue. *ESCAPE, *NOTIFY, and *STATUS messages can be sent only if the message is predefined in a message file; the MSGID parameter must be specified.
The RPYMSGQ parameter lets you specify, for *INQ and *NOTIFY message types, which message queue will receive the reply to the message. This message queue may be any type of message queue except the *EXT job message queue. When an *INQ or *NOTIFY message is sent, the default for RPYMSGQ is *PGMQ. This means that the reply will be sent to the call message queue of the program sending the message. You can also specify the qualified name of a message queue.
The last parameter of the SNDPGMMSG command, KEYVAR, is used to retrieve the value of the message key and place that value into a CL program variable. Remember that each message queue uses a message key to keep track of messages within the queue. The message key is not a decimal number such as 1, 2, 3, or 4, but rather an internal number that the system generates when you send a message to a message queue. You specify the KEYVAR parameter as a CL variable: KEYVAR(&variable). You must declare the CL variable as follows:
DCL &variable *CHAR 4
You might want to retrieve the value of the generated message key so that later in a program you can selectively receive or remove a particular message. We describe this technique in more detail when we cover the RCVMSG and RMVMSG commands later in this chapter.
The following examples illustrate use of the SNDPGMMSG command.
To send a completion message to the previous program's message queue:
SNDPGMMSG MSG('Program successfully completed') +
MSGTYPE(*COMP)
To send an escape message to the previous program's message queue and cause the current program to end immediately:
SNDPGMMSG MSGID(CPF9898) +
MSGF(QCPFMSG) +
MSGDTA('Program ended abnormally') +
MSGTYPE(*ESCAPE)
To send a status message to the external message queue:
SNDPGMMSG MSGID(CPF9898) +
MSGF(QCPFMSG) +
MSGDTA('Now processing Step 1.') +
TOPGMQ(*EXT) +
MSGTYPE(*STATUS)
For an interactive job, the message sent by this command is shown on the message line of the workstation. The message does not appear in the job log.
To send an informational message to the call message queue used by program PGM1:
SNDPGMMSG MSG('Pgm3 working ok') +
TOPGMQ(*SAME PGM1) +
KEYVAR(&msgkey)
When this message is placed into the message queue, the message key assigned by the system is returned to the program and placed into the CL variable &msgkey, which is defined as *CHAR 4.
The SNDUSRMSG Command
The final command used to send messages is the SNDUSRMSG (Send User Message) command. Like SNDPGMMSG, this command can be used only within a CL program; it cannot be entered on a command line. You can use the SNDUSRMSG command to send an immediate message or a predefined message, but not to send a message to a call stack entry message queue. The SNDUSRMSG command includes useful features not available with other message commands. For example, you can both send a message and receive the reply to the message with this one command. You can check for the validity of a reply and optionally translate replies from lower case to upper case.
When sending impromptu messages, the SNDUSRMSG command uses the following format:
SNDUSRMSG MSG(message-text) +
TOUSR(to-user-message-queue) +
TOMSGQ(to-message-queue) +
MSGTYPE(message-type) +
VALUES(list-of-allowable-replies) +
DFT(default-reply-value) +
MSGRPY(message-reply) +
TRNTBL(translation-table)
When using predefined messages, the SNDUSRMSG command takes the following form:
SNDUSRMSG MSGID(message-identifier) +
MSGF(qualified-message-file-name) +
MSGDTA(message-substitution-data) +
TOUSR(to-user-message-queue) +
TOMSGQ(to-message-queue) +
MSGTYPE(message-type) +
VALUES(list-of-allowable-replies) +
DFT(default-reply-value) +
MSGRPY(message-reply) +
TRNTBL(translation-table)
The MSG, MSGID, MSGF, and MSGDTA parameters work the same for this command as they do for the SNDPGMMSG command.
You can specify either the TOUSR parameter or the TOMSGQ parameter, but not both. When you specify the TOUSR parameter, the allowable values are *SYSOPR, *REQUESTER, or the name of a user profile to which you want to send the message.
When you specify the TOMSGQ parameter, the allowable values are *, *SYSOPR, *EXT, or the qualified name of a message queue. If * is specified and the program is running interactively, the message is sent to the job's external message queue; if it is a batch job, the message is sent to the QSYSOPR message queue. If *SYSOPR is specified, the message is sent to the QSYSOPR message queue. If *EXT is specified, the message is sent to the job's external message queue. However, if the job is a batch job and the message is an *INQ message type, the default reply is always returned to the program.
The MSGTYPE parameter identifies the type of message that will be sent. The allowable values are *INFO and *INQ (the default). For *INQ messages, several other parameters are available: VALUES, DFT, MSGRPY, and TRNTBL. These additional parameters are used only with *INQ messages.
The VALUES parameter is used to specify the allowable values that can be used to reply to this message. You can specify up to 20 different valid replies. When sending an *INQ message to a user, you must enter an allowable value, or an error message is issued to the user and the message is resent automatically. When you specify the VALUES parameter, you must also specify the MSGRPY parameter.
The DFT parameter contains the default reply that will be used for this message. If, when a recipient is presented with an INQ message, he or she presses the Enter key, the DFT value is returned to the program. When you specify the DFT parameter, you must also specify the MSGRPY parameter.
The MSGRPY parameter identifies the variable to hold the message's reply. When a user is sent the *INQ message type and a reply is entered, the reply is returned to the program and placed into the CL variable specified on the MSGRPY parameter. If you wanted to store the message reply in a variable named &reply, for example, you would specify MSGRPY(&reply).
The TRNTBL parameter lets you specify that any reply value a user enters be translated before it is placed into the variable specified on the MSGRPY parameter. The default value of this parameter is *LIBL/QSYSTRNTBL. QSYSTRNTBL is a translation table used to translate lower case characters into upper case. You may specify the name of a different translation table or use *NONE for no translation.
Let's look at a couple of examples of using the SNDUSRMSG command. First, the following command sends an *INQ message to the QSYSOPR message queue and allows the values C and G to be entered in reply.
SNDUSRMSG MSG('Please load the IRS Tape #5 (C G)') +
TOUSR(*SYSOPR) +
VALUES(C G) +
DFT(C) +
MSGRPY(&reply)
C is the default reply value. The reply entered by the system operator will be placed into variable &reply, which in this case would be declared as *CHAR 1. After the program issues the SNDUSRMSG command, it waits until a reply is received before processing any further.
To send an informational message to an *EXT message queue (if running in an interactive job) or to the QSYSOPR message queue (if used in a batch job), you might use this command:
SNDUSRMSG MSGID(CPF9898) +
MSGF(QCPFMSG) +
MSGDTA(&message) +
TOMSGQ(*) +
MSGTYPE(*INFO)
The text of the message is in the &message variable. The external message queue is displayed on a workstation as the Program Messages display.
Jim is the president and founder of imPower Technologies, where he provides professional IBM i training and consulting services. He is active in the IBM i community, working to help companies train their employees in the latest IBM technologies and develop the next generation of IBM i professionals.
MC Press books written by Jim Buck available now on the MC Press Bookstore.
 |
||
 |
|
Control Language Programming for IBM i Master the A-Z of CL, including features such as structured programming, file processing enhancements, and ILE. List Price $79.95 Now On Sale
|
|
||
 |
|
Mastering IBM i Get the must-have guide to the tools and concepts needed to work with today's IBM i. List Price $85.95
Now On Sale
|
|
||
 |
|
Programming in ILE RPG Get the definitive guide to the RPG programming language. List Price $95.95
Now On Sale
|
|
||
 |
|
Programming in RPG IV Understand the essentials of business programming using RPG IV. List Price $79.95
Now On Sale
|
Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. 
LATEST COMMENTS
MC Press Online