PathWAI Editor for Messages User’s ഀ䜀甀椀搀publib.boulder.ibm.com/tividd/td/ITPathEfM/GC32...Listing of queues for queue managers or JMS providers ... This guide provides

User’s GuidePathWAI™ Editor for Messages

Version 200

GC32-9340-00

November 2003

Candle Corporation100 North Sepulveda Blvd.

El Segundo, California 90245

2 PathWAI Editor for Messages User’s Guide, Version 200

Registered trademarks and service marks of Candle Corporation: AF/OPERATOR, AF/PERFORMER, AF/REMOTE, Availability Command Center, Candle, Candle Command Center, Candle Direct logo, Candle Electronic Customer Support, Candle logo, Candle Management Server, Candle Management Workstation, CandleNet eBusiness Platform, CandleNet Portal, Candle Technologies, CL/CONFERENCE, CL/SUPERSESSION, CommandWatch, CandleNet Command Center, CT, CT/Data Server, CT/DS, DELTAMON, eBA, eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness Assurance, eBusiness Institute, ETEWatch, IntelliWatch, IntelliWatch Pinnacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON/e, OMEGAMON II, OMEGAMON Monitoring Agent, OMEGAVIEW, OMEGAVIEW II, PQEdit, Solutions for Networked Applications, Solutions for Networked Businesses, and Transplex.Trademarks and service marks of Candle Corporation: Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Candle Alert, Candle Business Partner Logo, Candle Command Center/SentinelManager, Candle CommandPro, Candle CIRCUIT, Candle eDelivery, CandleLight, CandleNet, CandleNet 2000, CandleNet eBP, CandleNet eBP Access, CandleNet eBP Administrator, CandleNet eBP Broker Access, CandleNet eBP Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, CCC, CCP, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes, Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine, CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD, !DB/EXPLAIN, !DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, DEXAN, e2e, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light, eBusiness at the speed of light logo, eBusiness Exchange, eBusiness Institute, eBX, End-to-End, ENTERPRISE, Enterprise Candle Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, EPILOG, ER+, ERPNet, ESRA, ETEWatch Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, MessageMate, Messaging Mastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NetGlue, NetGlue Extra, NetMirror, NetScheduler, OMA, OMC Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON Management Center, OSM, PC COMPANION, Performance Pac, PowerQ, PQConfiguration, PQScope, Response Time Network, Roma, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The Millennium Management Network Alliance, TMA2000, Tracer, Unified Directory Services, Volcano and ZCopy.Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein are trademarks or registered trademarks of their respective companies.

Copyright © November 2003, Candle Corporation, a California corporation. All rights reserved. International rights secured.

Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements (Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No. 5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No. 5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.

NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions set forth in the applicable license agreement and/or the applicable government rights clause.This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only. Any unauthorized use, duplication, or disclosure is unlawful.

Contents 3

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Adobe Portable Document Format . . . . . . . . . . . . . . . . . . . . . . . . . . 14Candle Customer Service and Satisfaction . . . . . . . . . . . . . . . . . . . . 16

Chapter 1. Introducing PathWAI™ Editor for Messages. . . . . . . . . . . . . . . . 17What is PathWAI Editor for Messages?. . . . . . . . . . . . . . . . . . . . . . . . 18PathWAI Editor Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Using PathWAI Editor: Typical Scenarios . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Configuring the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Starting and Stopping the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Connecting to the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 3. Managing Connections and Queues . . . . . . . . . . . . . . . . . . . . . 45The Main Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Adding and Deleting Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Filtering Queue Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Working with Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 4. Creating and Using Message Format Definitions . . . . . . . . . . . . 57About Message Format Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 58Namespaces and Message Format Definitions . . . . . . . . . . . . . . . . . . 60Distributing Message Format Definitions . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 5. Browsing and Editing Queues. . . . . . . . . . . . . . . . . . . . . . . . . . 65Opening the Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66The Message Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Browsing and Selecting Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Contents


Copying, Moving, and Deleting Messages . . . . . . . . . . . . . . . . . . . . . 77Finding and Replacing Message Data . . . . . . . . . . . . . . . . . . . . . . . . 79Forwarding Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Loading and Unloading Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Previewing and Printing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 6. Creating and Editing Messages . . . . . . . . . . . . . . . . . . . . . . . . . 87Creating and Editing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Working with Formatted Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . 92Working with Unformatted Messages. . . . . . . . . . . . . . . . . . . . . . . . . 94Working with XML Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Working with Hexadecimal Messages . . . . . . . . . . . . . . . . . . . . . . . 100Working with JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 7. Working with Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . 107About Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Applying Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Creating Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Editing Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Deleting Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Creating Column Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Editing Column Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Deleting Column Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Chapter 8. Creating Variant Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 127About Variant Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128An Example of Variant Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Creating Variant Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Editing a Variant Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Deleting a Variant Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Contents 5

Appendices

Appendix A. Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Appendix B. LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145About LDAP Directories and Directory Services . . . . . . . . . . . . . . . 146Starting and Stopping the Directory Server . . . . . . . . . . . . . . . . . . . 150Importing Records to an Existing Directory (Seeding) . . . . . . . . . . . 153Backing Up a Local Directory Database . . . . . . . . . . . . . . . . . . . . . 158Unconfiguring the Local Directory Service. . . . . . . . . . . . . . . . . . . . 161Removing the Local Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Reconfiguring the Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . 164

Appendix C. Return Codes and Error Messages . . . . . . . . . . . . . . . . . . . . . 167Metadata Repository Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Client Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176WebSphere MQ Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203


Figures 7

Figure 1. Configuration Tool: Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Figure 2. Configuration Window: Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Figure 3. Sample Server Profile (config.xml) . . . . . . . . . . . . . . . . . . . . . . . . . . 32Figure 4. Adding a Service User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Figure 5. Filtering WebSphere MQ and JMS Queue Lists by Queue Type. . . . . 53Figure 6. Tree Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Figure 7. Text Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Figure 8. XML Tree Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Figure 9. Hexadecimal Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Figure 10. The Apply Filters Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Figure 11. The Variant Definition Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Figure 12. The Retrieve Variant Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Figure 13. Smplfmt2 Definition in the Directory Administrator . . . . . . . . . . . . . 148Figure 14. Manage Candle Services (Windows) . . . . . . . . . . . . . . . . . . . . . . . . 151Figure 15. Seed Business Directory Tab of the Configuration Tool (Windows) . 154Figure 16. Business Directory Utilities Tab of the Configuration Tool (Windows) 159Figure 17. Configure Business Directory Tab of the Configuration Tool (Windows).

165

Figures


What’s New 9

What’s New

PathWAI Editor for Messages represents a re-engineering of Candle’s PQEdit message editing product, coupled with a sophisticated message format definition, parsing, and formatting tool.

PathWAI Editor preserves all the functionality of PQEdit and introduces new features requested by many users:

� New client–server architecture that lets you access queues on remote machines without client connections

� Support for JMS messages

� Support for XML and SOAP messages, as well as a wide range of non-XML message formats

� Two levels of security

� Support for long messages

� Discovery of local queue managers

� Listing of queues for queue managers or JMS providers

� Queue and message filters

W


Preface 11

Preface

This guide introduces PathWAI™ Editor for Messages, a powerful tool for application development and testing in queue-based messaging environments.

This guide provides an overview of the product and instructions for using it to create, edit, and manage messages on WebSphere MQ and JMS queues.

P

About This Book


About This Book

Who should read this bookThis book is intended for application developers and testers who want to use PathWAI Editor to create messaging scenarios for application development and testing. It is also intended for administrators who are responsible for troubleshooting problems with messaging between applications or systems.

Although it provides some basic information in these areas, this book assumes some familiarity with WebSphere MQ and JMS messaging systems and the structure of XML messages.

Documentation set informationPathWAI Editor uses Candle’s Message Format Editor to create the message format definitions it uses to parse and format messages. An introduction to the format editor and instructions for using it to create message formats definitions are provided in the Message Format Editor’s User’s Guide.

Instructions for installing the PathWAI Editor server, the Message Format Editor’s Directory Administrator, and the Candle LDAP server can be found in the PathWAI™ Editor for Messages Installation Guide.

Where to look for more informationYou can access help for many tasks and options by using the Help button on dialog windows. You can also access the table of contents and index of the Help system from the Help menu.

For information on Java Message Service, messages, please refer to Sun Microsystem’s JMS documentation, especially the Java Message Service API specification version 1.1. You can obtain the documentation from http://java.sun.com/products/jms/.

For information on the WebSphere MQ messaging system, consult IBM’s Websphere library: http://www-3.ibm.com/software/integration/websphere/library/

http://java.sun.com/products/jms/

http://www-3.ibm.com/software/integration/websphere/library/

Preface 13

About This Book

For information on XML messages, please refer to World Wide Web Consortium’s XML Recommendation 1.0. You can obtain the recommendation at http://www.w3.org/TR/REC-xml.

Ordering additional documentationTo order additional product manuals, contact your Candle Support Services representative.

We would like to hear from youCandle welcomes your comments and suggestions for changes or additions to the documentation set. A user comment form, located at the back of each manual, provides simple instructions for communicating with the Candle Information Development department. You can also send email to [email protected]. Please include "PathWAI Editor for Messages User’s Guide, Version 200" in the subject line.

http://www.w3.org/TR/REC-xml

Adobe Portable Document Format



Printing this bookCandle supplies documentation in the Adobe Portable Document Format (PDF). The Adobe Acrobat Reader will print PDF documents with the fonts, formatting, and graphics in the original document. To print a Candle document, do the following:

1. Specify the print options for your system. From the Acrobat Reader Menu bar, select File > Page Setup… and make your selections. A setting of 300 dpi is highly recommended as is duplex printing if your printer supports this option.

2. To start printing, select File > Print... on the Acrobat Reader Menu bar.

3. On the Print pop-up, select one of the Print Range options for� All� Current page� Pages from: [ ] to: [ ]

4. (Optional). Select the Shrink to Fit option if you need to fit oversize pages to the paper size currently loaded on your printer.

Printing problems?The print quality of your output is ultimately determined by your printer. Sometimes printing problems can occur. If you experience printing problems, potential areas to check are:� settings for your printer and printer driver. (The dpi settings for both your

driver and printer should be the same. A setting of 300 dpi is recommended.)

� the printer driver you are using. (You may need a different printer driver or the Universal Printer driver from Adobe. This free printer driver is available at www.adobe.com.)

� the halftone/graphics color adjustment for printing color on black and white printers (check the printer properties under Start > Settings > Printer). For more information, see the online help for the Acrobat Reader.

� the amount of available memory in your printer. (Insufficient memory can cause a document or graphics to fail to print.)

For additional information on printing problems, refer to the documentation for your printer or contact your printer manufacturer.

Preface 15


Contacting AdobeIf additional information is needed about Adobe Acrobat Reader or printing problems, see the Readme.pdf file that ships with Adobe Acrobat Reader or contact Adobe at www.adobe.com.

Adding annotations to PDF filesIf you have purchased the Adobe Acrobat application, you can add annotations to Candle documentation in .PDF format. See the Adobe product for instructions on using the Acrobat annotations tool and its features.

http://www.adobe.com

Candle Customer Service and Satisfaction


Candle Customer Service and Satisfaction

BackgroundTo assist you in making effective use of our products, Candle offers a variety of easy-to-use online support resources. The Candle Web site provides direct links to a variety of support tools that include a range of services. For example, you can find information about training, maintenance plans, consulting and services, and other useful support resources. Refer to the Candle Web site at www.candle.com for detailed customer service information.

Candle Customer Service and Satisfaction contactsYou will find the most current information about how to contact Candle Customer Service and Satisfaction by telephone or e-mail on the Candle Web site. Go to the www.candle.com support section and choose the link to Support Contacts to locate your regional support center.

http://www.candle.com

http://www.candle.com

Introducing PathWAI™ Editor for Messages 17

Introducing PathWAI™ Editorfor Messages

OverviewThis chapter introduces PathWAI Editor and illustrates how it can help you develop, test, and troubleshoot applications in queue-based messaging environments.

This chapter explains how PathWAI Editor works, describes its features, and introduces key concepts.

Chapter contentsWhat is PathWAI Editor for Messages? . . . . . . . . . . . . . . . . . . . . . . . . . . . 18PathWAI Editor Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Using PathWAI Editor: Typical Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . 24

1

What is PathWAI Editor for Messages?



PathWAI Editor is a tool for generating, editing, and managing messages in queue-based messaging environments.

PathWAI Editor enables you to create messaging scenarios to test applications before you deploy them. It also helps you diagnose and correct problems with messages sent by applications already in production.

What can I do with PathWAI Editor?Using PathWAI Editor you can:

� View, edit, and create messages in a queue in a formatted or unformatted display

� Re-route messages to another queue or forward messages after modifying or repairing them

� Unload a set of messages for archiving or for reuse in regression testing

� Create a test queue and populate it with a previously-created or modified set of messages

You can use PathWAI Editor with both WebSphere MQ and JMS-based messaging systems.

How does PathWAI Editor work?The PathWAI Editor agent acts as a web server, providing browser access to the WebSphere MQ queue managers and JMS providers on its host. This means you can access resources on another system by simply using your browser to log on to the PathWAI Editor server on that system.

PathWAI Editor uses user-created format definitions to parse and display the messages in the queue and to format and validate messages as you create them.



PathWAI Editor provides a sophisticated message format editor for creating the format definitions it uses to parse and format messages. In addition to tools for creating message format definitions, the format editor provides directory services and namespace organization for the metadata repository in which those definitions are stored. The message format definitions can be easily shared through a central LDAP server or through configuration files stored locally or accessed through networked systems.

How does PathWAI Editor help application development and testing?

View, edit, and create messages in virtually any format

PathWAI Editor makes it possible to view, edit, and create messages in meaningful formats, as well as in byte-oriented streams of character or hexadecimal data.

When it opens a queue, PathWAI Editor displays messages as rows of string, hexadecimal, or XML data divided into columns. For XML messages, each column represents an element. For formatted non-XML (raw) messages, each column represents a labeled field. Unformatted raw messages, including messages retrieved as hexadecimal digits, are divided into fixed-length blocks. The formatted display eliminates the need to scroll through message contents looking for fields or delimiters visually, or for counting bytes and offsets to get to a desired field.

Message formatting makes it simple to create messages by entering data in a structured form, without worrying about things like XML markup or field delimiters.

PathWAI Editor supports a wide range of message formats—including XML with and without DTDs and schemas, SOAP, fixed width fields, delimited fields, fields with length prefixes, tag prefixes, and optional fields.

Manage queues interactively

PathWAI Editor gives you an efficient way to manage all of your queues, including the dead-letter queue. With PathWAI Editor, you can view and edit messages in the dead-letter queue and process those messages interactively. You can retry messages, forward them to another queue, correct inaccurate message data, or unload messages to a file for future review. PathWAI Editor does all this while working with your existing WebSphere MQ security.



Retrieve exactly the messages you want

PathWAI Editor lets you create and apply filters so you can retrieve precisely the messages you want. Filters also make it possible to retrieve and scan messages more quickly.


PathWAI Editor Features


SecurityA PathWAI Editor server can be configured to operate with or without user authentication.

All operations performed by the server are performed on behalf of the user, using the user’s identity. This allows WebSphere MQ administrators to exercise access control using the Object Access Manager.

For information on configuring the server for secure access, see “Configuring server security” on page 38.

Listing of local and remote resourcesPathWAI Editor discovers and lists local WebSphere MQ queue managers, and lets you create entries for remote queue managers you want to access through client connections.

You can also create entries for JMS connections. PathWAI Editor supplies default connection properties for major JMS providers (Websphere MQ, Websphere Application Server, Weblogic, and Sun) and lets you create entries for other implementations by providing the required property values.

For more information, see “Adding and Deleting Connections” on page 49.

Filters for queues and messagesWhen you select a queue manager or JMS connection, PathWAI Editor presents a list of its queues. Since this list may contain hundreds of queues, PathWAI Editor lets you filter the list by queue type and queue name. This helps you locate the queues you want to access and reduces the time required to list the queues. See “Filtering Queue Lists” on page 53.

PathWAI Editor also lets you create message filters that pinpoint specific messages in each queue and particular fields within those messages. You can create filters for both message data and message headers. Filters can be created in advance and shared throughout an enterprise, or created and applied on the fly. See “Working with Message Filters” on page 107



Powerful message format definition capabilitesPathWAI Editor uses user-defined message format definitions to parse, format, filter, and validate messages. These definitions are created using the Message Format Editor.

The Message Format Editor enables you to create message format definitions that describe the combination and structure of fields in a message, the structure of its individual fields, and restrictions on those fields. It also provides the means for storing and distributing those definitions.

The Message Format Editor supports a wide range of message formats and data types, which allows you to create definitions that precisely describe your messages.

For more information on creating message format definitions, see “Creating and Using Message Format Definitions” on page 57 and the Message Format Editor’s User’s Guide.

Editing viewsPathWAI Editor supports a variety of editing views. You can edit messages as string, XML, or hexadecimal data.

You can create and edit non-XML messages as formatted or unformatted strings, or as byte-oriented hexadecimal data.

You can create and edit unformatted XML messages as text, or open an XML tree view that lets you add elements and attributes without worrying about markup.

PathWAI Editor also provides special tree views for creating and editing JMS stream and map messages.

For more information, see “Creating and Editing Messages” on page 87.

LDAP directoryIn order to effectively create, share, and use message formats across the enterprise, an enterprise-wide repository of message format definitions is essential. PathWAI Editor provides an LDAP directory and supporting services that you can use for this purpose if you are not already using one.

For more information, see “LDAP Directory” on page 145.



Audit loggingPathWAI Editor allows you to log editing operations, so changes can be tracked. For more information, see “Auditing changes” on page 72.

Using PathWAI Editor: Typical Scenarios



OverviewThe following three scenarios illustrate typical ways you might use PathWAI Editor.

Scenario 1—Testing a new applicationYou have developed a new WebSphere MQ server application which processes request messages sent in a semicolon (;) delimited format. You can use PathWAI Editor to test the application and save the test messages for regression testing by taking the following steps:

1. Create a definition for the message format with the Message Format Editor.

2. Use your browser to connect to PathWAI Editor on the test machine, create a test queue, and create and validate a message using the new format definition.

3. Copy and paste the message to create a set of test messages and edit the content of fields if necessary.

4. Create copies of the messages on another queue.5. Run the server application. 6. If the application cannot process any of the messages, use PathWAI Editor

to examine the messages on the second queue and edit them if necessary, then copy them to the test queue.

7. When the application processes all the messages successfully, unload the messages from the second queue to save for regression testing, adding other messages as needed to test additional functionality.

Scenario 2—TroubleshootingYou are testing a distributed application. The client application is on a test workstation using a client connection to a WebSphere MQ server, and the server application is on a different server machine. It appears that the server has not received a request sent by the client.

Here is how you might use PathWAI Editor to troubleshoot the problem:



1. Use your browser to log on to PathWAI Editor on the machine that hosts the server used by the client applications and connect to the queue manager used by the client.

2. Browse the transmit queues for the target queue manager or the default transmit queue.

3. If you find messages on these queues, investigate the channel connections.If you don’t find the messages on these queues:A. Point the browser to the server application machine and connect to

the target machine.B. Browse the dead letter queue. C. If you find one or more messages, browse them to determine why the

messages ended up there.D. Once you have determined the cause of the problem, edit the

messages and forward them to their destination.

Scenario 3—Testing XML MessagesYou need to test a new application that processes XML requests. Here is how you might use PathWAI Editor to create messages to test it:

1. Log on to PathWAI Editor on the machine that hosts the server application.

2. Connect to the server queue manager and open the server’s input queue.3. Create a formatted XML message using tree editor, or create an

unformatted XML message using the text editor or the XML tree editor.4. Create multiple copies of the message by cutting and pasting.



Getting Started 27

Getting Started

OverviewThis chapter provides the information you need to get started using PathWAI Editor. It covers configuring, starting and stopping, and logging on to a PathWAI Editor server.

Chapter contentsConfiguring the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Starting and Stopping the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Connecting to the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

2

Configuring the Server



OverviewAt start up, a PathWAI Editor server loads a configuration profile containing the options configured for that particular server. Some of these options are set at installation and should not be changed, others default to preset values and can be modified as needed to meet your changing requirements or preferences. A sample configuration file is shown in Figure 3 on page 32.

The following section provides instructions for editing the server configuration profile. “Configuration parameters” on page 33 describe the various configuration options. “Configuring server security” on page 38 discusses the various security options and requirements.

Editing the server profile

Windows

To edit the profile:

1. Select Start > Programs > PathWAI Editor for Messages > Configuration Tool.The Candle PathWAI Editor for Messages Configuration dialog is displayed (see Figure 1 on page 29).

2. On the PathWAI Editor for Messages Configuration tab do the following:– To edit the parameters set at installation, enter the new values in the

appropriate fields.

– To edit other parameters, click Configure Additional Parameters.

The configuration profile is opened in Notepad.

A. Edit the parameters as appropriate.B. Save the file.C. Exit Notepad.

The Candle PathWAI Editor for Messages Configuration dialog is displayed.

3. Click Apply to save the changes.

Getting Started 29


You will see a message telling you that the variables have been set.

4. Click OK to dismiss the message.

5. Click Close to close the configuration dialog.

Figure 1. Configuration Tool: Windows



Unix (GUI mode)

To edit the profile:

1. In a command window, change to the PathWAI Editor bin directory:cd <candlehome>/bin

2. Enter the following command./msgEditConfig

The configuration window appears (see Figure 2 on page 31).

3. Do the following:– To edit the parameters set at installation, enter the new values in the

appropriate fields.

– To edit other parameters, click Edit template file.

The configuration profile is opened in a text editor.

A. Edit the parameters as appropriate.B. Save the file.C. Exit the editor.

The configuration window is displayed.

4. Click Save to save the changes and close the configuration window.

Unix (command line mode)

In command line mode, you can use the configuration utility to edit the variables set at installation (these are the variables shown in Figure 2 on page 31). To edit additional variables, you must edit the file <candlehome>/unix/MsgEdit/bin/config.template using a text editor.

To access the configuration utility:

1. In a command window, change to the PathWAI Editor bin directory:cd <candlehome>/bin

2. Enter the following command./msgEditConfig -l

3. Press Enter to accept the current setting for each parameter, or enter a new value and then press Enter.

Getting Started 31


Figure 2. Configuration Window: Unix



Figure 3. Sample Server Profile (config.xml)

<?xml version="1.0" ?><ServerProfile>

<Platform>WINDOWS</Platform><ProfilePath>C:/Program Files/Candle/msgedit</ProfilePath><Port>4444</Port><ResourceBase>C:/Program Files/Candle/msgedit/html</ResourceBase><ContextPath>/</ContextPath><Trace>None</Trace><Environment>MQSERIES</Environment><QMGRS>C:/Program Files/IBM/WebSphere MQ/qmgrs</QMGRS><ValidateUser>NO</ValidateUser><UseUserId>Yes</UseUserId><Audit>None</Audit><Timeout>10000</Timeout><Idle>30</Idle><FieldSize>100</FieldSize><MaximumResponseSize>1000000</MaximumResponseSize><MaximumQueues>100</MaximumQueues><Namespace>:CandleSamples.MessageEditor</Namespace><Filter>

<URL>ldap://ssabs01:389/cn=RomaContext,dc=Context,dc=Roma,dc=candle,dc=com</URL>

<UserId>manager</UserId><Password>secret</Password>

</Filter><MBCS>

<CCSID>1208</CCSID></MBCS><MAPCS>

<CCSID source="923">437</CCSID>

<MAPCS></ServerProfile>

ldap://ssabs01:389/cn=RomaContext,dc=Context

Getting Started 33


Configuration parameters

Platform

The type of operating system on the machine on which the server is running. Valid values are:

– WINDOWS

– UNIX

This parameter is set by the installer and should not be edited.

ProfilePath

The path to the directory where the server will find the user profile files. The default value is <candlehome> (the directory in which PathWAI Editor is installed.


Port

The number of the port on which the server receives messages. The default value is 4444.

The port number can also be specified as an option when the server is started from the command line (-port <port_number>: see “Running PathWAI Editor as a batch job” on page 40). The value supplied in the startup command overwrites the value specified in the configuration file. This is useful if you want to create a new process with the same configuration file, but on a different port.

ResourceBase

The resource to use as a relative base for all context resources. The default value is <candlehome>\html or <candlehome>/html.


ContextPath

The context prefix. The default value is “/” (the root).




Trace

The trace functionality is primarily for Candle's use in troubleshooting. It logs the messages exchanged by server and clients. This option should be changed only at the request of Candle customer support.

This parameter may have one of the following values:

Environment

The messaging services supported. Valid values are:

– MQSeries

– JMS

– ALL

The default is ALL (both MQSeries and JMS are supported).

QMGRS

The directory where WebSphere MQ is creating queue managers on this machine.

ValidateUser

Specifies if user validation (user ID and password) is to be performed. Valid values are:

– Yes

– No

By default, user validation is done.

None The default. Trace is disabled.

Flow Displays only the message flow in the Debugger window.

XML Displays the content of the XML requests and responses in the Debugger window.

Log Displays the content of the XML requests and responses in the Debugger window and in addition generates for each received message a log file containing the request as well as its response.

Getting Started 35


UseUserId

Specifies whether MQSeries operations are done using an alternate user ID (the user ID provided at login). Valid values are:

– Yes

– No

By default, the alternate user ID is used.

Keystore

The location of the JKS keystore used to store the private key/public key certificate for the server if configured for Secure Sockets Layer security.

Audit

Logs updates made to messages, so that administrators can maintain an audit trail of changes. One of the following two parameters:

Timeout

The maximum time, in milliseconds, PathWAI Editor waits for a response to a PCF (programmable command format) request.

The default is 10000 (10 seconds). Range 1–100000 (100 seconds).

Idle

The maximum amount of time, in minutes, the PathWAI Editor server will keep the connection alive while not receiving any request on it. If an attempt is made to access the connection after the idle time has expire, a timeout message is displayed and the session is ended.

The default is 30 minutes. Range 1–1000.

FieldSize

The field size for unformatted raw (non-XML) messages. The default is 100 bytes. Range 1–1000.

None The default. Audit logging is disabled.

Log The following edit operations are logged: creating a queue, deleting a queue, deleting a message, creating a message



MaximumResponseSize

The limit, in bytes, over which no more messages will be returned. Messages that exceed the maximum response size may be split.

The default is 2 MB. Range 100000–10000000 (100KB to 10MB).

MaximumQueues

OS/390 and z/OS client connections only. The maximum number of queue names displayed in the queue list when a queue manager is selected.

The default is 100. Range 1–500.

Namespace

The metadata repository namespace in which message formats are defined. It may be disabled by a queue profile.

The default is :CandleSamples.MessageEditor. For more information on namespaces, see “Namespaces and Message Format Definitions” on page 60.

Filter

The access mode for adding, updating, and removing message filters. This parameter should not be edited.

Filter definitions are stored in a data dictionary, MsgEdit_DataFilters, in the same metadata repository as message format definitions. The Filter field contains the information necessary for the server to access this data dictionary. The URL can be an LDAP server or a configuration file. If it is an LDAP server, the user ID and password for the server must also be provided:

<Filter>

<URL>data_dictionary</URL><UserId>id</UserId><Password>password</Password>

</Filter>

Where

Getting Started 37


– data_dictionary specifies the URL of the MsgEdit_DataFilters dictionary, in the form protocol/path. The URL should have the value of the KXCDIR environment variable set at installation for the LDAP server or configuration file in which the metadata repository containing message format definitions is housed.

For example:

ldap://localhost:389/cn=RomaContext,dc=roma,dc=candle,dc=com

file:///kxymsged.txt/cn=RomaContext,dc=roma,dc=candle,dc=com

– id represents the user ID required to access the LDAP server (the default is cn=manager)

– password represents the user password to access the LDAP server (the default is secret).

MBCS

The metadata repository in which messge format definitions are stored handles only SBCS (single byte character sets). MBCS (multiple byte character sets) are supported only in the text message mode. If you have MBCS messages, the corresponding CCSID must be listed here so that they can be handled appropriately, and the browser must have a suitable font installed to display the characters.

Parameters are a list of character set IDs (CCSID) for which conversion operations will not be applied to raw text messages. For example:

<MBCS>

<CCSID>1208</CCSID>

<CCSID>936</CCSID>

</MBCS>

MAPCS

This parameter lets WebSphere MQ supported Codepage Sets be mapped to ones supported by Java.

ldap://localhost:389/cn=RomaContext,dc=roma,dc=candle



The different platforms and release levels of MQ have different default codepages:

For example:

<MAPCS>



</MAPCS>

Configuring server securityThe PathWAI Editor server can be configured to operate at two levels of security:

� No authentication (<ValidateUser/>No</ValidateUser>)—In this mode, any user with a system ID can connect to a server and perform operations on the WebSphere MQ or JMS resources.

� User authentication (<ValidateUser/>Yes</ValidateUser>)—In this mode, the user needs to provide a user ID and password valid for the operating system on which the server resides. The user ID and password are flowed in clear text (as is the rest of the communication).

To run in this mode on the Windows platform, the user that starts the server needs to have permission to act as the operating system. This can be done using the Windows Security Policy Manager.

No special privileges are required on UNIX to run in this mode.

In either case, the user ID is used as the effective user ID for all WebSphere MQ operations, including client connections. That is, all operations performed by the server are actually performed on behalf of the user, using the user’s ID. This allows WebSphere MQ administrators to exercise access control using the Object Access Manager.

Sun 923 (819 is already handled via the alias table)

HP 1051

AIX 819

Getting Started 39

Starting and Stopping the Server


PermissionsTo start the PathWAI Editor for Messages server, a user must have full administrative access to WebSphere MQ (that is, must be a member of the mqm group). On Windows, this user must also have the Windows authority to “Act as part of the operating system” if server security is set to validate the user passwords. On UNIX, no special privileges are required. On MVS, user access rights need to be administered using OAM/RACF.

Users do not need to belong to the mqm group to log on to the PathWAI Editor for Messages server. Users need only be given specific access to perform the functions they need to. At a minimum, users need get, browse, and put access to the SYSTEM.DEFAULT.MODEL.QUEUE.

WindowsCandle recommends that you run the PathWAI Editor server as a Windows service. To implement user validation when PathWAI Editor is running as a service, you must update a Local Security Policy.

Updating the local security policy

If you run the service as the default Local System Account, add a Service user to the Act as part of the operating system policy under the User Rights Assignment (see Figure 4 on page 40).

If you are using an alternate user ID, select the user ID that the service is configured for.

Running PathWAI Editor as a Windows service

If you are running the PathWAI Editor server as a Windows service, you can the Manage Candle Services console to start and stop the service:

1. To access the console, from the Start menu select:Programs > PathWAI Editor for Messages > Manage Candle Services.

2. Right-click PathWAI Editor for Messages and select the appropriate command from the popup menu.



Running PathWAI Editor as a batch job

PathWAI Editor may also be run as a batch job. The appropriate ID must also be added to the policy.

To start PathWAI Editor as a batch job, run the kxyruns.bat command file located in the <candlehome>\msgedit\bin directory.

When the server starts, it displays the configuration parameters it is using. The message “The server was started on port <nnnn>.” indicates that the server is fully initialized and ready to receive connections. The command prompt must stay active while server is running.

To stop PathWAI Editor, enter Ctrl-c in the command prompt.

Figure 4. Adding a Service User

Getting Started 41


UNIX

Starting and stopping the server in GUI mode

In GUI mode you can start and stop the PathWAI Editor server using the Manage Candle Services utility.

To start the server:

1. Change to the <candlehome>/bin directory:cd <candlehome>/bin

2. Enter the following command:CandleManage

The Manage Candle Services window appears.

3. Do one of the following:

– Right-click PathWAI Editor for Messages and select Start from the popup menu, or

– Select (click) PathWAI Editor for Messages, then click .

To stop the server:





– Right-click PathWAI Editor for Messages and select Stop from the popup menu, or

– Select (click) PathWAI Editor for Messages, then click .

Starting and stopping the server from the command line


2. Enter the following command:CandleAgent start xy



When the agent is started successfully, you will see the message, “Agent started . . .”

To stop the PathWAI Editor server:

1. Change to the <candlehome>/bin directory:CD <candlehome>/bin

2. Enter the following command:CandleAgent stop xy

When the agent is stopped successfully, you will see the message, “Agent stopped . . .”

Getting Started 43

Connecting to the Server


Accessing the serverYou can connect to a server using either Internet Explorer 6.0 and above.

To access a server, enter its URL in the browser in the following form:

http://<host>:<port>

where

On Windows, you can connect to the server on the local machine from the Start menu by selecting Programs > PathWAI Editor for Messages > Access PathWAI for Messages Server.

Logging inWhen the browser successfully connects to the server, the login window appears.

In order to log in, you must supply a user ID that is defined on the server system. If the server was configured for user authentication, you also need to provide a valid password.

<host> is the host on which the server is running

<port> is the configured port



Managing Connections and Queues 45

Managing Connections andQueues

OverviewThis chapter addresses the administrative tasks involved in adding entries for remote queue managers and JMS providers to the PathWAI Editor resource tree and managing the queues associated with the resources listed in the tree.

Chapter contentsThe Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Adding and Deleting Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Filtering Queue Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Working with Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

3

The Main Window


The Main Window

OverviewWhen you first log on to a PathWAI Editor server, you see the main application window in your browser. The main window is where you select the resources and queues you want to work with. On the left is a console tree, which lists the WebSphere MQ and JMS resources available at this server. On the right is an area where the queues associated with a selected queue manager or JMS connection are listed. Across the top is a menu bar with options for managing the editing session and the queue lists.

Console treeIf the server was configured with Websphere MQ as one of its environments, you should see Websphere MQ under the root of the console tree. Expanding this node exposes the Local Queue Manager and Client Connections branches. The PathWAI Editor server discovers the local queue managers and populates the Console tree with an entry for each one. However, you must create entries for any remote queue managers whose queues you want to access through client connections (see “Adding client connection entries” on page 49).

If the server was configured with JMS as one of its environments, you will see a JMS node under the console root. When you expand this node, you can see any JMS connections you have added (see “Adding JMS connection entries” on page 50).

You can edit the properties of a client or JMS connection by clicking the beside the entry and selecting Edit, or delete it by selecting Delete.

You can delete entries for remote queue managers accessed through client connections and for JMS connections. You cannot delete entries for local queue managers.


The Main Window

Queue listWhen you select a queue manager or JMS connection, a list of its queues appears to the right of the console tree. From this list you can select the queue you want to open for browsing or editing.

You can limit the number of queues that appear in the queue list by filtering on queue type and queue name. If there are many queues, this can save time retrieving the queue information and searching for the queue you want. (For more information, see “Filtering Queue Lists” on page 53)

You can also create new queues where you can test load, create, and test new messages, and clear or delete existing queues (see “Working with Queues” on page 55).

Menu commandsThe following table lists and describes the commands you can access from the menus in the main application window.

Menu Action

File

CreateQueue

Create a new queue

The Main Window


Log Out Log out of the application

Tools

Row Filters Create or edit a row filter by specifying threshold values for message fields (see “Working with Message Filters” on page 107)

ColumnFilters

Create or edit a column filter by specifying fields to be excluded from messages (see “Working with Message Filters” on page 107)

VariantDefinitions

Define alternate formats for formats with content-dependent variants (see “Creating Variant Definitions” on page 127)

Debugger Open the Debugger console.

Options Open the Options dialog to set debugging options.


Adding and Deleting Connections


OverviewA PathWAI Editor server discovers the local WebSphere MQ queue managers and populates the console tree with an entry for each one. Clicking an entry provides you access to its queues.

You can also access queues belonging to queue managers on a machine where a PathWAI Editor server is not installed, not running, or not supported (for example, OS/390) by using a client connection. However, you must create the entries for those queue managers. You must also create entries for any JMS providers you want to access.

Adding client connection entriesTo access a remote queue manager using PathWAI Editor, you must add a client connection entry to the console tree. Adding a client connection does not create a connection or a channel, it simply creates an entry for an existing connection. Once you have created an entry, you can click it to connect to the queue manager and view a list of queues. The entry is stored in the server profile and appears in the Console tree until you delete it.

Once a client connection entry is added, it is accessible to all users of this server.

To use the client connection:

� You must have a SVRCONN channel defined on the target queue manager with the name you specify.

� The channel must be started.

� A listener must be listening at the port specified.

To add a client connection:

1. Open the Client Connection node of the Console tree (if necessary) and click Add New Client.The New Client Connection dialog appears.

2. Type in the following information:



– Queue Manager Name—The name of the remote queue manager to which PathWAI Editor can request connection.The name must be a valid WebSphere MQ name consisting of alphanumeric characters, and the special characters period (.), slash (/), underscore (_), and percent (%).

– Host—The name of the system on which the queue manager resides.

– Channel Name—The name of the SRVCONN channel

– Port—The number of the port of the remote queue manager listener

– CCSID—The CCSID used to make the client connection. This parameter is optional. If no CCSID is specified, the default of 819 is used.

3. Click to create the new connection entry and close the dialog.

PathWAI Editor creates a new entry for the connection using the name of the remote queue manager. Click the beside the entry to see the connection properties (host, channel name, and port).

Adding JMS connection entriesYou can add a JMS connection entry for any local JMS service provider. The underlying transport must be present and configured as required.

Once you have created an entry, you can select it to connect to the service and view a list of queues in the root namespace and below. The entry is stored in the server’s profile and is accessible to all users until it is deleted.

To add a JMS connection:

1. Open the JMS node of the Console tree (if necessary) and click Add New JMS Connection.The New JMS Connection dialog appears.

2. For Connection Name, type a name for the new connection.

3. From the dropdown list, select the provider of the JMS implementation.For major providers (IBM, WebSphere, WebLogic, and Sun One) PathWAI Editor displays default values for the remaining properties. You may need to edit these for your site. If you are using another provider, you must provide the appropriate values.



– For Initial Context Factory, provide the name of the java class used to create the initial context

– For Provider URL, provide the protocol and path used to connect to the naming service in the form protocol://hostname:port/path

– For Connection Factory Name, provide the name of the factory object that creates the connection

– To add Other Properties, type the property name and value, then click .

To modify the provided properties:

A. Select the property you want to modify.B. Edit the name or property.

C. Click .

4. Click to create the new connection entry and close the dialog.The Editor creates a new entry for the connection. Click the beside the entry to see the connection properties.

Note: You may need to update the startup script/batch file(kxyruns.sh/bat) to add the required JMS jar files to the classpath variable.

Viewing and editing connection propertiesYou can view the properties of client and JMS connections by clicking the beside the entry. You can edit the properties of an entry as needed. For example, you might need to change the port on which a listener is listening, or the URL of the LDAP server in which the connection definition is stored.

To edit connection properties, click the button next to the connection, then select Edit from the popup menu. (For client connections, the channel name is read only.)

Deleting connectionsYou can delete entries for remote queue managers accessed through client connections and for JMS connections. You cannot delete entries for local queue managers.

protocol://hostname:port/path



Deleting an entry does not delete the actual client or JMS connection, only the information about the connection stored on the server. However, if you delete the entry, you can no longer view the queues associated with the remote queue manager or JMS connection.

To delete an entry:

1. Click the button next to the connection and select Delete from the popupmenu.

You will be asked to confirm the deletion.

2. Click to delete the entry.


Filtering Queue Lists


OverviewIf there is a very large number of queues in the queue manager, the request to fetch the list of queues may time out. This is particularly likely with OS/390 queue managers, which in the current version of PathWAI Editor must be accessed through a client connection. To prevent such time outs, you can restrict the number of queues to be retrieved using queue filters.

You can filter the queue list by queue type and by queue name.

Filtering by queue typeBy default, queues of all types appear in the queue list. To limit the queues listed to a particular type, select the type in the Type of Queues box to the right of the queue list. The queue types available depend on the type of messaging service (see Figure 5).

Figure 5. Filtering WebSphere MQ and JMS Queue Lists by Queue Type



Filtering by queue nameIn addition to filtering by queue type, you can limit the contents of the queue list further by filtering on queue names.

You can enter a specific name or use an asterisk (*) wildcard to specify queues which share a common element, such as a prefix or a midlevel qualifier.

The asterisk can be used only at the end of a string. For example, the following are valid entries:

ADMIN*

s*

REPLY*

Queue names are case-sensitive.

To apply a filter:

Type the string in the text field, then click OK.

To return to the complete list of retrieved queues:

Clear the field, then click OK.


Working with Queues

Working with Queues

Viewing queue properties (WebSphere MQ only)You can view the properties of queues in the queue list.

To view the queue properties:

Right-click the button beside the queue whose properties you want to view and select Attributes from the popup menu.

Creating a queueIf your user ID has the proper authority, you can use PathWAI Editor to create WebSphere MQ queues. You can also create temporary JMS queues—that is, queues that exist only for the current session.

You can then load stored messages onto the queue, create new ones, or copy and paste messages from another queue.

To create a queue:

Click Create Queue at the top of the queue list.

When you create the queue, PathWAI Editor asks you to specify the properties for the queue. The properties you set differ according to the type of queue you are creating. For more information, see the online Help for the Create Queue properties dialogs.

Clearing a queue (WebSphere MQ only)You can delete all the messages in a queue from a list of WebSphere MQ queues.

To clear a queue:

Right-click the button beside the queue you want to clear and select Clear from the popup menu.

PathWAI Editor will ask you to confirm that you want to delete the messages.

Deleting a queueIf your user ID has the proper authority, you can use PathWAI Editor to delete WebSphere MQ queues. You can also delete the temporary JMS queues you

Working with Queues


created for the current session and entries in the namespace representing permanent JMS queues. You cannot delete the physical queue.

To delete a queue:

Right-click the button beside the queue you want to delete and select Delete from the popup menu.

If you are deleting a WebSphere MQ queue, you can have PathWAI Editor empty the queue for you by checking Purge when you confirm the deletion.

Opening a queueClicking a queue in the queue list or the beside it invokes the Open Queue dialog.

The Open Queue dialog lets you select the column and row filters you want to apply to the messages retrieved (see “Working with Message Filters” on page 107.)

The Open Queue dialog also lets you determine how messages are displayed and under what conditions. The options available depend upon whether the queue is a JMS or a WebSphere MQ queue. The options you select for a particular queue are automatically selected the next time you open the queue and remain set until they are changed.

For more information about setting session properties, see “Opening the Queue” on page 66, the online Help topic “Opening Queues”, or the Help for the Open Queue dialog.

Creating and Using Message Format Definitions 57

Creating and Using MessageFormat Definitions

OverviewMessage format definitions allow PathWAI Editor to present messages in a formatted display and to format and validate messages when you create them.

This chapter discusses what message formats are, how they are created and stored, how PathWAI Editor determines which format to use when displaying or creating a message, and how message formats are distributed and shared.

Note: Message formatting is supported only for single byte characters sets (SBCS). Double byte character sets (DBCS) character sets are not supported.

For information on creating message formats, please refer to the Message Format Editor User’s Guide.

Chapter contentsAbout Message Format Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Namespaces and Message Format Definitions. . . . . . . . . . . . . . . . . . . . . . 60Distributing Message Format Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 63

4

About Message Format Definitions



What is a message format definition?A message format definition is a description of the message structure. Message format definitions enable applications to interpret and format messages.

PathWAI Editor uses user-defined format definitions to parse messages for display when you view or edit them and to format and validate messages when you create them.

If you create or edit messages without using message format definitions, you must be responsible for ensuring that the messages conform to the appropriate message structure. If you create them using message format definitions, PathWAI Editor can validate the message structure and ensure that the messages are properly formatted.

You create message format definitions using the Message Format Editor. The definitions are stored in a metadata repository. For a description of the Message Format Editor and detailed instructions for creating message format definitions, refer to the Message Format Editor User’s Guide.

PathWAI Editor and the Message Format Editor recognize two basic categories of messages: XML messages and non-XML, or raw, messages.

XML format definitionsFor XML messages, message format definitions describe the elements that must occur in a particular message type, the order in which they must occur, the attributes they must have, and what the attribute values must be. Those constraints are defined in Document Type Definitions (DTDs) or XML Schemas referenced through the message format definitions and stored in the Message Format Editor’s schema repository.

Because XML messages are self-describing, they can be interpreted without reference to external message format definitions. However, XML messages cannot be formatted or validated without reference to a message format definition, and through it to a DTD or XML Schema.

In the Message Format Editor, XML message formats are defined as XML documents. In essence, creating a message format definition for an XML



message means creating an association between an XML document name (its root element) and one or more DTDs or XML schemas.

The Message Format Editor lets you import or create DTDs and XML Schemas. It also provides a utility to convert COBOL copy books into raw message format definitions and raw message format definitions into XML Schema definitions.

Raw message format definitionsFor raw messages, message format definitions describe the structure of the individual fields that comprise the messages, the restrictions placed on those fields, and how the fields are combined.

In the Message Format Editor, raw message formats are defined as groups. A group contains a collection of group items, similar to a structure in the C language. The group items may be primitive data types or other groups. The group may have a structure associated with it such as a prefix, suffix, or delimiter.

A group may be one of these types:

� Fixed width—all group items have a fixed width

� Delimited—all group items are distinguished by a delimiter

� Implied—group items are distinguished by the group item’s width, length, prefix, or suffix

For information on creating raw message formats, see The Message Format Editor User’s Guide, especially the chapter on “Working with Raw Message Formats”.

Namespaces and Message Format Definitions



OverviewMessage format definitions created by the Message Format Editor are stored in the metadata repository (MDR), which provides a hierarchical namespace structure. Namespaces enable you to maintain metadata (“data about data”) in a hierarchy of separate partitions. This means you can partition your message format definitions for different needs. For example, you can maintain separate areas for different applications, departments, or groups.

The root of the MDR is an unnamed global namespace; other MDR definitions, including namespaces, reside within it. The namespace :CandleInternal.MessageEditor contains format definitions for Websphere MQ and JMS headers and should not be modified. The namespace :CandleSamples.MessageEditor contains the sample definitions provided with PathWAI Editor.

Each PathWAI Editor server uses a single namespace for looking up formats. The server, as installed, points to the namespace :CandleSamples.MessageEditor. You may create additional namespaces under this namespace, or any namespace you create, corresponding to queue managers in your environment. This is useful if you have the same format names for different actual formats used in the context of different queue managers.

If you use a namespace other than the default to store message format definitions, you must change the <Namespace> tag in the server's configuration profile to refer the new namespace. To use namespaces effectively, you need to understand how PathWAI Editor determines message format.

(For more information about creating and using namespaces in the MDR see the Message Format Editor User’s Guide. For information on editing the server’s configuration file, see “Configuring the Server” on page 28.)

How PathWAI Editor determines the message formatWhen PathWAI Editor reads a message from a queue, it uses the following logic to determine how the message should be processed.



1. If the message header contains a format name, PathWAI Editor attempts to locate a definition for that format in the MDR. If it finds one, it tries to parse the message using that definition. If this is successful, the message is returned with this format.

2. If it cannot locate a definition of the format or cannot successfully parse the message using the definition, PathWAI Editor tries to locate a format definition with the same name as the queue to which the message belongs and tries to parse the message with that format. If this is successful, the message is returned with this format.

3. If PathWAI Editor cannot successfully parse the message with the queue-based format, it tries to parse the message as an XML message. If successful, the message is returned as an XML message.

4. If PathWAI Editor cannot successfully parse the message as an XML message, it returns the message as text if it does not have any unprintable characters, and as a string of hexadecimal digits if it has unprintable characters. The browser client automatically opens the hexadecimal editor when such messages are edited.

When PathWAI Editor attempts to locate a format definition in the metadata repository, it first searches a subnamespace with the queue manager name, and then the namespace specified in the server configuration profile.

For example, if the configuration file points to the namespace :CandleSamples.MessageEditor, and the queue being browsed belongs to a queue manager named myQMGR, and the name of the queue is myqueue, PathWAI Editor will look for a format called myqueue in the namespace :candleSamples.MessageEditor.myQMGR first, and then in the namespace :candleSamples.MessageEditor.

The format PathWAI Editor actually used for parsing the message is returned in a tag called pFormat (parse format), which one of the properties PathWAI Editor adds to a message header.

Referencing message format definitionsThe namespace in which the PathWAI Editor server is running has implications for the form in which message format definition names are referenced.



If the server is running in the same namespace as the format definitions, the unqualified reference form of the message format definition name can be used in the message header. However, if the server is running in a different namespace than the message format definitions, the absolute or relative reference form of the name must be used. Only these forms will provide enough information for the server to find the correct message format definition.

If all message format names are specified in the unqualified form, it is probably easier to change the namespace of the server as necessary to access the appropriate definitions.

See the chapter “Defining Message Formats” in the Message Format Editor User’s Guide for more information.

Special WebSphere MQ considerationsWhile the Message Format Editor allows you to create format names longer than eight characters, you should keep the WebSphere MQ eight-character limitation in mind when you are creating message formats.

You can create WebSphere MQ messages using formats with names longer than eight characters, but in the queue the format name will be truncated to eight characters. This means that the messages cannot be presented in a formatted display, but only as byte-delimited raw messages.

The eight-character limitation on the format property does not apply to WebSphere MQ JMS messages.


Distributing Message Format Definitions


OverviewThe message format definitions you create using the Message Format Editor (or convert from a FORMAT.ini file, see below) are stored in the metadata repository. The metadata repository can be housed in either a central LDAP server or in a configuration file in LDIF format.

Using an LDAP serverUsing a central repository simplifies the configuration and sharing of message formats in a large enterprise. It eliminates the need to share formats by exchanging and merging definition configuration files and prevents errors caused by out-of-sync definition files, improperly overlaid configuration files, and lost files.

PathWAI Editor provides an LDAP directory and supporting software you can use to store your message format definitions. PathWAI Editor also supports IBM’s Secure Way Directory and Netscape’s Directory Server.

Using a configuration fileIf the metadata repository is housed in a configuration file, the file must be made accessible to PathWAI Editor servers through a networked file system or manually distributed to PathWAI Editor hosts.

The configuration file must be placed in the bin subdirectory of the PathWAI Editor installation directory. For example:

c:\Program Files\Candle\MsgEdit\bin

The Message Format Editor includes utilities for exporting data from one metadata repositiory and importing it into another. So message format definitions stored in one file can be merged with or replace definitions in another file.

Note: Message filter definitions are stored in the same metadata repository as message format definitions. Currently, PathWAI Editor provides no means for merging message filters definitions stored in different metadata repository configuration files, so if you import metadata



from another metadata repository, you will overwrite any filter definitions that exist in the target file.

Importing PQEdit FORMATS.INI filesTo use formats you have already defined for PQEdit in FORMAT.ini files, you must import the files into the metadata repository using the PQEdit import utility. For instructions on using the import utility, refer to the PathWAI Editor for Messages Installation Guide.

Browsing and Editing Queues 65

Browsing and Editing Queues

OverviewThis chapter covers managing and editing messages in a queue. It describes the Message window in which you manage and edit messages and how to browse, select, and filter messages. It also provides instructions for finding and replacing message data, moving or forwarding messages, and previewing and printing messages.

Creating and editing individual messages is discussed in the following chapter.

Chapter contentsOpening the Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66The Message Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Browsing messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Copying, Moving, and Deleting Messages. . . . . . . . . . . . . . . . . . . . . . . . . 77Finding and Replacing Message Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Forwarding Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Loading and Unloading Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Previewing and Printing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5

Opening the Queue


Opening the Queue

OverviewSelecting (clicking) a queue in the queue list invokes the Open Queue dialog.

The Open Queue dialog lets you select which column and row filters you want to apply to the messages retrieved from the queue and determine how messages are displayed and under what conditions the queue is being edited. The options available depend upon whether the queue is a JMS or a WebSphere MQ queue.

The options you select for a particular queue are automatically selected the next time you open the queue and remain set until you change them.

Applying filtersSince queues may contain messages of more than one format, you can specify any number of filters to be applied to the queue. However, only one filter of each type (row data, row header, column data, column header) can be applied to each format. If you apply any filters, messages that do not belong to any of the formats to which the filters apply are not retrieved.

If you select the Ignore Message Format option on the Open Queue dialog, only text filters and header filters are applied and all messages are retrieved, up to the limit specified in the <MaximumResponseSize> parameter set for the server (by default, this is 2MB). (For more information on creating and applying filters, see “Working with Message Filters” on page 107.)

JMS and WebSphere MQ options

Display header

If this option is selected, PathWAI Editor displays the message headers as well as message data in the Message window. (The display of message headers can also be controlled from the Message window: see “Displaying header fields” on page 71.)


Opening the Queue

Ignore message formatting

Selecting Ignore Message Formatting suppresses the use of message formats definitions for message display and creation. Messages are displayed as either standalone XML, text, or hexadecimal, as appropriate. (Non-XML messages are returned as text unless they contain unprintable characters, in which case they are displayed as strings of hexadecimal digits.)

If this option is selected, only header filters and text filters can be applied and you cannot edit or create messages using formatting.

You might want to use this mode of display to:

� see messages as they exist in the queue without any formatting

� repair messages that have parsing errors due to incorrect header or user fields

� make changes to XML messages that are based on DTD or schema definitions

Edit under syncpoint control

Editing under syncpoint control provides a mechanism for restoring the state of the queue in the event of error or system failure. Any changes you make before the syncpoint can be rolled back to the previous syncpoint if no action has been taken to commit them.

Editing under syncpoint control enables the Commit and Rollback commands on the File menu. If you select this option, edited messages will not be placed on the queue until the next rollback or commit. If you do not select this option, you will not be able to roll back any changes you make to a queue or to messages. All changes will take place immediately.

Maximum number of messages per display

This option sets the maximum number of messages PathWAI Editor retrieves for display at one time. For example, if you select 25, only 25 messages are retrieved at one time. After you have browsed the first set of 25, you must retrieve more messages to see the next 25. (Once you have opened the queue, you can change the number of messages retrieved each time by changing the Depth value.)

Opening the Queue


It is best to view a small number of messages—from 20 to 50 at a time, depending upon the average size of the messages involved. You can use filters to reduce the number of messages retrieved by displaying only messages of interest.

The maximum number of messages that can be retrieved at one time is 200.

Note: The number of messages displayed may also be affected by the Maximum Response Size specified in the server profile. When the maximum size is reached, no more messages are retrieved. Messages that exceed the limit may be split.

WebSphere MQ only options

Context

This option determines what context is in effect for the queue. Context provides information about the origin of the message and the identity of the message’s originator. Context information is carried in eight fields of the WebSphere MQ message descriptor.

There are six options that control how context information is handled by queue managers as messages pass through:

� Default—Each queue manager that handles a message writes its own context information into the message descriptor.

� No Context—No context information is included in the message descriptor.

� Pass ID—The queue manager copies the identity context information from the original message into a new message and updates the origin information.

� Pass All—The queue manager copies the identity and origin context information unchanged from the received message to the new message.

� Set ID—The sending program sets the identity context for a message. The queue manager sets the origin information.

� Set All—The sending program sets both the identity and the origin context information.


Opening the Queue

Your choice of a context option affects your ability to edit information in the eight context fields in the message descriptor. (For more information, see the online Help for the Open Message dialog.)

WebSphere MQ security may prevent you from editing a particular context. You must have rights to edit a particular context field before you can change information in the field.

Display queue in logical order

If this option is selected, PathWAI Editor displays messages in the queue in logical rather than physical order.

Physical order is the order in which messages arrive on a queue. Logical order is the ordering of messages in a message group. Logical and physical orders may differ because members of a group may arrive at similar times from different applications or be received out of order because of rerouting or delay.

Reassemble segmented messages

If this option is selected, PathWAI Editor displays messages segmented because of their length reassembled as one message.

Open read only

If this option is selected, PathWAI Editor opens the queue for browsing messages only. This option lets you display a queue even though another user has the queue open for exclusive use. If the other user updates the queue, you see the updates only after you refresh or commit the queue.

If you open the queue in read only mode, you cannot create or edit messages.

The Message Window


The Message Window

OverviewWhen you click OK to set the Open Queue options, PathWAI Editor opens the Message window. The Message window is where you browse, edit, create, and manage the messages on the queue.

What you see displayed in the Message window depends on which filters you applied, if any, when you opened the queue, and what options you selected.

For example, if you applied any row filters, only messages meeting the criteria specified by the filters are displayed. If you applied any column filters, only those fields specified in the filters are displayed for the messages retrieved. If you opted to ignore message formatting, all messages except XML messages are displayed in fixed-sized blocks instead of labeled fields, whether formatted or unformatted. If you open the queue in View Only mode, you cannot edit the queue nor the messages it contains. Commit and Rollback commands are available only if you opened the queue under syncpoint control.

The following sections describe how messages are displayed in this window and how to set its display and editing options.

Message displayIn the Message window, each message is displayed as a row, with its own column headings. For XML messages, each column represents an element. For formatted raw messages, each column represents a field. Unformatted raw messages, including messages retrieved as hexadecimal digits, are broken down into fixed-size blocks, one per column. If you elected to display headers when you opened the queue, the fields comprising the message header are displayed as well.

The message number is displayed in the column to the left of the message. (If PathWAI Editor cannot parse a message because it does not match the message format definition, or has been split because the maximum response


The Message Window

size has been exceeded, the message number is displayed in red and has an exclamation point next to it.)

PathWAI Editor follows the WebSphere MQ rules for getting and putting messages: as messages are added or modified they are put to the end of the queue. (This assumes that all messages have the same priority and/or FIFO has been indicated. If the priority of messages differs, messages with a higher priority will be placed before messages of lower priority.) However, in the Message window, messages you create are inserted at the end of the current set of displayed messages and marked INS until you refresh the display. (If you are editing under syncpoint control, the new message is not placed on the queue until you commit the changes.) Similarly, edited messages are marked UPD and remain in their current position in the display until you select Refresh or commit the changes. Deleted messages are marked DEL.

Initially, only the first 20 fields of each message are displayed (not counting header fields.) Click the arrow at the end of the row to retrieve additional fields, 50 at a time.

Displaying header fieldsYou can toggle the display of header fields off and on by checking and unchecking the Show Headers checkbox at the top of the message display.

Setting queue depthYou can change the number of messages retrieved and displayed at one time by specifying a different queue depth:

You must Refresh the display after changing the queue depth to see the effects of the change.

Filtering messagesYou can apply existing message filters at the time you open a queue, but you can also create and apply filters to modify the contents displayed while you are in the queue. For information on creating and applying filters, see “Working with Message Filters” on page 107.

The Message Window


Editing under syncpoint controlEditing under syncpoint control enables the Commit and Rollback commands on the File menu.

If you are editing a queue under syncpoint control, no changes take effect until you commit them using the Commit command. Committing the changes updates messages on the queue, makes them visible to other programs, and establishes a new syncpoint. Rolling back changes using the Rollback command undoes all the changes you have made since the last syncpoint. Edited messages will not be visible until after the next rollback or commit.

Auditing changesUpdates to messages can be logged so administrators can maintain an audit trail.

If auditing is enabled, edit operations are logged in the file kxymsged.aud in the <candlehome>/msged/output directory (Windows) or the <candlehome>\unix\MsgEdit\output directory (UNIX). The following operations are logged:

� creating a queue

� deleting a queue

� deleting a message

� creating a message

If a message is edited (updated), it is logged as a create operation followed by a delete operation.

To enable auditing of updates:

1. Set the <Audit> line in the config.xml file to Log (see “Editing the server profile” on page 28 ):

<Audit>Log</Audit>

2. Restart the server (see “Starting and Stopping the Server” on page 39).


The Message Window

CommandsThe table below summarizes the commands available for managing and messages in the Message Window. Many of these commands are discussed in more detail in following sections and chapters.

Command Action

File Menu

CreateMessage

Access an editor to create a new message

Commit Save any changes made since the queue was opened or since the last commit. This option is available only if the queue was opened under syncpoint control. Otherwise, any changes take effect immediately.

Rollback Cancel any changes made since the queue was opened or since the last commit. This option is available only if the queue was opened under syncpoint control. Otherwise, changes take effect as they are made and cannot be undone.

Refresh Apply changes. Some changes, such as cut and paste, or create message, are displayed but do not take effect in the queue until you refresh the queue.

Print Print the entire contents of the queue. If you want to print a single message, select (check) it, select Edit from the popup menu, then click Print in the editor window.

PrintPreview

Preview the messages as they will appear in printed form. (This is a good way to view entire long messages, without having to scroll through them.)

CloseQueue

Close the queue and return to the Main window.

Exit Quit PathWAI Editor.

Edit Menu These options are also available from a popup menu when you right-click the beside a message. If you are applying an operation to multiple messages, you must select the messages and use the dropdown menu.

The Message Window


Edit Access an editor to modify an existing message.

Delete Delete the selected message or messages. If you editing under syncpoint control, the message is deleted from the display, but it is not deleted from the queue until you commit the changes.

Cut Cut the selected message or messages. You can use this command to change the order of messages in the open queue or to paste it into another queue.

Copy Copy the selected message or messages. You can use this command to clone a message for editing as a new message or to paste into another queue.

Paste Paste a message into a queue.

Forward Send the message to another queue. You will need to provide the name of the queue manager and the queue to which you are forwarding it.

Search Menu

Before you invoke the Find or Replace dialog you must select the column that you want to search. Find and Replace operations apply to the selected column (field or element) in all messages in the current display with the same format.

Find Find the data in the selected field.

Replace Replace the data specified in the Find what field with the data specified in the Replace with field.

Tools Menu

Row Filters Launch an editor to create, edit, or delete a row filter.

ColumnFilters

Launch an editor to create, edit, or delete a column filter.

ApplyFilters

Select one or more filters to apply to the messages in the queue.

VariantDefinitions

Launch an editor to create, edit, or delete a variant definition for formats with data-determined structure.

Load Load messages from a flat file into the queue.

Command Action


The Message Window

Unload Unload a selected set of messages, or all messages in the queue, into a new or existing flat file.

Debugger Launch the debugger console.

Help Menu

Contents &Index

Access the Table of Contents for the online Help.

PathWAIEditor for

Messaging

Access version number and other information about PathWAI Editor.

Command Action

Browsing and Selecting Messages


Browsing and Selecting Messages

Browsing messagesIf more messages are retrieved at one time than can be displayed in a single window, use the vertical scroll bar to see the remaining messages. If there are more messages in the queue than the number you specified for retrieval at a single time, use the Next button to retrieve the next set of messages and the Previous button to return to the previous sets. You can also go to

the top or the bottom of the queue, or type a particular message number in the Go to Message box and press Enter (or Refresh).

Use the arrows at the bottom of the screen to scroll left and right through the message fields. The and arrows scroll 1/3 of a screen at a time, the

and arrows scroll a screen at a time. (If there are only a few messages displayed or you are at the end of the set of messges, you will also see a horizontal scoll bar at the bottom of the screen.)

Selecting messagesEach message has a button on its left. Click this button to edit the message or right-click it to access a popup menu of commands for editing that can be applied to it. (You can access the same commands from the Edit menu in the menu bar.)

Each message also has a checkbox. Use the check boxes to select multiple messages for operations such as deleting, unloading, and forwarding. (You can select a block of messages by holding the Shift key and selecting the first and the last message in the block.)

Check Select All to select all messages in the current display.

For individual messages, Delete, Cut, Copy, and Forward commands are available from the popup menu. To apply these commands to multiple messages, select the messages by checking them, then choose the command from the Edit menu in the menu bar.


Copying, Moving, and Deleting Messages


OverviewPathWAI Editor supports a number of commands that let you edit the queues by duplicating, moving, and deleting messages.

Copying messagesCopying messages is a good way to create a set of messages that share the same format. You can copy one message at a time, or many. The copies can be placed in the same queue as the original message or in a different queue.

To copy a single message:

Right-click the button at the left of the message, then select Copy from the popup menu.

To copy several messages:

Click the checkbox beside each message that you want to copy, then select Edit > Copy.

To place the copy (or copies) in the same queue:

Select Edit > Paste.

To place the copy in another queue:

Close the queue, open the target queue (selecting the appropriate queue manager, if necessary), then select Edit > Paste in the new Message window.

When you paste messages into a queue, they are placed at the bottom of the queue, but appear in the current display until you select File > Refresh.

Moving messagesMessages can be moved within the same queue, or to a different queue, using the Cut and Paste commands. Using the Cut command removes messages from the queue, but leaves them in the PathWAI Editor clipboard so they can be pasted into the same queue or into a different queue. Pasting the messages puts them at the end of the target queue.



If you want to move messages from one queue to another queue without opening the destination queue, you can use the Forward command. Forwarded messages are removed from the current queue after they are sent to the target queue manager. (For more information, see “Forwarding Messages” on page 81.)

To cut a single message:

Right-click the button at the left of the message, then select Cut from the popup menu.

To cut several messages:

Click the checkbox beside each message that you want to copy, then select Edit > Cut.

To place the message or messages at the bottom the current queue:

Select Edit > Paste.

To place the messages in the clipboard in another queue:

Close the queue, open the target queue (selecting the appropriate queue manager, if necessary), then select Edit > Paste in the new Message window.

Deleting messagesIf you are editing under syncpoint control, messages you delete are marked as deleted and remain in the display, but are not deleted from the queue until you commit your current changes. Until you commit the changes, you can select the Rollback command from the File menu to roll back your deletions and restore the messages.

If you are not editing under syncpoint control, messages are deleted from the queue immediated. However, the messages will remain in the display, marked as deleted, until you refresh the display.

To delete a single message:

Right-click the button at the left of the message, then select Delete from the popup menu.

To cut several messages:

Click the checkbox beside each message that you want to copy, then select Edit > Delete.


Finding and Replacing Message Data


OverviewYou can search displayed messages for specific text in a particular field or element, or search for and replace specific text.

The Find and Replace commands apply to the selected column (field or element) in all messages in the current display with the same format. You must select the field (column) you want to search before you invoke the Find or Replace dialog.

PathWAI Editor starts the search at the field you select. If you start the search from a field part way through a displayed set of messages and PathWAI Editor does not find the search text, it asks if you want to continue from the top of the set to search the remainder.

Note: Fields that belong to repeating groups cannot be searched.

Searching the contents of a field or elementTo search the contents of a selected field in all displayed messages with the same format:

1. Select the column name in the first message with the format you want to search

2. In the menu bar, select Search > Find. The Find dialog appears. The name of the column being searched is displayed.

3. Type the text (or value) you want to search for.

4. Click Find.

5. To continue searching after PathWAI Editor has found the search text, click Find Next. If the queue contains more messages of the same format which are not in the current display, you must retrieve the next set of messages and repeat the search.



Replacing the contents of a field or elementTo replace the contents of a selected field or element in all displayed messages of the same format:

1. Select the column name in the first message with the format you want to search.

2. In the menu bar, select Search > Replace. The Replace dialog appears. The name of the column being searched is displayed.

3. In the Find what field, type the text (or value) you want to search for.

4. In the Replace with field, type the text or value you want to replace the data with.

5. Click Find Next to find the next occurrence of the search string, then click Replace to substitute the replacement text.Repeat step 5 until you have found and replaced all the instances in the displayed messages. If the queue contains more messages of the same format which are not in the current display, you must retrieve the next set of messages and repeat the search and replace operation.

If you are confident that you have selected the correct column, search string, and replacement value, you can use Replace All to replace all the instances in the currently displayed set of messages. You must retrieve the next set of messages and repeat the operation until you have retrieved all the messages in the queue.

6. Click Apply to apply the changes you have made. Click Cancel to close the dialog without applying the changes.


Forwarding Messages

Forwarding Messages

OverviewYou can forward messages from the current queue to another queue using the Forward command. You can also use the Forward command to retry sending messages from a dead-letter queue to their original destination after repairing them or to another queue for troubleshooting or analysis.

Unlike the Copy and Paste commands, the Forward command lets you move messages from one queue to another queue without manually opening the destination queue.

Forwarded messages are deleted from the originating queue.

Note: To forward WebSphere MQ messages, you must have a channel pair defined between the two queue managers (the originating queue manager and the destination manager). If necessary, contact your MQSeries Administrator to provide queue manager to queue manager connectivity.

Forwarding messages from the dead letter queueThe dead letter queue (DLQ) is a queue where undeliverable messages are sent. Usually they are undeliverable because of addressing problems, user data problems, or problems with the receiving queue.

Messages on the DLQ are prefixed with a dead-letter header that identifies the messages as undeliverable and includes a reason code. When a message is put on the DLQ, the original message descriptor fields of the message are copied into the data portion of the message.

If you retry sending messages, PathWAI Editor attempts to put the messages on the original destination queue. The DLQ header is stripped and the message is rebuilt as it was before the DLQ header was added. The original message descriptor is restored and the message is then put on the original destination queue.

When you forward the messages to a queue other than the original destination queue, you can choose to strip the DLQ header or leave the DLQ header in the message. If you strip the DLQ header, PathWAI Editor restores the original message descriptor.

Forwarding Messages


Using Forward with filtersThe Forward command combined with message filtering offers an effective way to distribute messages from dead letter queues into application-based resolution queues. For example, by using header column filters to select messages using fields in the DLQ header, you can then select and forward messages to their appropriate resolution queues for analysis and correction. For information on using filters, see “Working with Message Filters” on page 107.

Forwarding a messageTo forward a message:

1. Right-click the button to the left of the message and select Forward from the popup menu. If you are forwarding multiple messages to the same queue, check the box beside each message, then select Edit > Forward from the menu bar.

The Forward Messages dialog appears. The dialog differs depending upon whether you are forwarding WebSphere MQ or JMS messages.

2. In the Forward Messages dialog:– Select (click) the name of the owner of the queue to which you want to

forward the message from the list of Available Queue Managers (WebSphere MQ) or Available Queue Connections (JMS).

– Type the name of the queue to which you want to forward the message.

If you are forward messages from a WebSphere MQ DLQ, you can select the following options:

– Retry—Retry sending the selected messages to their original destination.

This option is valid only if the messages contain a DLQ header. PathWAI Editor uses the queue and queue manager found in the DLQ header and resubmits the messages to that queue. The DLQ header is automatically removed and the original message descriptor is rebuilt.

– Strip DLQ Header—Strip DLQ header if found.

3. Click to forward the message and return to the Message window, or click to return to the Message window without forwarding the message.


Loading and Unloading Messages


OverviewThe Load and Unload commands are used to store and retrieve messages from a queue. Loading adds messages from a file to the end of the currently displayed queue. Unloading saves selected messages to a file. These operations can be used for archiving messages, reusing test messages for regression testing, reordering messages, or preserving the displayed order of messages. Unloading and loading messages also enables you to view them in different character sets.

The file to which you are adding the messages or from which you are unloading messages must be located in your individual profile directory, in the messages subdirectory. For example, on UNIX, if your login ID is jdoe , these files must be in:

<candlehome>/unix/MsgEdit/Users/jdoe/Messages

If PathWAI Editor is creating a new file for the unloaded messages, it creates them in this directory.

Files containing WebSphere MQ messages must have a .pmu extension. Files containing JMS messages must have a .pju extension. File names are case-sensitive on UNIX.

Unloading messagesYou can unload messages selected from the set of messages displayed or unload the entire queue.

To unload messages from a queue into a flat file:

1. Retrieve the messages you want to unload, if necessary using one or more filters and displaying as many messages at one time as you need to include the desired messages.

2. Check the box beside each message you want to unload.If you want to unload all the messages in the queue, you do not need to select individual messages. Instead, you can check Unload All Messages in the Unload dialog.

3. Select Tools > Unload.



The Unload Messages dialog appears.

4. Specify the name of the file as follows:– If you want to add the unloaded messages to an existing file, type the

name in the File Name field or use the browse button to display a list of available files from which you can select a name.

– If you want PathWAI Editor to create a file for messages, type a name for the new file in the File Name field.

5. Specify how you want PathWAI Editor to handle the messages:– Check Append messages to the end if you are adding messages to an

existing file and you do not want PathWAI Editor to overwrite the existing messages in the file.

– Check Unload all messages if you want PathWAI Editor to unload all the messages from the queue.

– Check Delete unloaded messages if you want PathWAI Editor to delete the unloaded messages from the queue once they are saved to the file.

6. Click OK to save the unloaded messages to the specified file and return to the queue. Click Cancel to return to the queue without unloading the messages.

Loading messagesThe files containing messages to be loaded must be located in your individual profile directory, in the messages subdirectory. For example, if your login ID is jdoe, these files must be located in <install-path>/MsgEdit/Users/jdoe/Messages.

To load messages from a flat file into a queue:

1. In the Message window, select Tools > Load.

2. Specify the name of the file from which you want to load the messages as follows:– If you know the name of the file you want to load, you can type the name

in the File Name field, then click OK.

– If you are not sure of the name of the file, click the browse button to view a list of files. Select (click) the name of the file you want to load.



The dialog offers you the option of selecting which fields you want included in the message header:

� If you click OK without clicking , all the fields are included in the header.

� If you click , only the fields you select in the resulting dialog are included in the header. (By default, the fields encoding, characterSet, and format are checked.)

� If you click and then click Cancel to close the resulting dialog, all the attributes are included.

PathWAI Editor notifies you when the messages have been loaded.

Previewing and Printing Messages


Previewing and Printing Messages

Printing messages in the current displayYou can print all the messages in the current display by selecting Print from the File menu. The Print command displays the standard Print dialog for the environment in which you are using PathWAI Editor.

You can preview how the messages will appear in printed form using Print Preview. Since Print Preview displays the entire contents of each message within a single window, using Print Preview is also a good way to view the contents of long messages without having to scroll through them.

If you want to print or preview a single message, use the Print command in the message editor.

Printing or previewing a single messageTo print or preview a single message:

1. Click the button beside the message you want to print and select Edit from the popup menu.The Edit Message window appears.

2. Click Print or Print Preview.If you select Print, PathWAI Editor displays the standard Print dialog for your system. Select the printer you want to use and the number of copies you want to print.

If you select Print Preview, the Print Preview dialog appears. After you view the messages, you can click Print to print the messages, or click Close to close the preview dialog.

3. Click Cancel to close the Edit Message dialog.

Note: If you click OK, PathWAI Editor considered the message to have been edited and moves it to the bottom of the queue, even though you made no changes to it.

Creating and Editing Messages 87

Creating and Editing Messages

OverviewThis chapter covers how to create and edit messages using PathWAI Editor. It describes the various editing views available and provides instructions for editing messages using each view.

Chapter contentsCreating and Editing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Working with Formatted Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Working with Unformatted Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Working with XML Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Working with Hexadecimal Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Working with JMS Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

6




OverviewPathWAI Editor provides several editors, or editing views, for creating or modifying messages. The editing view available depends upon whether the message is formatted or unformatted and what type of message it is.

For formatted messages, PathWAI Editor open a tree view, with nodes based on the message format definition. For unformatted messages, PathWAI Editor opens a text view. In the text view, you can create string or XML messages. You can also open a hexadecimal editor to work with hexadecimal messages or an XML tree editor to create or edit XML messages. If you are working with JMS messages, you can also open special tree views to edit stream or map messages.

In the tree and text views you can edit message headers as well as message data and preview and print messages. You can also edit the message properties of JMS messages.

Creating a new messageTo create a message:

Select File > Create Message.

You can create either formatted or unformatted messages.

If you select a message format in the Select Format dialog, PathWAI Editor opens the Create Message window in a tree view. In this view, you can fill in or edit message data and add or remove nodes, so long as the changes do not violate the message structure specified in the format definition. (For more information, see “Working with Formatted Messages” on page 92.)

If you do not select a message format, PathWAI Editor opens the Create Message window in text view. For more information, see “Working with Unformatted Messages” on page 94.

New messages are placed at the end of currently displayed set of messages and marked INS until you refresh the display or commit the changes. For example, if only 25 messages are displayed at a time, the new message is inserted at the end of the set as number 26. When you refresh the display or commit your changes, the new messages will be displayed at their actual



position in the queue. (If all messages have the same priority and/or FIFO has been specified, messages are placed at the bottom of the queue. If the priority of messages differs, messages with a higher priority will be placed before messages of lower priority. If you are editing under syncpoint, new messages are not added to the queue until you commit the changes.)

Editing a messageTo edit an existing message:

Click the button to the left of the message

The editing view that opens depends upon the type of message you select:

For more information on modifying messages using the various editing views, see “Working with Formatted Messages” on page 92 or “Working with Unformatted Messages” on page 94.

If you are interested in editing specific text in one particular field, and especially if you want to edit the same text in the same field in all messages with a particular format, you can use the Find and Replace command (see “Finding and Replacing Message Data” on page 79).

Any messages you edit are left in their current position in the display and marked as edited until you refresh the display or, if you are editing under syncpoint, commit or back out your changes. When you refresh the display or commit the changes, the edited messages are moved to the end of the queue. This means that if there are more messages in the queue than are currently displayed, the messages will disappear from display.

Note: PathWAI Editor interprets opening a message in an editing window and clicking OK as a modification. Be sure to click Cancel if you want to exit the editing window without modifying a message.

If you select PathWAI Editor opens

A formatted message tree view

An unformatted XML message or a raw message that contains only printable characters

text view

An unformatted raw message that contains unprintable characters

hexadecimal editor



Editing message headersIn the tree and text editing views you can edit the message header as well as the message body. When you click , PathWAI Editor opens a new editing view. This view displays the fields in the standard header for the message type (WebSphere MQ or JMS), as well as additional header entries used by PathWAI Editor.

Message header fields are used by applications and messaging systems to route and identify messages. Many of these fields are set at the time the message is sent, received, or consumed.

WebSphere MQ fields

You can set or edit any field of the WebSphere message header, or message descriptor. Valid values and values that may be ignored are described in IBM's WebSphere MQ Application Programming Reference, Document Number SC34-6062 or superceding documents.

Note: If you want to increase the priority of a message, you should edit under syncpoint control. When a message is edited out of syncpoint control, PathWAI Editor first writes the edited message to the queue, and then deletes the original message. This is done to ensure that messages are not lost while editing. If the updated message has a higher priority, it is placed in the queue ahead of the original message, and gets deleted when the editor attempts to remove the original message. Under syncpoint control, the original message is removed from the queue first, and then the updated message is written.

JMS fields

You can set/edit the following three fields:

� JMSCorrelationID

� JMSReplyTo

� JMSType

The provider sets the JMSRedelivered field. All other properties are set by the Send (Write) Method. For information on JMS header fields, consult Sun Microsystem's Java Messaging Service specification, version 1.1 or later.



PathWAI Editor fieldsPathWAI Editor add the following fields to the header of messages it handles:

� Body Type

� KXY_STATUS

� MessageLength

� OriginalMessageLength

� RemainingMessageLength

� STATUS

� Status Flag

� Format

� pFormat

� XMLEncoding

All of these fields are either read-only or ignored, except XMLEncoding, which is used for standalone XML messages (that is, messages with no document type definition or XML Schema)

Working with Formatted Messages



OverviewIf you are creating or editing a formatted message, PathWAI Editor opens the tree editor (Figure 6). The nodes of the tree represent the fields or elements defined in the message format. The properties of each field (such as minimum and maximum length and cardinality), or the attributes of each element, are displayed after the node name.

Figure 6. Tree Editor



Notes: If you selected Ignore Message Formatting when you opened the queue, you cannot create formatted messages.

If you want to edit a formatted raw message which contains hexadecimal data using a hex editor, you must select Ignore Message Formatting when you open the queue. Then when you select Edit, PathWAI Editor will launch the hex editor. Otherwise, the message will open in the tree editor.

Including the format name in the message descriptorTo create a formatted message, you must select the name of a predefined format. PathWAI Editor inserts the name of the selected format into the format field of the message descriptor, unless you also select the Do not update header format option in the Select Format dialog.

Adding and deleting nodesYou can remove a field or element or add another of the same type by clicking the button to the left of a node and selecting Add or Remove from the popup menu. Any addition or deletion you make must be consistent with the message format definition. For example, you cannot delete a node whose cardinality is 1 if it is the only node of that type.

You can edit attribute values, but you cannot change field properties.

Entering message dataYou enter or edit message data in the text box under each node. You can copy, cut, and paste text or undo an action using standard key commands (Ctrl+c, Ctrl+x, Ctrl+v, Ctrl+z.

Editing message propertiesIf you are working with a JMS message, you can also edit the message properties. Message properties specify values in addition to those provided by the header fields.

Click Edit Properties to open the editing view. Click [-] next to Properties to close the view.

Working with Unformatted Messages



OverviewIf you are creating or editing an unformatted message, PathWAI Editor opens an editing view with a text editing area (Figure 7). You can use the text area to create or edit string messages and XML messages in which you want to include prolog information or processing instructions. From this view you can also invoke a hexadecimal editor or an XML tree editor.

Figure 7. Text Editor



Editing view and type of messageIf you are creating an unformatted raw message that contains hexadecimal data or unprintable characters, you can access a hexadecimal editor by selecting Hexadecimal as the Type of Message. If you are editing an unformatted message that contain unprintable characters, it opens directly in a hexadecimal editor. (For information on using the hex editor, see “Working with Hexadecimal Messages” on page 100.)

If you are creating an XML message, you must select XML as the Type of Message. Otherwise, PathWAI Editor cannot check the well-formedness of the message. You can use the text editing area or access the XML tree editor. You can switch back and forth between the two editors to create or edit XML messages.

The XML tree editor simplifies the creation of XML messages, because it provides the document structure for you. You do not have to worry about creating element tags or remembering to set off attribute values in quotes. However, in the tree editor, messages begin with the root element. If you want to add information such as a document type declaration or processing instructions to the message prolog, you must edit the message in the text area. (For more information on using the XML tree editor, see “Working with XML Messages” on page 97.)

The text area status tableIf you are editing or creating a string message, you will see a Text Area Status table above the text area. It contains the following fields:

As you make changes in text area, the Current Position and Total Character fields are updated with the current values.

The Text Area Status table is not available if you are creating or editing an XML message.

Go to Position You can enter a positive integer in this text box to go to that position in the text.

Current Position This is a read-only text box that shows the current cursor position in the text area.

Total Characrers This is a read-only text box that shows the total number of bytes in the text area.



Entering message data in the text areaYou create or edit the message by typing in the text area. As you type, the the position of the cursor and the total number of bytes are shown in the status table.

You can use standard key commands (Ctrl+c, Ctrl+x, Ctrl+y for Copy, Cut, and Paste) to edit text.


Working with XML Messages


OverviewThe easiest way to create XML messages is to paste an existing message into the text area and then use the XML tree editor to fill in, or edit, the attribute values and message data. You can also create XML messages from scratch, in either the text area or the XML tree editor, or both.

All XML messages must be well-formed XML documents. If you create messages in the text area, you are responsible for using correct XML document structure and syntax. PathWAI Editor editor validates the message only when you save it.

If you create messages in the XML tree editor, PathWAI Editor provides the XML document structure and enforces the XML naming conventions as you enter values.

XML declarations, DTDs, and XML SchemasIf you create a message in either the text area or the tree editor, PathWAI Editor creates the XML declaration, so you can begin your message with the root element.

If you want to include information, such as a document type declaration or processing instructions, before the root element you must edit the message in the text area. You must also edit the message in the text area if you want to include reference to an XML Schema or include CDATA in the message body.

Naming conventionsElement and attribute names must conform to XML naming conventions. The following conventions are provided for your convenience. The W3C XML Recommendation remains the final authority on XML names. For detailed information on the XML names, please consult the World Wide Web Consortium at http://www.w3.org.

� XML names are case-sensitive.

� Element names must begin with a letter or underscore and may contain any number of letters, numbers, hyphens, periods, and underscores. (They may also include accented Roman characters and letters from

http://www.w3.org

http://www.w3.org

http://www.w3.org

http://www.w3.org



alphabets such as Cyrillic, Greek, Hebrew, Arabic, Thai, Hiragana, Katakana, and Devanagari.) Space, tab, newline, equals (=), and quote characters are not allowed.

� Elements may have any number of attributes, but each attribute must have a unique name.

Using the text editorYou create or edit the message by typing in the text area. As you type, the the position of the cursor and the total number of bytes in the message are shown in the status table. You can use standard key commands (Ctrl+c, Ctrl+x, Ctrl+y for Copy, Cut, and Paste) to edit text.

Using the XML tree editorTo add or delete elements and attributes in the tree editor, click the button to the left of the node to access a popup menu. Using the popup menu you can:

There is no way to edit an element or attribute name in the XML tree view. You can delete (remove) the node and then add it again with a revised name, or you can return to the text area and edit the element or attribute name in that view.

Add Child Add a subordinate, or descendant, element to the current node

Add Sibling Add a coordinate element

Remove Node Delete the current node

Add Attribute Add an attribute to the element

RemoveAttribute

Delete an attribute from the element

Add Data Add message text



Figure 8. XML Tree Editor

To edit text in the data fields, you can use standard key commands for copy (Ctrl+c), cut (Ctrl+x), paste (Ctrl+v), and undo (Ctrl+z) or access a popup edit menu by right-clicking while the cursor is in a field. The text of the message can include any character in the character set specified in the prolog.

You cannot edit the message header in the XML tree view. You must return to the text editor.

Working with Hexadecimal Messages



OverviewUnformatted raw messages that contain hexadecimal data open directly in the hexadecimal editor when you edit them. If you are creating an unformatted raw message that contains hexadecimal data or unprintable characters, you can select the hexadecimal editor when the Create Message window opens (see Figure 7 on page 94).

In the hex editor, you can enter or change information represented in either the Text field or the Hexadecimal field. Changes you make in one are reflected the other.

When you enter changes in the hex editor, they are also reflected in the text area of the text view. You must return to the text editor to edit the message header or to preview or print the message.

(If you want to edit a formatted message which contains hexadecimal data using a hex editor, you must select Ignore Message Formatting when you open the queue. Then when you select Edit, the hex editor will launch.)

Figure 9. Hexadecimal Editor



Entering message dataThe hexadecimal editor supports cut, copy, and paste operations using key commands (Ctrl+x, Ctrl+c, Ctrl+v), but you cannot Undo commands.

As you type, or move the cursor using the left and right arrow keys, the editor displays the following information:

The Status area at the bottom of the editor displays alerts when there are problems with the message text or editing operations.

The hex editor does not support double-byte character sets.

Area Shows

Offset Hexadecimal offset into the data buffer

Text The text of the message in ASCII or EBCDIC characters. Any unprintable characters are shown as dots (...)

Hexadecimal The hexadecimal numbers representing the message text.

CurrentPosition

The current offset position of the cursor

Current Text The ASCII or EBCDIC character at the current position

Current Hex The hex number at the current position

Total Bytes The total number of bytes in the message

Working with JMS Messages



OverviewPathWAI Editor supports all JMS message types except Object. Unformatted text messages are created and edited in a text view; string and map messages are handled as unformatted messages which are edited in a tree view.

PathWAI Editor let you edit JMS header fields and define and edit message properties.

Editing JMS header fieldsYou can edit the header fields of JMS messages in either a text or a tree view. Although all the fields appear empty if you try to edit them when you are creating a message, you can set only the following three fields, normally set by the client:

– JMSCorrelationID

– JMSReplyTo

– JMSType

The provider sets the JMSRedelivered field. All other fields are set by the Send (Write) method.

For valid content of these fields, refer to the Java Message Service specification referenced in the Preface.

If you are editing a JMS message, you will be able to see all the JMS header fields as well as the fields added by PathWAI Editor.

Editing JMS message propertiesJMS messages may contain properties in addition to the common properties already in the header. These properties may include standard properties defined by JMS, as well as properties specific to a JMS vendor implementation or to a particular application. Each property is characterized by an attribute "Type" and a value.

You can edit the message properties from a tree or text editing view. When you click Edit Properties, PathWAI Editor opens a header tree editing view



beside the message body. When you are creating a messge, this view is empty except for the root node Properties. You can add any properties you want.

Property names obey the rules for message selector identifiers. See the Java Message Service specification referenced in the Preface

Adding message properties

To add message properties:

1. In JMS tree or text editing view, click Edit Properties.The Properties editing view opens.

2. Click the button beside the root node (Properties) and select Add from the dropdown menu.The Add/Edit Property dialog appears.

3. Enter a name for the property.Property names obey the rules for message selector identifiers.

4. Select a property type from the list of Available property types.

5. Enter a value for the property.

6. Click to save the new properties and return to the message editing view. Click OK to save the new properties and close both editing views. Click Cancel to return to the message editing view without adding the new property.

Editing message properties

If you are editing an existing message, this view contains the standard predefined properties and any properties you added.

To edit the JMS message's properties:


2. Click the button beside the node (property) you want to edit and select Edit from the dropdown menu.The Add/Edit Property dialog appears.

3. Modify any or all the following parameters:� Property name

� Property type



� Property value

4. Click to save the changes and return to the message editing view. Click OK to save the changes and close both editing views. Click Cancel to return to the message editing view without adding the new property.

Deleting message properties

To delete a JMS message's property:


2. Click the button beside the node (property) you want to edit and select Delete from the dropdown menu.PathWAI Editor asks you to confirm that you want to delete the property..

3. Click OK to delete the selected property. Click Cancel to close the dialog without deleting the property.

Creating and editing stream and map messagesPathWAI Editor supports both map and stream JMS message types. Stream messages consist of a stream of primitive values in Java. Map messages consist of a set of name/value pairs, in which names are strings and values are primitive types in Java.

When you create a message in a JMS queue without selecting a message format, stream and map are among the types of messages you can select in the Create Message window. If you select one of these two types, PathWAI Editor opens a tree editing view that enables you to create a message of that type.

When you edit a stream or map message, PathWAI Editor opens the appropriate view.

Creating a stream message

To create a stream message:

1. Click the button beside the root node (Message) and select Add Child from the dropdown menu.The Add Child dialog appears.

2. Select the value type from the list of available types and click .



3. Click the button beside the new node and select Add Data from the dropdown menu.The Add Data dialog appears.

4. Enter a value for the node and click .

5. Click the button beside the node and select Add Sibling from the dropdown menu.The Add Sibling dialog appears.(You can also click beside the root node and select Add Child. The node will be added after the first child node.)

6. Select the value type and click .

7. Click the button beside the new node and select Add Data from the dropdown menu.The Add Data dialog appears.

8. Enter a value for the node and click .

9. Repeat steps 5–8 as need to complete the message.

Creating a map message

The steps for creating a map message are the same as for creating a stream message, except that you will be asked to supply a name for each node (value).



Working with Message Filters 107

Working with Message Filters

OverviewMessage filters enable you to retrieve only messages that match criteria you specify and to see only the message fields or elements you are interested in.

This chapter describes the row and column filters that PathWAI Editor supports and provides instructions for creating, applying, editing, and deleting them.

Chapter contentsAbout Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Applying Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Creating Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Editing Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Deleting Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Creating Column Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Editing Column Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Deleting Column Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

7

About Message Filters



OverviewBy default, PathWAI Editor displays all the messages on a queue. Usually, however, you want to view or edit only a subset of those messages, or to view only specific fields in the messages. Filters let you limit the messages retrieved to those messages that match certain criteria and to only the fields you are interested in.

You can create, edit, and apply filters without opening a queue, or while you are in a queue. You can save the filters you create for later use and revise them as required for application development and testing. Filter definitions are stored in the same metadata repository (MDR) as message format definitions so they can be shared by all PathWAI Editor users, but they can be edited only by the user who created them.

PathWAI Editor supports two types of message filters: row filters and column filters. Row filters let you limit the set of messages retrieved by specifying criteria for particular fields. Row filters are also used to allow processing of messages with variable formats. Column filters let you display only specific message fields in the messages retrieved. Both row and column filters may be defined on either message headers or message data. Fields that belong to repeating groups cannot participate in row or column filtering.

Note that filters apply to the actual format definition used to parse a message, which may not always be the one in the format field in the message descriptor (see “How PathWAI Editor determines the message format” on page 60).

Most filters are based on message formats definitions. PathWAI Editor also supports a special type of row filter for unformatted text or hexadecimal messages. This special text filter allows you to display a substring of a message without specifying particular columns.

Row filtersRow filters allow you to specify conditions that particular fields (or elements) in a message must satisfy in order to be retrieved. For example:

age>21 AND registered=="yes"

Row filters are defined using the Row Filter dialog, which contains an expression editor. When you select a format from the list of available formats,



the fields (or elements) in the format are displayed. You can then select individual fields and set values to create an expression that defines the set of conditions that the filter represents. See “Creating Row Filters” on page 113.

Column filtersColumn filters allow you to restrict the message fields returned by the Editor to specific fields of interest. For example, a message might be 500Kb in size, but you might be interested in only the 20 byte field towards the end of the message.

Column filters are defined using the Column Filters dialog. When you select a format from the list of available formats, the fields (or elements) of that format are displayed. You can then select the fields to be displayed when messages are retrieved. See “Creating Column Filters” on page 123

Variant format definitionsIn addition to letting you tailor the messages PathWAI Editor retrieves to your requirements, filters provide an additional level of flexibility for message parsing.

Sometimes the layout of a message is determined by contents of one or more fields in the message. Such messages typically have a fixed portion at the beginning of the message, followed by the variable portion. Filters allow you to process such messages, using the Variant Definitions (subtypes) feature.

PathWAI Editor uses format/filtern/formatn triplets to define variant formats. For more information, see “Creating Variant Definitions” on page 127.

Sharing filter and variant definitionsIf you are using configuration files rather than an LDAP server, and the files are not shared through a networked file system, any changes—creation, editing, deletion—are limited to the server on which the changes are made unless the configuration file is distributed to other servers. Since PathWAI Editor provides no mechanism for merging configuration files, you must exercise extreme caution to avoid overlaying changes and getting files out of sync.

For this reason, Candle strongly recommends that you use an LDAP directory to share formats and filters.



Sample filtersThe samples provided with PathWAI Editor include one which demonstrates how filters work and the relationship between filters and message formats. Refer to “Sample 1” on page 141 for instructions on loading the sample message files and using the sample filters.

You can also view the sample filters using the appropriate (row or column) filter editor.


Applying Filters

Applying Filters

OverviewYou can apply filters when you initially open a queue or while you are already in one.

Since queues may contain messages of more than one format, you can specify any number of filters to be applied to the queue. However, only one filter of each type (row data, row header, column data, column header) can be applied to each format. If you need to apply two filters to messages with the same format at the same time, you should combine them into a single filter.

Note: Since there are only two message header formats, one for each message type (WebSphere MQ and JMS), you can select only one column or row header filter at any time. You must check the box beside the list box title to enable selection of a header filter.

Note that if you apply filters to a queue, messages that do not belong to any of the filter formats are not included.

Applying filters when opening a queueWhen you click the name of a queue, the Open Queue dialog appears. In this dialog, you can specify a number of options, including which filters should be applied. The filters you applied last time you opened the queue are selected.

Deselect the filters you do not want to apply for this session and select the filters you want to apply from the lists of available row and column filters.

Note that if you select Ignore Message Formatting, only text and header filters can be applied.

Applying filters while in a queueIn the Messages window, you can apply filters to an open queue by selecting Tools > Apply Filters. The Apply Filters dialog appears (see Figure 10 on page 112).

The Apply Filters dialog contains scrolling lists of available row and column data and header filters. The filters you applied the last time you filtered the queue are selected.

Applying Filters


Figure 10. The Apply Filters Dialog

To apply a filter:

1. Uncheck any filters you do not want to apply.

2. Scroll in the appropriate list until you find the filter or filters you want to apply.

3. Click the box beside a filter to select it.

4. Click OK to select the filters and close the dialog. Click Cancel to close the dialog without applying any filters.


Creating Row Filters


OverviewCreating row filters involves creating a comparison expression, or set of expressions, that define the condition that the filter represents. For example,

Age>25 AND zip=="91301"

You can create row filters at any time by selecting Tools > Row Filters in either the Main window or the Message window to invoke the Row Filter dialog.

The Row filter editorThe Row Filter editor consists of:

� an expression editor

� an operators palette

� a filter definition display box

� format lists

� a structure display box

� buttons

Expression editor

The expression editor is where you define conditions consisting of a field name, a comparison operator, and a comparison value. Each expression is then added to the filter definition display. PathWAI Editor inserts the field or element name in the editor when you select it in the Format Structure display box.



Operators palette

The Operators palette lets you:

� add expressions to the filter definition

� insert the Boolean operators AND and OR to create complex expressions

� bracket AND’ed or OR’d expressions

� delete expressions from the filter definition

� edit expressions

Filter definition

As you create each expression, you add it to the filter definition. The filter definition is displayed in a box below the expression editor.



Formats and Format Structure boxes

The Formats boxes contain lists of the format definitions available to the server. When you select a format, its structure is displayed in tree format in the Format Structure box.

MQMD and JMSMD are formats defined by PathWAI Editor for the purpose of creating filters for WebSphere MQ and JMS message headers, respectively. All other Application Formats are user-defined message formats. System Formats are WebSphere MQ-defined message formats.

Buttons

The buttons in the editor let you:

Open the Retrieve Filter dialog to select filters for editing

Save a filter you have created or edited. Once you have named the filter and specified its type (data or header), you are returned to the editor.

Invoke the Delete Filter dialog, where you can select the filter that you want to delete.

Clear the current filter definition. You must clear any current definition before you can select another format and create a new definition or edit an existing one.



Creating a simple filter

1. In the Formats scrolling list, select (click) the format of the messages for which you are creating the filter.The structure of the message appears in expanded tree form in the Structure box.

2. Click the name of the field or element whose value you want to filter on.The name of the field appears in the Field Name area of the expression editor.

Note: Fields that belong to repeating groups cannot participate in filtering and cannot be selected for inclusion in expressions.

3. From the dropdown menu in the expression editor, select the appropriate comparison operator: equal to (==), not equal to (!=), greater than (>), less than (<), greater than or equal to (>=), or less than or equal to (<=).

4. In the Value field, type the string or number you want to compare, for example a product code, a name, or a price.The value can be a number or a string. Strings must be enclosed in double quotes (“ “). Special characters, such as backslash (\), double quote ("), new line (n), and carriage return (r), must be preceded by a backslash.

Binary values must be specified using the Binary function with the hexadecimal value of the string as its parameter. For example,

Binary("8080")

represents a binary constant having 2 bytes, each with the value of -128.

Close the editor window. If you have not saved the current definition, it is deleted.

Access help for using the editor



5. To add the expression to the filter definition, click either the or button.

The filter expression you just entered appears in the Filter definition box.

6. Click .The Save Filter dialog appears

7. Type a name for the filter and specify whether it is a data or a header filter.Filter names may have a maximum length of 32 characters. They can contain only letters, digits, hyphens (-), and underscores (_).

8. Click to save the definition.PathWAI Editor notifies you that the definition has been saved successfully. Click to return to the row filter editor.

9. If you are finished creating definitions, click to close the row filter editor. To define another filter, click , then repeat steps 1–8.

Creating a complex filterYou can create complex expressions using the boolean operators AND and OR and parentheses to group expressions. The following procedure demonstrates how to use these operators.

1. Create the first expression following the procedure for “Creating a simple filter” on page 116. For example:

age>=21

2. Select the new expression, then click in the Operators palette.AND is added after the first expression.

3. Create another expression, then select the first expression and click .The second expression is added to the Flter definition window below the first expression.

4. Select the first expression, then click the left parens button.A left parens is inserted at the beginning of the first expression.

5. Select the second expression, then click the right parens button.A right parens is added to the end of the second expression.

6. Select the second expression again, then click .OR is added after the right parens at the end of the second expression.



7. Create a third expression, select the second expression, then click .You should have a complex expression that looks like the following:

(Expression 1 ANDExpression 2) ORExpression 3

8. Click .The Save Filter dialog appears

9. Type a name for the filter and specify whether it is a data or a header filter.Filter names may have a maximum length of 32 characters. They can contain only letters, digits, hyphens (-), and underscores (_).

10. Click to save the definition.PathWAI Editor notifies you that the definition has been saved successfully. Click to return to the row filter editor.

11. If you are finished creating definitions, click to close the row filter editor. To define another filter, click , then repeat steps 1–10.

Creating a filter for unformatted textPathWAI Editor provides a special type of row filter for unformatted text or hexadecimal messages. The same filter that is used to select which messages to display is used to select a substring of the message for display. That is, it acts like a column filter does for formatted messages.

These filters are always created for a special message format called TextMessage, which is defined in the metadata repository. The TextMessage format has three fields: TextData, Length, and StartOffset. You create a row data filter for this format consisting of from 1 to 3 clauses connected by the AND operator.

For example,

TextData == “brown” AND StartOffset == 201 AND Length == 50

will select only those messages that are unformatted text and contain the substring “brown”. Only 50 bytes, starting at offset 201, will be retrieved.

StartOffset == 201 AND Length == 50

will retrieve 50 bytes, starting at offset 201 from unformatted text or hexadecimal messages.



StartOffset == 201

will retrieve messages starting from the offset 201.

Editing Row Filters


Editing Row Filters

OverviewOn occasion you may need to edit a row filter. For example, you may want to change one or more of the screening values. Editing a row filter and then saving it with another name is also good way to create a filter that differs only slightly from an existing filter.

Only the user who created the filter can edit it.

Editing a row filterTo edit a row filter:

1. In the Main or Message window, select Tools > Row Filters.The Row Filter editor appears.

2. Click to access the Retrieve Filters dialog.Row is already selected for Type.

3. Click , then click the filter you want to edit in the list of available row filters.If you have many filters, you can restrict the set of available filters that appear in the list by selecting the format to which the filter you want to edit applies or by typing the name of the user who created the filter (Owner) before retrieving the list of filters.

4. Click .The filter you selected appears in the Row Filter editor.

5. Add new expressions to the filter definition as described in “Creating a simple filter” on page 116. To modify an existing expression:A. Select (click) the expression in the filter definition box.

The expression appears in the expression editor.B. Modify the expression as required (for example, change the value of the

field or the comparison operator).

C. Click .

PathWAI Editor changes the expression.


Editing Row Filters

6. Click to save your changes.The Save Filter dialog appears with the current name of the filter in the Name field.

7. If you want to save the edited filter as a new filter, select the name, type the new name for the filter, then click . If you want to save the changes without changing the name or type of the filter, simply click .

Deleting Row Filters


Deleting Row Filters

OverviewDeleting filters deletes them from the MDR. Only the user that created a filter can delete it.

Deleting a row filterTo delete a row filter:

1. From the menu bar in the Main or Message window, select Tools > Row Filter.The Row Filter dialog appears.

2. Click .The Delete Filter dialog appears listing all the filters created by the current user ID.

3. Select (click) the name of the filter you want to delete from the Filters list.The name appears in the box above the list.

4. Click to delete the selected filter. PathWAI Editor asks you to confim the deletion.

5. Click to delete the filter and close the dialog, or click to close the dialog without deleting the filter.


Creating Column Filters


OverviewColumn filters let you specify which fields in a message are displayed when messages are retrieved from a queue. Using column filters means less scrolling to find the fields you want to work with.

You create column filters using the Column Filter editor. The editor can be invoked from the menu bar in either the Main window or the Message window by selecting Tools > Column Filter.

The Column Filter editorThe Column Filter editor contains two boxes. One box shows a list of available formats, the other displays the structure, or layout, of a selected format in tree form.

The buttons in the editor let you:

Open the Retrieve Filter dialog to select filters for editing

Save a filter you have created or edited. Once you have named the filter and specified its type (data or header), you are returned to the editor.

Invoke the Delete Filter dialog, where you can select the filter that you want to delete.

Clear the current filter definition. You must clear any current definition before you can select another format and create a new definition or edit an existing one.

Close the editor window. If you have not saved the current definition, it is deleted.

Access help for using the editor



Defining a column filterTo define a column filter:

1. From the menu bar in either the Main or Message window, select Tools > Column Filters.

2. Select (click) the format for which you want to define the filter.Its structure is displayed in the Format Structure box in a tree structure.

3. Select the fields to be displayed by clicking the box beside them. You can select either a parent node or individual child nodes. Clicking a parent node includes all its child nodes.

Note: Fields that belong to repeating groups cannot participate in filtering and cannot be selected.

Only the fields you have selected appear when messages are retrieved.

4. Click .The Save dialog appears.

5. Type a name for the filter and select its type: data or header.

6. Click to save the definition.PathWAI Editor notifies you if the definition has been saved successfully and returns you to the Column Filter editor.

7. If you are finished creating definitions, click to close the editor. To define another filter, click , then repeat steps 1–6.


Editing Column Filters

Editing Column Filters

OverviewOn occasion you may need to edit a column filter. For example, you may add a field to messages with a particular format and want to have the field appear when those messages are displayed. Editing a column filter is also good way to create a filter that differs only slightly from an existing filter.

Only the user who created the filter can edit it.

Editing a column filterTo edit a column filter:

1. From the menu bar in either the Main or Message window, select Tools > Column Filters.

2. Click Open. . . to access the Retrieve Filters dialog.Column is already selected for Type.

3. Click Get Filters, then click the filter you want to edit in the list of available column filters.If you have many filters, you can restrict the set of available filters that appear in the list by selecting the format to which the filter you want to edit applies or by typing the name of the user (Owner) who created the filter before retrieving the list of filters.

4. Click OK.The filter you selected appears in the Column Filter editor.

5. Make the changes you want by checking or unchecking fields in the Format Structure box.

6. Click Save to save your changes.The Save Filter dialog appears with the current name of the filter in the Name field.

7. If you want to save the edited filter as a new filter, select the name, type the new name for the filter, then click OK. If you want to save the changes without changing the name or type of the filter, simply click OK.

Deleting Column Filters


Deleting Column Filters

OverviewDeleting filters removes them from the MDR. Only the user who created a filter can delete it.

Deleting a column filterTo delete a column filter:

1. From the menu bar in the Main or Message window, select Tools > Column Filter.The Column Filter editor appears.

2. Click .The Delete Filter dialog appears listing all the filters created by the current user ID.

3. Select (click) the name of the filter you want to delete from the Filters list.The name appears in the box above the list.

4. Click to delete the selected filter. PathWAI Editor asks you to confim the deletion.

5. Click to delete the filter and close the dialog, or click to close the dialog without deleting the filter.

Creating Variant Definitions 127

Creating Variant Definitions

OverviewThis chapter discusses how to create the variant format definitions that allow PathWAI Editor to parse messages whose stucture varies according to the value of a particular field.

Chapter contentsAbout Variant Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Creating Variant Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Editing a Variant Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Deleting a Variant Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

8

About Variant Formats



What is a variant format?Some messages have formats whose stucture is determined by the value of a particular field. Such messages typically have a fixed portion at the beginning of the message, followed by the variable portion. PathWAI Editor handles this variable formatting using variant format definitions.

A variant format definition consists of a format–filtern–formatn triplet. The first format is the “source” or “common” format, which defines the fields common to all the variant formats, including the field whose value determines the structure of the variant formats. For each possible variant of the source format, there is a format definition and a row filter, defined using the value of the field that determines the variant.

Once PathWAI Editor determines that a format has variants, it applies the filters and identifies the appropriate format to use for processing each message with the source format. It sets the pFormat tag in the message header to indicate the actual format it used to parse the message.

Variant format definitions are available for use by all users through the metadata repository, but only the user who created them can edit or delete them.

How are variant formats created?The definitions of the common format and all its possible variants are created in the Message Format Editor. Then the filters for each variant are created in PathWAI Editor, using the Row Filter editor. Finally, the format–filter–format triplet is created using the Variant Format option in the Tools menu.

Sharing filter and variant definitionsIf you are using configuration files rather than an LDAP server, and the files are not shared through a networked file system, any changes—creation, editing, deletion—are limited to the server on which the changes are made unless the configuration file is distributed to other servers. Since PathWAI Editor provides no mechanism for merging configuration files containing filter and variant definitions, you must exercise extreme caution to avoid overlaying changes and getting files out of sync.



For this reason, Candle strongly recommends that you use an LDAP server to share filters and variant format definitions.

An Example of Variant Formats



OverviewThe samples provided with PathWAI Editor contain examples of variant formats.

The formats used are Smplvar, Smplvar1, and Smplvar2. Smplvar is the source format and defines the fields that all the variant formats have in common. It has a fixed portion, a four-character eye-catcher field, followed by a four-character field called Discr, the contents of which determine the layout of the subsequent fields.

Smplvar1 and Smplvar2 are the formats that are actually used to parse the messages. Smplvar1 is used if the value of the field Discr is VAR1, and Smplvar2 is used if the value is VAR2.

Two row filters, Smplvar1, and Smplvar2, define these two conditions on the original format Smplvar:

– Filter Smplvar1 contains the expression:

Discr==”VAR1”

– Filter Smplvar2 contains the expression:

Discr==”VAR2”

The variant formats and the filters are associated by two variant definitions:

– Variant definition Smplvar1 comprises the triplet:

Smplvar/Smplvar1/Smplvar1

– Variant definition Smplvar2 comprises the triplet:

Smplvar/Smplvar2/Smplvar2

PathWAI Editor determines which format to use on the basis of message content. First, it determines that a particular message has format Smplvar (either because the descriptor format field is Smplvar, or because the message belongs to a queue of that name). Then it identifies the variant definitions for Smplvar, applies the filter conditions, and determines the actual format to use to parse the message. The pFormat tag is set in the header to indicate the format actually used for parsing the message.



Loading the sample messagesTo load the sample messages:

1. Create a queue called Smplvar and open it for editing. (Be sure to remove the check against the Open read only option in the Open Queue dialog.)

2. From the Tools menu, select the Load option, then click the button to see a list of files available for loading.

3. Load the file Smplvar.pmu. Three messages should be loaded into the queue.

Examining the messagesBased on the name of the queue, the messages are first parsed with the format Smplvar. However, there are two variant definitions for Smplvar, Smplvar1 and Smplvar2. These are used to parse the messages once again with the more specific formats of Smplvar1 and Smplvar2.

View the headers for the messages to verify that all three messages have blank MQ format fields, while the first and third messages have Smplvar1 in the pFormat fields, and the second message has Smplvar2 in the pFormat field.

Viewing the sample filter definitions

You can view the sample filter definitions used to create the variant definitions by using the Retrieve Filters dialog. (See the instructions for retrieving filter definitions in “Editing Row Filters” on page 120.)

Viewing the sample variant format definition

You can view the sample variant definitions by using the Retrieve Variants dialog to retrieve Smplvar1 and Smplvar2. (See the instructions for retrieving variant definitions in “Editing a Variant Definition” on page 135.)




OverviewTo create the variant definitions that enable PathWAI Editor to process variant definitions, you must:

1. Define the source format and all possible variant formats.2. Define the row filters that determine which of the variant formats

definitions should be used.3. Create the variant definitions.

Defining the source and variant formatsYou define the source format and all the possible variant formats using the Message Format Editor. For instructions on creating messages format definitions, see the Message Format Editor User’s Guide.

Defining the filtersYou must create a filter for each possible variant format definition. Each filter defines the condition that determines a variant format to be used to process the message when the specified field contains a particular value. For example, the structure might depend upon the value of the field Age.

See “Creating Row Filters” on page 113.

Creating the variant definitionsYou must create a variant definition triplet for each possible variant format.

To create each triplet:

1. Select Tools > Variant Definitions.The Variant Definitions dialog appears (see Figure 11 on page 134).

2. In the Select Source Format scrolling list, select the format common to the set of variant definitions for which you are defining variant format triplets.The name of the format you select appears above the Select Source Format box.



3. Click to retrieve the filters available for the selected source format, then select the filter which matches the variant format for which you are defining creating the triplet.The name of the filter you select appears above the list of filters.

4. In the Select Variant scrolling list, select the variant format for which you are creating the triplet. The name of the variant format appears above the list of variant formats.

5. Click to save the variant definition triplet.The Save Variant dialog appears.

6. Type a name for this variant definition triplet. Names may consist of a maximum of 32 characters: a-z, A-Z, 1-9, hyphen (-), and underscore (_).

7. Click to save the triplet definition.PathWAI Editor notifies you if the definition has been saved successfully.

8. If you are finished creating definitions, click to close the dialog . To create another variant, click , then repeat steps 1–7.



Figure 11. The Variant Definition Dialog


Editing a Variant Definition


OverviewOn occasion, you may need to edit variant definitions. For example, you may change the field value that determines which variant format a message uses and need to update the filter for that variant.

Editing an existing variant and saving it with a new name is a quick way to create a set of variant definitions with a common source format.

Edit a variant definitionTo edit a variant definition:

1. In the menu bar select Tools > Variant Definitions.The Variant Definition dialog appears.

2. Click .The Retrieve Variant dialog appears (Figure 12 on page 136).

3. Retrieve a specific variant definition or a list of definitions by specifying any of the following: the variant name, the name of the source format, the name of the variant format, the name of the filter, or the name of the user who created the variant definition.

4. Click to retrieve the variants that match the criteria you specify.

5. Click the variant you want to edit, then click .The variant appears in the Variant Definition dialog.

6. Edit the variant by selecting a new source format, new filter, or new variant format.PathWAI Editor modifies the variant name to show that it has been updated.

7. Click to save the edited variant.

8. In the Save Variant dialog:– Click to save the edited variant with the same name, or

– Type a new name for the edited variant, then click .

9. Click to close the Variant Definition dialog.



Figure 12. The Retrieve Variant Dialog


Deleting a Variant Definition


OverviewYou may want to delete variant definitions that are no longer being used.

Delete a variant definitionTo delete a variant definition:

1. In the menu bar select Tools > Variant Definitions.The Variant Definition dialog appears.

2. Click .The Delete Variant dialog appears.

3. Select (click) the name of the variant definition you want to deleteThe variant appears in the Variant Definition dialog.

4. Click .PathWAI Editor asks you to confirm the deletion.

5. Click to delete the variant, or click to close the dialog without deleting the variant.



Appendices 139

Appendices


Samples 141

Samples

About the samplesPathWAI Editor includes samples which demonstrate message formatting and filtering. These samples take the form of message format definitions, filter definitions, and message files to be loaded into your queues.

The message format and filter definitions were seeded in the LDAP server (or configuration file) when you installed PathWAI Editor. The sample message files are named samples1.pmu, Smplfmt2.pmu, and Smplvar.pmu. They are located in the MsgEdit/samples directory. If you want to load these files to view the sample messages, you should copy to messages directory in your individual user profile directory. For example, if your login ID is jdoe, on Windows these files would go into:

<candlehome>\msgedit\Users\jdoe\messages

On UNIX, they would go into:

<candlehome>/unix/MsgEdit/Users/jdoe/messages

Sample 1This sample demonstrates how PathWAI Editor handles messages with and without format definitions and the relationship between filters and message formats.

Loading the sample messages

To load this sample, create a new queue with any name and open that queue. Be sure to remove the check against the Open read only option in the Open Queue dialog.

A

142 PathWAI Editor for Messages User’s Guide, Version200

There will be no messages in the queue. From the Tools menu, select the Load option, then click on the button to see a list of files available for loading.

Load samples1.pmu. This loads 11 messages into the queue.

Examining the sample messages

The first message is displayed in the hexadecimal form. Click the button to the left of the message and select Edit from the popup menu. This will open the hexadecimal editor. As this editor is an applet, it takes a few seconds to open the very first time, but opens quickly subsequently. When you have finished examining the message, dismiss the editor by clicking .

The second message is a text message. Opening this message to edit will display the text editor. Cancel out of this dialog too.

The third message is a large XML message, about 40K bytes in length. Open this message for editing. The XML message will be displayed in the text editor. You can browse or edit the message in this form, or you may select the XML tree view. Selecting the XML Tree Editor radio button will bring up the message in a tree view. Use the '+' and '-' buttons to expand and contract the XML tree nodes.

The next message is another, smaller XML message.

The next seven messages are examples of formatted messages. Open any of these messages for editing.

The message contents are displayed in a tree format, similar to XML messages. However, these messages are raw messages (non-XML), and are interpreted and formatted based on message definitions in the metadata repository.

In the editing view, you can click on Edit Headers to display the message header.The header includes information from the WebSphere MQ or JMS header, as well as some metadata used by PathWAI Editor.

The format field for these messages will either show Smplfmt1 or Smplfmt2, depending upon which message you selected; the two short messages are Smplfmt1, while the remaining four are Smplfmt2.

This demonstrates message formatting using the message format field. Close the queue.

Samples 143

Using the sample filters

Click on the same queue again. In the Open Queue dialog, select the row data filter Smpl1_Age_gt_40. This filter is defined on the format Smplfmt1. Only one message will be selected for display.

Now select Apply from the Tools menu, and select the Smpl1_zip_gt_91200 row filter. This filter is defined for the format Smplfmt2. Three more messages will be displayed.

Now also select the Smplfmt2col column filter. This will not change the number of rows displayed, but will reduce the Smplfmt2 messages to 3 columns.

Close the queue.

Sample 2The messages in this sample illustrate how PathWAI Editor uses the queue name to determine message format.

Loading the messages

Create a queue called Smplfmt2 and open it for editing. (Be sure to remove the check against the Open read only option in the Open Queue dialog.)

From the Tools menu, select the Load option, then click on the Browse button to see a list of files available for loading.

Load the file Smplfmt2.pmu into the queue. Six messages are loaded. The first message is an XML message.The next five messages are the same ones as in sample 1, except that these messages do not have Smplfmt2 specified as the message format. The queue name was used to select the format for these messages.

Verifying the message format used

Verify this by opening a message for editing and clicking Edit Header. The MQ format field is blank, but the internal field called pFormat displays the name of the format used to parse the message as Smplfmt2.

Close the queue and delete it if desired.

You can examine the definition of Smplfmt2 in the Message Format Editor.

144 PathWAI Editor for Messages User’s Guide, Version200

Sample 3The third sample demonstrates how PathWAI Editor processes variant message formats.

Loading the sample messages

Create a queue called Smplvar. Open the queue and load the file Smplvar.pmu. Three messages should be loaded into the queue.

Examining the messages

Based on the name of the queue, the messages are first parsed with the format Smplvar. However, there are two variant definitions for Smplvar, Smplvar1 and Smplvar2. These are used to parse the messages once again with the more specific formats of Smplvar1 and Smplvar2.

View the headers for the messages to verify that all three messages have blank MQ format fields, while the first and third messages have Smplvar1 in the pFormat fields, and the second message has Smplvar2 in the pFormat field.

LDAP Directory 145

LDAP Directory

OverviewThis appendix contains information on managing Candle’s LDAP directory and its directory services. It includes a brief introduction to LDAP directories and directory services, as well as step-by-step instructions for starting and stopping the directory server; backing up, deleting, unconfiguring, and reconfiguring a directory; and importing records from a backup file into a directory.

Note: Candle’s LDAP directory is part of a specially packaged toolkit named Candle Application Services Pac (CASP), which consists of selective features from Candle’s existing CandleNet eBusiness Platform (eBP) family of products. For this reason, you may see both the terms CASP and CandleNet eBP as you install and use the product.

For information on importing metadata definitions into the metadata repository and exporting metadata definitions from the metadata repository, please refer to the Message Format Editor User’s Guide.

Appendix contentsAbout LDAP Directories and Directory Services . . . . . . . . . . . . . . . . . . . 146Starting and Stopping the Directory Server. . . . . . . . . . . . . . . . . . . . . . . 150Importing Records to an Existing Directory (Seeding) . . . . . . . . . . . . . . . 153Backing Up a Local Directory Database . . . . . . . . . . . . . . . . . . . . . . . . . 158Unconfiguring the Local Directory Service . . . . . . . . . . . . . . . . . . . . . . . 161Removing the Local Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Reconfiguring the Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

B

About LDAP Directories and Directory Services



OverviewThe following sections provide a brief introduction to LDAP directories and directory services. For a more complete introduction, Candle recommends IBM’s Redbook, Understanding LDAP, SG24-4986-00, which can be obtained at http://www.redbooks.ibm.com/.

What is a directory?A directory is a special type of database, or data repository, containing information about objects accessible from a network. Directories are used primarily for read operations rather than write operations.

What is a directory server?Directory-enabled applications, like PathWAI Editor, can look up entries in the directory and perform certain operations. However, the applications do not read or write to the directory directly. Instead, they call a function or API which sends a request over the network to another program. That program, the directory server, maintains directory entry information in local tables and files and provides access to the directory from the network.

What is LDAP?The Lightweight Directory Access Protocol, or LDAP, is an open industry standard protocol for accessing and maintaining information in a directory conforming to the ISO 9594, Data Communications Network Directory, Recommendations X.500-X.521.

LDAP directory recordsAn LDAP directory contains entries, or records, consisting of one or more attributes. Each attribute has a type and one or more values.

Every directory entry has a special attribute, named objectClass. The value of this attribute determines what attributes the entry must or may have. This

http://www.redbooks.ibm.com/

LDAP Directory 147


attribute also defines what attribute is used as the naming attribute for the class. The value of this attribute serves as the object’s name.

Most object types, like namespaces or message formats, use the common name (cn) attribute as the naming attribute. Domain components, which define locations in the directory information hierarchy from which other domain components or objects can branch, use the domain component (dc) attribute as their naming attribute.

Entries in an LDAP directory are organized in a hierarchical structure known as the Directory Information Tree (DIT). Each entry in the tree is uniquely identified by its distinguished name (DN). DNs are constructed by concatenating the name of the entry itself with the name of its ancestor nodes in the DIT. Unlike files names, which begin with the root and end with the leaf, DNs begin with the leaf name and end with the root node.

For example, the DN for the sample message format Smplfmt2 in the default :CandleSamples.MessageEditor namespace used by PathWAI Message Editor would be:

cn=Smplfmt2,dc=MessageFormat,dc=Metadata,cn=MessageEditor,cn=CandleSamples,dc=Namespace,dc=Roma,dc=candle,dc=com

This message format definition as represented in the Message Format Editor’s Directory Administrator is shown in Figure 13 on page 148.



Figure 13. Smplfmt2 Definition in the Directory Administrator

Directory URLsTo use a directory service, an application needs to know which host to contact and what part of the directory to look in. Uniform Resource Locators (URLs) are used to provide this information. URLs are a standard way of referencing resources on the Internet or in an intranet. A URL consists of the protocol used to access the resource, the name of the host on which the resource resides, and the name of the resource:

LDAP Directory 149


protocol://host:port/resource_name

The most familiar type of URL is a Web page address, such as:

http://www.candle.com/custsupp/index.html

In this example, http is the hypertext transfer protocol used by Web browsers, www.candle.com is the host to contact, and custsupp/index.html is the name of a file on that host. In LDAP URLs, ldap is used as the protocol. In the simplest case, an LDAP URL has the following syntax:

ldap://host:port/resource_name

where:

For example:

ldap://localhost:389/cn=RomaContext,dc=Context,dc=Roma,dc=candle,dc=com

LDAP Data Interchange Format (LDIF)The LDAP Data Interchange Format is a data exchange mechanism, typically used to import and export directory information between LDAP-based directory servers, or to describe a set of changes to be made to directory entries.

The configuration files used by PathWAI Editor as an alternative repository are in LDIF. By convention such files have a .ldf file extension, but can have any extension.

ldap is the protocol used to access

host is the name or IP address of the LDAP server host

port is the port number of the LDAP server. The default port number for an LDAP server is 389.

resource_name is the distinguished name of the node used as the base of the search

protocol://host:port/resource_name

http://www.candle.com/custsupp/index.html

ldap://host:port/resource_name

ldap://localhost:389/cn=RomaContext,dc=Context,dc=Roma

Starting and Stopping the Directory Server



OverviewThis section provides instructions for starting and stopping CASP Directory Services on Windows and Unix.

WindowsOn Windows, the directory server is run as a Windows service. You can start and stop the server using the Manage Candle Services utility.


1. From the Start menu, select:Programs > PathWAI Editor for Messages > Manage Candle Services.

The Manage Candle Services window appears (see Figure 14 on page 151).


– Right-click CandleNet eBP Directory and select Start from the popup menu, or

– Select (click) CandleNet eBP Directory, then click .

To stop the server:

1. From the Start menu, select:Programs > PathWAI Editor for Messages > Manage Candle Services.


– Right-click CandleNet eBP Directory and select Stop from the popup menu, or

– Select (click) CandleNet eBP Directory, then click .

LDAP Directory 151


Figure 14. Manage Candle Services (Windows)

UNIX (GUI)In GUI mode you can start and stop the LDAP server using the Manage Candle Services utility.






– Right-click CASP Directory Services and select Start from the popup menu, or

– Select (click) CASP Directory Services, then click .

To stop the server:







– Right-click CASP Directory Services and select Stop from the popup menu, or

– Select (click) CASP Directory Services, then click .

UNIX (command line)To start the directory server:


2. Enter the following command:CandleAgent start xs

When the agent is started successfully, you will see the message, “Agent started . . .”

To stop the directory server:

1. Change to the <candlehome>/bin directory:CD <candlehome>/bin

2. Enter the following command:CandleAgent stop xs

When the agent is stopped successfully, you will see the message, “Agent stopped . . .”

LDAP Directory 153

Importing Records to an Existing Directory (Seeding)


OverviewThis section contains instructions for importing directory records from an LDIF file to an existing Directory database. (When records are being imported to initialize the directory, this operation referred to as “seeding”. )

Note: The import process will not overwrite existing records. If you have backed up the database files and are attempting to load them into a directory, you may get errors telling you that certain records already exist. The import process proceeds, ignoring those files.

WindowsFollow these steps:

1. From the Start menu, select: Programs > PathWAI Editor for Messages > PathWAI Configuration Tool

2. Click the Seed Business Directory tab.The Seed Business Directory dialog is displayed (see Figure 15 on page 154).

3. Under Business Directory Location, identify the Directory you want to update by specifying the following:

4. In Business Directory User ID and Business Directory Password fields, specify the login ID and password for the Directory you want to update.

5. In the Business Partition field, enter the partition name or your site’s domain name. If you use your site’s domain name, check Partition is a Domain Name.

6. Under Select LDIF Files for Seeding, identify the file(s) you want to import. If necessary, use the Browse button to locate the files.

Host Name The host name of the machine where the Directory resides. This may be the local machine or any other machine in your site’s network.

Port Number The TCP/IP listening port of the Directory.



7. Click Apply.You may optionally view and print or save to disk the results of the import operation.

Note: If you import records from a directory on another machine, edit the queue manager name to reflect the proper local queue manager on the new machine.

Figure 15. Seed Business Directory Tab of the Configuration Tool (Windows)

LDAP Directory 155


UNIXOn UNIX, you use the ldapadd command to import records from an LDIF file. The ldapadd command allows you to add one or more entries to the LDAP directory.

Follow these steps:

1. Change to the <candlehome>/arch/common/bin directory, where arch is the type and version number of the operating system on which the directory has been installed. For example:

cd candle/aix433/common/bin

aix433, sol273, hp11.

Note: Note: on Solaris 2.9 and later, you may have LDAP commands in /usr/bin. You may experience problems when you use those commands to access the LDAP directory instead of using the commands provided by Candle.

2. Enter the following command:ldapadd [-?][-b] [-c] -d debuglevel]-D userid -f file [-h ldaphost] [-n] [-p ldapport] [-v]-w password

where

-? Prints the command syntax to the screen.

-b Specifies that any values in the input file that start with a '/' are binary values. The external representation of binary data is unique to LDIF, and is not covered in this document.

-c Specifies continuous operation mode. Errors are reported, but processing continues. The default is to exit after reporting an error.

-D userid The user ID for this directory. The ID should be specified in the form cn=userid (for example, -D cn=manager). This parameter is required.

-f file Indicates that entries should be read from file, where file represents a platform-specific input file.

-h ldaphost Specifies an alternate host if the LDAP server is running on a different machine.

-n Shows the results of the command without actually adding entries. This is useful for debugging in conjunction with -v.



3. Enter the following command:ldapadd [-?] [-b] [-c] -D binddn [-f file] [-h ldaphost] [-n] [-p ldapport] [-v]-w password

-p ldapport Specifies an alternate TCP port for the LDAP server.

-v Runs in verbose mode, with diagnostics written to standard output. This is recommended for confirming the success or failure of a command.

-w password Indicates the password associated with the user ID. This parameter is required.

Where Indicates

-? Print the command syntax to the screen.

-b Specify that any values in the input file that start with a '/' are binary values.The external representation of binary data is unique to LDIF, and is not covered in this document.

-c Continuous operation mode. Errors are reported, but processing continues. The default is to exit after reporting an error.

-D binddn Use binddn to authenticate to the directory server, where binddn is the root DN defined in the directory configuration file. (Check with the LDAP administrator if you do not know the DN used at your site.) This parameter is required.

-f file Read a series of entry modifications from file rather than from standard input, where file represents a platform-specific input file.

-h ldaphost Specify an alternate host if the LDAP server is running on a different machine.

-n Show the results of the command without actually modifying or adding entries. This is useful for debugging in conjunction with -v.

-p ldapport Specify an alternate TCP port for the LDAP server.

LDAP Directory 157


-v Run in verbose mode, with diagnostics written to standard output. This is recommended for confirming the success or failure of a command.

-w password Use password for simple authentication. (Check with your LDAP administrator if you do not know the password used at your site.) This parameter is required.

Backing Up a Local Directory Database



OverviewThis section contains instructions for backing up the Directory database files on the local machine. Candle recommends that you always back up the Directory database before performing any kind of maintenance on it.

The backup operation writes the database records to an LDIF file, which can be used to seed a Directory database, as documented in “Importing Records to an Existing Directory (Seeding)” on page 153.

WindowsOn Windows, you use the Directory Utilities to backup the directory.

Note: You can also use the ldapsearch command discussed in the UNIX section below. The ldapsearch command is located in the <candlehome>\common\bin directory.

Follow these steps:


2. Click on the Business Directory Utilities tab.The Business Directory Utilities dialog (shown on the following page) is displayed.

3. Select Backup Local Database.

4. Enter the pathname of the backup file or click ... to browse for the file.

5. Click Apply and wait for this message:The backup command has successfully completed.

LDAP Directory 159


Figure 16. Business Directory Utilities Tab of the Configuration Tool (Windows)

UnixTo backup a directory on UNIX, you use the ldapsearch command, specifying all records with the objectclass attribute and directing the output to a file.



Follow these steps:

1. Change to the candlehome/arch/common/bin directory, where arch is the type and version number of the operating system on which the directory has been installed. For example:

cd candle/aix433/common/bin

2. Enter the following command:ldapsearch [-?] -h ldaphost -p port -D userid -w password -L -b searchbase “(objectclass=*)” >outputfile

where

-? Prints the command syntax to the screen

-h ldaphost Specifies the host of the LDAP server

-p port Indicates the TCP/IP listening port assigned to the LDAP server.

-b searchbase Indicates the starting point of the search, typically "" or "dc=com"

-D userid Is the user ID for this directory. The ID should be specified in the form cn=userid (for example, -D cn=manager).

-w password The password for this user ID.

-L Displays search results in LDIF format.

>outputfile Exports the contents of the LDAP directory into an LDIF file, where outputfile is the platform-specific output file.

LDAP Directory 161

Unconfiguring the Local Directory Service

Unconfiguring the Local Directory Service

OverviewThis section contains instructions for removing the Directory service from the local machine without deleting the Directory database files. Unconfiguring the Directory service allows you, for example, to change the user ID and password, leaving the database files intact.

Note that you can remove the entire Directory (removing the service and deleting the database files); see “Removing the Local Directory” on page 162 for instructions.

WindowsTo unconfigure the Directory service, follow these steps:


2. Click on the Business Directory Utilities tab.The Business Directory Utilities dialog is displayed.

3. Select Unconfigure Local eBP Directory Service.

4. Click Apply and wait for this message:eBP Directory Directory service unconfigured!

Removing the Local Directory



OverviewThis section contains instructions for removing a Directory from the local machine. Removing the directory stops and unconfigures the Directory service and deletes the Directory database files.

Candle recommends that you back up the database before removing the directory; refer to “Backing Up a Local Directory Database” on page 158 for instructions. Note that you can unconfigure the Directory service without deleting the database files; see “Unconfiguring the Local Directory Service” on page 161 for instructions.

WindowsFollow these steps:

1. From the Start menu, select Programs > PathWAI Editor for Messages > PathWAI Configuration Tool.

2. Click on the Business Directory Utilities tab.The Business Directory Utilities dialog (Figure 16 on page 159) is displayed.

3. Select Delete Local Database.

4. Click Apply and wait for this message:Directory service unconfigured!

5. Click OK.

6. Click Yes and wait for this message:The Directory database has been deleted.

Unix On Unix, you delete the directory by manually deleting the database files. Follow these steps:

1. Change to the <candlehome>/arch/common/ldap/dbb directory. For example:

cd candle/aix433/common/ldap/dbb

LDAP Directory 163


2. Remove the database files by entering the following command:rm NEXTID *.dbb

Reconfiguring the Directory Server



OverviewThe Directory server is configured at installation. However, you may need at some point to unconfigure and then reconfigure it. This section provides instructions for reconfiguring the directory server.

WindowsTo reconfigure a directory:

1. From the Start menu, select Start > Programs > PathWAI Editor for Messages > PathWAI Configuration Tool.The Configuration dialog appears.

2. Click the Configure Business Directory tab (see Figure 17 on page 165).

3. Under Business Directory Configuration, specify the following:

1. Under Business Directory Configuration, verify or specify the following:

2. In the Business Partition field, enter the name of the partition or your site’s domain name. If you use your site’s domain name, check Partition is a Domain Name.

3. Click Apply to continue and wait for this message:Global variables have been set.

4. Click OK.

Port Number The TCP/IP listening port that you want to assign to the directory server.

User ID The user ID of the directory administrator.Password The password for the above ID.

LDAP Directory 165


Figure 17. Configure Business Directory Tab of the Configuration Tool (Windows)



Return Codes and Error Messages 167

Return Codes and ErrorMessages

OverviewThis appendix contains the return code and error messages for the PathWAI Editor server and client and, as a convenience, the WebSphere MQ reason codes. It also contains a brief discussion of error messages from the metadata repository.

Appendix contentMetadata Repository Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Client Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176WebSphere MQ Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

C

Metadata Repository Messages

168 PathWAI Editor for Messaging User’s Guide, Version 200

Metadata Repository Messages

OverviewMessages from the metadata repository start with either KXM or KRR. In general, these messages indicate a problem involving the message format and typically indicate the field in error. For example, PathWAI Editor may encounter a problem parsing a message which does not conform to the message format definition, or the definition of a shared field referenced by the format may have been deleted from the metadata repositiory. While creating a message or a message filter, you may include the wrong type of data in a message field—putting a string in a field that requires a binary comparison—or fail to provide all the fields required by the format.

These messages are too numerous to document and are generated dynamically to reflect the exact problem. Study the text of the message, then examine the message format definition and the action being performed (for example, parsing a message versus creating a creating a message) to determine what the problem is. If you receive a message while creating a message, review the data you provided. If you receive a message while parsing a message, compare the message format definition to the message data.

.


Client Messages

Client Messages

These messages are self-explanatory.

Errors involving the resource tree (queue managers, client connections, JMS connections)

001 "Enter the name for the queue manager."

002 "Enter the name of the host."

003 "Enter the name of the channel."

004 "Enter the port number."

005 "Port should be a number."

006 "Necessary jar files should be included in classpath variable of the server starting script."The server script is kxyruns.bat or kxyruns.sh.

007 "Please enter a name."

008 "Please enter a value."

009 "Enter the name for the connection."

010 "Enter the value for provider URL."

011 "Enter the name of the factory."

012 "Enter the name of initial context factory."

013 "Host/Channel name can have only letters, digits, '.', '/', '%' and '_'."

014 "Select a property from table below to update."

015 "Select a property from table below to delete."

016 "Cannot have space in property name."

017 "Cannot have space in property value."

018 "A host name can have only letters, digits, '.', '/', '%', '-', and '_'."

Errors involving the queue list

101 "Enter the name for the queue."

102 "The name of the queue should be limited to 48 characters."

103 "Enter the name for the queue with no space in between."

104 "The queue description should be limited to 64 characters."

Client Messages


105 "Enter a whole number between 0 and 640000 for 'Max. Queue Depth' field."

106 "Enter a whole number between 0 and 100000000 for 'Max. Message Length field."

107 "Enter a whole number between 0 and 999999999 for 'Retention Interval' field."

108 "Enter a whole number between 0 and 999999999 for 'Backout Threshold' field."

109 "Enter a whole number between 0 and 999999999 for 'Trigger Depth' field."

110 "The trigger data should be limited to 64 characters for 'Trigger Data' field."

111 "Enter a whole number between 0 and 100 for 'Upper Queue Depth Threshold' field."

112 "Enter a whole number between 0 and 100 for 'Lower Queue Depth Threshold' field."

113 "Enter a whole number between 0 and 999999999 for 'Queue Service Interval' field."

114 "Remote queue manager name should be limited to 48 characters."

115 "Count field cannot be left empty."

116 "Enter a positive value for count."

117 "Enter a whole number for count."

118 "Enter a number for 'Max. No. of messages' field."

119 "Enter a number other than '0' for count."

120 "Count cannot be more than 500."

121 "Please enter Base Queue Name in Other Properties dialog."

122 "A queue name cannot start with ‘-’, ‘_’, or any special character."

123 "A queue name can have only letters, digits, and "_".

124 "A queue name cannot contain spaces."

Errors involving the Message window

201 "Enter a whole number greater than 0 for message number."


Client Messages

202 "Enter a whole number greater than 0 and not more than 200 for depth."

203 "Message number cannot be greater than total numer of messages which is"

204 "Wrong XML in textarea."

205 "Please enter something in textarea."

206 "Enter a whole number for characterSet field in header."

207 "Header meta data not available."

208 "The queue has been opened as 'Read only'."

209 "Your browser does not support XML."

210 "Comments should be inside root tag in XML."

211 "Please enter a queue name."

212 "Please enter a queue manager's name."

213 "Please enter or select a name for the file."

214 "Error, refresh before editing."

215 "Error, refresh before deleting."

216 "Error, refresh before cutting."

217 "Error, refresh before copying."

218 "Error, refresh before doing another pasting."

219 "Enter a number other than '0' for count."

220 "Error, refresh before forwarding."

221 "Error, refresh before using find."

222 "Error, refresh before using replace."

223 "Enter name in text box."

224 "A node name cannot start with a number or '-' or '_' or any special characters."

225 "A node name can have only letters, digits, '-' and '_'."

226 "A node name cannot have ' ' character."

227 "Select Do not use Message Formatting or select an available format."

Client Messages


228 "A file name can have only letters, digits, '-' and '_'."

229 "Enter a name for the node."

230 "Enter a value for text node."

231 "Text node already exists. Change the data value in text box."

232 "Enter a name for the attribute."

233 "Cannot remove root node."

234 "Enter name for the attribute to be removed."

235 "Enter a name for the sibling."

236 "Cannot add sibling to root node."

237 "Message too big to expand all. Individual fields can be expanded as necessary."

238 "Error retrieving formats for creating message."

239 "Message has been created."

240 "Message create request could not be sent."

241 "Messages have been deleted successfully."

242 "Select messages to delete first"

243 "Select only one message to edit."

244 "Select a message to edit."

245 "Error forming Hexa XML."

246 "Message has been updated successfully."

247 "Error passing the updated message."

248 "Messages have been copied to the clipboard successfully."

249 "Select messages to copy first."

250 "Messages have been cut to the clipboard successfully."

251 "Select messages to cut first."

252 "Messages have been pasted at the bottom of the queue."

253 "Select message(s) to delete."

254 "Select message(s) to forward."

255 "File loaded successfully."


Client Messages

256 "Messages unloaded successfully and deleted from this queue."

257 "Messages unloaded successfully."

258 "Transactions have been committed."

259 "Unable to commit, open the queue in transactional mode."

260 "Rollback finished successfully."

261 "Unable to rollback, open the queue in transactional mode."

262 "Please select a column first."

263 "Unable to replace."

264 "There are no messages to unload."

265 "Error retrieving attributes."

266 "A property name cannot start with a number or ‘-’ or ‘_’ or any special characters."

267 "A property name can have only letters, digits, ‘-’ and ‘_’."

268 "A property name cannot have ‘ ’ character."

269 "Please select a message type."

270 "Please select a message format."

271 "Close the Find window first."

272 "Close the Replace window first."

Miscellaneous errors

301 "Error displaying format structure."

302 "Select 'Clear' from menu to select another format."

303 "Select a format."

304 "Select fields from structure."

305 "Enter a name for the filter."

306 "There are no filters matching the selection criteria."

307 "Enter or select a filter name."

308 "Get the available filters first."

309 "There is no filter with that name."

Client Messages


310 "A filter name can have only letters, digits, '-' and '_' with no space."

311 "Filter has been deleted."

312 "There are no available filters for the selected source format"

313 "Please retrieve a variant first."

314 "Please select a source format."

315 "Please select a filter."

316 "Please select a variant format."

317 "Error retrieving variant."

318 "There are no available variants matching the selection criteria."

319 "Please select a variant."

320 "Please restart the debugger."

321 "Please select a valid field and value."

322 "Please select a field first."

323 "Please select a row in the text area first."

324 "Write or open a filter first."

325 "Error retrieving the filter."

326 "Open a queue manager first."

327 "Your browser does not support XML."

328 "Can't create XML document."

329 "A variant name can have only letters, digits, '-' and '_' with no space."

330 "Please enter a name for variant."

331 "Unable to connect. Please provide a userid and password."

332 "Please provide queue manager name and type."

333 "Enter a valid userid."

334 "New queue created successfully."

335 "The queue has been deleted successfully."

336 "The filter was saved successfully."


Client Messages

337 "Filter has been deleted."

338 "The filter has been updated successfully."

339 "The variant was added successfully."

340 "The variant was updated successfully."

341 "The variant has been deleted successfully."

342 "TIMEOUT: window will close."

343 "Filter name cannot start with a number or '-'."

344 "Variant name cannot start with number or '-'."

345 "Error retrieving formats for creating message."

346 "The queue has been cleared successfully."

347 "Format of retrieved filter not found in list of available formats."

348 "Source format of retrieved variant not found in list of available formats."

349 "Variant format of retrieved variant not found in list of available formats."

350 "Filter of retrieved variant not found in list of available filters."

Server Messages


Server Messages

The following are the server-related exception messages from PathWAI Editor. Some messages require user action. Other exceptions are code related and are used by Candle development and support for problem resolution.

KXY_ERR_BUFFER_FULL. The buffer is full. Please refresh.

Recommended action: Refresh the window.

KXY_ERR_CFG_PLATFORM Missing platform specification in the configuration file.

Recommended action: Add the <Platform> tag to the server configuration file.

KXY_ERR_CFG_QMGRS Missing queue manager directory specification in the configuration file.

Recommended action: Add the <QMGRS> tag in the server configuration file.

KXY_ERR_CHANNEL No channel specified for client connection.

KXY_ERR_CMD Invalid command: {0}.

KXY_ERR_COLUMN Column not found: {0}.

KXY_ERR_CONN_ID Invalid connection id: {0}.

KXY_ERR_DEL The message was already deleted.

Recommended action: None.

KXY_ERR_DLQ_FMT Invalid format for retry: {0}.

KXY_ERR_EMPTY_CLIPBOARD There are no messages to be pasted.

Recommended action: Copy or cut the messages and then paste them.

KXY_ERR_FACTORY No connection factory specified.

KXY_ERR_FILE_NAME The values for <old_file> and <new_file> must be different.

Recommended action: Use different names when you upgrade files from PQEdit to PathWAI Editor for Messages.

KXY_ERR_FILTER Invalid filter: {0}.


Server Messages

KXY_ERR_FLT_EXPR Invalid filter expression: {0}.

KXY_ERR_HEX_CHAR Invalid hexa character: {0}.

KXY_ERR_HEX_TYPE Unsupported type for hexa conversion: {0}.

KXY_ERR_IDLE Idle timeout, the connection was closed.

KXY_ERR_JMS_PROPERTY Invalid JMS property name: {0}.

KXY_ERR_LDAP The LDAP server is not running.

Recommended action: Start the LDAP server.

KXY_ERR_LOGIN Cannot login: {0}.

Recommended action: Provide a valid user id and password.

KXY_ERR_MAX_QNAME The number of queues {0} exceeds the maximum allowance {1}. Use a filter.

KXY_ERR_MEM Cannot alloc memory.

KXY_ERR_MKDIR Cannot make directory: {0}.

Recommended action: Set access privileges for the user ID to create the directory for its profile.

KXY_ERR_MONTH Invalid month: {0}.

Recommended action: Specify a valid month name.

KXY_ERR_MSG Invalid message.

KXY_ERR_MSG_TYPE Not supported message type: {0}.

KXY_ERR_NULL Invalid null argument.

KXY_ERR_OBJ_EXISTS Object {0} already exists. Recommended action: Change the name for the filter or variant you are saving.

KXY_ERR_OBJ_NONE Object {0} does not exists.

KXY_ERR_OPERATION Invalid operation.

KXY_ERR_OPTION Invalid option: {0}.

KXY_ERR_OWNER Insufficient privileges.

KXY_ERR_PCF_EXEC PCF execution error.

KXY_ERR_PCF_RES PCF result not supported.

Server Messages


KXY_ERR_PROFILE_CLI The profile does not contain the client connection {0}.

KXY_ERR_PROVIDER No initial context factory specified.

KXY_ERR_Q_CREATE The queue was already created.

KXY_ERR_Q_NAME No queue name is specified.

Recommended action: Specify another name for the queue.

KXY_ERR_Q_OPEN The queue was already opened.

KXY_ERR_Q_TYPE Invalid queue type: {0}.

KXY_ERR_QM_CONNECT Reconnect to port {0} to run the queue manager {1}.

KXY_ERR_QM_TRY The queue manager {1} cannot run on this port. Try on port {0}.

KXY_ERR_RSP Invalid response: {0}.

KXY_ERR_SECURITY Invalid session.

KXY_ERR_SESSION_CLOSED Session {0} was closed.

Recommended action: Log in again.

KXY_ERR_STR_LEN Invalid string length: {0}.

KXY_ERR_TYPE Not supported type: {0}.

KXY_ERR_UID Invalid user ID.

KXY_ERR_URL No URL specified.

KXY_ERR_VAL Invalid value {0} for option {1}.


WebSphere MQ Messages


These WebSphere MQ return codes are documented here for convenience. Please consult the WebSphere MQ documentation for the appropriate actions to take in response to these messages..

2001 The alias queue is not a local queue, a local definition of a remote queue, or a cluster queue.

2002 The application is already connected to the queue manager.

2003 The current unit of work encountered a fatal error or was backed out.

2004 The Buffer parameter is not valid.

2005 The BufferLength parameter is not valid.

2006 The CharAttrLength is not valid.

2007 The CharAttrs is not valid.

2008 The CharAttrLength is too short.

2009 Connection to the queue manager has been lost.

2010 The DataLength parameter is not valid.

2011 The DynamicQName field is not valid.

2012 The call is not valid for the current environment.

2013 The value for the Expiry field is not valid.

2014 The value for the Feedback field is not valid.

2016 The get calls for the queue are currently inhibited.

2017 The maximum number of open handles allowed has already been reached.

2018 The connection handle is not valid.

2019 The object handle is not valid.

2020 The value specified for the attribute is not valid.

2021 The IntAttount parameter is not valid.

2022 The IntAttount parameter is too small.

2023 The IntAttrs parameter is not valid.



2024 The number of uncommitted messages in the current unit of work exceeded the limit defined for the queue manager.

2025 The maximum number of concurrent connections has been exceeded.

2026 The MQMD structure is not valid.

2027 The ReplyToQ field is missing.

2029 The MsgType field is not valid.

2030 The message is too long and MQMF_SEGMENTATION_ALLOWED was not specified.

2031 The message is too long and MQMF_SEGMENTATION_ALLOWED was not specified.

2033 No messages are available. The command server might not have been started, or request timed out, perhaps too many queues.

2034 The browse cursor is not positioned at a retrievable message.

2035 The user is not authorized to perform the operation.

2036 The queue had not been opened for browse.

2037 The queue had not been opened for getting messages.

2038 The object had not been opened for inquire.

2039 The queue had not been opened for putting messages.

2040 The queue had not been opened for setting attributes.

2041 Object definitions have been changed.

2042 The object has already been opened by another application for exclusive input.

2043 The ObjectType field is not valid.

2044 The object descriptor MQOD is not valid.

2045 Invalid option for the queue being opened or closed.

2046 The Options parameter is not valid.

2047 The Persistence field is not valid.

2048 The queue does not support persistent messages.

2049 The value of the Priority field exceeds the maximum priority.

2050 The Priority field is not valid.



2051 The put calls are currently inhibited for the queue.

2052 The queue handle for a dynamic queue that has been deleted.

2053 The queue is full.

2055 The permanent dynamic queue is not empty and cannot be closed.

2056 There is no space available for the queue on the storage device.

2057 The queue type is invalid.

2058 The QMgrName parameter is not valid.

2059 The queue manager is not available for connection.

2061 The Report field is invalid.

2062 A message has already been marked within the current unit of work.

2063 A security error occurred.

2065 The Selectoount parameter is not valid.

2066 The Selectoount parameter is larger than the maximum supported.

2067 The Selectors array contains a selector that is not valid.

2068 One or more selectors in the Selectors array is not valid.

2069 There is already a signal outstanding for the queue.

2070 No suitable message was available.

2071 Insufficient main storage available.

2072 SYNCPOINT is not available.

2075 The value for the MQIA_TRIGGER_CONTROL attribute selector is not valid.

2076 The value for the MQIA_TRIGGER_DEPTH attribute selector is not valid.

2077 The value for the MQIA_TRIGGER_MSG_PRIORITY attribute selector is not valid.

2078 The value for the MQIA_TRIGGER_TYPE attribute selector is not valid.

2079 The message was truncated as the length was too large to fit into the supplied buffer.

2080 The message length was too large to fit into the supplied buffer.



2082 The BaseQName in the alias queue attributes is not recognized as a queue name.

2085 The object cannot be found.

2086 The ObjectQMgrName field does not satisfy the naming rules for objects.

2087 Unknown remote queue manager.

2090 The value specified for the WaitInterval is not valid.

2091 Transmission queue type is invalid.

2092 Transmission queue usage is invalid.

2093 The queue had not been opened with the MQOO_PASS_ALL_CONTEXT option.

2094 The queue had not been opened with the MQOO_PASS_IDENTITY_CONTEXT option.

2095 The queue had not been opened with the MQOO_SET_ALL_CONTEXT option.

2096 The queue had not been opened with the MQOO_SET_IDENTITY_CONTEXT option.

2097 Invalid context handle or the queue was not opened with MQOO_SAVE_ALL_CONTEXT.

2098 The queue has no context associated with it.

2099 The Signal1 field is not valid.

2100 The dynamic queue already exists.

2101 The object is damaged and cannot be used.

2102 There are insufficient system resources.

2103 The thread or process is already connected to a queue manager.

2104 The Report field is invalid.

2105 The storage-class object defined for the queue does not exist.

2106 MQRO_COD_* option specified for XCF queue.

2107 MQXWAIT has been canceled because a STOP CHINIT command has been issued.

2108 Invalid MQXWAIT call.



2109 The API crossing exit suppressed the call.

2110 The message cannot be converted.

2111 The coded character-set identifier is not valid or not supported.

2112 The Encoding value in the retrieved message specifies an invalid integer.

2113 The Encoding value in the retrieved message specifies an invalid decimal.

2114 The Encoding value in the retrieved message specifies an invalid float.

2115 The coded character-set identifier is not valid or not supported.

2116 The Encoding value in the MsgDesc specifies an invalid integer.

2117 The Encoding value in the MsgDesc specifies an invalid decimal.

2118 The Encoding value in the MsgDesc specifies an invalid float.

2119 The data can not be converted.

2120 The message data expanded during data conversion exceeded the size of the buffer provided by the application.

2121 No participating resource managers have been registered with the queue manager.

2122 One or more of the participating resource managers is not available.

2123 One or more of the participating resource managers can not handle the unit of work.

2124 One or more of the participating resource managers has not confirmed that the unit of work.

2127 The adapter was unable to acquire storage.

2129 The connection handling module could not be loaded.

2130 The batch adapter could not load the API service module CSQBSRV.

2131 The subsystem definition module does not contain the required control block identifier.

2132 The subsystem definition module could not be loaded.

2133 The adapter could not load the data conversion services modules.

2136 The result was not the same for all of the destinations in the list.

2137 The queue could not be opened successfully.



2138 The disconnect handling module could not be loaded.

2139 The connect-options structure MQCNO is not valid.

2140 The request was rejected by CICS.

2141 The dead letter header structure MQDLH in the message data is not valid.

2142 The header structure is not valid.

2143 The SourceLength parameter is invalid.

2144 The TargetLength parameter is not valid.

2145 The SourceBuffer parameter is not valid.

2146 The TargetBuffer parameter is not valid.

2150 The SourceBuffer parameter does not contain a valid DBCS string.

2152 The ObjectName field is neither blank nor the null string.

2153 The ObjectQMgrName field is neither blank nor the null string.

2154 The RecsPresent parameter is invalid.

2155 The MQOR object records are not specified correctly.

2156 The MQRR response records are not specified correctly.

2157 The caller’s primary ASID was found to be different from the home ASID.

2158 The PutMsgRecFields field in the MQPMO structure is not valid.

2159 The MQPMR put message records are not specified correctly.

2160 The queue manager conflicts with the connection identifier of another connected CICS or IMS system.

2161 The queue manager is quiescing (preparing to shut down).

2162 The queue manager is shutting down.

2163 A recovery coordinator already exists for the connection.

2173 The MQPMO structure is not valid.

2183 The API-crossing exit module could not be linked.

2184 The RemoteQName parameter is invalid.

2185 The Persistence field in MQMD that is different from the previous message.



2186 The MQGMO structure is not valid.

2188 The cluster workload exit rejected the call.

2189 The queue definition could not be resolved correctly.

2190 The message expanded during data conversion and exceeded the size of the field.

2191 The character trigger message structure is not valid.

2192 The external storage medium is full.

2193 The queue is on a page set that does not exist.

2194 The ObjectName field in the ObjDesc parameter is not blank.

2195 An unexpected error occurred.

2196 The XmitQName attribute is not the name of a locally-defined queue.

2197 The DefXmitQName attribute is not the name of a locally-defined queue.

2198 The DefXmitQName attribute is not a local queue.

2199 The DefXmitQName attribute does not have a Usage attribute of MQUS_TRANSMISSION.

2201 The dynamic queue already exists.

2202 The connection to the queue manager is in quiescing state.

2203 The connection to the queue manager is shutting down.

2204 The CICS adapter has been disabled, or has not been enabled.

2206 Selection by message identifier is not supported on this queue.

2207 Selection by correlation identifier is not supported on this queue.

2208 An unexpected return code was received from the file system.

2209 No message is currently locked.

2217 An application running under that subsystem subsequently issues an MQI call.

2218 The message is larger than the maximum message length allowed by the channel.

2219 Another MQI call was already being processed for that connection.

2220 The reference message header structure MQRMH in the message data is not valid.



2222 The queue manager becomes active.

2223 The queue manager is requested to stop or quiesce.

2224 The queue depth exceeded the limit specified in the QDepthHighLimit attribute.

2225 The queue depth is below the limit specified in the QDepthLowLimit attribute.

2226 No successful gets or puts have been detected within an interval that is greater than the limit specified in the QServiceInterval attribute.

2227 A successful get has been detected within an interval that is less than or equal to the limit specified in the QServiceInterval attribute.

2232 No TM/MP transaction had been started.

2233 The automatic definition of a channel is successful.

2234 The automatic definition of a channel fails.

2235 The PCF header structure MQCFH in the message data is not valid.

2236 A PCF integer list parameter structure MQCFIL in the message data is not valid.

2237 A PCF integer parameter structure MQCFIN in the message data is not valid.

2238 A PCF string list parameter structure MQCFSL in the message data is not valid.

2239 A PCF string parameter structure MQCFST in the message data is not valid.

2241 Incomplete message group.

2242 Incomplete logical message.

2243 The message to be retrieved consists of two or more segments that have differing values for the CodedCharSetId field in MQMD.

2244 The message to be retrieved consists of two or more segments that have differing values for the Encoding field in MQMD.

2245 The MQPMO_SYNCPOINT option is not consistent with the current group and segment information retained by the queue manager for the queue handle.

2246 The message that is under the cursor has an MQMD with an Offset field that is greater than zero.



2247 The MatchOptions field in the GetMsgOpts parameter is not valid.

2248 The MQMDE structure at the start of the application message data is not valid.

2249 The MsgFlags field in the message descriptor MQMD contains one or more message flags that are not recognized by the local queue manager.

2250 The MsgSeqNumber field in the MQMD or MQMDE structure is less than one or greater than 999 999 999.

2251 The value of the Offset field in the MQMD or MQMDE structure is less than zero or greater than 999 999 999.

2252 The OriginalLength field in the MQMD or MQMDE structure is invalid.

2253 The length of the application message data in the segment is zero.

2255 The options specified on the call required the queue manager to process the call within a unit of work.

2256 The MQGMO supplied is less than MQGMO_VERSION_2.

2257 The MQMD supplied is less than MQGMO_VERSION_2.

2258 An invalid combination of options and values was specified.

2259 The specification of the MQGMO_LOGICAL_ORDER option for the call is different from the specification of that option for the previous call for the queue handle.

2260 The transmission queue header structure MQXQH in the message data is not valid.

2261 A channel detects an error in the soue environment data of MQRMH.

2262 A channel detects an error in the soue name data of MQRMH.

2263 A channel detects an error in the destination environment data of MQRMH.

2264 A channel detects an error in the destination name data of MQRMH.

2265 The trigger message structure MQTM in the message data is not valid.

2266 The cluster workload exit defined by the queue-manager’s ClusterWorkloadExit attribute failed unexpectedly or did not respond in time.

2267 The cluster workload exit defined by the queue-manager’s ClusterWorkloadExit attribute could not be loaded.



2268 All instances of the cluster queue are currently put-inhibited.

2269 Trying to use a resource required for clustering.

2270 No instances of the queue in the cluster.

2274 The MQGMO_MARK_SKIP_BACKOUT option cannot be used from a DB2 Stored Procedure.

2277 The MQCD channel definition structure contains data that is not valid.

2278 The MQCD channel definition structure is not specified correctly.

2279 The channel has been stopped by an operator.

2280 The configuration handle Hconfig is not valid.

2281 The function identifier Function is not valid.

2282 The channel was started.

2283 The channel has been stopped.

2284 The channel is unable to do data conversion.

2285 The required underlying service is not available.

2286 Unable to complete initialization successfully.

2287 Unable to complete termination successfully.

2288 The name specified for the QName parameter is not recognized.

2289 The component encounters an unexpected error.

2290 The queue specified by the QName parameter is already defined to the name service.

2291 The user ID cannot be determined.

2292 The name specified by the EntityName parameter is not recognized.

2293 The name specified by the AuthEntityName parameter is not recognized.

2294 The name specified by the RefObjectName parameter is not recognized.

2295 The channel is able to become active.

2296 The channel is unable to become active.

2297 The unit of work had been canceled.

2299 The Selector parameter has the wrong data type.



2300 The value of the MQIASY_TYPE data item in the administration bag is not MQCFT_COMMAND.

2301 The value of the ItemIndex parameter is not MQIND_NONE.

2302 The data item is one that cannot be altered by the application.

2303 The data in the buffer or message could not be converted into a bag.

2304 The Selector parameter has a value that is outside the valid range.

2305 The bag contains more than one data item with the selector value specified by the Selector parameter.

2306 The specified index is not present.

2307 The String parameter is not valid.

2308 The Encoding field in the message descriptor MQMD contains a value that is not supported.

2309 The Selector parameter specifies a selector that does not exist in the bag.

2310 The OutSelector parameter is not valid.

2311 The string has been truncated to fit in the buffer.

2312 The data type conflicts.

2313 The data type of this occurrence differed from the data type of the first occurrence.

2314 An index parameter is not valid.

2315 The bag had been created by the system.

2316 The ItemCount parameter is invalid.

2317 The Format field value is not supported.

2318 The system selector is not one that is supported.

2319 The ItemValue parameter is not valid.

2320 The handle is not valid.

2321 A parameter is not present in the administration bag.

2322 The command server that processes administration commands is not available.

2323 The StringLength parameter is not valid.

2324 The command code is not recognized.



2325 Nested bags are not supported.

2326 The Bag parameter specifies the handle of a bag that has the wrong type.

2327 The ItemType parameter is not valid.

2328 System bags cannot be deleted by the application.

2329 The data item is one that cannot be deleted by the application.

2330 The CodedCharSetId parameter is not valid.

2331 The message token is not valid.

2332 The Format field was not MQFMT_WORK_INFO_HEADER.

2333 The message data did not begin with a valid MQWIH structure.

2334 The MQRFH structure is not valid.

2335 The contents of the NameValueString field in the MQRFH structure are not valid.

2336 The command name contained in the NameValueString field is not valid.

2337 A parameter name contained in the NameValueString field is not valid for the command specified.

2338 A parameter occurs more than once in the NameValueString field.

2339 The command specified in the NameValueString field requires a parameter that is not present.

2340 A required character-set conversion is not available.

2341 A required character-set conversion is not available.

2342 The queue manager is not connected to a DB2 subsystem.

2343 The queue specified in the MQOD structure cannot be resolved unambiguously.

2344 The connection tag associated with the unit of work is not yet available for reuse.

2345 No suitable coupling facility to hold the structure.

2346 The coupling-facility structure specified in the queue definition is temporarily unavailable.

2347 The list header associated with the coupling-facility structure specified in the queue definition is temporarily unavailable.



2348 The user is not authorized to access the coupling-facility structure specified in the queue definition.

2349 The coupling-facility structure name specified in the queue definition is not defined.

2350 The connection tag is being used by the queue manager for recovery processing.

2351 An attempt was made to use inside a global unit of work a connection handle that is participating in another global unit of work.

2352 An attempt was made to use inside a global unit of work a connection handle that is participating in a queue-manager coordinated local unit of work.

2353 An attempt was made to use outside a unit of work a connection handle that is participating in a global unit of work.

2354 An object created by a DTC transaction does not issue a transactional MQI call until after the DTC transaction has timed out.

2355 The mixture of calls used by the application to perform operations within a unit of work is not supported.

2356 The workload exit parameter structure ExitParms is not valid.

2357 The address specified by the CurrentRecord parameter is not the address of a valid record.

2358 The offset specified by the NextOffset parameter is not valid.

2359 The current record is the last record in the chain.

2360 he definition of the object to be accessed is not compatible with the queue manager to which the application has connected.

3009 Structure length not valid.

3010 Structure length not valid.

3011 String length not valid.

3013 Structure type not valid.

3014 Parameter identifier is not valid.

3015 Parameter identifier is not valid.

3017 Duplicate parameter.



3018 Duplicate parameter.

3019 Parameter count too small.

3020 Parameter count too big.

3021 Queue already exists in cell.

3022 Queue type not valid.

3025 Replace value not valid.

3035 Parameter sequence not valid.

3046 Purge value not valid.

3088 Cluster name conflict.

3090 Cluster usage conflict.

4001 Object already exists.

4002 Object has wrong type.

4003 New and existing objects have different type.

4004 Object is open.

4005 Attribute value not valid.

4008 Object name not valid.

4028 Get message failed.

4029 Put message failed.

4030 Ping error.

4031 Channel in use.

4032 Channel not found.

4033 Remote channel not known.

4034 Remote queue manager not available.

4035 Remote queue manager terminating.

4036 MQINQ call failed.

4037 Queue is not a transmission queue.

4038 Channel disabled.

4039 User exit not available.



4040 Commit failed.

4042 Channel already exists.

4043 Data too large.

4044 Channel name error.

4045 Transmission queue name error.

4047 Message channel agent name error.

4048 Channel send exit name error.

4049 Channel security exit name error.

4050 Channel message exit name error.

4051 Channel receive exit name error.

4052 Transmission queue name not allowed for this channel type.

4053 Message channel agent name not allowed for this channel type.

4054 Disconnection interval not allowed for this channel type.

4055 Short retry parameter not allowed for this channel type.

4056 Short timer parameter not allowed for this channel type.

4057 Long retry parameter not allowed for this channel type.

4058 Long timer parameter not allowed for this channel type.

4059 Put authority parameter not allowed for this channel type.

4061 Connection name parameter required but missing.

4062 Error in connection name parameter.

4063 Set call failed.

4064 Channel not active.

4065 Channel terminated by security exit.

4067 Dynamic queue scope error.

4068 Cell directory is not available.

4069 Message retry count not valid.

4070 Message-retry count parameter not allowed for this channel type.

4071 Channel message-retry exit name error.

4072 Message-retry exit parameter not allowed for this channel type.



4073 Message retry interval not valid.

4074 Message-retry interval parameter not allowed for this channel type.

4075 Nonpersistent message speed not valid.

4076 Nonpersistent message speed parameter not allowed for this channel type.

4077 Heartbeat interval not valid.

4078 Heartbeat interval parameter not allowed for this channel type.

4079 Channel automatic definition error.

4080 Channel automatic definition parameter not allowed for this channel type.

4081 Channel automatic definition event error.

4082 Channel automatic definition event parameter not allowed for this channel type.

4083 Channel automatic definition exit name error.

4084 Channel automatic definition exit parameter not allowed for this channel type.

4085 Action suppressed by exit program.

4086 Batch interval not valid.

4087 Batch interval parameter not allowed for this channel type.

4088 Network priority value is not valid.

4089 Network priority parameter not allowed for this channel type.

4090 Channel closed.

Index 195

Index

Symbols:CandleInternal.MessageEditor 60:CandleSamples.MessageEditor 60<Audit> 35, 72<ContextPath> 33<Environment> 34<FieldSize> 35<Filter> 36<Idle> 35<Keystore> 35<MAPCS> 37, 38<MaximumQueues> 36<MaximumResponseSize> 36<MBCS> 37<Namespace> 36, 60<Platform> 33<Port> 33<ProfilePath> 33<QMGRS> 34<ResourceBase> 33<Security> 35<Timeout> 35<Trace> 34<UseUserId> 35<ValidateUser> 34

Aaccess control 38adding client connections 49adding entries for client connections 49adding JMS connections 50adding nodes

in tree editor 93adding nodes (in text editor) 93Adobe portable document format 14Append messages to the end option 84application formats 115

Apply Filters command 74Apply Filters dialog 111Apply filters option 66auditing changes 23, 72

Bbacking up the LDAP directory

database 155, 158binary function 116binary values 116browsing messages 76

CCandle Customer Service and

Satisfaction 16cardinality 93CCSID 37changes, auditing 23, 72changing queue depth 71Channel Name (of SRVCONN channel) 50character sets, supported 57characterSet field 85client connections

adding entries for 49deleting 51editing properties 51using 49viewing properties 51

Close Queue command 73codepage sets, mapping 37Column Filter editor 123column filters

about 109creating 123–124deleting 126editing 125

Column Filters dialog 109

D


Commit command 73committing changes 72common format 128config.xml

description 28example 32

configuring server security 38Connection Factory Name 51Connection Name 50context

editing 69Context Factory 51context fields 69Context option 68Copy command (in text editor) 93copying messages 76Create Message command 73creating a new message 88creating entries for JMS connections 50creating formatted messages 92–93creating queues 55creating row filters

complex 117simple 116

creating unformatted messages 94–96, ??–98

customer support 16Cut command (in text editor) 93cutting messages 76

DDataFilters dictionary, location of 36dead letter queue

forwarding messages from 81dead-letter header 81default field size, unformatted messages 35default namespace 60Delete unloaded messages option 84deleting

column filters 126deleting client connections 51deleting JMS connections 51

deleting local queue managers 51deleting messages 76, 78deleting nodes (in text editor) 93deleting queues 55deleting remote queue managers 51deleting the LDAP directory 162description, PathWAI Editor 18Directory

backing up 158removing local 161unconfiguring local 158

Directory Information Tree 147directory records 146directory server 146

starting on UNIX (command line) 152starting on UNIX (GUI) 151starting on Windows 150stopping on UNIX (GUI) 151stopping on Windows 150

Display header option 66, 67Display queue in logical order 69distinguished name 147Do not update header format option 93document type declaration 97Document Type Definitions (DTDs) 58documentation set information 12domain components 147double byte character sets 57

EEdit command 74Edit Message dialog 86Edit under syncpoint control option 67editing

message properties 93editing connection properties 51editing formatted messages 92–93editing headers 90editing messages 89editing unformatted messages 94–96editing views 22encoding field 85

Index 197

F

error messagesclient 169–175metadata repository 168server 176–178WebSphere MQ 179–194

Exit command 73Expression editor 113

Ffield size, setting 35fields in repeating groups 79File menu 78Filter definition 114filter names 117filtering queue list 53

by queue name 54by queue type 53

filters 108–126applying 111–112for unformatted text 118naming conventions 117samples 109sharing definitions 109

finding message contents 79format field 85Format Structure box 115FORMAT.ini files, converting to message

format definitions 64Formats box 115formatted messages

creating 92–93editing 92–93

Forward command 82Forward Messages dialog 82forwarding messages 76, 78, 81–82

from dead letter queue 81

Hheader fields

JMS 90WebSphere MQ 90

header filters 111headers, editing 90hexadecimal editor 93, 100hexadecimal messages 100–101Host (of queue manager) 50

Iidle time, server 35Ignore Message Formatting 93Ignore message formatting option 67import utility 64importing PQEdit format definitions 64importing records to a Directory 153

JJMS connections

adding 50creating entries for 50deleting 51editing properties 51viewing properties 51

JMS messagesediting properties 93

JMSMD 115

Kkxymsged.aud 72kxyruns.bat 40

LLDAP 146LDAP directory

backing up the database 155, 158importing records 153removing 162seeding 153unconfiguring 161

LDAP server 22ldapadd command 155ldapsearch command 159.ldf file extension 149

M


LDIF format 149Length field 118Load command 74loading messages 84loading messages from a file 83local queue managers

deleting 51listing of 49

local security policy, updating 39logging in to server 43

Mmain application window 46Maximum number of messages per display

option 67MDR namespaces

:CandleInternal.MessageEditor 60:CandleSamples.MessageEditor 60changing default 60

message files, location of 83message filter definitions

storing 63message filters 21

about 108message format definitions 58–64

and namespaces 60and queue names 61converting FORMAT.ini files 64description 58distributing 63for non-XML (raw) messages 59for XML messages 59in the MDR 60referencing in message header 61storing 63use of 22

Message Format Editor 58message format, determining 60message header formats 115message headers

referencing message formats definitions in 61

message prolog, adding information to 95Message window 70–76

editing commands in 73message display in 70

messagesbrowsing 76copying 76creating 88cutting 76deleting 76, 78editing 89finding contents 79formatted display 70forwarding 76, 78, 81–82

from dead letter queue 81loading from a file 83, 84previewing 86printing 86replacing content 80sample 131selecting

selecting messages 76unformatted display 70unloading to a file 83unparsable 71

metadata repository 60MQMD 115multiple byte character sets 37

Nnamespace

default 36namespaces

and message format definitions 60naming attribute 147No authentication option 38

OObject Access Manager. 38objectClass attribute 146Open Message dialog 69Open Queue dialog 56, 66, 111

Index 199

P

Open read only option 69Operators palette 114Other Properties 51

PPaste command (in text editor) 93PathWAI Editor description 18PathWAI Editor server, see serverPDF files, adding annotations 15pFormat tag 130.pju extension 83.pmu extension 83Port (of queue manager) 50PQEdit format definitions, importing 64previewing messages 86Print command 73, 86Print dialog 86Print Preview command 73, 86printing messages 86printing problems 14Provider URL 51purging queues 56

Qqueue depth, changing 71queue filters 21queue list

filteringby queue name 53, 54by queue type 53

viewing 47Queue Manager Name 50queue name, filtering by 54Queue Type dialog 53queue type, filtering by 53queues

creating 55deleting 55maximum displayed 36open queue options

Apply filters 66Context 68

Display header 66, 67Display queue in logical order 69Edit under syncpoint control 67Ignore message formatting 67Maximum number of message per

display 67reassemble segmented messages 69

opening 56, 66opening options

open read only 69options 66–69purging 56

RReassemble segmented messages 69referencing message format definitions 61Refresh command 73remote queue managers

deleting 51removing local Directory 161removing nodes

in tree editor 93removing the LDAP directory 162repeating groups 79, 108Replace command 74replacing message content 80resources, listing of 21retry

messagesretry sending 81

Retry DLQ Messages option 81Retry option 82Rollback command 73, 78rolling back changes 72Row Filter dialog 108Row Filter editor 113row filters

about 108creating 113–119deleting 122editing 120

S


Ssample messages

examining 131loading 131

samples 141–144Save Filter dialog 118SBCS 37searching message contents

messagessearching contents 79

searching on fields in repeating groups 79security options, configuring 38seeding the LDAP directory 153Select Header Fields option 85server

connecting to 43logging in 43running as Windows service 39starting (on UNIX) 41starting (on Windows) 39, 40stopping (on Windows) 39

server configuration parameters 33–38<Audit> 35<ContextPath> 33<Environment> 34<FieldSize> 35<Filter> 36<Idle> 35<Keystore> 35<MAPCS> 37<MaximumQueues> 36<MaximumResponseSize> 36<MBCS> 37<Namespace> 36<Platform> 33<Port> 33<ProfilePath> 33<QMGRS> 34<ResourceBase> 33<Security> 35<Timeout> 35<Trace> 34

<UseUserId> 35<ValidateUser> 34

server configuration profiledescription 28example 32

server idle time 35server log in window 43server security

configuring 38server URL, specifying 43single byte character sets 37, 57source format 128starting the directory server

UNIX (command line) 152UNIX (GUI) 151Windows 150

starting the serveron UNIX 41on Windows 39, 40

StartOffset field 118stopping the directory server

UNIX (GUI) 151stopping the server

on UNIX 41on Windows 39

Strip DLQ Header option 82syncpoint control 67, 78system formats 115

Ttext editor

adding and deleting nodes in 93entering message data in 93

text filters 118TextData field 118TextMessage format 118tree editor

about 92Type of Message 95

Uunconfiguring a local Directory 158

Index 201

V

unconfiguring the LDAP directory server 161

Undo command (in text editor) 93unformatted messages

creating 94–96default field size 35editing 94–96setting field size 35

Unload All Messages option 83Unload all messages option 84Unload command 75unloaded messages

location of 83unloading messages to a file 83URLs, in LDAP 148usage scenarios 24User authentication 38Using Forward command

with dead letter queues 82with the Filter command 82

VVariant Definitions dialog 132Variant Definitions feature 109variant format definitions

about 109creating 132

variant formats 128–137creating 132description 128samples 130sharing 128sharing definitions 109

WWebSphere MQ message descriptor 68

XXML declaration 97XML messages 97–98XML naming conventions 97

XML Schema 97XML Schemas 58XML tree editor 95, 98

X


Glossary 203

Glossary

B

backout count A count maintained by the underlying transport of the number of times a message was received under syncpoint but had to be reread because the unit of work had to be backed out.Not all transports support the backout count.

Base64 encoding A format defined by standard RFC2045 for encoding binary data in text form; this allows binary data to be included in XML messages.

C

cardinality Indicates the number of members in a set. In the definition of message formats, cardinality indicates the number of permissible or required occurrences of a field. An optional field is defined by a minimum cardinality of 0.

channel See message channel.

class file A file containing Java object code for a single Java class.

client connection The connection used by a WebSphere MQ client

program to communicate with a queue manager on a server system.

code page An assignment of displayable, printable characters and control codes to every possible binary combination of fields of a given size. In a one-byte (eight-bit) code page, there are 256 possible binary values (called code points). In addition, there are seven-bit, two-byte, and three-byte code pages.

commit “An operation that applies all the changes made during the current unit of recovery or unit of work. After the operation is complete, a new unit of recovery or unit of work begins. Contrast with backout.” [I]

connection In a JMS implementation, a “connection encapsulates a virtual connection with a JMS provider”. A JMS client uses the set of connection configuration parameters encapsulated by a connection factory to create a connection with a provider.

connection factory An administered object that encapsulates the set of configuration parameter a JMS client uses to create a connection with a provider.

This glossary contains terms from IBM’s WebSphere MQ Bibliography and Glossary, document number SC34-6113-02 (indicated by an I), and from Sun Microsystem’s J2EE Glossary, http://java.sun.com/j2ee/glossary.html, (indicated by an S).

http://java.sun.com/j2ee/glossary.html

http://java.sun.com/j2ee/glossary.html


conversion The process of changing a message to conform to a different format. Examples include moving values of fields in a message or combining several fields in one message format into one field in another message format.

D

destination “A JMS administered object that encapsulates the identity of a JMS queue” [S] A destination is the object a client uses to specify the target of messages it produces and the source of messages it consumes.

Directory Administrator A Java-based GUI application for Windows systems that allows you to view and manage the configuration of the various elements that compose an eBP network. These configurations are stored in an LDAP database or a configuration file.

distinguished name (DN) The collection of attributes that form an entry’s unique symbolic name in the directory.

Document Object Model (DOM) A programming interface specification developed by the Worldwide Web Consortium (W3C) that lets a programmer create and modify XML documents as though they were program objects. With DOM, the programmer can specify how programs interact with documents, which encourages consistent

browser behavior within Web pages and their elements.With the Document Object Model core interface, which includes XML support, programs can individually address any XML element. The specification is also language-independent, built as it is upon CORBA’s Interface Definition Language (IDL).

document type definition (DTD) A document that defines the tags in an XML message. DTDs have the advantage that they are both standard and well understood. Compare to XML Schema.

DTD See document type definition.

E

external entity An XML entity such as a document type definition (DTD) whose content is stored in a separate file, which may reside on a separate system.

F

format See message format.

H

hexadecimal A base-16 number system. Hexadecimal encoding is a convenient way to express binary numbers: One hexadecimal digit can represent the arrangement of four binary

Glossary 205

digits. Two hexadecimal digits can represent eight binary digits, or a byte.

hexadecimal encoding A method for encoding binary data in text format in which each byte is represented by two hexadecimal digits.

I

initial context “The starting point for resolution of names for naming and directory operations.” [S]

J

JMS Java Message Service. An application program interface (API) from Sun Microsystems. The JMS API provides Java programs with a common interface to standard messaging protocols and to special messaging services.

JMS provider “A messaging system that implements the Java Message Service as well as other administrative and control functionality needed in a full-featured messaging product.” [S]

L

LDAP Lightweight Directory Access Protocol. A subset of the X.500 directory standard first designed and implemented by the University of Michigan; currently at version 3. LDAP is based on the

X.500 directory standard written by the International Standards Organization (ISO).Candle supplies a version-2 LDAP directory (CASP Directory Services) with PathWAI Editor for Messages, which is managed by the Directory Administrator.

LDIF LDAP Data Interchange Format. A form of LDAP that stores all directory information in a flat text file rather than a random-access database.

M

MDR See metadata repository.

message channel ““In distributed message queuing, a mechanism for moving messages from one queue manager to another. A message channel comprises two message channel agents (a sender at one end and a receiver at the other end) and a communication link.” [I]

message format The structure of a message or class of messages. This includes the order of the fields, the data types of each field, the length of the field, how the fields are delimited within the message, any tags or suffixes for each field, and so on. The message format does not describe the data values in the message, but rather the structure of the message.Also, a record in the metadata repository that defines a message’s format.


message format definition aA description of the structure of a particular type or class of message. Message format definitions document the structure of the messages and provide a vehicle for describing the message formats to others.

metadata Data about data. Definitional data that provides information about other data managed by an application.

metadata definition A definition of the structure and appearance of data. It does not actually describe the data values themselves.

metadata repository (MDR) A hierarchially structured store of metadata—in this particular implementation, metadata that provides information about message formats. The metadata repository can be stored in an LDAP directory or in a configuration file.

P

pFormat tag The field in the message header where PathWAI Editor records the name of the format used to parse a message if it uses a format other than the one supplied in the Format field. Used especially with variant formats.

Q

queue In messaging, a sequence of messages waiting to be processed by either a sender or a receiver. In JMS point-to-point messaging, a queue is the object (destination) a client uses to specify the target of messages it produces and the source of messages it consumes. In a WebSphere MQ messaging system, a queue is the object message queuing applications can put messages on, and get messages from. A queue is owned and maintained by a queue manager.

queue manager “A system program that provides queuing services to applications. It provides an application programming interface so that programs can access messages on the queues that the queue manager owns.” [I]

raw message A message defined in a format other than XML.

raw message format A message format defined in the metadata repository that is not an XML message format. Raw message-format definitions may indicate the structure of the overall message format, the structure of subcomponents, the structure of individual fields, and how messages and fields are composed and understood.

rollback “An operation that reverses all the changes made during the current unit of recovery or unit of work. After the operation is complete, a new unit of recovery or unit of work begins.... Contrast with commit.” [I]

Glossary 207

S

segmented message WebSphere MQ messages that are too long for a queue may be split into segments which are placed on the queue as separate messages. PathWAI Editor will reassemble these segments into a single message for display and editing if the Reassemble Segmented Messages option is selected when the queue is opened.

T

transport A messaging middleware system (such as WebSphere MQ or WebLogic) used to carry a message.

U

URI See Uniform Resource Identifier.

Uniform Resource Identifier (URI) A means of identifying content located on the internet. The most common form of URI is a web page address, a subtype of URI known as a Uniform Resource Locator (URL).A URI typically comprises:� the mechanism used to access the

resource (for example, http or ftp)� the computer on which the resource is

located� the name of the resource

X

XML Extensible Markup Language. A data-description language derived from Standard Generalized Markup Language (SGML). A tool for encoding messages so they describe their own fields. XML allows you to format a document as a data structure. As program objects, such documents can have their contents and data hidden within the object, which allows you to control who can manipulate the document and how.The XML standard aids in exchanging data between applications and users. It was designed to be, among other things, flexible, platform independent, and understandable.

XML message format A message format that follows the W3C standard and is defined in the metadata repository as an XML document.

XML namespace A tool for uniquely identifying XML tags in an XML document so no name collisions can occur with other documents.

XML Schema XML document that describe valid XML messages in ways that a document type definition (DTD) cannot and that can therefore be referenced via the DOM (Document Object Model) interface. In addition to supporting standard data types such as float and boolean, XML schemas let you define your own data types. Also, XML Schemas, unlike DTDs, support XML namespaces. (The metadata repository


provides XML namespace support for DTDs.)

Documents

PathWAI Editor for Messages User’s ഀ䜀甀椀搀publib.boulder.ibm.com/tividd/td/ITPathEfM/GC32...Listing of queues for queue managers or JMS providers ... This guide provides