Receive Program Message (QMHRCVPM) API
Required Parameter Group:
| 1 | Message information | Output | Char(*) |
| 2 | Length of message information | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Call stack entry | Input | Char(*) or Pointer |
| 5 | Call stack counter | Input | Binary(4) |
| 6 | Message type | Input | Char(10) |
| 7 | Message key | Input | Char(4) |
| 8 | Wait time | Input | Binary(4) |
| 9 | Message action | Input | Char(10) |
| 10 | Error code | I/O | Char(*) |
Optional Parameter Group 1:
| 11 | Length of call stack entry | Input | Binary(4) |
| 12 | Call stack entry qualification | Input | Char(20) |
Optional Parameter Group 2:
| 13 | Call stack entry data type | Input | Char(10) |
| 14 | Coded character set identifier | Input | Binary(4) |
Optional Parameter Group 3:
| 15 | Allow default reply rejection | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
The Receive Program Message (QMHRCVPM) API receives a message from a call message queue or external message queue and returns information describing the message.
To receive a message from nonprogram message queues, see Receive Nonprogram Message (QMHRCVM) API.
In a multithreaded job messages can be received from call message queues within the thread that calls this API, and messages sent from within the same thread can be received 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 received.
Authorities and Locks
- Message File Authority
- *USE, if receiving a predefined message and the message file used when the message was sent was deleted and recreated.
- Message File Library Authority
- *EXECUTE, if receiving a predefined message and the message file used when the message was sent was deleted and recreated.
Required Parameter Group
- Message information
- OUTPUT; CHAR(*)
The variable that receives the information returned, in the format specified in the format name parameter, of the length specified in the length of message information parameter.
- Length of message information
- INPUT; BINARY(4)
The size of the area to contain the message information, in bytes. The minimum size is 8.
This parameter must specify the size of the variable you use for the message information parameter. If this parameter specifies a longer size, other parts of storage could be overwritten when the API returns the information.
The API returns as much information as it can fit in this length. If the available message information is longer, it is truncated. If the available message information is shorter, the unused output area is unchanged; whatever is already stored in that space remains there.
To determine how much information the API actually returns in response to this call, see the bytes returned field in the RCVM0100, RCVM0200, or RCVM0300 output. To determine how much information the API could return if space were available, see the bytes available field.
- Format name
- INPUT; CHAR(8)
The format to use for the message information. Specify one of these format names:
RCVM0100 Brief message information. For details, see RCVM0100 Format. RCVM0200 All message information. For details, see RCVM0200 Format. RCVM0300 All message information. Complete sender information for the message being received. For details, see RCVM0300 Format.
- Call stack entry
- INPUT; CHAR(*) or Pointer
The call stack entry from whose message queue messages are to be received, or the call stack entry to start counting from when using a value other than 0 for 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 current call stack entry (that is, the one in which the API is being used). *EXT The external message queue. The call stack counter parameter is ignored. You cannot receive escape messages from this queue. 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 pointer must be 16 byte aligned. 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).
- 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.
- 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 received. 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 Receive the message from the message queue of the call stack entry specified in the Call stack entry parameter. 1 Receive the message 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) Receive the message 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.
- Message type
- INPUT; CHAR(10)
The type of the message being received. The message type and message key parameters work together. Depending on the message type, the key can be required, optional, or disallowed. For a list of valid message types and information about how they work with the message key parameter, see Message Types and Message Keys.
- Message key
- INPUT; CHAR(4)
The key to the message being received. The key is assigned by the command or API that sends the message.
What you can use for the message key parameter depends on what you use for the message type. For details, see Message Types and Message Keys.
If you are not receiving messages by key, use blanks for this parameter.
If you specify a key and the message queue does not contain a message with that key, an error is returned.
If you specify a key and the message queue does contain a message with that key, the API might or might not return a message. It never returns an error in this case. Whether or not the API returns a message depends on the value of the message type parameter. For example, if you specify the message type *PRV and there is no message before the message with the key, the API does not return a message. Because the key you specified is valid, the API does not return an error either.
You can receive the reply to a message through the key to the sender's copy of the message. If the reply is not available, no message is returned, and the API does not return an error.
When the message type is *NEXT, you can use *TOP for the message key to receive the next message after the last message received.
When the message type is *NEXT, *PRV, *NXTJLMSG, or *PRVJLMSG you can use hexadecimal zeros for the message key for the first receive operation to obtain a message key that can be specified on a subsequent receive operation.
If you know the message key of a message you want to receive, you can receive that message without regard to the call message queue containing the message. You can do this by specifying the key in this parameter, the special value '*' for the Call stack entry parameter and the value '0' for the call stack counter parameter. This is useful if the message was sent to a call stack entry that is no longer in the call stack.
- Wait time
- INPUT; BINARY(4)
The length of time to wait for the message to arrive in the queue so it can be received. Valid values follow:
0 Do not wait for the message. If the message is not in the queue and you specified a message key, an error is returned. -1 Wait until the message arrives in the queue and is received, no matter how long it takes. The system has no limit for the wait time. n (any positive number) Wait n seconds for the message to arrive in the queue. If you specify a value of zero or above and the message does not arrive in the specified time, most fields in the RCVM0100, RCVM0200 or RCVM0300 output are unchanged. The bytes returned output field has a value of 8, and the bytes available output field has a value of 0. The remaining output fields are unchanged; they contain whatever was already stored in the space.
- Message action
- INPUT; CHAR(10)
The action to take after the message is received. Valid values follow:
*OLD Keep the message in the message queue and mark it as an old message. You can receive the message again only by using the message key or by specifying the message type *NEXT, *PRV (previous), *FIRST, or *LAST. *REMOVE Remove the message from the message queue. This instance of the message is no longer available for you to work with. The message key is no longer valid; therefore, you cannot receive the message again. *SAME Keep the message in the message queue without changing its new or old designation. *SAME lets you receive the message again later without using the message key. For Integrated Language Environment® (ILE) programs, the message action also indicates if an exception message should be handled. If the message action is *OLD or *REMOVE, an exception is handled. If *SAME is specified, the exception is not handled.
- 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 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 name and program name 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 both the module name and bound program name should be specified as *NONE.
Optional Parameter Group 2
- 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.
- Coded character set identifier
- INPUT; BINARY(4)
The coded character set identifier (CCSID) that you want your message text and message data returned in. This applies to the text and the parts of the message data defined as a convertible character field (*CCHAR). For more information about *CCHAR fields, see the Add Message Description (ADDMSGD) Command. The following values are allowed:
0 The received message is converted to the CCSID of the job before being returned. If the job is 65535 and the text or data is something other than EBCDIC single byte or EBCDIC mixed, the text and data are converted to the default job CCSID.
65535 The received message will not be converted before being returned. CCSID Specify a CCSID you want your text and data converted to before being returned. Valid values are between 1 and 65535. This API will validate the CCSID specified. Only CCSIDs that a job can be changed to are accepted. For a list of valid job CCSIDs, display the prompt for the CCSID parameter on the CHGJOB command.
If this parameter is not specified, 0 is used and messages are returned in the CCSID of the job.
Note: If an invalid CCSID conversion is detected during the receive function, the data is not converted before it is returned. The CCSID conversion status field should be checked to determine if an error occurred.
For more information about message handler and its use of CCSIDs, see CCSID support for messages.
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 this parameter is not specified, a value of *NO is used. This parameter is only applicable when *REMOVE is specified for the message action parameter. 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 Types and Message Keys
The message type and message key parameters work together. Depending on the message type, the key can be required, optional, or disallowed. The following table lists each message type you can specify, tells whether it requires a key, and gives other information about using that type.
When used without a key, most message types receive only new messages. When used with a key, most can receive old or new messages. Message types *FIRST, *LAST, *PRV (previous), *NEXT, *NXTJLMSG (next job log message), and *PRVJLMSG (previous job log message) always receive both old and new messages.
New messages are messages that have been sent to a queue and have not yet been received. Old messages are messages that have been received but have not yet been removed from the queue.
Messages of type *EXCP are received in last-in first-out (LIFO) order. Messages of all other types are received in first-in first-out (FIFO) order.
The following terms are used to describe the message key in the following table:
| Disallowed | Do not specify a message key. Instead, use blanks for the message key parameter. Specifying a message key results in an error. |
| Required | Specify a message key. Not specifying a message key results in an error. |
| Optional | You can either specify a message key or use
blanks for the message key parameter.
When you do not specify a message key, the first new message of the specified type is received. If a new message of that type is not in the message queue, no error is returned. The unused space allowed for the output in the message information parameter is unchanged. When you specify a message key and the message in the message queue is of the type specified, the message is received. If the message is not found, or if the message found does not match the type specified, an error code or exception is returned. |
There are two cases where the message is not found and no error is returned. In both cases, the bytes returned field equals 8 and the bytes available field equals 0. The two cases are:
- Receiving without a message key (the key is optional or disallowed). A
message of the specified type is not found in the queue.
- Receiving with a message key (the key is required) and the message type is *PRV, *NEXT, *PRVJLMSG or *NXTJLMSG. The message with the key specified was found in the queue, but no previous or next message is found.
The message types you can specify in the QMHRCVPM API are:
| Message Type | Message Key | Description |
|---|---|---|
| *ANY | Optional | If message key is blanks, then this receives a message of any type except a sender's copy or request. If the message key is not blank, this receives the requested message and if the message does not exist CPF2410 is issued. If the message is a sender's copy type message, the associated reply is received. |
| *COMP | Optional | Receives a completion message. |
| *COPY | Required | Receives the sender's copy of a previously sent inquiry message. The program message queue parameter must specify the reply message queue specified when the inquiry was sent. |
| *DIAG | Optional | Receives a diagnostic message. |
| *ESCAPE | Optional | Receives an escape message. |
| *EXCP | Optional | Receives an escape or notify message. Both types of messages are received in last-in first-out (LIFO) order. |
| *FIRST | Disallowed | Receives the first new or old message in the queue, unless it is a request message. Request messages are skipped. |
| *INFO | Optional | Receives an informational message. |
| *LAST | Disallowed | Receives the last new or old message in the queue. |
| *NEXT | Required | Receives the next new or old message after the
message with the specified key, unless it is a request message. Request
messages are skipped.
You can use the special value *TOP for the message key. *TOP designates the message at the top of the message queue. You can use hexadecimal zeros (hex 00000000) for the message key for the first receive operation. If *TOP or hexadecimal zeros are specified, the search for the next message begins after the last request message is received. If no request messages have been received, the search starts at the top of the message queue. |
| *NOTIFY | Optional | Receives a notify message. |
| *NXTJLMSG | Required | Returns the job log message after the specified key.
Similar to *PRVJLMSG, it can obtain a message residing on an active
program message queue or an inactive program queue (where
the program or procedure has ended). This differs from *NEXT, which
only returns a message from an active program or procedure.
Specify the current call stack entry (using a * along with 0 for the call stack counter)
and the next message in the job log is returned regardless of the program queue.
The special value *TOP or hexadecimal zeros (hex 00000000) can be specified for the message key to return the first message on the program message queue. |
| *PRV | Required | Receives the new or old message before the
message with the specified key.
You can use hexadecimal zeros (hex 00000000) for the message key for the first receive operation to receive the last message on the queue. |
| *PRVJLMSG | Required | Returns the job log message before the specified key.
Similar to *NXTJLMSG, it can obtain a message residing on an active
program message queue or an inactive program queue (where
the program or procedure has ended). This differs from *PRV, which
only returns a message from an active program or procedure.
Specify the current call stack entry (using a * along with 0 for the call stack counter)
and the previous message in the job log is returned regardless of the program queue.
The special value hexadecimal zeros (hex 00000000) can be specified for the message key to return the newest message on the program message queue. |
| *RPY | Optional | Receives the reply to an inquiry or notify message. For the message key, you can use the key to the sender's copy of the inquiry or notify message. |
| *RQS | Optional | Receives the next request in the program message
queue for the program. Two actions are possible if no request exists:
|
RCVM0100 Format
The following table lists the fields returned in the RCVM0100 format. For more information about each item of information, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Message severity |
| 12 | C | CHAR(7) | Message identifier |
| 19 | 13 | CHAR(2) | Message type |
| 21 | 15 | CHAR(4) | Message key |
| 25 | 19 | CHAR(7) | Reserved |
| 32 | 20 | BINARY(4) | CCSID conversion status indicator of message data or text |
| 36 | 24 | BINARY(4) | CCSID of replacement data or impromptu message text |
| 40 | 28 | BINARY(4) | Length of replacement data or impromptu message text returned |
| 44 | 2C | BINARY(4) | Length of replacement data or impromptu message text available |
| 48 | 30 | CHAR(*) | Replacement data or impromptu message text |
RCVM0200 Format
The following table lists the fields returned in the RCVM0200 format. For more information about each item of information, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Message severity |
| 12 | C | CHAR(7) | Message identifier |
| 19 | 13 | CHAR(2) | Message type |
| 21 | 15 | CHAR(4) | Message key |
| 25 | 19 | CHAR(10) | Message file name |
| 35 | 23 | CHAR(10) | Message file library specified |
| 45 | 2D | CHAR(10) | Message file library used |
| 55 | 37 | CHAR(10) | Sending job |
| 65 | 41 | CHAR(10) | Sending job's user profile |
| 75 | 4B | CHAR(6) | Sending job's number |
| 81 | 51 | CHAR(12) | Sending program name |
| 93 | 5D | CHAR(4) | Sending program's instruction number |
| 97 | 61 | CHAR(7) | Date sent |
| 104 | 68 | CHAR(6) | Time sent |
| 110 | 6E | CHAR(10) | Receiving program name |
| 120 | 78 | CHAR(4) | Receiving program's instruction number |
| 124 | 7C | CHAR(1) | Sending type |
| 125 | 7D | CHAR(1) | Receiving type |
| 126 | 7E | CHAR(1) | Reserved |
| 127 | 7F | BINARY(4) | CCSID conversion status indicator for text |
| 131 | 83 | BINARY(4) | CCSID conversion status indicator for data |
| 135 | 87 | CHAR(9) | Alert option |
| 144 | 90 | BINARY(4) | CCSID of message and message help |
| 148 | 94 | BINARY(4) | CCSID of replacement data or impromptu message text |
| 152 | 98 | BINARY(4) | Length of replacement data or impromptu message text returned |
| 156 | 9C | BINARY(4) | Length of replacement data or impromptu message text available |
| 160 | A0 | BINARY(4) | Length of message returned |
| 164 | A4 | BINARY(4) | Length of message available |
| 168 | A8 | BINARY(4) | Length of message help returned |
| 172 | AC | BINARY(4) | Length of message help available |
| 176 | B0 | CHAR(*) | Replacement data or impromptu message text |
| The offsets to these fields equal the offset to the last fixed-length field plus the length of the previous variable length fields. | CHAR(*) | Message | |
| CHAR(*) | Message help | ||
RCVM0300 Format
The following table lists the fields returned in the RCVM0300 format. For more information about each item of information, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Message severity |
| 12 | C | CHAR(7) | Message identifier |
| 19 | 13 | CHAR(2) | Message type |
| 21 | 15 | CHAR(4) | Message key |
| 25 | 19 | CHAR(10) | Message file name |
| 35 | 23 | CHAR(10) | Message file library specified |
| 45 | 2D | CHAR(10) | Message file library used |
| 55 | 37 | CHAR(9) | Alert option |
| 64 | 40 | BINARY(4) | CCSID conversion status indicator of message and message help |
| 68 | 44 | BINARY(4) | CCSID conversion status indicator of message data or text |
| 72 | 48 | BINARY(4) | CCSID of replacement data or impromptu message text |
| 76 | 4C | BINARY(4) | CCSID of replacement data and message help |
| 80 | 50 | BINARY(4) | Length of replacement data or impromptu message text returned |
| 84 | 54 | BINARY(4) | Length of replacement data or impromptu message text available |
| 88 | 58 | BINARY(4) | Length of message returned |
| 92 | 5C | BINARY(4) | Length of message available |
| 96 | 60 | BINARY(4) | Length of message help returned |
| 100 | 64 | BINARY(4) | Length of message help available |
| 104 | 68 | BINARY(4) | Length of sender information returned |
| 108 | 6C | BINARY(4) | Length of sender information available |
| 112 | 70 | CHAR(*) | Replacement data or impromptu message text |
| The offsets to these fields equal the offset to the last fixed-length field plus the length of the previous variable length fields. | CHAR(*) | Message | |
| CHAR(*) | Message help | ||
| CHAR(*) | Sender information | ||
Sender Information Format
The following table lists the fields for the sender information format of the RCVM0300 format. For more information about each item of information, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Sending job |
| 10 | A | CHAR(10) | Sending job's user profile |
| 20 | 14 | CHAR(6) | Sending job's number |
| 26 | 1A | CHAR(7) | Date sent |
| 33 | 21 | CHAR(6) | Time sent |
| 39 | 27 | CHAR(1) | Sending type |
| 40 | 28 | CHAR(1) | Receiving type |
| 41 | 29 | CHAR(12) | Sending program name |
| 53 | 35 | CHAR(10) | Sending module name |
| 63 | 3F | CHAR(256) | Sending procedure name |
| 319 | 13F | CHAR(1) | Reserved |
| 320 | 140 | BINARY(4) | Number of statement numbers or instruction numbers available for the sending program or procedure |
| 324 | 144 | CHAR(30) | Sending program's statement numbers or instruction numbers |
| 354 | 162 | CHAR(10) | Receiving program name |
| 364 | 16C | CHAR(10) | Receiving module name |
| 374 | 176 | CHAR(256) | Receiving procedure name |
| 630 | 276 | CHAR(10) | Reserved |
| 640 | 280 | BINARY(4) | Number of statement numbers or instruction numbers available for the receiving program or procedure |
| 644 | 284 | CHAR(30) | Receiving program's statement number or instruction number |
| 674 | 2A2 | CHAR(2) | Reserved |
| 676 | 2A4 | BINARY(4) | Displacement to long sending program name |
| 680 | 2A8 | BINARY(4) | Length of long sending program name |
| 684 | 2AC | BINARY(4) | Displacement to long sending procedure name |
| 688 | 2B0 | BINARY(4) | Length of long sending procedure name |
| 692 | 2B4 | BINARY(4) | Displacement to long receiving procedure name |
| 696 | 2B8 | BINARY(4) | Length of long receiving procedure name |
| 700 | 2BC | CHAR(6) | Microseconds |
| 706 | 2C2 | CHAR(10) | Sending user profile |
| 716 | 2CC | CHAR(*) | Reserved |
| The offsets to these fields are found in the displacement fields identified in this table. | CHAR(*) | Long sending program name | |
| CHAR(*) | Long sending procedure name | ||
| CHAR(*) | Long receiving procedure name | ||
Field Descriptions
The following field descriptions apply only when a message is received. If no message is found, only the bytes available and bytes returned fields contain new values. The remaining fields contain whatever information was already stored in the space allowed for the output.
Alert option. Whether and when an SNA alert is created and sent for the message. If a message is received, the value is one of the following:
| *DEFER | An alert is sent after local problem analysis. |
| *IMMED | An alert is sent immediately when the message is sent to a message queue that has the allow alerts attribute set to *YES. |
| *NO | No alert is sent. |
| *UNATTEND | An alert is sent immediately when the system is running in unattended mode (when the value of the alert status network attribute, ALRSTS, is *UNATTEND). |
For more information, see the
Alerts Support
manual.
Bytes available. The length of all available information that could be returned for the format. Bytes available can be greater than the length specified in the API's length of message information parameter. If it is greater, the information returned in the message information parameter is truncated to the length specified.
Bytes returned. The length of all information returned in the format. The value of the bytes returned field is always less than or equal to the length of the message information parameter. Also, it is always less than or equal to the bytes available. There is one exception to this. When you attempt to receive a message and the message is not found, the following occurs:
- The value of the bytes returned field is 8.
- The value of the bytes available field is 0.
- The remaining fields are unchanged (that is, they contain whatever was already stored in that space).
If the bytes returned value is less than the length specified in the length of message information parameter, the extra space in the message information parameter is unchanged.
CCSID conversion status indicator for data. The following values may be returned:
| 0 | No conversion was needed because the CCSID of the replacement data or impromptu message text matched the CCSID you wanted the data converted to. |
| 1 | No conversion occurred because either the data was 65535 or the CCSID you wanted the data converted to was 65535. |
| 2 | No conversion occurred because you did not supply enough space for the data. |
| 3 | The data was converted to the CCSID specified using the best fit conversion tables. |
| 4 | A conversion error occurred using the best fit conversion tables so a default conversion was attempted. This completed without error. |
| -1 | An error occurred on both the best fit and default conversions. The data was not converted. |
CCSID conversion status indicator for text. The following values may be returned:
| 0 | No conversion was needed because the CCSID of the message or message help text matched the CCSID you wanted the message or message help text converted to. |
| 1 | No conversion occurred because either the message or message help text was 65535 or the CCSID you wanted the message or message help text converted to was 65535. |
| 2 | No conversion occurred because you did not supply enough space for the message or message help text. |
| 3 | The message or message help text was converted to the CCSID specified using the best fit conversion tables. |
| 4 | A conversion error occurred using the best fit conversion tables so a default conversion was attempted. This completed without error. |
| -1 | An error occurred on both the best fit and default conversions. The text was not converted. |
CCSID of message and message help. The CCSID of the text in the message and message help fields is returned. The inserted replacement data may not be the same CCSID. Refer to the CCSID of the replacement data or impromptu message text field description for a more details.
If a conversion error occurs or the CCSID you requested the text to be converted to is 65535, the CCSID that the message description is stored in is returned. Otherwise, the CCSID you wanted your text converted to is returned. If you do not want the text converted before it is returned to you but you do want to know the CCSID that the message description is stored in specify 65535 on the Coded character set identifier parameter. The CCSID that the message description is stored in is returned in the CCSID of message and message help output field.
CCSID of replacement data or impromptu message text. The CCSID of the impromptu message text or replacement data is returned. If an impromptu message is received, this is the CCSID of the impromptu message text. When replacement data is received, this is the CCSID of the message data fields defined as convertible character (*CCHAR) in the message description. All other replacement data will not be converted before it is returned. If a conversion error occurs or if the CCSID you requested the data to be converted to is 65535, the CCSID of the data is returned. If message data is being returned and there is no *CCHAR replacement data, 65535 is returned. Otherwise, the CCSID you wanted the data converted to is returned.
Date sent. The date on which the message was sent, in CYYMMDD (century, year, month, day) format.
Displacement to long receiving procedure name. When the receiving type is 1 or 2, the offset to the long receiving procedure name, in bytes, from the beginning of the data returned in the sender information format. If there is not enough room to contain any of the long receiving procedure, this field is zero.
Displacement to long sending procedure name. When the sending type is 1 or 2, the offset to the long sending procedure name, in bytes, from the beginning of the data returned in the sender information format. If there is not enough room to contain any of the long sending procedure, this field is zero.
Displacement to long sending program name. The offset to the long sending program name, in bytes, from the beginning of the data returned in the sender information format. If there is not enough room to contain any of the long sending program, this field is zero.
Length (general information about the following length fields). These formats use two types of length fields, each related to a single variable length text field. (The variable length text fields return information to the caller.) The first type of length field is returned length; the second is available length. Returned length is the actual length of the text in the variable length text field. Available length is the length of the text before it is placed in the variable length text field. It is always greater than or equal to the returned length. If the available length equals the returned length, all the message information is returned. If the text is truncated when placed in the variable length field, the available length is greater than the returned length by the number of characters truncated.
Length of long receiving procedure name. For type 1 and 2, the length of the complete receiving procedure name, in bytes.
Length of long sending procedure name. For type 1 and 2, the length of the complete sending procedure name, in bytes.
Length of long sending program name. The length of the complete sending program name, in bytes.
Length of message available. The length of the available message text, in bytes. If an immediate message is received, the value of this field is zero.
Length of message help available. The length of the available message help information, in bytes. If an impromptu message is received, the value of this field is zero.
Length of message help returned. The length of the message help information, in bytes. If an impromptu message is received, the value of this field is zero.
Length of message returned. The length of the returned text of a predefined message, in bytes. If an impromptu message is received, the value of this field is zero.
Length of replacement data or impromptu message available. The length of the available impromptu message text or replacement data, in bytes. If the message identifier is not blank, this field contains the length of the available message data for a predefined message. If the message identifier is blank, this field contains the length of the available text of an impromptu message.
Length of replacement data or impromptu message returned. The length of the returned impromptu message text or replacement data, in bytes. If the message identifier is not blank, this field contains the length of the replacement data. If the message identifier is blank, this field contains the length of the impromptu message text.
Length of sender information available. The length, in bytes, of information available in the sender information format.
Length of sender information returned. The length, in bytes, of information returned in the sender information format.
Long receiving procedure name. For type 1 and 2, complete procedure name that received the message. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
Long sending procedure name. For type 1 and 2, complete procedure name that sent the message. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
Long sending program name. The program name that sent the message.
Message. The text of a predefined message. If an impromptu message is received, this field is blank.
The API can truncate the message to fit the available space. If truncation occurs in the middle of double-byte character set (DBCS) data, the API returns only complete DBCS characters. It ends the data with a DBCS shift-in character.
Message file library specified. The name of the library containing the message file, as specified in the call to this API. If you specify *CURLIB or *LIBL for the library when you send the message, that value is returned as the library here. For the actual library used when the message is sent, see the message file library used field.
Message file library used. The name of the library used to send the message. Because the library can contain override instructions, this is not necessarily the library in which the message actually resides.
Message file name. The name of the message file containing the message received.
Message help. The message help for the message received. If an immediate message is received, this field is blank.
The API can truncate the message help to fit the available space. If truncation occurs in the middle of double-byte character set (DBCS) data, the API returns only complete DBCS characters. It ends the data with a DBCS shift-in character.
Message identifier. The identifying code of the message received. If an immediate message is received, this field is blank.
Message key. The key to the message received. The key is assigned by the command or API that sends the message. If the message action parameter specifies *REMOVE, this field is blank.
Message severity. The severity of the message received. Possible values are 0 through 99. If the message being received is an immediate message, the message severity is not returned.
Message type. The message type of the message received. The possible values and their meanings are:
| Value | Message Type |
|---|---|
| 01 | Completion |
| 02 | Diagnostic |
| 04 | Informational |
| 05 | Inquiry |
| 06 | Sender's copy |
| 08 | Request |
| 10 | Request with prompting |
| 14 | Notify |
| 15 | Escape |
| 16 | Notify, exception not handled when API is called |
| 17 | Escape, exception not handled when API is called |
| 21 | Reply, not validity checked |
| 22 | Reply, validity checked |
| 23 | Reply, message default used |
| 24 | Reply, system default used |
| 25 | Reply, from system reply list |
| 26 | Reply, from exit program |
Microseconds. The microseconds part of the time sent.
Name of the procedure receiving the message. This field is blank if the message was received by an original program model (OPM) program.
Number of statement numbers or instruction numbers available for the receiving program or procedure. For OPM programs and nonoptimized procedures, this count is 1. For optimized procedures, this count can be greater than 1. In this case, each statement number represents a potential point at which the message could have been received. If the mapping table information is removed from the program, this field returns a count of zero and no statement numbers are available.
Number of statement numbers or instruction numbers available for the sending program or procedure. For OPM programs and nonoptimized procedures, this count is 1. For optimized procedures, this count can be greater than 1. In this case, each statement number represents a potential point at which the message could have been sent. If the mapping table information is removed from the program, this field returns a count of zero and no statement numbers are available.
Receiving module name. For type 1 and 2, the name of the module receiving the message.
Receiving procedure name. For type 1 and 2, the name of the procedure receiving the message. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
Receiving program name. The name of the program receiving the message, or the Integrated Language Environment (ILE) program name that contains the procedure receiving the message.
Receiving program's statement number or instruction number. This field can contain up to three statement numbers or instruction numbers. When the receiving type is 1 or 2, the field contains statement numbers. When the receiving type is 0, this field contains an instruction number. Each statement number can be up to 10 characters in length. The instruction number is 4 characters in length. Each statement number or instruction number is left-justified in a 10-character partition of the 30-character field. The first statement number or instruction number is in the leftmost 10 characters and the third in the rightmost 10 characters. The unused parts of this field are set to blanks.
Receiving type. The type of program that received the message. Valid values follow:
| 0 | The message was sent to an original program model (OPM) program. |
| 1 | The message was sent to a procedure within an ILE program, and the procedure name is up to and including 256 characters in length. |
| 2 | The message was sent to a procedure within an ILE program, and the procedure name is from 257 characters up to and including 4096 characters in length. For this type, the receiving procedure name is blank, and the name can be obtained from the long receiving procedure name. |
Replacement data or impromptu message text. The values for substitution variables in a predefined message, or the text of an impromptu message. If the message identifier is not blank, this field contains message data. If the message identifier is blank, this field contains impromptu message text.
If this field contains message data that contains pointer data, each pointer must start on a 16-byte boundary. If you are running at security level 50, the pointer data is invalidated.
The API can truncate the data or text to fit the available space. If the field contains the text of an impromptu message and is truncated in the middle of double-byte character set (DBCS) data, the API returns only complete DBCS characters. It ends the data with a DBCS shift-in character. However, if the field contains data for a predefined message, the API does not check for DBCS data. This is because message data can contain pointers, and pointers can contain the same characters used to mark DBCS data.
Reserved. An ignored field.
Sending job. The name of the job in which the message being received was sent. Because the sending job also must be the receiving job for call message queues, this field is always blank.
Sending job's number. The job number of the job in which the message being received was sent. Because the sending job also must be the receiving job for call message queues, this field is always blank.
Sending job's user profile. The name of the user profile in the qualified job name of the job that sent the message being received. Because the sending job also must be the receiving job for call message queues, this field is always blank.
Sending module name. For type 1 and 2, the name of the module that contains the sending message.
Sending procedure name. For type 1, the name of the procedure sending the message. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
Sending program name. The program name or ILE program name that contains the procedure sending the message. This field is blank if the sending type is 3.
Sending program's instruction number. The number of the program instruction that issued the command or called the API used to send the message being received.
Sending program's statement numbers or instruction numbers. This field can contain up to three statement numbers or an instruction number. When the sending type is 0 or 3, this field contains an instruction number. The instruction number is 4 characters in length of original program model (OPM) programs and 6 characters in length for System Licensed Internal Code (SLIC) programs. For all other sending types, this field contains statement numbers. Each statement number can be up to 10 characters in length. The instruction number is 4 characters in length. Each statement number or instruction number is left-justified in a 10-character partition of the 30-character field. The first statement number or instruction number is in the leftmost 10 characters and the third in the rightmost 10 characters. The unused parts of this field are set to blanks.
Sending type. The type of the sender (whether it is a program or procedure). Possible values and their meanings are as follow:
| 0 | Sender is an original program model (OPM) program or a System Licensed Internal Code (SLIC) program with up to and including 12 characters in its name. |
| 1 | Sender is a procedure within an ILE program, and the procedure name is up to and including 256 characters in length. |
| 2 | Sender is a procedure within an ILE program, and the procedure name is from 257 characters up to and including 4096 characters in length. For this type, the sending procedure name is blank and the name can be obtained from the long sending procedure name. |
| 3 | Sender is a SLIC program with 13 or more characters in its name. For this type, the sending program name is blank, and the name can be obtained from the long sending program name. |
Sending user profile. The name of the user profile that the thread was running under when the message was sent.
Time sent. The time at which the message being received was sent, in HHMMSS (hour, minute, second) format.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24A3 E | Value for call stack counter parameter not valid. |
| CPF24A7 E | Value for the length of message information not valid. |
| CPF24A8 E | Value for wait time not valid. |
| CPF24A9 E | Value for message action not valid. |
| CPF24AF E | Message key not allowed with message type specified. |
| CPF24B9 E | When call stack entry name is '*' or '*CTLBDY', module name and program name must be '*NONE'. |
| CPF24BF E | Module or bound-program name is blank. |
| CPF24B1 E | Message key required for message type specified. |
| CPF24B2 E | Message key of *TOP requires message type of *NEXT. |
| CPF24B3 E | Message type &1 not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24B7 E | Value &1 for call stack entry name length not valid. |
| CPF24CE E | Qualifier &1 incorrect for use with pointer. |
| CPF24C5 E | Pointer to call stack entry not valid. |
| CPF24C6 E | Value of To call stack entry data type parameter not valid. |
| CPF2401 E | Not authorized to library &1. |
| CPF2407 E | Message file &1 in &2 not found. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF2411 E | Not authorized to message file &1 in &2. |
| CPF2415 E | End of requests. |
| CPF2422 E | Reply not valid. |
| CPF2423 E | Variable specified in SENDER parameter less than 80 bytes. |
| CPF2449 E | Message that should be a reply, is not a reply. |
| CPF247A E | Call stack entry not found. |
| CPF247E E | CCSID &1 is not valid. |
| CPF2479 E | Call stack entry not found. |
| CPF2531 E | Message file &1 in &2 damaged for &3. |
| CPF2548 E | Damage to message file &1 in &2. |
| CPF2551 E | Message key and message type combination not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| 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. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1.1