ATTRIBUTES=NONE

No special attributes will be associated with the message. The message will be delivered in accordance with normal message delivery practices.

ATTRIBUTES=RECOVERY

The message is a recovery signal being sent as part of a sysplex recovery protocol. The RECOVERY attribute indicates that it is important for the signal to be delivered in a timely manner to ensure that the sysplex recovery protocol can finish as soon as possible, and thereby enable the sysplex to resume normal operation.

ATTRIBUTES=CRITICAL

The message is to be treated as critical to the functionality of the XCF group by the target member.

DELIVERMSG=UNORDERED

The system is to deliver the message as soon as possible. No ordering is imposed on this message with respect to any other message sent by the sending member to the target member.

Given any other message sent by the sending member to the target member, no assumption can be made about the order in which the system will deliver that message and this message.

DELIVERMSG=ORDERED

The system is to impose ordering on this message with respect to other ordered messages sent by the sending member to the target member. The ordering is determined by the order in which the message-out service accepts the messages for delivery. The system presents the ordered messages to the message user routine of the target member in the same order that the messages were accepted for delivery. Delivery of these messages might be delayed to ensure that proper ordering occurs.

Note that the ordering is imposed on messages sent between a particular pair of members. The ordered delivery of messages sent between one particular pair of members is independent of message delivery between any other pair of members.

Use the STREAMID keyword to send messages in independently ordered streams between a particular pair of members. The streams of any one pair of members are independent of the streams of any other pair of members. For a given pair of members, messages within a particular stream are delivered independently of any other stream.

For ordered message delivery to occur, the systems on which the sending member and the target member reside must both be running a release that supports ordered message delivery. If the message is sent to a target member that resides on a release that does not support ordered message delivery, unordered delivery occurs. Use the XCF Query Service (IXCQUERY) to determine whether the ordered delivery protocol is supported for a particular target member.

DELIVERMSG=DUPLICATES

The target member can tolerate receiving the message for multiple times. In general, one should expect exactly one instance of the message to be delivered to each target member. However, if the signalling path over which the message has been sent is restarted or stopped before the signal is known to have been transferred to the target system, this option allows XCF to send the signal again to the target member through an alternate signalling path without first discovering whether the target system had already received the signal.

If the original signal has been transferred to the target system, both the original message and the resent copy are delivered to the target member.

If the signalling path used to send the second instance of the signal is similarly restarted or stopped, XCF will send yet another instance of the signal through an alternate signalling path. Thus specifying DELIVERMSG=DUPLICATES can potentially result in an arbitrary number of copies of the message being delivered to the targeted member.

It is up to the sender to determine whether or not the target member can tolerate duplicate messages. If the message is being broadcast to multiple targets, then every target member must tolerate duplicate copies of the message.

Use this parameter to specify the precision format of the addresses that is located within the message data element at the offsets specified by the PARTPTROFF and NEXTPTROFF keywords. The default is ELEMADDRMODE=31.

Use ELEMADDRMODE=31 to indicate that all of the addresses in message data elements are of 31-bit addressing precision (single word - 4 bytes) and reference only virtual storage below the 2-gigabyte virtual storage bar.

Use ELEMADDRMODE=64 to indicate that all of the addresses in message data elements are of 64-bit addressing precision (double word - 8 bytes) and can reference virtual storage below or above the 2-gigabyte virtual storage bar.

Specifying the PARTOFF parameter indicates that each element contains a buffer. Specifying the PARTPTROFF parameter indicates that each element contains a pointer to a buffer.

Elements must all reside in the same address space or data space — the caller's primary address space, an address space or data space that is accessible through a public entry on the caller's dispatchable unit access list (DU-AL), or a common area data space.

To Code: Use a register from 2 to 12 to specify the RS-type name or address of a required character input area that is the first element containing the data that describes the parts of the message.

Use ELEMFORM=QUEUE to indicate that the message data elements are organized as a queue.

If you omit ENDOFQUEUE, or specify ENDOFQUEUE=ZERO, the default value for the end-of-queue address is zero.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the end-of-queue address.

GETRESPONSE=NO

XCF is not to manage the collection of responses for this message. It is the responsibility of the user to handle any management of responses.

GETRESPONSE=YES

XCF is to manage the collection of responses for this message. When all responses are collected, XCF presents them to the message sender. Note that XCF recognizes situations for which it is not reasonable to expect a response, such as when a target member's system fails.

Response collection is a cooperative effort between XCF and the target members. When XCF presents the message to a target member's message user routine, the parameter list contains the following:

• A flag (MEPLNEEDSRESPONSE in IXCYMEPL) is set to indicate that XCF is managing response collection.
• A response identifier (MEPLRESPONSEID in IXCYMEPL) is provided to allow XCF to identify the message to which the response is to be associated.

After composing the response, the target member replies by invoking the message-out service to send the response to the ORIGINATOR of the message identified by the RESPONSEID. XCF recognizes the message as a response by the particular form of the message-out invocation used to make the reply. When collection of the response(s) has completed, XCF presents the collected response message(s) to the member that originated the GETRESPONSE message-out request through the member's message notify user routine.

For XCF to collect a response, the system on which a target member resides must be running a release that supports XCF-managed response collection. Also, the target member must be capable of participating in this protocol by invoking the message-out service to send its reply in a way that allows XCF to recognize it as a response. XCF sends the message to a target member even if it appears that the member is unable to participate in the XCF response collection. However, XCF does not expect a response from such a member. Use the XCF Query Service (IXCQUERY) to determine whether the XCF-managed response collection protocol is supported for a particular target member.

MEMBERS=TABLE

The sender is providing a table that contains a member token for each intended target member.

The table is an array of entries. Each entry has the same fixed size, and can contain data other than a target member token. The storage location identified by the TARGETS keyword contains the first 64-bit target member token. Subsequent target member tokens are iteratively located by adding the value NEXTTARGETOFF to the address of each member token in turn. The keyword #TARGETS indicates the number of entries in the table.

The table can contain “holes”, that is, entries that contain a target member token of X'0'. XCF will skip these entries, but will preserve the entries so that the TARGETS table has a one-to-one correspondence with any other table that XCF constructs for this request. For example, the “i'th” entry of the TARGETS table would correspond to the “i'th” MQATARGRESPENTRY (or MQATARGONLYENTRY) returned by the XCF Message Control Query Message service (IXCMSGC), or would correspond to the “i'th” MNPLTARGRESPENTRY (or MNPLTARGONLYENTRY) presented to a message notify user routine.

The IXCMSGOX invoker is responsible for maintaining the integrity of the TARGETS table until the Message-out service returns. If a table changes while being processed by the Message-out service, the message might be sent to a different set of targets than expected. Also, the content of the entries in tables constructed by XCF might no longer correspond to the content of the entries in the TARGET table.

MEMBERS=ALL

Send a copy of the message to every active member in the sender's XCF group (includes the sender).

XCF determines the collection of members that are currently active in the sender's XCF group throughout the sysplex. This collection is equivalent to the list of members that would be returned by invoking the XCF Query service IXCQUERY with REQTYPE=IMMEDIATE.

MEMBERS=OTHER

Send a copy of the message to every active member in the sender's XCF group except for the sender.

XCF determines the collection of members that are currently active in the sender's XCF group throughout the sysplex. This collection is equivalent to the list of members that would be returned by invoking the XCF Query service IXCQUERY with REQTYPE=IMMEDIATE, with the sender excluded.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-bit field that contains the member token of the sending member.

MSGACCESS=SYNC

XCF accesses the storage containing the text of the message synchronously with the message-out request. After the message-out service returns, the sender can dispose of the storage containing the message. For multipart messages, the sender can dispose of the storage containing the elements or tables that define the parts of the message as well.

MSGACCESS=ASYNC

XCF is allowed to access the storage containing the text of the message after the message-out request returns to the sender. Note that specifying MSGACCESS=ASYNC does not necessarily imply that XCF will access the storage asynchronously. When possible, XCF will attempt to use synchronous access.

If IXCMSGOX returns with return code X'4' and reason code X'410', the sender must preserve the storage containing the message text until the message is completed. For multipart messages, the elements and tables or queues must be preserved as well. For any other return and reason code, the sender can dispose of the storage as if MSGACCESS=SYNC were specified.

If IXCMSGOX returns with return code X'0', implying that XCF has accepted the message for delivery, and you have specified that the message notify user routine is to receive control when the message is complete, you do not need to preserve the storage containing the message text or the elements and tables or queues. However, the application may have to coordinate responsibility for freeing the message storage area between the sender and the notify exit. The notify exit can determine whether the message storage area had to be preserved by checking the MNPLMSGOASYNCMSGACCESS flag.

If the sending member becomes inactive before an ASYNC message is completed, the message-out service might terminate processing for the message. For example, the message might not be delivered to the target member(s) once the sender becomes inactive. In contrast, with MSGACCESS=SYNC, delivery of messages that were accepted by the message-out service continues even after the sender becomes inactive.

For MSGACCESS= ASYNC or MSGACCESS=SYNCSUSPEND, the length of the message can be in the decimal range of 0 to 134 217 728 (128M) bytes. If the sending member becomes inactive while the unit of work is suspended, the unit of work is to be released and control returned to the caller. The message-out service might end processing for the message. Specifically, the message might not be delivered to one or more of the target members when the sender becomes inactive.

MSGACCESS=ASYNC or MSGACCESS=SYNCSUSPEND must be specified to send message longer than 62 464 (61K) bytes.

See Restrictions for additional information about using MSGACCESS=ASYNC.

MSGACCESS=SYNCSUSPEND

The storage containing the text of the message must be accessed synchronously with the message-uut request. As needed, XCF can suspend the current unit of work for a specified amount of time in order to complete accessing storage areas that are associated with message text. After the message-out service returns, the sender is free to dispose of the storage containing the message. For multipart messages, the sender can dispose of the storage containing the elements and/or tables that define the parts of the message as well. When XCF returns, the message might not be complete.

MSGACCESS=SYNCSUSPEND is useful for senders that want to release storage resources that contained message text and queue or table elements that defined parts of the message before the message completes.

For MSGACCESS= SYNCSUSPEND, the length of the message can be in the decimal range of 0 to 134 217 728 (128M) bytes.

If the sending member becomes inactive while the unit of work is suspended, the unit of work is to be released and control returned to the caller. The message-out service might end processing for the message. Specifically, the message might not be delivered to one or more of the target members when the sender becomes inactive.

MSGACCESS=ASYNC or MSGACCESS=SYNCSUSPEND must be specified to send message longer than 62 464 (61K) bytes.

See Restrictions for additional information about using MSGACCESS=ASYNC.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the storage area containing the message.

• The type of message being sent
• The format of the message
• A sequence number to help detect missing signals when using ordered delivery.

The message control information is passed to the message user routine of the receiving member in the message exit parameter list (MEPL), which is mapped by the IXCYMEPL macro.

If you omit the MSGCNTL parameter, or if you specify MSGCNTL=ALLZERO, the message control information presented to the receiving member consists of zeros.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 32-byte storage area containing the message control information.

• For MSGACCESS=SYNC, the value must be in the decimal range of 0 to 62464 (61K) bytes.
• For MSGACCESS=ASYNC or MSGACCCESS=SYNCSUSPEND, the value can be in the decimal range of 0 to 134 217 728 (128M) bytes. If MSGLEN exceeds 61K, both the sending member and the target member must have specified GT61KMSG=YES when the IXCJOIN macro was invoked to join the group. Use the IXCQUERY service to determine whether a particular target member supports the large message delivery protocol.

The amount of buffer storage you provide must be equal to or greater than the value of MSGLEN.

If you specify MULTIPART=YES, then the sum of the lengths of the parts is the default value.

If you omit MSGLEN, IXCMSGOX determines the message length for you, but performance is reduced.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the length of the message.

If you omit the MSGSTGKEY parameter, or if you specify MSGSTGKEY=ANY, XCF does not verify that the buffers have any particular storage key.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-bit field formatted as kkkkxxxx, where the high-order four bits contain the storage key. The low-order halfword is ignored.

Use MULTIPART=YES to indicate that the message is in one or more buffers.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

The default value, if NEXTTARGETOFF is not specified, is 8 bytes, meaning that each table entry consists of a member token only.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword field containing the number of bytes in an individual table entry.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 31-bit message notify user routine.

NOTIFYIF=COMPLETED

The system is to provide notification when the message is completed. Notification occurs whether the message succeeded or failed.

NOTIFYIF=FAILED

The system is to provide notification only if the message failed.

• A message without response is considered to have failed if the message was not sent to one of the possible target members.
• A message with response is considered to have failed if XCF does not receive a response from every possible target member. (For example, if a message with response is targetted to a member that is no longer active — and therefore, no response is possible — the message is considered to have failed.

  Note that skipped targets are ignored when determining whether the message failed. A skipped target is one whose member token in the TARGETS table is X'0'.

If you omit PARTALET, PARTALETOFF, and PARTALETTBL, the default is PARTALET with an ALET of zero.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the ALET.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of partalettbl.

• When MSGACCESS=SYNC, PARTLEN must be in the decimal range of 0 to 62464 (61K) bytes. The length of the entire message must be in the decimal range of 0 to 62464 bytes.
• When MSGACCESS=ASYNC or MSGACCCESS=SYNCSUSPEND, PARTLEN can be in the decimal range of 0 to 134 217 728 (128M) bytes. The length of the entire message must be in the decimal range of 0 to 128M bytes. If the length of the entire message exceeds 61K bytes, both the sending member and the target member must have specified GT61KMSG=YES when they invoked the IXCJOIN macro to join the group. Use the IXCQUERY service to determine whether a particular target member supports the large message delivery protocol.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the length in bytes of each buffer.

If you specify the length of a buffer as zero, XCF does not use that buffer.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

• When MSGACCESS=SYNC, the length of an individual message part must be in the decimal range of 0 to 62464 (61K) bytes. The length of the entire message must be in the decimal range of 0 to 62464 bytes.
• When MSGACCESS=ASYNC or MSGACCCESS=SYNCSUSPEND, the length of an individual message part must be in the decimal range of 0 to 134 217 728 (128M) bytes. The length of the entire message must be in the decimal range of 0 to 128M bytes. If the length of the entire message exceeds 61K bytes, both the sending member and the target member must have specified GT61KMSG=YES when they invoked the IXCJOIN macro to join the group. Use the IXCQUERY service to determine whether a particular target member supports the large message delivery protocol.

If you specify the length of a buffer as zero, XCF does not use that buffer.

The table specified by PARTLENTBL must begin on a fullword boundary.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of partlentbl.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 24-byte character field containing the XCF response identifier.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the return code.

When using MSGACCESS=SYNCSUSPEND where the calling work unit must be suspended by XCF, the token is stored before the work unit is actually suspended. If it becomes necessary for the sender to leave the suspend before the service routine resumes and returns, some other work unit can use this token to release, discard, or force the completion of the request by invoking the XCF message control service (IXCMSGC). Note that cancelling the send likely implies that the message will not be delivered to all of the intended targets.

The storage area must be in the caller's primary address space, in an address space or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL), or in a common area data space.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 16-byte character output field to contain the token.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the reason code.

SENDTIME is a required input when MSGACCESS=SYNCSUSPEND. If the SENDTIME value expires before the processing that XCF paused for is complete, XCF cancels incomplete send processing, which might result in not all of the desired targets receiving the send request.

The SENDTIME value must be in the range 1 and 32 767 (X'7FFF'). If TIMEOUT is explictly specified on the message-out request , the SENDTIME value must be less than or equal to the TIMEOUT keyword value.

SENDTO=MEMBER

Send the message to the (one) member indicated by TARGET. This type of send is the default.

SENDTO=GROUP

Send the message to a collection of members. This type of send is referred to as a “broadcast”.

Note that a send to GROUP where the collection of members consists of only one member does not necessarily have the same behavior as a send to MEMBER. For example, suppose that in both cases the one target member specified was not a valid target. The system would reject the send to MEMBER request with return code X'08', reason code X'08', indicating that the target was not valid. The system would reject the send to GROUP request with return code X'04', reason code X'404', indicating that the broadcast completed but the send to at least one target was rejected. The send reason code reported for the individual target in the SENDTO=GROUP collection would indicate that the target was not valid.

SENDTO=ORIGINATOR

Send a response message. This is a response to a previously received message that indicated that the sender had requested that XCF manage the gathering of response(s) to that message.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword field containing the stream identification.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-bit field that contains the member token.

The storage area identified by TARGETS must be in the caller's primary address space, in an address space or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL), or in a common area data space.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the storage area containing the table of member tokens for each intended target member.

If the message has not completed before the expiration of the timeout value, the message is declared to be complete. The system then processes the message completion as specified by the NOTIFY keyword.

A nonzero timeout value is required when MSGACCESS=ASYNC is specified.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the halfword field containing the timeout value.

The user data is not presented to the targets of the message.

The default of ALLZERO consists of hexadecimal zeros.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the eight-character field containing the user data.

If you specify the default value (#MSGPARTS=ATLEASTONE), one message part is the minimum, or more as needed to send MSGLEN bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword containing the number of buffers.

The system programmer determines the maximum number of members per XCF group supported by the sysplex when using the XCF format utility (IXCL1DSU) to create the sysplex couple data set for the sysplex. In effect, the message can be broadcast to every member that can successfully invoke IXCJOIN to join the XCF group.

Note that #TARGETS indicates the number of potential targets. A TARGETS table entry that contain a member token of X'0' is considered a potential target and should be included in the #TARGETS count.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword field containing the number of entries in the TARGET table.