Use channel exits in IBM MQ .NET

If we use client bindings, we can use channel exits as for any other client connection. If we use managed bindings, we must write an exit program that implements an appropriate interface.


Client bindings

If we use client bindings, we can use channel exits as described in Channel exits. We cannot use channel exits written for managed bindings.


Managed bindings

If we use a managed connection, to implement an exit, you define a new .NET class that implements the appropriate interface. Three exit interfaces are defined in the IBM MQ package:

  • MQSendExit
  • MQReceiveExit
  • MQSecurityExit

Note: User exits written using these interfaces are not supported as channel exits in the unmanaged environment. The following sample defines a class that implements all three: 

class MyMQExits : MQSendExit, MQReceiveExit, MQSecurityExit
{
   // This method comes from the send exit
  byte[] SendExit(MQChannelExit       channelExitParms,
                  MQChannelDefinition channelDefinition,
                  byte[]              dataBuffer
                  ref int             dataOffset
                  ref int             dataLength
                  ref int             dataMaxLength)
  {
     // complete the body of the send exit here
  }
 
 
  // This method comes from the receive exit
  byte[] ReceiveExit(MQChannelExit       channelExitParms,
                     MQChannelDefinition channelDefinition,
                     byte[]              dataBuffer
                     ref int             dataOffset
                     ref int             dataLength
                     ref int             dataMaxLength)
  {
     // complete the body of the receive exit here
  }
 
 
  // This method comes from the security exit
  byte[] SecurityExit(MQChannelExit       channelExitParms,
                      MQChannelDefinition channelDefParms,
                      byte[]              dataBuffer
                      ref int             dataOffset
                      ref int             dataLength
                      ref int             dataMaxLength)
  {
     // complete the body of the security exit here
  }

}

Each exit is passed an MQChannelExit and an MQChannelDefinition object instance. These objects represent the MQCXP and MQCD structures defined in the procedural interface.

The data to be sent by a send exit, and the data received in a security or receive exit is specified using the exit's parameters.

On entry, the data at offset dataOffset with length dataLength in the byte array dataBuffer is the data that is about to be sent by a send exit, and the data received in a security or receive exit. The parameter dataMaxLength gives the maximum length (from dataOffset ) available to the exit in dataBuffer. Note: For a security exit, it is possible for the dataBuffer to be null, if this is the first time the exit is called or the partner end elected to send no data.

On return, the value of dataOffset and dataLength should be set to point to the offset and length within the returned byte array that the .NET classes should then use. For a send exit, this indicates the data that it should send, and for a security or receive exit, the data that should be interpreted. The exit should normally return a byte array; exceptions are a security exit which could elect to send no data, and any exit called with the INIT or TERM reasons. The simplest form of exit that can be written therefore is one which does nothing more than return dataBuffer:

The simplest possible exit body is: 
{
  return dataBuffer;
}


MQChannelDefinition class

The userid and password that are specified with the managed .NET client application are set in the IBM MQ .NET MQChannelDefinition class that is passed to the client security exit. The security exit copies the userid and password into the MQCD.RemoteUserIdentifier and MQCD.RemotePassword fields (see Writing a security exit).

  • Specify channel exits (managed client)
    If you specify a channel name and connection name when creating your MQQueueManager object (either in the MQEnvironment or on the MQQueueManager constructor) we can specify channel exits in two ways.
  • Specify channel exit user data (managed client)
    Channel exits can have user data associated with them. If you specify a channel name and connection name when creating your MQQueueManager object (either in the MQEnvironment or on the MQQueueManager constructor) we can specify the user data in two ways.

Parent topic: Writing and deploying IBM MQ .NET programs