| Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX) Threadsafe: Yes |
Parameters Examples Error messages |
The Remove Message (RMVMSG) command is used by a program to remove the specified message, or a group of messages, from the specified message queue. If an unanswered inquiry message is removed, the default reply is sent before it is removed. If the specified message queue is not allocated to the job in which this command is issued and no other job has the message queue allocated, it is implicitly allocated by this command for the duration of the command.
Restrictions:
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| PGMQ | Call stack entry message queue | Single values: *ALLINACT, *EXT Other values: Element list |
Optional |
| Element 1: Relationship | *SAME, *PRV | ||
| 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 | ||
| MSGQ | Message queue | Single values: *PGMQ Other values: Qualified object name |
Optional |
| Qualifier 1: Message queue | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| MSGKEY | Message key | Character value | Optional |
| CLEAR | Clear | *BYKEY, *ALL, *KEEPUNANS, *OLD, *NEW | Optional |
| RMVEXCP | Remove unhandled exception | *YES, *NO | Optional |
| RJTDFTRPY | Reject default reply | *NOALWRJT, *ALWRJT | Optional |
| Top |
Specifies the call message queue from which the messages are to be removed. Messages can be removed from the external queue (*EXT) or from a message queue associated with a call stack entry.
Notes:
Single values
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.
Note: If the message queue previous to the one identified by the second value is for an ILE program entry procedure (PEP), the message will be removed from the message queue immediately previous to the PEP message queue; effectively this would be two message queues previous to the one identified by the program or qualified 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
| Top |
Specifies the message queue from which one or more messages are to be removed. If this parameter is specified, the Call stack entry message queue (PGMQ) parameter cannot be specified.
Single values
Qualifier 1: Message queue
Qualifier 2: Library
| Top |
Specifies the name of the control language (CL) variable that contains the message reference key of the message to be removed. This parameter can be specified only if CLEAR(*BYKEY) is specified.
| Top |
Specifies whether one or more messages are to be removed from the queue.
| Top |
Specifies the action to be taken when an unhandled exception message is found. An unhandled exception message is an escape, notify, or status message that has been sent to an ILE procedure. When this command is run, the ILE procedure has not yet taken action to tell the system that the exception is handled. One action that the ILE procedure can take is to call a CL program that will remove the exception message. More information on actions that an ILE procedure can take to handle an exception is in the ILE Concepts book, SC41-5606.
This parameter is valid only when working with a message queue that is associated with a call stack entry for an ILE procedure. This parameter is ignored when working with a message queue associated with a call stack entry for an OPM (original program model) program.
| Top |
Removing an unanswered inquiry message causes the default reply to be sent to the inquiry message. This value indicates whether a reply handling exit program will be allowed to reject a default reply that is sent as a result of using this command. A reply handling exit program can be registered via the system registration facility for exit point QIBM_QMH_REPLY_INQ.
| Top |
Example 1: Removing a Message
RMVMSG MSGQ(SMITH) MSGKEY(&KEY)
This command removes the message with the reference key specified in the CL variable &KEY from the message queue named SMITH.
Example 2: Keeping Unanswered Messages
RMVMSG MSGQ(SMITH) CLEAR(*KEEPUNANS)
This command removes all messages except the unanswered inquiry messages from the message queue named SMITH.
Example 3: Removing Messages Using a Partial Procedure Name
RMVMSG PGMQ(*SAME 'PROCESS_ORDER>>>') CLEAR(*ALL)
This command removes all messages from the most recent procedure whose name begins with PROCESS_ORDER.
| Top |
*ESCAPE Messages
| Top |