CL Command Reference - SNDPGMMSG

CL Command List > SNDPGMMSG Reference

Description:

The Send Program Message (SNDPGMMSG) command sends a message to a named message queue or to a call message queue. A call message queue can be the *EXT external message queue or a message queue associated with a call stack entry. Each time a program or procedure is called a new message queue is associated with its call stack entry. The message queue is identified by the name of its associated program or procedure.

A program can send a message to its own message queue or to a message queue that is associated with a different call stack entry.

This command can send both exception and non-exception messages.

Restrictions:

1. The SNDPGMMSG command allows a message of up to 512 characters to be sent. However, if the message is sent to the *EXT message queue of an interactive job, only 76 characters are shown on the Display Program Messages display. If the message is sent to a user¡¯s, work station¡¯s, or the system operator¡¯s message queue, the Display Message (DSPMSG) command allows all 512 characters to be displayed.

2. This command can only send inquiry messages (specified by MSGTYPE(*INQ)) to one message queue or to two nonprogram message queues if one of the queues is *HSTLOG.


Examples:

Example 1: Specifying Substitution Values

SNDPGMMSG MSGID(UIN0023) MSGF(INV) MSGDTA(¡¯50 100¡¯) TOPGMQ(*EXT)

This command sends the message identified as UIN0023, which is stored in message file INV, to the external message queue of the job (the Display Program Messages presents the message at a display station). The data, which contains two substitution values specified in the MSGDTA parameter, is sent with the message. This data can then be used as substitution values when the message is received, or it can be used as data to be dumped, depending on how the message UIN0023 is defined in the message file. Assuming that the variables &1 and &2 have been defined in the message file as character variables, each 3 characters long, and that the first-level message text of the message UIN0023 is: ¡¯Requested item decreased by &1; current balance &2.¡¯ The message text sent is: ¡¯Requested item decreased by 50; current balance 100.¡¯



Example 2: Sending an Inquiry Message

SNDPGMMSG MSG(¡¯Mount checks in printer before continuing¡¯)
MSGTYPE(*INQ) TOMSGQ(*SYSOPR)

This command sends an inquiry message to the system operator. The operator looks at the message that was sent by using the DSPMSG command and responds to the message directly on that display. A Receive Message (RCVMSG) command is used in the program to accept the operator¡¯s response.



Example 3: Sending an Escape Message

SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR) TOPGMQ(*PRV *) MSGTYPE(*ESCAPE)

This command is an example of how a message could be sent to the caller of a program or procedure to cause an abnormal end. The message USR0001 could indicate that an invalid code was passed (such as a nonnumeric code when numeric is required). Because the message being sent is an escape message, the program or procedure that is sending the message cannot be resumed. The values *PRV and * did not have to be coded on this command because they are the default values on the TOPGMQ parameter.



Example 4: Sending an Escape Message to an ILE Procedure

SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR) TOPGMQ(*SAME ACCOUNT_FINAL_TOTALS)
MSGTYPE(*ESCAPE)

This command sends a message to an ILE procedure. In this example, the call stack entry identifier is more than 10 characters. Since no qualifier is specified, the actual module name and bound program name associated with the procedure are not used in finding the procedure. The escape exception message is sent to the message queue associated with ACCOUNT_FINAL_TOTALS because *SAME is specified for Element 1.



Example 5: Sending an Escape Message using Qualifiers

SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR)
TOPGMQ(*PRV FIRST_QTR_SUMMARY SUMQTRS REPORTS)
MSGTYPE(*ESCAPE)

This command sends an escape exception message to the caller of the procedure FIRST_QTR_SYMMARY. The procedure is qualified by the module name SUMQTRS and the bound program name REPORTS. The escape exception message interrupts the sending program and the sending program is not resumed.



Example 6: Sending a Completion Message using a Partial Procedure Name

SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR)
TOPGMQ(*SAME ¡¯MANAGE_SALES>>>¡¯) MSGTYPE(*COMP)

This command sends a completion message to the most recent procedure whose name begins with MANAGE_SALES.