Move Program Messages (QMHMOVPM) API

The Move Program Message (QMHMOVPM) API moves messages from a call message queue in the call stack to the call message queue of an earlier call stack entry. Moving a message does not change the sender information stored with the message. However, moving an escape message automatically changes it to a diagnostic message.

You can use the QMHMOVPM API to pass messages up the call stack, transferring important information to a previous program. When messages are sent to a call stack entry and the program running in that entry ends without moving its messages up the stack, the programs left in the stack cannot receive those messages unless:

• They use the message key of those messages.
• They use the List Job Log (QMHLJOBL) API.

For example, assume a program is sent several diagnostic messages and one escape message in response to an error. Another program earlier in the stack can handle the error. If the first program uses the QMHMOVPM API to move all the diagnostic messages to the program earlier in the stack, it then uses the Resend Escape Message (QMHRSNEM) API to send the escape message to the calling program.

In a multithreaded job, messages can be moved only from one call message queue to another call message queue within the thread that calls this API. Messages cannot be moved to a call stack entry in another thread.

Authorities and Locks

None.

Required Parameter Group

Message key

INPUT; CHAR(4)

When moving a single, specific message, use the key to that message for this parameter. The key is assigned by the command or API that sends the message.

When using the message types parameter to move a group of messages, use blanks for this parameter.

Message types

INPUT; ARRAY of CHAR(10)

The type or types of the messages being moved.

When moving a group of messages, specify a list of one through four message types. You can use these values in the list to move all messages of one or more types:

*COMP	Completion
*DIAG	Diagnostic
*ESCAPE	Escape. After an escape message is moved, its message type changes to diagnostic.
*INFO	Informational

For descriptions of the message types, see Message Types.

If there are no messages of a type you specify, the QMHMOVPM API does not return an error. It simply returns control to the calling program.

If the number of message types parameter specifies 0, this parameter is ignored.

Number of message types

INPUT; BINARY(4)

The number of message types specified in the message types parameter.

When moving a single message by specifying the message key in the message key parameter, use 0 for the number of message types parameter.

If you use blanks for the message key parameter and specify one or more message types, the value must be 1 through 4.

To call stack entry

INPUT; CHAR(*) OR POINTER

The call stack entry to move the messages to, or the call stack entry to start counting from when using a value other than 0 for the To call stack counter parameter. The call stack entry specified must be in the call stack; you cannot specify the external message queue.

You can specify a call stack entry by:

• Providing the name of the OPM program or ILE procedure running in the entry.
• Providing a pointer to the call stack entry, or
• Using one of the following special values:
  

  *	The current call stack entry (that is, the one in which the program or procedure using the API is running).
  *PGMBDY	The call stack entry is for the boundary of the specified program object. The program object is specified by providing a program name in the optional To call stack entry qualification parameter. The program object can be also be provided by not using the optional parameter or by specifying *NONE for the program name. In this case, the program object is assumed to be the program that is using the API. This option essentially identifies the oldest call stack entry which began a sequence of calls, where each call in this sequence involved the same program object. The call sequence could involve recursive calls to the same program or, in the case of ILE, calls to different procedures of the same ILE program or ILE service program. For OPM programs, in most cases, using *PGMBDY produces the same result as using * or using an OPM program name in this parameter. A difference will appear when an OPM program calls itself recursively. In this case, using * or an OPM program name identifies the current recursion level of the program. In contrast, using *PGMBDY identifies the first recursion level. For an ILE program, this option can be used to identify the first procedure of the ILE program that was called in the current sequence. If the ILE program was called using a dynamic call, this is the PEP (program entry procedure). For ILE service programs, this option can be used to identify the call stack entry for the first procedure that was called in the identified service program.
  *CTLBDY	The call stack entry at the most recent control boundary. This call stack entry is in the same activation group as the one using the API. If this keyword value is used and there is no control boundary in the current call stack entry, the error CPF24C8 is returned to the user of this API. This happens if the only entries on the call stack are for OPM programs. In some cases, *PGMBDY and *CTLBDY identify the same call stack entry. The option *CTLBDY does not care if all call stack entries in a call sequence involve the same program object. It only cares that a sequence started at a control boundary. Conversely, the start of a call sequence identified by *PGMBDY may not fall on a control boundary.
  *PGMNAME	The to call stack entry is identified by the program name and, optionally, module name that is provided by the optional To call stack entry qualification parameter. For OPM programs, specifying this special value and the optional parameter is the same as specifying the OPM program name in this parameter. For ILE programs or ILE service programs this special key value indicates that a procedure name is not being specified. Rather the call stack entry is identified by providing only the ILE program or service program name and optionally the ILE module name. This means that the call stack entry is the most recently called procedure that is part of the specified ILE program or ILE service program (and part of the ILE module if module name is also specified). The name of this most recently called procedure is not important in determining the correct call stack entry. If this special value is specified with a program name only, then the call stack entry is the most recently called OPM program that has the specified program name or the most recently called ILE procedure that is part of an ILE program or ILE service program of the specified name, whichever occurs most recently on the call stack. If the module name is also specified, then the call stack entry is the most recently called ILE procedure that is part of specified the ILE program or service program and module. If a module name is given, the call stack entry cannot be an OPM program.

If the call stack entry is identified by pointer, the pointer 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 To 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).

To call stack counter

INPUT; BINARY(4)

A number identifying the location in the call stack of the call stack entry to whose message queue the messages are to be moved. The number is relative to the call stack entry identified by the To call stack entry parameter. It indicates how many calls up the call stack the target entry is from the one identified by the To call stack entry parameter. Valid values follow:

0	Move the messages to the message queue of the entry specified by the to call stack entry parameter. You cannot use 0 when the to call stack entry parameter specifies *, a Null pointer, or a pointer that points to the user of the API. This combination means that you want to move the message from yourself to yourself which is not a valid operation.
1	Move the messages to the message queue of the call stack entry one earlier on the stack than the one identified by the To call stack entry parameter.
n (any positive number)	Move the messages to the queue of the nth call stack entry earlier in the stack from the one identified by the To 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. Do not include the external message queue in your count.

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 to call stack entry

INPUT; BINARY(4)

The length of the value for the to call stack entry parameter.

Valid values for this parameter are as follows:

• 1 to and including 4096 if partial name indicators are not used.
• 16 if the call stack entry parameter is a pointer.
• 1 to and including 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.

To call stack entry qualification

INPUT; CHAR(20)

Further identifies the To call stack entry. The parameter consists of two 10 character parts. The first part is the module name qualifier and the second part is the program name qualifier. The values provided in this parameter are used as a qualifier for the value provided in the To call stack entry parameter. The values that can be specified here depend upon the value provided in the To call stack entry parameter.

The special values discussed with this parameter can be used to indicate that the module name qualifier or program name qualifier is not being specified:

If the To call stack entry parameter contains an ILE procedure name then this parameter can contain the name of the module and the ILE program to further qualify the procedure name. The first 10 characters specify the module name, and the second 10 characters specify the ILE program name. If this parameter is not used or if *NONE is specified for both qualifiers, only the specified procedure name is used to determine the call stack entry.

If the required To call stack entry parameter contains the key value *PGMNAME, then the program name qualifier must contain either an OPM program name or an ILE program name. For ILE, the module name qualifier may contain a module name; otherwise it must contain *NONE.

When the To call stack entry parameter contains the special value * or *CTLBDY, the Optional Parameter Group 1 should either not be used or both the module name and program name qualifiers must be specified as *NONE.

When the To call stack entry parameter contains an OPM program name, the Optional Parameter Group 1 should also either not be used or both the module name and program name qualifiers should be specified as *NONE. If a module name or program name is specified here, the name specified as the To call stack entry is interpreted as an ILE procedure name rather than an OPM program name. Either the entry would not be found or an incorrect entry would be found.

When the special value *PGMBDY is used, the Optional Parameter Group 1 may be used. In this case, the module name qualifier must be specified as *NONE. For the program name qualifier, an OPM or ILE program name may be specified or *NONE may be used.

If the To call stack entry is identified by pointer, this parameter must still be passed to the API. The value specified for the module name qualifier must be specified as *NONE. The program name qualifier serves as a qualifier for the pointer and must be specified as one of the following special values:

*NONE

The call stack entry addressed by the pointer is the one to which the message is to be moved or the one to start counting from when using a value other than 0 for the To call stack counter parameter.

*PGMBDY

The call stack entry to move the message to or to start counting from is an ILE program boundary. The ILE program is the one which contains the procedure that is running in the call stack entry addressed by the pointer. If the ILE program was called using a dynamic call, using this special value with a pointer will identify the call stack entry for the PEP of that program. If a call was made using a procedure pointer, it will identify the call stack entry for the procedure that was pointed to. If the pointer addresses a call stack entry that is running a procedure from an ILE service program, this option can be used to identify the call stack entry for the first procedure that was called in that service program. If the call stack entry addressed by the pointer is running an OPM program than using the special value *PGMBDY here will have the same effect as using *NONE in most cases. A difference will occur if the OPM program called itself recursively. In this case using *PGMBDY identifies the first recursion level while *NONE identifies the current recursion level.

Optional Parameter Group 2

Use these optional parameters when:

• The call stack entry to which the messages are to be moved is identified by a pointer.
• The messages to be moved are not on the current call stack entry's message queue.

To call stack entry data type

INPUT; CHAR(10)

Whether the value of the To 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 To call stack entry parameter is a character string.

From call stack entry address

INPUT CHAR(16) OR POINTER

A pointer to the call stack entry where the messages to be moved exist or the call stack entry to start counting from if the from call stack counter is not 0.

The pointer that is specified must be an invocation pointer that addresses a valid call stack entry or must be set to Null.

For program languages that do not support pointers, a Null pointer can be presented by using a 16 byte variable. The first byte of the variable is set to the special value * and the remaining 15 bytes set to blanks.

If the pointer provided is set to Null, this indicates the current call stack entry (the one using the API).

If the pointer is not a valid pointer or if it is a valid pointer but is not Null nor does it address a valid call stack entry, the error message CPF24C5 is sent to the user of the API.

From call stack counter

INPUT; BINARY(4)

A number identifying the location in the call stack of the call stack entry where the messages to be moved exist. The number is relative to the To call stack entry that is addressed by the From call stack entry address pointer. It indicates how many calls up the call stack the entry is from the one that is addressed by the pointer. Valid values follow:

0	The message to move exists at the call stack entry that is addressed by the pointer.
1	The message to move exists at the call stack entry that is one earlier in the call stack than the one addressed by the pointer.
n (any positive number)	The message to move exists at the nth call stack entry earlier in the stack from the one addressed by the pointer. You can use any positive number that does not exceed the actual number of call stack entries in the call stack. Do not include the external message queue in your count.

The From call stack entry cannot be the same as the To call stack entry. Additionally, the To call stack entry must be earlier on the call stack than the From call stack entry.

Error Messages

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