System Administration Guide

The retry exit

WebSphere MQ allows you to write a C language retry exit. The exit allows your application to suspend data being sent on a channel when communication is not possible (for example, when the mobile user is traveling through a tunnel or is temporarily out of range of a transmitter).

The retry exit can be associated with a monitor program that can assess whether the IP connection is available for sending data. The exit has to be built into an AIX library (in the same way as any other WebSphere MQ library).

The exit is normally called before a datagram is about to be sent but is also called to provide other useful signals.

The retry exit is called under five different conditions:

When the WebSphere MQ channel is first initialized; the ExitReason variable is set to a value of MQXR_INIT.
When the WebSphere MQ channel is shut down; the ExitReason variable is set to a value of MQXR_TERM.
Before each datagram is sent; the ExitReason variable is set to a value of MQXR_RETRY.
When the end of a batch of messages occurs; the ExitReason variable is set to a value of MQXR_END_BATCH.
The UDP transport layer knows nothing about the end of batches because this is a concept known only at the queue manager level. At this point, however, the transport layer moves from a series of ccxSend() verbs to a single ccxReceive() verb and back again. This change of mode, from ccxSend() to ccxReceive(), is detected and the transport exit is called accordingly.
When an information datagram is received from the remote end of the link; the ExitReason variable is set to a value of MQXR_ACK_RECEIVED.

The following table provides an explanation of the variables.

Variable	Explanation
ExitReason	Reason for invoking the exit (for example MQXR_RETRY).
ExitUserArea	Exit user area. When the exit is first invoked, the user can return a value here. This value is presented in this field for all subsequent invocations of the exit for that channel.
TransportType	Transport type. This always has a value of MQXPT_UDP.
RetryCount	The number of times the data has been retried (zero on first entry to exit).
DataLength	Length of data to be sent (in bytes).
SessionId	Session identifier. This is unique for each channel.
GroupId	Group identifier. Identifies the batch of datagrams currently being sent.
DataId	Data identifier. This is an identifier for each datagram.
ExitResponse	Response from exit. The user fills this in on return with a value (for example, MQXCC_OK).
Feedback	Reserved.

If you want to postpone sending a datagram in response to an ExitReason of MQXR_RETRY, block returning from the exit until it is safe to send the datagram. In all other cases, the return from the exit is immediate.

There are three possible return codes that can be set when returning from the exit:

MQXCC_OK; the normal response.
MQXCC_CLOSE_CHANNEL; in response to an ExitReason of MQXR_RETRY, this closes the channel.
MQXCC_REQUEST_ACK; in response to a ExitReason of MQXR_RETRY, this modifies the datagram about to be sent so that it requests the remote end of the link to send an information datagram back to indicate that the node can be reached. If this datagram arrives, the exit is invoked again with an ExitReason of MQXR_ACK_RECEIVED.
Note: If the datagram fails to arrive at the remote node, for any reason, you have to repeat the request on the next datagram sent.

Other information is available to you when the exit is called (see the file CMQXC.H for full details). An example called REXIT is supplied (see various files called REXIT.*).

You can define the retry exit name, and change the name of the library that contains the exit. The library resides in the same a directory as other WebSphere MQ exits. See WebSphere MQ Intercommunication for general information about WebSphere MQ exits.

You configure the retry exit by editing the qm.ini file.