Version 9.6
 —  WMQ RPC Server and Listener  —

Advanced WebSphere MQ Listener Functionality


Support for Request/Reply Scenarios

The WebSphere MQ Listener provides support for a synchronous request/reply scenario. In this case the remote procedure call usually has both INPUT and OUTPUT parameters, or at least one INOUT. A request/reply scenario is automatically detected by the WebSphere MQ Listener if the MQ message specifies the ReplyToQ field.

Top of page

Dynamic IDL/RPC Parameters for WebSphere MQ Listener

With the WebSphere MQ RPC Server it is possible that certain parameters of a remote procedure call are dynamic parameters which are evaluated by the RPC server. Dynamic parameters have a fixed name; they can be defined only on level 1 in the parameter definition in the IDL file and before any variable length parameter, and have a specific format. The WebSphere MQ Listener uses the following parameter:

Parameter Format Description
MQRFH Header data (MQ_RFH_*) A with fixed length Arbitrary number of parameters. The names following the prefix "MQ_RFH_" are used as the names of the name value pairs of the MQRFH header.

If dynamic parameters are to be used, generate a properties file from the corresponding Software AG IDL file and specified with the entirex.bridge.names.file property. To generate this property file, use the template bridge.tpl in the template subdirectory of the EntireX installation. For batch generation, run erxidl.bat (Windows) or erxidl.bsh (UNIX) with the parameters "-t <path to template directory>/bridge.tpl <idlFile>".

Alternatively, you can also use the EntireX Workbench. Go to the Preferences for EntireX and create a new Custom Wrapper. Specify a name and browse to the bridge.tpl template. If the Custom Wrapper has been created (and the Workbench restarted), you can generate the properties file from an IDL file, using the context menu item Generate ... from Software AG IDL.

Top of page

Support for the MQRFH Header

The WebSphere MQ RPC Server supports the MQRFH header (rules and formatting header). This header consists basically of name value pairs. Restriction: only one header per MQ message is possible; MQ allows an arbitrary number of headers per message.

When sending a message to MQ: a MQRFH header is built if at least one parameter in the IDL file has a name with prefix "MQ_RFH_". All IN (or INOUT) parameters with this prefix are used to build the header. If for example the IDL file contains two fields MQ_RFH_H1 and MQ_RFH_H2 with the values "v1" and "v2", the resulting MQRFH header will have two name value pairs, "H1 v1" and "H2 v2".

If a message is received from MQ: if the message has a MQRFH header, all value entries in the name value pairs are copied to the corresponding OUT (or INOUT) parameter in the IDL file. The name has to match the part of the IDL parameter name after the prefix. In the above example consider that the MQ message has two name value pairs, "H1 v11" and "H3 v22". Then the value "v11" will be assigned to the parameter MQ_RFH_H1, the parameter MQ_RFH_H2 gets no value assigned, and the entry for "H3" will be ignored.

Top of page

Character Encoding Issues

When the WebSphere MQ RPC Server is exchanging messages via the EntireX Broker with an RPC client (or server), the usual rules apply. By default, the message is exchanged between the WebSphere MQ RPC Server and EntireX using the platform encoding of the JVM which executes the WebSphere MQ RPC Server.

If the payload of the MQ message is in XML format (property entirex.bridge.xmm has been set), the WebSphere MQ RPC Server converts the XML payload to the encoding used for the RPC request. If the WebSphere MQ RPC Server has to create the XML payload, it will use UTF-8.

If the payload of the MQ message is of type "text", the translation of the MQ message payload is done by the IBM MQ Java classes. When sending a message, the WebSphere MQ RPC Server converts the message to a Unicode string and the MQ classes convert the Unicode string to the encoding specified by the CCSID (Coded Character Set IDentification) of the queue manager. When receiving a message, the IBM MQ Java classes return a Unicode string.

Top of page

User Exit for Message Processing

WebSphere MQ does not have a clearly defined message layout, it is basically a stream of bytes. In general it is up to the MQ application to know the exact semantics of an MQ message. This might include application-specific headers and formatting rules. The WebSphere MQ RPC Server supports a general but simplified model of message processing.

To better handle application specific message layout details, a user exit (or callback routine) can be used. The user exit works on the WebSphere MQ Java representation of an MQ message (class com.ibm.mq.MQMessage) and can change the MQ message. The user exit gets control:

  1. after an MQ message has been read from an MQ queue and before it is processed by the WebSphere MQ Listener

  2. after an MQ message has been constructed by the WebSphere MQ Listener and before the message is put to the MQ queue.

The user exit can be used, for example, for an application-specific processing of the MQRFH, MQRFH2 or even custom headers.

To enable a user exit, use the property entirex.wmqbridge.userexit to specify the class name of the user exit implementation. The class will be loaded using the standard classpath. You can specify a separate classpath with the property entirex.wmqbridge.userexit.classpath. Note that for the classpath a file or HTTP URL must be specified. Your user exit class must implement the Java interface com.softwareag.entirex.rpcbridge.wmqBridgeExit. This Java interface has the following methods:

/**
 ** This method is called after the message has been created by the 
 ** WMQBridge and before the message is sent to an MQ queue (MQPUT).
 ** The Message object and/or the MessageOptions object can be changed.
 **
 ** @param msg The MQ message object.
 ** @param pmo The MQPutMessageOptions object.
 **/
public void beforePut(com.ibm.mq.MQMessage msg, com.ibm.mq.MQPutMessageOptions pmo);
/**
 ** This method is called before a message is retrieved from an MQ 
 ** queue (MQGET). The MessageOptions object can be changed.
 **
 ** @param gmo The MQGetMessageOptions object.
 **/
public void beforeGet(com.ibm.mq.MQGetMessageOptions gmo);
/**
 ** This method is called after a message has been retrieved from an 
 ** MQ queue (MQGET) and before the message will be processed by the 
 *  WMQBridge.
 ** The Message object can be changed.
 **
 ** @param msg The MQ message object.
 **/
public void afterGet(com.ibm.mq.MQMessage msg);

Top of page

Transactional Behavior

The WebSphere MQ Listener always works transactionally. A message is retrieved from the queue and then passed to the RPC server application. If no error occurs, the message is committed by the WebSphere MQ RPC Server. If the call to the RPC server is not successful, the call is retried as specified by properties entirex.server.retrycycles and entirex.bridge.retryinterval. If all retry attempts fail, the message is rolled back and the WebSphere MQ Listener terminates.

Top of page