Receive Nonprogram Message (QMHRCVM) API

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

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:

1. The message type is reply (*RPY), and the message key parameter specifies the key to the sender's copy of the message.
   
   
2. 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.

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 CCSIDs: Message Support in the Globalization topic.

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:

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:

RCVM0100 Format

The following table lists the fields returned in the RCVM0100 format. For more information about each item of information, see Field Descriptions.

RCVM0200 Format

The following table lists the fields returned in the RCVM0200 format. For more information about each item of information, see Field Descriptions.

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:

For more information, see the Alerts Support book.

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:

CCSID conversion status indicator for data. The following values may be returned:

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.

Message type. The message type of the message received. The possible values and their meanings are:

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