Receiving a Message (IXZXIXRM Macro)

JDUs running in the JES2 or JES3 address space, and JES3 JDUs running in a functional subsystem (FSS) address space, can receive messages. When the system places a message in a JDU's mailbox, the POST exit routine (that you specified on IXZXIXMB POSTXIT= parameter of the IXZXIXSM macro) associated with that mailbox posts the JDU. This posting action notifies the JDU that there is a message to receive.

To receive a message, issue the IXZXIXRM macro. When you issue IXZXIXRM, you must:

Provide the group token that represents the JES XCF member and group.
Identify the mailbox from which you are retrieving the message.
Indicate the type of message you wish to receive. Each time you issue IXZXIXRM, you can receive one of the following:
- Only system event messages that are in the mailbox (MSGFETCH=SYSEVENTS).
- Only acknowledgement messages that are in the mailbox (MSGFETCH=ACKS).
- Only JES- or installation-created messages that are in the mailbox (MSGFETCH=MESSAGES).
  Each segment of a multi-segment message is presented as a single message and all segments are ordered as originally sent. However, individual messages from multiple members might not be ordered in the mailbox in a timestamp order.
- All messages that are in the mailbox (MSGFETCH=ALL) ordered by type as follows:
  1. SYSEVENTS
  2. ACKS
  3. MESSAGES.
Provide a location where the system can return a pointer to the message. The system places this message within the address space from which IXZXIXRM is invoked and stores the buffer pointer in the location you provide by specifying the DATA= parameter.
Provide a location where the system can return the length of the message by specifying the DATALEN= parameter.
Provide a location where the system can return a message token that represents the message you receive. When you acknowledge receipt of a message, you must use the message token that the system returns in the area you specify through the MSGTOKEN= parameter.

Process an aborted message as you would any message. You must receive and acknowledge it. An aborted message is a multi-segment message that was either sent erroneously or incompletely. The error was discovered by the sender prior to sending all segments. The last segment indicates the error with the ABORT_SEGMENT bit set on in the message envelope (mapped by IXZYIXEN). The SEGTYPE=ABORT indication is also propagated to the first segment when the last segment is sent. Typically you will recognize and immediately discard such messages. An acknowledgement, as always, is returned to JES XCF.

Messages can be undeliverable because the receiving mailbox or member does not exist or because a mailbox was cleared or deleted prior to a message being acknowledged. JES XCF provides return and reason codes for REQTYPE=SYNC and ASYNCACK messages that identify the exact cause of the failure. But because the SYNC message causes an MVS wait, JES and JES XCF processing for each is different.

For SYNC messages only, if the mailbox was cleared (through IXZXIXMC) or deleted (through IXZXIXMD), JES XCF eventually provides a return and reason code, but the sender is unable to continue until the return code is returned. Once received, the acknowledgement from IXZXIXMC or IXZXIXMD ends the wait condition, and the sender receives the appropriate return and reason codes.
For ASYNCACK messages only, JES XCF returns system return and reason codes in the message envelope to provide an explanation for why a message was not received. If the mailbox was cleared or deleted, JES XCF eventually provides a return and reason code, but the sender proceeds with other processing until posted to issue an IXZXIXRM call, at which time, the return and reason codes are available in the message envelope. Fields SYSTEM_RETURN_CODE and SYSTEM_REASON_CODE in the message envelope IXZYIXEN are used to indicate this information to the sender.

Refer to Table 1 for the list of system return and reason codes JES XCF can return in the message envelope.