MQSeriesIn

The MQSeriesIn component provides an interface to queues on IBM WebSphere MQ 5.3 and above using MQSeries client for Java. The component sends messages that are received to queues on the MQSeries Server. The input message contains details of the message to be sent to the queue.

Configuration and Testing

Creating Qqueues on IBM WebSphere MQ using WebSphere MQ Explorer

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.

Steps for creating a queue on IBM Websphere MQ:

1. Start WebSphereMQ Explorer.
2. In the WebSphereMQ Explorer Navigator pane, expand the IBM WebSphere MQ and right-click Queue Managers node.
3. From the pop-up menu, select New and click Queue Manager.
   
   

   

   
   Figure 1: Adding new queue manager
    
4. Enter the Queue manager name with required name in Enter basic values (Step 1).
   
   

   

   
   Figure 2: Providing a name for queue manager
    
5. Proceed to Enter listener options (Step 4) wizard page.
6. Provide a port number which is not used by any other application or any other Queue Manager in IBM WebSphere MQ as shown in Figure 3.
   
   

   

   
   Figure 3: Providing port number
    
7. Click Finish. A new Queue Manager with given name is created and shown in WebSphereMQ Explorer – Navigator.
   
   

   

   
   Figure 4: New Queue Manager Sample QM
    
8. In the WebSphereMQ Explorer – Navigator, expand IBM WebSphere MQ > Queue Managers > SampleQM > Advanced and right-click Channels node as shown in Figure 5.
9. From the pop-up menu, select New and click Server-connection Channel to add a server-connection channel as shown in Figure 5.
   
   

   

   
   Figure 5: Adding a server-connection channel
   
   
10. Enter the Name in Create a Server-connection Channel step, as shown in Figure 6, and click Finish.
    
    

    

    
    Figure 6: Configuring Server-connection Channel with required name
     
11. On successful completion, newly added server-connection channel is shown when IBM WebSphere MQ > Queue Managers > SampleQM > Advanced > Channels node is expanded as shown in Figure 7.
    
    

    

    
    Figure 7: Newly added server connection channel
     
12. Right-click the newly added Server-connection Channel and click Start option from the pop-up menu as shown in Figure 8.
    
    

    

    
    Figure 8: Starting Server-connection Channel
     
13. In the WebSphereMQ Explorer – Navigator, expand IBM WebSphere MQ > Queue Managers > SampleQM and right-click Queues node as shown in Figure 8.
14. From the pop-up menu, select New and click Local queue to add a local queue as shown in Figure 9.
    
    

    

    
    Figure 9: Adding a new local queue
     
15. Enter the Name in Create a Local Queue step, as shown in Figure 10, and click Finish.
    
    

    

    
    Figure 10: Name for local queue
     
16. On successful completion, newly added Local Queue is shown when IBM WebSphere MQ > Queue Managers > SampleQM > Queues node is expanded as shown in Figure 11.
    
    

    

    
    Figure 11: Newly added Local Queue

Managed Connection Factory

The connection details are configured in the first panel, Managed Connection Factory (MCF). Figure 12 illustrates the panel.

Attributes

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 for connection requests to connect to configured Queue Manager. To view the port number for required Queue Manager (value for property Queue Manager Name), expand IBM WebSphere MQ > Queue Managers > SampleQM > Advanced > Listeners in WebSphereMQ Explorer – Navigator.

Server Channel Name

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

Queue Manager Name

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

Is Authentication required

• yes - Use authentication when connecting to the MQSeries Server. When this value is selected, values for properties Username and Password are used for authentication.
• no - Do not use authentication when connecting to the MQSeries Server. When this value is selected, values for properties Username and Password (if provided) are ignored while connecting to Queue Manager.

User name

The user name to connect to the MQSeries Queue Manager.

Password

The user password to connect to the MQSeries Queue Manager.

SendExitClass

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

ReceiveExitClass

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.

SecurityExitClass

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

Interaction Configuration

Business logic configuration details are configured in the second panel, Interaction Configurations.

Attributes

DestinationQueue

This property defines the queue on IBM WebSphere MQ to which messages 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 MQSeriesIn component takes in an input message in text format (either XML or raw), builds a 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 a 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.
    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 the all of the following 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, Structure button is disabled and Headers button is enabled.

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

• Structures

The structure 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. The value in Tag Name column is the element name for the element in XML structure which holds data for the field. The value in Data Type column is the type of the 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 above figure shows the definition of structure to build a MQ message with data for a ID, name and age of a person.

The order of fields is important and the order of rows in this table defines the order of fields in the MQ message. The Move Up and Move Down buttons are used to reorder the fields. The 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.

Headers

Click Headers button to launch an editor, refer to Figure 17, that defines MQ message descriptor (MQMD) fields and RFH2 Headers to be used. This property depends on TextType.

Defining headers when Text Type is XML Text

When TextType is set to XML Text the editor defines the following:

• • MQMD headers whose values have to be provided in input message.
  • RFH2 headers, if required, and their default values
    
    .

    

    
    Figure20:HeaderseditorwhenTextTypeisXMLText

Defining MQMD headers

Available Headers: Contains MQMD headers that can be defined on MQ message and whose values are not taken from input message. Headers in this list are set with default values on MQ message.
Included Headers: Contains MQMD headers that can be defined on MQ message and whose values are taken from input message.
Headers in Available Headers and Included Headers together contain all MQMD headers.

MQMD headers can be selected or unselected as

• To populate values for MQMD headers from input message, select required headers from Available Headers list and click

  

  .
• To populate values for all MQMD headers from input message, click

  

  .
• To use default values for MQMD headers, select required headers from Included Headers list and click

  

  .
• To use default values for all MQMD headers, click

  

  .

The default values are used for MQMD headers which are in Available Headers list or which are in Included Headers, but corresponding elements are not present in input XML.
Refer to section MQMD headers for default values

Defining RFH2 headers

Select the Include RFH2 headers check box to set RFH2 headers on MQ Message, refer to Figure 17. If the check box Include RFH2 headers is unchecked the input schema created will not contain elements related to RFH2 headers.

Multiple RFH2 headers can be set in the input message. Each RFH2 header should contain all the fields shown in Figure 17. If any RFH2 header in input XML does not contain the particular field then corresponding value from the Default Value column is used. The Variable data is also a field of RFH2 header and is treated similar to other RFH2 fields in the table.

Refer to section RFH2 header fields for default values.

Defining headers when Text Type is Raw Text

When Text Type is set to Raw Text, the editor defines the following:

• MQMD headers and their values that have to be set on MQ message.
• RFH2 headers, if required, and their values that have to be set on MQ message.
  
  

  

  
  Figure 21: Selection of MQBD headers that has to be set on the Input Message

Defining MQMD headers

Select the check box in Select column if a particular MQMD header value in Name column has to be set on the input message with value specified in Constant Value column, refer to Figure 21. If the check box in Select column is not checked, then the default value for corresponding MQMD header is used. The values provided in Constant Value column are not validated against the data type of the corresponding MQMD header and hence, should be carefully defined.

MQMD headers are set with same values on all messages.

Refer to section MQMD headers for default values and data types.

Defining RFH2 headers

Select the Include RFH2 headers check box to set RFH2 header on MQ Message, refer to Figure 18. If the check box Include RFH2 headers is unchecked RFH2 header is not set on the message.
Only one RFH2 header can be set on message. Values for each field of RFH2 header can be provided in Constant Value column against corresponding field as shown in Figure 21. The Variable data is also a field of RFH2 header and is treated similar to other RFH2 fields in the table. By default, when this editor is opened for the first time default values for all fields are loaded.
Refer to section RFH2 header fields for additional information.

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.

Values in Default value column of Table 1 are the defaults defined in the component and may vary from the actual default values of IBM WebSphere MQ.

Table 1 Short descriptions, default values and data types of MQMD headers used in the component

RFH2 Header fields

Refer to Table 2 for a short description and default value used for each RFH2. Refer to link http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/csqzak10172.htm for detailed information on RFH2 header fields.

Values in Default value column of Table 2 are the defaults defined in the component and may vary from the actual default values of IBM WebSphere MQ.

Table 2 Short descriptions, default values and data types of RFH2 header fields used in the component

Variable Data

The variable portion contains a variable number of MQRFH2 folders. Each folder contains a variable number of elements or properties. Folders group together related properties. Each MQRFH2 folder can be added as an entry in the table as shown in the figure 18 using the add button. Refer to link http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/js07180.htm for additional details about this field

RFHFolder format

When the input type is XML, the way MQRFH2 folders can be specified in the input message depends on this property.

• TEXT
  When this option is chosen the RFHFolders can be specified as CDATA. For example a sample jms Folder <jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms> can be specified as<![CDATA[<jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms>]]>

• CUSTOM XML
  When this opton is chosen the RFHFolders can be specified as parseable elements in the input schema. If the property value is empty then an attribute isNull="true" must be added to corresponding Property element. For example a sample jms Folder <jms><Dst>queue:///Test</Dst><Dlv>4</Dlv><Tms>3543534</Tms></jms> can be specified as
  <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>

Sync Point Control

The IBM WebSphere MQ series support transactions similar to JMS transaction. Select the check box if the messages sent to MQ queue have to be committed after sending a batch of messages. The messages are not visible or available for consumption on queue until a commit is performed. If the check box is unchecked, any messages sent are immediately available for consumption on the queue.
The Batch Size is taken into account only if this check box is checked.

• Batch Size
  The number of messages after which a commit should be performed, if the check box Sync Point Control is checked. The Batch size is counted based on the number of messages that are successfully sent to MQ Queue. If any message could not be sent to MQ Queue due to an error that message is not counted, but the count continues.

CCSID

The Coded Character Set Identification should be an integer or null, in case of null, 819 (ISO 8859-1 ASCII) is used as CCSID. This character set is set on the MQMessage. This overrides the MQCharacterSet header property set in MQMD headers.

Input and Output

Input

The input schema for the component is defined based on the configuration selected.

• 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.
• When the Text Type is set to XML Text the input schema varies based on the configuration of structure and headers.
• When only fields of message body are defined in Structure dialog as shown in Figure 19.

The input schema is defined as shown in Figure 20 and a sample input is shown in Figure 21.

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 19 and MQMD headers are defined in Headers dialog as shown in Figure 22.

The input schema is defined as shown in Figure 23 and a sample input is shown in Figure 24.

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 in 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 22.

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

The input schema is defined as shown in Figure 26 and a sample input is shown in Figure 27.

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. The RFH2 headers are added as well under Message Header element as RFH2Headers element, and the RFH2Headers element can contain multiple RFH2Header elements.

If Message Header element is not present, MQMD headers and RFH2 header 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 25. If RFH2Headers element is not present or if RFH2Headers element is present but does not have any child RFH2Header elements then RFH2 headers are not set. If there is a RFH2Headers element which contains one or more RFH2Header elements as children, then one RFH2 header is added for each of the RFH2Header elements present in the same order. A RFH2 header is populated with field values from the values present at elements with corresponding field names. If a particular field element is not present, as a child to RFH2 header then the default value defined in the CPS for that field is taken.

If the input message contains a property with name TargetQueueName and the value of property is not null message, the message is sent to the queue with name specified by the property. If the property is not defined or a value is not set for the property the message is sent to queue with name configured in CPS.

Output

The output schema for the component is fixed. The schema is shown in Figure 28.

The output message contains only two elements:

• QueueName – The name of queue to which the message is sent.
• status – success

The queue name to which the message is sent is also set as message property with name TargetQueueName.

Functional Demonstration

Scenario 1

Configure the component for Text type mode as Raw Text and configure Headers as shown in Figure 29.

Input Message

testMessage

Output Message

<?xml version="1.0" encoding="UTF-8"?>
<MessagePublishReport xmlns="http://www.fiorano.com/fesb/activity/MQSeriesIn1In/Out">
   <QueueName>TestQueue</QueueName>
   <status>success</status>
</MessagePublishReport>

MQMD headers that are selected in Figure 19 are set on MQMessage with values provided in Constant Value column. For the MQMD headers which are not selected in CPS, default values are set on MQ Message

Scenario 2

Configure the component for XML type message.
Add two fields Name1 and Name2 with type String in Structure editor as shown in Figure 30.

Select MQMD headers MQCharacterSet and MQApplicationName and check RFH2 Headers as shown in Figure 31

InputMessage

<?xml version="1.0" encoding="UTF-8"?>
<ns1:MQMessage xmlns:ns1="http://www.fiorano.com/fesb/activity/MQSeriesIn1In/In">
   <ns1:MessageHeader>
      <ns1:MQCharacterSet>1208</ns1:MQCharacterSet>
      <ns1:RFH2Headers>
         <ns1:RFH2Header>
            <ns1:StructId>RFH</ns1:StructId>
            <ns1:Version>2</ns1:Version>
            <ns1:Encoding>273</ns1:Encoding>
            <ns1:CodedCharSetId>1208</ns1:CodedCharSetId>
            <ns1:Format>MQSTR</ns1:Format>
            <ns1:Flags>0</ns1:Flags>
            <ns1:NameValueCCSID>1208</ns1:NameValueCCSID>
            <ns1:VariableData><![CDATA[<mcd>jms_text</mcd>]]></ns1:VariableData>
         </ns1:RFH2Header>
      </ns1:RFH2Headers>
   </ns1:MessageHeader>
   <ns1:MessageBody>
      <ns1:Name1>Name1value</ns1:Name1>
      <ns1:Name2>Name2value</ns1:Name2>
   </ns1:MessageBody>
</ns1:MQMessage>

OutputMessage

<?xml version="1.0" encoding="UTF-8"?>
<MessagePublishReport xmlns="http://www.fiorano.com/fesb/activity/MQSeriesIn1In/Out">
   <QueueName>TestQueue</QueueName>
   <status>success</status>
</MessagePublishReport>

In the above sample, input message only not all MQMD headers which are selected in CPS are provided. For those MQMD headers which are not provided in input message, default values are set. And for RFH2 headers, default values are taken from the CPS if they are not provided in input message.

Scenario 3

Configure the component for XML type message.
The RFH Format is chosen as "CUSTOM XML" instead of "TEXT" in figure 31. The input and output will be as below.

InputMessage

<?xml version="1.0" encoding="UTF-8"?>
<ns1:MQMessage xmlns:ns1="http://www.fiorano.com/fesb/activity/MQSeriesIn1In/In">
   <ns1:MessageHeader>
      <ns1:MQCharacterSet>1208</ns1:MQCharacterSet>
      <ns1:RFH2Headers>
         <ns1:RFH2Header>
            <ns1:StructId>RFH</ns1:StructId>
            <ns1:Version>2</ns1:Version>
            <ns1:Encoding>273</ns1:Encoding>
            <ns1:CodedCharSetId>1208</ns1:CodedCharSetId>
            <ns1:Format>MQSTR</ns1:Format>
            <ns1:Flags>0</ns1:Flags>
            <ns1:NameValueCCSID>1208</ns1:NameValueCCSID>
            <ns1:RFH2Folders>
               <ns1:Folder type="mcd">
                  <ns1:Property name="msd">jms_text</ns1:Property>
               </ns1:Folder>
            </ns1:RFH2Folders>
         </ns1:RFH2Header>
      </ns1:RFH2Headers>
   </ns1:MessageHeader>
   <ns1:MessageBody>
      <ns1:Name1>Name1value</ns1:Name1>
      <ns1:Name2>Name2value</ns1:Name2>
   </ns1:MessageBody>
</ns1:MQMessage>

OutputMessage

<?xml version="1.0" encoding="UTF-8"?>
<MessagePublishReport xmlns="http://www.fiorano.com/fesb/activity/MQSeriesIn1In/Out">
   <QueueName>TestQueue</QueueName>
   <status>success</status>
</MessagePublishReport>

In the above sample, input message does not have all MQMD headers which are selected in CPS. For such MQMD headers default values are set. For RFH2 headers, default values are taken from the CPS if they are not provided in input message.

Useful Tips

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