MQ_CHANNEL_EXIT - Channel exit

This call definition is provided solely to describe the parameters that are passed to each of the channel exits called by the Message Channel Agent. No entry point called  MQ_CHANNEL_EXIT  is actually provided by the queue manager; the name  MQ_CHANNEL_EXIT  is of no special significance since the names of the channel exits are provided in the channel definition MQCD.

This definition is part of the WebSphere MQ Security Enabling Interface (SEI), which is one of the WebSphere MQ framework interfaces.

There are five types of channel exit:

• Channel security exit
• Channel message exit
• Channel send exit
• Channel receive exit
• Channel message-retry exit

The parameters are similar for each type of exit, and the description given here applies to all of them, except where specifically noted.

Syntax

Parameters

The  MQ_CHANNEL_EXIT  call has the following parameters.

ChannelExitParms (MQCXP) - input/output

Channel exit parameter block.

This structure contains additional information relating to the invocation of the exit. The exit sets information in this structure to indicate how the MCA should proceed.

ChannelDefinition (MQCD) - input/output

Channel definition.

This structure contains parameters set by the administrator to control the behavior of the channel.

DataLength (MQLONG) - input/output

Length of data.

When the exit is invoked, this contains the length of data in the AgentBuffer parameter. The exit must set this to the length of the data in either the AgentBuffer or the ExitBufferAddr (as determined by the ExitResponse2 field in the ChannelExitParms parameter) that is to proceed.

The data depends on the type of exit:

• For a channel security exit, when the exit is invoked this contains the length of any security message in the AgentBuffer field, if ExitReason is MQXR_SEC_MSG. It is zero if there is no message. The exit must set this field to the length of any security message to be sent to its partner if it sets ExitResponse to MQXCC_SEND_SEC_MSG or MQXCC_SEND_AND_REQUEST_SEC_MSG. The message data is in either AgentBuffer or ExitBufferAddr.

  The content of security messages is the sole responsibility of the security exits.

• For a channel message exit, when the exit is invoked this contains the length of the message (including the transmission queue header). The exit must set this field to the length of the message in either AgentBuffer or ExitBufferAddr that is to proceed.
• For a channel send or channel receive exit, when the exit is invoked this contains the length of the transmission. The exit must set this field to the length of the transmission in either AgentBuffer or ExitBufferAddr that is to proceed.

If a security exit sends a message, and there is no security exit at the other end of the channel, or the other end sets an ExitResponse of MQXCC_OK, the initiating exit is re-invoked with MQXR_SEC_MSG and a null response (DataLength=0).

AgentBufferLength (MQLONG) - input

Length of agent buffer.

This can be greater than DataLength on invocation.

For channel message, send, and receive exits, any unused space on invocation can be used by the exit to expand the data in place. If this is done, the DataLength parameter must be set appropriately by the exit.

In the C programming language, this parameter is passed by address.

AgentBuffer (MQBYTE×AgentBufferLength) - input/output

Agent buffer.

The contents of this depend upon the exit type:

• For a channel security exit, on invocation of the exit it contains a security message if ExitReason is MQXR_SEC_MSG. If the exit wishes to send a security message back, it can either use this buffer or its own buffer (ExitBufferAddr).
• For a channel message exit, on invocation of the exit this contains:
  • The transmission queue header (MQXQH), which includes the message descriptor (which itself contains the context information for the message), immediately followed by
  • The message data

  If the message is to proceed, the exit can do one of the following:

  • Leave the contents of the buffer untouched
  • Modify the contents in place (returning the new length of the data in DataLength; this must not be greater then AgentBufferLength)
  • Copy the contents to the ExitBufferAddr, making any required changes

  Any changes that the exit makes to the transmission queue header are not checked; however, erroneous modifications may mean that the message cannot be put at the destination.

• For a channel send or receive exit, on invocation of the exit this contains the transmission data. The exit can do one of the following:
  • Leave the contents of the buffer untouched
  • Modify the contents in place (returning the new length of the data in DataLength; this must not be greater then AgentBufferLength)
  • Copy the contents to the ExitBufferAddr, making any required changes

  Note that the first 8 bytes of the data must not be changed by the exit.

ExitBufferLength (MQLONG) - input/output

Length of exit buffer.

On the first invocation of the exit, this is set to zero. Thereafter whatever value is passed back by the exit, on each invocation, is presented to the exit next time it is invoked. The value is not used by the MCA (except in WebSphere MQ for z/OS using CICS for distributed queue management, where a check is made that DataLength does not exceed ExitBufferLength, if the exit is returning data in ExitBufferAddr).

Note:

This parameter should not be used by exits written in programming languages which do not support the pointer data type.

ExitBufferAddr (MQPTR) - input/output

Address of exit buffer.

This is a pointer to the address of a buffer of storage managed by the exit, where it can choose to return message or transmission data (depending upon the type of exit) to the agent if the agent's buffer is or may not be large enough, or if it is more convenient for the exit to do so.

On the first invocation of the exit, the address passed to the exit is null. Thereafter whatever address is passed back by the exit, on each invocation, is presented to the exit the next time it is invoked.

Note:

This parameter should not be used by exits written in programming languages that do not support the pointer data type.

Usage notes

1. The function performed by the channel exit is defined by the provider of the exit. The exit, however, must conform to the rules defined here and in the associated control block, the MQCXP.
2. The ChannelDefinition parameter passed to the channel exit may be one of several versions. See the Version field in the MQCD structure for more information.
3. If the channel exit receives an MQCD structure with the Version field set to a value greater than MQCD_VERSION_1, the exit should use the ConnectionName field in MQCD, in preference to the ShortConnectionName field.
4. In general, channel exits are allowed to change the length of message data. This may arise as a result of the exit adding data to the message, or removing data from the message, or compressing or encrypting the message. However, special restrictions apply if the message is a segment that contains only part of a logical message. In particular, there must be no net change in the length of the message as a result of the actions of complementary sending and receiving exits.

   For example, it is permissible for a sending exit to shorten the message by compressing it, but the complementary receiving exit must restore the original length of the message by decompressing it, so that there is no net change in the length of the message.

   This restriction arises because changing the length of a segment would cause the offsets of later segments in the message to be incorrect, and this would inhibit the queue manager's ability to recognize that the segments formed a complete logical message.

C invocation

exitname (&ChannelExitParms, &ChannelDefinition,
         &DataLength, &AgentBufferLength, AgentBuffer,
         &ExitBufferLength, &ExitBufferAddr);

The parameters passed to the exit are declared as follows:

MQCXP   ChannelExitParms;   /* Channel exit parameter block */
MQCD    ChannelDefinition;  /* Channel definition */
MQLONG  DataLength;         /* Length of data */
MQLONG  AgentBufferLength;  /* Length of agent buffer */
MQBYTE  AgentBuffer[n];     /* Agent buffer */
MQLONG  ExitBufferLength;   /* Length of exit buffer */
MQPTR   ExitBufferAddr;     /* Address of exit buffer */

COBOL invocation

     CALL 'exitname' USING CHANNELEXITPARMS, CHANNELDEFINITION,
                           DATALENGTH, AGENTBUFFERLENGTH, AGENTBUFFER,
                           EXITBUFFERLENGTH, EXITBUFFERADDR.

The parameters passed to the exit are declared as follows:

**   Channel exit parameter block
 01  CHANNELEXITPARMS.
     COPY CMQCXPV.
**   Channel definition
 01  CHANNELDEFINITION.
     COPY CMQCDV.
**   Length of data
 01  DATALENGTH         PIC S9(9) BINARY.
**   Length of agent buffer
 01  AGENTBUFFERLENGTH  PIC S9(9) BINARY.
**   Agent buffer
 01  AGENTBUFFER        PIC X(n).
**   Length of exit buffer
 01  EXITBUFFERLENGTH   PIC S9(9) BINARY.
**   Address of exit buffer
 01  EXITBUFFERADDR     POINTER.

PL/I invocation

call exitname (ChannelExitParms, ChannelDefinition, DataLength,
              AgentBufferLength, AgentBuffer, ExitBufferLength,
              ExitBufferAddr);

The parameters passed to the exit are declared as follows:

dcl ChannelExitParms   like MQCXP;     /* Channel exit parameter
                                          block */
dcl ChannelDefinition  like MQCD;      /* Channel definition */
dcl DataLength         fixed bin(31);  /* Length of data */
dcl AgentBufferLength  fixed bin(31);  /* Length of agent buffer */
dcl AgentBuffer        char(n);        /* Agent buffer */
dcl ExitBufferLength   fixed bin(31);  /* Length of exit buffer */
dcl ExitBufferAddr     pointer;        /* Address of exit buffer */

RPG invocation (ILE)

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     exitname(MQCXP : MQCD : DATLEN :
     C                                        ABUFL : ABUF : EBUFL :
     C                                        EBUF)

The prototype definition for the call is:

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     Dexitname         PR                  EXTPROC('exitname')
     D* Channel exit parameter block
     D MQCXP                        160A
     D* Channel definition
     D MQCD                        1328A
     D* Length of data
     D DATLEN                        10I 0
     D* Length of agent buffer
     D ABUFL                         10I 0
     D* Agent buffer
     D ABUF                            *   VALUE
     D* Length of exit buffer
     D EBUFL                         10I 0
     D* Address of exit buffer
     D EBUF                            *

RPG invocation (OPM)

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALL 'exitname'
     C* Channel exit parameter block
     C                     PARM           MQCXP
     C* Channel definition
     C                     PARM           MQCD
     C* Length of data
     C                     PARM           DATLEN  90
     C* Length of agent buffer
     C                     PARM           ABUFL   90
     C* Agent buffer
     C                     PARM           ABUF    n
     C* Length of exit buffer
     C                     PARM           EBUFL   90
     C* Address of exit buffer
     C                     PARM           EBUF   16

Declare the structure parameters as follows:

     I*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     I* Channel exit parameter block
     IMQCXP       DS
     I/COPY CMQCXPR
     I* Channel definition
     IMQCD        DS
     I/COPY CMQCDR

System/390 assembler invocation

         CALL EXITNAME,(CHANNELEXITPARMS,CHANNELDEFINITION,DATALENGTH, X
               AGENTBUFFERLENGTH,AGENTBUFFER,EXITBUFFERLENGTH,         X
               EXITBUFFERADDR)

The parameters passed to the exit are declared as follows:

CHANNELEXITPARMS   CMQCXPA  ,      Channel exit parameter block
CHANNELDEFINITION  CMQCDA   ,      Channel definition
DATALENGTH         DS       F      Length of data
AGENTBUFFERLENGTH  DS       F      Length of agent buffer
AGENTBUFFER        DS       CL(n)  Agent buffer
EXITBUFFERLENGTH   DS       F      Length of exit buffer
EXITBUFFERADDR     DS       F      Address of exit buffer