RMVMSG (Remove Message)

RMVMSG Command syntax diagram

 

Purpose

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 the specified message queue is not allocated to the job in which this command is issued, or to any other job, it is allocated by this command for the duration of the command.

 

Restrictions

1. This command is valid only in a compiled CL program.
2. To remove a message from the message queue, the user must have *CHANGE authority for the queue and *USE authority for the library in which the queue is stored.

 

Optional Parameters

PGMQ

Specifies the call message queue from which the message is removed. Messages can be removed from the external queue (*EXT) or from a message queue associated with a call stack entry.

Note:

If CLEAR(*BYKEY) is specified, the PGMQ parameter is ignored.

Element 1: Relationship

Element 1 of this parameter specifies whether the message queue is associated with the program or procedure identified by Element 2, or if it is associated with the caller of the program or procedure.

*PRV: The message is removed from the message queue of the program or procedure that called the program or procedure identified by Element 2.

Note:

If the message queue previous to the one identified by Element 2 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 Element 2).

*SAME: The message is removed from the message queue of the program or procedure identified by Element 2.

Element 2: Program or Qualified Procedure

Element 2 of this parameter has three items. Item 1 specifies the program or procedure of the job message queue. Items 2 and 3 specify the module name and the bound program name, which can be used to qualify the procedure name.

Item 1: Program or Procedure Name

*: Identifies the program or procedure running the RMVMSG command.

program-or-procedure-name: Specify the name of the program or procedure used.

If Item 1 identifies a program, the name specified can be a maximum of 10 characters. If Item 1 identifies a procedure, the name specified can be a maximum of 256 characters.

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.

Item 2: Module Name

The module name qualifier identifies the module into which the procedure was compiled.

*NONE: No module name is specified.

module-name: Specify the module name to be used as a qualifier for the specified procedure name (modules are associated only with procedures). The module name can be a maximum of 10 characters.

If a module name is not specified but a bound program name is, *NONE must be specified in the module name position.

Item 3: Bound Program Name

The bound program name qualifier identifies the program to which the procedure was bound.

*NONE: No bound program name is specified.

bound-program-name: Specify the bound program name to be used as a qualifier for the specified procedure name (and module name if specified). The bound program name can be a maximum of 10 characters.

Other Single Values

*ALLINACT: All messages for all inactive call stack entries are removed from the user's job message queue. If this value is specified for the PGMQ parameter, the value *ALL must be specified on the CLEAR parameter.

*EXT: The message is removed from the external message queue of the job.

MSGQ

Specifies the qualified name of the message queue from which one or more messages are removed. If MSGQ is specified, the PGMQ parameter cannot be specified.

*PGMQ: The call message queue specified in the PGMQ parameter is the only queue from which the messages are removed. If CLEAR(*KEEPUNANS) is specified, MSGQ(*PGMQ) cannot be specified.

The name of the message queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-queue-name: Specify the name of the message queue from which one or more messages are removed.

MSGKEY

Specifies the name of the CL variable that contains the message reference key of the message being removed. MSGKEY cannot be specified if *ALL, *KEEPUNANS, *OLD, or *NEW is specified for the CLEAR parameter.

CLEAR

Specifies whether one message, all messages (except unanswered inquiry messages), or only old or new messages in the specified message queue are removed from the queue.

*BYKEY: The message identified by the CL variable named in the MSGKEY parameter is removed from the message queue.

*ALL: All messages are removed from the specified message queue.

*KEEPUNANS: Messages other than unanswered inquiry messages are removed from the specified message queue. If CLEAR(*KEEPUNANS) is specified, MSGQ(*PGMQ) cannot be specified (a message-queue name must be specified for MSGQ).

*OLD: Old messages in the specified message queue are removed from the queue.

*NEW: New messages in the specified message queue are removed from the queue.

RMVEXCP

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 ILE Concepts book.

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 a program.

*YES: The unhandled exception message on the specified message queue is removed. As a result, the exception is handled.

*NO: The unhandled exception message on the specified message queue is not removed. The message remains on the queue as an unhandled exception message.

Examples for RMVMSG

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.

Error messages for RMVMSG

*ESCAPE Messages

CPF24A6

Value for messages to remove not valid.

CPF24AD

Messages to remove must be *ALL if program message queue is *ALLINACT.

CPF2401

Not authorized to library &1.

CPF2403

Message queue &1 in &2 not found.

CPF2407

Message file &1 in &2 not found.

CPF2408

Not authorized to message queue &1.

CPF241A

Clear option &1 in system program is not valid.

CPF2410

Message key not found in message queue &1.

CPF2411

Not authorized to message file &1 in &2.

CPF2419

Message identifier &1 not found in message file &2 in &3.

CPF2450

Work station message queue &1 not allocated to job.

CPF2451

Message queue &1 is allocated to another job.

CPF247A

Call stack entry not found.

CPF2477

Message queue &1 currently in use.

CPF2479

Call stack entry not found.

CPF2483

Message file currently in use.

CPF2499

Message identifier &1 not allowed.

CPF8127

&8 damage on message queue &4 in &9. VLIC log-&7.

CPF8176

Message queue for device description &4 damaged.

CPF9830

Cannot assign library &1.

CPF9838

User profile storage limit exceeded.