Resend Escape Message (QMHRSNEM) API
Required Parameter Group:
| 1 | Message key | Input | Char(4) |
| 2 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 3 | To call stack entry | Input | CHAR(*) |
| 4 | To call stack entry length | Input | Binary(4) |
| 5 | Format of to call stack entry parameter | Input | Char(8) |
| 6 | From call stack entry address | Input | CHAR(16) or Pointer |
| 7 | From call stack counter | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: Yes
The Resend Escape Message (QMHRSNEM) API resends an escape message from the current call stack entry to the previous call stack entry in the call stack or to any call stack entry that is earlier if the optional parameters are used. This API can also be used to resend an escape message from a call stack entry other than the current one.
You can use this API along with the Move Program Messages (QMHMOVPM) API to streamline exception message handling. If a call stack entry is sent diagnostic messages and an escape message but cannot handle the error itself, you can use the QMHMOVPM API to move the diagnostic messages. You can use the QMHRSNEM API to forward the escape message to the previous call stack entry in the call stack. The call stack entry does not need to send an escape message of its own. For details about the QMHMOVPM API, see Move Program Messages (QMHMOVPM) API.
In a multithreaded job messages can be resent only from one call message queue to another call message queue within the thread that calls this API. Messages cannot be resent to a call stack entry in another thread.
Authorities and Locks
None.
Required Parameter Group
- Message key
- INPUT; CHAR(4)
The key to the escape message being resent. The key is assigned by the command or API that first sends the message.
To resend the last new escape message, use blanks for this parameter.
A message is new until it is received. It then becomes an old message. You can resend an old message only if you specify the message key.
- 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
Use these optional parameters if the call stack entry, to which the message is to be resent, is not just previous to the one that is using this API. Use these optional parameters also when the message to resend is not on the current call stack entry's message queue.
- To call stack entry
- INPUT; CHAR(*)
A structure that contains the information that this API will use to determine the call stack entry to resend the message to. The structure can be in one of two formats; RSNM0100 or RSNM0200.
- To call stack entry length
- INPUT; BINARY(4)
The length of the To call stack entry parameter. The length specified here must be at least large enough to hold the specified format of the To call stack entry parameter. It may be larger. In case it is larger, the structure must be left justified in the area. If the length specified by this parameter is not adequate for the format being used, error CPF24C7 is sent to the caller of this API.
- Format of to call stack entry parameter
- INPUT; CHAR(8)
The format of the to call stack entry parameter. Use one of the following format names:
RSNM0100 The To call stack entry parameter is in the RSNM0100 format. This format is used when the to call stack entry is identified by name or by special value. RSNM0200 The To call stack entry parameter is in the RSNM0200 format. This format is used when the call stack entry is identified by a pointer.
- From call stack entry address
- INPUT; Pointer or CHAR(16)
A pointer to the call stack entry where the escape message to resend exists 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 programming languages that do not support pointers, a Null pointer can be represented by a 16 byte variable in which the first byte is set to the special value '*' and the remaining 15 bytes are set to blanks.
If the pointer provided is set to Null, this indicates the current call stack entry.
If the pointer is not Null or it does not 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 from where the message is to be resent. The number is relative to the from call stack entry that is addressed by the pointer. It indicates how many calls earlier in the call stack the entry is from the one that is addressed by the pointer. Valid values follow:
0 The message to resend exists at the call stack entry that is addressed by the pointer. 1 The message to resend 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 resend 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.
RSNM0100 Format
The following table shows the structure of the To call stack entry parameter when the RSNM0100 format is used. This format is used when the to call stack entry is identified by name or by special value.
The information passed in the RSNM0100 format is described in Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | To call stack counter |
| 4 | 4 | CHAR(20) | To call stack entry qualification |
| 24 | 18 | BINARY(4) | Length of to call stack entry identifier |
| 28 | 1C | CHAR(*) | To call stack entry identifier |
RSNM0200 Format
The following table shows the structure of the To call stack entry parameter when the RSNM0200 format is used. This format is used when the to call stack entry is identified by a pointer.
The information passed in the RSNM0200 format is described in Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Pointer | To call stack entry address |
| 16 | 10 | BINARY(4) | To call stack counter |
| 20 | 14 | CHAR(10) | Pointer qualifier |
Field Descriptions
Length of the to call stack entry identifier. The length of the To call stack entry identifier. Valid values for this parameter are as follows:
- 1 to and including 4096 if partial name indicators are not used.
- 1 to and including 4102 is partial name indicators are used.
Note: The actual length of the call stack entry name cannot exceed 4096.
Pointer qualifier. Specify one of the following special values:
| *NONE | Specify this special value if the call stack entry addressed by the pointer is the one to which the message is to be resent or the one to start counting from when using a value other than 0 for the To call stack counter parameter. |
| *PGMBDY | Specify this special value if call stack entry to
resend 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, 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. |
To call stack counter. A number identifying the location in the call stack of the call stack entry to which the message is to be resent. The number is relative to the call stack entry identified by the To call stack entry identifier field. It indicates how many calls up the call stack the target entry is from the one specified in the To call stack entry identifier field. Valid values follow:
| 0 | Resend the message to the message queue of call stack entry specified by the To call stack entry identifier field. You cannot use 0 when the To call stack identifier field specifies * to designate the current call stack entry. |
| 1 | Resend the message to the message queue of the call stack entry that is one earlier in the call stack than the one identified by the To call stack entry identifier field. |
| n (any positive number) | Resend the message to the queue of the nth call
stack entry earlier in the stack from the one specified in the to call stack
entry field.
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.
To call stack entry address. A pointer to the call stack entry to resend 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 pointer that is specified must be an invocation pointer that addresses a valid call stack entry or must be set to Null.
If the pointer provided is Null, this indicates the current call stack entry. If a Null pointer is provided, the To call stack counter parameter must be specified as a non-zero value.
If the pointer provided is not Null and does not address a valid call stack entry, the error message CPF24C5 is sent to the user of the API.
To call stack entry identifier. An identification of the call stack entry to resend the message 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 identified by this field must be in the call stack, and you cannot specify the external message queue.
You can identify the To call stack entry by providing the name of the OPM program or ILE procedure running in the entry or by using one of the following special values:
| * | The call stack entry of the program or procedure using the API. |
| *PGMBDY | The call stack entry is for the boundary of the
specified program object. The program object is specified explicitly by
providing a program name in the To call stack entry qualification field. The
program object can be implicitly specified by specifying the program name
qualification as *NONE. 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 an OPM program name directly in this field. 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. 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) of the ILE program. If sequence was started by calling using a procedure pointer, this is the call stack entry for the procedure that was pointed to. For ILE service programs, this special value can be used to specify the call stack entry for the first procedure 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 that
is using the API.
If this key word value is used and there is no control boundary in the current call stack, the error CPF24C8 is returned to the user of this API. This would happen if the only entries on the call stack are for OPM programs. Note that in some cases, *PGMBDY and *CTLBDY will identify the same call stack entry but not in all cases. The option *CTLBDY does not care if all call stack entries in a call sequence involve the same program object. It cares only 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 call stack entry is identified entirely by the program
name and optionally module name that is provided in the To call stack entry
qualification field.
For OPM programs, specifying this special value here and the program name in the To call stack entry qualification field produces the same results as if the program name had been specified directly here. For ILE programs or service programs, this special value is used to indicate that a procedure name is not being specified. Rather the call stack entry is identified by providing only the ILE program name or ILE service program name and optionally the ILE module name. This means that the call stack entry will be the most recently called procedure that is part of the specified ILE 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 key 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 service program of the specified name, whichever is the most recent 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 ILE program or service program and module. If module name is given then the call stack entry cannot be an OPM program. |
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.
To call stack entry qualification. This field is used when it is necessary to further identify 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 field are used as a qualifier for the value provided in the To call stack entry identifier field. The values that can be specified here depend upon the value provided as the To call stack entry identifier.
The following special value may be used to indicate that the module name qualifier or program name qualifier is not being specified:
| *NONE | This value can be used for the value of the module name qualifier, program name qualifier, or both to indicate that no qualifier is being specified. |
If the To call stack entry identifier field contains an ILE procedure name then this field can contain the name of the module and program that the procedure was compiled and bound into. The module and program name qualifiers are used to distinguish the correct call stack entry in the case where different procedures of the same name are on the call stack at the same time. The first 10 characters specify the module name, and the second 10 characters specify the ILE program name or ILE Service program name. If *NONE is specified for both the module and program name qualifiers, only the specified procedure name is used to determine the call stack entry.
If the To call stack entry identifier field contains the special value *PGMNAME than the program name qualifier must contain either an OPM program name or an ILE program or Service program name. For ILE, the module name qualifier may contain a module name; otherwise it must contain *NONE.
When the To call stack entry identifier field contains the special value * or *CTLBDY, both the module name qualifier and program name qualifier must be specified as *NONE.
When the To call stack entry identifier field contains an OPM program name, 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 identifier 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 To call stack entry identifier field contains the special value *PGMBDY, the module name qualifier must be specified as *NONE. For the program name qualifier, an OPM, ILE program, or ILE Service program name may be specified or *NONE may be used.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24A3 E | Value for call stack counter parameter not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24B7 E | Value &1 for call stack entry name length not valid. |
| CPF24B9 E | When call stack entry name is '*' or '*CTLBDY', module name and program name must be '*NONE'. |
| CPF24BC E | No escape message to resend. |
| CPF24C5 E | Pointer to call stack entry not valid. |
| CPF24C7 E | The length &1 is not valid when the specified format is &2. |
| CPF24C8 E | Control boundary not found on call stack. |
| CPF24C9 E | Program boundary not found on call stack. |
| CPF24CA E | Call stack entry is not valid to resend message. |
| CPF24CB E | *PGMNAME requires a specified program name. |
| CPF24CC E | Call stack entry &2 for *PGMNAME not found. |
| CPF24CD E | Module name cannot be specified when *PGMBDY is used. |
| CPF24CE E | Qualifier &1 incorrect for use with pointer. |
| CPF24CF E | Pointer qualifier &1 incorrect for use with pointer. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF246A E | Destination call stack entry not valid. |
| CPF247A E | Call stack entry not found. |
| CPF2479 E | Call stack entry not found. |
| CPF2524 E | Exception handler not available because of reason code &1. |
| CPF2550 E | Exception message sent to a deleted program or procedure. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1.1