TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ … · 2016. 8. 24. · About WebSphere...

TIBCO ActiveMatrix BusinessWorks™

Plug-in for WebSphere MQUser's GuideSoftware Release 8.5August 2016

Two-Second Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (ORPROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion, TIBCO ActiveMatrix BusinessWorks Plug-in forWebSphere MQ, TIBCO Business Studio, and TIBCO Enterprise Administrator are either registeredtrademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform EnterpriseEdition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks ofOracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2012-2016 TIBCO Software Inc. All rights reserved.

TIBCO Software Inc. Confidential Information

2

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Contents

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Plug-in Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

About WebSphere MQ Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Creating a WebSphere MQ Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Configuring a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Testing a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Configuring the Local Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Deploying Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Generating an EAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

TIBCO Business Studio Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

WebSphere MQ Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

WebSphere MQ Message Body Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

WebSphere MQ Application Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

WebSphere MQ Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

WebSphere MQ Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

WebSphere MQ Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

WebSphere MQ Inquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

WebSphere MQ Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

WebSphere MQ Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

WebSphere MQ Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

WebSphere MQ RequestReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

WebSphere MQ Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Working with Sample Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Importing Sample Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Running the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Transactions with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Data Conversion Plug-in with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Creating Secure Connections to the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Setting Up WebSphere MQ Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Creating IBM Keystores for the Queue Manager and Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118

Configuring the Queue Manager to Use Generated Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Using the IBM Key Management Tool to Review the Personal Certificate Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

3


Creating a TLS Connection for the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Setting Up TIBCO ActiveMatrix BusinessWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Plug-in with Large Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Sending and Receiving Long Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

4


TIBCO Documentation and Support Services

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. Thissite is updated more frequently than any documentation that might be included with the product. Toensure that you are accessing the latest available help topics, please visit:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on theTIBCO Documentation site. To directly access documentation for this product, double-click thefollowing file:

TIBCO_HOME/release_notes/TIB_bwmq_version_docinfo.html

where TIBCO_HOME is the top-level directory in which TIBCO products are installed. On Windows,the default TIBCO_HOME is C:\Program Files\tibco. On UNIX systems, the default TIBCO_HOMEis /opt/tibco.

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Installation

● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User's Guide

● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Release Notes

The following documents provide additional information and can be found on the TIBCODocumentation site:

● TIBCO ActiveMatrix BusinessWorks Documentation

● TIBCO Enterprise Administrator User's Guide

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCO Community offersforums, blogs, and access to a variety of resources. To register, go to the following web address:

https://community.tibco.com

5


https://docs.tibco.com

http://www.tibco.com/services/support

https://support.tibco.com

https://community.tibco.com

Plug-in Overview

You can design and implement ActiveMatrix BusinessWorks applications that exchange messages withother WebSphere MQ-capable applications across a wide range of hardware and operating systems byusing TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ.

The plug-in is specifically used to exchange free form binary and text data with TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion. By using several transport mechanisms such as this Plug-in, TIBCO ActiveMatrix BusinessWorks applications can use standard IBM copybooks to interface withlegacy applications.

The plug-in supports the following features:

● WebSphere MQ 7.x and upward releases. The plug-in supports the connection to WebSphere MQ6.x to the same extent that IBM supports connections between WebSphere MQ Server 6.x and Client7.x. See the IBM documentation for the version of software installed to determine if the features youwant to use are supported. The unsupported items are listed as follows:

— Pub/Sub Applications

— Application Properties

— Locally bound connections to WebSphere MQ Server 6.x

● A Connection resource that contains all parameters relevant to establishing a connection, includingautomatic re-connectivity.

● Connections can be pooled and secured with Transport Layer Security (TLS).

● A WebSphere MQ Browse activity that is used to retrieve a message nondestructively from aconfigured queue.

● A WebSphere MQ Get activity that gets a message from a queue and returns the contents of themessage as fields in the output schema.

● A WebSphere MQ Inquire activity that inquires about the current state of a queue and is primarilyintended to obtain the depth of the queue.

● A WebSphere MQ Listener activity that gets a message from a queue as a process starter. Eachprocess started might access the message read as fields in the activity output. Optionally, themessage can be explicitly acknowledged from the new process. If the message is not acknowledged,it is placed back on the queue.

● WebSphere MQ Publisher/Subscriber activities that perform topic publish and subscribe functionsusing messages, as described previously.

● A WebSphere MQ Put activity that puts message to a queue.

● A WebSphere MQ RequestReply activity that sends a request type message to a queue, and thenwaits for a response in the configured reply queue. Multi-message formats are not supported forthis activity. With the Put and Get activities, you can manually construct a request/reply processusing logical or segmented messages.

● Handling of the following message types:

— Datagram— Request— Reply— Report (COA, COD, Expiration, Exception, PAN, and NAN types are supported)

● Filtering on correlation, message identifiers, and group.

● Local MQ transactions for Get and Put activities.

6


● Grouped and segmented messages.

● Dynamic queues.

● WebSphere MQ message properties.

7


About WebSphere MQ Messages

You can access WebSphere MQ queues and messages with WebSphere MQ applications by usingTIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ.

WebSphere MQ messages consist of three basic sections:

● A header containing fields.

● Message properties that are the collection of property names and property values.

● The message body.

The plug-in uses different mechanisms to provide access to these sections.

Message Headers

Get, Put, and Listener activities provide access to WebSphere MQ message headers using the input andoutput schemas for an activity. The root name mqproperties contains the fields of message headers.Field names used in the mqproperties node generally map to message header field names used in theWebSphere MQ interface for Java. Only applicable fields are exposed in the input and output schema.For example, the accountingToken element is not an input schema field but is an output schema fieldfor the Get activity.

Message Properties

Message properties are a collection of name value pairs that can be sent with a Put activity to adestination, or can be received from a destination for Get and Listener activities. Values for a propertyare interpreted according to the schema that defines the properties node, and honor the encoding of themessage.

Message Body

The message body is exchanged as text strings or byte arrays for Get, Put, and Listener activities.

WebSphere MQ message payloads are often complex combinations of string, integer, and other fieldstypes. It is good practice that the Plug-in for Data Conversion be used to parse and render suchcomplex message bodies.

8


Getting Started

This section is designed for the beginners who want to use TIBCO ActiveMatrix BusinessWorks Plug-infor WebSphere MQ in TIBCO Business Studio™.

All the operations are performed in TIBCO Business Studio. See TIBCO Business Studio Overview toget familiar with TIBCO Business Studio.

A basic procedure of using the plug-in includes:

1. Creating a Project

2. Creating a WebSphere MQ Connection

3. Configuring a Process

4. Testing a Process

5. Deploying Applications

Creating a ProjectThe first task using the plug-in is creating a project. After creating a project, you can add resources andprocesses.

An Eclipse project is an application module configured for TIBCO ActiveMatrix BusinessWorks™. Anapplication module is the smallest unit of resources that is named, versioned, and packaged as part ofan application.

Procedure

1. Start TIBCO Business Studio using one of the following ways:

● Microsoft Windows: click Start > All Programs > TIBCO > TIBCO_HOME > TIBCO BusinessStudio version_number > Studio for Designers.

● Linux: run the TIBCO Business Studio executable file located in the TIBCO_HOME/studio/version_number/eclipse directory.

2. From the menu, click File > New > BusinessWorks Resources to open the BusinessWorks Resourcewizard.

3. In the "Select a wizard" dialog, click BusinessWorks Application Module and click Next to openthe New BusinessWorks Application Module wizard.

4. In the Project dialog, configure the project that you want to create:a) In the Project name field, enter a project name.b) By default, the created project is located in the workspace current in use. If you do not want to

use the default location for the project, clear the Use default location check box and click Browseto select a new location.

c) Use the default version of the application module, or enter a new version in the Version field.d) Keep the Create empty process and Create Application check boxes selected to automatically

create an empty process and an application when creating the project.e) Select the Use Java configuration check box if you want to create a Java module.

A Java module provides the Java tooling capabilities.f) Click Finish to create the project.

Result

A project and an application are created and displayed in the Project Explorer view. The Process editoris displayed automatically.

9


Creating a WebSphere MQ ConnectionTo use the plug-in activities, you are required to create a WebSphere MQ Connection shared resourcewhich contains all the parameters necessary to connect to a queue manager.

Prerequisites

The WebSphere MQ Connection shared resource is available at the Resources level. Ensure that youhave created a project, as described in Creating a Project.

Procedure

1. Expand the created project in the Project Explorer view.

2. Right-click the Resources folder and then click New > WebSphere MQ Connection.

3. Type a name in the Resource Name field in the WebSphere MQ Connection Resource dialog. ClickFinish.

4. Configure the WebSphere MQ Connection shared resource in the displayed editor, as described in WebSphere MQ Connection.

Configuring a ProcessAfter creating a project, an empty process is created. You can add activities to the empty process tocomplete a task. For example, place messages into a configured queue.

Prerequisites

Ensure that you have created an empty process when Creating a Project.

10


Procedure

1. In the Project Explorer view, click the created project and open the empty process from theProcesses folder.

2. Select an activity from the Palette view and drop it in the Process editor.For example, select and drop the Timer activity from the General Activities palette, and the Putactivity from the MQ palette.

3. Drag the icon to create a transition between the added activities.

4. Configure the added activities, as described in WebSphere MQ Palette.

A WebSphere MQ Connection shared resource is required when configuring activities. See Creating a WebSphere MQ Connection for more details on how to create a WebSphere MQConnection shared resource.

5. Click File > Save to save the project.

Testing a ProcessAfter configuring a process, you can test the process to check if the process completes your task.

Prerequisites

Ensure that you have configured a process, as described in Configuring a Process.

Procedure

1. On the toolbar, click Debug > Debug Configurations.

11


2. Click BusinessWorks Application > BWApplication in the left panel.By default, all the applications in the current workspace are selected in the Applications tab. Ensurethat only the application you want to debug is selected in the Applications tab in the right panel.

3. Click the Advanced tab and click Browse to locate the logback file.By default, the logback file is located in the TIBCO_HOME/bw/version_number/config/design/logback directory and determines what error logs are captured. See Managing Logs for moredetails.

4. Click Debug to test the process in the selected application.TIBCO Business Studio changes to the Debug perspective. The debug information is displayed inthe Console view.

5. In the Debug tab, expand the running process and click an activity.

6. In the upper-right corner, click the Job Data tab, and then click the Output tab to check the activityoutput.

Configuring the Local ConnectionIf the connection binding type is Local, then the JVM running your application expects to find the MQnative libraries on the java.library.path. If it does not, your process fails with anMQRC_MODULE_NOT_FOUND error.

To add the MQ native libraries to the application debug configuration:

Procedure

1. In TIBCO Business Studio, click Run > Debug Configurations.

2. Click BusinessWorks Application > BWApplication in the left panel.

3. Click the Environment tab in the right panel.

4. In the Edit Environment Variable wizard, add or modify the library search path variable for yoursystem:

● For Linux (The entry is similar to):

Type LD_LIBRARY_PATH in the Name field and ${env_var:RV_HOME}/lib/64:${env_var:RV_HOME}/lib:/opt/mqm/java/lib/OSGi:/opt/mqm/java/lib64:$

{env_var:LD_LIBRARY_PATH} in the Value field.

12


● For Windows:

Type PATH in the Name field and ${env_var:RV_HOME}/bin${system_property:path.separator}C:\Program Files (x86)\IBM\WebSphere MQ\java

\lib${system_property:path.separator}${env_var:PATH} in the Value field.

Deploying ApplicationsAfter testing, if the configured process works as expected, you can deploy the application that containsthe configured process into a runtime environment, and then use the bwadmin utility to manage thedeployed application.

Prerequisites

The following tasks are required before deploying applications:

● Creating a Project.● Generating an EAR File.

Deploying an application involves the following tasks:

1. Uploading an EAR file.

2. Deploying an application.

3. Configuring an application.

4. Starting an application.

See TIBCO ActiveMatrix BusinessWorks Administration for more details about how to deploy anapplication.

Generating an EAR FileApplication archives are enterprise archive (EAR) files that are created in TIBCO Business Studio. AnEAR file is required when deploying an application.

Prerequisites

An application project has already been created, as described in Creating a Project.

There are many ways to generate an EAR file. See TIBCO ActiveMatrix BusinessWorks Administration formore information.

Procedure

1. Go to the File Explorer view and click the Open Directory to Browse icon.

2. Select the folder where you want to generate the EAR file and click OK.A new folder is displayed in the File Explorer view.

3. Drag the application from the Project Explorer view to the new folder in the File Explorer view.

The EAR file is generated with the name <name>.<application>_<version>.ear.

TIBCO Business Studio OverviewTIBCO Business Studio is an Eclipse-based integrated development environment that is used to design,develop, and test ActiveMatrix BusinessWorks applications.

TIBCO Business Studio provides a workbench in which you can create, manage, and navigate resourcesin your workspace. A workspace is the central location on your machine where all data files are stored.

13


The workbench consists of:

1. Menu: contains menu items such as File, Edit, Diagram, Navigate, Search, Project, Run, Window,and Help.

2. Toolbar: contains buttons for frequently used commands such as New , Save , Enable/

Disable Business Studio Capabilities , Create a new BusinessWorks Application Module ,

Create a new BusinessWorks Shared Module , Debug , Run , and so on.

3. Perspective: contains an initial set and layout of views that are required to perform a certain task.TIBCO Business Studio launches the Modeling perspective by default. You can change theperspective from the menu Window > Open Perspective > Perspective_Name.

4. View: displays resources. For example, the Project Explorer view displays the ActiveMatrixBusinessWorks applications, modules, and other resources in your workspace; the Properties viewdisplays the properties for the selected resource. You can open a view from the menu Window >Show View > View_Name.

5. Editor: provides a canvas to configure, edit, or browse a resource. Double-click a resource in a viewto open the appropriate editor for the selected resource. For example, double-click an ActiveMatrixBusinessWorks process (DemoWorkflow.bwp) in the Project Explorer view to open the process in theeditor.

6. Palette: contains a set of widgets and a palette library. A palette groups activities that perform similartasks and provides quick access to activities when configuring a process.

14


Shared Resource

Shared resources are specifications that are shared among activities. This plug-in contains theWebSphere MQ Connection, WebSphere MQ Message Body Schema, and WebSphere MQ ApplicationProperties shared resources.

WebSphere MQ ConnectionThe WebSphere MQ Connection shared resource contains all the parameters necessary to connect to aqueue manager.

The connection resource supports these modes:

● Local: A local connection uses the C language libraries and JNI to locate and connect to queuemanagers on the local machine.

— Local connections support local transactions.

— Local connections require a WebSphere MQ server installation on the local machine.

— Local connections use the credentials for the logged on user.

● Remote: A remote connection uses TCP/IP to connect to the listening port of a queue manager on thenetwork or the local machine.

— Remote connections support local transactions.

— Remote connections support the use of specific user credentials.

— Remote connections support secure transports (TLS/SSL).

● Client Connection Table: This type of connection uses a Client Channel Definition Table (CCDT)exported by the queue manager upon saving a client channel definition. This is the only supportedmethod to connect to a multi-instance queue manager.

— Client connection table connections support local transactions. However, note that transactionsare not guaranteed to survive reconnections to the backup server in a failover situation.

— Client connection table connections support the use of specific user credentials.

— Client connection table connections support secure transports (TLS/SSL).

See the IBM documentation for a description of CCDTs and how to use them.

General

The General panel contains the following fields:

FieldModuleProperty? Description

Package N This field documents the package name to which this resourcebelongs.

Name N The name to be displayed as the label for the WebSphere MQConnection shared resource in the process.

Description N Description of the resource.

15


Queue Manager Connection Configuration

The Queue Manager Connection Configuration panel contains the following fields:


Binding N The connection resource supports three modes:

● Local● Remote● Client Connection Table

ClientConnectionTable

Y When using a Client Connection Table, enter the URL of the CCDTfile that is exported by the server to which you are trying toconnect.

This file is located in the queue manager home directory in the@ipcc/AMQCLCHL.TAB file. You can either reference this file fromthis location, or copy it to a location where it is accessible to therunning BusinessWorks instance.

This URL supports the HTTP, FTP, and FILE protocols.

Host Name Y Provide the name of the machine hosting the queue manager.

Default: localhost

This field is only available for remote bindings.

Port Y Provide the TCP port number on which the queue manager islistening.

Default: 1414

Range: 1 - 65535

This field is only available for remote bindings.

User Name Y The name of credential user for secure remote connection. If a username is not provided, the credentials of the current securitycontext are used.

Password Y For remote connections, the password is associated with thespecified user name.

Queue ManagerName

Y For Local and CCT connections, the name of the queue manager toconnect to. If not specified, the default queue manager is selected.

Server ChannelName

Y For remote connections, the server channel to connect to.

Queue managers can use multiple server channels if needed, forexample, to support TLS and plain connections.

16



HeaderCompression

N If RLE is selected, Run Length Encoding compression is applied tothe header portion of messages sent or received over thisconnection.

The server connection channel must be configured forcompression for this to work.

MessageCompression

N If RLE is selected, Run Length Encoding is applied to the body ofmessages sent over this connection.

If ZlibFast is selected, both RLE and ZlibFast are applied.

If ZlibHigh is selected, all three compression techniques areapplied.

The server connection channel must be configured forcompression for this to work.

Test Connection N Click it to test the queue manager connection. Whether successfulor not, a report is placed in the text area to the right. If the testfails, the report helps you determine what the problem is. In theevent that the connection is TLS enabled and you are unsure whatcipher to use, Test Connection searches for an acceptable cipherand includes it in the report.

If this is a local connection, Test Connection might fail because itcannot load the native JNI libraries it needs. If this happens, youmust add the WebSphere MQ jative libraries (dll's) to the libraryloading path for your platform. The easiest way to do this is to adda line like this to the TIBCOBusinessStudio.ini file:

● For Microsoft Windows, -Djava.library.path=C:\ProgramFiles (x86)\IBM\WebSphere MQ\java\lib64

● For Unix or Linux, -Djava.library.path=/opt/mqm/java/lib64

Pooling Configuration

The Pooling Configuration panel contains the following fields:

17



PoolingEnabled

N When you select the check box, pooling is active for this connection.The primary consideration for choosing pooling parameters is thenumber of available connections to the queue manager. Choosevalues which do not create unnecessary resource consumption in thequeue manager, and leave available connections for otherapplications (including other pooled connections, depending onwhether or not this application is deployed on multiple servers).

If you clear this check box, pooling is not active, a new non-pooledconnection is acquired and released for each activity.

It is good practice to clear this check box for the Listen andSubscriber activities, because these activities rarelyrelinquish their configured connection resources.

Max Y Determines the maximum number of connections in the pool. Whenthis limit is reached, subsequent activities fail with the indication:MQRC_CONNECTION_NOT_AVAILABLE

Max Unused Y Determines the maximum number of idle connections in the pool.When the number of unused connections reaches this number, theidle connections are disconnected and closed, freeing resources onthe server. Amounts over the Max Connections value are ignored.

Timeout Y The length of time an inactive connection is kept in the pool. Aconnection that has remained unused for this number ofmilliseconds is closed and removed from the pool, freeing resourceson the server.

No Verify N Enable this option to disable verification check made on connectionsas they are removed from the pool. If connections are not verifiedwhen removed from the pool, it is possible to use a disconnectedconnection in the process which will cause the activity to fail.

TLS Configuration

The TLS Configuration panel contains the parameters required to make a secure connection to thequeue manager using the Transport Layer Security (TLS) protocol. Before TLS can be used, the queuemanager and server channel used by clients must be configured. For more information, see CreatingSecure Connections to the Queue Manager.

The TLS Configuration panel contains the following fields:


TransportLayer Security

Y This flag enables or disables transport layer security for theconnection. It can be mapped to a module property which you canuse to control this configuration option during deployment.

18



TLSConfiguration

N Create an SSL Client Configuration resource.

See Creating Secure Connections to the Queue Manager for moreinformation about this field.

TLS CipherSpec

Y The queue manager requires that a particular cipher is specified inthe connection field. Normally ciphers are negotiated during thehandshake, but this is not true of WebSphere MQ connections. Thecipher must match the one selected in the queue managers securechannel configuration. However, note that the names do not matchbecause the queue manager refers to the cipher spec, and the plug-inrefers to a cipher suite. To find out the correct cipher, simply leavethe field blank, and press Test Connection to see if any cipheravailable in Java is acceptable by the queue manager. If not, youmight have to adjust the queue managers cipher specification. Manyof the cipher specifications supported by WebSphere MQ are notavailable in the stock JRE from Oracle.

You have two ways to improve the chances of having acipher match:● Use a platform where the IBM JRE is the standard.

● Refer to IBM APAR IV66840 which explains how toimprove the number of acceptable cipher suites on nonIBM JRE's.

Configure TLS using these fields and ensure:● That a Java Key Store is configured for the SSL Client.

● That the SSL Client protocol is TLSv1 and that the cipher is explicitly specified and matches thecipher used by the server channel. It must be noted that any cipher spec where the word "EXPORT"is displayed is unacceptably weak. NULL ciphers are not encrypted at all and the MD5 hash alsohas weaknesses.

See the TIBCO ActiveMatrix BusinessWorks documentation for more details about the TLSConfiguration panel.

WebSphere MQ Message Body SchemaIf the message content type for a message is set to Schema, then the message is parsed or rendered(depending on the operation) based on the schema derived from this resource. Therefore, to interactwith an application all that has to be known is the schema to which its messages conform.

General

The General panel contains the following fields:


Package N This read-only field documents the package to which the resourcebelongs.

19



Name N The name to be displayed as the label for the WebSphere MQMessage Body Schema shared resource in the process.

Description N Description of the resource.

Message Body Configuration

To create a schema, instantiate a Message Body Schema resource and add fields in the sequence thatthey are displayed in the message.

● The string type fields require the length to be provided. The length is ignored for other types. Datais space padded or truncated as necessary to conform to the length provided.

● The fields are inserted or removed from the message in the order in which they are added to thetable in this resource.

● Field names must be unique.

● If there is no syncpoint in place for the activity and an error occurs while extracting message bodyfields which causes the activity to fail, then the message is effectively lost. If there is any chance ofthis happening in your application, force a syncpoint. See the Explicit Commit check box from the Multi-Message tab .

The Message Body Configuration panel contains the following columns:

Column Name Description

FieldName Assign a unique name to this field. The name is for reference and XMLconsistency only, and is not stored in the message.

FieldType Select a type from the FieldType list.

For detailed field types, see the following table.

String Length Specify the length for a string.

The following table lists the field types and the methods used to access the field types:

Field Type Put API Get API

String writeString readStringOfCharLength(name encodes length)

Boolean writeBoolean readBoolean

Byte writeByte readByte

Bytes write readFully

Short writeShort readShort

Int writeInt readInt

20


Field Type Put API Get API

Long writeLong readLong

Float writeFloat readFloat

Double writeDouble readDouble

Decimal2 writeDecimal2 readDecimal2



Unsignedbyte write readUnsignedByte

Unsignedshort writeShort readUnsignedShort

Utf writeUTF readUTF

Char writeChar readChar

Line writeString readLine

WebSphere MQ Application PropertiesThere is no shared resource representing the application properties for a message in BusinessWorks 6.Instead, a generic schema is used and mapped onto the operation.

The following field types are supported:

● boolean● byte● bytes● short● int● long● float● double● stringThe node represented by this schema is present on the input schema of the Put activity and in theoutput schema of the Get and Listener activities. Fields which contain values are mapped onto sentmessages. When processing a received message, all fields in the schema which have correspondingnamed counterparts in the message are mapped onto the output schema. If a type mismatch occurswhen mapping fields onto the output schema, the field is skipped. If fields that are required by theschema are missing from the message, it causes the activity to fail. If there is no sync-point in place forthe activity and an error occurs while extracting the properties which causes the activity to fail, then themessage is effectively lost. If there is any chance of this happening in your application, you are requiredto force a sync-point. See the Explicit Commit check box from the Multi-Message tab.

To create a WebSphere MQ Application Properties Schema, right-click the Schemas folder in the ProjectExplorer view, click New > XML Schema File, and configure the schema and then select it from all theactivities that use it.

21


If the application properties are used on a message, the properties are included in an MQRFH2 header.This header is visible to and must be handled by non-Java applications in order for those applicationsto access the properties.

22


WebSphere MQ Palette

The WebSphere MQ palette contains eight activities that can be added to your business processes.

WebSphere MQ BrowseThe Browse activity is used to retrieve a message nondestructively from a configured queue. Messagescan be retrieved based on filter criteria specified in the input document.

The queue is opened in browse mode, and the results of the first message are returned. To retrievesubsequent messages, the activity must be placed in a loop. If no more messages on the queue satisfythe filter criteria, the activity fails with fault message code 50217. Interception of this fault by a faulthandler allows the process to gracefully exit the browse loop.

The Browse activity can be used to check the queue with or without a wait interval. The activity waitson the queue for the specified interval, then returns whether or not a message is received.

General

The General tab of the Browse activity contains the following fields:


Name N The name to be displayed as the label for the activity in theprocess.

Connection Y The connection resource which connects this activity with thequeue manager that has access to the desired queue.

Click the icon to select a usable connection for theactivity.

Destination Y Enter the name of the queue on which this operation isperformed. This field can be dynamically provided in theinput schema and is not required here.

Message ContentType

N Choose the way that the message body is represented in theoutput schema.

● Binary: the message is an array of bytes suitable for use bythe Data Conversion Palette activities.

● Text: the message is a string. The message is decodedusing characterSet for the message, or 819 if none isprovided. Characterset 819 is the Java API default.

● Schema: the message is formatted according to the schemaprovided in the Message Body Fields field. Values for thisschema are displayed in the Output tab.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at runtime to encode the contents of this message. This field is onlyavailable if Schema is selected in the Message Content Typefield.

23



Fail If Quiescing N Select this check box to cause the activity to fail and exit if thequeue manager attempts to quiesce. A failure to do so causesquiesce operations to take much longer. This check box isselected by default.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used forthis operation. It causes the queue manager to convert stringand numeric fields using the characterSet and encodingelements before the data is copied to the message buffer.

ApplicationProperties

N Select the application properties resource to be used to mapthe output of this Browse activity. Application properties aresimilar to regular message header fields except that the nameand type of the fields can be determined by a predefinedschema. If the received message contains properties, they aremapped according to this schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and mapthat schema to this field. See the IBM WebSpheredocumentation for property types supported by the level ofclient you have installed.

A failure to observe cardinality results in errorsprocessing the input or output schema.

Property Control N Select one of the following settings:

● AS_Q_DEF● COMPATIBILITY● IN_HANDLE● FORCE_MQRFH2

After selecting one of these options, you can use the Browseactivity to inter-operate with various versions of WebSphereMQ applications. Which option to use depends on thesending application. See the section entitled "MQGMOmessage property option setting" in the IBM WebSphere MQdocumentation for detailed information.

Logger Name Y Enter the name of any logger which has been configured forthe run time to write to. If no logger name is provided, thenthe default one is used. The activity writes informationalmessages to the log depending on how the logger isconfigured.

Description

A short description for the Browse activity.

24


Input

The following table lists the input items for the Browse activity:

Input ItemModuleProperty? Description

InteractionInput N The root node for all the input provided to the activity.

25



mqproperties N The node containing all the message header fields (plusthe destination override) which are relevant to input.

● destination: override the destination queue namewith the string specified in this field.

● destqmgr: the name of the remote queue managerfrom which to fetch the message.

The queue managers involved must beconfigured with the necessary sender andreceiver channels in place and started.

● correlationId: provide a correlation identifier forthis message by mapping a byte array to this field.The XPath statement tib: string-to-base64("correlationid") is sufficient to populate thisfield. The provided correlation ID is used to filtermessages from the queue.

● messageId: specify a message ID. This valueoverrides the default value generated by the queuemanager. The rules are the same as forcorrelationId. If a message ID is provided, it isused to filter the browse results.

● groupId: specify a group ID. If a single message isplaced in the queue using a specific group ID, thenthis message can be filtered and received by aBrowse activity after this activity maps the correctgroup ID there. This field is provided for use as anextra filter field only.

● characterSet: set the IBM Coded Characterset IDof this message. Valid values are:

— 850: the commonly used ASCII codeset.

— 819: the ISO standard ASCII codeset.

— 37: the American EBCDIC codeset.

— 1200: Unicode.

— 1208: UTF-8.

The queue manager might apply this codeset whendoing conversions for the purpose of creating reportmessages.

● alternateUserId: to document the alternate useridused in this operation, if any.

● waitinterval: specify a new browse timeout valuefor this operation only. It is the number ofmilliseconds that the operation waits before timingout.

26


Output

The following table lists the output items for the Browse activity:

Output ItemModuleProperty? Description

InteractionOutput N The root node for all the output provided by the activity.

27



mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant to output.

● destination: to document the destination for thismessage. If the queue is a dynamic queue, the generatedname is reported here.

● destqmgr: the name of the remote queue manager suppliedin the input schema.

● correlationId: to document the message correlation ID, ifany.

● messageId: to document the message ID.

● groupId: to document the group ID.

● characterSet: to document the character set the queuemanager uses to process this message.

● alternateUserId: to document the alternate userid usedin this operation, if any.

● accountingToken: the accounting token provided by thesending application.

● applicationIdData: application ID data. This is theapplication data provided by the sender of the message.

● applicationOriginData: origin data as provided byeither the sender of the message or the queue manager.

● putApplicationType: the type of the application that putsthe message.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

● putApplicationName: application name data as providedby either the sender of the message or the queue manager.

28



● userId: the effective user ID used to connect to the queuemanager.

● replyToQueueName: the name of the queue to which areply is sent. If the type of the message is Request, thenthis is the name of the queue that the application sends thereply message to.

● replyToQmgrName: the name of the remote queue managerfor this message's reply-to destination, if one is provided.

● format: to describe the nature of the data in the message.The sender of the application can use standard names(these names are prefixed by the MQ text) or application-generated names. If the message originates from a TIBCOActiveMatrix BusinessWorks Plug-in for WebSphere MQapplication, this is an empty string.

● expiry: the expiration time (in tenths of a second), afterwhich the message is eligible to be discarded by the queuemanager.

The default value of -1 means there is no expiration.

● priority: the priority (from 1 to 9) with which themessage is sent.

● reportOptionPan: reflects the value of the PositiveAcknowledgment bit of the report field. This field is anapplication only field and is not acted upon by the queuemanager.

● reportOptionNan: reflects the value of the NegativeAcknowledgment bit of the report field. This field is anapplication only field and is not acted upon by the queuemanager.

● report: to document the numerical value of the reportfield.

● encoding: to document the numerical value of theencoding field. This encoding is used for extractingnumerical data from the message if the numbers are inproperties or a message body schema.

● messageType: enumerated value indicating the messagetype:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.— 1 is Request.

● backoutCount: the number of times this message is backedout before being committed.

29



● feedback: if the message is a Report message, this fielddefines the nature of the report. Defaults to 0 for non-report messages.

● version: to document the version of the message. Thisplug-in supports type 2 messages only.

● putDateTime: the time that the message is placed into thequeue.

● groupStatus: to indicate whether the message is part of alogical message. It can contain any of the following:

— MSG_IN_GROUP

— MSG_NOT_IN_GROUP

— MSG_LAST_IN_GROUP

appProperties N This field maps the application properties present in thereceived message to the schema attached to the activity.Properties which are missing or not present in the schema arenot shown here.

messageFields N Contains the message body formatted using Schema in theMessage Content Type field of the General tab.

This field is displayed for schema-based messages only.

dynamicProperties N● dynamic property: these properties are exactly the same

as those mapped through the appProperties node withthe exception that no special schema is required to mapthem. A dynamicProperties node is created for eachproperty in the message which was not mapped by theappProperties schema mechanism. If no appPropertiesschema is in place, all properties are dynamic.

● name: the name of the property.

● value: the string type value of the property.

● type: the type for the property. The valid types are"string", "boolean", "short", "integer", "long","float", "double", and "byte".

bytes N If the activity is configured to use binary messages, then thisfield contains the output body of the message. Typically, thisbyte array is to be mapped as input to a TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion parse activity.

This field is only displayed when Binary is selected in theMessage Content Type area.

30



text N If the activity is configured to use text for the payload, thisfield is present and contains the contents of the messagedecoded as a string.

This field is only displayed when Text is selected in theMessage Content Type area.

responsetimemilli

sec

N To indicate how long it takes to receive the message. Thisvalue includes any time spent waiting on an empty queue.

Fault

The Fault tab lists the possible exceptions that occur in the Browse activity:

Error SchemaElement

DataType Description

msg String The descriptive text provided by this exception object.

msgCode String If the message has a BW message code, it is mapped to this field.

mqCompCode String If the message originates as a WebSphere MQ API exception, thenthat exception's completion code is here.

mqReasonCode String If the message originates as a WebSphere MQ API exception, thenthat exception's reason code is here.

mqErrorCode String If the message originates as a WebSphere MQ API exception, thenthat exception's error code is here.

WebSphere MQ GetThe Get activity is used to retrieve a message from a configured queue. Messages can be retrievedbased on filter criteria specified in the input document.

The Get activity can be used to:

● Check the queue with a wait interval. The activity waits on the queue for the specified interval, thenreturns whether or not a message is received.

● Check the queue without a wait interval. The activity checks the queue and returns immediately,regardless of whether a message is read.

● Listen indefinitely on the queue. The activity returns a message if one is available, or waits foreverfor a message to arrive.

General

The General tab of the Get activity contains the following fields:

31





Click the icon to select a usable connection for theactivity.

Destination Y Enter the name of the queue on which this get operation isperformed. This field can be dynamically provided in theinput schema and is not required here.

DynamicDestination

N Select the Dynamic Destination check box to enable dynamicdestinations for this operation. This enables the DynamicDestination Model field.

DynamicDestinationModel

Y Enter the name of the model queue which the queue manageruses as a template when constructing this dynamicdestination.

Message ContentType

N Choose the way that the message body is represented in theoutput schema.

● Binary: the message is an array of bytes suitable for use bythe Data Conversion Palette activities.

● Text: the message is a string. The message is decodedusing characterSet for the message, or 819 if none isprovided. Characterset 819 is the Java API default.

● Schema: the message is formatted according to the schemaprovided in the Message Body Fields field. Values for thisschema are displayed in the Output tab.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at runtime to encode the contents of this message. This field is onlyavailable if Schema is selected in the Message Content Typefield.

32



Close Option N Select the close option for this Get activity. These options arefor use with permanent dynamic queues only.

● NONE: no action is taken.

● DELETE: deletes the queue, if it is empty. If the queue isnot empty, no action is taken.

● PURGE: deletes the queue and any messages in it.

If the Get activity is being performed on a permanent dynamicqueue and the intention is for the queue to be deleted, you canchoose either DELETE or PURGE. DELETE deletes the queueif it is empty, and PURGE deletes the queue and any messagesthat are in it.

Do not select DELETE or PURGE for permanentlydefined queues. Depending on your security access,this might delete them.

Access Mode N Select the access mode for the queue:

● QDEFAULT: it accepts the access mode established whenthe queue is created.

● SHARED: other listeners can access the queue in thismode.

● EXCLUSIVE: other listeners cannot access the queue inthis mode. If another WebSphere MQ application has thequeue open, this activity fails.

Fail If Quiescing N Select this check box to cause the activity to fail and exit if thequeue manager attempts to quiesce. A failure to do so causesquiesce operations to take much longer. This check box isselected by default.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used forthis get operation. It causes the queue manager to convertstring and numeric fields using the characterSet andencoding elements before the data is copied to the messagebuffer.

Wait Forever N If the Wait Forever check box is selected, the Get activity waitsforever for a message in the queue. If the Wait Forever checkbox is cleared, the Wait Timeout field is enabled and thewaitinterval node of the input schema is observed andoverrides the values in the Wait Timeout field.

If a Get activity is configured to wait forever, it doesso even after the application is set to stop using theadministrator or shell command. To release theconnection and close the destination, it is necessaryto stop the appNode on which this application isrunning.

33



Wait Timeout Y The number of milliseconds this activity waits for a messagebefore failing.

This field is not available if the Wait Forever check box isselected.


N Select the application properties resource to be used to mapthe output of this Get activity. Application properties aresimilar to regular message header fields except that the nameand type of the fields can be determined by a predefinedschema. If the received message contains properties, they aremapped according to this schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and mapthat schema to this field. See the IBM WebSpheredocumentation for property types supported by the level ofclient you have installed.


Property Control N Select one of the following settings:


After selecting one of these options, you can use the Getactivity to inter-operate with various versions of WebSphereMQ applications. Which option to use depends on the sendingapplication. See the section entitled "MQGMO messageproperty option setting" in the IBM WebSphere MQdocumentation for detailed information.

Logger Name Y Enter the name of any logger which has been configured forthe run time to write to. If no logger name is provided, thenthe default one is used. The activity writes informationalmessages to the log depending on how the logger isconfigured.

Description

A short description for the Get activity.

Multi-Message

The Multi-Message tab of the Get activity contains the following fields:

34



Multi-MessageSupport

N This value can be None, BatchGroup or CustomGroup.

● None: in this mode, the Get activity operates as though it isexpecting a non-logical ordinary message from the queue.However, there is no way to prevent it from getting the firstmember of a logical message if it exists. The Complete Message,and Get Ordered fields apply. If the activity is not in a localtransaction and the Explicit Commit check box is clear, itoperates without a syncpoint for efficiency.

The Syncpoint Used indicator is off.

● BatchGroup: in this mode, the get operation is expecting to geteither a group of individual messages (in which case the BatchSize field controls how many messages are retrieved) or aLogical Message. This operation implies a unit of work and theentire batch is processed as a single unit of work unless the unitof work is extended by the use of a local transaction. Because it isnot possible to filter out logical messages, if a normal message isfetched and then a logical message is encountered, the entirelogical message is included with the normal message in oneoperation regardless of the Batch Size value. If the intention is toprocess Logical Messages only, set the batch size to 1. TheComplete Message and Get Ordered fields are in effect.

● CustomGroup: in this mode, the activity gets a single messagefrom the queue and stores the context of this message forsubsequent use. This mode is intended to be used in a loop toiteratively process the contents of a Logical Message. The outputschema field groupStatus indicates whether the message is in agroup and whether or not is the last message with the contents:MSG_IN_GROUP, MSG_NOT_IN_GROUP, MSG_LAST_IN_GROUP.This field is used to determine when to terminate the loop.Unless the activity is in a local transaction, it commits thecontents of each get as they are performed.

● CustomSegmented: in this mode, the activity gets a singlesegment of a segmented message from the queue and stores thecontext of this message for subsequent use. This mode isintended to be used in a loop to iteratively process the contentsof a Segmented Message. The output schema field lastSegmentindicates whether the currently fetched message is the last one inthe group or not. If it is set to true for the last message, thisvalue can be used to terminate a loop on the segmented message.Unless the activity is used in a local transaction, it commits thecontents of each get as they are performed. The activity isspecifically intended to be used in a loop to process the contentsof a segmented message where the entire message is too large tofit into memory.

35



Batch Size Y If BatchGroup mode is in effect, this field becomes enabled. Enterthe number of discrete messages which are to make up this batchget. The output schema contains a node for each message retrieved.If a timeout occurs while the batch is incomplete, then theincomplete batch is processed and no exception is thrown.

CompleteMessage

N Selecting the Complete Message check box causes the Get activity towait for a logical message to be complete before returning any of themessages. When the Complete Message check box is cleared, alogical message needs not be complete for the get to work, which ishandy for processing damaged messages, or messages which areintended to be processed as they are written to the queue. It has noeffect on non-logical messages. A message is considered to becomplete when all members are committed to the queue by thesending application.

Get Ordered N When the Get Ordered check box is selected, it requires that alogical message be processed in the order it is written to the queue.Therefore, the first get in a message requires that message number 1be present, so it must be disabled to process partial (damaged)logical messages. The queue must be indexed for this to work. If thequeue is not indexed, this option is dynamically switched off.

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits because of the overhead involved. However ,you mightselect the check box to force the creation of a unit of work andsubsequent commit. The commit happens after any applicationproperties and message body fields have been processed, soselecting this check box protects you from removing a message fromthe queue only to fail while processing the contents. Messagecontents can cause failures if, for example, the encoding or characterset is inappropriate for the data, or the schema used to process themessage is in error.

SyncpointUsed

N This is a status indicator only and does not represent anyconfiguration information. It indicates whether the activity runswith a syncpoint in effect and therefore require a subsequentcommit operation. Every effort has been made to avoid unnecessarycommits. The flag might be off if the activity is in a local transaction,but there is still a syncpoint in place on behalf of the transaction, soit is irrelevant in that case.

Input

The following table lists the input items for the Get activity:


InteractionInput N The root node for all the input provided to the activity.

36



mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant to input.

● destination: override the destination queue name withthe string specified in this field.

● destqmgr: the name of the remote queue manager fromwhich to fetch the message.

The queue managers involved must beconfigured with the necessary sender andreceiver channels in place and started.

● correlationId: provide a correlation identifier for thismessage by mapping a byte array to this field. TheXPath statement tib: string-to-base64("correlationid") is sufficient to populate this field.The provided correlation ID is used to filter messagesfrom the queue.

● messageId: specify a message ID. This value overridesthe default value generated by the queue manager. Therules are the same as for correlationId. If a messageID is provided, it is used to filter the get results.

● groupId: specify a group ID. If a single message isplaced in the queue using a specific group ID, then thismessage can be filtered and received by a Get activityafter this activity maps the correct group ID there. Thisfield is provided for use as an extra filter field only.

● characterSet: set the IBM Coded Characterset ID ofthis message. Valid values are:




— 1200: Unicode.

— 1208: UTF-8.



● waitinterval: specify a new get timeout value for thisoperation only. It is the number of milliseconds that theoperation waits before timing out. If the Wait Forevercheck box in the General tab is selected , this field isignored.

37


Output

The following table lists the output items for the Get activity:


Batch N If BatchGroup is selected for this activity, this Batchnode is the high level item for the activity andcontains a number of InteractionOutput nodesequal to or less than the Batch Size parameterdepending on how many messages are availablewithin the timeout period. If a get in theBatchGroup mode encounters a logical message onthe queue, even after processing one or more singlemessages, an entire logical message is retrieved aspart of the get operation. This might cause theoutput node to exceed the size of the Batch Sizeparameter. It is good practice to design theapplication such that queues containing logicalmessages contain only logical messages.

InteractionOutput N The root node for all the output provided by theactivity.

38



mqproperties N The node containing all the message header fields(plus the destination override) which are relevant tooutput.

● destination: to document the destination forthis message. If the queue is a dynamic queue,the generated name is reported here.

● destqmgr: the name of the remote queuemanager supplied in the input schema.

● correlationId: to document the messagecorrelation ID, if any.


● groupId: to document the group ID.

● characterSet: to document the character set thequeue manager uses to process this message.

● alternateUserId: to document the alternateuserid used in this operation, if any.

● accountingToken: the accounting tokenprovided by the sending application.

● applicationIdData: application ID data. This isthe application data provided by the sender ofthe message.

● applicationOriginData: origin data asprovided by either the sender of the message orthe queue manager.

● putApplicationType: the type of theapplication that puts the message.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF

39



MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: application name data asprovided by either the sender of the message orthe queue manager.

● userId: the effective user ID used to connect tothe queue manager.

● replyToQueueName: the name of the queue towhich a reply is sent. If the type of the message isRequest, then this is the name of the queue thatthe application sends the reply message to.

● replyToQmgrName: the name of the remote queuemanager for this message's reply-to destination,if one is provided.

● format: to describe the nature of the data in themessage. The sender of the application can usestandard names (these names are prefixed by theMQ text) or application-generated names. If themessage originates from a TIBCO ActiveMatrixBusinessWorks Plug-in for WebSphere MQapplication, this is an empty string.

● expiry: the expiration time (in tenths of asecond), after which the message is eligible to bediscarded by the queue manager.

The default value of -1 means there is noexpiration.

● priority: the priority (from 1 to 9) with whichthe message is sent.

● reportOptionPan: reflects the value of thePositive Acknowledgment bit of the report

40



field. This field is an application only field and isnot acted upon by the queue manager.

● reportOptionNan: reflects the value of theNegative Acknowledgment bit of the reportfield. This field is an application only field and isnot acted upon by the queue manager.

● report: to document the numerical value of thereport field.

● encoding: to document the numerical value ofthe encoding field. This encoding is used forextracting numerical data from the message ifthe numbers are in properties or a message bodyschema.

● messageType: enumerated value indicating themessage type:

— 8 is Datagram.

— 2 is Reply.


● backoutCount: the number of times this messageis backed out before being committed.

● feedback: if the message is a Report message,this field defines the nature of the report.Defaults to 0 for non-report messages.

● version: to document the version of themessage. This plug-in supports type 2 messagesonly.

● putDateTime: the time that the message isplaced into the queue.

● groupStatus: to indicate whether the message ispart of a logical message. It can contain any ofthe following:

— MSG_IN_GROUP



appProperties N This field maps the application properties present inthe received message to the schema attached to theactivity. Properties which are missing or not presentin the schema are not shown here.

41



messageFields N Contains the message body formatted using Schemain the Message Content Type field of the Generaltab.

This field is displayed for schema-based messagesonly.

dynamicProperties N● dynamic property: these properties are exactly

the same as those mapped through theappProperties node with the exception that nospecial schema is required to map them. AdynamicProperties node is created for eachproperty in the message which was not mappedby the appProperties schema mechanism. If noappProperties schema is in place, all propertiesare dynamic.



● type: the type for the property. The valid typesare "string", "boolean", "short", "integer","long", "float", "double", and "byte".

bytes N If the activity is configured to use binary messages,then this field contains the output body of themessage. Typically, this byte array is to be mappedas input to a TIBCO ActiveMatrix BusinessWorksPlug-in for Data Conversion parse activity.

This field is only displayed when Binary is selectedin the Message Content Type area.

text N If the activity is configured to use text for thepayload, this field is present and contains thecontents of the message decoded as a string.

This field is only displayed when Text is selected inthe Message Content Type area.

lastMessageInGroup N This field is displayed in the output schema afterclicking CustomGroup in the Multi-MessageSupport area .

In a custom group, this flag indicates the lastmessage in the group.

lastSegment N This field is displayed in the output schema afterclicking CustomSegmented in the Multi MessageSupport area.

In a segmented message, this flag indicates the lastmessage in the group.

42



responsetimemillisec N To indicate how long it takes to receive the message.This value includes any time spent waiting on anempty queue.

Fault

The Fault tab lists the possible exceptions that occur in the Get activity:

Error SchemaElement


msg String The descriptive text provided by this exception object.

msgCode String If the message has a BW message code, it is mapped to this field.




WebSphere MQ InquireThe WebSphere MQ Inquire activity inquires about the current state of a queue and is primarilyintended to obtain the depth of the queue.

General

The General tab of the Inquire activity contains the following fields:

NameGlobalVariable Description

Name N Name of the activity.


Destination Y The name of the queue from which the state is retrieved.

Logger Name Y Enter the name of any pre-configured logger available to the runtime. Loggers are configured in an XML document referencedby the Dlogback.configurationFile runtime parameter.

Description

A short description for the Inquire activity.

43


Input

The following table lists the input items for the Inquire activity:

Input ItemGlobalVariable Description

InteractionInput N The root node for all the input provided to the activity

mqproperties N destination: the destination can be overridden at run time.

destqmgr N Destination queue manager, for future use only.

Output

The following table lists the output items for the Inquire activity:

Output ItemGlobalVariable Description


● depth: documents the current depth of the queue (thatis, how many messages are in the queue).

● maxDepth: documents the configured maximumdepth of the queue.

● maxMsgLength: documents the configured maximumsize of any individual message in the queue.

● type: documents the configured queue type.

● shareability: documents the configured shareabilityfor the queue.

● triggerDepth: documents the configured triggerdepth for the queue.

● openInput: the number of handles open for input onthis queue.

● openOutput: the number of handles open for outputon this queue.

mqproperties N The node containing all the message header fields (plusthe destination override) which are relevant on input.

● destination: documents the actual destination usedfor the inquiry.

● destqmgr: destination queue manager, for future useonly.

responsetimemilli

sec

N The number of milliseconds the inquiry takes.

44


Fault

The following table lists the error schema elements for the Inquire activity:

Error Schema ElementDataType Description

msg String The textual message as it relates to the direct or underlyingcause of the exception that caused the activity to fail.

msgCode String The error message identifier for this message.

mqCompCode String The completion code for the failing WebSphere MQ APIcall if applicable.

mqReasonCode String The reason code for the failing WebSphere MQ API call ifapplicable.

mqErrorCode String If extra information is available to augment that providedin the msg field it is provided here, otherwise this is a copyof msg.

WebSphere MQ ListenerThe WebSphere MQ Listener activity listens on a queue and when a message arrives that satisfies theconfigured filters it retrieves and it starts a process including the contents of the message.

The listener can poll a queue based on interval and a timeout values, or it can wait indefinitely on aqueue. Regardless of which mode it is in, when messages arrive on the queue and the listener isrunning, they are each processed immediately with no intervening interval time.

45


When using the Listener activity, it is important to understand the relationship between theBusinessWorks engine and WebSphere MQ API. The engine can stop the Listener activity, or the wholeapplication in response to commands from the administrator in TIBCO Enterprise Administrator.However, WebSphere MQ API does not provide any mechanism to interrupt threads, which areblocked on the get methods. So even though, the Listener activity is instructed to stop, it cannotterminate the currently executing thread, which is waiting on the get call. In a polling Listener activity,this situation is resolved when the timeout interval expires and the thread exits. However, a non-polling Listener activity never exits the get call. There are two scenarios to show this situation.● A message arrives after a Listener activity is stopped. In this scenario, the message is rolled back if

there is a unit of work in effect. If there is no unit of work, the message is returned to the queuethrough a put call. Note that if the listener does not have the authority to put the message back onthe queue, it attempts to put it on the dead letter queue. If there is no dead letter queue or there is anerror putting the message on it, the message is lost and an error message is issued.

● There are two listeners in the same queue after you start a new listener. Normally this is not anissue, because when a new message arrives, the first listener exits. However, if the queue isconfigured to be opened only by one listener, the newly started listener gets errors whileconnecting. It continues to attempt to connect and issue warning messages periodically. Until amessage arrives, it terminates the first listener, after that, the newly started listener connects andprocesses the message.

There is another general scenario, which affects all process starters. If the Listener activity receives anumber of messages and creates processes for them, but those processes are either running or waitingto run without adding checkpoints and the engine is shut down, those messages are lost. If it isimperative that messages are never lost, you can select the Require Client Confirmation check box inthe General tab to ensure their integrity.

General

The General tab of the Listener activity contains the following fields:


Name N The name to be displayed as the label for the activity in the process.

Connection Y The connection resource which connects this activity with the queuemanager that has access to the desired queue.

Instances Y Enter the number of instances of the queue listener you want thisactivity to run. This translates exactly to the number of threads andconnections to the queue manager created by this activity.

The default is 1 and the maximum is 64.

If the Require Client Confirmation check box is selected, eachthread this activity runs waits for the confirmation before gettinganother message from the queue. Therefore, to process messages inan absolute serial fashion, start only one instance of the listener. Inthis case, the number of messages processed becomes a function ofhow much latency exists in the activity prior to the confirmation.

Destination Y The name of the queue from which the message is retrieved.

DynamicDestination

N A flag that enables the creation of a dynamic queue. When selected,the Dynamic Destination Model field is enabled.

46



DynamicDestinationModel

Y Provide the name of the model queue after which this dynamicqueue is patterned. This field is only available when the DynamicDestination check box is selected.

It is good practice that static queue names (queue namesthat do not contain a pattern) be used for listeneractivities. If a pattern is used for a Listener activity queuename, the name generated by the queue manager is notavailable until the listener creates a process which makesit impossible for a sender to know the name.

MessageContent Type

N Select the type of message contents:

● Binary: the body of the message is represented as a byte array tosubsequent activities in the process and is contained in the byteselement.

● Text: the body of the message is represented as a string tosubsequent activities in the process and is contained in the textelement. This string is converted from the bytes in the messageusing the characterSet element in effect for this message.

● Schema: if the message has been written using the MQMessageread/write API calls, it can be parsed here by providing a schemaresource that conforms to the schema of the message.

MessageBody Fields

Y If the message has been written using the MQMessage read/writeAPI calls, use this field to map a schema conforming to the messagebody.

Fail IfQuiescing

N Select the Fail If Quiescing check box to prevent this listener fromholding up a queue manager quiesce operation. If the queuemanager does terminate, the activity attempts to reconnectindefinitely.

Access Mode N Select the access mode for the queue:

● QDEFAULT: it accepts the access mode established when thequeue is created.

● SHARED: other listeners can access the queue in this mode.

● EXCLUSIVE: other listeners cannot access the queue in thismode. During execution, if the queue is opened by anotherapplication, then the activity fails.

GMOConvert

N Causes the get message option MQGMO_CONVERT to be used for thisget operation. It causes the queue manager to convert string andnumeric fields using the characterSet and encoding elementsbefore the data is copied to the message buffer.

47



RequireClientConfirmation

N Select the Require Client Confirmation check box to request theexplicit confirmation of a received message.

The confirm activity can be used to confirm the message’s arrivaland remove it from the queue. The plug-in uses the queuemanager's syncpoint capability to ensure that the message is onlyremoved from the queue if it is confirmed.

The activity waits for the confirmation before obtaininganother message which imposes limit on throughput. Ifserial processing of the messages is not essential, raise thevalue of the Instances field until the desired throughput isachieved.

If the activity fails to confirm the message, it loops and repeatedlyprocesses the same message. To avoid this behavior, it is goodpractice to copy the message to an error queue and then confirm theoriginal.

Logger Name Y Enter the name of any pre-configured logger available to the runtime. Loggers are configured in an XML document referenced by theDlogback.configurationFile runtime parameter.

Description

A short description for the Listener activity.

Multi-Message

The Multi-Message tab of the Listener activity contains the following fields:

48




N Two options are supported:

● None● BatchGroup

If BatchGroup is selected, an activity is started by a listener tooperate in the batch mode that contains multipleInteractionOutput nodes, each representing one message in thebatch. You can determine the number of discrete messages to beincluded in the batch with the Batch Size field enabled. When Noneis selected, the Listener activity processes a single message at onetime from the queue.

The main use for BatchGroup mode is to process an entire logicalmessage in a single job.

If the Require Client Confirmation check box is selectedfor a batch, the entire batch is confirmed when theConfirm activity runs. If an error is detected whileprocessing a message, the entire batch must bereprocessed.

Batch Size Y If BatchGroup is selected, this field becomes enabled. Enter validinputs range from 1 to 100 to control the size of the batchesretrieved by this listener.

CompleteMessage

N Enable this field to cause the listener to only process the firstmember of a logical message when all the members of the logicalmessage have been written to the queue. This must be deselectedwhen processing incomplete logical messages and when processinghuge logical messages one message at a time.

Get Ordered N Select this field to cause logical messages to be processed in theorder in which they are created. To process incomplete logicalmessages, do not select this field. This option requires that the queuebe indexed, otherwise it is disabled dynamically at run time.

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits because of the overhead involved. However, you mightselect this check box to force the creation of a unit of work andsubsequent commit. The commit happens after any applicationproperties and message body fields have been processed, soselecting this check box protects you from removing a message fromthe queue only to fail while processing the contents. Messagecontents can cause failures if, for example, the encoding or characterset is inappropriate for the data, or the schema used to process themessage is in error.

SyncpointUsed

N This field is not a configuration parameter, but is a status indicationof whether the activity is configured to require a syncpoint or not.Because of the cost of syncpoint operations, every effort has beenmade to avoid them. If the activity requires a confirmation or usesmultiple messages, a sync is required.

49



Poison MsgDetection

N Select this check box to turn on poison message detection. If theListener activity processes a message where the backout count isgreater than the poison message threshold, the message is notprocessed but is moved to the designated poison message queue.This prevents the Listener activity from looping on a message thatcannot be confirmed. Note that this check box is only available afteryou select the Require Client Confirmation check box and clickNone from the Multi -Message Support area in the Listener activity.

Poison MsgThreshold

Y Enter the backout count at which a message is considered poison. Ifthe backout exceeds this value, it is moved to the poison messagequeue.

Poison MsgQueue

Y Enter the queue which poison messages are moved to.

Advanced

The Advanced tab of the Listener activity contains the following fields:


Sequence Key N This field can contain an XPath expression that specifies whichprocesses are required to run, and in which in order. Processinstances with sequencing keys that evaluate to the same value areexecuted sequentially in the order the process instance is created.

See the TIBCO ActiveMatrix BusinessWorks documentation formore information about controlling the execution order of processinstances and about XPath expressions.

Custom Job Id N This field can contain an XPath expression that specifies a custom IDfor the process instance. This ID is displayed in the View Servicedialog of TIBCO Enterprise Administrator, and it is also available inthe $_processContext process variable.

50



EnablePolling

N When selected, the activity instantiates a connection to the queuemanager and opens the queue. It then periodically issues timed getson the queue where the timeout value is equal to the polling timeoutand the period between gets is equal to the polling interval.

However, if there are multiple messages in the queue they areprocessed without an intervening polling interval, thus diminishingapplication latency.

When cleared, the activity waits forever in the queue, processingmessages as they arrive. If the queue manager connection fails, theactivity attempts to reconnect based on the reconnection interval. Ifthe listener is not polling, it is doing an unbounded get on thequeue, and the listener does so even after the application is set tostop using the administrator or shell command. To release theconnection and close the destination, you must stop the appNode onwhich this application is running. This also means that if youredeploy the application without recycling the appNode, theconnections from the previous deployment persist until the node isrecycled. This is because there is no safe way to interrupt aWebSphere MQ native Java API get method.

A poor choice of polling interval and polling timeoutvalues might impose a high overhead on the engine aswell as the queue manager to which the activity isconnected. Use values here which take into account thelatency in the network between this activity and the queuemanager, as well as the processing demands you arewilling to place on that queue manager.

PollingInterval

Y If the Enable Polling check box is selected, this is the interval atwhich a new polling cycle is initiated.

Specify time in milliseconds.

Valid range: 100 to 1000000

Default: 1000

PollingTimeout

Y If the Enable Polling check box is selected, this is the timeout valuefor each individual listen. The value specified here must besignificantly smaller than the polling interval. This minimizes thenumber of concurrent connections to the queue and reduces theprocessing resources needed.



Default: 1000

51



ReconnectionInterval

Y The length of time, in milliseconds, that the listener waits betweenattempts to reconnect to the queue.

This setting is used only when the Enable Polling check box iscleared. If the Enable Polling check box is cleared, the Listeneractivity listens indefinitely on the queue. However, if an error occursand the queue manager is subsequently unavailable (shut down forexample), this value is the number of milliseconds betweenreconnection attempts.


Default: 10000

FilterEncoding

N This field specifies the encoding of the values provided in theCorrelation Id, Message Id, and Group Id fields. The FilterEncoding field provides three types of values: text, base64, andhexbin.

When this field is set to either base64 or hexbin, the values of thethree Id fields are transformed appropriately to form a binary filteras follows.

For example, a valid base64 filter isbzkMF27syhmb37nm8kPQojEupbpNVJHm and a valid hexbin filter is6f390c176eecca199bdfb9e6f243d0a2312ea5ba4d5491e6.

Note that you do not use a prefix "0x" with the hexbin filter.

Correlation Id Y The Listener activity instructs the queue manager to filter therequest based on this correlation ID. Only messages with exactly thesame ID are accepted.

Message Id Y The Listener activity instructs the queue manager to filter therequest based on the specified message ID.

In contrast to correlation IDs, message IDs are alwaysprovided. If the listener does not explicitly state a messageID, it accepts any message. If an ID is provided, the listenis filtered for that message ID.

Group Id Y The Listener activity instructs the queue manager to filter therequest based on the specified group ID. Only messages with exactlythe same group ID are accepted.

52




N Select the Application Properties resource to be used to map theoutput of this get. Application properties are similar to regularmessage header fields except that the name and type of the fieldscan be determined by a predefined schema. If the received messagecontains properties, they are mapped according to this schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and map thatschema to this field. See the IBM WebSphere MQ documentation forproperty types supported by the level of client you have installed.


PropertyControl

N Select one of the following settings:


After selecting one of these options, you can use the Listener activityto inter-operate with various versions of WebSphere MQapplications. Which option to use varies depending on the sendingapplication. See the section entitled "MQGMO message propertyoption setting" in the IBM WebSphere MQ documentation fordetailed information.

Conversations

You can use the Conversations tab of the Listener activity to initiate or join a conversation.

Conversations receive messages after the creation of a process instance, which is initiated or joined byan activity. This activity can be used to initiate a conversation. Click the Add New Conversation iconto initiate a conversation. For more details regarding conversations, see TIBCO ActiveMatrixBusinessWorks Application Development.

Output

The following table lists the output items for the Listener activity:

Output Item

ModuleProperty? Description

Batch N If BatchGroup in the Multi-Message tab is selected, this node ispresent and contains an InteractionOutput node for eachmessage retrieved as part of this batch.


53


Output Item


mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant to output.

● destination: to document the destination for this message.If the queue is a dynamic queue, the generated name isreported here.

● destqmgr: if the message is routed through a remote queuemanager, document the name of the destination queuemanager.

● correlationId: to document the message correlation ID, ifany.


● groupId: to document the group ID used for this message, ifany.

● characterSet: to document the character set the queuemanager uses to process this message.

● alternateUserId: to document the alternate userid used inthis operation, if any.

● accountingToken: the accounting token provided by thesending application.

● applicationIdData: application ID data as provided by thesending application.

● applicationOriginData: additional information about theorigin of the message provided by the sender of the message.

● putApplicationType: the type of the application that putsthe message.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

54


Output Item


● putApplicationName: the name of the application that putsthe message.


● replyToQueueName: the name of the queue to which a replyis sent. If the type of the message is Request, then this is thename of the queue that the application sends the replymessage to.

● replyToQmgrName: the name of the remote queue manager tobe used when processing any reply or report message.

● format: a name that describes the nature of the data in themessage. The sender of the application can use standardnames (these names are prefixed by the MQ text) orapplication generated names. If this message originates froma TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ application, then this field contains an empty string.

● expiry: the expiration time (in tenths of a second), afterwhich the message is eligible to be discarded by the queuemanager. This contains whatever value is used when themessage is sent.

● priority: the priority (from 1 to 9) with which the messageis sent.



● report: this is the report options field for the message. Ifreports are requested for the message, the relevant bits arepresent here.

● encoding: this is the encoding element for the message andit specifies the representation used for numeric values in theapplication message data. This applies to binary, packeddecimal and floating point data. This encoding element isused when processing of fields mapped by a message bodyschema. For specific values, see the MQMessage encodingfield in the WebSphere MQ documentation.

● messageType: enumerated value indicating the message type.

Where:

● 8 is Datagram.

● 2 is Reply.

55


Output Item


● 4 is Report.● 1 is Request.

● backoutCount: the number of times this message was backedout before being committed.

● feedback: if the message is a Report message, this fielddefines the nature of the report. Defaults to 0 for non-reportmessages.

● version: to document the version of the message. This Plug-in supports type 2 messages only.

● putDateTime: the time that the message is placed into thequeue.

● groupStatus: to indicate whether the message is part of alogical message. It can contain any of the following:

— MSG_IN_GROUP



dynamicProperties● dynamic property: these properties are exactly the same as

those mapped through the appProperties node with theexception that no special schema is required to map them. AdynamicProperties node is created for each property in themessage which was not mapped by the appPropertiesschema mechanism. If no appProperties schema is in place,all properties are dynamic.



● type: the type for the property. The valid types are "string","boolean", "short", "integer", "long", "float","double", and "byte".

bytes N The output body of the message. Typically, this byte array is tobe mapped as input to a Data Conversion Plug-in parse activity.


text N If the activity is configured to use text messages then this node ispresent instead of the bytes field. The contents of the messageare decoded into a string using the Java default encoding andpresented here.

This field is only displayed when Text is selected in the MessageContent Type area.

56


Output Item


responsetimemilli

sec

N The time, in milliseconds, that the listener takes to receive thismessage. It is measured from when the listener starts listening towhen it finishes creating the event context passed to theremaining activities in this process.

appProperties N This field maps the application properties present in the receivedmessage to the schema attached to the activity and only displaysif application properties are mapped on the Advanced tab.Properties which are missing or not present in the schema arenot shown here.

messageFields N Contains the message body formatted using Schema in theMessage Content Type field of the General tab. Each field in theschema is mapped here.


Fault

The Fault tab lists exceptions that occur in the Listener activity:

Error SchemaElement


msg String The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQerror message.

msgCode String The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQerror code.



mqErrorCode String If the message originates as a WebSphere MQ API exception, thenthat exception's reason code is here.

WebSphere MQ PublishThe WebSphere MQ Publish activity publishes a message to a dynamic or predefined topic.

The activity is capable of sending any of the four message types described in the WebSphere MQ Putactivity. The capabilities of the activity are determined by the configuration, with some runtimebehaviors controlled by the input schema. The type of the message being sent might determine whatfields are applicable for the publish operation, for example, request messages are incompatible withreport options. Even though this is a pub/sub type of activity, the report and reply-to queues are realqueues, not topics.

In WebSphere MQ, a topic is defined as a string of characters starting with a forward slash (/) and cancontain many topic nodes to the right. WebSphere MQ supports a mechanism for separating

57


administratively defined topic strings from application-defined ones. This is exposed on the publishactivity by the Destination field and the Topic Dynamic field. The intent is that administrativelydefined portions of the topic string are represented by selecting a permanently defined topic for the firstpart of the topic string and concatenating the dynamic portion to the right. This way an application canbe deployed in several environments without naming conflicts.

There is no difference between the message object published by this activity from the one sent by thePut activity.

General

The General tab of the Publish activity contains the following fields:



Connection Y The connection resource which associates this activity with thequeue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined topic to which themessage is published. This field is optional in the event that thetopic string is to be entirely specified in the Topic Dynamic fieldor the input schema.

Topic Dynamic Y The contents of this field are concatenated to the topic namereferenced by the administratively defined topic. If noadministratively defined topic is provided this string forms theentire topic string.

Message ContentType

N The following types of message content are supported:

● Binary: the bytes field in the input schema to map bytearray data onto the outgoing message.

● Text: the text field in the output schema onto which regularstring data can be mapped. At run time, this string isconverted to bytes using the default Java encoding.

● Schema: select Schema to write the message body such thatit conforms to a schema. The schema to be used is designedas a sharable resource and is provided for mapping on theinput schema.

Message BodyFields

Y Provide the schema to be used in the Input tab, and at run timeto encode the contents of this message.

58



Message Type N Select the type of the message that is to be sent:

● Datagram● Request● Reply● Report

If a Request message is selected, the Reply To Destination fieldis enabled and the report options are disabled. The reportoptions are available when using any other message type.

Reply ToDestination

Y This Reply To Destination field is enabled only when theRequest message type is selected from the Message Type list.This field contains the queue name which is placed into thereplyToQueueName field in the Input tab. Click Choose a field

value type next to the Reply To Destination field to selectthe queue.

Retain Message N Select the Retain Message check box to indicate that themessage is to be retained in the queue manager even if nosubscribers exist. The future subscribers can receive the messagewhen they are created. This is useful for conveying applicationstate information.

Fail If Quiescing N Select the Fail If Quiescing check box to prevent this activityfrom holding up a queue manager quiesce operation.


N Select a schema which represents the application properties tobe placed in this message. To use application properties, create ageneric XML schema composed of a node with simple elementsinside it and map that schema to this field.

See the IBM WebSphere MQ documentation for property typessupported by the level of client you have installed.


Logger Name Y Enter the name of any pre-configured logger available to therun time. Loggers are configured in an XML documentreferenced by the Dlogback.configurationFile runtimeparameter.

Description

A short description for the Publish activity.

Advanced

The Advanced tab of the Publish activity contains the following fields:

59



MessagePriority

Y Set the priority of the message as it is to be retrieved by thequeue manager. The values range from 0 to 9. If not specified,the default is the destination queue's default priority.

Context Support N The input fields of a publish operation fall into categoriesbased on their context. Many fields are always present, butothers are only present if the context relevant to that field ischosen. This is because the queue manager must grant the userthe authorization to update these fields.

Select one of the following settings:

● Default: the input schema conforms to the fields accessibleto a user with the default authority.

● Identity: the input schema conforms to the fields accessibleto a user with the Set Identity Context authority.

The new fields are:

● accountingToken

● applicationIdData

● userId

● All: the input schema conforms to the fields accessible to auser with the Set Identity Context and Set All Contextauthorities.

The new fields (in addition to those provided by Identity)are:

● applicationOriginData

● putApplicationType

● putApplicationName

60



Confirm OnArrival

N Trigger a report message by using the Confirm on Arrivaltype. The report is not enabled by default.

Report types are:

● NONE: the report is not enabled.

● NO_DATA: the body of the message does not accompanythe report.

● WITH_DATA: the first 100 bytes of the message bodyaccompanies the report.

● FULL_DATA: the entire body of the message accompaniesthe report.

Reports are delivered to the reply to queue specified in theReport Reply Queue field. Because this field maps to themessage's replyToQueueName field, reports are mutuallyexclusive with the Request type messages. That is, if themessage type is Request, a report confirmation is not sent.

Confirm OnDelivery

N Trigger a report message by using the Confirm on Deliverytype. The report is not enabled by default.

Report types are:






61



Confirm OnException

N Trigger a report message by using the Confirm on Exceptiontype. The report is not enabled by default.

Report types are:






Confirm OnExpiry

N Trigger a report message by using the Confirm on Expiry type.The report is not enabled by default.

Report types are:






Report ReplyQueue

Y Enter the name of the queue where you want to send Reportmessages. The value entered here maps onto thereplyToQueueName field.

AsynchronousPut*

N Select the check box to achieve a modest improvement in thelatency of the Put activity if your application can tolerate thepotential for an unreported failure writing to the queue. Seethe IBM WebSphere MQ documentation for the put messageoption MQPMO_ASYNC_RESPONSE for more informationregarding the risks of this option.

Input

The following table lists the input items for the Publish activity:

62



InteractionInput N This input schema field is the root node for all the inputprovided to the activity.

63



mqproperties N The node containing all the message header fields (plusthe destination override) that are relevant to input.

● destination: specify a destination here to overridethe topic name from the configuration panels.

● destqmgr: destination queue manager name. Thename of the queue manager on which this topic islocated.

A transmission queue and a senderchannel must be configured for this queuemanager for it to work.

● topicdynamic: the dynamic portion of the topicstring. This can be the entire topic string andoverride any dynamic topic specified on theconfiguration panel.

● correlationId: to provide a correlation identifierfor this message by mapping a byte array to thisfield. The XPath expression tib:string-to-base64("correlationid") is sufficient to populate thisfield. This field is only valid if the topic referenced isan administratively defined unmanaged topic. In allother cases, it is ignored by the queue manager.

Consult the IBM WebSphere MQ documentation fordescriptions of managed and unmanagedsubscriptions.

● messageId: to provide a message identifier for thismessage by mapping a byte array to this field. TheXPath expression tib:string-to-base64("messageId") is sufficient to populate this field.This field is only valid if the topic referenced is anadministratively defined unmanaged topic. In allother cases it is ignored by the queue manager.

● characterSet: to set the IBM Coded CharactersetID of this message.

Valid values are:

● 850: The commonly used ASCII codeset.

● 819: The ISO standard ASCII codeset.

● 37: The American EBCDIC codeset.

● 1200: Unicode.

● 1208: UTF-8.



64



● accountingToken: to provide a binary (base 64encoded) accounting token to be used on hostsystems to assist in accounting for resources used bythe application.

● applicationIdData: to provide a string that can beused on all end points to identify this application.

● applicationOriginData: to provide informationrelated to the originating application node for thismessage.

● putApplicationType: to provide either one of theIBM documented application type enumerators forthis application or one of your choosing.

See the IBM WebSphere MQ documentation for themeaning of the documented application types.

The documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT

65



0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

● putApplicationName: the name of the applicationthat puts the message. Provide information aboutthe originating application in this field.

● userId: to provide the user ID to be used whenauthorizing this message as it traverses themessaging system. For operations with reportoptions, this field is mandatory. If a value is notprovided here, it is taken from the connectionresource if one is available there, and from theenvironment if it is not.

● replyToQueueName: to specify the name of anexisting queue that the target application can use asa destination for its response. This enables thecommon "request response" pattern.

● replyToQmgrName: destination queue managername. The name of the queue manager on which thisqueue is located.

A transmission queue and a senderchannel must be configured for this towork.

● format: to describe the nature of the data in themessage. It defaults to a space character orMQFMT_NONE. A user defined format can be usedto assist the receiving application in decoding themessage, for example, in the selection of a DataConversion parse activity for this message type.

● expiry: to indicate the length of time (in tenths of asecond) that the message is kept in the queue beforebeing deleted. Defaults to -1, which means there isno expiration. This field overrides the configurationvalue for expiry if it is mapped.

Permissible values are positive integers or -1.

● priority: the priority (from 1 to 9) of the message.This field overrides a configuration value for priorityif it is mapped.

● reportOptionPan: this is the PositiveAcknowledgment report field and is provided by thesending application. This report field is not actedupon by the queue manager.

● reportOptionNan: this is the NegativeAcknowledgment report field and is provided by thesending application. This report field is not actedupon by the queue manager.

66



● report: this is the report options field for themessage. If nothing is entered, then the reportoptions as configured in the Advanced tab are usedto populate it at run time. However, if a number ismapped here, it is logically OR'ed with the results ofprocessing the report options. It is provided toenable the use of report options not configurable inthe Advanced tab.

● encoding: this is the encoding field for the messageand it specifies the representation used for numericvalues in the application message data. This appliesto binary, packed decimal and floating point data.This encoding is used when processing of fieldsmapped by a message body schema.

For specific values, see the MQMessage encodingfield in the WebSphere MQ documentation.

dynamicProperties N● dynamic property: these properties are exactly the

same as those mapped through the appPropertiesnode with the exception that no special schema isrequired to map them. A dynamicProperties nodeis created for each property in the message whichwas not mapped by the appProperties schemamechanism. If no appProperties schema is in place,all properties are dynamic. Note that the publish andsubscribe mechanisms in WebSphere MQ usesmessage properties in the implementation, you cansee the property mqps.Top and possibly others on allpublications.




bytes N Map the main content of the message body here. Ingeneral, this is the output of a Plug-in for DataConversion render activity, but can be any array ofbytes. If string data is to be mapped to this field, use theXPath function tib:string-to-base64 to convert it tobytes.

This field is only displayed when Binary is selected inthe Message Content Type area.

67



text N This field contains a text representation of the bytes inthe message body as converted using the default Javaencoding.


appProperties N Contains fields that correspond to the schema as it isdefined in the application properties resource that ismapped to this activity.

The appProperties node is only present if aWMQ Properties Resource has beenconfigured for the activity.

messageFields N This element is present when Schema is selected fromthe Message Content Type list of the General tab. Thecontents of the mapped schema are present in this nodefor mapping purposes.

Output

The following table lists the output items for the Publish activity:



68



mqproperties N The node containing all the message header fields (plusthe destination override) as they are mapped from themessage after it is sent.

● destination: to document the destination for thismessage. If the topic is a dynamic topic, thegenerated name is reported here.

● destqmgr: to document the remote queue managerspecified in the input schema.

● topicdynamic: to document the effective topic stringfor this publication. This includes the root portionfrom any administratively defined topic provided, aswell as the any dynamic portion.

● correlationId: to document the messagecorrelation ID, if any.




● accountingToken: as provided in the input schema.

● applicationIdData: as provided in the inputschema.

● applicationOriginData: as provided in the inputschema.

● putApplicationType: as provided in the inputschema.

● putApplicationName: as provided in the inputschema.

● userId: the effective user ID used to connect to thequeue manager.

● replyToQueueName: same as input.

● replyToQmgrName: same as input.

● format: the character string placed into the formatfield by the sending application.

● expiry: to indicate the number in tenths of a secondthat the message is to be kept in the queue beforebeing deleted. Defaults to -1, which means there isno expiration.


● reportOptionPan: reflects the value of the PositiveAcknowledgment bit of the report field. This field isan application only field and is not acted upon by thequeue manager.

69



● reportOptionNan: reflects the value of the NegativeAcknowledgment bit of the report field. This field isan application only field and is not acted upon by thequeue manager.

● report: this is the report options field for themessage. If nothing is entered, then the reportoptions as configured in the Advanced tab are usedto populate it at run time. However, if a number ismapped here, it is logically OR'ed with the results ofprocessing the report options. It is provided toenable the use of report options not configurable inthe Advanced tab.

● encoding: this is the encoding field for the messageand it specifies the representation used for numericvalues in the application message data. This appliesto binary, packed decimal and floating point data.This encoding element is used when processing offields mapped by a message body schema. Forspecific values, see the MQMessage encoding field inthe WebSphere MQ documentation.

● messageType: enumerated value indicating themessage type.

Where:

● 8 is Datagram.

● 2 is Reply.

● 4 is Report.● 1 is Request.

● backoutCount: the number of times this message isbacked out before being committed.

● feedback: if the message is a Report message, thisfield defines the nature of the report. Defaults to 0 fornon-report messages.

● version: to document the version of the message.This plug-in supports type 2 messages only.

● putDateTime: the time that the message is placedinto the queue.

● groupStatus: to indicate the logical message statusof a message. Pub/Sub does not support logicalmessages so this field is empty.

responsetimemillisec N To indicate, in milliseconds, how long it takes to publishthe message.

70


Fault

The Fault tab lists exceptions that occur in the Publish activity:

Error SchemaElement Data type Description






WebSphere MQ PutThe Put activity can place messages into a configured queue.

The four types of messages are as follows:

● Datagram: basic message.

● Request: a message for which the sending application expects a response and for which a Reply toQueue is required.

● Reply: a message sent in response to a received Request type message. Usually the destination forthis message has been mapped from the Reply To Queue field of the request message.

● Report: a message containing monitoring data. In most cases, report messages are generated byqueue managers. However, it is possible for applications to do so using this message type.

The activity is capable of sending any of the four message types to permanent or dynamic queues. Thecapabilities of the activity are determined by the configuration, with some runtime behaviors controlledby the input schema. The type of message being sent might determine what fields are applicable for theput operation.

Messages can be sent to predefined queues or dynamic queues. If the destination or the reply to queueis dynamic, you must specify a properly configured model queue. The queue manager constructs adynamic queue based on that template. The name of a unique dynamic queue can be generated if thequeue name provided ends with an asterisk (*). It makes sense to use such names only if it is possible toconfigure a receiving application with the name of the newly created queue. The name can be takenfrom the destination element in the Output tab.

General

The General tab of the Put activity contains the following fields:

71




Connection Y The connection resource which associates this activity with thequeue manager that has access to the desired queue.

Destination Y The name of the queue onto which the message is placed. If thequeue is to be created dynamically, enter the name of thedynamic queue. The name must follow the MQSeries rules fordynamic queue names.

If the queue name has been dynamically mapped using theinput schema's destination field, this field is not required.

DynamicDestination

N Select this check box to enable the creation of a dynamic queue.When selected, the Dynamic Destination Model field isenabled. Dynamic queues are ones which are created as neededand destroyed when the lifespan dictated by the model isreached.

DynamicDestination Model

Y Select the Dynamic Destination check box to enable this field.

Enter the name of a queue model for the queue manager to useas a template for creating this dynamic queue.

Message ContentType

N Select the type of message content:

● Binary: if Binary is selected, string content can still be sent,but it must be translated to binary through an XPathexpression.

● Text: string data can be directly mapped onto the message.The message is decoded using characterSet for themessage, or 819 if none is provided. Characterset 819 isthe Java API default.

● Schema: the message is formatted according to the schemaprovided in the Message Body Fields field. Input values forthis schema are displayed in the input editor.

Message BodyFields


Message Type N Select the type of the message that is to be sent:

● Datagram● Request● Reply● Report

If a Request message is selected, the Reply To Destination andDynamic ReplyToDestination fields are enabled.

72



Reply ToDestination

Y This field is enabled for the Request message type only.

The queue name which is placed into the message header'sReply To Destination field. If the reply to destination isdynamic, a queue is created and kept open until the end of theprocess. If an asterisk is the last character of the name, or noname is provided, the queue manager generates a name. Thedestination element in the Put activity's output schemadocuments this dynamically generated name, and the sentmessage also contains the name so that the receivingapplication knows where to send the response.

DynamicReplyToDestination

N This check box is enabled if Request is selected in the MessageType field.

When this check box is selected, the Dynamic ReplyToDestModel field is enabled, and the reply queue is dynamicallycreated based on the model in the Dynamic ReplyToDestModel field. If a dynamic reply queue is specified, the dynamicreply queue is created during the put operation so that it isavailable to the responding application. The created destinationexists until the end of the process, so any activity which repliesto this request must do so before the process ends or thedestination is deleted.

DynamicReplyToDestModel

Y Specify the model after which the reply queue is to bepatterned.

This field is enabled only when the DynamicReplyToDestination check box is selected.

Fail If Quiescing N Select this check box to cause the activity to fail if the queuemanager attempts to quiesce during the operation. Thisprevents the queue manager quiesce from being delayed by thisactivity. This check box is selected by default.


N Select the Application Properties resource to be included as partof this message. Application properties are similar to regularmessage header fields except that the name and type of thesefields can be determined by a predefined schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and map itto this field. See the IBM WebSphere documentation forproperty types supported by the level of client you haveinstalled.


73



Logger Name Y Loggers are configured in an XML file used at run time. Theruntime logger configuration is specified by the -Dlogback.configurationFile parameter of either thedeployed application instance or of the debugger instance.After the logger is configured, it can be named here to causeinformational messages to be written there. See the TIBCOActiveMatrix BusinessWorks documentation for more detailsabout how to configure loggers.

Description

A short description for the Put activity.

Multi-Message

The Multi-Message tab of the Put activity contains the following fields:

74




N Select the level of support this activity is to have for batch groupsand logical messages.


● None: the input schema provides only for a single message andit is put without a sync-point. This is the fastest operationconfigurable.

● Batch: the input schema is configured for batch messages.Multiple nodes are sent as separate messages and committed asa single unit of work.

● BatchGroup: the input schema is configured for batch but allthe messages provided are sent as a single logical messagegroup.

● CustomGroup: in this mode, the input schema is configuredfor a single message, and the lastMessageInGroup field isprovided. In this mode, the activity must be used in a loop tocreate a logical message group. On the last pass through theloop, the lastMessageInGroup field of the input schema mustbe set to true to terminate the group.

Unless the activity is in an MQ Local Transaction, each memberof the logical message is committed as the activity ends. If anerror occurs, an incomplete logical message can be left in thequeue. It is therefore good practice to use a local transaction tocommit an entire logical message at once.

● CustomSegmented: in this mode, the input schema isconfigured for a single message and the lastSegment field ispresent to indicate when the last segment of the segmentedmessage is sent. In this mode, the Put activity must be used in aloop to send a segmented grouped message. This is useful if theentire message cannot be held in memory and must beprocessed a segment at a time.

Unless the activity is in an MQ Local Transaction, each memberof the segmented message is committed as the activity ends. Ifan error occurs, an incomplete logical message can be left in thequeue. It is therefore good practice to use a local transaction tocommit an entire segmented message at once.

CustomGroup or CustomSegmented options must beused in a loop because the activity stores the messageobject for use as context when sending the nextmessage.

75



Segmentation N Select the segmentation behavior for this put operation.


● None: the message is not segmented and the queue managercannot segment the message.

● Explicit: this enables the Max Segment Size field and segmentsthe message configured in the input schema into as manysegments as necessary to send the whole message.

● QueueManager: the message is sent with flags set so that thequeue manager can segment it to suit the buffer sizes of anychannels encountered on the way to the destination.

● Both: the message is explicitly segmented by Max Segment Sizeand flags are set supporting the queue manager to furthersegment the message if necessary.

Max SegmentSize

Y If Explicit or Both is enabled, this field is enabled. Enter themaximum size in bytes that any segment of this message canconsume (not including the size of the header on each segment).

Default: 0

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits because of the overhead involved. However, you mightselect the check box to force the creation of a unit of work andsubsequent commit. The commit happens after any applicationproperties and message body fields have been processed, soselecting the check box protects you from removing a messagefrom the queue only to fail while processing the contents. Messagecontents can cause failures if, for example, the encoding orcharacter set is inappropriate for the data, or the schema used toprocess the message is in error.

SyncpointUsed

N This field is not a configuration field, rather it is an indication ofwhether a syncpoint is required for the operation. Non-syncpointoperations are significantly faster than syncpoint ones, howeverthe overhead of a syncpoint is much less significant for largebatches.

If an activity is inside a local transaction, this field isunaware of that fact. In that case, a syncpoint is alwaysin effect for the local transaction.

Advanced

The Advanced tab of the Put activity contains the following fields:

76



Message Priority Y Set the priority of the message as it is to be retrieved by the queuemanager.

MessageExpiration

Y The time, in tenths of a second, that the message persists in thequeue before being deleted by the queue manager. The default, 0,as well as the value -1, mean that the message never expires.

Values range from -1 to 2147483647.

GenerateCorrelation Id

N Select this check box to cause the queue manager to generate aunique correlation identifier for the message when it is sent. Thismeans that the message identifier, which is always generated, iscopied to the correlation identifier field.

If this option is enabled, the queue manager overlaysany correlation identifier that is mapped in the inputschema.

Load Balance N Select this check box to enable load balancing when puttingmessages to suitably configured cluster queues. When it isenabled for a single message, option MQOO_BIND_NOT_FIXEDis used to operate the destination. If the Put activity is for a logicalmessage, the option MQOO_BIND_ON_GROUP is used and ifthe Put activity is likely to be for a message segment, theMQOO_BIND_ON_OPEN option is used. These options ensurethat message groups are all put to the same queue manager. Inother respects, the messages are distributed to queue managersaccording to the workload algorithms in effect for the cluster.

Persistence N Determines whether messages on the queue manager persistacross restarts.


● AS_QUEUE_DEF: it uses the persistence level defined in thequeue definition.

● PERSISTENT: it ensures that the message persists if the queuemanager fails or restarts.

● NOT_PERSISTENT: not persistent.

77



Context Support N The input fields of a put operation fall into categories based ontheir context. Many fields are always present, but others are onlypresent if the context relevant to that field is chosen. This isbecause the queue manager must grant the user the authorizationto update these fields.


● Default: the input schema conforms to the fields accessible toa user with the default authority.

● Identity: the input schema conforms to the fields accessible toa user with the Set Identity Context authority.

The new fields are:

● accountingToken


● userId


The new fields (in addition to those provided by Identity) are:




Confirm onArrival

N Trigger a report message by using the Confirm on Arrival type.The report is not enabled by default.

Report types are:


● NO_DATA: the body of the message does not accompany thereport.


● FULL_DATA: the entire body of the message accompanies thereport.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive withRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

78



Confirm onDelivery

N Trigger a report message by using the Confirm on Delivery type.The report is not enabled by default.

Report types are:






Confirm onException

N Trigger a report message by using the Confirm on Exceptiontype. The report is not enabled by default.

Report types are:






79



Confirm onExpiry

N Trigger a report message by using the Confirm on Expiry type.The report is not enabled by default.

Report types are:






Report ReplyQueue

Y Enter the name of the queue to which Report messages are sent.This queue needs not exist and is not checked, but can be selectedusing Choose a field value type on the right side of the field. Thevalue entered here maps onto a message's replyToQueueNamefield.

Pass CorrelationId

N Determines the setting for a report message’s correlation ID.

● When selected, the correlation ID of the sent message is copiedto the correlation ID field of the report message.

● When cleared, the message ID of the sent message is copied tothe correlation ID field of the report message.

AsynchronousPut*

N Select this check box to achieve a modest improvement in thelatency of the Put activity if your application can tolerate thepotential for an unreported failure writing to the queue.

See the IBM WebSphere documentation for the put messageoption MQPMO_ASYNC_RESPONSE for more information regardingthe risks of using this option.

Input

The following table lists the input items for the Put activity:


Batch N This node is present when any of the multi-message modesare active based on the activity configuration. With it, theInteractionInput node can be duplicated any number oftimes to make up a composite batch for the put operation.

80




81



mqproperties N The node containing all the message header fields (plus thedestination override) that are relevant to input.

● destination: specify a destination here to override thequeue name from the configuration panels. With it, thequeue can be dynamically specified.

● destqmgr: destination queue manager name. The nameof the queue manager on which this queue is located.

A transmission queue and a sender channelmust be configured for this queue manager inorder for it to work.

● correlationId: provide a correlation identifier for thismessage by mapping a byte array to this field. TheXPath expression tib:string-to-base64("correlationid") is sufficient to populate this field.

● messageId: specify a message ID. This value overridesthe default value generated by the queue manager. Therules are the same as for correlationId.

● groupId: specify a group ID. The queue manageroverrides the group ID for any message composed ofmultiple physical messages. However, if the intention isto send a single message and use the groupId elementas an additional filter by the receiving application, thenmapping a group ID here meets that requirement. Therules are the same as that for correlationId.

● characterSet: set the IBM Coded Characterset ID ofthis message. Valid values are:




— 1200: Unicode.

— 1208: UTF-8.

The queue manager might apply this codeset whendoing conversions for the purpose of creatingreport messages.


● accountingToken: provide a binary (base 64 encoded)accounting token to be used on host systems to assist inaccounting for resources used by the application.

● applicationIdData: provide a string that can be usedon all end points to identify this application.

● applicationOriginData: provide information relatedto the originating application node for this message.

● putApplicationType: provide either one of the IBMdocumented application type enumerators for this

82



application or one of your choosing. See the IBMWebSphere MQ documentation for the meaning of thedocumented application types. These are thedocumented enumerations:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

● putApplicationName: provide information about theoriginating application in this field.

● userId: provide the user ID to be used whenauthorizing this message as it traverses the messagingsystem. For operations with report options, this field ismandatory. If a value is not provided here, it is takenfrom the connection resource if one is available there,and from the environment if it is not.

● replyToQueueName: specify the name of a queue thatthe target application can use as a destination for itsresponse. This enables the common "request response"pattern. If the queue is a dynamically created one, it iscreated by the Put activity and is closed at the end ofthe process that creates it. Therefore, any get for the

83



reply must be done in the same process; otherwise, thequeue will be deleted by the queue manager.

● replyToQmgrName: destination queue manager name.The name of the queue manager on which this queue islocated.

A transmission queue and a sender channelmust be configured for this to work.

● format: describes the nature of the data in the message.It defaults to " ", or MQFMT_NONE. A user defined formatcan be used to assist the receiving application indecoding the message, for example, in the selection of aData Conversion parse activity for this message type.

● expiry: indicates the length of time (in tenths of asecond) that the message is kept in the queue beforebeing deleted. Defaults to -1, which means there is noexpiration. This field overrides the configuration valuefor expiry if it is mapped. Permissible values are apositive integer or -1.

● priority: the priority (from 1 to 9) of the message.This field overrides a configuration value for priority ifit is mapped.

● reportOptionPan: set this boolean field to add thevalue Positive Acknowledgment to the report field ofthe message. This field is an application only field andis not acted upon by the queue manager.

● reportOptionNan: set this boolean field to add thevalue Negative Acknowledgment to the report field ofthe message. This field is an application only field andis not acted upon by the queue manager.

● report: this is the report options field for the message.If nothing is entered, then the report options asconfigured in the Advanced tab are used to populate itat run time. However, if a number is mapped here, it islogically OR'ed with the results of processing the reportoptions. It is provided to enable the use of reportoptions not configurable in the Advanced tab.

● encoding: this is the encoding field for the message andit specifies the representation used for numeric valuesin the application message data. This applies to binary,packed decimal and floating point data. This encodingis used when processing fields is mapped by a messagebody schema. For specific values, see the MQMessageencoding field in the WebSphere MQ documentation.

84



dynamicProperties N● dynamic property: these properties are exactly the

same as those mapped through the appPropertiesnode with the exception that no special schema isrequired to map them. Create one node for eachproperty to be placed on the message. Note that if thename of a dynamic property collides with a propertyfrom the appProperties node, the dynamic propertytakes precedence.




appProperties N Contains fields that correspond to the schema as it isdefined in the application properties resource that ismapped to this activity. Application properties areincluded in an MQRFH2 header which is dynamicallyadded to the message.

This node is only displayed if a propertiesresource is specified for the activity.

messageFields N This element is present when Schema is selected from theMessage Content Type list of the General tab. Thecontents of the mapped schema are present in this node formapping purposes.

bytes N Present if Binary is selected in the Message Content Typearea. Map the main content of the message body here. Ingeneral, this is the output of a Plug-in for Data Conversionrender activity, but it can be any array of bytes. If stringdata is to be mapped to this field, use the XPath functiontib:string-to-base64 to convert it to bytes.

text N Present if Text is selected in the Message Content Typearea. A string mapped to this field is converted to bytesusing the character set specified for the message.

lastMessageInGroup N This field is displayed in the input schema after clickingCustomGroup in the Multi-Message Support area.

In a custom group, it is up to the application to terminatethe logical message by setting this field to TRUE on the lastmessage.

85



lastSegment N This field is displayed in the input schema after clickingCustomSegmented in the Multi Message Support area.

In a custom group, it is up to the application to terminatethe segmented message by setting this field to TRUE on thelast message.

Output

The following table lists the output items for the Put activity:

Some of these fields are missing or inaccurate if the Asynchronous Mode is used.


Batch N This node is present when Batch or BatchGroup in theMulti-Message tab is selected. For each InteractionInputnode present in the input schema, an InteractionOutputnode is present here under the Batch node.


86



mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant to input for asubsequent activity.


● destqmgr: to document the remote queue managerspecified for the put operation.

● correlationId: to document the correlation ID, if any.


● groupId: to document the group ID, if any.

● characterSet: to document the character set used bythe queue manager to process this message.

● alternateUserId: as provided in the input schema.


● applicationIdData: as provided in the input schema.

● applicationOriginData: as provided in the inputschema.

● putApplicationType: as provided in the input schema.

● putApplicationName: as provided in the input schema.


● replyToQueueName: same as input.

● replyToQmgrName: destination queue manager name.The name of the queue manager on which this queue islocated.

A transmission queue and a sender channelmust be configured for this to work.

● format: the character string placed into the formatelement by the sending application.

● expiry: to indicate the number of tenths of a second thatthe message is kept in the queue before being deleted.Defaults to -1, which means there is no expiration.




87



● report: to document the contents of the report field inthe returned message.

● encoding: to document the numerical value of theencoding field. This encoding is used for extractingnumerical data from the message if those numbers are inproperties or a message body schema.

● messageType: enumerated value of the chosen messagetype:

— 8 is Datagram.

— 2 is Reply.


● backoutCount: the number of times this message wasbacked out before being committed.

● feedback: for a Report message received by a WMQ Getor Listener activity, this field defines the nature of thereport. The field is unused with a value of 0 in Putactivities.

● version: to document the version of the message. ThisPlug-in supports type 2 messages only.

● putDateTime: the time that the message is placed intothe queue.

● groupStatus: to indicate whether the message is part ofa logical message.

responsetimemilli

sec

N To indicate, in milliseconds, how long it takes to send themessage.

Fault

The Fault tab lists exceptions that occur in the Put activity:

Error SchemaElement Data Type Description



mqCompCode String This is the original MQException's completion code, if it is anMQException that triggers the fault.

88



mqReasonCode String This is the original MQException's reason code, if it is anMQException that triggers the fault.

mqErrorCode String This is the original MQException's error code, if it is anMQException that triggers the fault.

WebSphere MQ RequestReplyThe RequestReply activity performs the combined operations of putting a request message into aqueue, and then listening on the indicated response queue for the reply.

Because the RequestReply activity depends on the request being committed to the request queue, thisactivity does not participate in local transaction semantics. This also means that this activity does notshare a connection resource with activities in a local transaction because it can unexpectedly commitresources under the control of the local transaction.

General

The General tab of the RequestReply activity contains the following fields:



Connection Y The connection resource which associates this activity with thequeue manager that has access to the desired queue.

Destination Y The name of the queue into which the message is placed. If thequeue is to be created dynamically, enter the name of thedynamic queue. The name must follow the MQSeries rules fordynamic queue names.

If the queue name has been dynamically mapped using theinput schema's destination field, this field is not required.

Message ContentType

N Select the type of message content:

● Binary: if Binary is selected, string content can still be sent,but it must be translated to binary through an XPathexpression.

● Text: string data can be directly mapped onto the message.The message is decoded using characterSet for themessage, or 819 if none is provided. Characterset 819 isthe Java API default.

● Schema: the message is formatted according to the schemaprovided in the Message Body Fields field. Input values forthis schema are displayed in the input editor.

89



Message BodyFields


Reply ToDestination

Y Specify a reply queue on which the RequestReply activityperforms a get immediately after sending a request. Theactivity waits for the number of milliseconds specified in thewaitinterval element of the input schema.

The queue name which is placed into the message header'sReply To Destination field. If this queue is dynamic, it iscreated before the put is performed, and the name of thetemporary queue is set in the request message.

DynamicReplyToDestination

N A flag that enables the creation of a dynamic queue.

When selected, the Dynamic ReplyToDest Model field isenabled, and the reply queue is dynamically created based onthe model in the Dynamic ReplyToDest Model field. If adynamic reply queue is specified, it is created during the putoperation so that it is available to the responding application.

DynamicReplyToDestModel

Y Specify the model after which the reply queue is to bepatterned.

This field is enabled only when the DynamicReplyToDestination check box is selected.

Fail If Quiescing N Select this check box to cause the activity to fail if the queuemanager attempts to quiesce during the operation. Thisprevents the queue manager quiesce from being delayed bythis activity.


N Select the Application Properties resource to be included aspart of this message. Application properties are similar toregular message header fields except that the name and type ofthese fields can be determined by a predefined schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and map itto this field. See the IBM WebSphere documentation forproperty types supported by the level of client you haveinstalled.


Logger Name Y Loggers are configured in an XML file used at run time. Theruntime logger configuration is specified by the -Dlogback.configurationFile parameter of either thedeployed application instance or of the debugger instance.After the logger is configured, it can be named here to causeinformational messages to be written there. See the TIBCOActiveMatrix BusinessWorks documentation for more detailsabout how to configure loggers.

90


Description

A short description for the RequestReply activity.

Advanced

The Advanced tab of the RequestReply activity contains the following fields:


MessagePriority

Y Set the priority of the message as it is to be retrieved by the queuemanager. The values range from 0 to 9.

MessageExpiration

Y The time, in tenths of a second, that the message persists in thequeue before being deleted by the queue manager.

Values range from 0 to 2147483647.

The default is 0, which means the message never expires.

GenerateCorrelation Id

N Select this check box to cause the queue manager to generate aunique correlation identifier for the message when it is sent. Thismeans that the message identifier, which is always generated, iscopied to the correlation identifier field.

If this option is enabled, the queue manager overlaysany correlation identifier that is mapped in the inputschema.

Persistence N Determines whether messages on the queue manager persistacross restarts.


● AS_QUEUE_DEF: it uses the persistence level defined in thequeue definition.

● PERSISTENT: it ensures that the message persists if thequeue manager fails or restarts.

● NOT_PERSISTENT: not persistent.

91



ContextSupport

N The input fields of a put operation fall into categories based ontheir context. Many fields are always present, but others are onlypresent if the context relevant to that field is chosen. This isbecause the queue manager must grant the user the authorizationto update these fields.


● Default: the input schema conforms to the fields accessible toa user with the default authority.

● Identity: the input schema conforms to the fields accessible toa user with the Set Identity Context authority.

The new fields are:

● accountingToken


● userId


The new fields (in addition to those provided by Identity) are:




CICS BridgeHeader

N When enabled causes the input and output schemas to includethe CICS bridge header: MQCIH. By mapping fields onto thisheader in accordance with the IBM CICS bridge for WebSphereMQ, it is possible to invoke CICS programs and run transactionswhich display screens. See the IBM Knowledge Center resourcesat https://www.ibm.com/support/knowledgecenter/SSGMCP_4.2.0/com.ibm.cics.ts.wmq.bridge.doc/topics/zc12190_.html for more information on how to interact with theCICS bridge. The specific fields related to the MQCIH header arenot described in the input and output schemas section. Please seethe relevant IBM documentation for this.

IMS BridgeHeader

N When enabled causes the input and output schemas to includeIMS bridge header: MQIIH. By mapping fields onto this headerin accordance with the WebSphere MQ bridge for IMS, it ispossible to invoke IMS programs and transactions. See the IBMKnowledge Center resources at https://www.ibm.com/support/knowledgecenter/SSFKSG_9.0.0/com.ibm.mq.pro.doc/q004310_.htm for more information on how to interact with theIMS bridge. The specific fields to the MQIIH header are notdescribed in the input and output schemas section. Please see therelevant IBM documentation for this.

92


https://www.ibm.com/support/knowledgecenter/SSGMCP_4.2.0/com.ibm.cics.ts.wmq.bridge.doc/topics/zc12190_.html



https://www.ibm.com/support/knowledgecenter/SSFKSG_9.0.0/com.ibm.mq.pro.doc/q004310_.htm



Input

The following table lists the input items for the RequestReply activity:



93



mqproperties N The node containing all the message header fields (plus thedestination override) that are relevant to the put side of theoperation. Note that any values mapped to the filtering fields(messageId, correlationId, and groupId) are subsequentlyused to filter the get side of the operation.

● destination: specify a destination here to override thequeue name from the configuration panels. With it, thequeue can be dynamically specified.

● destqmgr: destination queue manager name. The name ofthe queue manager on which this queue is located.

A transmission queue and a sender channel mustbe configured for this queue manager in order forit to work.

● correlationId: provide a correlation identifier for thismessage by mapping a byte array to this field. The XPathexpression tib:string-to-base64 ("correlationid")is sufficient to populate this field. If a correlation ID isprovided, then the activity filters the reply queue using thesame correlation ID.

● messageId: specify a message ID. This value overrides thedefault value generated by the queue manager. The rulesare the same as for correlationId. If a message ID isprovided, then the activity filters the reply queue using thesame message ID.

● groupId: specify a group ID for a message if the message ispart of a group. If a group ID is provided, then the activityfilters the reply queue using the same group ID.

● characterSet: set the IBM Coded Characterset ID of thismessage. Valid values are:

— 850: The commonly used ASCII codeset.

— 819: The ISO standard ASCII codeset.

— 37: The American EBCDIC codeset.

— 1200: Unicode.

— 1208: UTF-8.


● alternateUserId: to document the alternate userid usedin this operation, if any.

● accountingToken: provide a binary (base 64 encoded)accounting token to be used on host systems to assist inaccounting for resources used by the application.

● applicationIdData: provide a string that can be used onall end points to identify this application.

94



● applicationOriginData: provide information related tothe originating application node for this message.

● putApplicationType: provide either one of the IBMdocumented application type enumerators for thisapplication or one of your choosing. See the IBMWebSphere MQ documentation for the meaning of thedocumented application types. These are the documentedenumerations:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

● putApplicationName: provide information about theoriginating application in this field.

● userId: provide the user ID to be used when authorizingthis message as it traverses the messaging system. Foroperations with report options, this field is mandatory. If avalue is not provided here, it is taken from the connectionresource if one is available there, and from the environmentif it is not.

● replyToQueueName: this field overrides the Reply ToDestination field provided in the General tab. This is thedestination on which the Get side of the operation waitsafter sending the request. If neither the configuration valuenor this field is provided, then the activity fails with anMQRC_MISSING_REPLY_TO_Q error.

● replyToQmgrName: destination queue manager name.Because WebSphere MQ does not support a get operationin a remote queue, this field is ignored. The reply mustcome back from the same queue manager to which theactivity is connected.

● format: describes the nature of the data in the message. Itdefaults to " ", or MQFMT_NONE. A user defined format can be

95



used to assist the receiving application in decoding themessage, for example, in the selection of a Data Conversionparse activity for this message type.

● expiry: indicates the length of time (in tenths of a second)that the message is kept in the queue before being deleted.Defaults to -1, which means there is no expiration. Thisfield overrides the configuration value for expiry if it ismapped. Permissible values are a positive integer or -1.

● priority: the priority (from 1 to 9) of the message. Thisfield overrides a configuration value for priority if it ismapped.

● reportOptionPan: set this boolean field to add the valuePositive Acknowledgment to the report field of themessage. This field is an application only field and is notacted upon by the queue manager.

● reportOptionNan: set this boolean field to add the valueNegative Acknowledgment to the report field of themessage. This field is an application only field and is notacted upon by the queue manager.

● report: because this activity always sends a request typemessage, report options are not available. If any reportoptions are provided here, they are reset to zero by thequeue manager.

● encoding: this is the encoding field for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packeddecimal and floating point data. This encoding is usedwhen processing of fields mapped by a message bodyschema. For specific values, see the MQMessage encodingfield in the WebSphere MQ documentation.

● waitinterval: specify the number of milliseconds that theRequestReply activity waits for the response after sendingthe request before throwing a timeout exception. To waitindefinitely, define a -1 in this field using the statementxsd:int(-1).

appProperties N Contains fields that correspond to the schema as it is defined inthe application properties resource that is mapped to thisactivity. Application properties are included in an MQRFH2header which is dynamically added to the message.

This node is only displayed if a properties resourceis specified for the activity.

messageFields N This element is present when Schema is selected from theMessage Content Type list of the General tab. The contents ofthe mapped schema are present in this node for mappingpurposes.

96



dynamicPropertie

s

N● dynamic property: these properties are exactly the same





bytes N Present if Binary is selected in the Message Content Type area.Map the main content of the message body here. In general,this is the output of a Plug-in for Data Conversion renderactivity, but it can be any array of bytes. If string data is to bemapped to this field, use the XPath function tib:string-to-base64 to convert it to bytes.

text N Present if Text is selected in the Message Content Type area. Astring mapped to this field is converted to bytes using thecharacter set specified for the message.

Output

The following table lists the output items for the RequestReply activity:

Some of these fields are missing or inaccurate if the Asynchronous Mode is used.



97



mqproperties N The node containing the message fields relevant to the get sideof the request/reply operation. Any fields which relate tofiltering messages (messageId, correlationId, and groupId)which are mapped on the input schema are used to filter theresponse presented here.


● destqmgr: to document the destination queue manager as itis specified in the reply message. Because get operationsmust occur on the queue manager to which the activity isconnected, this destination queue manager is always thatsame queue manager.

● correlationId: to document the correlation ID, if any.


● groupId: to document the group ID, if any.

● characterSet: to document the character set used by thequeue manager to process this message. This character setis also the character set used to extract string data from themessage.

● alternateUserId: as provided in the input schema.


● applicationIdData: as provided in the input schema.

● applicationOriginData: as provided in the input schema.

● putApplicationType: as provided in the input schema.

● putApplicationName: as provided in the input schema.


● replyToQueueName: normally null for this activity typebecause the output of this activity represents a reply.

● replyToQmgrName: destination queue manager name. Thename of the queue manager on which this queue is located.

● format: the format of the message. This field is normallyused to help the receiving application parse the payload.The value can be one of the IBM standard formats or ancustom application specific value.

● expiry: to indicate the number of tenths of a second thatthe message is kept in the queue before being deleted.Defaults to -1, which means there is no expiration.


● reportOptionPan: reflects the value of the PositiveAcknowledgment bit of the report field. This field is an

98



application only field and is not acted upon by the queuemanager.


● report: to document the report field in the message as it isreceived.

● encoding: to document the encoding field in the messageas it is received. This encoding is used to extract anynumerical data from the message.

● waitinterval: the number of milliseconds theRequestReply activity waits for the response to the requestsent by this activity.

● messageType: enumerated value of the chosen messagetype:

— 8 is Datagram.

— 2 is Reply.


● backoutCount: the number of times this message is backedout before being committed.

● feedback: for a Report message received by a WMQ Get orListener activity, this field defines the nature of the report.The field is unused with a value of 0 in Put activities.

● version: to document the version of the message. ThisPlug-in supports type 2 messages only.

● putDateTime: the time that the request message is placedinto the queue.

● groupStatus: to indicate whether the message is part of alogical message. It can contain any one of the following:

— MSG_IN_GROUP



appProperties N This field maps the application properties present in thereceived message to the schema attached to the activity.Properties which are missing or not present in the schema arenot shown here.

messageFields N Contains the message body formatted using Schema in theMessage Content Type field of the General tab.


99



dynamicProperties N● dynamic property: these properties are exactly the same





bytes N If the activity is configured to use binary messages, then thisfield contains the output body of the message. Typically, thisbyte array is to be mapped as input to a TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion parse activity.


text N If the activity is configured to use text for the payload, thisfield is present and contains the contents of the messagedecoded as a string.


responsetimemilli

sec

N To indicate, in milliseconds, how long it takes to send themessage.

Fault

The Fault tab lists exceptions that occur in the RequestReply activity:




mqCompCode String This is the original MQException's completion code, if it is anMQException that triggers the fault.

mqReasonCode String This is the original MQException's reason code, if it is anMQException that triggers the fault.

100




The elements listed below occur only for the MqReqReply error schema.

Error SchemaElement


mqReqReplyCor

rId

ByteArray

If the message originates as a WebSphere MQ API exception, thenthat exception's request reply correlation id is here.

mqReqReplyMsg

Id

ByteArray

If the message originates as a WebSphere MQ API exception, thenthat exception's request reply message id is here.

WebSphere MQ SubscriberThe Subscriber activity listens on a topic or an administratively defined subscription and starts aprocess that provides the contents of the message.

The subscriber can poll a topic based on interval and timeout values, or it can wait indefinitely.Regardless of which mode it is in, when messages arrive they are each processed immediately with nointervening interval time. When polling is enabled, messages published to the subscribed topic are notlost during the interval when the subscriber is not actively listening because the subscriber exists for theduration and is not created and destroyed across intervals. However, this does not necessarily applyduring error recovery or lost connection scenarios.

The topic string is composed of two optional parts:

● An administratively defined topic. This option implies a root topic string defined on the server.

● A dynamic topic string which is concatenated to the topic string for the defined topic, if one isspecified.

If neither of these fields is provided but an existing durable subscription is specified, the activitysubscribes to the durable subscription.

The queue manager inserts the forward slash (/) as necessary to compose a well formed topic string.

While the listener is active, a temporary dynamic subscription is created (in the queue manager) so thatall messages appropriate for the topic are routed there. This subscription ceases to exist when thelistener is stopped, or in error recovery. To avoid missing messages destined for the topic, you canenable the Durable Subscription option to have the subscription persisted indefinitely in the queuemanager using the name provided. Durable subscriptions accumulate messages even when there are nolisteners, much like a queue would.

101


When using the Subscriber activity, it is important to understand the relationship between theBusinessWorks engine and WebSphere MQ API. The engine can stop the Subscriber activity, or thewhole application in response to commands from the administrator in TIBCO EnterpriseAdministrator. However, WebSphere MQ API does not provide any mechanism to interrupt threads,which are blocked on the get methods. So even though, the Subscriber activity is instructed to stop, itcannot terminate the currently executing thread, which is waiting on the get call. In a pollingSubscriber activity, this situation is resolved when the timeout interval expires and the thread exits.However, a non-polling Subscriber activity never exits the get call. There are two scenarios to show thissituation.● A message arrives after a Subscriber activity is stopped. In this scenario, the message is rolled back.

● There are two subscribers in the same queue after you start a new subscriber. Normally this is not anissue, because when a new message arrives, the first subscriber exits. However, if the subscriber isusing a durable subscription, only one thread can use this destination at a time, and the secondsubscriber fails to connect. It continues to attempt to connect and issue warning messagesperiodically. Until a message arrives, it terminates the first subscriber, after that, the second startedsubscriber connects and processes the message.

There is another general scenario, which affects all process starters. If the Subscriber activity receives anumber of messages and creates processes for them, but those processes are either running or waitingto run without adding checkpoints and the engine is shut down, those messages are lost. If it isimperative that messages are never lost, you can select the Require Client Confirmation check box inthe General tab to ensure their integrity.

General

The General tab of the Subscriber activity contains the following fields:



Connection Y Choose the connection resource which associates this activitywith the queue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined portion of the topicstring. If a topic name is specified, the topic string associated withthat name in the queue manager forms the root or left-mostportion of the topic string.

WildcardScheme

N WebSphere MQ supports two wild card schemes:

● Topic: associated with current queue managers.

● Char: associated with version 6 and earlier of WebSphere MQ.

Either scheme can be used. Consult the WebSphere MQdocumentation for information about these schemes.

Topic Dynamic Y Enter the dynamic portion of the topic string here. This field cancontain the entire topic string or only the right-most portion of it,depending on whether it is to be used with an administrativelydefined topic.

102



DurableSubscription

N When selected, the subscription created by this subscriber isdurable. Durable subscriptions survive subscriber and queuemanager restarts, and accumulate messages until they areexplicitly deleted.

SubscriptionName

Y Enabled if the Durable Subscription check box is selected. This isthe name of the permanent subscription.

A subscriber can be started using only the durable subscriptionname. If the subscription exists, no topic string or dynamic topicare necessary.

MessageContent Type

N The following types of message content are supported:

● Binary: the bytes field in the output schema is provided andcontains a byte array representing the messages contents.

● Text: the text field in the output schema is provided andcontains a string composed by decoding the message's bytearray using the default Java encoding.

● Schema: if the message has been written using theMQMessage read/write API calls, it can be rendered here byproviding a schema resource that conforms to the schema ofthe message.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at run timeto decode the contents of this message.

NewPublicationsOnly

N Select the New Publications Only check box for non-durablesubscriptions where you do not want to receive the last messagepublished with the Retain Message option. In essence, this is away of opting out of the application state message.

Fail IfQuiescing

N Select the Fail If Quiescing check box to prevent this subscriberfrom holding up a queue manager quiesce operation. If the queuemanager does terminate, the activity attempts to reconnectindefinitely.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisGet operation. It causes the queue manager to convert string andnumeric fields using the characterSet and encoding elementsbefore the data is copied to the message buffer.

103



Require ClientConfirmation

N Select the Require Client Confirmation check box to requestexplicit confirmation of a received message.

The confirm activity can be used to confirm the message’s arrivaland remove it from the queue. The plug-in uses the queuemanager's syncpoint capability to ensure that the message is onlyremoved from the queue if it is confirmed.

The activity waits for the confirmation before obtaininganother message which imposes an absolute limit onthe throughput. If serial processing of the messages isnot essential, raise the value of the Instances field untileither the worker threads are 100% busy or the desiredthroughput is achieved.

If the activity fails to confirm the message, it loops and repeatedlyprocesses the same message.

Logger Name Y Enter the name of any pre-configured logger available to the runtime. Loggers are configured in an XML document referenced bythe Dlogback.configurationFile runtime parameter.

Description

A short description for the Subscriber activity.

Advanced

The Advanced tab of the Subscriber activity contains the following fields:


Sequence Key N This field can contain an XPath expression that specifies whichprocesses can run, and in which in order. Process instances withsequencing keys that evaluate to the same value are executedsequentially in the order the process instance was created.

See the TIBCO ActiveMatrix BusinessWorks documentation formore information about controlling the execution order of processinstances and about XPath expressions.

Custom Job Id N This field can contain an XPath expression that specifies a custom IDfor the process instance. This ID is displayed in the View Servicewizard of TIBCO Enterprise Administrator, and it is also available inthe $_processContext process variable.

104



EnablePolling

N When selecting the Enable Polling check box, the activityinstantiates a connection to the queue manager and opens the topic.It then periodically issues timed gets on the topic where the timeoutvalue is equal to the polling timeout and the period between gets isequal to the polling interval. However, if there are multiplemessages available, they are processed without an interveningpolling interval, thus diminishing application latency.

When clearing the Enable Polling check box, the activity waitsindefinitely on the topic, processing messages as they arrive. If thequeue manager connection fails, the activity attempts to reconnectbased on the reconnection interval.

A poor choice of polling interval and polling timeoutvalues might impose a high overhead on the engine aswell as the queue manager to which the activity isconnected. Use values here which take into account thelatency in the network between this activity and the queuemanager, as well as the processing demands you arewilling to place on that queue manager.

PollingInterval

Y If the Enable Polling check box is selected, this is the interval atwhich a new polling cycle is initiated. Specify time in milliseconds.


Default: 1000

PollingTimeout

Y If the Enable Polling check box is selected, this is the timeout valuefor each individual listen. The value specified here must besignificantly smaller than the value in the Polling Interval field. Thisminimizes the number of concurrent connections to the queue andreduces the processing resources needed.



Default: 1000

ReconnectionInterval

Y The length of time, in milliseconds, that the listener waits betweenattempts to reconnect to the topic.

This setting is used only when polling is disabled. If polling is notenabled, the listener listens indefinitely on the queue. However, if anerror occurs and the queue manager is subsequently unavailable(shut down for example), this value is the number of millisecondsbetween reconnection attempts.


Default: 10000

105




N If the messages expected on this topic contain application specifictopics, a shared schema resource must be created to represent thoseproperties and it has to be mapped here. Messages which containany or all of these properties have them provided as input to theprocess created by this starter. To use application properties, create ageneric XML schema composed of a node with simple elementsinside it and map that schema to this field.

See the IBM WebSphere MQ documentation for property typessupported by the level of client you have installed.


PropertyControl

N Select one of the following settings:


After selecting one of these options, you can use the Subscriberactivity to inter-operate with various versions of WebSphere MQapplications. Which option to use varies depending on the sendingapplication. See the section entitled "MQGMO message propertyoption setting" in the IBM WebSphere MQ documentation fordetailed information.

Conversations

You can use the Conversations tab of the Subscriber activity to initiate or join a conversation.

Conversations receive messages after the creation of a process instance, which is initiated or joined byan activity. This activity can be used to initiate a conversation. Click the Add New Conversation iconto initiate a conversation. For more details regarding conversations, see TIBCO ActiveMatrixBusinessWorks Application Development.

Output

The following table lists the output items for the Subscriber activity:



106



mqproperties N The node containing all the message header fields (plusthe destination override) which have been mapped fromthe received message.

● destination: to document the destination for thismessage. This field contains the complete topic stringfor the message.

● destqmgr: to document the remote queue managerspecified in the input schema.

● topicdynamic: to override the Topic Dynamic fieldfrom the General tab. This string forms the dynamicportion of the fully resolved topic name.

● correlationId: to document the messagecorrelation ID. In most cases, this is an internal queuemanager value and is not available for filteringpurposes.




● accountingToken: the accounting token thatsupports work done as a result of the message to beappropriately billed.

● applicationIdData: application ID data. This isapplication data was provided by sender of themessage.

● applicationOriginData: additional informationabout the origin of the message provided by thesender of the message.

● putApplicationType: the type of application thatput the message.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX

107



0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14

● putApplicationName: the name of the applicationthat puts the message, if one is provided.


● replyToQueueName: the name of the queue to whicha reply is sent if the message is a request.

● replyToQmgrName: if this message arrived by way ofa remote queue manager specification, this fielddocuments the queue manager to which thissubscriber is connected.

● format: a name that describes the nature of the datain the message.

● expiry: the expiration time (in tenths of a second),after which the message is eligible to be discarded bythe queue manager. This contains whatever value isused when the message is sent.


● reportOptionPan: reflects the value of the PositiveAcknowledgment bit of the report field. This field isan application only field and is not acted upon by thequeue manager.

● reportOptionNan: reflects the value of the NegativeAcknowledgment bit of the report field. This field is

108



an application only field and is not acted upon by thequeue manager.

● report: this is the report options field for themessage. Reflects the report options in effect for thismessage.

● encoding: this is the encoding element for themessage and it specifies the representation used fornumeric values in the application message data. Thisapplies to binary, packed decimal and floating pointdata. This encoding is used when processing of fieldsmapped by a message body schema. For specificvalues, see the MQMessage encoding field in theWebSphere MQ documentation.

● messageType: enumerated value indicating themessage type:

— 8 is Datagram.

— 2 is Reply.


● backoutCount: the number of times this message isbacked out before being committed.

● feedback: if the message is a Report message, thisfield defines the nature of the report. Defaults to 0 fornon-report messages.

● version: to document the version of the message.

● putDateTime: the time that the message is placedonto the topic.

● groupStatus: to indicate whether the message ispart of a logical message. It can contain any of thefollowing:

— MSG_IN_GROUP



109



dynamicProperties● dynamic property: these properties are exactly the

same as those mapped through the appPropertiesnode with the exception that no special schema isrequired to map them. A dynamicProperties nodeis created for each property in the message whichwas not mapped by the appProperties schemamechanism. If no appProperties schema is in place,all properties are dynamic. Note that the publish andsubscribe mechanisms in WebSphere MQ usesmessage properties in the implementation, you cansee the property mqps.Top and possibly others on allpublications.




bytes N The output body of the message. Typically, this bytearray is to be mapped as input to a Data ConversionPlug-in parse activity.

This field is only displayed when Binary is selected inthe Message Content Type area.

text N This field contains a text representation of the bytes inthe message body as converted using the default Javaencoding.


responsetimemillisec N This field records the time, in milliseconds, that it takesto start the WebSphere MQ get API call until the eventcontext for the new activity is created.

appProperties N This field maps the application properties present in thereceived message to the schema attached to the activity.Properties which are missing or not present in theschema are not shown here.

The field is only displayed if an application propertiesschema is configured for the activity.

messageFields N Contains the message body formatted using Schema inthe Message Content Type field of the General tab.


Fault

The Fault tab lists exceptions that occur in the Subscriber activity:

110


Error SchemaElement







111


Working with Sample Projects

Working through the sample projects helps you to understand how TIBCO ActiveMatrixBusinessWorks Plug-in for WebSphere MQ works.

After installing the plug-in, you can locate the eight sample projects in the TIBCO_HOME/bw/palettes/bwmq/version_number/samples directory. These sample projects contain twenty processes, eachprocess corresponds to a task.

The eight sample projects are as follows:

● basicSendReceive

This package contains a process. The process puts a message in the queue and then retrieves themessage using the Get activity.

● dynamicDestinations

This package contains three processes, which are related to dynamic destinations.

Dynamic destinations are queues, which do not exist until they are opened for read or write. Thesequeues are patterned after a model queue (which you have to create), and they can be of atemporary or permanent nature.

Temporary dynamic queues disappear as soon as the last subscriber and message are gone from thequeue.

Permanent dynamic queues behave much like normal queues in that they survive queue managerrestarts and retain their messages as would a normal queue. The main difference is that they can becreated and deleted by an application, which frees administrators from some of the maintenanceobligations for applications designed to use them.

A dynamic queue can be created either by the Put, Get, or Listen activity. The most common use ofdynamic queues is for the reply messages.

A brief description of these processes are as follows:

GetFromDynamicDest shows the Get activity can create a destination and listen on it.

ListenToDynamicDest shows the Listener activity can create and listen on a dynamic destination.

SendToDynamicDest shows the Put activity can create a dynamic queue and a subsequent Getactivity can get either that message or a response type message on the dynamic queue.

In all cases, the dynamic queue can exist until the process that created it ends.

● logicalmessages

This package contains five processes, which show the ways in which logical messages can behandled by the plug-in. Logical messages can be created and consumed in single pass activitiesthrough the Get, Put, and Listen activities. Logical messages can also be processed in loops by theGet and Put activities.

● messagebodyschemas

This package contains one process, which shows the use of message body schemas. It uses a schemafrom the Resources directory to map a number of different kinds of variables on and off of amessage using the Get and Put activities.

● mqtransactions

This package contains three processes, which shows how the Get, Put, and Publish activities can bewrapped in a local transaction group such as the messages sent and retrieved by each activity areonly committed when the process exits the local transaction group. The RequestReply activity doesnot participate in transactions because it is a compound activity, which requires that its initial put to

112


the request queue be committed immediately. Rollback of all messages involved in a localtransaction is also illustrated.

● pubsub

This package contains two processes, which shows the basic use of the pub sub capabilities of theplug-in.

● report

This package contains two processes. The plug-in can be configured such that all of the commonlyused reporting options are selectable on the Advanced tab of the Put activity. The fact that thereports were created is verified by listening for them in another process.

● segmented

This package contains two processes. Message segmentation is a technique used to split largemessages into smaller ones called "segments", which can fit into the buffers of the various channelsencountered in the messaging system. With this plug-in, messages can be explicitly segmented,whereby you provide the segment size, or have the queue manager segment the message asnecessary along the way. The Put activity provides explicit configuration options for segmentingmessages but the Get and Listener activities support segmented messages implicitly.

Importing Sample ProjectsBefore running the project, you must import the sample project to TIBCO Business Studio.

Procedure

1. Start TIBCO Business Studio using one of the following ways:

● Microsoft Windows: click Start > All Programs > TIBCO > TIBCO_HOME > TIBCO BusinessStudio version_number > Studio for Designers.

● Linux: run the TIBCO Business Studio executable file located in the TIBCO_HOME/studio/version_number/eclipse directory.

2. From the menu, click File > Import.

3. In the Import dialog, expand the General folder and select the Existing Studio Projects intoWorkspace item. Click Next.

4. Click Browse next to the Select root directory field to locate the sample. Click Finish.The sample project is located in the TIBCO_HOME/bw/palettes/bwmq/version_number/samplesdirectory.

Result

The sample project is imported to TIBCO Business Studio.

113


Running the ProjectYou can run a process in a sample project by completing the following steps.

Prerequisites

● Ensure that you have imported the sample project to TIBCO Business Studio, as described in Importing Sample Projects.

● You have to create the following queues to use the samples:

BWMQ.APP

BWMQ.DEST.DYNAMIC

BWMQ.SEGMENTED

BWMQ.LOGICAL

BWMQ.REPLY

BWMQ.REPORT● You also have to create the basic model queue.

BWMQ.MODEL - a model for a temporary dynamic queue.

Procedure

1. In the Project Explorer view, expand the Resource folder and then expand the testmq sharedresource.

2. Double-click localhost.mqcon to edit the WebSphere MQ connection and then click TestConnection to validate your connection.

114


3. In the Project Explorer view, expand the Module Descriptors resource and then double-clickComponents.

4. By default, all the processes are listed in the Components editor. In the Components editor, select

the process that you do not want to run and click .

5. On the toolbar, click the icon to save your changes.

6. From the menu, click Run > Run Configurations to run the selected process.

7. In the Run Configurations dialog, expand BusinessWorks Application and click BWApplication.

8. In the right panel, click the Applications tab, select the check box next to Examples.application.

9. Click Run to run the process.

10. Click the icon to stop the debug session.

115


Miscellaneous

Miscellaneous describes how TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ is usedwith TIBCO Active matrix BusinessWorks Plug-in for Data Conversion and WebSphere MQ.

Transactions with WebSphere MQThe Plug-in for WebSphere MQ has its own type of local transaction called MQ. The Get and Putactivities enclosed in such a transaction group have their queue manager resources enlisted with thislocal transaction and when it ends, all the queue actions are committed.

TIBCO ActiveMatrix BusinessWorks 6.0 and above have enhanced support for local transactions.

If activities within a single MQ local transaction use different queue managers, the resources arecommitted at the end of the transaction one queue manager at a time. Therefore, if the second or thirdqueue manager fails to commit, the queues can be left in an inconsistent state. For this reason, it isadvisable to confine local MQ transactions to queues involving a single queue manager.

Data Conversion Plug-in with WebSphere MQThe plug-in, together with TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion, providesActiveMatrix BusinessWorks with the ability to encode XML-structured data into byte sequences to besent to a WebSphere MQ-capable application.

The plug-in does not attempt to provide tools for the manipulation of the message body itself. Thisrequirement is fulfilled by TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion. Messagescan be free form text (like XML documents) or they can have internal structure. In the case of mostlegacy applications, that structure is usually expressed in the form of a copybook document like thisone: * *===========================================================* * * TIBCO Mainframe sample COBOL Copybook * * *===========================================================*

01 WS-IVP-FIELDS. 05 IVP-ID PIC X(8) USAGE DISPLAY. 05 IVP-DESCR PIC X(56) USAGE DISPLAY. 05 IVP-RESULT PIC X(80) USAGE DISPLAY. 05 IVP-BES-NAME PIC X(8) USAGE DISPLAY. 05 IVP-BES-TRAN-ID PIC X(8) USAGE DISPLAY. 05 IVP-BES-PGM-NAME PIC X(8) USAGE DISPLAY. 05 IVP-USERID PIC X(8) USAGE DISPLAY. 05 IVP-START-TIME PIC X(8) USAGE DISPLAY. 05 IVP-REPLY-TIME PIC X(8) USAGE DISPLAY. 05 IVP-SUBJ-SFX PIC X(30) USAGE DISPLAY.

116


05 IVP-TYPE PIC X(1) USAGE DISPLAY. 05 IVP-BES PIC X(1) USAGE DISPLAY. 05 IVP-WRITES PIC S9(8) USAGE COMP. 05 IVP-BES-TASKNO PIC S9(8) USAGE COMP. 05 IVP-BES-DELAY PIC S9(8) USAGE COMP. 05 IVP-BTCH-SEQ-NO PIC S9(8) USAGE COMP. 05 IVP-START-DATE-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-START-TIME-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-REPLY-DATE-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-REPLY-TIME-CHAR PIC X(16) USAGE DISPLAY.

TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion converts copybooks to XML schemasfor use in other activities. The Data Conversion Plug-in render and parse activities convert canonicaldata to memory based formats and vice versa. If your WebSphere MQ project converses with anapplication that uses these formats, simply create Data Conversion Plug-in activities that represent themessage structure for those applications and pipe the values in and out of message activities tocommunicate with them, the following figure shows how canonical data is converted using the DataConversion Plug-in:

Creating Secure Connections to the Queue ManagerYou can create a secure connection between the plug-in and the WebSphere MQ queue manager byusing Transport Layer Security (TLS).

There are many variables that control secure connections, and all must be correctly enabled for TLS tofunction. If problems occur, it might be difficult to identify the source. The Troubleshooting sectionoffers a few suggestions to aid in identifying the source of any problems.

Procedure

1. Configure the WebSphere MQ queue manager to accept TLS connections.

2. Create a keystore for the certificates and trusts used by the queue manager.See Setting Up WebSphere MQ Queue Manager for more details. The WebSphere MQ queuemanager configuration is covered extensively in the IBM documentation. If any of the terms used inthis section are unfamiliar, review the IBM documentation for clarification.

3. Configure TIBCO ActiveMatrix BusinessWorks to connect using TLS.See Setting Up TIBCO ActiveMatrix BusinessWorks for more details.

Setting Up WebSphere MQ Queue ManagerTo create a secure connection to the WebSphere MQ queue manager, you are required to set up theWebSphere MQ queue manager.

This section introduces how to enable the WebSphere MQ queue manager to accept TLS connections byusing the sample that is provided by the plug-in. You must create a keystore for the certificates andtrusts used by the queue manager.

117


These examples use self-signed certificates. Although self-signed certificates are acceptable in adevelopment environment, they must never be used in production.

Procedure

1. Create IBM keystores for the queue manager and client by using a given script in the plug-insamples directory.The following steps describe the configuration of the queue manager to use certificates generated bythe script using the command: createQueueManagerKeystore.sh/var/mqm/qmgrs/qmwn/sslqmwn password.

2. Configure the queue manager to use generated keystore.

3. Use the IBM Key Management tool to review the personal certificate name.

4. Create a TLS connection for the queue manager.

5. Verify that all SSL files can be read by the mqm group.

Verify the security of all the files in the directory which you configured as the SSL Key Repositoryproperty of the queue manager are readable by the mqm group. This is the security group mqm that iscreated during the installation of WebSphere MQ on the platform. If they are not, adjust their accessproperties or the queue manager is not able to read them.The queue manager is now capable of making a secure connection with a client. Using the plug-in,you can now create a TLS-secured connection to the queue manager.

Creating IBM Keystores for the Queue Manager and Client

Each end of the TLS connection must have a keystore. A sample script is included in the plug-in'ssamples directory to create keystores for the queue manager and client.

Setting up the WebSphere MQ queue manager relies on certificates generated using this script. Thescript is annotated, and is intended to be used as a template to aid you in the creation of your ownscripts. Use this script to assist in the creation of TLS connections in an evaluation or developmentenvironment only. Because all the certificates created by the script are self-signed, they areinappropriate for production use.

Location of the Script

Versions of the script are available for UNIX and Windows. The scripts are:

● UNIX

TIBCO_HOME/bw/palettes/bwmq/8.4/samples/createQueueManagerKeystore.sh

● Microsoft Windows

TIBCO_HOME\bw\palettes\bwmq\8.4\samples\sslcert.bat

Script Syntax

Run the script on the platform based on your requirements. For example, on the UNIX system runningthe command: createQueueManagerKeystore.sh keystordir qm-name keystore-password

where:

● keystordir is the directory in which to create the keystores. This can be a working directory or the SSLdirectory in the queue manager's data directory, so long as the queue manager's keystore iseventually placed in the location configured in its SSL parameters.

● qm-name is the name of the queue manager for which the keystore is being created. This name mustuse lower case characters only.

● keystore-password is the password used to secure the keystore.

118


You might either customize the scripts to produce keystores that suit your environment's standards, orenter the commands discretely to accomplish the same thing.

Output of the Script

The objective of each script is to produce two IBM CMS type keystores, each containing an identity andthe other's signing CA certificate. That way, a TLS connection can be instantiated using one keystore ateach end.

Running this script generates a number of files, most importantly:

● qm-name.sth is the stash file for the queue manager's key store.

● qm-name.kdb is the IBM CMS format keystore for the queue manager.

● client.kdb is the IBM CMS format keystore to be used to make a Java keystore for the client.

Configuring the Queue Manager to Use Generated Keystore

After the script has created the keystores, you must configure the queue manager to use the generatedkeystore.

In the plug-in's example, the keystore is named qmwn.kdb and the queue manger name is qmwn. Toconfigure the queue manager, set its SSL Key Repository parameter to this file without the suffix. Thekeystore created with the example in Step 1 is /var/mqm/qmgrs/qmwn/ssl/qmwn.kdb. The value for thecorresponding key database for the queue manager would be /var/mqm/qmgrs/qmwn/ssl/qmwn.

The following figure shows an example of the IBM WebSphere MQ Explorer queue manager propertiesfor SSL.

119


Using the IBM Key Management Tool to Review the Personal Certificate Name

The IBM Key Management tool is used to open the keystore, and it is normally started by the script inthe mqm/bin/strmqikm directory, and the executable is called iKeyMan.

The Personal Certificate name must use all lowercase characters. If your queue manager name containsuppercase characters, rename this alias so that all characters are in lower case. If this alias is not correct,the queue manager is not able to open the keystore.

You cannot simply change an uppercase character to a lowercase character by using IBM KeyManagement tool (iKeyMan). To retain the same name, you have to use an intermediate name for therename function to work.

You can also review the CA certificate that is copied using the script to instruct the queue manager to"trust" the client’s certificate. To see this information, select Signer Certificates from the list below theKey database content heading.

The following figure shows the keystore created in Step 1. Note the name of the personal certificate isibmwebspheremqqmwn. This special alias is composed of the tag ibmwebspheremq with the name of thequeue manager concatenated onto it. In this example, the queue manger name is qmwn.

Creating a TLS Connection for the Queue Manager

Using the IBM WebSphere MQ Explorer, create a server connection channel for the new queue managerand set its SSL properties so that client authorization is enabled (if desired) and a cipher suite isselected.

For example, TRIPLE_DES_SHA_US is a specification which must have a matching cipher inBusinessWorks.

The terms SSL and TLS are used interchangeably in the IBM documentation, and most of the parametersettings for TLS are labeled SSL. Insofar as this document is concerned, TLS is functionally equivalentto SSL V3.

The following figure (SSL Cipher Suite Selection) shows the SSL setting configured using the IBMWebSphere MQ Explorer tool.

120


Setting Up TIBCO ActiveMatrix BusinessWorksAfter setting up the WebSphere MQ queue manager, you can configure TIBCO ActiveMatrixBusinessWorks to use the secure channel.

Procedure

1. In TIBCO Business Studio, open an existing project or create a new one.

2. Create a WebSphere MQ connection.

3. Configure the shared resource.a) In the General panel, type a name in the Name field.b) In the Queue Manager Connection Configuration panel, click Remote in the Binding area.c) Enter remote connection values in the Host Name, Port, User Name, Password, and Server

Channel Name fields.d) In the Pooling Configuration panel, select Pooling Enabled check box.See WebSphere MQ Connection for more information about the configuration.

121


4. Start the IBM Key Manager tool using the strmqikm program.This program is located in the mqm/bin directory in the WebSphere MQ server installation.

5. Using the IBM Key Manager, open the client keystore created by the script during the Setting UpWebSphere MQ Queue Manager.

122


6. Create a Java keystore from the contents of the IBM keystore.a) Select the client identity alias, and click Save As from the File menu.b) Change the keystore type to JKS and enter a new name for the client keystore in the Save As

dialog.This is the file that you reference from the connection resource, as pictured previously.

c) Set the Key file type to JKS.d) Click Save.e) At the prompt, enter a password to be used with the keystore.

7. Specify the WebSphere MQ connection shared resource created in Step 2.a) Select the Transport Layer Security check box in the TLS Configuration panel.

b) Click next to the TLS Configuration field.You can create an SSL Client Configuration resource in the pop-up window.

8. Configure the SSL Client Configuration resource.a) In the General panel, type a name in the Name field.

b) In the Basic SSL Client Configuration panel, click next to the Keystore Provider as TrustStore field.You can create a Keystore Provider resource in the pop-up window.

9. Configure the Keystore Provider resource.a) In the General panel, type a name in the Name field.b) Select SUN from the Provider list.c) In the URL field, specify the java keystore used for the credentials of this connection.d) Specify the value in the Password field.e) Select JKS from the Type list.

123


10. In the created SSL Client Configuration resource, select TLSv1 from the SSL Protocol list.

See TIBCO ActiveMatrix BusinessWorks Bindings and Palettes Reference for more information about theconfiguration.

TroubleshootingYou might encounter some errors while creating secure connections to the queue manager. By verifyingsimple details these errors can be resolved.

Some of the possible errors you might encounter and their resolutions are as follows:

● If you do not know the correct cipher, leave the field blank and press Test Connection. It cyclesthrough all the available ciphers until it finds one that works and report it in the status dialog to theright. If no cipher is accepted, you might have to change the configuration of the server channel.

● Disable client authentication. This means that the queue manager does not check that it trusts thesigner of the plug-in's certificate. If it works with client authentication disabled but not with itenabled, then the two parties do not have all the signing CA certificates in place.

124


● Check the queue manager's log files. These files are in the queue manager's work directory under"errors". For the queue manager above, this file is:

/var/mqm/qmgrs/qmwn/errors/AMQERR01.LOG

A typical error from that file looks like:

----- amqrmrsa.c : 889 --------------------------------------------------------12/07/2012 02:46:09 PM - Process(15433.5) User(jsmith) Program(amqrmppa) Host(bilbo.jrr.org) Installation(Installation1) VRMF(7.5.0.0) QMgr(qmwn) AMQ9660: SSL key repository: password stash file absent or unusable.

EXPLANATION:The SSL key repository cannot be used because MQ cannot obtain a password toaccess it. Reasons giving rise to this error include: (a) the key database file and password stash file are not present in the location configured for the key repository, (b) the key database file exists in the correct place but that no password stash file has been created for it, (c) the files are present in the correct place but the userid under which MQ is running does not have permission to read them, (d) one or both of the files are corrupt.

The channel is '????'; in some cases its name cannot be determined and so isshown as '????'. The channel did not start.ACTION:Ensure that the key repository variable is set to where the key database fileis. Ensure that a password stash file has been associated with the key databasefile in the same directory, and that the userid under which MQ is running hasread access to both files. If both are already present and readable in thecorrect place, delete and recreate them. Restart the channel.----- amqccisa.c : 5540 -------------------------------------------------------12/07/2012 02:46:09 PM - Process(15433.5) User(jsmith) Program(amqrmppa) Host(bilbo.jrr.org) Installation(Installation1) VRMF(7.5.0.0) QMgr(qmwn)

This error occurred because the queue manager does not have read permission to the files in the SSLdirectory. This happened because the default file creation mask does not support group read.

Plug-in with Large MessagesWebSphere MQ cannot accept an arbitrarily large message. It has restrictions based on the size of thebuffers in the queue manager and its various channels. The preferred method for dealing withmessages too large for the queue manager or an intermediate channel to accept is to segment themessage.

The plug-in supports explicit segmentation, whereby the message is split into segments by the plug-initself as well as automatic segmentation performed by the queue manager. See the Multi-Message tabof the Put activity for more information.

Segmented messages are not supported on z/OS.

Sending and Receiving Long MessagesActivities that support logical messages have a Multi-Message tab on which the sending and receivingof logical messages can be configured.

When getting a message from a queue which has or might have logical messages, it is important toconfigure these options to prevent the inadvertent removal of a member of a group, the followingfigure shows the Multi-Message tab in the Put activity.

125


Message Groups

Both the put and get operations support message groups.

● The put operation, there are three ways to send a multiple message group through the plug-in:

— The Batch option does not create a group. If you click Batch, you can send all the messagesconfigured through the input schema in a single logical unit of work. Each node in the inputschema is composed into a message and is sent within the bounds of a syncpoint. When thenodes are sent successfully, a commit is performed. If this is done within the context of an MQLocal Transaction, the commit is deferred until the transaction scope ends.

— The BatchGroup option sends all the messages represented by the input schema as members ofa single logical message. Commit boundaries are the same as for a Batch group.

— You can use the CustomGroup option to use a sequence of put operations to create a logicalgroup. You can turn on the last message flag in the input schema for the last message or makethe group fail. You can also use a loop to create the logical message. If the individual CustomGroup operations are not in a local transaction, they are committed at the end of the activitywhich means that any application listening for these message might begin to process themimmediately. If it is a requirement that no application accesses these messages until the group iscompleted, place the creating loop inside a local transaction.

● The get operation supports the Batch and BatchGroup operations. In the Batch mode, messages areretrieved until the specified size of the batch is reached and then returned to the activity asindividual nodes on the output Batch schema. This is done as a single unit of work and is committedwhen the activity completes unless it is inside an MQ Local Transaction. The BatchGroup modefetches the contents of an entire logical message and returns it as a batch. The commit semantics arethe same as for Batch gets.

If the None option is selected, an a logical message is encountered and the first member ofthe logical message is fetched and returned from the activity. This breaks the logicalmessage structure, so take note when accessing queues, which contain logical messages.The Complete Message and Get Ordered flags can be turned off to access the members ofbroken groups.

For get and put operations, the Multi-Message tab contains the Syncpoint Used check box, which isnot a configuration option, but an indication of whether the operation requires the use of a syncpoint.Syncpoints impose a significant overhead on queue operations, so avoid using them wherever possiblefor performance reasons. However, for groups of messages, it is efficient to process the group within asingle sync-point.

Logical messages can also be created and consumed in loops by using the Get and Put activitiesconfigured with the CustomGroup option which is in the Multi-Message tab. Working with largemessages in loops makes it possible to process very large messages without necessarily consuming anequivalent amount of memory.

Segmented Messages

Both the Get and Put activities support segmented messages.

The Get activity creates segmented messages if messages are slices of a larger message. The segmentedmessages are always concatenated together to reconstitute the original message after the operation.Individual segments might not differ in terms of the message context or other fields on the input

126


schema. The Get activity always returns a single reconstituted message when a segmented message isencountered.

The Put activity creates a segmented message if Explicit is selected in the Segmentation field and themessage is larger than the size provided. The queue manager automatically creates segment messagesif Queue Manager is selected in the Segmentation field. If Both is selected in the Segmentation field, itmeans both the Explicit and Queue Manager options are selected.

Segmented messages can also be created and consumed in loops by using get and put activitiesconfigured with the CustomSegmented option which is in the Multi-Message tab. Working with largemessages in loops makes it possible to process very large messages without necessarily consuming anequivalent amount of memory.

The segmented message feature is not supported by WebSphere MQ on z/OS.

Message FiltersWhen reading messages from WebSphere MQ, you can limit which messages are read using messagefilters.

You can read only messages that match a specified correlation ID, message ID, or group ID in the Getand Listener activities.

● Assigning IDs

These values are assigned to the WebSphere MQ message when it is created. You can specify thedesired ID using the mqproperties element in the Input tab of the Put activity. However, mostapplications let the queue manager automatically generate an identifier.

● Specifying Filters

Filters can be set for Get and Listener activities.

● For Get activities, the filter can be set using the correlationId, messageId, and groupIdelements in the Input tab. These elements are grouped under the mqproperties elementheading.

● For Listener activities, the filter is set using the Correlation Id, Message Id, and Group Id fieldsin the Advanced tab.

Filter Scenario: Request-Reply

One common use for filters is in a request-reply interaction. In this scenario, a message publisher puts aRequest message in the queue that is handled by a service application. The Request message specifies aReply To Queue name, indicating the queue where the requestor looks for the reply message.

Because the same Reply to Queue is often used by many message requestors, the message requester canuse the correlation ID generated by the Put activity to identify those reply messages that are sent inresponse to its own request.

To enable this functionality, map the correlationId element from the Output tab of the Put activity tothe correlationId element in the Input tab of the Get activity that reads the reply message. Startingfrom version 8.3.0 of the plug-in, there is a specific RequestReply activity to automate this pattern.

It is the responsibility of the application replying to the request to set the correct correlation ID in thereply message. The correlation ID is present in the request message header.

Filter Scenario: Reports

Filters can also be used to identify the confirmation of delivery report associated with a put message.

When a put message activity requests a delivery report using the report element in the Input tab, thequeue manager puts a report message into the specified Report Reply Queue queue.

127


Correlation IDs are used to relate the original put message to the report messages. Using the PassCorrelation ID check box, you choose whether the original message ID or correlation ID is used for thereport message correlation ID.

As in the previous scenario, the process can pass the correlationId element shown in the Output tabof the Put activity to the correlationId element in the Input tab of Get activity that reads the reportmessages.

128


Managing Logs

Logs are used to trace and troubleshoot plug-in exceptions.

A logback.xml file is located in the TIBCO_HOME\bw\version_number\config\design\logbackdirectory. Update this file to set up log levels and export logs to a file.

Log LevelsThe plug-in captures logs at different levels.

Log Level Description

Info Indicates normal plug-in operations. No action is needed. A tracing messagetagged with Info indicates that a significant processing step is reached, andlogged for tracking or auditing purposes. Only info messages preceding atracking identifier are considered as significant steps.

Warn Indicates that an abnormal condition occurred. Processing continues, butspecial attention from an administrator is recommended.

Error Indicates that an unrecoverable error occurred. Depending on the severity ofthe error, the plug-in might continue with the next operation or might stop.

Debug Indicates a developer-defined debug message.

Setting Up Log LevelsBy default, the log level is Error . You can change the log level to trace different messages.

If neither the plug-in log nor the BusinessWorks log is configured in the logback.xml file, the errorlogs of the plug-in is displayed in the Console view by default.

If the plug-in log is not configured but the BusinessWorks log is configured in the logback.xml file, theconfiguration for the BusinessWorks log is implemented by the plug-in.

Procedure

1. Navigate to the TIBCO_HOME\bw\version_number\config\design\logback directory and openthe logback.xml file.

2. Add the following node in the Console Appender area to specify the log level for the plug-in.<logger name="com.tibco.bw.palette.bwmq.runtime"> <level value="DEBUG"/></logger>

The level tag defines the log level and the value is Error or Debug.

When the level is set to Debug, the input and output for the plug-in activities are alsodisplayed in the Console view. See Log Levels for more details regarding each log level.

3. Optional: Add the following node in Console Appender area to specify the log level for an activity.<logger name="com.tibco.bw.palette.bwmq.runtime.ActivityNameActivity"> <level value="DEBUG"/></logger>

129


For example, if you want to set the log level of the Put activity to Debug, you are required to add thefollowing node:<logger name="com.tibco.bw.palette.bwmq.runtime.PutActivity"> <level value="DEBUG"/></logger>

For the activities that do not configure with specific log levels, they still inherit the loglevel configured for the plug-in or BusinessWorks.

4. Save the file.

Exporting Logs to a FileModify the logback.xml file to export plug-in logs to a file.

Procedure

1. Navigate to the TIBCO_HOME\bw\version_number\config\design\logback directory and openthe logback.xml file.

When deploying an application in TIBCO Enterprise Administrator, navigate to theTIBCO_HOME\bw\domains\mydomain\appnodes\myspace\mynode directory to find thelogback.xml file.

2. Add the following node to specify the file location.<appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>c:/bw6-mq.log</file> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36}-%msg%n</pattern> </encoder></appender>

The file tag defines the location to which the log is to be exported and the value is the absolutepath of the file.

You also have to add the file name in the file path.

3. Add the following node to the root node at the bottom of the logback.xml file to enable exportingthe logs to a file. <appender-ref ref="FILE" />

<root level="DEBUG"> <appender-ref ref="STDOUT" /> <appender-ref ref="FILE" /></root>

4. Save the file.

130


Error Messages

The following table lists the error messages of TIBCO ActiveMatrix BusinessWorks Plug-in forWebSphere MQ.

Message Identifier Message Solution

TIBCO-BW-PALETTE-MQ-000001

{0} This is an internal error. It isappropriate to open a supportissue for this error.


{0) This is a trace message andresolution is not applicable.


{0} This is a debug message andresolution is not applicable.


{0} This is an informationalmessage and it highlights theruntime progress of theactivity. Resolution is notapplicable.


{0} This is a warning message,usually related to havingreceived a warning from theMQ API. No resolution isnecessary.


Warning; failed to release

resources in event source:

[{0}]

This indicates that connectionsor destinations may have beenleft open after the end of theprocess. Investigate if thisoccurs frequently.


Warning; explicit client

confirmation not encountered

for message in activity [{0}]

A confirmation was indicatedfor this process starter andnone was encountered in theprocess. Correct the process.


Warning; confirm encountered

for a message that did not

specify explicit client

confirmation

A confirmation activity wasencountered for a processstarted that did not indicateconfirmation was required.Correct the process.


Warning, error while closing

client: [{0}]

An exception happened whenclosing the connection to thequeue manager. An orphanedconnection might exist until theinstance is terminated.Investigate if this occursfrequently

131




Warning; exception

encountered while rolling

back a queuing operation;

CompCode [{0}] ReasonCode

[{1}] ErrorCode [{2}]

DecodedMessage [{3}]

Check to see if a message wasremoved from the queuewithout having been properlyprocessed. Investigate toensure that the message wassuccessfully rolled back.


Warning; exception

encountered while closing a

destination; CompCode [{0}]

ReasonCode [{1}] ErrorCode

[{2}] DecodedMessage [{3}]

An exception was encounteredwhile closing the destinationobject. Examine the error codesand consult the IBMWebsphere documentation formore information.


Warning; exception

encountered while closing the

queue manager; CompCode [{0}]



There is no resolution requiredfor this warning.


Warning; exception

encountered while

disconnecting from the queue

manager; CompCode [{0}]



There is no resolution requiredfor this warning.


Warning; exception

encountered during commit;




Examine the error codes andconsult the IBM Webspheredocumentation for moreinformation. Contact support ifno resolution is reached.


WebSphere MQ warning during

get or put operation;




This operation completedsuccessfully but a warningexception was thrown.Examine the output of theactivity to be sure that itconforms to expectations. Themost common reason for awarning is that an encodingproblem exists with themessage.


The named property [{0}] does

not exist in the message or

is not of type [{1}]

The schema which representsthe message propertiescontained a node that was notin the message. This could benormal or could indicate anincorrect schema.


Value "[{0}]" for field [{1}]

contains whitespace

Correct the configuration ormapped variable.

132




Error sending message: [{0}] The message has not been sent.Use the error messageprovided to debug the issue.Contact support if noresolution is reached.


Error connecting to queue

manager: [{0}]

The plug-in cannot connect tothe queue manager, eitherbecause it is misconfigured orthere is a network or queuemanager problem. Correct theproblem and retry.


Error Opening:[{0}] [{1}] Ensure that the queue existsand this this user has access toit.


Error closing destination

[{0}] with close option [{1}]

message: [{2}]

No resolution required. Therehas been an error closing thedestination after the processhas finished committing itswork.


Error processing credentials:

[{0}]

Examine the configuration ofthe connection resource's TLSconfiguration for possibleproblems with the keystorepassword.


Message get error;

DecodedMessage [{0}] CompCode

[{1}] ReasonCode [{2}]

ErrorCode [{3}]

The schema for the messagedid not match the content orthe code page used to decode itwas incorrect. Correct theconfiguration.


Error getting a message:

[{0}]

This is a generic get failure.Examine the contents of theembedded message for moreinformation. Contact support ifno resolution is reached.


Error connecting to the local

queue manager because the

native libraries are not

available on

java.library.path: [{0}]

Ensure that the relevant librarysearch paths for the platformcontain the MQ native librarydirectories. Refer to the UsersGuide for assistance.


Connection resource local

bindings are not supported

for XA transactions

In order to participate in an XAtransaction the connectionmust be of the Remote orCCDT type.

133




Failed to create destination

[{0}:{1}]

The configuration of thedestination is incorrect. Verifythat this destination exists andthat the application isauthorized to open it.


Configuration error; Model

queue not provided

Provide a model queue for thetemporary destination.


Malformed URL exception for

client connection table:

[{0}]

The CCDT TAB file was notfound. Valid formats for thisURL are: file:///.. ftp://...http://... A browser can be usedto test that the URL is valid.


Internal Error; missing

required input parameter:

[{0}]

No input was provided for aput or publish activity. Providecontent for the message beingsent.


Activity [{0}] confirm failed The queue manager wasunable to commit a unit ofwork. Examine the errormessage and queue managerlogs to determine why thequeue manager could notperform the associated commitoperation.


Queue manager failed to

commit a unit of work: [{0}]

Examine the error message andqueue manager logs todetermine why the queuemanager could not perform theassociated commit operation.


Get timed out There were no messagesmatching the selection criteriafor this get operation withinthe number of millisecondsthat the operation wasconfigured to wait. This can bea normal occurrence.


Index type error Check that the queue isindexed. It is not possible tofilter a get unless the queuemanager is maintainingindexes for the filter fields.Note that z/OS queuemanagers do not automaticallyindex queues where otherplatforms do.

134




Activity cancelled The MqListener eventsource isstopped while processing amessage; the message is backedout.


Message received on a

cancelled listener; sent to

dead letter queue: [{0}]

The MqListener eventsourcewas stopped but because theWebSphere MQ get API call isnot interruptable itsubsequently received amessage which has beentransferred to the dead letterqueue. This can be avoided byturning on explicit commits.


Message received on a

cancelled listener but there

is no dead letter queue;

messageId [{0}] lost.

The MqListener eventsourcewas stopped but because theWebSphere MQ get API call isnot interruptable itsubsequently received amessage. There is no deadletter queue so the message hasbeen discarded.


IO Error in MQ; [{0}] There has been an errorreading or writing the contentsof a message. Ensure that themessage body is describedcorrectly by its schemas (ifany), and that all encodings arecorrect.


Invalid application

properties item: [{0}]

Message: [{1}]

An application properties itemof an unsupported type wasprovided. Use a supportedtype for the property.


Invalid dynamic properties

item: [{0}] Message: [{1}]

A dynamic property item of anunsupported type or contentwas provided. Use a supportedtype for the property.


Failed to open poison message

error queue [{0}:{1}]

The error queue defined forpoison message handling couldnot be opened. Provide anaccessible queue for poisonmessages.


Failed to put a poison

message to the configured

error queue [{0}:{1}]

Ensure that the application hasaccess to the queue and can putmessages on it.

135




A poison message ID [{0}] was

detected and copied to the

error queue [{1}]

Ensure that the application hasaccess to the queue and can putmessages on it.


Message put error;

DecodedMessage [{0}] CompCode

[{1}] ReasonCode [{2}]

ErrorCode [{3}]

Examine the provided messageand codes to determine thesource of the put error. Contactsupport if no resolution isreached.


Local transaction commit

failed

The queue manager failed tocommit a unit of work whichwas associated with a localtransaction. This failureoccurred on the first (possiblyonly) queue manager involvedso all resources is backed out.


Local transaction commit for

queue manager [{0}] failed

after [{1}] succeeded; queues

are in an inconsistent state

The queue manager failed tocommit a unit of work whichwas associated with a localtransaction. Multiple queuemanagers were involved and atleast one other queue managerhas committed messages aspart of this failed transaction. Itis not supported to enlistmultiple queue managers in alocal transaction.


Failed to confirm or release

an MQ ProcessStarter activity

[{0}]. This error can occur

after recovering from a

check-pointed BusinessWorks

process instance.

A confirm activity hasattempted to confirm amessage after an activityresume (from checkpoint) butthe connection is lost. Themessage is backed out and theprocess must be restarted.


Process started encountered

an unexpected error:[{0}]

Internal error. Contact support.


Failed to close the

destination object associated

with this process

An error was encounteredclosing a destination. This isnot normally a serious problembut should be investigated if itoccurs repeatedly.


Configuration error; Dynamic

ReplyTo Model not provided

A model queue was notprovided for a temporaryreplyto destination.

136




Error processing password:

[{0}]

There is a problem decodingthe password, check that it iscorrectly specified on theconnection resource.


Error processing message body

field [{0}] - [{1}]

The message body schema forthis message does not matchthe contents of the message intype or length. The field inerror is indicated.


Inquire error; Unknown queue

type [{0}] returned

This is an internal error. It isappropriate to open a supportissue for this error.


Inquire error; Unknown

sharability type [{0}]

returned

This is an internal error;contact support.


Inquire error; Destination

type [{0}] provided

Destination type must bequeue


Inquire error; Reason [{0}]



Examine the provided reasonand codes to determine thesource of the inquire error. Thecodes are described in IBM'sWebSphere MQdocumentation.


Connection pool is exhausted,

size is [{0}]

Increase the pool size


Browse timed out There were no messagesmatching the selection criteriafor this browse operationwithin the number ofmilliseconds that the operationwas configured to wait. Thiscan be a normal occurrence.


Error reported by the CICS

bridge: [{0}]

Examine the error message andresolve the problem related tothe host program execution.


WebSphere MQ client API

version info: [{0}]

Information only, no resolutionrequired.


WebSphere MQ BusinessWorks

plug-in version info: [{0}]

Information only, no resolutionrequired.

137


Date post:	18-Aug-2020
Category:	Documents
Upload:	others
View:	4 times
Download:	0 times

TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ … · 2016. 8. 24. · About WebSphere...

Documents