Home

 

Channel send and receive exit programs

 

We can use the send and receive exits to perform tasks such as data compression and decompression. In WebSphere MQ V6.0 on all platforms, and with WebSphere MQ clients, we 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:

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

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

  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. If compression is turned on for the channel, the exits will be passed compressed data.

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

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

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

  6. 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 1 shows the data that appears in byte 10 of the channel flow when an API call is being processed.

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

    Identifying API calls
    API call Value of byte 10 for request Value of byte 10 for reply
    MQCONN (6.a, 6.b) X'81' X'91'
    MQDISC (6.a) X'82' X'92'
    MQOPEN (6.c) X'83' X'93'
    MQCLOSE X'84' X'94'
    MQGET (6.d) X'85' X'95'
    MQPUT (6.d) X'86' X'96'
    MQPUT1 request (6.d) 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:

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

    2. MQCONNX is treated in the same way as MQCONN for the purposes of the client-server connection.

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

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

 

Parent topic:

What are channel-exit programs?


ic17510_


 

Home