TIBCO ActiveMatrix BusinessWorks™ Plug

TIBCO ActiveMatrix BusinessWorks™ Plug
TIBCO ActiveMatrix
BusinessWorks™ Plug-in for
WebSphere MQ
User’s Guide
Software Release 7.6
November 2015
Two-Second Advantage®
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE
LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED
IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS
AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN
AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws and
treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO
Software Inc.
TIBCO, Two-Second Advantage, TIBCO Administrator, TIBCO ActiveMatrix BusinessWorks,
TIBCOActiveMatrix BusinessWorks Plug-in for Data Conversion, TIBCO BusinessWorks XA Transaction
Manager, TIBCO Designer, TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ, TIBCO Enterprise
Message Service, TIBCO Hawk, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered
trademarks 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 Enterprise Edition
(J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation
in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC
OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.
CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE 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 OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING
BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 2012-2015 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Documentation . . . . . . . . . . . . . . . . . . . . . xii
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Third-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xvii
xvii
xvii
xvii
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
WebSphere MQ Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Chapter 2 Working with the Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Transactions with WebSphere MQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using the Data Conversion Plug-in with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Creating Secure Connections to the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
WebSphere MQ Queue Manager Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
TIBCO ActiveMatrix BusinessWorks Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using the Plug-in with Large Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Logical and Segmented Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using Loops to Send and Receive Logical Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Filter Scenario: Request-Reply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Filter Scenario: Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Trace Facilities Available In The Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
iv
| Contents
Chapter 3 WebSphere MQ Palette. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
WebSphere MQ Connection Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pooling Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TLS Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
27
29
30
WebSphere MQ Properties Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
WebSphere MQ Message Body Fields Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultiMessage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
37
39
44
47
53
55
WebSphere MQ Get Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultiMessage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
57
58
63
66
68
72
WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultiMessage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Misc Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
74
78
81
82
83
88
WebSphere MQ Publish Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
WebSphere MQ Subscriber Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Misc Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
103
104
106
108
109
113
WebSphere MQ SyncPoint Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Contents v
|
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
WebSphere MQ Inquire Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Chapter 4 Sample ActiveMatrix BusinessWorks Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Opening the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Using the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Overview of Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Basic Send and Receive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Dynamic Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Message Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Segmented Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
CustomGroup Logical Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Appendix A Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
vi
| Contents
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Figures vii
|
Figures
Figure 1
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Figure 2
Using the Data Conversion Plug-in to Convert Canonical Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Figure 3
WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 4
IBM Key Management Tool: iKeyMan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Figure 5
SSL Cipher Suite Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 6
TLS Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Figure 7
The Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 8
The Connection Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Figure 9
Schemas—The WebSphere MQ Application Properties Resource . . . . . . . . . . . . . . . . . . . . . . . 126
Figure 10
The Put Activity—Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Figure 11
The Put Activity—Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Figure 12
The Put Activity—Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Figure 13
The Put Activity—Output Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Figure 14
The Get Activity—Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Figure 15
The Get Activity—Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Figure 16
Dynamic Destinations—Listen Activity Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Figure 17
Dynamic Destinations—Put to a Dynamic Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Figure 18
Message Groups—MultiMessage Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Figure 19
Send Grouped Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Figure 20
Reports—Requesting a Confirm on Delivery Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Figure 21
Reports—Put Activity Input Tab and Application Properties Node . . . . . . . . . . . . . . . . . . . . . . . . 141
Figure 22
Reports—Listener Activities and Filter Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Figure 23
Reports—Report Message Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Figure 24
Requests—Message Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Figure 25
Requests—Mapping the Reply to Queue Name from a Global Variable . . . . . . . . . . . . . . . . . . . 145
Figure 26
Segmented Messages—Put Activity MultiMessage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Figure 27
Custom Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Figure 28
Custom Group of the Get Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
viii
| Figures
Figure 29
XA Transaction—Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Figure 30
XA Transaction—Success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Figure 31
XA Transaction—Failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Tables ix
|
Tables
Table 1
General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Table 2
Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Table 3
Fields in the Configuration Tab: WMQ Connection Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 4
Fields in the Pooling Tab: WMQ Connection Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 5
Fields in the TLS Tab: WMQ Connection Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 6
Types and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 7
Fields in the Configuration Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 8
Fields in the Advanced Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 9
Fields in the MultiMessage Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 10
Fields in the Input Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 11
Fields in the Output Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Table 12
Field in the Error Output Tab: WebSphere MQ Put Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Table 13
Fields in the Configuration Tab: WebSphere MQ Get Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Table 14
Fields in the MultiMessage Tab: WebSphere MQ Get Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 15
Fields in the Input Tab: WebSphere MQ Get Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Table 16
Fields in the Output Tab: WebSphere MQ Get Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 17
Fields in the Error Output Tab: WebSphere MQ Get Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 18
Fields in the Configuration Tab: WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . 74
Table 19
Fields in the Advanced Tab: WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Table 20
Fields in the MultiMessage Tab: WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . 81
Table 21
Fields in the Output Tab: WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Table 22
Fields in the Error Output Tab: WebSphere MQ Listener Activity . . . . . . . . . . . . . . . . . . . . . . . . . 88
Table 23
Fields in the Configuration Tab: WebSphere MQ Publish Activity . . . . . . . . . . . . . . . . . . . . . . . . . 90
Table 24
Fields in the Advanced Tab: WebSphere MQ Publish Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Table 25
Fields in the Input Tab: WebSphere MQ Publish Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Table 26
Fields in the Output Tab: WebSphere MQ Publish Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Table 27
Fields in the Error Output Tab: WebSphere MQ Publish Activity . . . . . . . . . . . . . . . . . . . . . . . . . 102
Table 28
Fields in the Configuration Tab: WebSphere MQ Subscriber Activity . . . . . . . . . . . . . . . . . . . . . 104
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
x
| Tables
Table 29
Fields in the Advanced Tab: WebSphere MQ Subscriber Activity. . . . . . . . . . . . . . . . . . . . . . . . . 106
Table 30
Fields in the Misc Tab: WebSphere MQ Subscriber Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Table 31
Fields in the Output Tab: WebSphere MQ Subscriber Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Table 32
Fields in the Error Output Tab: WebSphere MQ Subscriber Activity. . . . . . . . . . . . . . . . . . . . . . . 113
Table 33
Fields in the Configuration Tab: WebSphere MQ SyncPoint Activity . . . . . . . . . . . . . . . . . . . . . . 114
Table 34
Fields in the Input Tab: WebSphere MQ SyncPoint Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Table 35
Fields in the Error Output Tab: WebSphere MQ SyncPoint Activity . . . . . . . . . . . . . . . . . . . . . . . 115
Table 36
Fields in the Configuration Tab: WebSphere MQ Inquire Activity . . . . . . . . . . . . . . . . . . . . . . . . . 116
Table 37
Fields in the Input Tab: WebSphere MQ Inquire Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Table 38
Fields in the Output Tab: WebSphere MQ Inquire Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Table 39
Fields in the Error Output Tab: WebSphere MQ Inquire Activity . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Table 40
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
| xi
Preface
TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ is referred to
as the plug-in in this manual. With this plug-in, you can design and implement
ActiveMatrix BusinessWorks applications that exchange messages with other
WebSphere MQ-capable applications across a wide range of hardware and
operating systems.
This plug-in, together with TIBCO ActiveMatrix BusinessWorks Plug-in for Data
Conversion, provides ActiveMatrix BusinessWorks with the ability to encode
XML-structured data into byte sequences to be sent to a WebSphere MQ-capable
application. These byte sequences can populate a memory range within the
application and then be interpreted by the application as variable values, as
defined by the application programming language (COBOL, RPG or PL/I).
Conversely, the value of variables occupying a memory range within the
WebSphere MQ-capable application may be sent to an ActiveMatrix
BusinessWorks as a byte sequence, and from there be decoded into
XML-structured data for further use.
Topics
•
Related Documentation, page xii
•
Typographical Conventions, page xiv
•
Connecting with TIBCO Resources, page xvii
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
xii
| Related Documentation
Related Documentation
This section lists documentation resources you might find useful.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Documentation
The following documents form the TIBCO ActiveMatrix BusinessWorks Plug-in
for WebSphere MQ documentation set:
•
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Installation Read
this manual for instructions on site preparation and installation.
•
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s
Guide Read this manual for instructions on using the product on all platforms.
•
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Release
Notes Read the release notes for a list of new and changed features. This
document also contains lists of known issues and closed issues for this release.
Other TIBCO Product Documentation
You might find it useful to read the documentation for the following TIBCO
products:
•
TIBCO Administrator™ software: this product provides capabilities for
managing users, monitoring machines, and deploying and managing
applications that use TIBCO products.
•
TIBCO ActiveMatrix BusinessWorks™ software: this product provides an
integration platform for companies to rapidly integrate systems and automate
business processes.
•
TIBCO ActiveMatrix BusinessWorks™ Plug-in for Data Conversion software:
this product is a prerequisite for working with TIBCO ActiveMatrix
BusinessWorks Plug-in for WebSphere MQ.
•
TIBCO BusinessWorks™ XA Transaction Manager software: this product is
required if the TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere
MQ activities run in a TIBCO BusinessWorks XA Transaction group.
•
TIBCO Designer™ software: TIBCO Designer is an intuitive graphical user
interface for the design-time configuration of TIBCO applications. Online help
is available for TIBCO Designer palettes.
•
TIBCO Enterprise Message Service™ software: this product sends messages
from your applications in a format that conforms to the Java Messaging
Service (JMS) specification.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Preface xiii
|
•
TIBCO Hawk® software: this product is for monitoring and managing
distributed applications and systems throughout the enterprise.
Third-Party Documentation
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ relates to other
products documentation which you might find helpful.
WebSphere MQ description and documentation, which may be found at:
http://www-01.ibm.com/software/integration/wmq/library/library75.html
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
xiv
| Typographical Conventions
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention
Use
ENV_NAME
TIBCO products are installed into an installation environment. A product
installed into an installation environment does not access components in other
installation environments. Incompatible products and multiple instances of the
same product must be installed into different installation environments.
TIBCO_HOME
<ProductAcron
ym>_HOME
An installation environment consists of the following properties:
•
Name Identifies the installation environment. This name is referenced in
documentation as ENV_NAME. On Microsoft Windows, the name is
appended to the name of Windows services created by the installer and is a
component of the path to the product shortcut in the Windows Start > All
Programs menu.
•
Path The folder into which the product is installed. This folder is referenced
in documentation as TIBCO_HOME.
TIBCO <ProductName> installs into a directory within a TIBCO_HOME. This
directory is referenced in documentation as <ProductAcronym>_HOME. The
default value of <ProductAcronym>_HOME depends on the operating system.
For example on Windows systems, the default value is
C:\tibco\<ProductAcronym>\<ReleaseNumber>.
code font
Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use M y C o m m a n d to start the foo process.
bold code
Bold code font is used in the following ways:
font
•
In procedures, to indicate what a user types. For example: Type a d m i n .
•
In large code samples, to indicate the parts of the sample that are of
particular interest.
•
In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, M y C o m m a n d is enabled:
MyCommand [enable | disable]
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Preface xv
|
Table 1 General Typographical Conventions (Cont’d)
Convention
Use
italic font
Italic font is used in the following ways:
Key
combinations
•
To indicate a document title. For example: See TIBCO ActiveMatrix
BusinessWorks Concepts.
•
To introduce new terms For example: A portal page may contain several
portlets. Portlets are mini-applications that run in a portal.
•
To indicate a variable in a command or code syntax that you must replace.
For example: M y C o m m a n d PathName
Key name separated by a plus sign indicate keys pressed simultaneously. For
example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example,
data loss or corruption if certain steps are taken or not taken.
Table 2 Syntax Typographical Conventions
Convention
Use
[ ]
An optional item in a command or code syntax.
For example:
MyCommand [optional_parameter] required_parameter
|
A logical O R that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand param1 | param2 | param3
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
xvi
| Typographical Conventions
Table 2 Syntax Typographical Conventions (Cont’d)
Convention
Use
{ }
A logical group of items in a command. Other syntax notations may appear
within each logical group.
For example, the following command requires two parameters, which can be
either the pair p a r a m 1 and p a r a m 2 , or the pair p a r a m 3 and p a r a m 4 .
MyCommand {param1 param2} | {param3 param4}
In the next example, the command requires two parameters. The first parameter
can be either p a r a m 1 or p a r a m 2 and the second can be either p a r a m 3 or p a r a m 4 :
MyCommand {param1 | param2} {param3 | param4}
In the next example, the command can accept either two or three parameters.
The first parameter must be p a r a m 1 . You can optionally include p a r a m 2 as the
second parameter. And the last parameter is either p a r a m 3 or p a r a m 4 .
MyCommand param1 [param2] {param3 | param4}
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Preface xvii
|
Connecting with TIBCO Resources
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts. It is a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to https://community.tibco.com/.
How to Access TIBCO Documentation
Documentation for this and other TIBCO products is available on the TIBCO
Documentation site:
https://docs.tibco.com
Documentation on the TIBCO Documentation site is updated more frequently
than any documentation that might be included with the product. To ensure that
you are accessing the latest available help topics, please visit us at
https://docs.tibco.com.
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, contact
TIBCO Support as follows:
•
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 can request one.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
xviii Connecting with TIBCO Resources
|
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
|1
Chapter 1
Introduction
This chapter provides an overview of the product TIBCO ActiveMatrix
BusinessWorks Plug-in for WebSphere MQ, referred to as the plug-in in this
manual. It discusses main features of the product and describes how the various
components are designed.
Topics
•
Product Overview, page 2
•
WebSphere MQ Messages, page 4
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
2
| Chapter 1
Introduction
Product Overview
You can access WebSphere MQ queues and messages with WebSphere MQ
applications by using the plug-in. While it is possible to exchange free form text
data using WebSphere MQ, the Plug-in is specifically intended to be used with the
TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion. The Plug-in for
Data Conversion allows TIBCO ActiveMatrix BusinessWorks applications to use
IBM standard copybooks to interface with legacy applications using several
transport mechanisms such as this Plug-in.
The Plug-in supports the following features:
•
WebSphere MQ 7.x and upward releases. The Plug-in supports the connection
to WebSphere MQ 6.x to the same extent that IBM supports connections
between WebSphere MQ Server 6.x and Client 7.x. See the IBM documentation
for the version of softwares installed to determine if the features you wish 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
— Schema based messages
•
A Connection resource that contains all parameters relevant to establishing a
connection, including automatic re-connectivity.
•
Connections can be pooled and secured with TLS.
•
A WebSphere MQ Get activity that gets a message from a queue and returns
the message as a byte array, a text string, or an XML schema based structure
defined in a separate resource.
•
A WebSphere MQ Put activity that puts message to a queue. Payloads are
binary blobs, text strings and XML schema based messages.
•
A WebSphere MQ Listener activity that gets a message from a queue as a
process starter. The message can be explicitly acknowledged from within the
new process. If the message is not acknowledged, it is placed back on the
queue.
•
The WebSphere MQ Publisher and Subscriber activities perform topic publish
and subscribe functions using messages, as described previously.
•
The WebSphere MQ Inquire activity that inquires about the current state of a
queue. It is primarily intended to obtain the depth of the queue.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Product Overview 3
|
•
Handles the following message types:
— Datagram
— Request
— Reply
— Report (COA, COD, Expiration and Exception types are supported)
•
Filters on correlation, message and group identifiers.
•
XA transactions for get and put activities.
•
Grouped messages (Logical Messages) and segmented messages. Logical
message members can also be segmented messages.
•
Batched messages. To improve performance in certain circumstances,
messages can be sent or retrieved in batches. These batches are not logical
messages, but groups of messages only related by the selection criteria
specified on the get. They are presented on the input and output schema as
duplicates of the usual message node.
•
Dynamic queues.
•
WebSphere MQ message properties.
•
Dynamic properties. All activities which work with messages now have a
DynamicProperties node on their input or output schemas.
•
The WebSphere MQ Listener activity can filter messages in the usual three
fields (Correlation Id, Message Id, and Group Id) by using a filter composed
of a text, hexbin, or base64 filter string.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
4
| Chapter 1
Introduction
WebSphere MQ Messages
WebSphere MQ messages consist of three basic sections:
•
A header containing fields.
•
Message properties that are collection of property names and property values.
•
The message body.
The Plug-in uses different mechanisms to provide access to these sections.
Message
Headers
The Get, Put, and Listener activities provide access to WebSphere MQ message
headers using the input and output schemas for an activity. The root name
m q p r o p e r t i e s contains the fields of message headers. Field names used in
m q p r o p e r t i e s generally map to message header field names used in the
WebSphere MQ interface for Java. Only applicable fields are exposed in the input
and output schema. For example, the field a c c o u n t i n g T o k e n is not an input
schema field but is an output schema field for the get activity.
Message
Properties
Message properties are a collection of name value pairs that can be sent with a Put
activity to a destination, or can be received from a destination for Get and Listener
activities. Values for the properties are either defined by a schema or are provided
dynamically. If a schema is used (WMQ Application Properties resource), the
property types are enforced by the schema. If dynamic properties are used, the
property types are provided in the input or output of the activity.
Message Body
The message body can be an opaque byte array, a string (XML for instance) or a
schema based byte arrays. Text strings are encoded and decoded using the
c h a r a c t e r s e t property of the message being sent or retrieved. Schema based
message bodies are encoded and decoded based on a "WMQ Message Fields"
schema defined in the projects S c h e m a s folder.
Binary WebSphere MQ message payloads are often complex combinations of
string, integer, and other fields types. Ensure that the Plug-in for Data Conversion
is used to parse and render such complex message bodies.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
|5
Chapter 2
Working with the Plug-in
This chapter describes topics particular to the TIBCO ActiveMatrix
BusinessWorks Plug-in for WebSphere MQ.
Topics
•
Transactions with WebSphere MQ, page 6
•
Using the Data Conversion Plug-in with WebSphere MQ, page 7
•
Creating Secure Connections to the Queue Manager, page 9
•
Using the Plug-in with Large Messages, page 20
•
Using Message Filters, page 23
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
6
| Chapter 2
Working with the Plug-in
Transactions with WebSphere MQ
If a WebSphere MQ put or get activity appears within the context of an XA
transaction group, it participates in the XA transaction. Resources committed or
rolled back at the end of the transaction include those of the WebSphere MQ
activities in the group.
Figure 1 depicts a scenario where two XA Transaction aware activities exist within
an XA Transaction group. In the case of the WebSphere MQ Plug-in, the resource
manager enlisted on the XA Transaction is the WebSphere MQ Queue Manager
which allows it to participate as a full member in the distributed transaction, thus
ensuring the integrity of both the WebSphere MQ queue and the state of any other
XA resource coordinated by this transaction. Thus, the access to a WebSphere MQ
queue, a database and a JMS queue can all be synchronized through their
participation in this distributed XA Transaction.
This scenario assumes that the client API used by the plug-in is an Extended
Transactional Client (ETC). ETC is the default client delivered in all 7.5 client
installations and is a free of charge option for older versions (bearing in mind that
the Plug-in requires a 7.x client installation).
Please refer to the IBM support statement entitled "How do I download the
Extended Transactional Client (XA)" at:
http://www-01.ibm.com/support/docview.wss?uid=swg21605388
Figure 1 Transactions
Due to limitations in WebSphere MQ, a transaction can only reference one
WebSphere MQ queue manager. The queue manager and the queues opened
using get and put activities will remain open for the life of the transaction. They
are automatically closed and released when the transaction ends.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Using the Data Conversion Plug-in with WebSphere MQ 7
|
Using the Data Conversion Plug-in with WebSphere MQ
The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ does not
attempt to provide tools for the manipulation of the message body itself. This
requirement is fulfilled by the Plug-in for Data Conversion. Messages can be free
form text (like XML documents) or they can have internal structure. In the case of
most legacy applications, that structure is usually expressed in the form of a
copybook document like this one:
*
*
*
*===========================================================*
* TIBCO Mainframe sample COBOL Copybook
*
*===========================================================*
01
WS-IVP-FIELDS.
05
IVP-ID
05
IVP-DESCR
05
IVP-RESULT
05
IVP-BES-NAME
05
IVP-BES-TRAN-ID
05
IVP-BES-PGM-NAME
05
IVP-USERID
05
IVP-START-TIME
05
IVP-REPLY-TIME
05
IVP-SUBJ-SFX
05
IVP-TYPE
05
IVP-BES
05
IVP-WRITES
05
IVP-BES-TASKNO
05
IVP-BES-DELAY
05
IVP-BTCH-SEQ-NO
05
IVP-START-DATE-CHAR
05
IVP-START-TIME-CHAR
05
IVP-REPLY-DATE-CHAR
05
IVP-REPLY-TIME-CHAR
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
X(8)
X(56)
X(80)
X(8)
X(8)
X(8)
X(8)
X(8)
X(8)
X(30)
X(1)
X(1)
S9(8)
S9(8)
S9(8)
S9(8)
X(16)
X(16)
X(16)
X(16)
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
COMP.
COMP.
COMP.
COMP.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
The Data Conversion Plug-in converts copybooks to XML schemas for use in
other activities. The Data Conversion Plug-in render and parse activities convert
canonical data to memory based formats and vice-versa. If your WebSphere MQ
project converses with an application that uses these formats, simply create Data
Conversion Plug-in activities that represent the message structure for those
applications and pipe the values in and out of message activities to communicate
with them.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
8
| Chapter 2
Working with the Plug-in
Figure 2 Using the Data Conversion Plug-in to Convert Canonical Data
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 9
|
Creating Secure Connections to the Queue Manager
You can create a secure connection between the Plug-in and the WebSphere MQ
queue manager using Transport Layer Security (TLS).
To enable secure connections, you must:
1. Configure the WebSphere MQ queue manager to accept TLS connections, and
create a keystore for the certificates and trusts used by the queue manager.
This step is described in WebSphere MQ Queue Manager Setup.
The WebSphere MQ queue manager configuration is covered extensively in
the IBM documentation. If any of the terms used in this section are unfamiliar,
review the IBM documentation for clarification.
2. Configure TIBCO ActiveMatrix BusinessWorks to connect using TLS. This
step is described in TIBCO ActiveMatrix BusinessWorks Setup on page 15.
Note that there are many variables that control secure connections, and all must
be correctly enabled for TLS to function. If problems occur, it might be difficult to
identify the source. The section Troubleshooting on page 17 lists a few
suggestions to aid in identifying the source of any problems.
The secure connections provided by the plug-in use the cipher suites which are
enabled in the JRE running the Tibco ActiveMatrix BusinessWorks instance. By
default, the Cipher Suite list is quite limited and might not include a match for the
cipher specification specified in the channel definition of the queue manager. If
this is the case and you cannot change the channel, you have the following three
options:
•
Deploy the application on a platform where the IBM JRE is the default. The
IBM JRE supports a much wider range of cipher suites than does the stock
Oracle JRE. AIX and zLinux are two platforms which fit this category.
•
Install the IBM JRE on an Intel based Linux platform and manually adjust the
TRA for the application so that it runs on the IBM JRE.
•
Read and implement the conditions of IBM APAR IV66840. These conditions
involve upgrading the WebSphere MQ client software to the latest available
fixpack and adding the following parameter to the application or the
d e s i g n e r . t r a file:
java.propery.com.ibm.mq.cfg.useIBMCipherMappings=false
Setting this property significantly improves the number of potential cipher
specifications available for use on non-IBM JREs.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
10
| Chapter 2
Working with the Plug-in
WebSphere MQ Queue Manager Setup
To enable the WebSphere MQ queue manager to accept TLS connections, you
must create a keystore for the certificates and trusts used by the queue manager:
These examples use self-signed certificates. Although self-signed certificates are
acceptable in a design environment, they cannot be used in production.
•
Task A, Create IBM keystores for the queue manager and client
•
Task B, Configure the queue manager to use generated keystore
•
Task C, Review the Personal Certificate name using the IBM Key Management
tool
•
Task D, Create a TLS connection for the queue manager
•
Task E, Verify that all SSL files can be read by the mqm group
Task A Create 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's s a m p l e s directory. This script can be used to create keystores for
the queue manager and client. The script is annotated, and is intended to be used
as template to aid you in the creation of your own scripts.
Use this script to assist in the creation of TLS connections in an evaluation or
development environment only. Because all the certificates created by the script
are self-signed, they are inappropriate for production use.
Subsequent steps in this sample setup process rely on certificates generated using
this script.
Versions of the script are available for UNIX and Windows. The scripts are:
UNIX
Windows
TIBCO_HOME/ b w / p l u g i n s / m q / s a m p l e s / c r e a t e Q u e u e M a n a g e r K e y s t o r e . s h
TIBCO_HOME\ b w \ p l u g i n s \ m q \ s a m p l e s \ s s l c e r t . b a t
The objective of each script is to produce two IBM CMS type keystores, each
containing an identity and the other's signing CA certificate. That way, a TLS
connection can be instantiated using one keystore at each end. For example, on a
UNIX system running the command:
createQueueManagerKeystore.sh
keystordir qm-name keystore-password
where:
keystoredir is the directory in which to create the keystores. This can be a
working directory or the SSL directory in the queue managers data directory,
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 11
|
so long as the queue manager's keystore is eventually 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 must use lower case characters only.
keystore-password is the password used to secure the keystore.
Running this script generates a number of files, most importantly:
— qm-name. s t h is the stash file for the queue managers key store.
— qm-name. k d b is the IBM CMS format keystore for the queue manager.
—
c l i e n t . k d b is the IBM CMS format keystore to be used to make a Java
keystore for the client.
You might either customize the scripts to produce keystores that suit your
environment's standards, or enter the commands discretely to accomplish the
same thing.
Example
The following steps describe the configuration of the queue manager to use
certificates generated by the script using the command:
createQueueManagerKeystore.sh/var/mqm/qmgrs/qmwn/ssl qmwn password
Task B Configure the queue manager to use generated keystore
After the script has created the keystores, you must configure the queue manager
to use the generated keystore.
In this example, the keystore is named q m w n . k d b and the queue manger name is
q m w n . To configure the queue manager, set its SSL Key Repository parameter to
this file without the suffix.
The keystore created with the previous Example is
/ v a r / m q m / q m g r s / q m w n / s s l / q m w n . k d b . The value for the corresponding key
database for the queue manager would be / v a r / m q m / q m g r s / q m w n / s s l / q m w n .
Figure 3 shows an example of the IBM WebSphere MQ Explorer queue manager
properties for SSL.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
12
| Chapter 2
Working with the Plug-in
Figure 3 WebSphere MQ
Task C Review the Personal Certificate name using the IBM Key
Management tool
Open the keystore using the IBM Key Management tool. This tool is normally
started by the script in the m q m / b i n / s t r m q i k m directory, and the executable is
called i K e y M a n .
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 13
|
Figure 4 shows the keystore created in Task A. Note the name of the personal
certificate is i b m w e b s p h e r e m q q m w n . This special alias is composed of the tag
i b m w e b s p h e r e m q with the name of the queue manager concatenated onto it. In
this example, the queue manger name is q m w n .
The Personal Certificate name must use all lower case characters. If your queue
manager name contains upper case characters, rename this alias so that all
characters are in lower case. If this alias is not correct, the queue manager will not
be able to open the keystore.
Note that the IBM Key Management tool (i K e y M a n ) does not let you simply
change an uppercase character to a lowercase character. To retain the same name,
you will have to use an intermediate name for the rename function to work.
Figure 4 IBM Key Management Tool: iKeyMan
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
14
| Chapter 2
Working with the Plug-in
You can also review the CA certificate that was 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 under the Key database content heading.
Task D Create a TLS connection for the queue manager
Using the IBM WebSphere MQ Explorer, create a server connection channel for
the new queue manager and set its SSL properties so that client authorization is
enabled (if desired) and a cipher suite is selected. For example,
TRIPLE_DES_SHA_US is a specification that must have a matching cipher in
BusinessWorks.
Note that the terms SSL and TLS are used interchangeably in the IBM
documentation, and most of the parameter settings for TLS are labeled SSL.
Insofar as this document is concerned, TLS is functionally equivalent to SSL V3.
Figure 5 shows the SSL setting configured using the IBM WebSphere MQ Explorer
tool.
Figure 5 SSL Cipher Suite Selection
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 15
|
Task E 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 S S L
property of the queue manager are readable by the m q m group.
(This is the security group m q m that was created during the installation of
WebSphere MQ on the platform.) If they are not, adjust their access properties or
the queue manager will not be able to read them.
Key Repository
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.
TIBCO ActiveMatrix BusinessWorks Setup
Once the queue manager is set up, you can configure the BusinessWorks to use
the secure channel:
1. In TIBCO Designer, open an existing project or create a new one.
2. Create a new WebSphere Plug-in for MQ Connection resource.
3. In the Configuration Tab, set up the normal TCP/IP parameters for a remote
connection, and check the TLS Enabled option.
4. In the Pooling Tab, enable pooling and set reasonable parameters for the pool.
Because TLS connections are more resource intensive to establish, there is
even more reason to pool these connections.
5. Open the TLS panel:
Figure 6 TLS Panel
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
16
| Chapter 2
Working with the Plug-in
As you can see in the previous figure, the connection is configured to use a
Java keystore file for its credentials. This is the easiest option to configure for
use with the IBM Key Manager, and is used in this example. However, you
can alternately use an identity, in p k c s 1 2 format, in combination with a
directory of trusted certificates.
6. Start the IBM Key Manager tool using the s t r m q i k m program. This program is
located in the m q m / b i n directory in the WebSphere MQ server installation.
7. Using the IBM Key Manager, open the client keystore created by the script
during the WebSphere MQ Queue Manager Setup.
8. Create a Java keystore from the contents of the IBM keystore:
a. Select the client identity alias and select Save As from the File menu.
b. In the Save As dialog, change the keystore type to JKS and enter a new
name for the client keystore. This will be the file 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.
9. In TIBCO Designer, navigate to the TLS Tab.
10. In the Keystore File field, select the Java keystore just created, and enter the
password used to secure it in the Password field.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 17
|
11. In the Cipher Suite field, select the cipher
S S L _ R S A _ W I T H _ 3 D E S _ E D E _ C B C _ S H A . This must be the first cipher in the list,
and corresponds with the T R I P P L E _ D E S _ S H A _ U S cipher chosen for the queue
manager's channel.
12. Test the connection by clicking the Test button at the bottom-left of the
Designer panel.
This test attempts to connect with the queue manager using the parameters
specified. If the cipher does not match, the test probes for a correct match from
all of the ciphers that the current JRE supports. If a cipher is found, the test
prints the cipher in the informational dialog that displays output from the test
button. That cipher name will also be printed in the Designer log, from which
it can be easily copied.
Troubleshooting
•
Because of the number of vulnerabilities in the SSL protocol, TIBCO has
disabled the SSL protocol bundled with the JRE in the most recent run times.
To determine if this is the case for the JRE running your application, examine
the j a v a . s e c u r i t y file in the
T I B C O _ H O M E / t i b c o j r e 6 4 / v e r s i o n / l i b / s e c u r i t y directory for a line
(usually at the bottom) like:
jdk.tls.disabledAlgorithms=SSLv3
If the preceding property is present, the SSLv3 protocol has been disabled and
all the SSLv3-specific ciphers have been disabled. This reduces the already
short list of cipher suites specifications available in your JRE, which are
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
18
| Chapter 2
Working with the Plug-in
compatible with those of the queue manager. To address this issue, see IBM
APAR IV66840 that documents changes made to the client to enable a wider
range of cipher suites specifications on non-IBM JREs.
In brief:
If you provide the parameter
j a v a . p r o p e r y . c o m . i b m . m q . c f g . u s e I B M C i p h e r M a p p i n g s = f a l s e in the tra
for your application (or designer), this option enables a number of cipher
specs that are not normally available on non-IBM JREs. This feature is only
available in the most recent WebSphere MQ fixpacks, so you might have to
apply maintenance to obtain this feature.
•
Review the TIBCO Designer log file. If an error internal to the Plug-in or
Designer occurs, look in the Designer log for more information.
•
Disable client authentication. This means that the queue manager will not
check that it trusts the signer of the plug-in's certificate. If it works with client
authentication disabled but not with it enabled, then the two parties do not
have all the signing CA certificates in place.
•
Enable JSSE debug messages in TIBCO Designer to display messages related
to creating the TLS connection:
java.property.javax.net.debug ssl
This option enables tracing of all access to certificates as well as the handshake
process itself.
•
Check the log files of the queue manager. These files are in the work directory
under "errors" of the queue manager. For the previous queue manager, 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 to
access 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
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Creating Secure Connections to the Queue Manager 19
|
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 is
shown as '????'. The channel did not start.
ACTION:
Ensure that the key repository variable is set to where the key database file
is. Ensure that a password stash file has been associated with the key database
file in the same directory, and that the userid under which MQ is running has
read access to both files. If both are already present and readable in the
correct 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 SSL directory. This happened because the default file creation mask
does not allow group read.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
20
| Chapter 2
Working with the Plug-in
Using the Plug-in with Large Messages
WebSphere MQ cannot accept an arbitrarily large message. It has restrictions
based on the size of the buffers in the queue manager and its various channels.
There are two techniques to deal with this: Message Groups and Segmented
Messages. Both mechanisms use the concept of a "virtual message" composed of
many physical member messages all uniquely identified by the same group ID.
Segmented messages are not supported on z/OS.
Logical and Segmented Messages
The Get, Put and Listener activities support logical messages and the
MultiMessage tab is present on these activities.
A Put operation can send:
•
A single simple message by selecting None from the Multi Message Support
list and None from the Segmentation Support list.
•
A single segmented message by selecting None from the Multi Message
Support list and any choice from the Segmentation Support list.
•
A single segment of a segmented message by selecting CustomSegmented
from the Multi Message Support list. This must be used in a loop to send
each segment separately and is intended to allow the activity to send a
segmented message which will not fit into memory.
•
A logical message by selecting BatchGroup from the Multi Message Support
list and any choice from the Segmentation Support list. Each node provided
on the input schema will become a member of the logical message placed on
the queue.
•
A logical message can be sent, one message at a time, using a loop and
selecting CustomGroup from the Multi Message Support list.
A Get operation can retrieve:
•
A single simple message by selecting None from the Multi Message Support
list. If the message is segmented it will be automatically retrieved as a single
message.
•
A single message segment by selecting CustomSegmented from the Multi
Message Support list. This makes it possible to process a segmented message
which does not fit into memory.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Using the Plug-in with Large Messages 21
|
•
A logical message by selecting BatchGroup from the Multi Message Support
list. The output will contain a node for each message in the logical message.
•
A logical message can be retrieved, one message at a time, using a loop and
selecting CustomGroup from the Multi Message Support list.
See WebSphere MQ Palette for the description of each individual field.
When using logical messages on z/OS, your queue definition extended property
I n d e x T y p e must be set to g r o u p - i d . If the queue is not indexed by group ID, the
activity resorts to using non-ordered gets which might or may not process the
messages in the order that they were created.
Using Loops to Send and Receive Logical Messages
The Put and Get activities can be configured to process logical and segmented
messages in loops by selecting CustomGroup and CustomSegmented from the
Multi Message Support list. In this configuration each activity is intended to
process a single message, but the message and destination are cached within the
loop. Each Put or Get operation uses this stored context to ensure that the
operation adheres to the semantics of the overall logical message.
The Put activity exposes a boolean field in its input schema called
l a s t M e s s a g e I n G r o u p or l a s t S e g m e n t . Setting this field to t r u e causes that
instance of the put to terminate the logical or segmented message.
The Get activity provides an output field in the m q P r o p e r t i e s node called
g r o u p S t a t u s which contains: M S G _ I N _ G R O U P, M S G _ N O T _ I N _ G R O U P,
M S G _ L A S T _ I N _ G R O U P, M S G _ S E G M E N T or M S G _ L A S T _ S E G M E N T. The Get activity, when
used in CustomGroup or CustomSegmented mode also has a boolean value in
the output schema called l a s t M e s s a g e I n G r o u p which can be used to detect the
end of a logical group. It is up to the application designer to correctly interpret
these flags to create and consume logical messages.
The Get activity has a check box called All Messages Available.
When the All Messages Available check box is selected, the Get operation waits
for the entire logical message to be present on the queue before processing the
first member of that logical messages. This flag is turned off "under the covers" for
the rest of the logical group.
When the All Messages Available check box is cleared, messages are processed
as soon as they arrive, making it possible to process a logical message without it
having ever existed in its entirety on the queue. This is handy for extremely large
logical messages linking two batch processes.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
22
| Chapter 2
Working with the Plug-in
In CustomGroup and CustomSegmented modes the activities must be used
within a loop. Each successive call to the activity uses the same connection and
destination object opened by the first iteration. The destination and queue
manager connection are closed at the end of the process, not the end of the group.
Messages are committed at the end of each activity's execution not at the end of
the loop or process.
You can commit an entire logical message at one time using a loop. The loop must
be configured in one of the following ways:
•
The entire loop is contained in an XA transaction.
•
The activities inside the loop use the Commit Via SyncPoint flag, and a
SyncPoint activity is executed immediately after the loop exits.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Using Message Filters 23
|
Using Message Filters
When reading messages from WebSphere MQ, you can limit which messages are
read using message filters. You can read only messages that match a specified
correlation ID, message ID or group ID by using the Get and Listener Plug-in
activities.
Assigning IDs
Specifying Filters
These values are assigned to the WebSphere MQ message when it is created. You
can specify the desired ID using the mqproperties field on the put activity Input
tab. However, most applications let the queue manager automatically generate an
identifier.
Filters can be set for Get and Listener activities.
•
For Get activities, the filter can be set using the c o r r e l a t i o n I d , m e s s a g e I d
and g r o u p I d elements of the Input tab. These fields are grouped under the
mqproperties field heading.
•
For Listener activities, the filter is set using the Correlation Id, Message Id and
Group Id fields in the Advanced tab and can be encoded as t e x t , b a s e 6 4 , or
hexbin.
Filter Scenario: Request-Reply
One common use for filters is in a request-reply interaction. In this scenario, a
message publisher puts a Request message on the queue that is handled by a
service application. The Request message specifies a Reply To Queue name,
indicating the queue where the requestor will look for the reply message.
Because the same Reply to Queue is often used by many message requestors, the
message requester can use the correlation ID generated by the Put activity to
identify those reply messages that are sent in response to its own request.
To enable this functionality, map the c o r r e l a t i o n I d from the Output tab of the
Put activity to the c o r r e l a t i o n I d field in the Input tab of the Get activity that
will read the reply message.
It is the responsibility of the application replying to the request to set the correct
correlation ID in the reply message. The correlation ID is present in the request
message header.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
24
| Chapter 2
Working with the Plug-in
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 Reports field on
the Input tab, the queue manager puts a report message onto the specified Report
Reply Queue queue.
Correlation IDs are used to relate the original put message to the report messages.
Using the Pass Correlation ID check box, you choose whether the original
message ID or correlation ID is used for the report message correlation ID.
As in the previous scenario, the process can pass the c o r r e l a t i o n I d shown on
the Output tab of the Put activity to the c o r r e l a t i o n I d field in the Input tab of
Get activity that will read the report messages.
Trace Facilities Available In The Plug-in
If the deployed instance is running with detailed trace on trace records will be
written to the application log when WebSphere MQ API calls are used within the
plug--in. This forms the most basic trace mode available. To enable tracing, use
TIBCO Administrator to specifically turn on the Enable Verbose Tracing in the
Server Settings tab of the application instance configuration.
If greater detail is required, an internal trace can be enabled by inserting this
record in the TRA used to start the application:
java.property.com.ibm.mq.commonservices
/home/tibcobw5/wmqtraceconfig.txt
The trace w m q t r a c e c o n f i g . t x t file can be anywhere on the file system and
conforms to the instructions provided by IBM in the WebSphere MQ
documentation.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
| 25
Chapter 3
WebSphere MQ Palette
This chapter describes the capabilities of the WebSphere MQ palette.
Topics
•
WebSphere MQ Connection Shared Resource, page 26
•
WebSphere MQ Properties Shared Resource, page 33
•
WebSphere MQ Message Body Fields Shared Resource, page 34
•
WebSphere MQ Put Activity, page 36
•
WebSphere MQ Get Activity, page 57
•
WebSphere MQ Listener Activity, page 73
•
WebSphere MQ Publish Activity, page 89
•
WebSphere MQ Subscriber Activity, page 103
•
WebSphere MQ SyncPoint Activity, page 114
•
WebSphere MQ Inquire Activity, page 116
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
26
| Chapter 3
WebSphere MQ Palette
WebSphere MQ Connection Shared Resource
The connection resource contains all the parameters necessary to connect to a
queue manager. It supports these modes:
•
Local A local connection uses the C language libraries and JNI to locate and
connect to queue managers on the local machine.
— Local connections are not eligible for XA 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 on
any queue manager on the network or the local machine.
— Remote connections support XA 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 supported method to connect to a
multi-instance queue manager.
— Client connection table connections support XA transactions. However,
note that transactions are 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 they are to be
used.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Connection Shared Resource 27
|
Configuration Tab
Table 3 lists and describes the fields in the Configuration tab.
Table 3 Fields in the Configuration Tab: WMQ Connection Resource
Field
Global
Variable
Description
Name
N
The name of the Region Resource.
Default: W e b S p h e r e
MQ Connection
Description
N
Description of the resource.
Binding
N
Local, Remote, or Client Connection Table. See WebSphere
MQ Connection Shared Resource for more information.
Client Connection
Table URL
Y
When using a Client Connection Table, enter the URL of the
CCDT file that was exported by the server to which you are
trying to connect.
This file must be located in the queue manager home
directory in the @ i p c c / A M Q C L C H L . T A B file. You can either
reference this file from this location, or copy it to a location
where it is accessible to the running BusinessWorks
instance.
This URL supports the HTTP, FTP and FILE protocols.
Hostname
Y
For remote connections, provide the name of the machine
hosting the queue manager.
Default: l o c a l h o s t
This field is only available for remote bindings.
Port
Y
For remote connections, provide the TCP port number on
which the queue manager is listening.
Default: 1 4 1 4
Range: 1 - 6 5 5 3 5
This field is only available for remote bindings.
User Name
Y
For secure remote connections, the user name which will be
used to create the connection. If a user name is not provided,
the credentials of the current security context is used.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
28
| Chapter 3
WebSphere MQ Palette
Table 3 Fields in the Configuration Tab: WMQ Connection Resource (Cont’d)
Field
Global
Variable
Password
Y
For remote connections, the password associated with the
specified user name.
Queue Manager Name
Y
For Local and CCT connections, the name of the queue
manager to connect to. If not specified, the default queue
manager is selected.
Server Channel Name
Y
For remote connections, the server channel to connect to.
Queue managers can use multiple server channels if
required, for example to support TLS and plain connections.
TLS Enabled
Y
When selected, the TLS tab is enabled. This option enables
the use of Transport Layer Security for the connection
resource. Relevant parameters are configured in the TLS
Tab. This option is only enabled for remote connections.
Header Compression
N
Select the check box to use RLE header compression. For
compression features to work the server connection channel
to which the plug-in connects must be configured to support
compression.
Description
Note: This feature is not relevant and not used for locally
bound connections.
Message Compression
N
Select the level of message body compression desired.
See the IBM WebSphere MQ documentation for more
information about the compression algorithms used. For
compression features to work the server connection channel
to which the plug-in connects must be configured to support
compression.
Note: That this feature is not relevant and not used for
locally bound connections.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Connection Shared Resource 29
|
Pooling Tab
Table 4 lists and describes the fields in the Pooling tab.
Table 4 Fields in the Pooling Tab: WMQ Connection Resource
Field
Global
Variable
Pooling Enabled
N
Description
When this check box is selected, pooling is active for this
connection.
When sizing the pool, note that if an activity attempts to
acquire a connection and the pool is full, that is, all
connections are in use and the pool cannot make any more
connections, the activity fails. So it is better to allocate a few
more connections than your application requires.
Note that as of version 7.6 of this plug-in, the pool no longer
uses the WebSphere MQ M q S i m p l e C o n n e c t i o n M a n a g e r.
The pool now uses its own pool of hot standby connections.
This improves latency for normally low latency activities,
such as the Put activity.
If pooling is not active, a new non-pooled connection is
acquired and released for each activity.
Max Connections
Y
Determines the maximum number of connections allowed
in the pool. When this limit is reached, subsequent started
activities will fail with a max connection error code, unless
some connections are available before starting.
Maximum Unused
Y
Determines the maximum number of idle connections
allowed in the pool. When the number of unused
connections reaches this number, the idle connections are
disconnected and closed, freeing resources on the server.
Amounts over the Max Connections value are ignored.
Timeout
Y
The length of time an inactive connection is kept in the
pool. A connection that has remained unused for this
number of milliseconds are closed and removed from the
pool, freeing resources on the server.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
30
| Chapter 3
WebSphere MQ Palette
TLS Tab
The TLS tab contains the parameters required to make a secure connection to the
queue manager using the Transport Layer Security protocol. Before TLS can be
used, the queue manager and server channel used by clients must be configured.
For more information, see Creating Secure Connections to the Queue Manager on
page 9.
Note that the TLS tab is enabled only if the Binding type is Remote or Client
Connection Table, and the TLS Enabled check box is selected in the
Configuration tab.
If the JRE running the BW application is the standard Oracle Java runtime, the
number of cipher suites supported is quite limited. If none of the cipher suites
available to the JRE can be used to connect to the queue manager, the
configuration of the queue manager cannot be relaxed to accomodate the JRE.
There are three options:
•
See IBM APAR IV66840 regarding improving cipher suite selection on
non-IBM JREs. This is described in more detail in Creating Secure Connections
to the Queue Manager, page 9.
•
Relocate the application to a platform where the standard JRE is the IBM JRE.
Those platforms are, at the moment, AIX and zLinux.
•
Relocate the application to a Linux based or Intel x86 based machine, install
the IBM JRE on that machine and configure the application to be run on the
IBM JRE. The user must manage this configuration as there is no way to
automatically select the JRE used in a particular deployment.
The IBM JSSE implementation supports a more extensive cipher suite set than
does the standard JRE.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Connection Shared Resource 31
|
Table 5 lists and describes the fields in the TLS tab.
Table 5 Fields in the TLS Tab: WMQ Connection Resource (Sheet 1 of 2)
Field
Global
Variable
Description
Repository Type
N
Specifies the mechanism used to store the identity and trust
information for the connection. Options are:
•
Keystore The TLS certificate and trusted signer
certificates are expected to be in a Java keystore file.
•
Files The TLS certificate is expected to be in a p k c s 1 2
file and the trusted certificates are located in a directory
by themselves.
Note that if client authorization is required on the channel to
which this plug-in connects, the CA which signed the
certificate of the plug-in must be imported into the keystore
of the server. See the Creating Secure Connections to the
Queue Manager on page 9 section for more information.
Keystore File
Y
If the Repository Type is Keystore, this field contains the
name of a Java keystore file containing the client certificate
and its signer certificate(s). If client authentication is enabled
on the server-connection channel, then the CA which signed
the queue manager's certificate must be imported here to
create a trust relationship.
Client Identity File
Y
If the Repository Type is Files, this field that contains the
name of a p k c s 1 2 -formatted certificate with the private key
included. This file is secured with a password.
p k c s 1 2 -formatted
certificates can be suffixed p k c s 1 2 or p 1 2 .
Trusted Cert Dir
Y
If the Repository Type is Files, this field contains the
directory where all the certificates necessary to trust the
server's certificate are located. These certificates can be
PEM- or DER-encoded.
Password
Y
If the Repository Type is Keystore, this field contains the
password used to secure the Java keystore.
If the Repository Type is Files, this field contains the
password used to secure the identity file.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
32
| Chapter 3
WebSphere MQ Palette
Table 5 Fields in the TLS Tab: WMQ Connection Resource (Sheet 2 of 2)
Field
Global
Variable
Cipher Suite
Y
Description
Contains the cipher specification which matches the one
selected in the queue manager's server-channel SSL
parameters.
Note: If all of the other required fields in this connection
resource are correct but the cipher specification is unknown,
the Test button probes for an acceptable cipher specification
and reports it in the pop-up as well as printing it in the log.
Note: If a client connection table is in use for this connection,
the cipher suite is encoded in the table and this value is
ignored.
Enable FIPS
N
When selected, Federal Information Processing Standards
(FIPS) are enabled on platforms where the Java runtime
environment supports it.
For a FIPS connection to be possible, both the queue
manager and the Java runtime environment in which the
Plug-in runs must be configured to be FIPS capable. Consult
the FIPS documentation to determine which key lengths,
algorithms and ciphers are appropriate for the requirements
of your installation.
Embed TLS Parameters
N
When selected, the keystore represented by the parameters
on this panel is stored in the application's configuration
data.
This allows the configuration to be deployed to platforms
where these files do not exist. The certificates chosen must
be valid for all systems to which this application is
deployed. If that is not the case, do not select this option and
ensure that the files specified are present on all target
environments. Global variables might be used to facilitate
the necessary flexibility here.
Note: If the parameters here are of the Files type and the
Embed TLS Parameters check box is selected, an internally
represented Java keystore will be created from the files and
stored within the project's configuration data.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Properties Shared Resource 33
|
WebSphere MQ Properties Shared Resource
The application properties shared resource provides a mechanism for creating
and using application properties on MQ messages. The appearance and function
of the resource is identical to the one provided for JMS Properties. The following
subset of JMS property types is supported:
•
boolean
•
byte
•
bytes
•
short
•
int
•
long
•
float
•
double
•
string
The node represented by this Application Properties resource will be present on
the input schema of Put activities and in the output schema of Get and Listener
activities. Fields that contain values are mapped onto sent messages. When
processing a received message, all fields in the schema that have corresponding
named counterparts in the message are mapped onto the output schema. If a type
mismatch occurs when mapping fields onto the output schema, the field is
skipped.
If 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.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
34
| Chapter 3
WebSphere MQ Palette
WebSphere MQ Message Body Fields Shared Resource
This schema can be created by adding a shared resource of the type "WMQ
Message Fields" to a folder and then selecting it from the Message Content Type
list of the Configuration tab of an activity. The schema is only used when Schema
is selected from the Message Content Type list. The dialog for creating message
body schemas contains a field name and field type column. The field name only
has to be unique to the schema to facilitate mapping requirements and the type
can be any of the supported types. If the type is String and the schema is intended
to be use by a Get activity, then the string length must be known. In this case the
field name must be suffixed with an underscore character and the numeric length
of the string. All other types are of determinate lengths.
Table 6 lists the types and the methods used to access them.
Table 6 Types and Methods
Type
Put API
Get API
boolean
writeBoolean
readBoolean
byte
writeByte
readByte
short
writeShort
readShort
int
writeInt
readInt
long
writeLong
readLong
float
writeFloat
readFloat
double
writeDouble
readDouble
string
writeString
readStringOfCharLength (name encodes length)
line
writeString
readLine
utf
writeUTF
readUTF
char
writeChar
readChar
decimal2
writeDecimal2
readDecimal2
decimal4
writeDecimal4
readDecimal4
decimal8
writeDecimal8
readDecimal8
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Message Body Fields Shared Resource 35
|
When writing and reading these values, the c h a r a c t e r S e t element from the
message is used to encode and decode string values and the e n c o d i n g element is
use to encode and decode numeric values.
This schema is represented on the input and output of the activity such that each
field is a node with a child node describing the field type. Map the intended
values to this child node.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
36
| Chapter 3
WebSphere MQ Palette
WebSphere MQ Put Activity
The Put activity places a message on the configured queue. The activity is capable
of sending any of the four message types to permanent or dynamic queues. The
capabilities of the activity are determined by the configuration, with some
runtime behaviors controlled by the input schema.
The type of message being sent may determine what fields are applicable for the
put operation. The four message types are:
•
Datagram Basic message.
•
Request A message for which the sending application expects a response and
for which a reply to queue is required.
•
Reply A message sent in response to received Request type message. Usually
the destination for this 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 by queue managers. However, it is possible for applications to
do so using this message type.
Messages can be sent to predefined queues or dynamic queues. If the destination
or the reply to queue is dynamic, you must specify a properly configured model
queue. The queue manager constructs the dynamic queue based on that template.
The name of a unique dynamic queue can be generated if the queue name
provided ends with an asterisk (*). If a Request message is sent to a queue with a
dynamic reply destination, the Put activity will create the dynamic reply queue
based on the configuration of the put activity and keep it open until the end of the
process. Therefore the dynamic reply destination will be available to the receiving
application in the message's reply-to destination for as long as the process is
active. The name can be taken from the d e s t i n a t i o n element in the Output tab.
The Put activity supports options which request that the queue manager send
confirmation reports when the message arrives or is delivered, however reports
are delivered to the reply-to destination and must be used carefully when
combined with a request type message.
Test Button
Each activity includes a Test button. The Test button for the Put activity attempts
to validate the selections for queue manager and queue by opening the queue
manager and instantiating the queue object. For dynamic queues, only the
presence of the model is verified. For predefined queues which were successfully
opened, a status box is presented.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 37
|
For example:
Configuration Tab
Table 7 lists and describes the fields in the Configuration tab.
Table 7 Fields in the Configuration Tab: WebSphere MQ Put Activity (Sheet 1 of 3)
Field
Global
Variable
Description
Name
N
The name of the Put activity.
Default: W e b S p h e r e
MQ Put Activity
Description
N
Optional free-form description.
Connection Resource
Y
Choose the connection resource which associates this
activity with the queue manager that has access to the
desired queue.
Queue Name
Y
The name of the queue onto which the message will be
placed. Queue names can be chosen by clicking Choose
Queue. If the queue is to be created dynamically, enter the
name of the dynamic queue. The name must follow the
MQSeries rules for dynamic queue names.
If the queue name has been dynamically mapped using the
input schema's destination field, this field is not required.
However, note that the Test button cannot verify
dynamically mapped queue names.
Dynamic Queue
N
A flag that enables the creation of a dynamic queue. When
selected, the Model Queue Name field is enabled. Dynamic
queues are ones which are created as required and disappear
when the lifespan dictated by the model is reached.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
38
| Chapter 3
WebSphere MQ Palette
Table 7 Fields in the Configuration Tab: WebSphere MQ Put Activity (Sheet 2 of 3)
Field
Global
Variable
Description
Model Queue Name
Y
Select the Dynamic Queue check box to enable this field.
Enter the model queue name, or select a name by clicking
the Choose Queue button. The queue manager uses the
specified model queue when creating this dynamic queue.
Message Type
N
Select the type of message that is to be sent:
•
Datagram
•
Request
•
Reply
•
Report
If a Request message is selected, the Reply To Queue field is
enabled. All other message types enable the Reports field.
Reply To Queue
Y
This field is enabled for Request message types only.
The queue name which will be placed into the message
header's reply to queue field. This queue does not have to
exist and is not checked, but can be chosen using the Choose
Queue button on the right side of the field.
Dynamic Reply Queue
N
A flag that enables the creation of a dynamic queue. When
selected, the Model Queue Name field is enabled, and the
reply queue will be dynamically created based on the model
in the Model Queue Name field. If a dynamic reply queue is
specified, it will be created during the Put operation so that
it is available to the responding application.
This field is available only for the Request message type.
Model Queue Name
Y
Specify the model after which the reply queue is to be
patterned. It can be selected from models using the Choose
Queue button to the right.
This field is only available if the Dynamic Reply Queue
check box is selected.
Fail If Quiescing
N
Select the Fail If Quiescing check box for destinations and
queues opened on behalf of this activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 39
|
Table 7 Fields in the Configuration Tab: WebSphere MQ Put Activity (Sheet 3 of 3)
Field
Global
Variable
Message Content Type
N
Description
Choose the way that the message body will be represented
on the input schema.
•
Binary The message is an array of bytes suitable for use
by the Data Conversion Palette activities.
•
Text The message is a string. The message will be
encoded using the c h a r a c t e r S e t for the message, or 819
is none is provided.
Charset 819 is the Java API default.
•
Schema The message will be formatted according to the
schema provided in the Message Body Fields field.
Input values for this schema will appear in the input
editor.
Message Body Fields
Y
Provide the schema to be used in the Input tab, and at run
time to encode the contents of this message.
Application Properties
Y
Select the Application Properties resource to be included as
part of this message. Application properties are similar to
regular message header fields except that the name and type
of the fields can be determined by a predefined schema.
To use custom application properties, create an instance of
the WebSphere MQ Application Properties sharable resource
and map it to this field.
Advanced Tab
Table 8 covers the fields in the Advanced tab.
Table 8 Fields in the Advanced Tab: WebSphere MQ Put Activity (Sheet 1 of 5)
Field
Global
Variable
Description
Message Priority
Y
Set the priority of the message as it is to be retrieved by the
queue manager. The values range from 0 to 9 .
If not specified, the default is the destination queue's default
priority.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
40
| Chapter 3
WebSphere MQ Palette
Table 8 Fields in the Advanced Tab: WebSphere MQ Put Activity (Sheet 2 of 5)
Field
Global
Variable
Message Expiration
Y
Description
The time, in tenths of a second, that the message will persist
on the queue before being deleted by the queue manager. The
default, 0 , is to persist forever.
Values range from 0 to 2 1 4 7 4 8 3 6 4 7 .
The default is 0 , which means the message never expires.
Generate Correlation
Id
N
Select this check box to cause the queue manager to generate
a unique correlation identifier for the message when it is sent.
This means that the message identifier, which is always
generated, is copied to the correlation identifier field.
Note that if this option is enabled, the queue manager
overlays any correlation identifier that is mapped on the
input schema.
Load Balance
N
When the Load Balance check box is selected, the put
operations are load balanced among the members in a
cluster-enabled queue.
For more information about load balancing, see WebSphere
MQ Clustering-Workload balancing on the IBM website.
Persistence
N
Determines whether messages on the queue manager persist
across restarts. Select one of the following settings:
•
Persistent It ensures that the message persists if the
queue manager fails or restarts.
•
Not Persistent It discards the message after a restart.
•
Persist as queue def It uses the persistence level defined
in the queue definition.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 41
|
Table 8 Fields in the Advanced Tab: WebSphere MQ Put Activity (Sheet 3 of 5)
Field
Global
Variable
Set Context Info
N
Description
Select the level of authorization this application was given by
the queue manager.
The two authorizations (Identity Context and All Context)
are selectable and are used to control which fields are
available on the input schema.
Note: Selecting a context option for which your userid is not
authorized is a very common cause for authorization failures.
It is best practice to select the default authorization, unless
the application requires access to the extra fields enabled by
these options.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
42
| Chapter 3
WebSphere MQ Palette
Table 8 Fields in the Advanced Tab: WebSphere MQ Put Activity (Sheet 4 of 5)
Field
Global
Variable
Reports
N
Description
Several kinds of report message can be triggered by a
message's arrival a a particular point in the WebSphere MQ
system. Select the type of report message and event trigger
using the combination box.
Events that can trigger a report are:
•
Confirm on arrival The report is sent when the message
arrives at the destination queue.
•
Confirm on delivery The report is sent when the message
has been removed from the destination queue by an
application.
•
Exception The report is sent when the message
encounters an error while being routed through the
messaging system. For instance, if the message was
destined for a remote queue but the queue does not exist
on the remote queue manager.
•
Expiry The report is sent when the message is removed
from the queue because its expiry time has arrived.
Report types are:
•
None The report is not enabled.
•
With No Data The body of the message does not
accompany the report.
•
With Data The first 100 bytes of the message body
accompanies the report.
•
With Full Data The entire body of the message
accompanies the report.
Reports are delivered to the reply to queue specified in the
Report Reply Queue field. Because this field maps to the
message's r e p l y T o Q u e u e N a m e field, reports are mutually
exclusive with the Request type messages. That is, if the
message type is Request, a report confirmation is not sent.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 43
|
Table 8 Fields in the Advanced Tab: WebSphere MQ Put Activity (Sheet 5 of 5)
Field
Global
Variable
Report Reply Queue
Y
Enter the name of the queue to which Report messages must
be sent. This queue does not have to exist and is not checked,
but can be chosen using the Choose Queue button on the
right side of the field. The value entered here maps onto the
message's r e p l y T o Q u e u e N a m e field.
Pass Correlation ID
N
Determines the setting for the correlation ID of a report
message.
Asynchronous Put*
N
Description
•
When selected, the correlation ID of the sent message is
copied to the correlation ID field of the report message.
•
When cleared, the message ID of the sent message is
copied into correlation ID field of the report message.
Put the message asynchronously. This operation does not
wait for a response from the queue manager for filling in
many of the fields in the output schema. Message Id and
Correlation Id will be available.
Note that if an error occurs while placing the message in the
queue, it may not cause the activity to fail outright. For that
reason this option must not be selected for reliable
messaging.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
44
| Chapter 3
WebSphere MQ Palette
MultiMessage Tab
Table 9 lists and describes the fields in the MultiMessage tab.
Table 9 Fields in the MultiMessage Tab: WebSphere MQ Put Activity
Field
Global
Variable
Description
Multi Message
Support
N
Select the behavior of this put with respect to multiple
messages:
•
None The activity will provide for a single message on the
input schema and will send only one message. This
behavior is modified by the Segmentation selection. If no
segmentation is desired then no sync-point is used.
•
Batch The activity will configure the input schema to
accept an arbitrary number of input messages. All of these
messages will be sent in a single unit of work (sync-point
implied).
•
BatchGroup The activity configures the input schema to
accept an arbitrary number of input messages. All the
messages configured are sent as a single logical message in
a single unit of work (sync-point implied). Changing the
destination between members of a Logical Grouped
Message result in an incomplete grouped message on all
queues involved. This condition is not detected until
process cleanup. Changing any of the filter fields, while
possible, will most likely result in a corrupt or unusable
message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 45
|
Table 9 Fields in the MultiMessage Tab: WebSphere MQ Put Activity (Cont’d)
Field
Multi Message
Support
Global
Variable
Description
N
•
CustomGroup The activity will configure the input
schema for a single message. The activity is designed to
function within a loop and using it outside of a loop will
not produce a valid logical message. On the first
invocation it will place the first member of a logical
message on the queue. Subsequent invocations will use the
same message and group identifiers to place new members
into the logical message until the l a s t M e s s a g e I n G r o u p
element is set to t r u e , at which point the logical message
will be terminated. Changing the filter or destination fields
between messages belonging to the same logical message
is possible, but will result in an invalid and unusable
logical message.
•
CustomSegmented The activity configures the input
schema for a single message and places a single message
segment into the queue. The activity is designed to
function within a loop and it does not produce a valid
segmented message if used outside of a loop. On the first
invocation, it places the first segment into the queue and
subsequent invocations place the remainder of the
segmented message into the queue. Set the input schema
element l a s t S e g m e n t to t r u e to indicate that the loop is
about to exit and the segmented message is completed.
This mode of operation disables the Segmentation Support
options and is intended to be used to send messages which
are too large to fit into memory. All other modes of
handling segmented messages require that the entire
message be in memory during execution. Members of a
segmented message group must not differ in any way
except for the byte array mapped to the "b y t e s " node.
Changing any other field on the input schema might result
in an invalid or unusable segmented message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
46
| Chapter 3
WebSphere MQ Palette
Table 9 Fields in the MultiMessage Tab: WebSphere MQ Put Activity (Cont’d)
Field
Segmentation
Support
Global
Variable
Description
N
Select the segmentation behavior for the message.
•
None No segmentation will be performed on the message.
If it is too large for the queue manager or the channel, it
will fail.
•
Explicit This option enables the Maximum Segment Size
field. The message will be segmented into chunks of the
specified size. This will be done by sending multiple
messages so a sync-point is implied.
•
QueueManager The M Q M F _ S E G M E N T A T I O N _ A L L O W E D option
will be specified on the put which instructs the queue
manager to segment the message if it will not fit in the
buffers available to either itself, or any channel en-route to
the destination.
•
Both The message will be segmented in the plug-in
according to the Maximum Segment Size field, and the
flag will also be turned on.
This allows the queue manager to re-segment the message
if its segments are too large for any buffer encountered
en-route to the destination.
MQMF_SEGMENTATION_ALLOWED
Maximum Segment
Size
Y
Available when Explicit or Both is selected from the
Segmentation Support list. Enter the maximum segment size
for messages leaving the plugin.
Commit Via
SyncPoint Activity
N
Select this check box to enlist the activity in an MQ unit of
work. Queue operations performed by this activity are not
committed to the queue until a SyncPoint Activity either
commits or backs out of the operation. The process must be
designed so that all activities preceding the SyncPoint Activity
use the same connection resource and all use the sync point
flag. Any activity which uses the same connection
configuration but does not specify the "Commit Via
SyncPoint" option prematurely commits the unit of work.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 47
|
Input Tab
Table 10 lists and describes the fields in the Input tab.
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 1 of 6)
Field
Global
Variable
Batch
N
This node will be present when Batch or BatchGroup is
selected from the Multi Message Support list in the
MultiMessage tab. With it, the I n t e r a c t i o n I n p u t node can
be duplicated up to 100 times to make up a composite batch
for the put operation.
InteractionInput
N
This input schema field is the root node for all the input
provided to the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) that are relevant on input.
Description
•
destination Specify a destination here to override the
queue name from the configuration panels. With it, the
queue can be dynamically specified.
•
destqmgr Destination queue manager name. The name
of the queue manager on which this queue resides. Note
that a transmission queue and a sender channel must be
configured for this queue manager for it to work.
•
correlationId Provide a correlation identifier for this
message by mapping a byte array to this field. The
XPath expression
t i b : s t r i n g - t o - b a s e 6 4 ( " correlationid" ) is sufficient to
populate this field.
•
messageId Specify a message ID. This value overrides
the default value generated by the queue manager. The
rules are the same as for c o r r e l a t i o n I d .
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
48
| Chapter 3
WebSphere MQ Palette
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 2 of 6)
Field
Global
Variable
Description
mqproperties
N
•
groupId Documents the group ID, if any.
•
characterSet Sets the IBM Coded Characterset ID of this
message. Valid values are:
—
8 5 0 —the
commonly used ASCII codeset.
—
8 1 9 —the
ISO standard ASCII codeset.
—
3 7 —the
—
1 2 0 0 —Unicode.
—
1 2 0 8 —UTF-8.
American EBCDIC codeset.
The queue manager may use this value to convert some
or all of the message content depending on the type of
message and options like GMO Convert (available in
the Get activity). The Java API uses this field to interpret
string values from schema based messages.
•
alternateUserId Specify a userid to be used as an
alternate user for this operation only. The user used in
the connection resource must have the Alternate Userid
Authority to use this field.
•
accountingToken Provide a binary (base 64 encoded)
accounting token to be used on host systems to assist in
accounting for resources used by the application.
Only present if Identity Context or All Context is
selected from the Pass Context Info list in the Advanced
tab.
•
applicationIdData Provide a string that can be used on all
end points to identify this application.
Only present if Identity Context or All Context is
selected from the Pass Context Info list in the Advanced
tab.
•
applicationOriginData Provide information related to the
originating application node for this message.
Only present if All Context is selected from the Pass
Context Info list in the Advanced tab.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 49
|
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 3 of 6)
Field
Global
Variable
Description
•
putApplicationType Provide either one of the IBM
documented application type enumerators for this
application or one of your choosing.
Only available when All Context is selected from the
Pass Context Info list in the Advanced tab. See the IBM
WebSphere MQ documentation for the meaning of the
documented application types. These are the
documented enumerations:
MQAT_AIX
MQAT_CICS
MQAT_DOS
MQAT_IMS
MQAT_MVS
MQAT_OS2
MQAT_OS400
MQAT_QMGR
MQAT_UNIX
MQAT_WINDOWS
MQAT_JAVA
MQAT_UNKNOWN
MQAT_NO_CONTEXT
MQAT_CICS_VSE
MQAT_VMS
MQAT_GUARDIAN
MQAT_VOS
MQAT_DEFAULT
MQAT_NSK
MQAT_CICS_BRIDGE
MQAT_NOTES_AGENT
MQAT_WINDOWS_NT
MQAT_IMS_BRIDGE
MQAT_XCF
MQAT_NO_CONTEXT
•
putApplicationName Provide information about the
originating application in this field.
Only available when All Context is selected from the
Pass Context Info list in the Advanced tab.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
50
| Chapter 3
WebSphere MQ Palette
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 4 of 6)
Field
Global
Variable
Description
•
userId Provide the userid to be used when authorizing
this message as it traverses the messaging system. For
operations with report options, this field is mandatory. If
a value is not provided here, it is taken from the
connection resource if one is available there, and from
the environment if it is not.
Only present when Identity Context or All Context is
selected from the Pass Context Info list in the Advanced
tab.
•
replyToQueueName Specify the name of an existing
queue that the target application can use as a destination
for its response. This enables the common "request
response" pattern.
•
replyToQmgrName Destination queue manager name.
The name of the queue manager on which this queue
resides. Note that a transmission queue and a sender
channel must be configured for this to work.
•
format Describes the nature of the data in the message. It
defaults to " " , or M Q F M T _ N O N E . A user defined format
can be used to assist the receiving application in
decoding the message, for instance in the selection of a
Data Conversion parse activity for this message type.
•
expiry Indicates the length of time (in tenths of a second)
that the message is kept on the queue before being
deleted. Defaults to - 1 , which means there is no
expiration. This field overrides the configuration value
for expiry if it is mapped.
Permissible Values: A positive integer or - 1
•
priority The priority (0 - 9) of the message. This field
overrides a configuration value for priority if it is
mapped.
•
reportOptionPan Set to t r u e to turn the positive
acknowledgment flag in the r e p o r t field on.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 51
|
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 5 of 6)
Field
Global
Variable
Description
•
reportOptionNan Set to t r u e to turn the negative
acknowledgment flag in the r e p o r t field on.
bytes
N
•
report Reporting options are fully configurable in the
Advanced tab, however any integer entered here will be
logically added with existing ones and set into the
message.
•
encoding The encoding value is described in the
WebSphere MQ API documentation. It is used by
methods that set and get numeric values from the
message. If the message body is described by a schema,
this encoding will be used when setting numeric data
into the message.
Map the main content of the message body here. In general,
this is the output of a Plug-in for Data Conversion render
activity, but could be any array of bytes. If string data is to
be mapped to this field, use the XPath function
t i b : s t r i n g - t o - b a s e 6 4 to convert it to bytes.
This element will be present when Binary is selected from
the Message Content Type list of the Configuration tab.
text
N
This element will be present when Text is selected from the
Message Content Type list of the Configuration tab. The
text mapped to this field will be converted to bytes using the
message's characterSet property.
messageFields
N
This element will be present when Schema is selected from
the Message Content Type list of the Configuration tab.
The contents of the mapped schema will be present in this
node for mapping purposes.
appProperties
N
Contains fields that correspond to the schema as it is defined
in the application properties resource that is mapped to this
activity. Application properties are included in an MQRFH2
header which is dynamically added to the message.
Note that the appProperties field is only present if WMQ
Properties Resource has been configured for the activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
52
| Chapter 3
WebSphere MQ Palette
Table 10 Fields in the Input Tab: WebSphere MQ Put Activity (Sheet 6 of 6)
Field
Global
Variable
dynamicProperties
N
Description
This optional node provides an alternative way to specify
application properties and is patterned after a similar node
on the JMS palette objects.
Each property is specified in its own "property" node and
contains the name, type, and value for the property.
Supported types are: String, Boolean, Byte, Short, Int, Long,
Float, and Double. String is the default value. This node can
be directly mapped between JMS and MQ messages.
lastMessageInGroup
N
This field is present when CustomGroup has been selected
from the Multi Message Support list of the MultiMessage
tab.
When the Put is used in a loop to create a logical message
this field must be mapped to t r u e or f a l s e to indicate last
message by an XPATH expression like:
if ($loopcount=20) then "true" else "false"
which would set the 20th message sent by the loop to the
last message and terminate the logical group.
lastSegment
N
This field is displayed when CustomSegmented is selected
in the Multi Message Support list.
Set this field to t r u e when sending the last segment of a
custom segmented message. Failure to set this flag on the
last segment results in an invalid message group.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 53
|
Output Tab
Table 11 lists and describes the fields in the Output tab.
Table 11 Fields in the Output Tab: WebSphere MQ Put Activity (Sheet 1 of 3)
Field
Global
Variable
Description
Batch
N
This node will be present when Batch or BatchGroup is
selected from the Multi Message Support list of the
MultiMessage tab. For each I n t e r a c t i o n I n p u t node
present in the input schema, an I n t e r a c t i o n O u t p u t node
will be present here under the Batch node.
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on input.
mqproperties
N
•
destination Documents the destination for this
message. If the queue was a dynamic queue, the
generated name is reported here.
•
destqmgr Documents the remote queue manager
specified for the put operation.
•
correlationId Documents the correlation ID, if any.
•
messageId Documents the message ID.
•
groupId Documents the group ID, if any.
•
characterSet Documents the character set used by the
queue manager to process this message. If Schema is
selected from the Message Content Type list, and there
are string fields in the message they will be decoded
using this character set. The same goes for fields in
application properties.
•
alternateUserId Documents this message field as it
exists after the put if it is not null.
•
accountingToken Documents this message field as it
exists after the put if it is not null.
•
applicationIdData Documents this message field as it
exists after the put if it is not null.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
54
| Chapter 3
WebSphere MQ Palette
Table 11 Fields in the Output Tab: WebSphere MQ Put Activity (Sheet 2 of 3)
Field
Global
Variable
Description
•
applicationOriginData Documents this message field as
it exists after the put if it is not null.
•
putApplicationType Documents this message field as it
exists after the put if it is not null.
•
putApplicatinName Documents this message field as it
exists after the put if it is not null.
•
userid Documents the effective user ID used to connect
to the queue manager.
mqproperties
N
•
replyToQueueName Same as input.
•
replyToQmgrName Destination queue manager name.
The name of the queue manager on which this queue
resides. Note that a transmission queue and a sender
channel must be configured for this to work.
•
format The character string placed into the format field
by the sending application. Plug-in applications do not
support modification of this field and for those
applications it will be empty. However, if a custom
application sent the message its contents would be
visible here.
•
expiry Indicates the number of tenths of a second that
the message is kept on the queue before being deleted.
Defaults to - 1 , which means there is no expiration.
•
priority The priority (1-9) with which the message was
sent.
•
reportOptionPan Set to t r u e if the positive
acknowledgment bit of the r e p o r t field is on.
•
reportOptionNan Set to t r u e if the negative
acknowledgment bit of the r e p o r t field is on.
•
report Documents this message field as it exists after
the put.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Put Activity 55
|
Table 11 Fields in the Output Tab: WebSphere MQ Put Activity (Sheet 3 of 3)
Global
Variable
Field
Description
•
encoding Documents this message field as it exists after
the put.
Note that this element will be overridden by 1 if a
resource is selected in the Application Properties field.
•
messagetype Enumerated value of the chosen message
type, where:
mqproperties
N
responsetimemillisec
N
—
8
is Datagram.
—
2
is Reply.
—
4
is Report.
—
1
is Request.
•
backoutCount The number of times this message was
backed out before being committed.
•
feedback For a Report message received by a WMQ
Get or Listener activity, this field defines the nature of
the report. The field is unused with a value of 0 in Put
activities.
•
version Documents the version of the message. This
Plug-in supports type 2 messages only.
•
putDateTime The time that the message was placed
onto the queue
•
groupStatus Indicates whether the message is part of a
logical message group or not. Contains three possible
values: M S G _ I N _ G R O U P, M S G _ N O T _ I N _ G R O U P,
M S G _ L A S T _ I N _ G R O U P.
Indicates, in milliseconds, how long it takes to send the
message.
Error Output Tab
Errors produced by this activity throw an exception of the type B w m q E x c e p t i o n .
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
56
| Chapter 3
WebSphere MQ Palette
Table 12 Field in the Error Output Tab: WebSphere MQ Put Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the
exception that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the m s g
element it is provided here, otherwise this is a copy of m s g .
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 57
|
WebSphere MQ Get Activity
The Get activity retrieves a message from the configured queue. Messages can be
retrieved based on filter criteria specified on 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, then returns whether or not a message was received.
•
Check the queue without a wait interval. The activity checks the queue and
returns immediately, regardless of whether a message was read.
•
Listen indefinitely on the queue. The activity returns a message if one is
available, or waits forever for a message to arrive.
There are several things to be aware of when testing applications in design mode.
Normally the WebSphere MQ get operation is not safely interruptable, however
while using the designer with remote or CCDT type connections such operations
are interrupted and terminated when the application test "stop" button is pressed.
This does not happen in a deployed instance. If the application uses a locally
bound connection the get operation blocks until it times out, or if it is an indefinite
wait, until the designer is shut down. So, depending on the design of the process
being tested, the connection and input counts for resources used by the
application might appear to climb during iterative testing.
Threadpool Size
It is important to consider the impact of the wait interval on ActiveMatrix
BusinessWorks thread resources. If the wait is likely to consume an ActiveMatrix
BusinessWorks worker thread for long enough that the engine performance could
be affected, then use a thread pool for best results. This can be accomplished by
setting the Threadpool Size to a number greater than 0. If you elect to use a thread
pool, ensure that it is large enough to accommodate all potential instances of this
activity. If a thread is not available, an activity waits indefinitely for an available
thread. Because other activities before the Get activity might have acquired
resources such as connections and destinations a long wait for a thread might
have undesirable effects on connection pools and queue manager resources. If
this exposure exists then the process must be flow limited such that the engine
does not create more instances of the process than can be accommodated by
connection pools and queue manager resources.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
58
| Chapter 3
WebSphere MQ Palette
Test Button
The Test button for the Get activity attempts to validate the selections for the
Queue Manager and queue by opening the Queue Manager and instantiating the
queue object. For dynamic queues, only the presence of the model is verified. For
predefined queues which were successfully opened, a status box is presented. If
the queue is defined as a Cluster Queue, the Test button also indicates the
following case.
For example:
The Test button for the Get activity does not know whether the queue defined as a
Cluster Queue actually exists on the queue manager to which it is connected,
therefore, when running the process, the M Q R C _ U N K N O W N _ O B J E C T _ N A M E error
messages appear when the queue is actually hosted by a remote member of the
cluster. To use the Get activity in the Queue Manager Cluster, it is necessary to
connect to the Queue Manager that hosts the queue.
Configuration Tab
Table 13 lists and describes the fields in the Configuration tab.
Table 13 Fields in the Configuration Tab: WebSphere MQ Get Activity (Sheet 1 of 5)
Field
Global
Variable
Description
Name
N
The name of the Get activity.
Default: W e b S p h e r e
MQ Get Activity
Description
N
Optional free-form description.
Connection Resource
Y
Choose the connection resource which connects this
activity with the queue manager that has access to the
desired queue.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 59
|
Table 13 Fields in the Configuration Tab: WebSphere MQ Get Activity (Sheet 2 of 5)
Field
Global
Variable
Threadpool Size
Y
Description
Because gets necessarily block for long periods of time, it is
important not to occupy worker threads for this activity.
Enter the number of threads that this deployed instance
must dedicate to the named activity. Note that the activity
will wait for an available thread if one is not open. Because
waits for this type of activity can be long to indefinite, it is
important to size this pool so that each activity can obtain a
thread when it starts. It might be necessary to flow limit the
process to avoid exceeding the size of connection pools
used by previous activities in the process.
If the field is 0 or empty, no thread pool is allocated and the
activity will run in a TIBCO ActiveMatrix BusinessWorks
worker thread.
Default: 2
Valid Range: 0 to 2 5 6
Queue Name
Y
The name of the queue from which the message will be
retrieved. Queue names can be chosen using the Choose
Queue button to the right of this field.
If the queue is to be created dynamically, enter the name of
the dynamic queue. The name must follow the MQSeries
rules for dynamic queue names.
If the queue name has been dynamically mapped using the
input schema's destination field, then it is not required
here. However, note that the Test button cannot test
dynamically mapped queue names.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
60
| Chapter 3
WebSphere MQ Palette
Table 13 Fields in the Configuration Tab: WebSphere MQ Get Activity (Sheet 3 of 5)
Field
Global
Variable
Close Option
N
Description
Select the close option for this get operation. These options
are for use on permanent dynamic queues only.
•
None—No action is taken.
•
Delete—Delete the queue, if it is empty. If the queue is
not empty, no action is taken.
•
Purge Delete—Delete the queue and any messages on
it.
If the get is being performed on a permanent dynamic
queue and the intention is for the queue to be deleted, you
must choose either Delete or Purge Delete. Delete will
delete the queue if it is empty, and Purge Delete will delete
the queue and any messages that are on it.
Do not select Delete or Purge Delete for permanently
defined queues. Depending on your security access, this
may delete them.
Dynamic Queue
N
A flag that enables the creation of a dynamic queue. When
selected, the Model Queue Name field is enabled.
Depending on the nature of the model queue selected, the
dynamic queue could be either "temporary dynamic" or
"permanent dynamic". Temporary queues are deleted by
the queue manager as soon as their message and
connection counts are zero. A permanent dynamic queue
behaves exactly like a predefined queue except that its life
cycle is intended to be managed by the application.
Dynamic queues are most frequently used as reply-to
destinations in messaging applications.
Model Queue Name
Y
Provide the name of the dynamic queue. This field is only
available if the Dynamic Queue check box is selected.
Note: Ensure that static queue names (queue names that do
not contain a pattern) are used for get activities. If a pattern
is used for a get activity queue name, the name generated
by the queue manager is not available until the get activity
is completed.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 61
|
Table 13 Fields in the Configuration Tab: WebSphere MQ Get Activity (Sheet 4 of 5)
Field
Global
Variable
Description
Access Mode
N
Select the access mode for the queue:
•
Shared You can use other listeners to access the queue
after selecting this mode.
Wait Forever
N
•
Exclusive You can’t use other listeners to access the
queue after selecting this mode. If another WebSphere
MQ application has the queue open then this activity
fails
•
Queue Default It accepts the access mode established
when the queue is created.
If selected, the Get activity will wait forever for a message
on the queue. When cleared, the Wait Timeout field is
enabled.
Default: Selected
Wait Timeout
Y
The number of milliseconds this activity waits for a
message before failing. If significant wait intervals are
allowed, a separate thread pool must be used. See
Threadpool Size on page 57.
This field is not available if the Wait Forever check box is
selected.
Fail If Quiescing
N
Select the Fail If Quiescing check box for destinations and
queues opened on behalf of this activity.
GMO Convert
N
Enable the Get Message Option "Convert". The queue
manager will perform field conversions appropriate for the
option.
Consult the IBM WebSphere documentation regarding the
Get message option GMO_CONVERT to see if it is
appropriate to your situation.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
62
| Chapter 3
WebSphere MQ Palette
Table 13 Fields in the Configuration Tab: WebSphere MQ Get Activity (Sheet 5 of 5)
Field
Global
Variable
Message Content Type
N
Description
Choose the way that the message body will be represented
in the output schema.
•
Binary The message is an array of bytes suitable for use
by the Data Conversion Palette activities.
•
Text The message is a string. The message will be
decoded using c h a r a c t e r S e t for the message, or 819 if
none is provided. Characterset 819 is the Java API
default.
•
Schema The message will be formatted according to
the schema provided in the Message Body Fields field.
Values for this schema will appear in the Output tab.
Message Body Fields
Y
Provide the schema to be used in the Output tab, and at run
time to decode the contents of this message.
Application Properties
Y
Select the Application Properties resource to be used to
map the output of this Get activity. Application properties
are similar to regular message header fields except that the
name and type of the fields can be determined by a
predefined schema. If the received message contains
properties, they are mapped according to this schema.
Property Control
N
Select one of the following settings:
•
PROPERTIES_AS_Q_DEF
•
PROPERTIES_COMPATIBILITY
•
PROPERTIES_IN_HANDLE
•
PROPERTIES_FORCE_MQRFH2
This setting overrides the queue's property control setting
and can be used to force message properties into a format
which is usable by the plug-in. In general, if a legacy
application sends properties in a message and the plug-in
does not detect them, setting this to I N _ H A N D L E is the best
option. The other options are provided for completeness.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 63
|
MultiMessage Tab
Table 14 lists and describes the fields in the MultiMessage tab.
Table 14 Fields in the MultiMessage Tab: WebSphere MQ Get Activity
Field
Global
Variable
Description
Multi Message Support
N
Select the behavior of this put with respect to multiple
messages:
•
None The activity will provide for a single message in
the output schema and will receive only one message.
No sync-point is used unless the Explicit Syncpoint
check box is selected.
•
BatchGroup The activity will configure the output
schema to have a B a t c h high level node and repeatable
I n t e r a c t i o n O u t p u t nodes. This selection enables the
Batch Size field and message batches of that size will
be retrieved as a single unit of work. However, if at
any point before the batch is complete a logical
message is encountered the entire logical message will
be returned as part of that batch. When the last
message from the logical message is transferred the
operation will complete regardless of whether a full
batch, as specified in the Batch Size field has been
retrieved. Using this mode on a queue containing very
large logical messages may result in an out of memory
condition in the virtual machine. A sync-point is
implied.
•
CustomGroup The activity configures the output
schema for a single message. The activity is designed
to function within a loop and using it outside a loop
does not process a logical message correctly. Each
invocation of the activity returns a message from the
logical message and l a s t M e s s a g e I n G r o u p in the
output schema can be used to determine when the last
message was processed and thus when to terminate
the loop. This field contains t r u e or f a l s e .
No sync-point is used unless the Explicit Syncpoint
check box is selected.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
64
| Chapter 3
WebSphere MQ Palette
Table 14 Fields in the MultiMessage Tab: WebSphere MQ Get Activity (Cont’d)
Field
Global
Variable
Description
Multi Message Support
N
•
Batch Size
Y
When BatchGroup is selected from the Multi Message
Support list, the Batch Size field becomes enabled.
CustomSegmented The activity configures the output
schema for a single message. The activity is designed
to function within a loop and using it outside a loop
does not process a segmented message correctly. Each
invocation of the activity returns a message segment
from the queue and lastMessageInGroup in the output
schema can be used to determine when the last
message was processed and thus when to terminate
the loop. This field contains true or false. This mode of
operation is intended to process segmented messages
which are too large to fit into memory all at once.
Note that setting an excessively large value for the Batch
Size field might cause the plug-in to run out of memory.
All Messages Available
N
When the All Messages Available check box is selected,
the first get of any operation that could involve a logical
message is sent with the M Q G M O _ A L L _ M S G S _ A V A I L A B L E flag
so that a logical message is only processed if it is
completed on the queue.
Get Ordered
N
Specify ordered sequencing of the gets for logical
messages. If the queue is not indexed this flag is disabled
at run time.
Commit Via SyncPoint
Activity
N
Select this check box to enlist this activity in an MQ unit of
work. Queue operations performed by this activity are not
committed to the queue until a SyncPoint Activity either
commits or backs out of the operation. The process must
be designed so that all activities preceding the SyncPoint
Activity use the same connection resource and all use the
sync point flag. Any activity which uses the same
connection configuration but does not specify the
"Commit Via SyncPoint" option prematurely commits the
unit of work.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 65
|
Table 14 Fields in the MultiMessage Tab: WebSphere MQ Get Activity (Cont’d)
Field
Global
Variable
Explicit Syncpoint
N
Description
While every effort is taken to avoid unnecessary
sync-points, this flag will force one when enabled. If there
is any possibility that converting the message to text (for
text messages), or parsing the body via a schema (for
schema based messages) fails, enabling this flag results in
the message being rolled back onto the queue rather than
being lost.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
66
| Chapter 3
WebSphere MQ Palette
Input Tab
Table 15 lists and describes the fields in the Input tab.
Table 15 Fields in the Input Tab: WebSphere MQ Get Activity
Field
Global
Variable
Description
InteractionInput
N
The root node for all the input provided to the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on input.
•
destination Override the destination queue name with the
string specified in this field.
•
destqmgr The name of the remote queue manager from
which to fetch the message. Note that the queue managers
involved must be configured with the necessary sender and
receiver channels in place and started.
•
correlationId Provide a correlation identifier for this message
by mapping a byte array to this field. The XPath statement
t i b : s t r i n g - t o - b a s e 6 4 ( " correlationid" ) is sufficient to
populate this field. The provided correlation ID is used to
filter messages from the queue.
•
messageId Specify a message ID. This value overrides the
default value generated by the queue manager. The rules are
the same as for c o r r e l a t i o n I d . If a message ID is provided,
it is used to filter the get results.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 67
|
Table 15 Fields in the Input Tab: WebSphere MQ Get Activity (Cont’d)
Field
Global
Variable
Description
mqproperties
N
•
groupId Set the group ID filter for the Get activity. Group
ID can be used like an extra filter field to filter non-grouped
messages.
•
characterSet Sets the IBM Coded Characterset ID of this
message. Valid values are:
—
8 5 0 —the
commonly used ASCII codeset
—
8 1 9 —the
ISO standard ASCII codeset
—
3 7 —the
—
1 2 0 0 —Unicode
—
1 2 0 8 —UTF-8
American EBCDIC codeset
The queue manager may apply this codeset when doing
conversions for the purpose of creating report messages.
•
alternateUserId Specify a userid to be used as an alternate
user for this operation only. The user used in the connection
resource must have the Alternate Userid Authority to use
this field.
•
waitInterval Specify a new get timeout value for this
operation only. It is the number of milliseconds that the
operation will wait before timing out. If the Wait Forever
check box is selected in the configuration tab, this field will
be ignored.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
68
| Chapter 3
WebSphere MQ Palette
Output Tab
Table 16 lists and describes the fields in the Output tab.
Table 16 Fields in the Output Tab: WebSphere MQ Get Activity (Sheet 1 of 5)
Field
Global
Variable
Description
Batch
N
If the BatchGroup is selected from the Multi Message
Support list for this activity, this B a t c h node will be the
high level item for the activity and will contain a number of
I n t e r a c t i o n O u t p u t nodes equal to or less than the Batch
Size parameter depending on how many messages are
available within the timeout period.
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on output.
•
destination Documents the destination for this message.
If the queue was a dynamic queue, the generated name
is reported here.
•
destqmgr The name of the remote queue manager
supplied in the input schema.
•
correlationId Documents the message correlation ID, if
any.
•
messageId Documents the message ID.
•
groupId Documents the group ID used for this message,
if any.
•
characterSet Documents the character set the queue
manager used to process this message.
•
alternateUserId If an alternate userid was in effect for
this activity it will be reflected here.
•
accountingToken The accounting token provided by the
sending application.
•
applicationIdData Application ID data. This is
application data was provided by sender of the
message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 69
|
Table 16 Fields in the Output Tab: WebSphere MQ Get Activity (Sheet 2 of 5)
Field
Global
Variable
Description
mqproperties
N
•
applicationOriginData Origin data as provided by either
the sender of the message or the queue manager.
•
putApplicationType The type of application that put the
message. Documented enumerations are:
MQAT_AIX
MQAT_CICS
MQAT_DOS
MQAT_IMS
MQAT_MVS
MQAT_OS2
MQAT_OS400
MQAT_QMGR
MQAT_UNIX
MQAT_WINDOWS
MQAT_JAVA
MQAT_UNKNOWN
MQAT_NO_CONTEXT
MQAT_CICS_VSE
MQAT_VMS
MQAT_GUARDIAN
MQAT_VOS
MQAT_DEFAULT
MQAT_NSK
MQAT_CICS_BRIDGE
MQAT_NOTES_AGENT
MQAT_WINDOWS_NT
MQAT_IMS_BRIDGE
MQAT_XCF
MQAT_NO_CONTEXT
•
putApplicationName Application name data as
provided by either the sender of the message or the
queue manager.
•
userId The effective user ID is used to connect to the
queue manager.
•
replyToQueueName The name of the queue to which a
reply must be sent. If the type of the message is
R e q u e s t , this is the name of the queue that the
application must send the reply message to.
•
replyToQmgrName The name of the remote queue
manager for the reply-to destination of this message, if
one was provided.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
70
| Chapter 3
WebSphere MQ Palette
Table 16 Fields in the Output Tab: WebSphere MQ Get Activity (Sheet 3 of 5)
Field
Global
Variable
Description
mqproperties
N
•
format Describes the nature of the data in the message.
The sender of the application can use standard names
(these names are prefixed by the M Q text) or
application-generated names. If the message originated
from a TIBCO ActiveMatrix BusinessWorks Plug-in for
WebSphere MQ application, this is an empty string.
•
expiry The expiration time (in tenths of a second), after
which the message is eligible to be discarded by the
queue manager.
The default value of - 1 means there is no expiration.
•
priority The priority (1-9) with which the message was
sent.
•
reportOptionPan Set to t r u e when the positive
acknowledgment flag in the r e p o r t field on.
•
reportOptionNan Set to t r u e when the negative
acknowledgment flag in the r e p o r t field on.
•
report If the message has any report bits set (PAN, NAN
for instance) they will be reflected here. Any other
report options that the queue manager has left on will
be present as well.
•
encoding Provide the encoding to be used for accessing
the numeric data in a schema based message.
•
messagetype Enumerated value indicating the message
type, where:
•
—
8
is Datagram.
—
2
is Reply.
—
4
is Report.
—
1
is Request.
backoutCount The number of times this message was
backed out before being committed.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Get Activity 71
|
Table 16 Fields in the Output Tab: WebSphere MQ Get Activity (Sheet 4 of 5)
Field
Global
Variable
Description
mqproperties
N
•
feedback If the message was a Report message, this
field defines the nature of the report. Defaults to 0 for
non report messages.
•
version Documents the version of the message. This
Plug-in supports type 2 messages only.
•
putDateTime The time that the message was placed onto
the queue.
•
groupStatus Contains one of these values:
M S G _ I N _ G R O U P, M S G _ N O T _ I N _ G R O U P,
or
M S G _ L A S T _ I N _ G R O U P.
appProperties
N
This field maps the application properties present in the
received message to the schema attached to the activity.
Properties which are missing or not present in the schema
are not shown here.
dynamicProperties
N
This optional node provides an alternative way to specify
application properties and is patterned after a similar node
on the JMS palette objects.
Each property is specified in its own "property" node and
contains the name, type, and value for the property.
Supported types are: String, Boolean, Byte, Short, Int, Long,
Float, and Double. String is the default value. This node can
be directly mapped between JMS and MQ messages.
bytes
N
The output body of the message. Typically, this byte array is
to be mapped as input to a TIBCO ActiveMatrix
BusinessWorks Plug-in for Data Conversion parse activity.
text
N
Contains the body of the message converted to text using
the c h a r a c t e r S e t element from the message.
Appear for text based messages only.
messageFields
N
Contain the message body formatted using Schema in the
Message Context Type list of the Configuration tab.
Appear for schema based messages only.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
72
| Chapter 3
WebSphere MQ Palette
Table 16 Fields in the Output Tab: WebSphere MQ Get Activity (Sheet 5 of 5)
Global
Variable
Field
lastMessageInGroup
Description
This field is present when CustomGroup or
CustomSegmented is selected from the Multi Message
Support list of the MultiMessage tab.
When the Get is used in a loop to receive a logical message
we use this field to indicate last message of the logical
group.
responsetimemillisec
N
Indicates how long it took to receive the message. This
value includes any time spent waiting on an empty queue.
Error Output Tab
Errors produced by this activity throw an exception of the type B w m q E x c e p t i o n .
Table 17 Fields in the Error Output Tab: WebSphere MQ Get Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the exception
that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the m s g field it is
provided here, otherwise this is a copy of m s g .
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 73
|
WebSphere MQ Listener Activity
The Listener activity listens on a queue and when a message arrives that satisfies
the configured filters it retrieves it and starts a process including the contents of
the message. The listener can poll a queue based on interval and timeout values,
or it can wait indefinitely on a queue. In non polling mode, messages are
processed as soon as they arrive. In polling mode, messages are also processed as
they arrive until a cessation in activity causes the listener to timeout on a get, at
which point it will wait one polling interval before resuming.
Test Button
The Test button for the Listener activity attempts to validate the selections for
queue manager and queue by opening the queue manager and instantiating the
queue object. For dynamic queues, only the presence of the model is checked. For
predefined queues which were successfully opened, a status box is presented.
For example:
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
74
| Chapter 3
WebSphere MQ Palette
The Test button on the Listener activity does not know whether the queue defined
as a Cluster Queue actually exists on the queue manager to which it is connected,
therefore, when running the process, the M Q R C _ U N K N O W N _ O B J E C T _ N A M E error
messages appear when the queue is actually hosted by a remote member of the
cluster. To use the Listener activity in the Queue Manager Cluster, it is necessary
to connect to the Queue Manager that hosts the queue.
If the listener is configured to receive groups of messages, either logical messages,
or just groups of unrelated ones, and it is not in polling mode an exposure exists
to the integrity of your application. In non polling mode the listener never times
out on a get, therefore if it has received (and committed) a partial group of
messages and is waiting indefinitely for the remainder it is exposed to losing
messages if the listener is shut down or the queue manager is terminated. In such
cases it is better to either use confirmations, or run the listener in polling mode.
There are several things to be aware of when testing applications in design mode.
Normally the WebSphere MQ get operation is not safely interruptable, however
while using the designer with remote or CCDT type connections such operations
are interrupted and terminated when the application test "stop" button is pressed.
This does not happen in a deployed instance! If the application uses a locally
bound connection the get operation will block until it times out, or if it is an
indefinite wait, until the designer is shut down. So, depending on the design of
the process being tested, the connection and input counts for resources used by
the application may appear to climb during iterative testing.
Configuration Tab
Table 18 lists and describes the fields in the Configuration tab.
Table 18 Fields in the Configuration Tab: WebSphere MQ Listener Activity (Sheet 1 of 4)
Field
Global
Variable
Description
Name
N
The name of the process listener activity.
Default: W e b S p h e r e
MQ Listener Start
Description
N
Optional free-form description.
Connection Resource
Y
Choose the connection resource which connects this
activity with the queue manager that has access to the
desired queue.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 75
|
Table 18 Fields in the Configuration Tab: WebSphere MQ Listener Activity (Sheet 2 of 4)
Field
Global
Variable
Instances
Y
Description
Enter the number of instances of the queue listener you
wish this activity to run. This translates exactly to the
number of threads and connections to the Queue Manager
created by this activity.
The default is 1 and the maximum is 6 4 .
If the Require Client Confirmation check box is selected,
each thread this activity runs waits for the confirmation
before getting another message from the queue. Therefore,
to process messages in an absolute serial fashion, only one
instance of the listener can be started. In this case, the
number of messages processed becomes a function of how
much latency exists in the activity before the confirmation.
Queue Name
Y
The name of the queue from which the message will be
retrieved. Click the Choose Destination button to choose
the Queue names.
Dynamic Queue
N
A flag that enables the creation of a dynamic queue. When
selected, the Model Queue Name field is enabled.
Model Queue Name
Y
Provide the name of the model queue after which this
dynamic queue will be patterned. This field is only
available if the Dynamic Queue check box is selected.
Note: Ensure that static queue names (queue names that do
not contain a pattern) are used for listener activities. If a
pattern is used for a Listener activity queue name, the name
generated by the queue manager is not available until the
listener creates a process that makes it impossible for a
sender to know the name.
Fail If Quiescing
N
Select the Fail If Quiescing check box to prevent this
listener from holding up a queue manager quiesce
operation. If the queue manager does terminate, the
activity attempts to reconnect indefinitely.
GMO Convert
N
When selected, turns on the get message option "convert".
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
76
| Chapter 3
WebSphere MQ Palette
Table 18 Fields in the Configuration Tab: WebSphere MQ Listener Activity (Sheet 3 of 4)
Field
Global
Variable
Description
Access Mode
N
Select the access mode for the queue:
•
Shared Other listeners can access the queue when this
mode is selected.
Require Client
Confirmation
N
•
Exclusive Other listeners can’t access the queue when
this mode is selected. During execution, if the queue is
open by another application then the activity fails.
•
Queue Default It accepts the access mode established
when the queue was created.
Select the Require Client Confirmation check box to
request explicit confirmation of a received message.
The confirm activity can be used to confirm the arrival of a
message and remove the message from the queue. The
plug-in uses the Syncpoint capability of the queue manager
to ensure that the message is only removed from the queue
if it is confirmed. Note also that the activity will wait for the
confirmation before obtaining another message which
imposes an absolute limit on the throughput. If serial
processing of the messages is not essential, raise the
Instances parameter until either the worker threads are
100% busy or the desired throughput is achieved.
If the activity fails to confirm the message, it will loop and
repeatedly process the same message.
Disable Connection
Reuse
N
This option is available when using client confirmation.
Enable this option to release the connection after the
message is confirmed. If the connection is pooled, the
connection is released back to the pool. Therefore, if the
objective is to clean the connection, it is best to use a
non-pooled connection.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 77
|
Table 18 Fields in the Configuration Tab: WebSphere MQ Listener Activity (Sheet 4 of 4)
Field
Global
Variable
Message Content Type
N
Description
Choose the way that the message body will be represented
on the output schema.
•
Binary The message is an array of bytes suitable for use
by the Data Conversion Palette activities.
•
Text The message is a string. The message will be
decoded using c h a r a c t e r S e t for the message, or 819 if
none is provided.
Characterset 819 is the Java API default.
•
Message Body Fields
Y
Schema The message will be formatted according to
the schema provided in the Message Body Fields field.
Values schema will appear in the Output tab.
Provide the schema to be used in the Output tab, and at run
time to decode the contents of this message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
78
| Chapter 3
WebSphere MQ Palette
Advanced Tab
Table 19 lists and describes the fields in the Advanced tab.
Table 19 Fields in the Advanced Tab: WebSphere MQ Listener Activity (Sheet 1 of 3)
Field
Global
Variable
Description
Enable Polling
N
When selected, the activity instantiates a connection to the
queue manager and opens the queue. It then periodically
issues timed gets on the queue where the timeout value is
equal to the polling timeout and the period between gets is
equal to the polling interval.
However, if there are multiple messages on the queue they
are processed without an intervening polling interval, thus
diminishing application latency.
When cleared, the activity waits forever on the queue,
processing messages as they arrive. If the queue manager
connection fails the activity attempts to reconnect based on
the reconnection interval.
Note that a poor choice of polling interval and polling
timeout values could impose a high overhead on the engine
as well as the queue manager to which the activity is
connected. Use values here which take into account the
latency in the network between this activity and the queue
manager, as well as the processing demands you are willing
to place on that queue manager.
Polling Interval
Y
If the Enable Polling check box is selected, this is the interval
at which a new polling cycle is initiated.
Specify time in milliseconds.
Valid range: 1 0 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 79
|
Table 19 Fields in the Advanced Tab: WebSphere MQ Listener Activity (Sheet 2 of 3)
Field
Global
Variable
Polling Timeout
Y
Description
If the Enable Polling check box is selected, this is the timeout
value for each individual listen. The value specified here
must be significantly smaller than the Polling Interval value.
This minimizes the number of concurrent connections to the
queue and reduces the processing resources required.
Specify time in milliseconds.
Valid range: 1 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0
Reconnection Interval
Y
The length of time, in milliseconds, that the listener waits
between attempts to reconnect to the queue.
This setting is used only when the Enable Polling check box
is cleared. If the Enable Polling check box is cleared, the
Listener activity listens indefinitely on the queue. However,
if an error occurs and the queue manager is subsequently
unavailable (shut down for instance), this value is the
number of milliseconds between reconnection attempts.
Valid range: 2 0 0 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0 0
Filter Encoding
N
This field specifies the encoding of the values provided in the
Correlation Id, Message Id, and Group Id fields. The Filter
Encoding field provides three type values: t e x t , b a s e 6 4 ,
and h e x b i n .
When this field is set to either b a s e 6 4 or h e x b i n , the values
of the three Id fields as follows are transformed
appropriately to form a binary filter.
For example, a valid base64 filter looks like
and a valid hexbin
filter looks like
bzkMF27syhmb37nm8kPQojEupbpNVJHm
6f390c176eecca199bdfb9e6f243d0a2312ea5ba4d5491e6.
Note that you do not prefix the hexbin filter with "0x".
Correlation Id
Y
The Listener activity instructs the queue manager to filter the
request based on this correlation ID. Only messages with
exactly the same ID are accepted.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
80
| Chapter 3
WebSphere MQ Palette
Table 19 Fields in the Advanced Tab: WebSphere MQ Listener Activity (Sheet 3 of 3)
Field
Global
Variable
Message Id
Y
The Listener activity instructs the queue manager to filter the
request based on the specified message ID.
Group Id
Y
The Listener activity instructs the queue manager to filter the
request based on the specified group ID. Group ID can be
used like an extra filter field for non-grouped messages.
Application Properties
Y
Select the Application Properties resource to be used to map
the output of this get. Application properties are similar to
regular message header fields except that the name and type
of the fields can be determined by a predefined schema. If
the received message contains properties, they are mapped
according to this schema.
Property Control
N
Select one of the following settings:
Description
•
PROPERTIES_AS_Q_DEF
•
PROPERTIES_COMPATIBILITY
•
PROPERTIES_IN_HANDLE
•
PROPERTIES_FORCE_MQRFH2
This setting overrides the queue's property control setting
and can be used to force message properties into a format
which is usable by the plug-in. In general, if a legacy
application sends properties in a message and the plug-in
does not detect them, setting this to I N _ H A N D L E is the best
option. The other options are provided for completeness.
Error Output
N
Enable this option to cause the listener to create a process
consisting of only a B w m q E x c e p t i o n object when the listener
encounters an error.
If the Error Output check box is not selected, the listener
simply logs such conditions and continues.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 81
|
MultiMessage Tab
Table 20 lists and describes the fields in the MultiMessage tab.
Table 20 Fields in the MultiMessage Tab: WebSphere MQ Listener Activity
Field
Global
Variable
Description
Multi Message
Support
N
Select the behavior of this put with respect to multiple
messages:
•
None The activity will provide for a single message in
the output schema and will receive only one message.
•
BatchGroup The activity will configure the output
schema to have a B a t c h high level node and repeatable
I n t e r a c t i o n O u t p u t nodes. This selection enables the
Batch Size field and message batches of that size will be
retrieved as a single unit of work. However, if at any
point before the batch is complete a logical message is
encountered the entire logical message will be returned
as part of that batch. When the last message from the
logical message is transferred the operation will
complete regardless of whether a full batch, as specified
in Batch Size has been retrieved. Using this mode on a
queue containing very large logical messages may result
in an out of memory condition in the virtual machine.
If the listener is not polling, it waits indefinitely for
messages and in the event that a partial batch is received
but the remainder does not come before the listener is
shut down the partial batch is not processed. If this
scenario is possible it is good practice to set the listener
to poll so that a timeout eventually causes the partial
batch to be processed.
Batch Size
Y
When BatchGroup is selected from the Multi Message
Support list, the Batch Size field becomes enabled.
Note that setting an excessively large value for the Batch
Size field might cause the plug-in to run out of memory.
All Message Available
N
When selected the first get of any operation that could
involve a logical message is sent with the
M Q G M O _ A L L _ M S G S _ A V A I L A B L E flag so that a logical message
is only processed if it is completed in the queue.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
82
| Chapter 3
WebSphere MQ Palette
Table 20 Fields in the MultiMessage Tab: WebSphere MQ Listener Activity (Cont’d)
Field
Global
Variable
Get Ordered
N
Select the Get Ordered check box to specify ordered
sequencing of the get operations for logical messages. If the
queue is not indexed, the M Q G M O _ A L L _ M S G S _ A V A I L A B L E flag
is disabled at run time.
Poison Msg Detection
Y
If the following conditions are met, the Poison Msg
Threshold and the Queue Name fields are enabled:
Description
•
The listener is operating in client confirmation mode,
which is enabled by selecting the Require Client
Confirmation option in the Configuration tab.
•
The listener does not receive multiple messages, which
is enabled by setting the Multi Message Support option
to N o n e .
•
Select the Poison Msg Dectection check box.
After the Poison Msg Detection check box is selected, the
listener can relocate any message that the listener cannot
confirm to a special queue, which is processed as an
exception or by manual intervention.
Poison Msg Threshold
N
If the Poison Msg Detection check box is selected, the value
in the Poison Msg Threshold field represents the number of
times a message is backed out because of a failure to commit
before the message is relocated to the poison message
queue.
Queue Name
Y
Specifies the name of the queue to which poison messages
are relocated.
Misc Tab
This tab contains fields that can be used by the activity to effect workload
balancing across threads and even engines.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 83
|
Sequencing Key
This field can contain an XPath expression that specifies which processes must
run, and in which in order. Process instances with sequencing keys that evaluate
to the same value are executed sequentially in the order the process instance was
created.
See TIBCO ActiveMatrix BusinessWorks Process Design Guide for more information
about controlling the execution order of process instances and about XPath
expressions.
Custom Id
This field can contain an XPath expression that specifies a custom ID for the
process instance. This ID is displayed in the View Service dialog of TIBCO
Administrator, and it is also available in the $ _ p r o c e s s C o n t e x t p r o c e s s
variable.
Output Tab
Table 21 lists and describes the fields in the Output tab.
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 1 of 6)
Field
Global
Variable
Batch
N
If Batch or BatchGroup is selected from the Multi Message
Support list in the MultiMessage tab, this node will be
present and will contain an I n t e r a c t i o n O u t p u t node for
each message retrieved as part of this batch.
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on output.
Description
•
destination Documents the destination for this message.
If the queue was a dynamic queue, the generated name is
reported here.
•
destqmgr If the message was routed through a remote
queue manager, documents the name of the destination
queue manager.
•
correlationId Documents the message correlation ID, if
any.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
84
| Chapter 3
WebSphere MQ Palette
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 2 of 6)
Field
Global
Variable
Description
•
messageId Documents the message ID.
•
groupId Documents the group ID used for this message,
if any.
•
characterSet Documents the character set the queue
manager used to process this message or was set by the
sending application.
•
alternateUserId If an alternate userid was in effect for this
activity it will be reflected here.
•
accountingToken The accounting token provided by the
sending application.
•
applicationIdData Application ID data as provided by the
sending application.
•
applicationOriginData Additional information about the
origin of the message provided by the sender of the
message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 85
|
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 3 of 6)
Field
Global
Variable
Description
mqproperties
N
•
putApplicationType The type of application that put the
message. Documented enumerations are:
MQAT_AIX
MQAT_CICS
MQAT_DOS
MQAT_IMS
MQAT_MVS
MQAT_OS2
MQAT_OS400
MQAT_QMGR
MQAT_UNIX
MQAT_WINDOWS
MQAT_JAVA
MQAT_UNKNOWN
MQAT_NO_CONTEXT
MQAT_CICS_VSE
MQAT_VMS
MQAT_GUARDIAN
MQAT_VOS
MQAT_DEFAULT
MQAT_NSK
MQAT_CICS_BRIDGE
MQAT_NOTES_AGENT
MQAT_WINDOWS_NT
MQAT_IMS_BRIDGE
MQAT_XCF
MQAT_NO_CONTEXT
•
putApplicationName The name of the application that put
the message.
•
userId The effective user ID is used to connect to the
queue manager.
•
replyToQueueName The name of the queue to which a
reply must be sent. If the type of the message is R e q u e s t ,
this is the name of the queue that the application must
send the reply message to.
•
replyToQueueMgrName The name of the remote queue
manager to be used when processing any reply or report
message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
86
| Chapter 3
WebSphere MQ Palette
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 4 of 6)
Field
Global
Variable
Description
mqproperties
N
•
format A name that describes the nature of the data in the
message. The sender of the application can used standard
names (these names are prefixed by the text M Q ) or
application generated names. If this message originated
from a TIBCO ActiveMatrix BusinessWorks Plug-in for
WebSphere MQ, then this field contains an empty string.
•
expiry The expiration time (in tenths of a second), after
which the message is eligible to be discarded by the
queue manager. This contains whatever value was used
when the message was sent.
•
priority The priority (1-9) with which the message was
sent.
•
reportOptionPan Set to t r u e when the positive
acknowledgment flag in the r e p o r t field on.
•
reportOptionNan Set to t r u e when the negative
acknowledgment flag in the r e p o r t field on.
•
report Documents the type of report requested for this
message. The feedback field relates to the report field and
are extensively documented in the IBM WebSphere MQ
documentation.
•
encoding The encoding used to decode numeric data in
the message body for schema based messages.
•
messagetype Enumerated value indicating the message
type, where:
•
—
8
is Datagram.
—
2
is Reply.
—
4
is Report.
—
1
is Request.
backoutCount The number of times this message was
backed out before being committed.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Listener Activity 87
|
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 5 of 6)
Field
Global
Variable
Description
mqproperties
N
•
feedback If the message was a Report message, this field
defines the nature of the report. Defaults to 0 for non
report messages.
•
version Documents the version of the message. This
Plug-in supports type 2 messages only.
•
putDateTime The time that the message was placed onto
the queue.
•
groupStatus Indicates whether the message is part of a
logical message group or not.
Contains three possible values: M S G _ I N _ G R O U P,
M S G _ N O T _ I N _ G R O U P, M S G _ L A S T _ I N _ G R O U P.
appProperties
N
This field maps the application properties present in the
received message to the schema attached to the activity.
Properties which are missing or not present in the schema are
not shown here.
dynamicProperties
N
This optional node provides an alternative way to specify
application properties and is patterned after a similar node
on the JMS palette objects.
Each property is specified in its own "property" node and
contains the name, type, and value for the property.
Supported types are: String, Boolean, Byte, Short, Int, Long,
Float, and Double. String is the default value. This node can
be directly mapped between JMS and MQ messages.
bytes
N
The output body of the message. Typically, this byte array is
to be mapped as input to a Data Conversion Plug-in parse
activity.
Appears for binary messages.
text
N
Contains the body of the message converted to text using the
message's c h a r a c t e r S e t field.
Appears for text type messages.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
88
| Chapter 3
WebSphere MQ Palette
Table 21 Fields in the Output Tab: WebSphere MQ Listener Activity (Sheet 6 of 6)
Field
Global
Variable
messageFields
N
Description
Contains the message body formatted using the schema
specified in the Configuration tab.
Displayed for schema-based messages only.
Error Output Tab
Errors produced by this activity are written to the log and the activity continues to
listen. If the polling interval or the reconnection interval is small and the activity
is attempting to reconnect to an unavailable queue manager, it could produce a lot
of output in the activities log.
If the Error Output check box in the Advanced tab of the WebSphere MQ Listener
activity is selected, errors produced by this activity throw an exception of the type
BwmqException.
Table 22 shows the fields displayed in the Error Output tab after the Error Output
check box is selected:
Table 22 Fields in the Error Output Tab: WebSphere MQ Listener Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the
exception that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the m s g field it is
provided here, otherwise this is a copy of m s g .
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 89
|
WebSphere MQ Publish Activity
The Publish activity publishes a message to a dynamic or a predefined topic. The
activity is capable of sending any of the four message types described in the
WebSphere MQ Put Activity section. The capabilities of the activity are
determined by the configuration, with some runtime behaviors controlled by the
input schema. The type of message being sent may determine what fields are
applicable for the publish operation, for instance request messages are
incompatible with report options. Even though this is a pub/sub type of activity,
the report and reply-to queues are real queues not topics.
In WebSphere MQ, a topic is defined as a string of characters starting with a
forward slash key (/) and can contain many topic nodes to the right. WebSphere
MQ supports a mechanism for separating administratively-defined topic strings
from application-defined ones. This is exposed on the publish activity by the two
fields Topic and Topic Dynamic. The intent is that administratively defined
portions of the topic string are represented by selecting a permanently defined
topic for the first part of the topic string and concatenating the dynamic portion to
the right. This way an application can be deployed in several environments
without naming conflicts.
There is no difference between the message object published by this activity from
the one sent by the Plug-in's Put activity.
Test Button
Each activity includes a Test button. The Test button for the Publish activity
verifies that any administratively defined topic objects exist. Dynamic portions
are not checked, and if the entire topic is dynamically defined, only an
informational message is printed.
For example:
If the topic is a clustered topic which is not physically defined in the Queue
Manager to which this activity connects, the Test button will not detect it, but the
run time will work so long as the Topic Dynamic field composes the entire path
for the subscription.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
90
| Chapter 3
WebSphere MQ Palette
Configuration Tab
Table 23 lists and describes the fields in the Configuration tab.
Table 23 Fields in the Configuration Tab: WebSphere MQ Publish Activity
Field
Global
Variable
Description
Name
N
The name of the Publish activity.
Default: W e b S p h e r e
MQ Publish Activity
Description
N
Optional free-form description.
Connection Resource
Y
Choose the connection resource which associates this
activity with the queue manager that has access to the
desired topic.
Topic
Y
The name of the administratively defined topic to which
the message will be published. Click the Choose
Destination button to choose the Topic. This field is
optional in the event that the topic string is to be entirely
specified in the Topic Dynamic field.
Topic Dynamic
Y
The contents of this field are concatenated to the topic
name referenced by the previous administratively defined
topic. If no administratively defined topic is provided this
string forms the entire topic string.
Message Type
N
Select the type of message that is to be sent:
•
Datagram
•
Request
•
Reply
•
Report
If a Request message is selected, the Reply To Queue field
is enabled and the report options are disabled. All other
message types allow report options.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 91
|
Table 23 Fields in the Configuration Tab: WebSphere MQ Publish Activity (Cont’d)
Field
Global
Variable
Reply To Queue
Y
This Reply To Queue field is enabled only when the
Request message type is selected from the Message Type
list. This field contains the queue name which will be
placed into the r e p l y T o Q u e u e N a m e element in the Input
tab. Click the Choose Queue button besides the Reply To
Queue field to select the queue.
Fail If Quiescing
N
Select the Fail If Quiescing check box for destinations and
queues opened on behalf of this activity
Retain Message
N
Select the Retain Message check box to indicate that the
message is to be retained in the queue manager even if no
subscribers exist. The future subscribers can receive the
message when they are created. This is useful for
conveying application state information.
Message Content Type
N
Choose the way that the message body will be represented
in the input schema.
Description
•
Binary The message is an array of bytes suitable for use
by the Data Conversion Palette activities.
•
Text The message is a string. The message will be
encoded using c h a r a c t e r S e t for the message, or 819 if
none is provided.
Characterset 819 is the Java API default.
•
Schema The message will be formatted according to
the schema provided in the Message Body Fields field.
Message Body Fields
Y
Provide the schema to be used in the Input tab, and at run
time to encode the contents of this message.
Application Properties
Y
Select a schema which represents the application properties
to be placed in this message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
92
| Chapter 3
WebSphere MQ Palette
Advanced Tab
Table 24 lists and describes the fields in the Advanced tab.
Table 24 Fields in the Advanced Tab: WebSphere MQ Publish Activity (Sheet 1 of 3)
Field
Global
Variable
Message Priority
Y
Set the priority of the message as it is to be retrieved by the
queue manager. The values range from 0 to 9. If not
specified, the default is the destination queue's default
priority.
Set Context Info
N
Select the level of authorization this application has been
given by the queue manager. The two authorizations
(Identity Context and All Context) are selectable and will be
used to control which fields are available in the input
schema.
Description
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 93
|
Table 24 Fields in the Advanced Tab: WebSphere MQ Publish Activity (Sheet 2 of 3)
Field
Global
Variable
Reports
N
Description
Several kinds of report message can be triggered by a
message's arrival at a particular point in the WebSphere MQ
system. Select the type of report message and event trigger
using the combination box.
Events that can trigger a report are:
•
Confirm on arrival The report is sent when the message
arrives at the destination. If no subscription exists at the
time of the messages delivery to the queue manager, then
this report is not produced.
•
Confirm on delivery The report is sent when the
message has been removed from the destination queue
by an application.
•
Exception The report is sent when the message
encounters an error while being routed through the
messaging system. For instance, if the message was
destined for a remote queue but the queue does not exist
on the remote queue manager.
•
Expiry The report is sent when the message is removed
from the queue because its expiry time has arrived.
Report types are:
•
None The report is not enabled.
•
With No Data The body of the message does not
accompany the report.
•
With Data The first 100 bytes of the message body
accompanies the report.
•
With Full Data The entire body of the message
accompanies the report.
Reports are delivered to the reply to queue specified in the
Report Reply Queue field. Because this field maps to the
message's r e p l y T o Q u e u e N a m e field, reports are mutually
exclusive with Request type messages. That is, if the message
type is Request, a report confirmation is not sent.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
94
| Chapter 3
WebSphere MQ Palette
Table 24 Fields in the Advanced Tab: WebSphere MQ Publish Activity (Sheet 3 of 3)
Field
Global
Variable
Report Reply Queue
Y
Enter the name of the queue to which Report messages must
be sent. Click Choose Queue to select the queue. The value
entered here maps onto the r e p l y T o Q u e u e N a m e element.
Asynchronous Put*
N
Put the message asynchronously. This operation does not
wait for a response from the queue manager for filling in
many of the fields in the output schema. Message Id and
Correlation Id are available.
Description
Input Tab
Table 25 lists and describes the fields in the Input tab.
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 1 of 6)
Field
Global
Variable
Description
InteractionInput
N
This input schema field is the root node for all the input
provided to the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) that are relevant on input.
•
destination Specify a destination here to override the
topic name from the configuration panels.
•
destqmgr Destination queue manager name. The name of
the queue manager on which this topic resides. Note that
a transmission queue and a sender channel must be
configured for this queue manager for it to work.
•
topicdynamic The dynamic portion of the topic string.
This can be the entire topic string and will override any
dynamic topic specified on the configuration panel.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 95
|
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 2 of 6)
Field
Global
Variable
Description
mqproperties
N
•
correlationId Provide a correlation identifier for this
message by mapping a byte array to this field. The XPath
expression t i b : s t r i n g - t o - b a s e 6 4 ( " correlationid" ) is
sufficient to populate this field. This field is only valid if
the topic referenced is an administratively defined
unmanaged topic. In all other cases it will be ignored by
the queue manager. Consult the IBM WebSphere MQ
documentation for descriptions of managed and
unmanaged subscriptions.
•
messageId Provide a message identifier for this message
by mapping a byte array to this field. The XPath
expression t i b : s t r i n g - t o - b a s e 6 4 ( " messageId" ) is
sufficient to populate this field. This field is only valid if
the topic referenced is an administratively defined
unmanaged topic. In all other cases it will be ignored by
the queue manager.
•
characterSet Sets the IBM Coded Characterset ID of this
message. Valid values are:
—
8 5 0 —the
commonly used ASCII codeset
—
8 1 9 —the
ISO standard ASCII codeset
—
3 7 —the
—
1 2 0 0 —Unicode
—
1 2 0 8 —UTF-8
American EBCDIC codeset
The queue manager may apply this codeset when doing
conversions for the purpose of creating report messages.
•
alternateUserId Specify a userid to be used as an alternate
user for this operation only. The user used in the
connection resource must have the Alternate Userid
Authority to use this field.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
96
| Chapter 3
WebSphere MQ Palette
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 3 of 6)
Field
Global
Variable
Description
mqproperties
N
•
accountingToken Provide a binary (base 64 encoded)
accounting token to be used on host systems to assist in
accounting for resources used by the application.
Require Identity Context or All Context in the Set
Context Info list.
•
applicationIdData Provide a string that can be used on all
end points to identify this application.
Require Identity Context or All Context in the Set
Context Info list.
•
applicationOriginData Provide information related to the
originating application node for this message.
Require All Context in the Set Context Info list.
•
putApplicationName The name of the application that put
the message. Provide information about the originating
application in this field.
Require All Context in the Set Context Info list.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 97
|
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 4 of 6)
Field
Global
Variable
Description
mqproperties
N
•
putApplicationType Provide either one of the IBM
documented application type enumerators for this
application or one of your choosing. See the IBM
WebSphere MQ documentation for the meaning of the
documented application types.
Require All Context in the Set Context Info list, and the
documented enumerations are:
MQAT_AIX
MQAT_CICS
MQAT_DOS
MQAT_IMS
MQAT_MVS
MQAT_OS2
MQAT_OS400
MQAT_QMGR
MQAT_UNIX
MQAT_WINDOWS
MQAT_JAVA
MQAT_UNKNOWN
MQAT_NO_CONTEXT
MQAT_CICS_VSE
MQAT_VMS
MQAT_GUARDIAN
MQAT_VOS
MQAT_DEFAULT
MQAT_NSK
MQAT_CICS_BRIDGE
MQAT_NOTES_AGENT
MQAT_WINDOWS_NT
MQAT_IMS_BRIDGE
MQAT_XCF
MQAT_NO_CONTEXT
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
98
| Chapter 3
WebSphere MQ Palette
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 5 of 6)
Field
Global
Variable
Description
mqproperties
N
•
userId Provide the userid to be used when authorizing
this message as it traverses the messaging system. For
operations with report options, this field is mandatory. If
a value is not provided here, it is taken from the
connection resource if one is available there, and from the
environment if it is not.
Require Identity Context or All Context in the Set
Context Info list.
•
replyToQueueName Specify the name of an existing
queue that the target application can use as a destination
for its response. This enables the common "request
response" pattern.
•
replyToQmgrName Destination queue manager name.
The name of the queue manager on which this queue
resides. Note that a transmission queue and a sender
channel must be configured for this to work.
•
format Describes the nature of the data in the message. It
defaults to " " , or M Q F M T _ N O N E . A user defined format
can be used to assist the receiving application in decoding
the message, for instance in the selection of a Data
Conversion parse activity for this message type.
•
expiry Indicates the length of time (in tenths of a second)
that the message is kept on the queue before being
deleted. Defaults to - 1 , which means there is no
expiration. This field overrides the configuration value
for expiry if it is mapped.
Permissible Values: A positive integer or - 1
•
priority The priority (0-9) of the message. This field
overrides a configuration value for priority if it is
mapped.
•
reportOptionPan Set to t r u e to turn the positive
acknowledgment flag in the r e p o r t field on.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 99
|
Table 25 Fields in the Input Tab: WebSphere MQ Publish Activity (Sheet 6 of 6)
Field
Global
Variable
Description
mqproperties
N
•
reportOptionNan Set to t r u e to turn the negative
acknowledgment flag in the r e p o r t field on.
•
report Reporting options are fully configurable in the
Advanced tab, however any integer entered here will be
logically ended with existing ones and set into the
message.
•
encoding The encoding value is described in the
WebSphere MQ API documentation. It is used by
methods that set and get numeric values from the
message if it is schema based.
appProperties
N
Contains fields that correspond to the schema as it is defined
in the application properties resource that is mapped to this
activity. Note that a p p P r o p e r t i e s is only present if a WMQ
Properties Resource has been configured for the activity.
dynamicProperties
N
This optional node provides an alternative way to specify
application properties and is patterned after a similar node
on the JMS palette objects.
Each property is specified in its own "property" node and
contains the name, type, and value for the property.
Supported types are: String, Boolean, Byte, Short, Int, Long,
Float, and Double. String is the default value. This node can
be directly mapped between JMS and MQ messages.
bytes
N
Map the main content of the message body here. In general,
this is the output of a Plug-in for Data Conversion render
activity, but could be any array of bytes.
Appear for the Binary type messages.
text
N
Contain the body of the message converted to text using the
field.
characterSet
Appear for the Text type messages.
messageFields
N
Contain the formatted output of a schema type messages.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
100
| Chapter 3
WebSphere MQ Palette
Output Tab
Table 26 lists and describes the fields in the Output tab.
Table 26 Fields in the Output Tab: WebSphere MQ Publish Activity (Sheet 1 of 3)
Field
Global
Variable
Description
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on input.
•
destination Documents the destination for this message.
If the topic was a dynamic topic, the generated name is
reported here.
•
destqmgr Documents the remote queue manager
specified in the input schema.
•
topicdynamic Documents the effective topic string for
this publication. This includes the root portion from any
administratively defined topic provided, as well as the
any dynamic portion.
•
correlationId Documents the message correlation ID, if
any.
•
messageId Documents the message ID.
•
characterSet Documents the character set the queue
manager used to process this message.
•
alternateUserId If an alternate userid was specified in the
input schema is reflected here.
•
accountingToken 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.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Publish Activity 101
|
Table 26 Fields in the Output Tab: WebSphere MQ Publish Activity (Sheet 2 of 3)
Field
Global
Variable
Description
•
userId The effective user ID is used to connect to the
queue manager.
mqproperties
N
•
replyToQueueName Same as input.
•
replyToQmgrName Same as input.
•
format The character string placed into the format field
by the sending application.
•
expiry Indicates the number in tenths of a second that the
message is to be kept on the queue before being deleted.
Defaults to - 1 , which means there is no expiration.
•
priority The priority (1-9) with which the message was
sent.
•
reportOptionPan Set to t r u e when the positive
acknowledgment flag in the r e p o r t field on.
•
reportOptionNan Set to t r u e when the negative
acknowledgment flag in the r e p o r t field on.
•
report Documents the report field of the published
message.
•
encoding Documents the encoding field of the published
message.
•
messagetype Enumerated value indicating the message
type, where:
•
—
8
is Datagram.
—
2
is Reply.
—
4
is Report.
—
1
is Request.
backoutCount The number of times this message was
backed out before being committed.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
102
| Chapter 3
WebSphere MQ Palette
Table 26 Fields in the Output Tab: WebSphere MQ Publish Activity (Sheet 3 of 3)
Global
Variable
Field
Description
•
feedback If the message was a Report message, this field
defines the nature of the report. Defaults to 0 for non
report messages.
•
version Documents the version of the message. This
Plug-in supports type 2 messages only.
mqproperties
N
•
putDateTime The time that the message was placed onto
the queue.
•
groupStatus Because logical messages are not supported
by the Pub/Sub activity, this must always be
M S G _ N O T _ I N _ G R O U P.
responsetimemillisec
N
Indicates, in milliseconds, how long it took to publish the
message.
Error Output Tab
Errors produced by this activity throw an exception of the type B w m q E x c e p t i o n .
Table 27 Fields in the Error Output Tab: WebSphere MQ Publish Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the exception
that caused the activity to fail.
msgCode
The error message identifier for this message
errorMessage
If extra information is available to augment that provided in the m s g field it is
provided here, otherwise this is a copy of m s g .
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 103
|
WebSphere MQ Subscriber Activity
The Subscriber activity listens on a topic or administratively defined subscription
and starts a process that provides the contents of the message. The subscriber can
poll a topic based on interval and a timeout values, or it can wait indefinitely.
Regardless of which mode it is in, when messages arrive they are each processed
immediately with no intervening interval time.
When polling is enabled, messages published to the subscribed topic are not lost
during the interval when the subscriber is not actively listening because the
subscriber exists for the duration and is not created and destroyed across
intervals. However, this does not necessarily apply during 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 is specified.
If neither of these fields is provided but an existing durable subscription is
specified, the activity subscribes 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 that all messages appropriate for the topic are routed there.
This subscription will cease to exist when the listener is stopped, or in error
recovery. To avoid missing messages destined for the topic, you can enable the
Durable Subscription option to have the subscription persisted indefinitely in the
queue manager using the name provided. Durable subscriptions accumulate
messages even when there are no listeners, much like a queue would.
Test Button
The Test button for the Subscriber activity will confirm the existence of the
administratively defined topic and durable subscription when either is specified.
If the topic is a clustered topic hosted by a different Queue Manager than the one
to which this activity connects, the Test button will not detect it. However, at run
time if the Topic Dynamic field contains the entire path for the subscription, it
will work.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
104
| Chapter 3
WebSphere MQ Palette
Configuration Tab
Table 28 lists and describes the fields in the Configuration tab.
Table 28 Fields in the Configuration Tab: WebSphere MQ Subscriber Activity
Field
Global
Variable
Description
Name
N
The name of the subscriber activity.
Default: W e b S p h e r e
MQ Subscriber Start
Description
N
Optional free-form description.
Connection Resource
Y
Choose the connection resource which associates this
activity with the queue manager that has access to the
desired topic.
Topic
Y
The name of the administratively defined portion of the
topic string. If a Topic Name is specified, the topic string
associated with that name in the queue manager forms the
root or left-most portion of the topic string. Existing topics
can be selected by clicking the Choose Destination button
besides the Topic field.
Wildcard Scheme
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 MQ
documentation for information about these schemes.
Topic Dynamic
Y
Enter the dynamic portion of the topic string here. This
field can contain the entire topic string or only the
right-most portion of it, depending on whether it is to be
used in conjunction with an administratively defined topic.
Durable Subscription
N
When selected, the subscription created by this subscriber
is durable. Durable subscriptions survive subscriber and
queue manager restarts, and accumulate messages until
they are explicitly deleted.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 105
|
Table 28 Fields in the Configuration Tab: WebSphere MQ Subscriber Activity (Cont’d)
Field
Global
Variable
Subscription Name
Y
Description
Enabled if the Durable Subscription check box is selected.
This is the name of the permanent subscription.
A subscriber can be started using only the durable
subscription name. If the subscription exists, no topic string
or dynamic topic are necessary.
New Publications Only
N
Select the New Publications Only check box for
non-durable subscriptions where you do not want to
receive the last message published with the Retain
Message option. In essence, this is a way of opting out of
the application state message.
Fail If Quiescing
N
Select the Fail If Quiescing check box to prevent this
subscriber from holding up a queue manager quiesce
operation. If the queue manager does terminate, the
activity attempts to reconnect indefinitely.
GMO Convert
N
Enable the get message option "Convert".
Require Client
Confirmation
N
When selected a message confirm activity is required to
commit the consumption of this message.
Disable Connection
Reuse
N
This option is available when using client confirmation.
Enable this option to release the connection after the
message is confirmed. If the connection is pooled, it is
released back to the pool, so if the objective is to clean up
the connection it is best to use a non-pooled connection.
Message Content Type
N
Choose the way that the message body will be represented
on the output schema.
•
Binary The message is an array of bytes suitable for use
by the Data Conversion Palette activities.
•
Text The message is a string. The message will be
decoded using c h a r a c t e r s e t for the message, or 8 1 9 if
none is provided.
Characterset 819 is the Java API default.
•
Schema The message will be formatted according to
the schema provided in the Message Body Fields field.
Values for this schema will appear in the Output tab.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
106
| Chapter 3
WebSphere MQ Palette
Table 28 Fields in the Configuration Tab: WebSphere MQ Subscriber Activity (Cont’d)
Field
Global
Variable
Message Body Fields
Y
Description
Provide the schema to be used in the Output tab, and at run
time to decode the contents of this message.
Advanced Tab
Table 29 lists and describes the fields in the Advanced tab.
Table 29 Fields in the Advanced Tab: WebSphere MQ Subscriber Activity
Field
Global
Variable
Enable Polling
N
Description
When selected, the activity instantiates a connection to the
queue manager and opens the topic. It then periodically
issues timed gets on the topic where the timeout value is
equal to the polling timeout and the period between gets is
equal to the polling interval. However, if there are multiple
messages available, they are processed without an
intervening polling interval, thus diminishing application
latency.
When clear the Enable Polling check box, the activity waits
indefinitely on the topic, processing messages as they arrive.
If the queue manager connection fails, the activity attempts
to reconnect based on the reconnection interval.
Note that a poor choice of polling interval and polling
timeout values could impose a high overhead on the engine
as well as the queue manager to which the activity is
connected. Use values here which take into account the
latency in the network between this activity and the queue
manager, as well as the processing demands you are willing
to place on that queue manager.
Polling Interval
Y
When polling is enabled, this is the interval at which a new
polling cycle is initiated. Specify time in milliseconds.
Valid range: 1 0 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 107
|
Table 29 Fields in the Advanced Tab: WebSphere MQ Subscriber Activity (Cont’d)
Field
Global
Variable
Polling Timeout
Y
Description
If polling is enabled, this is the timeout value for each
individual listen. The value specified here must be
significantly smaller than the P o l l i n g I n t e r v a l . This
minimizes the number of concurrent connections to the
queue and reduces the processing resources required.
Specify time in milliseconds.
Valid range: 1 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0
Reconnection Interval
Y
The length of time, in milliseconds, that the listener waits
between attempts to reconnect to the topic.
This setting is used only when polling is disabled. If polling
is not enabled, the listener listens indefinitely on the queue.
However, if an error occurs and the queue manager is
subsequently unavailable (shut down for instance), this
value is the number of milliseconds between reconnection
attempts.
Valid range: 2 0 0 0 to 1 0 0 0 0 0 0
Default: 1 0 0 0 0
Application Properties
Y
If the messages expected on this topic contain application
specific topics, a shared schema resource must be created to
represent those properties and it must be mapped here.
Messages which contain any or all of these properties will
have them provided as input to the process created by this
starter.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
108
| Chapter 3
WebSphere MQ Palette
Table 29 Fields in the Advanced Tab: WebSphere MQ Subscriber Activity (Cont’d)
Field
Global
Variable
Description
Property Control
N
Select one of the following settings:
•
PROPERTIES_AS_Q_DEF
•
PROPERTIES_COMPATIBILITY
•
PROPERTIES_IN_HANDLE
•
PROPERTIES_FORCE_MQRFH2
This setting overrides the queue's property control setting
and can be used to force message properties into a format
which is usable by the plug-in. In general, if a legacy
application sends properties in a message and the plug-in
does not detect them, setting this to I N _ H A N D L E is the best
option. The other options are provided for completeness.
Error Output
N
Enable this option to cause the subscriber to create a process
consisting of only a B w m q E x c e p t i o n object when it
encounters an error.
If the Error Output check box is not selected, the subscriber
simply logs such conditions and continues.
Misc Tab
This tab contains fields that can be used by the activity to effect workload
balancing across threads and even engines.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 109
|
Table 30 lists and describes the fields in the Misc tab.
Table 30 Fields in the Misc Tab: WebSphere MQ Subscriber Activity
Field
Global
Variable
Description
Sequencing Key
N
This field can contain an XPath expression that specifies
which processes must run, and in which in order. Process
instances with sequencing keys that evaluate to the same
value are executed sequentially in the order the process
instance was created.
See the TIBCO ActiveMatrix BusinessWorks Process Design
Guide for more information about controlling the execution
order of process instances and about XPath expressions.
Custom Id
N
This field can contain an XPath expression that specifies a
custom ID for the process instance. This ID is displayed in the
View Service dialog of TIBCO Administrator, and it is also
available in the $ _ p r o c e s s C o n t e x t process variable.
Output Tab
Table 31 lists and describes the fields in the Output tab.
Table 31 Fields in the Output Tab: WebSphere MQ Subscriber Activity (Sheet 1 of 5)
Field
Global
Variable
Description
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on input.
•
destination Documents the destination for this message.
This field contains the complete topic string for the
message.
•
destqmgr Documents the remote queue manager
specified on the input schema.
•
correlationId Documents the message correlation ID. In
most cases this is an internal queue manager value and is
not available for filtering purposes.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
110
| Chapter 3
WebSphere MQ Palette
Table 31 Fields in the Output Tab: WebSphere MQ Subscriber Activity (Sheet 2 of 5)
Field
Global
Variable
Description
mqproperties
N
•
messageId Documents the message ID.
•
characterSet Documents the character set the queue
manager used to process this message.
•
alternateUserId If an alternate userid was in effect for the
activity it will be reflected here.
•
accountingToken The accounting token that allows work
done as a result of the message to be appropriately billed.
•
applicationIdData Application ID data. This is application
data was provided by sender of the message.
•
applicationOriginData Additional information about the
origin of the message provided by the sender of the
message.
•
putApplicationType The type of application that put the
message. Documented enumerations are:
MQAT_AIX
MQAT_CICS
MQAT_DOS
MQAT_IMS
MQAT_MVS
MQAT_OS2
MQAT_OS400
MQAT_QMGR
MQAT_UNIX
MQAT_WINDOWS
MQAT_JAVA
MQAT_UNKNOWN
MQAT_NO_CONTEXT
MQAT_CICS_VSE
MQAT_VMS
MQAT_GUARDIAN
MQAT_VOS
MQAT_DEFAULT
MQAT_NSK
MQAT_CICS_BRIDGE
MQAT_NOTES_AGENT
MQAT_WINDOWS_NT
MQAT_IMS_BRIDGE
MQAT_XCF
MQAT_NO_CONTEXT
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 111
|
Table 31 Fields in the Output Tab: WebSphere MQ Subscriber Activity (Sheet 3 of 5)
Field
Global
Variable
Description
mqproperties
N
•
putApplicationName The name of the application that put
the message, if one was provided.
•
userId the effective user ID used to connect to the queue
manager.
•
replyToQueueName The name of the queue to which a
reply must be sent if the message is a request.
•
replyToQmgrName If this message arrived by way of a
remote queue manager specification, this field documents
the queue manager to which this subscriber is connected.
•
format A name that describes the nature of the data in the
message.
•
expiry The expiration time (in tenths of a second), after
which the message is eligible to be discarded by the
queue manager. This contains whatever value was used
when the message was sent.
•
priority The priority (1-9) with which the message was
sent.
•
reportOptionPan Set to t r u e when the positive
acknowledgment flag in the r e p o r t field on.
•
reportOptionNan Set to t r u e when the negative
acknowledgment flag in the r e p o r t field on.
•
report Documents the report options in effect for this
message.
•
encoding The encoding value is described in the
WebSphere MQ API documentation. It is used by
methods that set and get numeric values from the
message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
112
| Chapter 3
WebSphere MQ Palette
Table 31 Fields in the Output Tab: WebSphere MQ Subscriber Activity (Sheet 4 of 5)
Field
Global
Variable
Description
mqproperties
N
•
messagetype Enumerated value indicating the message
type, where:
—
8
is Datagram.
—
2
is Reply.
—
4
is Report.
—
1
is Request.
•
backoutCount The number of times this message was
backed out before being committed.
•
feedback If the message was a Report message, this field
defines the nature of the report. Defaults to 0 for non
report messages.
•
version Documents the version of the message.
•
putDateTime The time that the message was placed onto
the topic.
•
groupStatus Contains M S G _ N O T _ I N _ G R O U P. Grouped
messages are not supported by the subscriber.
appProperties
N
This field maps the application properties present in the
received message to the schema attached to the activity.
Properties which are missing or not present in the schema are
not shown here.
dynamicProperties
N
This optional node provides an alternative way to specify
application properties and is patterned after a similar node
on the JMS palette objects.
Each property is specified in its own "property" node and
contains the name, type, and value for the property.
Supported types are: String, Boolean, Byte, Short, Int, Long,
Float, and Double. String is the default value. This node can
be directly mapped between JMS and MQ messages.
bytes
N
The output body of the message. Typically, this byte array is
to be mapped as input to a Data Conversion Plug-in parse
activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Subscriber Activity 113
|
Table 31 Fields in the Output Tab: WebSphere MQ Subscriber Activity (Sheet 5 of 5)
Field
Global
Variable
text
N
Description
Contains the body of the message converted to text using the
message's c h a r a c t e r S e t field.
Appears for text type messages.
messageFields
N
Contains the message body formatted using the schema
specified in the Configuration tab.
Displayed for schema-based messages only.
Error Output Tab
Errors produced by this activity are written to the log and the activity continues to
listen. If the polling interval or the reconnection interval is small and the activity
is attempting to reconnect to an unavailable queue manager, it might produce a
lot of output in the activities log.
If the Error Output check box in the Advanced tab of the WebSphere MQ
Subscriber activity is selected, errors produced by this activity throw an exception
of the type B w m q E x c e p t i o n .
Table 32 shows the fields displayed in the Error Output tab after the Error Output
check box is selected:
Table 32 Fields in the Error Output Tab: WebSphere MQ Subscriber Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the
exception that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the m s g field it is
provided here, otherwise this is a copy of m s g .
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
114
| Chapter 3
WebSphere MQ Palette
WebSphere MQ SyncPoint Activity
This activity commits or backs out all resources outstanding on the configured
connection. Previous Get and Put activities in this process which had the
"Commit Via SyncPoint Activity" option enabled and used the same connection
configured for this SyncPoint activity will have created a unit of work. The
commit flag on this activities input schema determines whether the unit of work
will be committed or backed out.
It is important, when using the SyncPoint activity that all activities using the
configured connection resource are participating in the unit of work. Any activity
not so configured accidentally commits resources intended to be controlled by
this SyncPoint activity.
If a SyncPoint activity is not encountered in the normal course of the process and
a unit of work has been created, it will be backed out at the end of the process.
Configuration Tab
Table 33 lists and describes the fields in the Configuration tab.
Table 33 Fields in the Configuration Tab: WebSphere MQ SyncPoint Activity
Name
Global
Variable
Description
Name
N
Name of the activity.
Description
N
Description for the activity.
Connection
Resource
Y
This required parameter associates the activity with the Connection
Resource for which a unit of work must be processed, either committed
or backed out.
Input Tab
Table 34 lists and describes the fields in the Input tab.
Table 34 Fields in the Input Tab: WebSphere MQ SyncPoint Activity
Name
Global
Variable
Description
InteractionInput
N
The root node for all the input provided to the activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ SyncPoint Activity 115
|
Table 34 Fields in the Input Tab: WebSphere MQ SyncPoint Activity
Name
Global
Variable
commit
N
Description
Set this boolean field to "t r u e " to cause the unit of work to be
committed or "f a l s e " to back it out.
Error Output Tab
Errors produced by this activity throw an exception of the type BwmqException.
Table 35 Fields in the Error Output Tab: WebSphere MQ SyncPoint Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the exception
that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the msg field it is
provided here, otherwise this is a copy of msg.
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
116
| Chapter 3
WebSphere MQ Palette
WebSphere MQ Inquire Activity
This activity inquires about the current state of a queue. It is primarily intended to
obtain the depth of the queue.
Configuration Tab
Table 36 lists and describes the fields in the Configuration tab.
Table 36 Fields in the Configuration Tab: WebSphere MQ Inquire Activity
Name
Global
Variable
Description
Name
N
Name of the activity.
Description
N
Description for the activity.
Connection
Resource
Y
The connection resource to be used to obtain a connection to the
queue manager.
Queue Name
Y
The name of the queue in which the inquiry is performed.
Input Tab
Table 37 lists and describes the fields in the Input tab.
Table 37 Fields in the Input Tab: WebSphere MQ Inquire Activity
Name
Global
Variable
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 The destination queue manager can be
overridden at run time. This queue manager must be
configured such that it is accessible from the configured
queue manager through transmission queues and channels.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
WebSphere MQ Inquire Activity 117
|
Output Tab
Table 38 lists and describes the fields in the Output tab.
Table 38 Fields in the Output Tab: WebSphere MQ Inquire Activity
Name
Global
Variable
Description
InteractionOutput
N
The root node for all the output provided by the activity.
mqproperties
N
The node containing all the message header fields (plus the
destination override) which are relevant on input.
responsetimemillisec
N
•
destination Documents the actual destination used for
the inquiry.
•
destqmgr Documents the actual queue manager used for
the inquiry.
•
depth Documents the current depth of the queue (that is,
how many messages are in the queue).
•
maxDepth Documents the configured maximum depth
of the queue.
•
maxMsgLength Documents the configured maximum
size of any individual message in the queue.
•
type Documents the configured queue type.
•
shareability Documents the configured shareability for
the queue.
•
triggerDepth Documents the configured trigger depth
for the queue.
The number of milliseconds the inquiry takes.
Error Output Tab
Errors produced by this activity throw an exception of the type B w m q E x c e p t i o n .
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
118
| Chapter 3
WebSphere MQ Palette
Table 39 Fields in the Error Output Tab: WebSphere MQ Inquire Activity
Exception
Description
msg
The textual message as it relates to the direct or underlying cause of the
exception that caused the activity to fail.
msgCode
The error message identifier for this message.
errorMessage
If extra information is available to augment that provided in the msg field it is
provided here, otherwise this is a copy of msg.
mqCompCode
The completion code for the failing WebSphere MQ API call if applicable.
mqReasonCode
The reason code for the failing WebSphere MQ API call if applicable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
| 119
Chapter 4
Sample ActiveMatrix BusinessWorks
Projects
This chapter describes the sample ActiveMatrix BusinessWorks project included
with the plug-in.
Topics
•
Opening the Sample Project, page 120
•
Using the Sample Project, page 121
•
Overview of Samples, page 122
•
Connections, page 123
•
Schemas, page 125
•
Processes, page 127
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
120
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Opening the Sample Project
The Plug-in contains a sample ActiveMatrix BusinessWorks project, which is
located in the directory
TIBCO_HOME\ b w \ p l u g i n s \ m q \ s a m p l e s \ b w m q S a m p l e . z i p .
To open the sample project in TIBCO Designer, do the following:
1. Unzip the b w m q S a m p l e . z i p file.
2. Start TIBCO Designer and click Open existing project.
3. On the Open Project page, click the Select A File From The File System icon
besides the Project Directory filed. Navigate to the directory where the
unzipped file is located. For example:
TIBCO_HOME\ b w \ p l u g i n s \ m q \ s a m p l e s \ b w m q S a m p l e
4. Click OK.
Figure 7 The Sample Project
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Using the Sample Project 121
|
Using the Sample Project
This sample project is intended to help familiarize you with the components of
the TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ, as well as
the modes these components were intended to be used in.
Not all of the sample activities are documented here, see WebSphere MQ Palette
for more information.
Recommended Software
The sample project references two additional Plug-in products:
•
TIBCO ActiveMatrix BusinessWorks Plug-in For Data Conversion
To run the samples without the Plug-in for Data Conversion, replace the
references with an XPath expression that provides some input to the affected
activity.
•
TIBCO BusinessWorks XA Transaction Manager
The XA Transaction sample cannot be run without the transaction manager
plug-in.
These Plug-ins are frequently used with the Plug-in for WebSphere MQ.
However, most samples can still be run if you do not have either plug-in.
Required Queues and Models
You must create these basic queues to use the sample:
•
BWMQ.APP
•
BWMQ.DEST.QUEUE
•
BWMQ.FROM.QUEUE
•
BWMQ.REPLY
•
BWMQ.REPORT
You must also create these basic model queues:
•
BWMQ.MODEL—a model for a temporary dynamic queue.
•
BWMQ.DURABLE.MODEL—a model for a permanent dynamic queue.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
122
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Overview of Samples
The sample contains folders for C o n n e c t i o n s , P r o c e s s e s , and S c h e m a s .
•
The activities contained in the C o n n e c t i o n s folder are described in
Connections on page 123.
•
The resources contained in the S c h e m a s folder are covered in Schemas on
page 125.
•
The activities and samples in the P r o c e s s e s folder are described in Processes
on page 127.
Not all of the capabilities of the Plug-in are demonstrated by these samples. If you
have general questions about the capabilities of the product, visit
https://community.tibco.com/.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Connections 123
|
Connections
The Connection resource represents the WebSphere MQ connection and contains
all the information required to instantiate one. Configure the connection resource
to connect to the queue manager that you intend to test with.
For best results, use a remote connection for most Designer activities. This
prevents difficulties that may occur when attempting to interrupt a connection to
the queue manager over a local connection.
Figure 8 The Connection Resource
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
124
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
The Connection resource can be used to configure two types of connection:
•
Remote Binding It connects to the queue manager using TCP/IP.
•
Local Binding It connects to the queue manager using the Java Native
Interface (JNI). Note that this binding type is not recommended for use during
testing in TIBCO Designer because locally bound connections cannot be
interrupted using the Stop button.
Depending on which type of binding is selected, a different subset of fields are
enabled to create the connection. These fields are described in Table 3, Fields in
the Configuration Tab: WMQ Connection Resource, on page 27.
Use the Test button at the bottom of the Configuration tab to create a connection
to the WebSphere MQ Queue Manager using the parameters you have provided.
JMS Connection Folder
The C o n n e c t i o n s folder also contains a JMS Connection resource, which is used
in the XA transaction examples. These samples are described in Transactions on
page 149.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Schemas 125
|
Schemas
The S c h e m a s folder contains four schema resources that are used in this project:
•
The WebSphere MQ Application Properties schema, which is created from the
JMS Application Properties resource that is used to map various properties
into and out of a WebSphere MQ message.
•
The Data Conversion Plug-in copy book schema. The Plug-in for Data
Conversion can take any memory layout represented by a copy book and
convert it to an XML schema that is used in ActiveMatrix BusinessWorks to
translate canonical data into formats that adhere to the definitions in the copy
book. The conversion activities are called render and parse. The TIBCO
ActiveMatrix BusinessWorks Plug-in for WebSphere MQ was designed to
work hand in hand with the Plug-in for Data Conversion to facilitate
communication with WebSphere MQ applications on any platform.
•
The WebSphere MQ Message Body schema. Schemas of this sort are used for
sending and receiving messages whose contents conform to the WebSphere
MQ API for reading and writing variables into a message body.
The application properties resource allows you to define a group of application
specific name value pairs to be included with a sent message, or to be extracted
from a received one. If one is selected for a WebSphere MQ Plug-in activity, that
activity's input or output schema includes fields that relate to this resource. You
can then map data into or out of them for use in your application.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
126
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 9 Schemas—The WebSphere MQ Application Properties Resource
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 127
|
Processes
The P r o c e s s e s folder contains samples of most basic process activities. These
activities are described in the following sections:
•
Basic Send and Receive, page 127
•
Dynamic Destinations, page 132
•
Message Groups, page 136
•
Report, page 138
•
Request, page 144
•
Segmented Messages, page 146
•
Transactions, page 149
Basic Send and Receive
The first and simplest activity is a basic Send and Receive, contained in the
B a s i c S e n d R e c e i v e folder. This activity puts a message in the queue, then
retrieves the message using the Get activity.
Configuring the Put Activity
Figure 10 shows the configuration panel of the Plug-in Put activity. In this sample,
the Put activity is minimally configured. The sample puts a very simple datagram
message on the queue B W M P . A P P. The minimum configuration for a Put activity
requires only a connection resource and a queue name.
Click the Choose Queue buttons besides each of the queue and model fields to
select the queues and models you would like to connect to.
The Test button at the bottom of the panel creates a connection to the configured
queue manager and instantiates an instance of the configured queue object. If
there are any errors in the configuration or when creating the connection, an error
message appears. If the connection is successfully created, some minimal
information about the selected queue is displayed.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
128
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 10 The Put Activity—Configuration Tab
Configuring the Input Schema
Figure 11 shows the Input tab for the Put activity. This tab exposes all the
modifiable input fields in the message header, as well as the destination and
payload (bytes) fields.
Because this is a "simple" example, the payload for this message is supplied by an
XPath expression which converts a string into a base 64-encoded byte array:
tib:string-to-base64($_processContext/ns:ProcessContext/ProjectName)
You can use this technique to convert a string to a byte array for any field that
requires it.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 129
|
Figure 11 The Put Activity—Input Tab
When the activity is run, the input data can be seen in its base 64 form, as shown
in Figure 12.
Figure 12 The Put Activity—Input Data
Reviewing the Output
The Output tab, shown in Figure 13, documents all of the fields as they were
modified by the queue manager during the put operation. Other activities in this
sample illustrate the use of the Input and Output fields.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
130
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 13 The Put Activity—Output Data
Configuring the Get Activity
Once a message exists in the queue, you can use the Basic Get sample in this
folder to retrieve it.
As with the Put activity, the minimal configuration for a Get activity requires
selecting the connection resource and the queue, as shown in Figure 14.
The default behavior of the Get activity is to wait forever for a message in the
queue. Although this sample uses the default, it is more common to place an
upper limit on how long the activity have to wait for a message.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 131
|
Figure 14 The Get Activity—Configuration Tab
The Input and Output tabs are also similar to those of the Put activity. Run the
activity and examine the Output tab, as shown in Figure 15:
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
132
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 15 The Get Activity—Output Tab
Notice that the output from the activity is similar to the output of the Put activity,
with the exception of the t e x t field which is the payload.
These two simple activities can be combined in many ways using more of their
options to create sophisticated queuing applications. The following sections
explain the rest of the activities in this sample application focussing on the
nuances that can be achieved via the other options present on the activity panels.
Dynamic Destinations
The D y n a m i c D e s t i n a t i o n s folder contains the Dynamic Destinations sample.
Dynamic destinations are queues which do not exist until they are opened for
read or write. These queues are patterned after a model queue (which you must
create), and they can be of a temporary or permanent nature.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 133
|
Temporary dynamic queues disappear as soon as the last subscriber and message
are gone from the queue.
Permanent dynamic queues behave much like normal queues in that they survive
queue manager restarts and retain their messages as would a normal queue. The
main difference is that they can be created and deleted by an application, which
frees administrators from some of the maintenance obligations for applications
designed to use them.
A dynamic queue can be created either by the Put, Get or Listen activity. The most
common use of dynamic queues is for the reply messages.
Configuring a Queue Listener to Use a Dynamic Queue
In this example, a queue listener, which is a process starter, is configured to use a
dynamic queue whose name and model are taken from global variables. For
dynamic queues which have a fixed instead of dynamic name, global variables
are a good way to let message senders and receivers know what names to use.
All activities that use dynamic destinations check for the existence of the queue
before attempting to create it. If it exists, they open it as though it were a normal
queue. In this sample, the listener will typically start before the sender and
therefore will create the queue if it does not exist.
This listener monitors the specified dynamic destination and logs the arrival of
any messages. Whether this queue is temporary or permanent depends on the
model queue chosen. Using this sample, you can experiment with both temporary
and permanent queues to learn about the lifetime of the resulting dynamic queue.
The D y n a m i c D e s t i n a t i o n s folder has an activity called G e t F r o m D y n a m i c D e s t
which has been configured to use a Get operation instead of a Listener. It must be
explicitly started to receive the message.
Figure 16 shows the Configuration tab for the queue listener. Note that the Test
button does not attempt to create a dynamic queue. It merely checks that the
model specified exists.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
134
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 16 Dynamic Destinations—Listen Activity Configuration Tab
Sending a Message to a Dynamic Queue
The Put activity shown in Figure 17 sends a message to the dynamic queue
listener that is created previously. If the listener is started before the Put activity is
run, the queue already exists and the Put activity simply opens it for output and
places the message there. If the listener is not started first, the Put activity itself
creates the queue before placing the message in it.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 135
|
Figure 17 Dynamic Destinations—Put to a Dynamic Queue
If you select a temporary model queue for this sample, two scenarios are possible
regarding the lifetime of the queue:
1. If the Listener activity is used to monitor the queue and it is started before the
Put activity is run, the temporary queue exists for as long as the Listener
activity is running.
2. If the explicit Get activity is used to monitor the dynamic queue, it ends as
soon as the message arrives. Because this leaves no client attached to an empty
queue, the queue is deleted by the queue manager.
Close Options
If you change the model queue used in these activities from a temporary one to a
persistent one, the resulting queue remains after the activities have finished.
When using a persistent dynamic queue, you can modify this behavior using the
Close Options dialog box in the Get activity:
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
136
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
•
If you choose Delete and the queue is empty after the Get activity, the
permanent dynamic queue is deleted.
•
If you choose Purge Delete, the queue and any remaining messages are
deleted.
Note that you must have the appropriate authorization to perform these actions.
Message Groups
The sample contained in the M e s s a g e G r o u p s folder is very similar to the previous
one except that it demonstrates the handling of large messages using message
groups.
Message groups, sometimes called logical messages, are a group of closely related
messages which are created and meant to be processed by the same application.
An obvious example is the case where a batch process creates a number of
messages specifically for consumption by another batch process.
The plugin provides two mechanisms for handling logical messages:
•
BatchGroup For small logical messages the BatchGroup mechanism (as
shown in Figure 18) is appropriate.
•
CustomGroup For larger groups which may not fit into memory a looping
approach using CustomGroup is more appropriate.
Even logical message members can be segmented and the plug-in fully supports
this.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 137
|
Figure 18 Message Groups—MultiMessage Configuration
If you observe the queue after such a put, you will see a series of messages on it
corresponding to your large message. This sample writes a group of four
messages on the B W M Q . A P P queue, as shown in Figure 19.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
138
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 19 Send Grouped Message
Report
The R e p o r t s folder contains a sample that demonstrates the use of report
messages.
In WebSphere MQ, it is possible to set options on a put message which instruct
the queue manager to provide status messages related to the progress of the
message through the queuing system. These confirmation messages are
automatically delivered to the destination in the message's r e p l y T o Q u e u e N a m e
header field.
To configure these status messages in the Plug-in, use the settings located in the
Configuration tab of the Put activity. Select the type of confirmation message you
want using the Report Confirmation field.
It is up to you to monitor the reply-to queue for confirmations.
This folder contains three activities:
•
ReportSend Send a message with a report request.
•
ListenAndReply Listen for the business message and reply to the sender.
•
ReportListen Listen for the reports.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 139
|
To use this sample, load all three activities. The two process starters, ReportListen
and ListenAndReply, start listening immediately. When you run the ReportSend
activity, it sends a message to the ListenAndReply activity. The queue manager
then sends a report to the ReportListen activity.
The TIBCO ActiveMatrix BusinessWorks Plug-in For Data Conversion
This sample also introduces the use of the The TIBCO ActiveMatrix
BusinessWorks Plug-in For Data Conversion to provide the input for the
WebSphere MQ activities. If you do not have this Plug-in, simply remove those
activities and replace the inputs with XPath statements like the ones in previous
samples. See Configuring the Input Schema on page 128 for an example.
The Data Conversion Plug-in takes information from the canonical model in
ActiveMatrix BusinessWorks and transforms it to a byte array which conforms to
the copy book from which it was configured. See the TIBCO ActiveMatrix
BusinessWorks Plug-in For Data Conversion documentation for a detailed
explanation of its use.
Configuring the Put Activity for Reports
Figure 20 shows the configuration of the Put activity to request a "Confirm on
Delivery" message from the queue manager. Note also that this activity has been
configured with a schema resource in the Application Properties field. This
causes the fields defined in that schema to be available in the Input tab of the Put
activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
140
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 20 Reports—Requesting a Confirm on Delivery Report
Configuring the Input Schema
When the Put activity has been associated with a schema resource using the
Application Properties field, the fields defined in that schema are available in the
Input tab.
The contents of the application properties node can be filled out with type
checked variables, or they can be mapped from a suitable source. These variables
are made available to the receiving application. If the receiving application is
another WebSphere MQ activity, it can be made aware of these properties simply
by mapping the same schema to that activity.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 141
|
Figure 21 shows the sample Input tab, which maps these fields using the
application properties schema:
—
FirstName
—
LastName
—
Age
—
Weight
—
AstroSymbol
Figure 21 Reports—Put Activity Input Tab and Application Properties Node
Note that in this input schema there is a variable mapped to the c o r r e l a t i o n I d
field. The presence of this variable causes that correlation ID to be placed on the
message. Message receivers can select messages by either the correlation ID or
message ID. Message IDs tend to be unique, whereas correlation IDs may be
common to a whole group of messages that relate to a particular unit of work.
The message listener in this sample is configured to filter on this correlation ID.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
142
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Filtering Report Messages
The ListenAndReply process listens for a message and sends the requested reply
message. The queue manager takes care of sending the report to the intended
destination without any application involvement.
Because a process starter has no Input tab on which to map things like correlation
IDs, the Advanced panel of this activity has fields for the correlation and message
IDs. Figure 22 shows the settings in the Advanced tab.
Figure 22 Reports—Listener Activities and Filter Fields
Note that in WebSphere MQ these IDs are binary 24-byte fields and they are never
translated at any point in the infrastructure. However, configuration variables in
ActiveMatrix BusinessWorks are strings. Therefore if it is necessary to filter using
a correlation ID in ActiveMatrix BusinessWorks, be careful to choose an ID that
can be reliably represented as a string to this listener.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 143
|
Viewing the Report Message
The Output tab of the Report Monitor activity shows the nature of the report
message sent by the queue manager.
Figure 23 Reports—Report Message Output Tab
Information about the fields presented here and in all other message receive
operations is briefly documented in this manual. More detailed descriptions can
be found in the IBM WebSphere MQ documentation.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
144
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Request
A common use case in all messaging applications is for a client application to
send a message to a server application from which it expects a reply. This scenario
is demonstrated in the R e q u e s t sample folder.
To make the application architecture flexible, it is best to have the requestor
dictate the queue in which the reply is to be sent. This is done using either the
Reply To Queue field of either the Configuration tab of the Put activity, or the
r e p l y T o Q u e u e N a m e field in the activity’s Input schema. While any message can
sport a reply-to field, the special Request message type mandates its presence.
Figure 24 shows the Configuration tab for the sample put message activity. Note
that the selected message type is R e q u e s t .
Figure 24 Requests—Message Type
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 145
|
When R e q u e s t is selected in the Message Type list, the Reply To Queue field is
enabled. However, the field is not required because it is possible to dynamically
map the reply-to queue using the input schema.
Note that when the Request message type is chosen, the option for report
confirmation messages is disabled. This is because report messages use the
reply-to destination name, making these fields mutually exclusive.
If the specified reply to queue is dynamic, it is best to use a permanent dynamic
queue to simplify application design. In this sample, the Reply To Queue name is
mapped in the input schema using a global variable (see Figure 25). In the case
where a configuration variable is present and the input schema is mapped, like
this, the input schema takes precedence in all cases.
Figure 25 Requests—Mapping the Reply to Queue Name from a Global Variable
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
146
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
The destination for the server activities response is dynamically mapped from the
source messages reply to field. This allows the conversation between the two
activities to be completely dynamic.
Segmented Messages
Message segmentation is a technique used to split large messages into smaller
ones called "segments" which can fit into the buffers of the various channels
encountered in the messaging system. The plug-in allows messages to be
explicitly segmented, whereby you provide the segment size, or have the queue
manager segment the message as necessary along the way. The Put activity
provides explicit configuration options for segmenting messages but the Get and
Listener activities support segmented messages implicitly. They will always be
returned as a single large message.
Sending Segmented Messages
Explicityly segmented messages are configured on the MultiMessage tab of the
Put activity. When Explicit or Both is selected from the Segmentation Support
list, the Maximum Segment Size field is enabled and you can enter the maximum
size for the individual segments.
These settings are shown in Figure 26.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 147
|
Figure 26 Segmented Messages—Put Activity MultiMessage Tab
CustomGroup Logical Messages
Because the input and output documents of activities are not large enough to
accommodate some logical messages, or the interaction model is unbounded
(where the size of the message to put is unknown) it is sometimes necessary to
process logical messages in a loop. The plug-in supports this via selecting
CustomGroup from the Multi Message Support list in the MultiMessage tab of
the Put and Get activities. See Figure 27.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
148
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 27 Custom Group
For a loop of (for instance) size 20, the Put activity can configure its input schema
field l a s t M e s s a g e I n G r o u p to terminate the logical message like this:
if($loopcount = 20) then "true" else "false"
If the l a s t M e s s a g e I n G r o u p field is not correctly configured an invalid unusable
group will result. The plug-in cannot prevent this situation, however when the
process ends there will be a warning about incomplete groups in the log.
To receive a logical message in a loop configure a Get activity (with
CustomGroup) in a loop such that the loop is terminated when the last message
arrives. See Figure 28.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 149
|
Figure 28 Custom Group of the Get Activity
Note the formula:
$WebSphere-MQ-Get-Activity/InteractionOutput/lastMessageInGroup =
"true"
Used in conjunction with the All Messages Available and Get Ordered flags the
Get activity can process messages either as they are placed on the queue or after
the logical message is complete. If it is necessary to process an incomplete
message (perhaps for recovery purpose) these flags must be off.
Transactions
WebSphere MQ queue managers support the XA Transaction architecture, and
both the Get and Put activities in this Plug-in can also participate in XA
transactions. The Transactions folder contains sample Put and Get activities that
use XA transactions.
To run this sample, you must have installed and configured the TIBCO
BusinessWorks XA Transaction Manager. Get and put activities that fall inside an
XA transaction group automatically participate in the transaction. This sample
demonstrates commit coordination between JMS and WebSphere MQ.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
150
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 29 XA Transaction—Configuration
In this case both a simple JMS and WebSphere MQ message are placed on queues.
You can start monitoring activities if you want. When running, you will observe
that both the JMS and WebSphere MQ messages are sent to their respective
queues.
The run shown in Figure 30 indicates that messages to both queues were
successfully delivered.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Processes 151
|
Figure 30 XA Transaction—Success
In Figure 31, an intentional error has been introduced to cause an XA rollback on
both resource managers. The two receivers have not received any messages and
the respective queues are empty.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
152
| Chapter 4
Sample ActiveMatrix BusinessWorks Projects
Figure 31 XA Transaction—Failed
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
| 153
Appendix A
Error Messages
This appendix shows the error messages of TIBCO ActiveMatrix BusinessWorks
Plug-in for WebSphere MQ.
Table 40 Error Messages (Sheet 1 of 8)
Message
Identifier
Message
Resolution
BWMQ-100100
Error; No such connection:
[%1]
The activity is configured with a nonexistent connection.
BWMQ-100500
Warning exception returned
from the WebSphere MQ java
library: [%1]
The activity has completed with a
warning type exception from the
messaging layer.
BWMQ-100501
Warning: backout failed: [%1]
The activity was attempting the backout
of a unit of work and got an error. The
connection is broken due to network or
queue manager issues.
BWMQ-100502
the activity has been
configured to wait
indefinitely and to receive
batch groups. If the activity
is canceled before the group
is complete one or more
messages may be lost. It is
preferable to poll for groups
and logical messages"
No action.
BWMQ-100200
Null not permitted for field
[%1]
A required field is not configured, so
provide a value for it.
BWMQ-100201
Field not numeric: [%1]
A numeric field contains non-numeric
characters; remove them.
BWMQ-100202
Global value not mapped for
field: [%1]
A field is mapped to a non-existent
global variable. Correct the field or
provide the global variable.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
154
| Appendix A
Error Messages
Table 40 Error Messages (Sheet 2 of 8)
Message
Identifier
Message
Resolution
BWMQ-100203
Value for out of range for
field: [%1] actual: [%2] min:
[%3] max: [%4]
Correct the value.
BWMQ-100204
Value too long for field: [%1]
Shorten the indicated value.
BWMQ-100205
Value "[%1]" for field [%2]
contains whitespace
Remove the whitespace characters from
the named field.
BWMQ-100206
Error: [%1]
Contact support with the contents of the
error and any stacktraces that might be
available.
BWMQ-100207
No connection configured
Configure a valid connection for the
activity.
BWMQ-100208
Error sending datagram: [%1]
An error occurs when calling the "put"
API call. Examine the error code
provided and correct the condition. If
unsuccessful contact support.
BWMQ-100209
Error connecting to queue
manager: [%1]
An error occurs when creating a
connection to the queue manager.
Examine the error code provided and
correct the condition. If unsuccessful
contact support.
BWMQ-100211
Internal configuration error:
[%1]
This is an internal error, and contact
support.
BWMQ-100227
Error Opening:[%1] [%2]
Examine the error code to determine
why the destination cannot be opened
and correct the condition.
BWMQ-100231
Error closing destination [%1]
with close option [%2],
message: [%3]
An error occurs when closing a
destination. In most cases, no action is
required. If this error occurs regularly
contact support.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Error Messages 155
|
Table 40 Error Messages (Sheet 3 of 8)
Message
Identifier
Message
Resolution
BWMQ-100232
Threadpool size must be zero
for transactional activities
Get activities cannot use a pooled thread
when participating in an XA transaction.
Set the T h r e a d p o o l S i z e parameter to
zero.
BWMQ-100233
Activity not within an
XA-Transaction group
An activity is configured in an XA
group, but no transaction context can be
found at run time. Correct the XA
transaction group configuration.
BWMQ-100235
Dynamic reply-to queue is
missing
A request type message is specified but
no reply to destination is provided.
Correct the configuration of the activity.
BWMQ-100236
Port out of range: [%1]
Specify a valid port number.
BWMQ-100237
Invalid port: [%1]
Specify a valid port number.
BWMQ-100238
Error processing credentials:
[%1]
An attempt to open the keystore failed
because of invalid credentials. Correct
the keystore password.
BWMQ-100239
Error; missing required
parameter: [%1]
The named parameter is required for the
activity to function. Provide the missing
parameter.
BWMQ-100213
MQGet failed [%1]
The get API call failed for the provided
reason. Correct the condition or contact
support.
BWMQ-100216
Error connecting to the local
queue manager because the
native libraries are not
available on
java.library.path: [%1]
A locally bound connection has been
defined, which requires the use of java
native libraries and those libraries are
not on the virtual machines library path.
Add the M Q _ H O M E / j a v a / l i b directory to
the native library paths specified in the
TRA file of the application, or reinstall
the plug-in.
BWMQ-100217
Connection resource local
bindings are not supported for
XA transactions
A remote or CCDT type connection is
required for activities to participate in an
XA transaction.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
156
| Appendix A
Error Messages
Table 40 Error Messages (Sheet 4 of 8)
Message
Identifier
Message
Resolution
BWMQ-100220
Connection resource not
specified
Provide a connection resource.
BWMQ-100221
Error; get timed out
A bounded get operation failed to
retrieve a message in the time allowed.
This is normal for a queue that does not
contain a message satisfying the filters
used.
BWMQ-100222
Failed to create destination
"[%1]":[%2]
The activity was unable to open the
named destination. The destination does
not exist or the application is not
authorized to access the destination.
BWMQ-100223
Configuration error; Model
queue not provided
A dynamic destination was specified but
no model was provided. Correct the
configuration.
BWMQ-100244
SSL connection failed due to
an invalid cipher or
certificate; probing for a
valid cipher returned: [%1]
The provided cipher specification did
not match the suite used by the queue
manager. If this message suggests one
that works, use it.
Reconfigure the queue manager to use a
supported cipher suite.
BWMQ-100245
No destination info is
specified in the configuration
therefore it MUST be mapped on
the input schema
Either provide a destination in the
configuration or dynamically in the
input schema.
BWMQ-100248
No destination info is
specified in the configuration
The listener or subscriber must be
configured with a destination.
BWMQ-100249
No name for durable
subscription
A name must be provided for durable
subscriptions.
BWMQ-100250
Filtered or ordered get issued
to a queue which is not indexed
The queue manager is probably hosted
on a z/OS system where indexing must
be explicitly specified. Either correct the
definition of the queue, or remove the
order option.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Error Messages 157
|
Table 40 Error Messages (Sheet 5 of 8)
Message
Identifier
Message
Resolution
BWMQ-100251
Malformed URL exception for
client connection table: [%1]
Client Data Definition Table URLs
support the file, http, and ftp protocols.
Ensure that the URL provided is valid by
testing it with a web browser.
Some examples of valid CCDT URLs are:
•
http://mqserver/htdocs/ipcc/AMQC
LCHL.TAB
•
ftp://mqftpserver/ftpdocs/ipcc/AM
QCLCHL.TAB (assuming that
anonymous FTP is enabled)
•
file://var/mqm/qmgrs/QMA/@ipcc
/AMQCLCHL.TAB
BWMQ-100252
Connections to multiple queue
managers within an XA
transaction is not supported
The XA transaction resource for
WebSphere MQ only works with a single
queue manager. Reconfigure the
transaction so that all queues are hosted
on the same queue manager.
BWMQ-100253
Failed to commit an operation:
backing out
The commit API call failed for a unit of
work. The unit of work is backed out
and the interaction fails. If this is not a
problem with the network or the queue
manager, contact support.
BWMQ-100254
Activity canceled
The application was stopped (or the
debugger Stop button was pressed)
while the activity was running. No
action is required.
BWMQ-100255
IOError processing a corrupt
message! This message cannot
be processed but has been
removed from the queue! Use
Explicit Commit to avoid this
in the future.
A message was removed from the queue
when not using an explicit commit.
Subsequent to its removal, an error
occurred in mapping the output schema
and the message was lost. Use the
explicit commit option to avoid this
situation in the future if schema
mapping errors are a possibility.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
158
| Appendix A
Error Messages
Table 40 Error Messages (Sheet 6 of 8)
Message
Identifier
Message
Resolution
BWMQ-100256
IOError processing the message
body using the provided schema
on field: [%1] at offset [%2]
An activity is configured to use a
message body schema; however the
message does not match the schema and
an error occurs. Use explicit commit to
avoid losing such messages, and take
steps to ensure that the schema matches
the messages received.
BWMQ-100257
IOError extracting the message
body contents; possible
incorrect character set
A encoding error was encountered when
extracting string fields from the
message. Correct the encoding used.
BWMQ-100258
IOError writing the contents
of a schema based message body
at field: [%1]
The data provided does not match the
type of the field. Correct the mapping.
BWMQ-100259
IOError reading the contents
of field [%1]; the name must
encode the length of the
field, for example
"fieldname_12"
The field is a string field and the
expected length of the field must be hard
coded in the name. Correct the
configuration.
BWMQ-100261
MQException during the put
process: [%1]
A put error occurred. If the problem
cannot be rectified using the error code
provided, contact support for assistance.
BWMQ-100262
MQException during a deferred
commit: [%1]
One or more activities were configured
to have their unit of work committed by
the SyncPoint activity and that activity
failed. The updates are rolled back.
Examine the exception provided to
determine why the commit failed and
contact support if the problem cannot be
solved.
BWMQ-100263
Error encoding dynamic
property: [%1]
The type provided for the property must
be compatible with the value provided.
Correct the mapping and retry.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Error Messages 159
|
Table 40 Error Messages (Sheet 7 of 8)
Message
Identifier
Message
Resolution
BWMQ-100266
Listener [%1], while
terminating, failed to restore
message with ID [%2] to any
dead letter queue. Message is
lost!
During shutdown processing, a listener
received a message without using a unit
of work and could not return the
message to the queue from which the
message was fetched, or any configured
dead letter queue. To avoid this provide
ample "graceful shutdown" time for the
application.
BWMQ-100267
Listener [%1], relocated a
poison message with ID [%2] to
the poison message queue: [%3]
This is an informational message issued
when the listener detects and responds
to a poison message as configured in the
MultiMessage tab.
BWMQ-100268
Listener [%1], failed to
relocate a poison message with
ID [%2] to the poison message
queue: [%3]
The listener detected a poison message
but failed to put it in the designated
poison message queue. Ensure that the
listener has access and authorization to
the named queue.
BWMQ-100269
Inquire [%1], unexpected queue
type [%2] returned
Internal error. Contact support.
BWMQ-100270
Inquire [%1], unexpected
share-ability type [%2]
returned
The shareable attribute of the destination
is not one of the allowed values. Contact
support.
BWMQ-100271
Inquire [%1], unexpected
destination type [%2], must be
queue
The destination type is not one of the
allowed values. Contact support.
BWMQ-100272
Inquire [%1], MQException [%2]
An error occurred during an inquire
operation. Contact support.
BWMQ-100275
SyncpointActivity error: no
deferred commit unit of work
for this connection: [%1]
A SyncPoint activity did not find any
unit of work to commit. Correct the
process configuration.
BWMQ-100276
Error in SyncpointActivity:
[%1]
If a resolution based on the error code
provided cannot be found, contact
support.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
160
| Appendix A
Error Messages
Table 40 Error Messages (Sheet 8 of 8)
Message
Identifier
Message
Resolution
BWMQ-100304
The WebSphere MQ
Subscriber/Listener has been
instructed to stop
This is a normal informational message
issued when the listener or subscriber is
stopped either by manual intervention,
or because of flow limiting in the
application.
BWMQ-100305
The WebSphere MQ
Subscriber/Listener has been
instructed to start
This is a normal informational message
issued when the listener or subscriber is
started either by manual intervention, or
because of flow limiting in the
application.
BWMQ-100309
Listener/Subscriber
informational message: [%1]
This normal message is issued to
provide information about recover and
retry operations in the listener or
subscriber.
BWMQ-100310
Listener filter field contents
not valid for encoding: [%1]
Reason: [%2]
Correct the filter fields so that they
conform to the specified filter.
BWMQ-300004
The identity file provided is
empty
Correct the configuration.
BWMQ-300005
I/O error processing the
identity file. Probable bad
password [%1]
Correct the configuration.
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
| 161
Index
B
support, contacting xvii
Batch 47, 53, 68, 83
T
C
certificates 10
customer support xvii
technical support xvii
TIBCO_HOME xiv
TLS connection 10
W
K
keystore 10
M
message type 38
datagram 38
reply 38
report 38
request 38
WebSphere MQ
unsupported items 2
WebSphere MQ Connection Shared Resource 26
WebSphere MQ Get activity 57
WebSphere MQ Inquire Activity 116
WebSphere MQ Listener activity 73
WebSphere MQ Properties Shared Resource 33
WebSphere MQ Publisher activity 89
WebSphere MQ Put activity 36
WebSphere MQ Subscriber activity 103
WebSphere MQ SyncPoint Activity 114
wildcard scheme 104
char 104
topic 104
S
sample folder
listenandreply 138
reportlisten 138
sample project
configuring the Get activity 130
configuring the Put activity 127
sample report folder
reportsend 138
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User’s Guide
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement