MQ_CHANNEL_EXIT - Channel exit

The MQ_CHANNEL_EXIT call describes 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 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.

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

    MQ_CHANNEL_EXIT (ChannelExitParms, ChannelDefinition, DataLength,
    AgentBufferLength, AgentBuffer, ExitBufferLength, ExitBufferAddr)


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

    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.

    The data depends on the type of exit:

    • For a channel security exit, when the exit is invoked this parameter 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 parameter 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. This must be greater than or equal to the length of the transmission queue header (MQXQH).
    • For a channel send or channel receive exit, when the exit is invoked this parameter 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 parameter 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 x AgentBufferLength) - input/output

    Agent buffer.

    The contents of this parameter 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. To send a security message back, the exit can either use this buffer or its own buffer (ExitBufferAddr).
    • For a channel message exit, on invocation of the exit this parameter 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 than 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 might 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 than AgentBufferLength)
      • Copy the contents to the ExitBufferAddr, making any required changes

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

    Note: This parameter must 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 parameter 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 buffer of the agent is or might 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.

    If ExitBufferAddr is null the data used is taken from the AgentBuffer parameter.

    If ExitBufferAddr is not null the data used is taken from the buffer pointed to by the ExitBufferAddr parameter.

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


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.


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                            *


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


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 might 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 must 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 can 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 ability of the queue manager to recognize that the segments formed a complete logical message.