Description

The IXCMSGOX macro is the interface to the XCF (cross-system coupling facility) message-out service. This interface is the successor to the IXCMSGO macro interface, contains all the functionality of the IXCMSGO message-out macro interface and is the suggested XCF message-out service interface to use.

The IXCMSGOX macro allows a member of an XCF group to send a message to one or more members in its XCF group. IXCMSGOX , and its companion services, IXCMSGIX (message-in service) and IXCMSGC (message control service), comprise the XCF signalling services. The target XCF member can receive the message by issuing the IXCMSGIX macro from within a message user routine it defines when it joins the XCF group. The target member can also save or discard the message by issuing the IXCMSGC macro from within the message user routine. Between pairs of members, you can specify that XCF is to deliver messages to a target member in the same order in which they were sent.

Messages can vary in length up to 134 217 278 (128M) bytes. An IXCMSGOX request to send a "large message" must specify MSGACCESS=ASYNC or MSGACCESS=SYNCSUSPEND. A “large message” is defined to be one that is greater than 62 464 (61K) bytes. XCF handles large messages somewhat differently from messages of less than 61K bytes, and also imposes the following restrictions when sending large messages:

Both sending and target systems must be running OS/390® Release 8 or higher. (This does not necessarily imply that all members residing on those systems support large message delivery.)
Both sending and target members must have specified when they joined their XCF group that they supported large message delivery. (Each must have specified GT61KMSG=YES on the IXCJOIN invocation.)

The following IXCMSGOX error notifications occur if either of the above conditions is not met:

If a target system is not at the appropriate release level, requests to send a large message to a member on that system are rejected with return code X'8', reason code X'340'. If a source system is not at the appropriate release level, requests to send a large message from a member on that system are rejected with return code X'8', reason code X'40'.
If a sending member has not specified support for large message delivery when joining the XCF group, a request to send a large message is rejected with return code X'8', reason code X'C'. If a target member has not specified support for large message delivery when joining the XCF group, a request to send a large message is rejected with return code X'8', reason code X'340'.

You pass the message to the IXCMSGOX service using either a single buffer or multiple buffers. If you are using a single buffer, you need only:

Identify the message buffer using the MSGBUF parameter.
Identify the message length using the MSGLEN parameter.

If you are sending a message that resides in multiple buffers, you have several options for specifying the location and size of the message buffers. For each message buffer, you must describe a message data element. Message data elements can either contain the message buffer or provide a pointer to it. Message data elements can optionally contain the length of the buffer and an ALET to qualify the buffer address (if the buffer is not in message data element).

You can pass the message data elements either organized as a queue or a table. Message buffer lengths and message buffer ALETs can also be passed separately if you do not wish to include them in the message data elements. A message buffer can be in your primary address space, in an address space accessible through your dispatchable unit access list (DU-AL), or in a common area data space. z/OS MVS Programming: Sysplex Services Guide provides a complete description of the different options for passing messages in multiple buffers.

The buffer storage in which the message resides is accessed by XCF when IXCMSGOX is invoked. XCF can access this storage in one of two ways, as specified by the MSGACCESS keyword.

With MSGACCESS=SYNC, XCF accesses the storage synchronously with the message-out request. Once IXCMSGOX returns to the sender, the sender can dispose of the storage that contained either the message or the queue or table that defined the parts of the message.
Note that a request to send a message longer than 61K bytes will be rejected with return code X'8', reason code X'C' when MSGACCESS=SYNC is specified.

With MSGACCESS=SYNCSUSPEND, a request to send a message in the decimal range of 0 to 134 217 728 (128M) bytes long can be made synchronously. As needed, XCF can suspend the current unit of work for a specified amount of time in order to complete accessing storage areas associated with message text. As with MSGACCESS=SYNC, once IXCMSGOX returns to the sender, the sender can dispose of the storage that contained either the message or the queue or table that defined the parts of the message.

MSGACCESS=SYNCSUSPEND is useful for senders that want to send messages that are greater than 61K in length, can tolerate having their unit of work possibly suspended and that would like to release storage resources that contained message text, and queue or table elements that defined parts of the message prior to the completion of the message.
With MSGACCESS=ASYNC, XCF can access the storage even after IXCMSGOX returns to the sender. If IXCMSGOX returns with return code X'4', reason code X'410', the sender must preserve the storage containing the message text as well as the queue or table that defined the parts of the message until the message is completed. To determine when a message is complete, either
- Wait for XCF to notify the sender via the message notify user routine.
- Invoke the IXCMSGC service. (IXCYMQAA contains an indication as to whether the message has completed.)
With MSGACCESS=ASYNC, you must specify a non-zero TIMEOUT value. See z/OS MVS Programming: Sysplex Services Guide for additional information about specifying a timeout value.
For any other return and reason codes, the sender can dispose of the storage as with MSGACCESS=SYNC or MSGACCESS=SYNCSUSPEND.

Messages you send using IXCMSGOX are delivered asynchronously. A return code of zero from IXCMSGOX indicates that XCF has accepted the message; it does not indicate that the message has been delivered. If it is necessary for the sender to know the message has been received, then it is up to the sender and receiver to maintain a protocol to indicate that the message has been received. Alternatively, the sender can request that the target member is to respond to the message and that XCF is to manage the response or the collection of responses, if the message is sent to more than one target member.

If you do not specify the #MSGPARTS parameter and, while looking for your message data, IXCMSGOX finds more than 65536 consecutive buffers of length zero, IXCMSGOX assumes an error has occurred. The message is not sent, and you receive a return code and reason code indicating the error.

Be sure to read the IXCMSGOX guidance information in z/OS MVS Programming: Sysplex Services Guide. The information presented here assumes you have done so. IXCMSGOX guidance information includes:

Illustrations showing the message data element formats specified by the various IXCMSGOX parameters.
Design considerations relating to the use of signalling services.
Information on designing a protocol for sending and receiving multipart messages.