Channel send and receive exit programs
You can use the send and receive exits to
perform tasks such as data compression and decompression. In WebSphere MQ Version 6.0 on
all platforms, 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.
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.
Notes:
- 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.
- If compression is turned on for the channel, the exits will be
passed compressed data.
- 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.
- 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.
- 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.
- 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 38 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 38. Identifying API calls
API call |
Value of byte 10 for request |
Value of byte 10 for reply |
MQCONN (1, 2) |
X'81' |
X'91' |
MQDISC (1) |
X'82' |
X'92' |
MQOPEN (3) |
X'83' |
X'93' |
MQCLOSE |
X'84' |
X'94' |
MQGET (4) |
X'85' |
X'95' |
MQPUT (4) |
X'86' |
X'96' |
MQPUT1 request (4) |
X'87' |
X'97' |
MQSET request |
X'88' |
X'98' |
MQINQ request |
X'89' |
X'99' |
MQCMIT request |
X'8A' |
X'9A' |
MQBACK request |
X'8B' |
X'9B' |
xa_start request |
X'A1' |
X'B1' |
xa_end request |
X'A2' |
X'B2' |
xa_open request |
X'A3' |
X'B3' |
xa_close request |
X'A4' |
X'B4' |
xa_prepare request |
X'A5' |
X'B5' |
xa_commit request |
X'A6' |
X'B6' |
xa_rollback request |
X'A7' |
X'B7' |
xa_forget request |
X'A8' |
X'B8' |
xa_recover request |
X'A9' |
X'B9' |
xa_complete request |
X'AA' |
X'BA' |
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.
-
Large messages can exceed the transmission segment
size. If this happens there can be a large number of network flows resulting
from a single API call.
|