What are channel-exit programs?

Channel-exit programs are called at defined places in the processing carried out by MCA programs.

Some of these user-exit programs work in complementary pairs. For example, if a user-exit program is called by the sending MCA to encrypt the messages for transmission, the complementary process must be functioning at the receiving end to reverse the process.

The different types of channel-exit program are described below. Table 52 shows the types of channel exit that are available for each channel type.

Table 52. Channel exits available for each channel type

If you are going to run channel exits on a client, you cannot use the MQSERVER environment variable. Instead, create and reference a client channel definition table as described in the WebSphere MQ Clients book.

Processing overview

On startup, the MCAs exchange a startup dialog to synchronize processing. Then they switch to a data exchange that includes the security exits; these must end successfully for the startup phase to complete and to allow messages to be transferred.

The security check phase is a loop, as shown in Figure 120.

Figure 120. Security exit loop

During the message transfer phase, the sending MCA gets messages from a transmission queue, calls the message exit, calls the send exit, and then sends the message to the receiving MCA, as shown in Figure 121.

Figure 121. Example of a send exit at the sender end of message channel

Figure 122. Example of a receive exit at the receiver end of message channel

The receiving MCA receives a message from the communications link, calls the receive exit, calls the message exit, and then puts the message on the local queue, as shown in Figure 122. (The receive exit can be called more than once before the message exit is called.)

Channel security exit programs

You can use security exit programs to verify that the partner at the other end of a channel is genuine.

Channel security exit programs are called at the following places in an MCA's processing cycle:

• At MCA initiation and termination.
• Immediately after the initial data negotiation is finished on channel startup. The receiver or server end of the channel may initiate a security message exchange with the remote end by providing a message to be delivered to the security exit at the remote end. It may also decline to do so. The exit program is re-invoked to process any security message received from the remote end.
• Immediately after the initial data negotiation is finished on channel startup. The sender or requester end of the channel processes a security message received from the remote end, or initiates a security exchange when the remote end cannot. The exit program is re-invoked to process all subsequent security messages that may be received.

A requester channel never gets called with MQXCC_INIT_SEC. The channel notifies the server that it has a security exit program, and the server then has the opportunity to initiate a security exit. If it does not have one, it sends a null security flow to allow the requester to call its exit program.

Note:

You are recommended to avoid sending zero-length security messages.

WebSphere MQ for AIX, HP-UX, Linux, Solaris, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and the WebSphere MQ client for Windows 95 and Windows 98 supply a security exit program that uses the DCE security services. See Supplied channel-exit programs using DCE security services.

Examples of the data exchanged by security-exit programs are illustrated in figures Figure 123 through Figure 126. These examples show the sequence of events that occur involving the receiver's security exit (left-hand column) and the sender's security exit (right-hand column). Successive rows in the figures represent the passage of time. In some cases, the events at the receiver and sender are not correlated, and therefore can occur at the same time or at different times. In other cases, an event at one exit program results in a complementary event occurring later at the other exit program. For example, in Figure 123:

1. The receiver and sender are each invoked with MQXR_INIT, but these invocations are not correlated and can therefore occur at the same time or at different times.
2. The receiver is next invoked with MQXR_INIT_SEC, but returns MQXCC_OK which requires no complementary event at the sender exit.
3. The sender is next invoked with MQXR_INIT_SEC. This is not correlated with the invocation of the receiver with MQXR_INIT_SEC. The sender returns MQXCC_SEND_SEC_MSG, which causes a complementary event at the receiver exit.
4. The receiver is subsequently invoked with MQXR_SEC_MSG, and returns MQXCC_SEND_SEC_MSG, which causes a complementary event at the sender exit.
5. The sender is subsequently invoked with MQXR_SEC_MSG, and returns MQXCC_OK which requires no complementary event at the receiver exit.

Figure 123. Sender-initiated exchange with agreement

Figure 124. Sender-initiated exchange with no agreement

Figure 125. Receiver-initiated exchange with agreement

Figure 126. Receiver-initiated exchange with no agreement

The channel security exit program is passed an agent buffer containing the security data, excluding any transmission headers, generated by the security exit. This may be any suitable data so that either end of the channel is able to perform security validation.

The security exit program at both the sending and receiving end of the message channel may return one of four response codes to any call:

• Security exchange ended with no errors
• Suppress the channel and close down
• Send a security message to the corresponding security exit at the remote end
• Send a security message and demand a reply (this does not apply on z/OS when using CICS)

Notes:

1. The channel security exits usually work in pairs. When you define the appropriate channels, make sure that compatible exit programs are named for both ends of the channel.

2. In OS/400, security exit programs that have been compiled with "Use adopted authority" (USEADPAUT=*YES) have the ability to adopt QMQM or QMQMADM authority. Take care that the exit does not exploit this feature to pose a security risk to your system.

Channel send and receive exit programs

You can use the send and receive exits to perform tasks such as data compression and decompression. WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS without CICS, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and with WebSphere MQ clients, you can specify a list of send and receive exit programs to be run in succession.

Channel send and receive exit programs are called at the following places in an MCA's processing cycle:

• The send and receive exit programs are called for initialization at MCA initiation and for termination at MCA termination.
• The send exit program is invoked at either end of the channel, immediately before a transmission is sent over the link.
• The receive exit program is invoked at either end of the channel, immediately after a transmission has been taken from the link.

Note:

For WebSphere MQ for z/OS using CICS, only the security exit is called at MCA initiation; other exits are called with the ExitReason parameter set to MQXR-INIT when the first message is sent across the channel.

There may be many transmissions for one message transfer, and there could be many iterations of the send and receive exit programs before a message reaches the message exit at the receiving end.

The channel send and receive exit programs are passed an agent buffer containing the transmission data as sent or received from the communications link. For send exit programs, the first eight bytes of the buffer are reserved for use by the MCA, and must not be changed. If the program returns a different buffer, then these first eight bytes must exist in the new buffer. The format of data presented to the exit programs is not defined.

A good response code must be returned by send and receive exit programs. Any other response will cause an MCA abnormal end (abend).

Note:

Do not issue an MQGET, MQPUT, or MQPUT1 call within syncpoint from a send or receive exit.

WebSphere MQ for AIX, HP-UX, Linux, Solaris, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and the WebSphere MQ client for Windows 95 and Windows 98 supply send and receive exit programs that use the DCE encryption security services. See Supplied channel-exit programs using DCE security services.

Notes:

1. Send and receive exits usually work in pairs. For example a send exit may compress the data and a receive exit decompress it, or a send exit may encrypt the data and a receive exit decrypt it. When you define the appropriate channels, make sure that compatible exit programs are named for both ends of the channel.

2. Channel send and receive exits may be called for message segments other than for application data, for example, status messages. They are not called during the startup dialog, nor the security check phase.

3. Although message channels send messages in one direction only, channel-control data flows in both directions, and these exits are available in both directions, also. However, some of the initial channel startup data flows are exempt from processing by any of the exits.

4. There are circumstances in which send and receive exits could be invoked out of sequence; for example, if you are running a series of exit programs or if you are also running security exits. Then, when the receive exit is first called upon to process data, it may receive data that has not passed through the corresponding send exit. If the receive exit were just to perform the operation, for example decompression, without first checking that it was really required, the results would be unexpected.

   You should code your send and receive exits in such a way that the receive exit can check that the data it is receiving has been processed by the corresponding send exit. The recommended way to do this is to code your exit programs so that:

   • The send exit sets the value of the ninth byte of data to 0 and shifts all the data along one byte, before performing the operation. (The first eight bytes are reserved for use by the MCA.)
   • If the receive exit receives data that has a 0 in byte 9, it knows that the data has come from the send exit. It removes the 0, performs the complementary operation, and shifts the resulting data back by one byte.
   • If the receive exit receives data that has something other than 0 in byte 9, it assumes that the send exit has not run, and sends the data back to the caller unchanged.

   When using security exits, if the channel is ended by the security exit it is possible that a send exit may be called without the corresponding receive exit. One way to prevent this from being a problem is to code the security exit to set a flag, in MQCD.SecurityUserData or MQCD.SendUserData, for example, when the exit decides to end the channel. Then the send exit should check this field, and process the data only if the flag is not set. This prevents the send exit from unnecessarily altering the data, and thus prevents any conversion errors that could occur if the security exit received altered data.

5. In the case of MQI channels for clients, byte 10 of the agent buffer identifies the API call in use when the send or receive exit is called. This is useful for identifying which channel flows include user data and may require processing such as encryption or digital signing.

   Table 53 shows the data that appears in byte 10 of the channel flow when an API call is being processed.

   Note:

   These are not the only values of this byte. There are other reserved values.

   
   

   Table 53. Identifying API calls
   

   API call	Value of byte 10
   MQCONN request (1, 2)	X'81'
   MQCONN reply (1, 2)	X'91'
   MQDISC request (1)	X'82'
   MQDISC reply (1)	X'92'
   MQOPEN request (3)	X'83'
   MQOPEN reply (3)	X'93'
   MQCLOSE request	X'84'
   MQCLOSE reply	X'94'
   MQGET request (4)	X'85'
   MQGET reply (4)	X'95'
   MQPUT request (4)	X'86'
   MQPUT reply (4)	X'96'
   MQPUT1 request (4)	X'87'
   MQPUT1 reply (4)	X'97'
   MQSET request	X'88'
   MQSET reply	X'98'
   MQINQ request	X'89'
   MQINQ reply	X'99'
   MQCMIT request	X'8A'
   MQCMIT reply	X'9A'
   MQBACK request	X'8B'
   MQBACK reply	X'9B'
   Notes: The connection between the client and server is initiated by the client application using MQCONN. Therefore, for this command in particular, there will be several other network flows. This also applies to MQDISC that terminates the network connection. MQCONNX is treated in the same way as MQCONN for the purposes of the client-server connection. If a large distribution list is opened, there may be more than one network flow per MQOPEN call in order to pass all of the required data to the SVRCONN MCA. If the message data exceeds the transmission segment size, there may be a large number of network flows per single API call.

Channel message exit programs

You can use the channel message exit for the following:

• Encryption on the link
• Validation of incoming user IDs
• Substitution of user IDs according to local policy
• Message data conversion
• Journaling
• Reference message handling

WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS without CICS, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and with WebSphere MQ clients, you can specify a list of message exit programs to be run in succession.

Channel message exit programs are called at the following places in an MCA's processing cycle:

• At MCA initiation and termination
• Immediately after a sending MCA has issued an MQGET call
• Before a receiving MCA issues an MQPUT call

The message exit is passed an agent buffer containing the transmission queue header, MQXQH, and the application message text as retrieved from the queue. (The format of MQXQH is given in the WebSphere MQ Application Programming Reference book.) If you use reference messages, that is messages that contain only a header which points to some other object that is to be sent, the message exit recognizes the header, MQRMH. It identifies the object, retrieves it in whatever way is appropriate appends it to the header, and passes it to the MCA for transmission to the receiving MCA. At the receiving MCA, another message exit recognizes that this is a reference message, extracts the object, and passes the header on to the destination queue. See the WebSphere MQ Application Programming Guide for more information about reference messages and some sample message exits that handle them.

Message exits can return the following responses:

• Send the message (GET exit). The message may have been changed by the exit. (This returns MQXCC_OK.)
• Put the message on the queue (PUT exit). The message may have been changed by the exit. (This returns MQXCC_OK.)
• Do not process the message. The message is placed on the dead-letter queue (undelivered message queue) by the MCA.
• Close the channel.
• Bad return code, which causes the MCA to abend.

Notes:

1. Message exits are called just once for every complete message transferred, even when the message is split into parts.

2. In UNIX systems, if you provide a message exit for any reason the automatic conversion of user IDs to lowercase characters does not operate. See User IDs on UNIX systems, Compaq OpenVMS Alpha.

3. An exit runs in the same thread as the MCA itself. It also runs inside the same unit of work (UOW) as the MCA because it uses the same connection handle. Therefore, any calls made under syncpoint are committed or backed out by the channel at the end of the batch. For example, one channel message exit program can send notification messages to another and these messages will only be committed to the queue when the batch containing the original message is committed.

   Therefore, it is possible to issue syncpoint MQI calls from a channel message exit program.

WebSphere MQ for AIX, HP-UX, Linux, Solaris, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp supplies a message exit program that uses the DCE security services. See Supplied channel-exit programs using DCE security services.

Channel message retry exit program

The channel message-retry exit is called when an attempt to open the target queue is unsuccessful. You can use the exit to determine under which circumstances to retry, how many times to retry, and how frequently. (This exit is not available on WebSphere MQ for z/OS.)

This exit is also called at the receiving end of the channel at MCA initiation and termination.

The channel message-retry exit is passed an agent buffer containing the transmission queue header, MQXQH, and the application message text as retrieved from the queue. The format of MQXQH is given in the WebSphere MQ Application Programming Reference book.

The exit is invoked for all reason codes; the exit determines for which reason codes it wants the MCA to retry, for how many times, and at what intervals. (The value of the message-retry count set when the channel was defined is passed to the exit in the MQCD, but the exit can ignore this.)

The MsgRetryCount field in MQCXP is incremented by the MCA each time the exit is invoked, and the exit returns either MQXCC_OK with the wait time contained in the MsgRetryInterval field of MQCXP, or MQXCC_SUPPRESS_FUNCTION. Retries continue indefinitely until the exit returns MQXCC_SUPPRESS_FUNCTION in the ExitResponse field of MQCXP. See MQCXP - Channel exit parameter for information about the action taken by the MCA for these completion codes.

If all the retries are unsuccessful, the message is written to the dead-letter queue. If there is no dead-letter queue available, the channel stops.

If you do not define a message-retry exit for a channel and a failure occurs that is likely to be temporary, for example MQRC_Q_FULL, the MCA uses the message-retry count and message-retry intervals set when the channel was defined. If the failure is of a more permanent nature and you have not defined an exit program to handle it, the message is written to the dead-letter queue.

Channel auto-definition exit program

The channel auto-definition exit can be called when a request is received to start a receiver or server-connection channel but no channel definition exists. The exit applies to WebSphere MQ for AIX, HP-UX, iSeries, Solaris, and Windows, and MQSeries for Compaq Tru64 UNIX, and OS/2 Warp V5.1. You can use it to modify the supplied default definition for an automatically defined receiver or server-connection channel, SYSTEM.AUTO.RECEIVER or SYSTEM.AUTO.SVRCON. See Auto-definition of receiver and server-connection channels for a description of how channel definitions can be created automatically.

The channel auto-definition exit can also be called when a request is received to start a cluster-sender channel. It can be called for cluster-sender and cluster-receiver channels to allow definition modification for this instance of the channel. In this case, the exit applies to WebSphere MQ for z/OS as well as WebSphere MQ for AIX, HP-UX, iSeries, Solaris, and Windows, and MQSeries for Compaq Tru64 UNIX, and OS/2 Warp V5.1. For more information about this, see the WebSphere MQ Queue Manager Clusters book.

As with other channel exits, the parameter list is:

MQ_CHANNEL_AUTO_DEF_EXIT (ChannelExitParms, ChannelDefinition)

ChannelExitParms are described in MQCXP - Channel exit parameter. ChannelDefinition is described in MQCD - Channel definition.

MQCD contains the values that are used in the default channel definition if they are not altered by the exit. The exit may modify only a subset of the fields; see MQ_CHANNEL_AUTO_DEF_EXIT - Channel auto-definition exit. However, attempting to change other fields does not cause an error.

The channel auto-definition exit returns a response of either MQXCC_OK or MQXCC_SUPPRESS_FUNCTION. If neither of these is returned, the MCA continues processing as though MQXCC_SUPPRESS_FUNCTION were returned. That is, the auto-definition is abandoned, no new channel definition is created and the channel cannot start.

Transport-retry exit program

The transport-retry exit applies to WebSphere MQ for AIX, V5.3 and is supported on UDP only. It 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 a mobile user is traveling through a tunnel or is temporarily out of range of a transmitter).

The transport-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 a library that is included in the path in which you are operating.

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.
• 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.

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

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

• MQXCC_OK -- this is the normal response.
• MQXCC_CLOSE_CHANNEL -- in response to an ExitReason of MQXR_RETRY, this will cause the channel to be closed.
• MQXCC_REQUEST_ACK -- in response to an ExitReason of MQXR_RETRY, this will cause the datagram about to be sent to be modified 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 will be invoked again with an ExitReason of MQXR_ACK_RECEIVED.

  Note:

  If the datagram fails to arrive at the remote node, for any reason, you must repeat the request on the next datagram that is sent.

The transport-retry exit name can be defined by the user, who can also change the name of the library that contains the exit. You configure the retry exit by editing the qm.ini file. For more information about editing these files, see the WebSphere MQ System Administration Guide book.