Entry Specifications

XCF passes information to the message notify user routine in registers and in a parameter list.

Registers at Entry: when the message notify user routine receives control, the GPRs contain:

Register: Contents
0: Used as a work register by the system.
1: Address of the message notification parameter list (MNPL).
2-12: Used as work registers by the system.
13: Address of a 144-byte work area. The message notify user routine does not have to save and restore XCF's registers in this work area. The message notify user routine can use this work area in any way it chooses.
14: Return address
15: Entry point address of message notify user routine.

When the message notify user routine receives control, the ARs do not contain any information for use by the message notify user routine.

The message notification parameter list (MNPL), mapped by IXCYMNPL, contains a header record followed by zero or more data records. Information in the header record indicates the type of notification data that follows.

The header record contains the following information:

MNPLVERSION: The version number of the parameter list.
MNPLTYPE: The type of notification that is being presented. Note that new types of notification might be provided in future releases. Your message notify user routine should be written to tolerate any future changes or additions. In the initial version of the MNPL, the type of notification is the completion of a message-out request.
MNPLFLAGS: Flags to describe characteristics of the notification or its presentation.
MNPLMEMTOKEN: The member token of the member to which this notification is presented.
MNPLMEMDATA: A copy of the contents of the field specified by the MEMDATA parameter on the IXCJOIN macro when this member joined the XCF group, or zeros if the parameter was omitted.
MNPLEXITPARMS: User exit parameters. If the member invoked the IXCMSGC Call Exit service to call the message notify user routine, this is a copy of the data specified by the EXITPARMS parameter on the IXCMSGC macro. Otherwise, it contains zeros.
MNPL#DATARECORDS: The number of data records provided.
MNPLDATARECOFFSET: Offset from the start of the header record at which the first data record can be found.

The data record contains the following information:

MNPLRECTYPE: The type of data described in this record. In the initial version of the MNPL, the types of data supported are MSGOUT data and MEMBER data.
MNPLRECLEN: The number of bytes in this data record.
MNPLRECDATA: The variable content of the data record. The contents are a MSGOUT data record.

For a MSGOUT data record, the record contains the following information:

MNPLMSGOTOKEN

Token to identify this message and any associated responses to XCF services, such as IXCMSGC.

MNPLMSGOUSERDATA

User data associated with the message. This is a copy of the contents of the USERDATA parameter when the IXCMSGOX macro was invoked to send the message or as modified by the IXCMSGC macro when the message was saved or completed.

MNPLMSGOFLAGS

Flags to describe characteristics of the message. The information includes:

Whether the sender requested notification of message completion by an XCF-scheduled message.
Whether a broadcast request completed successfully.
Whether the message was saved.
Whether XCF had to access user storage describing or containing the message even after IXCMSGOX returned to the caller.

MNPLMSGOMLEN

Number of bytes of message data for the message-out request.

MNPLMSGOSOURCE

The member token of the sending member.

MNPLMSGOMSGCNTL

The message control information from the message-out request.

MNPLMSGO#TARGETS

Number of targets for the message (including skipped targets).

MNPLMSGOTBLPTR

Address of the table containing target/response information for this message. MNPLMSGOENTTYPE indicates which type of entries the table contains.

MNPLMSGOENTTYPE

Code that identifies which mapping to use for the entries in the table of target/response data. The entries are either target only entries or target/response entries. A target only entry describes the result of a send to one particular target member. A target/response entry describes the result of a send to and response from one member.

MNPLMSGOENTLEN

Length in bytes of an individual entry in the table containing target/response information.

For a MEMBER data record, the record contains the following information:

MNPLMEMBERMNAME: The member name.
MNPLMEMBERSYSNAME: The member token.
MNPLMEMBERSYSID: The name of the system on which the member resides. The system name is made up of the system token and the system slot number.

The table of target/response information contains either target only entries or target/response entries.

A target only entry contains the following information:

MNPLTOTARGET: Target member token.
MNPLTOSENDSTATUS: Status of the message send request.
MNPLTOSENDRETCODE: Return code from the IXCMSGOX macro about the send message request to this particular target member.
MNPLTOSENDRSNCODE: Failing reason code from the IXCMSGOX macro. Only valid if MNPLTOSENDRETCODE is nonzero.

A target/response entry contains the following information:

MNPLTRTARGET: Target member token.
MNPLTRSENDSTATUS: Status of the message send request.
MNPLTRSENDRETCODE: Return code from the IXCMSGOX macro about the send message request to this particular target member.
MNPLTRSENDRSNCODE: Failing reason code from the IXCMSGOX macro. Only valid if MNPLTRSENDRETCODE is nonzero.
MNPLTRRESPSTATUS: Status of response message.
MNPLTRRESPCODE: Code to explain why XCF believes the response was not received. Only valid if XCF did not receive a response.
MNPLTRRESPMLEN: Total number of bytes of message data remaining for delivery with the IXCMSGIX macro. The length is accurate only on entry to the message notify user routine. It is not updated while the user routine is running to reflect any partial deliveries performed by the routine. Only valid if the associated response is still available, that is, it has been received and has not been delivered, saved, or discarded.
MNPLTRRESPSRCE: Member token of the originator of the response. Only valid if XCF received a response.
MNPLTRRESPCNTL: The contents of the MSGCNTL parameter from the originator of the response. Only valid when XCF received a response.
MNPLTRMSGITOKEN: Token to identify the response message. Specify this value for the TOKEN parameter when invoking the IXCMSGIX macro or the IXCMSGC macro to process this response message. Only valid if the associated response is available.
MNPLTRRESPONSEID: Message response ID. Specify this value for the RESPONSEID parameter when invoking the IXCMSGOX macro to reply to this response message. Only valid if the sender requested that XCF manage the gathering of responses to this message.

See z/OS® MVS™ Data Areas in the z/OS Internet library for more information about the IXCYMNPL mapping macro.