Remove Program Messages (QMHRMVPM) API

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.

Authorities and Locks

None.

Required Parameter Group

Call stack entry

INPUT; CHAR(*) or Pointer

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:

• If the less-than signs (<<<) are specified only at the beginning of the call stack entry name, the less-than signs are truncated and the remaining character string is right-justified. The remaining string is then compared to the current call stack entry on the call stack. The comparison starts at the end of the call stack entry name and backwardly compares the number of characters in the specified string.
• If the greater-than signs (>>>) are specified only at the end of the call stack entry name, the greater-than signs are truncated. The remaining character string is compared to the current call stack entry on the call stack. The comparison starts at position 1 of the call stack entry name and compares the number of characters in the specified string.
• If the less-than signs (<<<) are specified at the beginning of the call stack entry name and the greater-than signs (>>>) are specified at the end of the call stack entry name, both the less-than signs and the greater-than signs are truncated. The remaining characters are used to scan and to compare the entire length of the specified string and the current call stack entry on the call stack.

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).

Call stack counter

INPUT; BINARY(4)

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:

• When the program message queue parameter specifies all queues for inactive call stack entries (*ALLINACT) or the external message queue (*EXT).
• When you specify a message key and the messages to remove parameter specifies *BYKEY.

Message key

INPUT; CHAR(4)

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.

Messages to remove

INPUT; CHAR(10)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group 1

Length of call stack entry

INPUT; BINARY(4)

The length of the value for the call stack entry parameter. Valid values for this parameter are as follows:

• 1 through 4096 if partial name indicators are not used.
• 16 if the call stack entry parameter is a pointer.
• 1 through 4102 if partial name indicators are used.

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.

Call stack entry qualification

INPUT; CHAR(20)

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.

Remove unhandled exceptions

INPUT; CHAR(10)

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.

Optional Parameter Group 2

This parameter group is used when the Call stack entry parameter is specified as a pointer.

Call stack entry data type

INPUT; CHAR(10)

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.

Optional Parameter Group 3

Allow default reply rejection

INPUT; CHAR(10)

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.

Error Messages

[ Back to top | Message Handling APIs | APIs by category ]