| Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX) Threadsafe: Yes |
Parameters Examples Error messages |
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. When an exception message is sent, processing of the sending program is interrupted until action is taken on the exception. Depending on the action taken, processing of the sending program may resume. If allowed to resume, processing continues in the sending program at the CL command immediately following the SNDPGMMSG command. When a non-exception message is sent, processing of the sending program is not interrupted. After the message is sent, the sending program continues to run at the CL command immediately following the SNDPGMMSG command.
When a program or procedure monitors for an exception message and an exception message is sent to the call stack entry in which that program or procedure is running, the related exception handler is called and run by the system. Therefore, a program or procedure can identify when an exception message is sent to the call stack entry in which it is running. There is no automatic notification for non-exception messages.
The message can be an immediate or a predefined message that is stored in a message file. Substitution data can be specified in the MSGDTA parameter (as a single character string containing one or more concatenated message data fields) to replace the substitution variables in the message. The message can be sent to the job's *EXT message queue, to a message queue associated with a call stack entry, to one or more nonprogram message queues (such as a user profile message queue), to the system operator message queue, or to the system history log, QHST.
Restrictions:
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| MSG | Message text, or | Character value | Optional, Positional 1 |
| MSGID | Message identifier | Name | Optional, Positional 2 |
| MSGF | Message file | Qualified object name | Optional, Positional 3 |
| Qualifier 1: Message file | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| MSGDTA | Message data field values | Character value, *NONE | Optional, Positional 4 |
| TOPGMQ | Call stack entry message queue | Single values: *EXT Other values: Element list |
Optional |
| Element 1: Relationship | *PRV, *SAME | ||
| Element 2: Call stack entry identifier | Element list | ||
| Element 1: Call stack entry | Character value, * | ||
| Element 2: Module | Name, *NONE | ||
| Element 3: Bound program | Name, *NONE | ||
| TOMSGQ | Send to non-pgm message queue | Single values: *TOPGMQ, *SYSOPR Other values (up to 50 repetitions): Qualified object name |
Optional |
| Qualifier 1: Send to non-pgm message queue | Name, *HSTLOG | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| TOUSR | To user profile | Name, *SYSOPR, *ALLACT, *REQUESTER | Optional |
| MSGTYPE | Message type | *INFO, *INQ, *RQS, *COMP, *DIAG, *NOTIFY, *ESCAPE, *STATUS | Optional |
| RPYMSGQ | Message queue to get reply | Single values: *PGMQ Other values: Qualified object name |
Optional |
| Qualifier 1: Message queue to get reply | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| KEYVAR | CL var for KEYVAR (4) | Character value | Optional |
| CCSID | Coded character set ID | 1-65535, *HEX, *JOB | Optional |
| Top |
Specifies the message text that is to be sent. A maximum of 3000 characters can be specified or, if you are prompting for this command in an interactive job, a maximum of 512 characters can be specified. The string must be enclosed in apostrophes if special characters (including blanks) are used. If this parameter is specified, a value cannot be specified for the Message identifier (MSGID) parameter, and *ESCAPE, *NOTIFY, or *STATUS cannot be specified for the Message type (MSGTYPE) parameter. If this parameter is specified, a value cannot be specified for the Message file (MSGF) parameter or the Message data field values (MSGDTA) parameter, because these types require that a message identifier also be specified.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for the MSG parameter is assumed to be in the CCSID of the job running this command unless a coded character set identifier is supplied in the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
| Top |
Specifies the message identifier of a message description whose predefined message is being sent by the program to a message queue. If this parameter is specified, a value cannot be specified for the Message text, or (MSG) parameter.
| Top |
Specifies the message file that contains the predefined message to be sent. This parameter is required if a value is specified for the Message identifier (MSGID) parameter.
Qualifier 1: Message file
Qualifier 2: Library
| Top |
Specifies the character string, or a CL variable that contains a character string, containing one or more substitution values that are used as message data fields within the predefined message. The substitution values take the place of the substitution variables that were defined in the message text when the message was defined.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for the MSGDTA parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID of the job running this command unless the coded character set identifier is supplied in the CCSID parameter. All other text supplied for the MSGDTA parameter is assumed to be 65535 and is not converted. For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/. For more information about the *CCHAR type fields, see the Add Message Description (ADDMSGD) command.
| Top |
Specifies the call message queue to which the specified message is to be sent. The message queue can be the *EXT external queue or the call message queue associated with a call stack entry.
Single values
Messages sent to this queue can be 512 characters in length, but only 76 characters of text are shown on the Program Messages display.
Element 1: Relationship
Two parameter elements are used to specify the call stack entry message queue from which a message is to be removed. The first element specifies whether the message queue is associated with the program or procedure identified by the second element, or if it is associated with the caller of the program or procedure.
Element 2: Call stack entry identifier
The second element of this parameter has three elements. Element 1 specifies an OPM program or ILE procedure name or a special value. Element 2 specifies an ILE module name which is used as a qualifier for the value specified in element 1. Element 3 can specify either an OPM program name or an ILE program name or a service program name, depending on what is specified in element 1. Element 3 is also used as a qualifier for what is specified in element 1.
Element 1: Call stack entry
If this element identifies an OPM program, the name specified can be a maximum of 10 characters. If this element identifies an ILE procedure, the name specified can be a maximum of 256 characters.
Nested procedure names can be specified by separating each procedure name with a colon (:). When specifying nested procedure names, the outermost procedure name is identified first, followed by its contained procedures. The innermost procedure name is identified last in the string.
Partial names of programs or procedures can be specified by placing three less-than symbols (<<<) at the beginning of the name or by placing three greater-than symbols (>>>) at the end of the name. If both the greater-than symbols and the less-than symbols are used, the program or procedure name specified is limited to 250 characters.
The system begins its search for the specified program or procedure name with the most recently called program or procedure.
When searching for a partial program or procedure name:
Element 2: Module
Element 3: Program
The procedure name alone may not identify the correct procedure. Several different procedures with the same name can run in a job. To further identify a procedure, the name specified can be qualified by a module name, or by both a module name and a bound program name. The following special values can be specified for the first qualifier of the second element of this parameter:
If it is an ILE program that is being specified, this special value identifies the call stack entry for the program entry procedure (PEP) of that program, if the program was called by a dynamic call. If the program was called by a procedure pointer, this special value identifies the call stack entry for the procedure that was pointed to. If it is an ILE service program that is being specified, this special value identifies the call stack entry for the first procedure that was called in that service program.
If the program being specified is an OPM program, this special value has the same effect as specifying the special value * or a program name for item 1. A difference will occur if the OPM program has called itself recursively. In this case, this special value identifies the first recursion level rather than the current recursion level as would be the case if the special value * or a program name was used.
This special value is used to send a message to the most recently called procedure that is part of the specified ILE program or service program. When using this special value, it is not necessary to explicitly provide a procedure name. If a module name is also provided, then this special value is used to send a message to the most recently called procedure that is both part of the identified program and the identified module.
This special value may also be used to send a message to an OPM program. In this case, using this special value and providing the OPM program name in item 3 has exactly the same effect as providing that program name here in item 1. Note that if this special value is being used to send to an OPM program then the module name must be specified as *NONE.
| Top |
Specifies up to 50 nonprogram message queues to which an informational message is sent. For an inquiry message, one message queue may be specified or two message queues may be specified if one of the queues is *HSTLOG. This parameter cannot be used if a value is specified for the To user profile (TOUSR) parameter.
Single values
Qualifier 1: Send to non-pgm message queue
Qualifier 2: Library
| Top |
Specifies that the message is to be sent to the message queue specified in the user profile for the user named on this parameter. This parameter cannot be used if a value is specified for the Send to non-pgm message queue (TOMSGQ) parameter or the Call stack entry message queue (TOPGMQ) parameter.
| Top |
Specifies which message type is assigned to this message when it is sent by this program.
Notes:
Note: This value cannot be specified if the Message text, or (MSG) parameter, is specified.
| Top |
Specifies, for inquiry and notify messages only, the call message queue or the non-program message queue to which the reply message is to be sent.
Single values
Qualifier 1: Message queue to get reply
Qualifier 2: Library
| Top |
Specifies the name of the CL character variable, if any, that contains the message reference key that identifies the message sent by the program containing this command. The message reference key is assigned by the system when the message is sent and is placed in the variable specified here.
If a message is being sent to a message queue associated with a call stack entry, KEYVAR refers to that message queue (specified for the Call stack entry message queue (TOPGMQ) parameter). If *INQ or *NOTIFY is specified for the Message type (MSGTYPE) parameter, KEYVAR refers to the message queue specified for the Message queue to get reply (RPYMSGQ) parameter. In all other cases, KEYVAR refers to the message queue specified for the TOPGMQ parameter.
Any type of message can be assigned a key when it is being sent to a program message queue. For messages sent to a nonprogram message queue, message reference keys are available for inquiry (*INQ) messages only. If another message type is sent to a nonprogram queue, no message key is available and blanks are returned for KEYVAR.
The variable must be a character variable having a length of 4 characters. If KEYVAR is not specified and a reply is required, it can be received by the program in FIFO order.
| Top |
Specifies the coded character set identifier (CCSID) that the supplied message or message data is in. If a message identifier is specified, the text supplied by the MSGDTA (message data) parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID specified by the CCSID parameter. The data supplied that does not correspond to the *CCHAR type field is assumed to be 65535 and is not converted. For more information about the *CCHAR type field see the Add Message Description (ADDMSGD) command.
If no message identifier is specified, the text supplied by the MSG (message) parameter is assumed to be in the CCSID supplied by the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
| Top |
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.
| Top |
*ESCAPE Messages
| Top |