MQSeriesRequestor component provides an interface to queues on IBM WebSphere MQ 5.3 and above. The component sends messages that are received on the input port to queues on MQSeries Server and waits for response for the same message.
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.
- For information about adding queue to WebSphere MQ server refer to MQSeriesIn/Out help documentation.
Managed Connection Factory
The connection details are configured in the first panel, Managed Connection Factory(MCF).
Figure 1: Managed Connection Factory Configuration
Connection Configuration
Figure 2: Connection Configuration in MCF panel
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.
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.
Authentication Configuration
Figure 3: Authentication configuration
Authentication required
- Enable 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 (if provided) are ignored while connecting to Queue Manager.
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 use by the server security exit.
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
Figure 4: Resource Configuration panel
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.
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 Cofiguration
Business logic configuration details are configured in the second panel, Interaction Configuration panel.
Figure 5:Interaction Configuration panel
Request Queue
Figure 6: Request Queue Configuration
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 MQSeriesRequestor component first 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. 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 followings conditions are met:
- When the message body contains only a single text field and complex transformation and XML parsing is not needed. 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 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.
Figure 7: Editor to define fields in 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 Figure 7 shows the definition of structure to receive a MQ message which has fields of ID and name.
The order of the fields is important and the order of the 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.
MQMD Headers
Click Headers button to launch an editor, refer to Fig 18, that defines MQ message descriptor(MQMD) fields and RFH2 Headers to be used. This property depends on Text Type.
Defining headers when Text Type is XML Text:
When Text Type 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
Figure 8: Headers editor when Text Type is XML Text
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 or
- 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 selected headers, select required headers from Included Headers and click .To remove all selected 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 8. 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 8. 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.
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 9. 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.
Refer to section MQMD headers for default values and data types.
Figure 9: Selection of MQMD headers that has to be set on the input message
MQMD Header details
Only some of the 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 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 : Short descriptions, default values and data types of MQMD headers used in the component
MQMD header name | Description | Default value | Data type |
---|---|---|---|
MQApplicationName | Name of application that put the message. | Empty string ("") | String |
MQApplicationType | Type of application that put the message | 0 (MQAT_NO_CONTEXT) | Integer |
MQCharacterSet | Character set identifier of character data in the message | 0 (MQCCSI_Q_MGR) | Integer |
MQCorrelationID | 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 | null (MQCI_NONE) | byte array as a hex string |
MQMessageID | A byte string that is used to distinguish one message from another. The message identifier is a permanent property of the message, and persists across restarts of the queue manager. | null (MQMI_NONE) | byte array as a hex string |
MQDeliveryMode | Delivery mode indicating whether the message survives system failures and restarts of the queue manager. | 0 (MQPER_NOT_PERSISTENT) | Integer |
MQExpirationTime | A period of time expressed in tenths of a second, set by the application that puts the message. The message becomes eligible to be discarded if it has not been removed from the destination queue before this period of time elapses. | -1 (MQEI_UNLIMITED) | Integer |
MQEncodingBinaryIntegers | Subfield of encoding header that specifies encoding for binary integers | 1 (MQENC_INTEGER_NORMAL) | Integer |
MQEncodingPackedDecimal | Subfield of encoding header that specifies encoding for packed-decimal integers | 16 (MQENC_DECIMAL_NORMAL) | Integer |
MQEncodingFloatPointNumbers | Subfield of encoding header that specifies encoding for floating-point integers | 256 (MQENC_FLOAT_IEEE_NORMAL) | Integer |
MQPriorityTag | Priority of the Message | -1 (MQPRI_PRIORITY_AS_Q_DEF) | Integer |
MQReplyToQueueName | Name of the message queue to which the application that issued the get request for the message sends MQMT_REPLY and MQMT_REPORT messages | Empty string ("") | String |
MQMessageType | Type of message | 8 (MQMT_DATAGRAM) | Integer |
MQUserId | User identifier of the application that originated the message. The queue manager treats this information as character data, but does not define the format of it. | Empty string ("") | String |
MQMessageFormat | A name that the sender of the message uses to indicate to the receiver the nature of the data in the message | null | String |
Table 1:Defining all MQMD headers
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/mqmd.htm]http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/csqzak10172.htm[ |http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/mqmd.htm] for detailed information on RFH2 header fields.
Table 2 Short descriptions, default values and data types of RFH2 header fields used in the component
RFH2 Header field | Description | Default value | Data type |
---|---|---|---|
StructId | Structure identifier. This field should strictly contain 4 characters. If there are more than 4 characters content after 8th character is pruned by the component. If there are less than 8 characters required additional blank spaces are padded at the end by the component. | RFH (MQRFH_STRUC_ID) | String of length 4 characters |
Version | Structure version number | 2 (MQRFH_VERSION_2) | Integer |
Encoding | The numeric encoding of the data that follows the last NameValueData field; it does not apply to numeric data in the MQRFH2 structure itself | 273 (MQENC_NATIVE) | Integer |
CodedCharSetId | The character set identifier of the data that follows the last NameValueData field; it does not apply to character data in the MQRFH2 structure itself. | 1208 | Integer |
Format | The format name of the data that follows the last NameValueData field. This field should strictly contain 8 characters. If there are more than 8 characters content after 8th character is pruned by the component. If there are less than 8 characters required additional blank spaces are padded at the end by the component. | MQSTR (MQFMT_STRING) | String of length 8 characters |
Flags | This value should be set to MQRFH_NONE | 0 (MQRFH_NO_FLAGS) | Integer |
NameValueCCSID | The coded character set identifier of the data in the NameValueData field. | 1208 | Integer |
Variable Data | A variable-length character string containing data encoded using an XML-like syntax. 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 | null | String |
Table 2:Defining RFH2 headers
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 fig 20 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>
Reply to Queue
Figure 11: Launching editor for configuring queue and message sending options
Queue Name
Name of the queue on IBM WebSphere MQ from which responses 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 MQSeriesRequestor component parses messages read from a 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 a XML message containing fields and headers with their respective values is generated. The output message is always a 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 XML or Raw Text.
There are two formats for defining the output message:
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.
Structures
This button is enabled only when Text Type is Parse Message. Click Structure button to launch editor to define the fields of the message.
Figure 12: Headers editor when Text Type is parse message
The editor contains a table with Tag Name, Data Type and Length 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 value in Length column is the 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 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.
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, which defines MQ message descriptor(MQMD) fields that have to be read from the MQ message and set on output message.
Figure 13: Selection of MQBD headers that has to be set on the input message
Refer to section 4.17.1.5 to know about MQMD headers
Refer to Table 1 to know the default values for MQMD headers.
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 a RFH Header contains variable number of MQHRF2 folders. Refer to link http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzak.doc/js07180.htm for additional details.
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.
Wait Interval
Maximum time in milliseconds the component should wait for a response on the MQ queue. When a request is sent to get message from queue, a message is received if it is present on the queue. If there are no messages on the queue, it waits for the specified interval of time for the message.
Default value is -1 which specifies infinite wait time that is, waits until a message is received. Any value which is less than 0 (zero) specifies infinite time.
Action when message is not available
This property specifies the action to be taken when there are no messages on the queue within the timeout specified. This property is disabled when the wait interval(timeout) is -1 (infinite).
- Send Empty Message
- This value is set by default. An empty message is sent to output port when 'Text type' is set to 'Raw Text'. When Text type is set to 'Parse message', a default xml message with empty 'MQMessages' element is sent to output port.
- Treat as Exception
- An exception message is sent to error port and no message is sent to output port.
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 this 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 error while building the output message or they can be junk data in output message.
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 below figure.
Figure 14: Fields defined for message body
Figure 15: Schema when only fields of message body are defined
Figure 16: Sample input XML for the given input schema
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.
Figure 17: Selecting MQMD headers whose values have to be taken from input XML
The input schema is defined as shown in Fig 30 and a sample input is shown in Fig 31.
Figure 18: schema when fields of message body and some MQMD headers are defined
Figure 19: 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 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 20.
- When fields of message body are defined in Structure dialog as shown in fig 19 and both MQMD headers and RFH2 header are defined in Headers dialog as in fig 20
Figure 20: Selecting some MQMD headers and enable RFH2 header
The input schema is defined as shown in Fig 21 and a sample input is shown in Fig 22.
Figure 21: Schema when RFH2 headers are selected as well
Figure 22: 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, 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
Headers
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.
Figure 23: Selecting some MQMD headers and enable RFH2 header
The output schema for the component is fixed. The schema is shown in Figure 24.
Figure 24: Output schema for the above input
Useful Tips
The correct CCSID should be set for message encoding when transferring messages from AS 400 systems to other platforms and vice versa.