Receive Nonprogram Message (QMHRCVM) API
Required Parameter Group:
| 1 | Message information | Output | Char(*) |
| 2 | Length of message information | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified message queue name | Input | Char(20) |
| 5 | Message type | Input | Char(10) |
| 6 | Message key | Input | Char(4) |
| 7 | Wait time | Input | Binary(4) |
| 8 | Message action | Input | Char(10) |
| 9 | Error code | I/O | Char(*) |
Optional Parameter Group 1:
| 10 | Coded character set identifier | Input | Binary(4) |
Optional Parameter Group 2:
| 11 | Allow default reply rejection | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
The Receive Nonprogram Message (QMHRCVM) API receives a message from a nonprogram message queue. To receive a message from a program message queue or from the external message queue, see Receive Program Message (QMHRCVPM) API.
The QSYS2.MESSAGE_QUEUE_INFO view and QSYS2.MESSAGE_QUEUE_INFO table function can be used as alternatives to this API. See MESSAGE_QUEUE_INFO view and MESSAGE_QUEUE_INFO table function for more information.
Authorities and Locks
- Message Queue Authority
- *USE and *DLT if the message action parameter specifies *REMOVE; *USE for
other message actions.
- Message Queue Library Authority
- *EXECUTE
- 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.
- Message Queue Lock
- If a wait time is specified and the API must wait, the message queue is
allocated to the job calling the API for the duration of the wait.
Other jobs on the system can only send messages to the queue during the wait time. Other jobs cannot place the queue in *BREAK or *NOTIFY mode, remove messages from the queue, or do an additional receive message with wait operation during this time.
Required Parameter Group
- Message information
- OUTPUT; CHAR(*)
The variable that receives the information returned, in the format specified by the format name parameter, of the length specified by 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 or RCVM0200 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.
- Qualified message queue name
- INPUT; CHAR(20)
The name of the message queue from which to receive the message, and the library in which it resides. The first 10 characters specify the message queue, and the second 10 characters specify the library. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list You cannot receive messages from the history log, QHST.
- 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 this 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 an inquiry message through the key to the sender's copy of the inquiry. If the reply is not available, no message is returned, and the API does not return an error.
When the message type is the special value *NEXT, you can use the special value *TOP for the message key. *TOP returns the message at the top of the queue.
When the message type is the special value *NEXT or *PRV, you can use hexadecimal zeros for the message key for the first receive operation.
- Wait time
- INPUT; BINARY(4)
The length of time in seconds to wait for the message to arrive in the queue so it can be received.
The system ignores this parameter when you specify both a message key and a message type other than reply (*RPY). The parameter is used in only two cases:
- The message type is reply (*RPY), and the message key parameter specifies
the key to the sender's copy of the message.
- The message type is anything except reply (*RPY), and the message key parameter is blank. In this case, the QMHRCVM API does not use the wait time parameter immediately. First, the API checks the queue for the first message of that type that has not been received. If no such message is found, the API then waits the specified length of time for a message to arrive.
Valid values follow:
0 Do not wait for the message. You must use 0 if you specify a message key and the message is not a reply message. -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 or RCVM0200 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.
- The message type is reply (*RPY), and the message key parameter specifies
the key to the sender's copy of the message.
- 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. The message key is no longer valid, so 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.
- 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
- Coded character set identifier
- INPUT; BINARY(4)
The coded character set identifier (CCSID) in which that you want your message text and replacement data returned. This applies to the message text and the parts of the replacement 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. This is the default value if this parameter is not coded. 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. Only CCSIDs that a job can be changed to are acceptable values. This API will validate the CCSID specified. 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 2
- 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), and *NEXT 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.
All message types listed in the following table 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 or *NEXT. The message with the key specified was found in the queue, but no *PRV or *NEXT message is found.
The message types you can specify in the QMHRCVM API follow:
| Message Type | Message Key | Description |
|---|---|---|
| *ANY | Optional | Receives a message of any type except sender's copy. |
| *COMP | Optional | Receives a completion message. |
| *COPY | Required | Receives the sender's copy of a previously sent inquiry message. The qualified message queue name parameter must specify the reply message queue specified when the inquiry was sent. |
| *DIAG | Optional | Receives a diagnostic message. |
| *FIRST | Disallowed | Receives the first new or old message in the queue. |
| *INFO | Optional | Receives an informational message. |
| *INQ | Optional | Receives an inquiry message. If the message action is *REMOVE and a reply to the inquiry message has not been sent yet, the default reply is automatically sent when the inquiry message is received. |
| *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.
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 to receive the first message on the 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. |
| *RPY | Optional | Receives the reply to an inquiry message. For the message key, you can use the key to the sender's copy of the inquiry or notify message. |
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 message data or 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) | Reserved |
| 97 | 61 | CHAR(7) | Date sent |
| 104 | 68 | CHAR(6) | Time sent |
| 110 | 6E | CHAR(6) | Microseconds |
| 116 | 74 | CHAR(10) | Sending user profile |
| 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 or 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 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 | ||
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 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. |
| 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 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 or text 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 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 replacement data or impromptu message text is returned. If an impromptu message text is received, this is the CCSID of the impromptu message text. When replacement data is received, this is the CCSID of the replacement data fields defined as convertible character (*CCHAR) in the message description. All other replacement data is not converted before it is returned. If a conversion error occurs or the CCSID you requested the data to be converted to is 65535, the CCSID of the data or text is returned. If replacement 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.
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 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 text 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 replacement 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 text 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.
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 name. The name of the message file containing the message received.
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 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 impromptu 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 |
| 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.
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.
Sending job's number. The job number of the job in which the message being received was sent.
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.
Sending program name. The original program model (OPM) program name or ILE bound program name that contains the procedure sending the message.
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 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 |
|---|---|
| CPF24AF E | Message key not allowed with message type specified. |
| 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. |
| 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. |
| CPF2401 E | Not authorized to library &1. |
| CPF2403 E | Message queue &1 in &2 not found. |
| CPF2407 E | Message file &1 in &2 not found. |
| CPF2408 E | Not authorized to message queue &1. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF2411 E | Not authorized to message file &1 in &2. |
| CPF2422 E | Reply not valid. |
| CPF2433 E | Function not allowed for system log message queue &1. |
| CPF2450 E | Work station message queue &1 not allocated to job. |
| CPF2451 E | Message queue &1 is allocated to another job. |
| CPF247E E | CCSID &1 is not valid. |
| CPF2477 E | Message queue &1 currently in use. |
| 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