MQSeriesReplier

The MQSeries component provides an interface to queues on IBM WebSphere MQ 5.3 and above using MQSeries client for Java. The component Receives messages from MQ server and sends back corresponding replies to a specified Destination Queue.

Configuration and Testing

Required queue should be created on IBM WebSphere MQ prior to configuring the component.

This section can be skipped if the queue to which messages are sent is already created.

Component Configuration

Connection Configuration

Host Address

The hostname or IP address of the machine on which IBM WebSphereMQ Server is running. If connecting to IBM WebSphereMQ on the same machine on which the component is running, use localhost.

Port for MQSeries server

The port number on which IBM WebSphere MQ listens to connection requests for connecting to configured Queue Manager.

To view the port number for required Queue Manager (value for property Queue Manager Name), navigate through the node IBM WebSphere MQ > Queue Managers > SampleQM > Advanced > Listeners as shown in Figure 3. The value in Port column is the required port number.

Server channel Name

The case-sensitive name of the channel to be used for communicating with the Queue Manager.

Queue Manager Name

The name of the Queue Manager in which destination queue is present.

Authentication Configuration

Authentication required

• Enable authentication when connecting to the MQSeries Server. When this value is selected, values for properties Username and Password are used for authentication.

• Do not use authentication when connecting to the MQSeries Server. When this value is selected, values for properties Username and Password are be used for authentication.

Username

The user name to be used to connect to the MQSeries Queue Manager. The ID is used to identify the WebSphere MQ client. It overrides the value of WebSphere MQ environment variable MQ_USER_ID.

If no security exit is defined for this client, the value of userID is transmitted to the server and is available for Server Security Exit use.

Password

The password to be used to connect to the MQSeries Queue Manager. The password is used to verify the identity of the WebSphere® MQ Client. It overrides the value of MQEnvironment variable MQ_PASSWORD .

If a Security Exit is not defined for this client, the value of password is transmitted to the server and is available to the Server Security Exit when it is invoked.

Resource Configuration

Send Exit Class

The class that implements the MQsendExit interface. This class allows you to examine and possibly alter the data sent to the queue manager by the MQSeries client. At runtime, new instance of this class is created and assigned to the variable 'MQEnvironment.sendExit' (class in IBM MQSeries API).

Receive Exit class

The class that implements the MQReceiveExit interface. This class allows you to examine and possibly alter the data received from the queue manager by the MQSeries client. At runtime, new instance of this class is created and assigned to the variable 'MQEnvironment.receiveExit'.

SecurityExit Class

The class that implements the MQSecurityExit interface. This class allows you to customize the security flows that occur when an attempt is made to connect to a queue manager. At runtime, new instance of this class is created and assigned to the variable 'MQEnvironment.securityExit'.  

A WebSphere MQ JMS application can use Channel Security, Send, and Receive exits on the MQI channel that starts when the application connects to a queue manager. An application connects to a queue manager by setting channel-related fields or environment properties in the MQEnvironment class. Further information can be found at http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/uj21370_.htm

Request Queue

Queue Name

Name of the queue on IBM WebSphere MQ from which messages are received.

Text Type

An MQ message contains message descriptor (a set of headers that define the message) and data. The data is stored in binary format. Multiple fields are written in a sequence using a Type-specific API. The data in the message is read by the consuming application exactly in the same order as the data is written.

The MQSeriesReplier component parses messages read from an MQ queue based on Structure and Headers configurations in the CPS. It builds output message based on Text Type, Output Mode, Structure and Headers configurations in the CPS.

Parse Message

This option is used when the MQ message contains multiple fields in the message body. When this option is selected, both Structure button and Headers button are enabled. Fields in the MQ message are defined in Structure editor.

The MQ message is parsed based on the fields defined and then an XML message containing fields and headers with their respective values is generated. The output message is always an XML message.

Raw Text

This option is used if MQ message contains only a single String field. MQ message is read from the queue and the data from the message is set in text format on output message. Any headers that have to be read from the MQ message are defined in Headers editor. The output message can either be in raw text or in XML format based on the value for property Output Mode.

When this option is selected, Structure button is disabled and Headers button is enabled.

Refer to section Input and Output for details about the effects of these configurations on input and output structures.

Output Mode

When Text Type is Raw Text, format of the message to be sent on output port can be set either as Raw Text or XML.

Raw Text

This option is used when the user wants the output message to be set as raw text. Headers defined in CPS are set as message properties on output message.

XML

This option is used when the user wants the output message in XML format. Output XML contains values for header fields defined in CPS, and message body which contains the text read from MQ message.

When the Include RFH2 Headers is selected in Headers option, the Output Mode gets disabled and output message is always set to XMLformat.

Structures

This button is enabled only when Text Type is 'Parse Message'. Click Structures button to launch the editor to define the fields of the message.

The Structures editor contains a table with Tag Name, Data Type and Length columns. Each row corresponds to a field in the MQ message.

• Tag Name: Element name for the element in XML structure which holds data for the field.
• Data Type: Type of data that is held in the field. It can only contain following values (case sensitive) - Char, Double, Float, Integer, Long Integer, Short Integer, UTF, String, Boolean, Byte Array.
• Length: Length of the field that has to be read from MQ message. This value is applicable for only String and Byte Array data types and the value is ignored for other data types. For String data type, default value is '1', which means the whole message is read from MQ message and is set on the output message.

• Order of the fields is important and the order of the rows in this table defines the order of fields in the MQ message.
• Move Up and Move Down buttons are used to reorder the fields.
• Add and Delete buttons are used to add or remove the fields.

Schema for output XML is built based on the fields defined here. However, the types for elements in schema do not use the types defined here. All the elements are defined as String type and hence, the schema does not validate content of element with appropriate data type.

1. Data in output XML for Boolean type fields contains true or false.
2. Data in output XML for Byte Array type fields contains Base64 encoded string. The Base64-Decode function under Advanced Functions in Fiorano Mapper can be used to convert Base64 encoded string into byte array.
3. If the order of elements defined in Structure editor differs from order of fields in MQ message or if there are additional fields defined in Structure editor or if some of the fields present in the MQ message are not defined in the Structure editor, one of the following happens:
   1. error when building output message from MQ message.
   2. mixed up values between fields.
   3. junk data is set on output message.

Headers

Click Headers button to launch an editor, the figure below defines MQ message descriptor (MQMD) fields that have to be read from the MQ message and set on output message.

Defining MQMD headers

Available Headers

Contains MQMD headers that are defined on MQ message.

Included Headers

Contains MQMD headers that can be defined on output message and whose values are taken from MQ message received from the queue.

Selected headers are set in Output XML when

• Text type is parse message
• Text type is Raw Text and Output mode is XML

When output message is raw text, selected headers are set as message properties on the output message.

Headers in Available Headers and Included Headers together contain all MQMD headers.

MQMD headers can be selected or unselected as 

• To read values of MQMD headers from MQ message and set them on output message, select required headers from Available Headers list and click

  

• To read values of all MQMD headers from MQ message and set them on output message, click 

  

  .
• To remove any of the selected headers, select required headers from Included Headers and click 

  

• To remove all selected headers, click 

  

Refer to section MQMD headers for default values.

Include RFH2 Headers

Select this option to parse MQRFH2 headers present in MQ message and set them on output message.If this option is not selected,then MQRFH2 headers are discarded and the output message contains only message data present in MQ message.

RFHFolder format

This property is used to specify the way in which the variable portion of the RFHHeaders has to be sent in output XML. The variable portion of an RFH Header contains variable number of MQHRF2 folders.

Refer to http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/js07180.htm for additional details. It can be chosen as explained below

TEXT

When this option is chosen, the RFHFolders in the header is output as CDATA.

For example, a sample JMS Folder <jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms> present in the retrieved message is output as below:

<![CDATA[<jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms>]]>

CUSTOM XML

When this opton is chosen, the RFHFolders in the header is output as elements conforming to a schema. For example, a sample JMS Folder <jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms> present in the retrieved message is output as below:

<ns1:Folder type="jms">
<ns1:Property name="Dst">queue:///Test</ns1:Property><ns1:Property name="Dlv">4</ns1:Property><ns1:Property name="Tms">3543534</ns1:Property>
</ns1:Folder>

• When the Include RFH2 Headers is selected, the output message is always in XML format and Output Mode is disabled.
• The component is able to parse MQRFH2 headers present in MQ message. Any other headers except MQMD and MQRFH2 headers (if present) are not parsed and are set in message body of the output message.

Refer to section Input and Output for details about the effects of these configurations on input and output structures

MQMD Headers

Only some of most commonly used MQMD headers are provided in the CPS of the component. Refer to Table 1 for a short description and default value used for each MQMD header. Refer to link http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/mqmd.htm for detailed information on MQMD headers.

Table 1 shows short description, default values and data types of MQMD headers used in the component.

Table 1: Message Selection Properties

Message Selection

This option is used to receive specific messages from the MQ queue. Selection is based on the MQMD headers Message ID, Correlation ID and Message Sequence Number.

• Message Sequence Number: This is the sequence number of a logical message within a group.

• Message ID: This is a byte string that is used to distinguish one message from another.

• Correlation ID: This is a byte string that the application can use to relate one message to another, or to relate the message to other work that the application is performing

CCSID

Coded Character Set Identification (should be an integer or null), in case of null, 819 (ISO 8859-1 ASCII) is used as CCSID. Data in MQ message is always present in the form of bytes. This field is used while converting these data bytes (decodes bytes into string using the specified Charset) and this conversion depends on the type of output message.

• When text type is Raw Text and Output mode is Raw Text, the data bytes in MQ message is converted to string data using the CCSID value and set as output message.
• When text type is Raw Text and Output mode is XML, the data bytes in MQ message is converted to string data using the CCSID value and set as message body in output message.
• When text type is parse message, the data bytes in MQ message are read based on the structure fields. Whenever there is a String data field, CCSID value is used for conversion of the data bytes.
• The behavior is unspecified if the data bytes present in message are not valid in specified Charset. There can be errors while building the output message or they can be junk data in output message.

Reply To Queue

This property defines the queue on IBM WebSphere MQ to which replies are sent, format of message, and message sending options.

Click the ellipsis button

Queue Name

Name of the queue on IBM WebSphere MQ to which messages are sent.

Text Type

An MQ message contains message descriptor (a set of headers that define the message) and data. The data is stored in binary format. Multiple fields are written in a sequence using a type specific API. The data in the message is read by the consuming application exactly in the same order as the data is written.

The MQSeriesReplier component takes-in an input message in text format (either XML or raw), builds an MQ message internally from the message in text format based on message details configured in CPS, and sends the message to the configured queue.

There are two formats for defining the input message:

XML Text

This option defines an XML structure with headers and fields of message body defined in CPS. The input XML contains values for headers and message body fields, which are parsed, and respective values are set on MQ message. The MQ message will then be sent to MQ queue.

This option should be used in any of the following cases:

• When the message body contains data for multiple fields, for example, name and age of a person MQMD or RFH2 headers and/or their values vary with each input message.
• When this option is selected, both Structure and Headers buttons are enabled.

Raw Text

This option does not define any structure for input message. The input message is set on the message body as a single string field. Headers (MQMD and RFH2) with values defined in CPS are sent on every message. Only one RFH2Header is added to the message.

This option should be used when all of the followings conditions are met:

• When the message body contains only a single text field and complex transformation and XML parsing can be avoided. A typical case, when a message is pulled from one system and passed on without any modifications to IBM WebSphere MQ series. MQMD or RFH2 headers and their values are constant for all messages.
• When this option is selected, Structures button is disabled and Headers button is enabled.

Refer to section Input and Output for details about the effects of these configurations on input and output structures.

Structures

The structures button is enabled only when Text Type is XML Text. Click this button to launch editor to define the fields of the message.

The editor contains a table with Tag Name and Data Type columns. Each row corresponds to a field in the MQ message.

• Tag Name: The element name for the element in XML structure which holds data for the field.
• Data Type: The type of data that is held in the field. It can only contain following values (case sensitive) - Char, Double, Float, Integer, Long Integer, Short Integer, UTF, String, Boolean, Byte Array. The figure above shows the definition of structure to build a MQ message with data for a ID, name and age of a person.

• Order of the fields is important and the order of the rows in this table defines the order of fields in the MQ message.
• Move Up and Move Down buttons are used to reorder the fields.
• Add and Delete buttons are used to add or remove the fields.

The schema for input XML is built based on the fields defined here. However, the types for elements in schema do not use the types defined here. All the elements are defined as string type and hence, the schema does not validate content of element with appropriate data type. 

• Data in input XML for Boolean type fields should contain true or false (not case sensitive). Any other value is treated as false.
• Data in input XML for Byte Array type fields should contain Base64 encoded string. The Base64-Encode function under Advanced Functions in Fiorano Mapper can be used to convert byte array into Base64 encoded string.
• Data in input XML for Char type fields should contain only one character. If there is more than one character, only the first character is picked.
• If the order of elements in input XML differs from the order defined or if there are additional elements or if some of the elements are missing, one of the following happens:
  • error when building MQ message
  • mixed up values between fields
  • junk data is set on MQ message

Refer to section Input and Output for details about the effects of these configurations on input and output structures. 

Table 2: RHF2 Headers

Input and Output

Input

The input schema for the component is defined based on the configuration of Reply To Queue.

When the Text Type is set to Raw Text there is no schema defined for the input. The input message text is written MQ message body as a single String field. Selected MQMD headers with values defined in CPS and unselected MQMD headers with default values mentioned in section MQMD Headers are set on MQ Message. If RFH2 header is checked, one RFH2 header with field values defined in CPS is added. The MQMD headers and RFH2 header added is same for all messages.

The input schema is defined as shown in Figure 13 and a sample input is shown in Figure 14.

Figure 14: Sample input XML
All the fields defined are added as child elements under MessageBody in the same order in which these fields are defined in CPS. The Input XML should have all the fields and should strictly follow the order. MQMD headers are not explicitly set by the component.

When fields of message body are defined in Structure dialog as shown in Figure 15 and MQMD headers are defined in Headers dialog

 <?xml version="1.0" encoding="UTF-8"?>
<ns1:MQMessage xmlns:ns1="http://www.fiorano.com/RFH2_EP/MQSeriesReplier1">
   <ns1:MessageHeader>
      <ns1:MQApplicationName>MQApplicationName</ns1:MQApplicationName>
      <ns1:MQCharacterSet>MQCharacterSet</ns1:MQCharacterSet>
   </ns1:MessageHeader>
   <ns1:MessageBody>
      <ns1:Name1>Name1</ns1:Name1>
      <ns1:Name2>Name2</ns1:Name2>
   </ns1:MessageBody>
</ns1:MQMessage>

Figure 16: Sample input XML for headers defined in Figure 15

All the fields defined are added as child elements under MessageBody in the same order in which these fields are defined in CPS and all the MQMD headers selected are added as child elements under Message Header in the same order in which these headers are defined in CPS.

If Message Header element is not present MQMD headers are not explicitly set by the component and it behaves exactly like the case where only the fields of message body are defined.

If Message Header element is present, then for the MQMD fields that are present under the Message Header element in input XML, values are taken from input XML. For the MQMD fields that are not present under the Message Header element, default values as described in section MQMD Headers are used irrespective of whether the header is selected or not in CPS as shown in Figure 16.

When fields of message body are defined in Structure dialog as shown in figure 9 and both MQMD headers and RFH2 header are defined in Headers dialog.

Output

When the Text Type is set to Raw Text and Output Mode is set to XML Text, then there is no schema defined for the output. The output message text contains a single String field. Selected MQMD headers in CPS with values present of MQ message are set on output message.

When the Text Type is set to Parse Message, the output schema varies based on the configuration of structure and headers.

When only fields of message body are defined in Structure dialog.
All the fields defined are added as child elements under MessageBody in the same order in which these fields are defined in CPS. MQMD headers are not explicitly set by the component.

When fields of message body are defined in Structure dialog and MQMD headers are defined in Headers dialog.
All the fields defined are added as child elements under MessageBody in the same order in which these fields are defined in CPS and all the MQMD headers selected are added as child elements under Message Header in the same order in which these headers are defined in CPS.

When the Text Type is set to Raw Text and Output Mode is set to XML Text, the output schema varies based on the configuration headers.

<?xml version="1.0" encoding="UTF-8"?>
<ns1:MQMessages xmlns:ns1="http://www.fiorano.com/RFH2_EP/MQSeriesReplier1">
   <ns1:MQMessage>
      <ns1:MessageHeader>
         <ns1:MQPutApplicationName>MQPutApplicationName</ns1:MQPutApplicationName>
         <ns1:MQCharacterSet>MQCharacterSet</ns1:MQCharacterSet>
         <ns1:RFH2Headers>
            <ns1:RFH2Header>
               <ns1:StructId>StructId</ns1:StructId>
               <ns1:Version>Version</ns1:Version>
               <ns1:Encoding>Encoding</ns1:Encoding>
               <ns1:CodedCharSetId>CodedCharSetId</ns1:CodedCharSetId>
               <ns1:Format>Format</ns1:Format>
               <ns1:Flags>Flags</ns1:Flags>
               <ns1:NameValueCCSID>NameValueCCSID</ns1:NameValueCCSID>
               <ns1:RFH2Folders>
                  <ns1:Folder>Folder</ns1:Folder>
               </ns1:RFH2Folders>
            </ns1:RFH2Header>
         </ns1:RFH2Headers>
      </ns1:MessageHeader>
      <ns1:MessageBody>MessageBody</ns1:MessageBody>
   </ns1:MQMessage>
</ns1:MQMessages>

Figure 17: Sample Output XML for Message and RHF2 headers enabled 

Useful Tips

The correct CCSID should be set for message encoding when transferring messages from AS 400 systems to other platforms and vice versa.