| 1 | Call stack entry | Input | Char(*) or Pointer |
| 2 | Call stack counter | Input | Binary(4) |
| 3 | Message key | Input | Char(4) |
| 4 | Messages to remove | Input | Char(10) |
| 5 | Error code | I/O | Char(*) |
| 6 | Length of call stack entry | Input | Binary(4) |
| 7 | Call stack entry qualification | Input | Char(20) |
| 8 | Remove unhandled exceptions | Input | Char(10) |
| 9 | Call stack entry data type | Input | Char(10) |
| 10 | Allow default reply rejection | Input | Char(10) |
The Remove Program Messages (QMHRMVPM) API removes messages from call message queues and the external message queue. The removed instances of the messages are no longer available for you to work with. However, other instances of the messages might still exist in other message queues, and the definitions of predefined messages are still in the message files.
To remove messages from nonprogram message queues, see Remove Nonprogram Messages (QMHRMVM) API.
You can use the QMHRMVPM API to streamline program message handling. Assume that a program receives several diagnostic messages and an escape message from a called program. The program handles the escape message without receiving the diagnostic messages. The program could then use the QMHRMVPM API to remove all the new messages it has not received, including the unneeded diagnostic messages. This can prevent confusion if the program gets another escape message and must receive the diagnostic messages associated with the new escape to analyze the error.
In a multithreaded job messages can be removed from call message queues within the thread that calls this API, and messages sent from within the same thread can be removed from the external message queue. Messages on call message queues in other threads or sent to the external message queue from other threads cannot be removed.
None.
The call stack entry from whose message queue the message are to be removed, or the call stack entry to start counting from when using the call stack counter parameter. The call stack entry you specify must be in the call stack or you can specify the external message queue instead of a call stack entry.
You can specify a call stack entry by providing the name of the OPM program or ILE procedure running in the entry, by providing a pointer to the call stack entry, or by using one of the following special values:
| * | The message queue of the current call stack entry (that is, the call stack entry removing the messages). |
| *ALLINACT | All message queues for inactive call stack entries. The messages to remove parameter must specify *ALL. The call stack counter parameter is ignored. |
| *EXT | The external message queue. The call stack counter parameter is ignored. |
If you specify a message key and the messages to remove parameter specifies *BYKEY, this parameter is ignored.
If the call stack entry is to be identified by pointer, the pointer that is specified must address a valid call stack entry within the same job as the one the API is used in. Alternatively, the pointer can be set to Null. The Optional Parameter Group 1 must be used and the Length of Call stack entry parameter must be set to 16. In addition, the Optional Parameter Group 2 must also be used and the Call stack entry format parameter must be set to *PTR.
If the pointer provided is set to Null, this indicates that the call stack entry is the one in which the API is being used.
If the pointer does not address a valid call stack entry or is not a Null pointer, the error message CPF24C5 is sent to the user of the API.
The call stack entry can be a nested procedure name from 1 through 4096 characters in length. When specifying nested procedures, each procedure name must be separated by a colon, and the outermost procedure is identified first followed by the procedures it contains. The innermost procedure is the last procedure identified in the string.
The call stack entry can be a partial name. To specify a partial name, place three less-than signs (<<<) at the beginning of the call stack entry identifier, or place three greater-than signs (>>>) at the end of the call stack entry identifier, or place both the less-than signs and the greater-than signs at their respective ends of the call stack entry identifier. The value for the call stack entry excluding the less-than signs and the greater-than signs is used to search backward through the stack for the requested call stack entry name.
When searching for a partial call stack entry name:
Note: If the optional parameters Length of to call stack entry and To call stack entry data type are not specified, this parameter is assumed to be CHAR(10).
A number identifying the location in the call stack of the call stack entry from whose message queue the messages are to be removed. The number is relative to the call stack entry identified by the Call stack entry parameter. It indicates how many calls up the call stack the target entry is from the one identified by the Call stack entry parameter.Valid values follow:
| 0 | Remove the messages from the message queue of the call stack entry specified in the Call stack entry parameter. |
| 1 | Remove the messages from the message queue of the call stack entry that is one earlier than the entry identified by the Call stack entry parameter. |
| n (any positive number) | Remove the messages from the message queue of the
nth call stack entry up the stack from the call stack entry specified in the
Call stack entry parameter.
You can use any positive number that does not exceed the actual number of call stack entries in the call stack, excluding the external message queue. |
This parameter is ignored in these cases:
If the messages to remove parameter specifies *BYKEY or *SCOPE, the key to the single message being removed. (The key is assigned by the command or API that sends the message.) The call stack entry and call stack counter parameters are ignored when the message to remove parameter specifies *BYKEY.
If the messages to remove parameter does not specify *BYKEY or *SCOPE, you must use blanks for this parameter.
When the messages to remove parameter specifies *BYKEY, the call stack entry parameter and the call stack counter parameters are ignored, and the message will be removed without regard to the call message queue that contains the message. This is useful if the message was sent to a call stack entry that is no longer in the call stack.
When the messages to remove parameter specifies *SCOPE, the call stack entry and call stack counter parameters must specify the call message queue that contains the scope message.
The message or group of messages being removed. Valid values follow:
| *ALL | All messages in the call message queue. |
| *BYKEY | The single message specified in the message key parameter. If the message to be removed is a *SCOPE message, the *SCOPE value must be used instead of *BYKEY. |
| *KEEPRQS | All messages in the call message queue except requests. |
| *NEW | All new messages in the call message queue. New messages are those that have not been received. |
| *OLD | All old messages in the call message queue. Old messages are those that have already been received. The *SCOPE type message identified by the message key specified in the Message key parameter. |
| *SCOPE | The scope message specified in the message key parameter. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
The length of the value for the call stack entry parameter. Valid values for this parameter are as follows:
Note: The actual length of the call stack entry name cannot exceed 4096 characters. If this parameter is not used, the value for the call stack entry parameter is assumed to be 10 characters in length.
The name of the module and the ILE program or service program to further qualify the procedure name specified by the Call stack entry parameter. The first 10 characters specify the module name, and the second 10 characters specify the ILE program name or service program name. If this parameter is not used, only the Call stack entry parameter is used to determine the call stack entry. The following special value may be used:
| *NONE | This value is used for the module or ILE program name or service program name, or both. When *NONE is specified for one of the names, then that name is not used when searching for the call stack entry. If *NONE is specified for both names, only the Call stack entry parameter is used to identify the call stack entry. |
If the call stack entry is to be identified by pointer, this parameter must still be passed to the API but both the module and program qualifiers must be specified as *NONE. When a pointer is used, the module and program name qualification is not applicable.
The module name and bound program name should be used only when identifying the call stack entry for an ILE procedure. When identifying the entry for an OPM program, the Optional Parameter Group 1 should either not be used or the module and program qualifiers should be specified as *NONE.
Whether to remove unhandled exceptions in the identified call message queue. The exception handling support for some languages allows exceptions to not be handled. Valid values follow:
| *YES | Remove any unhandled exceptions in the identified call message queue. This is the default when this parameter is not used. |
| *NO | Do not remove any unhandled exceptions in the identified call message queue. |
This parameter group is used when the Call stack entry parameter is specified as a pointer.
Whether the value of the call stack entry parameter is a character string (a name or special value) or a pointer. Use one of the following special values;
| *CHAR | Value of the parameter is a character string (name or special value) |
| *PTR | Value of the parameter is a pointer. |
If the above optional parameter is not specified, it is assumed that the value of the call stack entry parameter is a character string.
Removing an unanswered inquiry 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 function. A reply handling exit program can be registered via the system registration facility for exit point QIBM_QMH_REPLY_INQ. If the parameter is not specified, a value of *NO is used. Valid values are:
| *NO | A reply handling exit program will not be allowed to reject a default reply. |
| *YES | A reply handling exit program will
be allowed to reject a default reply. If an exit program rejects
the reply, a CPD2476 (Reply rejected by a reply handling exit
program) will be sent as a diagnostic message to the program
using this function. The CPD2476 will be followed by a
CPF2422 (Reply not valid) escape message that the program using
this function should monitor for to handle and recover from
error situations. |
| Message ID | Error Message Text |
|---|---|
| CPF24AD E | Messages to remove must be *ALL if program message queue is *ALLINACT. |
| CPF24AE E | Message key and messages to remove are mutually dependent. |
| CPF24A3 E | Value for call stack counter parameter not valid. |
| CPF24A6 E | Value for messages to remove not valid. |
| CPF24BF E | Module or bound-program name is blank. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24B7 E | Value &1 for call stack entry name length not valid. |
| CPF24B8 E | Value &1 for remove unhandled exceptions not valid. |
| CPF24C5 E | Pointer to call stack entry not valid. |
| CPF24C6 E | Value of To call stack entry data type parameter not valid. |
| CPF241A E | Clear option &1 in system program is not valid. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF2422 E | Reply not valid. |
| CPF247A E | Call stack entry not found. |
| CPF2479 E | Call stack entry not found. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |