The storage area specified by ANSAREA must either be in the caller's primary address space or in an address 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 output area where IXCMSGC is to return the requested information.

The length of the answer area must be large enough to contain a complete header record (mapped by MQAHEADER). If the answer area is not large enough to contain all the available data records, data collection stops. The header record indicates how much storage would have been needed to collect all the data for the request (field MQAHDRTLEN). Note that the amount of storage needed to collect all the data can change by the time a new query is attempted.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field, or a decimal value, that contains the length in bytes of the answer area.

DATATYPE=MSGOUT

Collect summary information about messages sent by the member through the message-out service (IXCMSGO). The data returned for each message includes:

• A token that identifies the message
• User data associated with the message
• Status of the message.

This data is mapped by the MQAMSGOUTSUMMARY record defined in IXCYMQAA.

Note that a message reported by this query might not exist by the time the member making the query request attempts to use the message token returned in the answer area. For example, a message that was incomplete at the time of the query could complete and be processed by a message notify user routine before the member could use the message token returned from the query.

DATATYPE=MSGIN

Collect summary information about incoming messages that the member saved. Information is collected for messages that were saved by the message user routine or for responses saved by the message notify user routine. The data returned for each message includes:

• A token that identifies the message
• User data associated with the message
• The member token of the member that sent the message.

This data is mapped by the MQAMSGINSUMMARY record defined in IXCYMQAA.

DATATYPE=DETAIL

Collect detail information about the message identified by the TOKEN parameter. The data returned for the message depends on the type of message.

• For a message-out request, the data returned includes:
  • A token that identifies the message
  • User data associated with the message
  • Number of targets for the message
  • Message control data from the message-out request.
  • Flags to describe the characteristics of the message.
  • A table of response data with an entry for each possible target. The entry describes the result of the send and the associated response collection (if any). The entry also provides status information about the send, including whether it might require the asynchronous access of user storage.

  This data is mapped by the MQAMSGOUTDETAIL record defined in IXCYMQAA.

• For a message saved by the message user routine or for a response saved by the message notify user routine, the data returned includes:
  • A token that identifies the message
  • User data associated with the message
  • The member token of the member that sent the message
  • Message length
  • Message control data from the sender.

  This data is mapped by the MQAMSGINDETAIL record defined in IXCYMQAA.

• For a message user routine, MEPLEXEXITPARMS within the message exit parameter list (mapped by IXCYMEPL) contains a copy of these parameters.
• For a message notify user routine, MNPLEXITPARMS within the message notification parameter list (mapped by IXCYMNPL) contains a copy of these parameters.

The user can define the content and meaning of the 64-bit area. For example, you could use the area to pass the address and ALET of a storage area containing information that determines how the exit routine should perform its processing.

If the user does not specify EXITPARMS, the default is to set the parameters to X'0'.

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

,HOLDTIME=INDEFINITE

The message is to be saved until the message is processed by a CALLEXIT, discarded, or the member ends.

,HOLDTIME=CONTINUE

The currently established HOLDTIME for the message is to continue to be in effect. CONTINUE can only be specified if a message has previously been saved.

,HOLDTIME=SET

A finite HOLDTIME specified by the TIME keyword is to be assigned and set by XCF for the message. SET can be used to establish an initial HOLDTIME for a saved message or be used to modify the HOLDTIME for a message.

,TIME=xtime

The name (RS-type), or address in register (2)-(12), of a required halfword input that indicates the number of seconds, starting from the time the SAVEMSG request is processed, XCF is to keep a saved message before discarding the message. The xtime value must in the range 1 - 65535.

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.

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.

Note that MSGEXIT is mutually exclusive with NOTIFYEXIT.

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

The position of each bit in MSGTAGMASK corresponds to the same bit position in MSGTAGFILTER and in the message tag associated with a message. For example, if bit n in MSGTAGMASK is 1, bit n of MSGTAGFILTER is to be compared to bit n of the message tag associated with a message. If bit n in MSGTAGMASK is 0, then the corresponding bit in MSGTAGFILTER is not to be used for comparison. If all bits selected by MSGTAGMASK are equal and the message passes all other filter criteria, data associated with the message is to be collected.

Specifying a MSGTAGMASK where all the bits are zero indicates that the MSGTAGFILTER is always a match, and data for messages that pass all other filter criteria is to be collected. The storage area indicated by MSGTAGMASK must either be in the caller's primary address space or in an address/data space that is addressable through a public entry on the dispatchable unit access list (DU-AL) of the caller, or in a common area data space. The default is MSGTAGFILTER= ALL, which means that all bits in the MSGTAGFILTER need to be compared.

Note that NOTIFYEXIT is mutually exclusive with MSGEXIT.

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

REQUEST=SAVEMSG

Save the message for later processing. This request is valid only when invoked from a message user routine or a message notify user routine. Use the TOKEN parameter to identify the message that is to be saved. If the user routine neither saves the message with the SAVEMSG service nor receives the message with the IXCMSGI service, the system automatically discards the message when the user routine gives up control.

A message notify user routine can save the entire message-out request including any available responses and can save individual responses as independent messages. A message user routine can save its message.

Once the user routine saves the message, the system invalidates the message token passed through the TOKEN keyword. Thus, the message is no longer available to the user routine because both the IXCMSGI service and the IXCMSGC service will reject requests that attempt to use the invalidated token. You can process a saved message by invoking the IXCMSGC REQUEST=CALLEXIT service.

The system automatically discards saved messages when the member becomes not active. An active member can discard its saved message by invoking the IXCMSGC REQUEST=DISCARDMSG service.

When a message is saved from within a message user routine, only the undelivered portion of the message is saved along with the data required to create a new message exit parameter list (MEPL). Once a member has received message data into the member's buffer area, the message data is considered delivered. The delivered part of the message cannot be redelivered (with REQUEST=CALLEXIT) nor can it be saved. When a partially delivered message is saved, only the undelivered portion of the message is saved for later retrieval by the REQUEST=CALLEXIT service.

When a message with or without its associated responses is saved from within a message notify user routine, the message and its associated responses can be saved as a single entity or each individual response can be saved independently of the message or both.

• When saved as a single message/response entity, the undelivered portion of the responses is saved along with the data required to create a new message notification parameter list (MNPL). The token, passed by the TOKEN parameter, identifying the message is invalidated, as well as all the message tokens identifying the individual responses, if any, associated with the message (MNPLTRMSGITOKEN). The saved message/response entity can be processed at a later time by a message notify user routine specified on the IXCMSGC REQUEST=CALLEXIT service.
• When an individual response is saved as an independent message, the undelivered portion of the responses is saved along with the data required to create a new message exit parameter list (MEPL). The message token passed with the TOKEN parameter is invalidated. Note that a saved response is considered an independent message and must be processed as such with a message user routine specified on the IXCMSGC REQUEST=CALLEXIT service.

REQUEST=DISCARDMSG

Discard the message identified by TOKEN or SENDTOKEN. A discarded message is no longer available for processing:

• Usage with the IXCMSGI(X) and IXCMSGO(X) macros

  A discarded message is no longer available for processing. For example, XCF does not deliver a discarded message to any exit routine and the message is not visible to the message control QUERYMSG service. Any responses that are still associated with a message/response entity are discarded; however, saved responses are not discarded because saving a response causes the response to become disassociated from the message/response entity.

  If an exit routine does not explicitly save a message or if the message is not received by the IXCMSGI(X) macro, XCF automatically discards the message when the exit routine gives up control. Therefore, most members do not need to use REQUEST=DISCARDMSG on the macro from within an exit routine if they do not want to process the message. (Letting XCF discard the message automatically is preferable to discarding from within an exit routine because the automatic discard by XCF has less system processing overhead.)

  If a message is discarded while an exit routine is processing the message, attempts that the exit routine makes to process the message through XCF macros are rejected with a return/reason code. Depending on the timing, the current operation that the exit is performing might be permitted to complete before the message is discarded. In such a case, IXCMSGC REQUEST=DISCARDMSG returns to indicate that the discard of the message is pending.

  You can discard incomplete message-out requests before the message completes. For example, a message queued by XCF because of a lack of signalling resource or a message whose XCF-managed response collection is not complete can be discarded. Such a discard has the effect of cancelling the message-out request. For a broadcast to multiple targets, XCF does not send any remaining messages that have not yet been sent and discards any collected responses. XCF also discards any responses that arrive for the cancelled message, and the system does not call the notification exit for the cancelled message. If XCF has initiated a send to a particular target member before the message cancellation, it delivers any of those messages as usual.

• Usage with the client/server IXCSEND and IXCRECV macros.

  For XCF IXCSEND messages identified by SENDTOKEN, responses to a discarded message cannot be retrieved using the IXCRECV service. Status information about the message is no longer available. Undelivered responses that arrived before the message was discarded are no longer available. Subsequently arriving responses are discarded. Discarding a message releases a blocking receive initiated for that message. That is, if a unit of work has issued IXCRECV REQTYPE=BLOCKING to receive a message, and another unit of work issues IXCMSGC REQUEST=DISCARDMSG to discard the message, the blocked receiver is resumed and receives a return and reason code indicating that the message was not found. No data will be returned in the answer area for the resumed IXCRECV request.

  Use the XCF message control completion service to force a message-out or client/server request to be stopped in a way that preserves the request for further processing by the member or IXCRECV.

To force a message-out or a client/server request to be stopped in a way that preserves the request for further processing by the member or by IXCRECV, use the IXCMSGC REQUEST=COMPLETION.

REQUEST=QUERYMSG

Return information appropriate for the requested type of query in the storage area specified by ANSAREA. The DATATYPE parameter specifies the type of information requested. The contents of the answer area are mapped by IXCYMQAA. Use the length and offsets provided in the IXCYMQAA records to ensure compatibility with additional data provided in the future.

REQUEST=COMPLETION

Complete the message identified by the TOKEN parameter. You can request COMPLETION for a message-out request that XCF has accepted for delivery, but does not yet consider complete.

A message is considered complete in the following situations:

• A message-out request is considered complete if it times-out or if the REQUEST=COMPLETION service is used to force its completion.
• A message with response is considered complete when one or more of the expected responses arrive.
• A message without response is considered complete as soon as XCF has initiated the send of the message.
• A message broadcast to multiple targets is considered complete when XCF has initiated the send of the message to every valid target member.

Once completed, processing for the message continues just as if it completed without direct intervention. XCF no longer attempts to send the message to any intended target. XCF discards any responses to the message that subsequently arrive. If notification was to be provided upon completion of the message, the message notify user routine receives control.

Consider the following usage of IXCMSGC requests:

• For a message-out request: The user notify exit receives control. If not, you can use REQUEST=CALLEXIT to call a user notify exit routine.
• For an XCF client/server request: Undelivered responses that arrive before the message is forced to complete remain available. Any responses arriving after the message is considered to be complete are discarded. Completing a message releases a blocking initiated for that message; that is, if a unit of work has issued IXCRECV REQTYPE=BLOCKING to receive a message and another unit of work issues IXCMSGC REQUEST=COMPLETION to force that message to completion, the blocked receiver is resumed and receives any responses that have arrived up to that point.

If a unit of work has issued IXCMSGOX with MSGACCESS=SYNCSUSPEND or a client/server request (IXCSEND) and the unit of work is paused by XCF, the service invoker can receive a return and reason code indicating that the request may not have completed sending the message to all intended targets.

Use the REQUEST=DISCARDMSG service to force a message-out or client/server request to be stopped in a way that makes the message unavailable for further processing.

To force a message-out request to be stopped so that the message is not available for further processing, use REQUEST=DISCARDMSG (for example, to prevent the notify exit from getting control even though it was requested on the IXCMSGO macro.)

REQUEST=CALLEXIT

Call a user routine to process the message identified by the TOKEN parameter. The message can be a saved message or a completed message-out request. The type of user routine must be appropriate for the message.

• Use a message user routine to process messages saved by a message user routine and responses saved by a message notify user routine.
• Use a message notify user routine to process completed message-out requests and saved message and response entities.

A CALLEXIT request first passes control to a system service routine that sets up the appropriate environment, collects information pertinent to the message, and calls the specified user routine. The user routine receives control synchronously — under the same unit of work as the invoker of the CALLEXIT service. After performing whatever processing is required, the user routine returns to the system service routine, which then releases resources as necessary, restores the environment, and returns control to the invoker of the CALLEXIT service.

Only one user routine is allowed to process a particular message at any one time. The system rejects the CALLEXIT request if a user routine is already processing the message.

REQUEST=RELEASEMSG

Release a client/server blocking receive request (IXCRECV), a client/server send message request (IXCSEND), or a message-out request (IXCMSGOX) issued with the MSGACCESS=SYNCSUSPEND keyword.

If a unit of work has issued IXCRECV REQTYPE=BLOCKING to receive the results of an XCF client/server message, and another unit of work issues IXCMSGC REQUEST=RELEASEMSG, the blocked receiver is resumed, and the receiver receives a return and reason code indicating that the receive request is released. Data is not returned in the answer area or the data area for the released IXCRECV request. The message persists for the HOLDTIME value specified on the IXCSEND macro service, and a subsequent IXCRECV can be issued to receive the message information.

If a unit of work has issued IXCMSGOX with MSGACCESS=SYNCSUSPEND or a client/server request (IXCSEND) and the unit of work is paused by XCF, the service invoker can receive a return and reason code indicating that the request might not complete sending the message to all intended targets. For an IXCMSGOX broadcast or IXCSEND to multiple targets, any remaining unsent messages are not sent. For message-out requests, if notification is to be provided upon completion of the message, the user notify exit receives control; otherwise, the message control CALLEXIT service can be used to call a user notify exit routine.

Note: If XCF initiates a send to a particular target member, the message is delivered. For an IXCSEND request with a HOLDTIME specified, the IXCRECV service macro can be issued to receive the results of the released client/server request.

To Code: Specify the name of a fullword field (or register 2-12 containing the address of the field) to contain the return code.

Pass this token to the DISCARDMSG or CALLEXIT services of IXCMSGC. You can also obtain a token for the message to be passed to these services by invoking the QUERYMSG service of IXCMSGC.

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

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 name of a fullword field (or register 2-12 containing the address of the field) to contain the reason code.

SENDTOKEN=sendtoken is mutually exclusive with TOKEN=token .

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

To Code: Specify the name of a 64-bit field (or register 2-12 containing the address of the field) to contain the member token.

STATUS=SAVED

Collect information about messages that were saved through use of the REQUEST=SAVEMSG service. These messages are the message and response entities saved by the message notify user routine.

STATUS=COMPLETE

Collect information about messages that are completed. A message is considered complete in the following situations:

• A message-out request is considered complete if it times-out or if the REQUEST=COMPLETION service is used to force its completion.
• A message with response is considered complete when the expected response(s) arrive.
• A message without response is considered complete as soon as XCF has initiated the send of the message.
• A message broadcast to multiple targets is considered complete when XCF has initiated the send of the message to every valid target member.

STATUS=INCOMPLETE

Collect information about messages that have not yet completed. For example, the message might have been queued due to an XCF signalling buffer shortage, or in the case of a response-required signal, a response to the message might not have arrived and the message has either not yet timed-out or been forced to completion with IXCMSGC REQUEST=COMPLETION.

• For a saved message, the following fields are used to pass the user data:
  • The field MEPLEXUSERDATA contains the user data passed to a message user routine.
  • The field MNPLMSGOUSERDATA contains the user data passed to a message notify user routine.
• For a completed message, the field MNPLMSGOUSERDATA contains the user data passed to a message notify user routine. Note that the current user data associated with the message is replaced by this user data only if the invocation of the IXCMSGC COMPLETION service causes the message to be considered complete.

To Code: Specify the RS-name or address (using a register from 2 to 12) of the 8-character field that contains the user data to be associated with the message.