User’s Guide PathWAI™ Editor for Messages
Version 200
GC32-9340-00
November 2003
Candle Corporation 100 North Sepulveda Blvd. El Segundo, California 90245 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.
2 PathWAI Editor for Messages User’s Guide, Version 200 Contents
What’s New ...... 9
Preface ...... 11 About This Book ...... 12 Adobe Portable Document Format ...... 14 Candle Customer Service and Satisfaction ...... 16
Chapter 1. Introducing PathWAI™ Editor for Messages...... 17 What is PathWAI Editor for Messages?...... 18 PathWAI Editor Features ...... 21 Using PathWAI Editor: Typical Scenarios ...... 24
Chapter 2. Getting Started ...... 27 Configuring the Server ...... 28 Starting and Stopping the Server...... 39 Connecting to the Server...... 43
Chapter 3. Managing Connections and Queues ...... 45 The Main Window...... 46 Adding and Deleting Connections ...... 49 Filtering Queue Lists ...... 53 Working with Queues ...... 55
Chapter 4. Creating and Using Message Format Definitions ...... 57 About Message Format Definitions ...... 58 Namespaces and Message Format Definitions ...... 60 Distributing Message Format Definitions ...... 63
Chapter 5. Browsing and Editing Queues...... 65 Opening the Queue...... 66 The Message Window ...... 70 Browsing and Selecting Messages ...... 76
Contents 3 Copying, Moving, and Deleting Messages ...... 77 Finding and Replacing Message Data ...... 79 Forwarding Messages ...... 81 Loading and Unloading Messages ...... 83 Previewing and Printing Messages ...... 86
Chapter 6. Creating and Editing Messages ...... 87 Creating and Editing Messages ...... 88 Working with Formatted Messages...... 92 Working with Unformatted Messages...... 94 Working with XML Messages ...... 97 Working with Hexadecimal Messages ...... 100 Working with JMS Messages ...... 102
Chapter 7. Working with Message Filters ...... 107 About Message Filters ...... 108 Applying Filters ...... 111 Creating Row Filters ...... 113 Editing Row Filters ...... 120 Deleting Row Filters ...... 122 Creating Column Filters...... 123 Editing Column Filters ...... 125 Deleting Column Filters ...... 126
Chapter 8. Creating Variant Definitions ...... 127 About Variant Formats ...... 128 An Example of Variant Formats...... 130 Creating Variant Definitions...... 132 Editing a Variant Definition ...... 135 Deleting a Variant Definition ...... 137
4 PathWAI Editor for Messages User’s Guide, Version 200 Appendices
Appendix A. Samples ...... 141
Appendix B. LDAP Directory ...... 145 About LDAP Directories and Directory Services ...... 146 Starting and Stopping the Directory Server ...... 150 Importing Records to an Existing Directory (Seeding) ...... 153 Backing Up a Local Directory Database ...... 158 Unconfiguring the Local Directory Service...... 161 Removing the Local Directory ...... 162 Reconfiguring the Directory Server ...... 164
Appendix C. Return Codes and Error Messages ...... 167 Metadata Repository Messages ...... 168 Client Messages...... 169 Server Messages ...... 176 WebSphere MQ Messages ...... 179
Index ...... 195
Glossary ...... 203
Contents 5
6 PathWAI Editor for Messages User’s Guide, Version 200 Figures
Figure 1. Configuration Tool: Windows ...... 29 Figure 2. Configuration Window: Unix...... 31 Figure 3. Sample Server Profile (config.xml) ...... 32 Figure 4. Adding a Service User ...... 40 Figure 5. Filtering WebSphere MQ and JMS Queue Lists by Queue Type. . . . . 53 Figure 6. Tree Editor ...... 92 Figure 7. Text Editor...... 94 Figure 8. XML Tree Editor ...... 99 Figure 9. Hexadecimal Editor...... 100 Figure 10. The Apply Filters Dialog ...... 112 Figure 11. The Variant Definition Dialog ...... 134 Figure 12. The Retrieve Variant Dialog...... 136 Figure 13. Smplfmt2 Definition in the Directory Administrator ...... 148 Figure 14. Manage Candle Services (Windows) ...... 151 Figure 15. Seed Business Directory Tab of the Configuration Tool (Windows) . 154 Figure 16. Business Directory Utilities Tab of the Configuration Tool (Windows) 159 Figure 17. Configure Business Directory Tab of the Configuration Tool (Windows). 165
Figures 7
8 PathWAI Editor for Messages User’s Guide, Version 200 W 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
Tw o le vel s of s ec urity
Support for long messages Discovery of local queue managers Listing of queues for queue managers or JMS providers
Queue and message filters
What’s New 9
10 PathWAI Editor for Messages User’s Guide, Version 200 P 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.
Preface 11 About This Book
About This Book
Who should read this book This 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 information PathWAI 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 information You 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/
12 PathWAI Editor for Messages User’s Guide, Version 200 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 documentation To order additional product manuals, contact your Candle Support Services representative.
We would like to hear from you Candle 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.
Preface 13 Adobe Portable Document Format
Adobe Portable Document Format
Printing this book Candle 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.
14 PathWAI Editor for Messages User’s Guide, Version 200 Adobe Portable Document Format
Contacting Adobe If 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 files If 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.
Preface 15 Candle Customer Service and Satisfaction
Candle Customer Service and Satisfaction
Background To 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 contacts You 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.
16 PathWAI Editor for Messages User’s Guide, Version 200 Introducing PathWAI™ Editor 1 for Messages
Overview This 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 contents What is PathWAI Editor for Messages? ...... 18 PathWAI Editor Features...... 21 Using PathWAI Editor: Typical Scenarios ...... 24
Introducing PathWAI™ Editor for Messages 17 What is PathWAI Editor for Messages?
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.
18 PathWAI Editor for Messages User’s Guide, Version 200 What is PathWAI Editor for Messages?
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.
Introducing PathWAI™ Editor for Messages 19 What is PathWAI Editor for Messages?
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.
20 PathWAI Editor for Messages User’s Guide, Version 200 PathWAI Editor Features
PathWAI Editor Features
Security A 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 resources PathWAI 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 messages When 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
Introducing PathWAI™ Editor for Messages 21 PathWAI Editor Features
Powerful message format definition capabilites PathWAI 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 views PathWAI 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 directory In 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.
22 PathWAI Editor for Messages User’s Guide, Version 200 PathWAI Editor Features
Audit logging PathWAI Editor allows you to log editing operations, so changes can be tracked. For more information, see “Auditing changes” on page 72.
Introducing PathWAI™ Editor for Messages 23 Using PathWAI Editor: Typical Scenarios
Using PathWAI Editor: Typical Scenarios
Overview The following three scenarios illustrate typical ways you might use PathWAI Editor.
Scenario 1—Testing a new application You 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—Troubleshooting You 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:
24 PathWAI Editor for Messages User’s Guide, Version 200 Using PathWAI Editor: Typical Scenarios
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 Messages You 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.
Introducing PathWAI™ Editor for Messages 25 Using PathWAI Editor: Typical Scenarios
26 PathWAI Editor for Messages User’s Guide, Version 200 2 Getting Started
Overview This 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 contents Configuring the Server ...... 28 Starting and Stopping the Server ...... 39 Connecting to the Server ...... 43
Getting Started 27 Configuring the Server
Configuring the Server
Overview At 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.
28 PathWAI Editor for Messages User’s Guide, Version 200 Configuring the Server
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
Getting Started 29 Configuring the Server
Unix (GUI mode) To edit the profile: 1. In a command window, change to the PathWAI Editor bin directory: cd
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
30 PathWAI Editor for Messages User’s Guide, Version 200 Configuring the Server
Figure 2. Configuration Window: Unix
Getting Started 31 Configuring the Server
Figure 3. Sample Server Profile (config.xml)
32 PathWAI Editor for Messages User’s Guide, Version 200 Configuring the Server
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
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
ContextPath The context prefix. The default value is “/” (the root). This parameter is set by the installer and should not be edited.
Getting Started 33 Configuring the Server
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:
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.
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.
34 PathWAI Editor for Messages User’s Guide, Version 200 Configuring the Server
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:
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
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.
Getting Started 35 Configuring the Server
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:
36 PathWAI Editor for Messages User’s Guide, Version 200 Configuring the Server
– 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:
MAPCS This parameter lets WebSphere MQ supported Codepage Sets be mapped to ones supported by Java.
Getting Started 37 Configuring the Server
The different platforms and release levels of MQ have different default codepages:
Sun 923 (819 is already handled via the alias table) HP 1051 AIX 819
For example:
Configuring server security The PathWAI Editor server can be configured to operate at two levels of security:
No authentication (
User authentication (
38 PathWAI Editor for Messages User’s Guide, Version 200 Starting and Stopping the Server
Starting and Stopping the Server
Permissions To 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.
Windows Candle 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.
Getting Started 39 Starting and Stopping the Server
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
Figure 4. Adding a Service User
40 PathWAI Editor for Messages User’s Guide, Version 200 Starting and Stopping the Server
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
Getting Started 41 Starting and Stopping the Server
When the agent is started successfully, you will see the message, “Agent started . . .” To stop the PathWAI Editor server: 1. Change to the
42 PathWAI Editor for Messages User’s Guide, Version 200 Connecting to the Server
Connecting to the Server
Accessing the server You 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://
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 in When 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.
Getting Started 43 Connecting to the Server
44 PathWAI Editor for Messages User’s Guide, Version 200 Managing Connections and 3 Queues
Overview This 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 contents The Main Window ...... 46 Adding and Deleting Connections ...... 49 Filtering Queue Lists ...... 53 Working with Queues ...... 55
Managing Connections and Queues 45 The Main Window
The Main Window
Overview When 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 tree If 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.
46 PathWAI Editor for Messages User’s Guide, Version 200 The Main Window
Queue list When 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 commands The following table lists and describes the commands you can access from the menus in the main application window.
Menu Action
File
Create Create a new queue Queue
Managing Connections and Queues 47 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)
Column Create or edit a column filter by specifying fields to be excluded Filters from messages (see “Working with Message Filters” on page 107)
Variant Define alternate formats for formats with content-dependent Definitions variants (see “Creating Variant Definitions” on page 127)
Debugger Open the Debugger console.
Options Open the Options dialog to set debugging options.
48 PathWAI Editor for Messages User’s Guide, Version 200 Adding and Deleting Connections
Adding and Deleting Connections
Overview A 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 entries To 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:
Managing Connections and Queues 49 Adding and Deleting Connections
– 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 entries You 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.
50 PathWAI Editor for Messages User’s Guide, Version 200 Adding and Deleting Connections
–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 properties You 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 connections You can delete entries for remote queue managers accessed through client connections and for JMS connections. You cannot delete entries for local queue managers.
Managing Connections and Queues 51 Adding and Deleting Connections
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 popup menu. You will be asked to confirm the deletion. 2. Click to delete the entry.
52 PathWAI Editor for Messages User’s Guide, Version 200 Filtering Queue Lists
Filtering Queue Lists
Overview If 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 type By 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
Managing Connections and Queues 53 Filtering Queue Lists
Filtering by queue name In 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 ap ply a filte r: 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.
54 PathWAI Editor for Messages User’s Guide, Version 200 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 queue If 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 queue If 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
Managing Connections and Queues 55 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 queue Clicking 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.
56 PathWAI Editor for Messages User’s Guide, Version 200 Creating and Using Message 4 Format Definitions
Overview Message 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 contents About Message Format Definitions ...... 58 Namespaces and Message Format Definitions...... 60 Distributing Message Format Definitions ...... 63
Creating and Using Message Format Definitions 57 About Message Format Definitions
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 definitions For 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
58 PathWAI Editor for Messages User’s Guide, Version 200 About Message Format Definitions
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 definitions For 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”.
Creating and Using Message Format Definitions 59 Namespaces and Message Format Definitions
Namespaces and Message Format Definitions
Overview Message 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
How PathWAI Editor determines the message format When PathWAI Editor reads a message from a queue, it uses the following logic to determine how the message should be processed.
60 PathWAI Editor for Messages User’s Guide, Version 200 Namespaces and Message Format Definitions
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 definitions The namespace in which the PathWAI Editor server is running has implications for the form in which message format definition names are referenced.
Creating and Using Message Format Definitions 61 Namespaces and Message Format Definitions
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 considerations While 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.
62 PathWAI Editor for Messages User’s Guide, Version 200 Distributing Message Format Definitions
Distributing Message Format Definitions
Overview The 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 server Using 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 file If 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
Creating and Using Message Format Definitions 63 Distributing Message Format Definitions
from another metadata repository, you will overwrite any filter definitions that exist in the target file.
Importing PQEdit FORMATS.INI files To 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.
64 PathWAI Editor for Messages User’s Guide, Version 200 5 Browsing and Editing Queues
Overview This 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 contents Opening the Queue ...... 66 The Message Window...... 70 Browsing messages...... 76 Copying, Moving, and Deleting Messages...... 77 Finding and Replacing Message Data ...... 79 Forwarding Messages ...... 81 Loading and Unloading Messages ...... 83 Previewing and Printing Messages ...... 86
Browsing and Editing Queues 65 Opening the Queue
Opening the Queue
Overview Selecting (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 filters 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 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
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.)
66 PathWAI Editor for Messages User’s Guide, Version 200 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.)
Browsing and Editing Queues 67 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.
68 PathWAI Editor for Messages User’s Guide, Version 200 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.
Browsing and Editing Queues 69 The Message Window
The Message Window
Overview When 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 display In 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
70 PathWAI Editor for Messages User’s Guide, Version 200 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 fields You 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 depth You 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 messages You 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.
Browsing and Editing Queues 71 The Message Window
Editing under syncpoint control Editing 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 changes Updates 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
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
72 PathWAI Editor for Messages User’s Guide, Version 200 The Message Window
Commands The 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
Create Access an editor to create a new message 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. Print Preview the messages as they will appear in printed form. (This is Preview a good way to view entire long messages, without having to scroll through them.)
Close Close the queue and return to the Main window. Queue
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.
Browsing and Editing Queues 73 The Message Window
Command Action
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 Before you invoke the Find or Replace dialog you must select the Menu 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.
Column Launch an editor to create, edit, or delete a column filter. Filters
Apply Select one or more filters to apply to the messages in the queue. Filters
Variant Launch an editor to create, edit, or delete a variant definition for Definitions formats with data-determined structure.
Load Load messages from a flat file into the queue.
74 PathWAI Editor for Messages User’s Guide, Version 200 The Message Window
Command Action
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 & Access the Table of Contents for the online Help. Index
PathWAI Access version number and other information about PathWAI Editor for Editor. Messaging
Browsing and Editing Queues 75 Browsing and Selecting Messages
Browsing and Selecting Messages
Browsing messages If 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 messages Each 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.
76 PathWAI Editor for Messages User’s Guide, Version 200 Copying, Moving, and Deleting Messages
Copying, Moving, and Deleting Messages
Overview PathWAI Editor supports a number of commands that let you edit the queues by duplicating, moving, and deleting messages.
Copying messages Copying 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 cop y a s ingle me ss age: 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 messages Messages 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.
Browsing and Editing Queues 77 Copying, Moving, and Deleting Messages
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 s eve ral me ss age s: 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 messages If 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 s eve ral me ss age s: Click the checkbox beside each message that you want to copy, then select Edit > Delete.
78 PathWAI Editor for Messages User’s Guide, Version 200 Finding and Replacing Message Data
Finding and Replacing Message Data
Overview You 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 element To 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.
Browsing and Editing Queues 79 Finding and Replacing Message Data
Replacing the contents of a field or element To 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.
80 PathWAI Editor for Messages User’s Guide, Version 200 Forwarding Messages
Forwarding Messages
Overview You 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 queue The 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.
Browsing and Editing Queues 81 Forwarding Messages
Using Forward with filters The 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 message To 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.
82 PathWAI Editor for Messages User’s Guide, Version 200 Loading and Unloading Messages
Loading and Unloading Messages
Overview The 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:
Unloading messages You 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.
Browsing and Editing Queues 83 Loading and Unloading Messages
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 messages The 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
84 PathWAI Editor for Messages User’s Guide, Version 200 Loading and Unloading Messages
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.
Browsing and Editing Queues 85 Previewing and Printing Messages
Previewing and Printing Messages
Printing messages in the current display You 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 message To 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.
86 PathWAI Editor for Messages User’s Guide, Version 200 6 Creating and Editing Messages
Overview This 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 contents Creating and Editing Messages ...... 88 Working with Formatted Messages ...... 92 Working with Unformatted Messages ...... 94 Working with XML Messages ...... 97 Working with Hexadecimal Messages ...... 100 Working with JMS Messages...... 102
Creating and Editing Messages 87 Creating and Editing Messages
Creating and Editing Messages
Overview PathWAI 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 message To 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
88 PathWAI Editor for Messages User’s Guide, Version 200 Creating and Editing Messages
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 message To 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:
If you select PathWAI Editor opens A formatted message tree view An unformatted XML message or a raw text view message that contains only printable characters An unformatted raw message that hexadecimal editor contains unprintable characters
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.
Creating and Editing Messages 89 Creating and Editing Messages
Editing message headers In 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.
90 PathWAI Editor for Messages User’s Guide, Version 200 Creating and Editing Messages
PathWAI Editor fields PathWAI 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)
Creating and Editing Messages 91 Working with Formatted Messages
Working with Formatted Messages
Overview If 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
92 PathWAI Editor for Messages User’s Guide, Version 200 Working with Formatted Messages
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 descriptor To 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 nodes You 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 data You 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 properties If 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.
Creating and Editing Messages 93 Working with Unformatted Messages
Working with Unformatted Messages
Overview If 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
94 PathWAI Editor for Messages User’s Guide, Version 200 Working with Unformatted Messages
Editing view and type of message If 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 table If 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:
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.
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.
Creating and Editing Messages 95 Working with Unformatted Messages
Entering message data in the text area You 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.
96 PathWAI Editor for Messages User’s Guide, Version 200 Working with XML Messages
Working with XML Messages
Overview The 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 Schemas If 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 conventions Element 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
Creating and Editing Messages 97 Working with XML Messages
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 editor You 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 editor To 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:
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 Remove Delete an attribute from the element Attribute Add Data Add message text
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.
98 PathWAI Editor for Messages User’s Guide, Version 200 Working with XML Messages
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.
Creating and Editing Messages 99 Working with Hexadecimal Messages
Working with Hexadecimal Messages
Overview Unformatted 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
100 PathWAI Editor for Messages User’s Guide, Version 200 Working with Hexadecimal Messages
Entering message data The 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:
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. Current The current offset position of the cursor Position 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
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.
Creating and Editing Messages 101 Working with JMS Messages
Working with JMS Messages
Overview PathWAI 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 fields You 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 properties JMS 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
102 PathWAI Editor for Messages User’s Guide, Version 200 Working with JMS Messages
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: 1. In JMS tree or text editing view, click Edit Properties. The Properties editing view opens. 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
Creating and Editing Messages 103 Working with JMS Messages
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: 1. In JMS tree or text editing view, click Edit Properties. The Properties editing view opens. 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 messages PathWAI 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 .
104 PathWAI Editor for Messages User’s Guide, Version 200 Working with JMS Messages
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).
Creating and Editing Messages 105 Working with JMS Messages
106 PathWAI Editor for Messages User’s Guide, Version 200 7 Working with Message Filters
Overview Message 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 contents About Message Filters ...... 108 Applying Filters...... 111 Creating Row Filters ...... 113 Editing Row Filters ...... 120 Deleting Row Filters ...... 122 Creating Column Filters ...... 123 Editing Column Filters ...... 125 Deleting Column Filters ...... 126
Working with Message Filters 107 About Message Filters
About Message Filters
Overview By 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 filters Row 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,
108 PathWAI Editor for Messages User’s Guide, Version 200 About Message Filters
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 filters Column 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 definitions In 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 definitions If 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.
Working with Message Filters 109 About Message Filters
Sample filters The 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.
110 PathWAI Editor for Messages User’s Guide, Version 200 Applying Filters
Applying Filters
Overview You 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 queue When 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 queue In 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.
Working with Message Filters 111 Applying Filters
Figure 10. The Apply Filters Dialog
To ap ply a filte r: 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.
112 PathWAI Editor for Messages User’s Guide, Version 200 Creating Row Filters
Creating Row Filters
Overview Creating 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 editor The 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.
Working with Message Filters 113 Creating Row Filters
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.
114 PathWAI Editor for Messages User’s Guide, Version 200 Creating Row Filters
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.
Working with Message Filters 115 Creating Row Filters
Close the editor window. If you have not saved the current definition, it is deleted.
Access help for using the editor
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.
116 PathWAI Editor for Messages User’s Guide, Version 200 Creating Row Filters
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 filter You 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.
Working with Message Filters 117 Creating Row Filters
7. Create a third expression, select the second expression, then click . You should have a complex expression that looks like the following: (Expression 1 AND Expression 2) OR Expression 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 text PathWAI 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.
118 PathWAI Editor for Messages User’s Guide, Version 200 Creating Row Filters
StartOffset == 201 will retrieve messages starting from the offset 201.
Working with Message Filters 119 Editing Row Filters
Editing Row Filters
Overview On 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 filter To ed it a ro w filte r: 1. In the Main or Message window, select Tool s > 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.
120 PathWAI Editor for Messages User’s Guide, Version 200 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 .
Working with Message Filters 121 Deleting Row Filters
Deleting Row Filters
Overview Deleting filters deletes them from the MDR. Only the user that created a filter can delete it.
Deleting a row filter To 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.
122 PathWAI Editor for Messages User’s Guide, Version 200 Creating Column Filters
Creating Column Filters
Overview Column 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 editor The 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
Working with Message Filters 123 Creating Column Filters
Defining a column filter To 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.
124 PathWAI Editor for Messages User’s Guide, Version 200 Editing Column Filters
Editing Column Filters
Overview On 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 filter To 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.
Working with Message Filters 125 Deleting Column Filters
Deleting Column Filters
Overview Deleting filters removes them from the MDR. Only the user who created a filter can delete it.
Deleting a column filter To 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.
126 PathWAI Editor for Messages User’s Guide, Version 200 8 Creating Variant Definitions
Overview This 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 contents About Variant Formats ...... 128 Creating Variant Definitions ...... 132 Editing a Variant Definition...... 135 Deleting a Variant Definition...... 137
Creating Variant Definitions 127 About Variant Formats
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 definitions If 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.
128 PathWAI Editor for Messages User’s Guide, Version 200 About Variant Formats
For this reason, Candle strongly recommends that you use an LDAP server to share filters and variant format definitions.
Creating Variant Definitions 129 An Example of Variant Formats
An Example of Variant Formats
Overview The 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. Tw o ro w 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.
130 PathWAI Editor for Messages User’s Guide, Version 200 An Example of Variant Formats
Loading the sample messages To 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 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.
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.)
Creating Variant Definitions 131 Creating Variant Definitions
Creating Variant Definitions
Overview To 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 formats You 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 filters You 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 definitions You 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.
132 PathWAI Editor for Messages User’s Guide, Version 200 Creating Variant Definitions
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.
Creating Variant Definitions 133 Creating Variant Definitions
Figure 11. The Variant Definition Dialog
134 PathWAI Editor for Messages User’s Guide, Version 200 Editing a Variant Definition
Editing a Variant Definition
Overview On 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 definition To 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.
Creating Variant Definitions 135 Editing a Variant Definition
Figure 12. The Retrieve Variant Dialog
136 PathWAI Editor for Messages User’s Guide, Version 200 Deleting a Variant Definition
Deleting a Variant Definition
Overview You may want to delete variant definitions that are no longer being used.
Delete a variant definition To 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 delete The 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.
Creating Variant Definitions 137 Deleting a Variant Definition
138 PathWAI Editor for Messages User’s Guide, Version 200 Appendices
Appendices 139
140 PathWAI Editor for Messages User’s Guide, Version 200 A Samples
About the samples PathWAI 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:
Sample 1 This 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.
Samples 141 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.
142 PathWAI Editor for Messages User’s Guide, Version200 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 2 The 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.
Samples 143 Sample 3 The 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.
144 PathWAI Editor for Messages User’s Guide, Version200 B LDAP Directory
Overview This 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 contents About LDAP Directories and Directory Services ...... 146 Starting and Stopping the Directory Server...... 150 Importing Records to an Existing Directory (Seeding) ...... 153 Backing Up a Local Directory Database ...... 158 Unconfiguring the Local Directory Service ...... 161 Removing the Local Directory ...... 162 Reconfiguring the Directory Server ...... 164
LDAP Directory 145 About LDAP Directories and Directory Services
About LDAP Directories and Directory Services
Overview The 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 records An 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
146 PathWAI Editor for Messages User’s Guide, Version 200 About LDAP Directories and Directory Services 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.
LDAP Directory 147 About LDAP Directories and Directory Services
Figure 13. Smplfmt2 Definition in the Directory Administrator
Directory URLs To 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:
148 PathWAI Editor for Messages User’s Guide, Version 200 About LDAP Directories and Directory Services
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:
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
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 Directory 149 Starting and Stopping the Directory Server
Starting and Stopping the Directory Server
Overview This section provides instructions for starting and stopping CASP Directory Services on Windows and Unix.
Windows On Windows, the directory server is run as a Windows service. You can start and stop the server using the Manage Candle Services utility. To start the server: 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). 2. Do one of the following: – 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. 2. Do one of the following: – Right-click CandleNet eBP Directory and select Stop from the popup menu, or – Select (click) CandleNet eBP Directory, then click .
150 PathWAI Editor for Messages User’s Guide, Version 200 Starting and Stopping the Directory Server
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. To start the server: 1. Change to the
LDAP Directory 151 Starting and Stopping the Directory Server
The Manage Candle Services window appears. 3. Do one of the following: – 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: 1. Change to the
152 PathWAI Editor for Messages User’s Guide, Version 200 Importing Records to an Existing Directory (Seeding)
Importing Records to an Existing Directory (Seeding)
Overview This 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.
Windows Follow 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: 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.
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.
LDAP Directory 153 Importing Records to an Existing Directory (Seeding)
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)
154 PathWAI Editor for Messages User’s Guide, Version 200 Importing Records to an Existing Directory (Seeding)
UNIX On 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
-? 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.
LDAP Directory 155 Importing Records to an Existing Directory (Seeding)
-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.
3. Enter the following command: ldapadd [-?] [-b] [-c] -D binddn [-f file] [-h ldaphost] [-n] [-p ldapport] [-v]-w password
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.
156 PathWAI Editor for Messages User’s Guide, Version 200 Importing Records to an Existing Directory (Seeding)
-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.
LDAP Directory 157 Backing Up a Local Directory Database
Backing Up a Local Directory Database
Overview This 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.
Windows On 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
158 PathWAI Editor for Messages User’s Guide, Version 200 Backing Up a Local Directory Database
Figure 16. Business Directory Utilities Tab of the Configuration Tool (Windows)
Unix To backup a directory on UNIX, you use the ldapsearch command, specifying all records with the objectclass attribute and directing the output to a file.
LDAP Directory 159 Backing Up a Local Directory Database
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.
160 PathWAI Editor for Messages User’s Guide, Version 200 Unconfiguring the Local Directory Service
Unconfiguring the Local Directory Service
Overview This 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.
Windows To unconfigure the Directory service, follow 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 is displayed. 3. Select Unconfigure Local eBP Directory Service. 4. Click Apply and wait for this message: eBP Directory Directory service unconfigured!
LDAP Directory 161 Removing the Local Directory
Removing the Local Directory
Overview This 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.
Windows Follow 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
162 PathWAI Editor for Messages User’s Guide, Version 200 Removing the Local Directory
2. Remove the database files by entering the following command: rm NEXTID *.dbb
LDAP Directory 163 Reconfiguring the Directory Server
Reconfiguring the Directory Server
Overview The 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.
Windows To 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: 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. 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.
164 PathWAI Editor for Messages User’s Guide, Version 200 Reconfiguring the Directory Server
Figure 17. Configure Business Directory Tab of the Configuration Tool (Windows)
LDAP Directory 165 Reconfiguring the Directory Server
166 PathWAI Editor for Messages User’s Guide, Version 200 Return Codes and Error C Messages
Overview This 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 content Metadata Repository Messages ...... 168 Client Messages ...... 169 Server Messages ...... 176 WebSphere MQ Messages ...... 179
Return Codes and Error Messages 167 Metadata Repository Messages
Metadata Repository Messages
Overview Messages 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.
.
168 PathWAI Editor for Messaging User’s Guide, Version 200 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."
Return Codes and Error Messages 169 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."
170 PathWAI Editor for Messaging User’s Guide, Version 200 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."
Return Codes and Error Messages 171 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."
172 PathWAI Editor for Messaging User’s Guide, Version 200 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."
Return Codes and Error Messages 173 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."
174 PathWAI Editor for Messaging User’s Guide, Version 200 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."
Return Codes and Error Messages 175 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
176 PathWAI Editor for Messaging User’s Guide, Version 200 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.
Return Codes and Error Messages 177 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}.
178 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 179 WebSphere MQ Messages
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.
180 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 181 WebSphere MQ Messages
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.
182 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 183 WebSphere MQ Messages
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.
184 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 185 WebSphere MQ Messages
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.
186 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 187 WebSphere MQ Messages
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.
188 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 189 WebSphere MQ Messages
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.
190 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 191 WebSphere MQ Messages
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.
192 PathWAI Editor for Messaging User’s Guide, Version 200 WebSphere MQ Messages
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.
Return Codes and Error Messages 193 WebSphere MQ Messages
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.
194 PathWAI Editor for Messaging User’s Guide, Version 200 Index
Symbols Apply Filters command 74 :CandleInternal.MessageEditor 60 Apply Filters dialog 111 :CandleSamples.MessageEditor 60 Apply filters option 66
Index 195 D
Commit command 73 deleting local queue managers 51 committing changes 72 deleting messages 76, 78 common format 128 deleting nodes (in text editor) 93 config.xml deleting queues 55 description 28 deleting remote queue managers 51 example 32 deleting the LDAP directory 162 configuring server security 38 description, PathWAI Editor 18 Connection Factory Name 51 Directory Connection Name 50 backing up 158 context removing local 161 editing 69 unconfiguring local 158 Context Factory 51 Directory Information Tree 147 context fields 69 directory records 146 Context option 68 directory server 146 Copy command (in text editor) 93 starting on UNIX (command line) 152 copying messages 76 starting on UNIX (GUI) 151 Create Message command 73 starting on Windows 150 creating a new message 88 stopping on UNIX (GUI) 151 creating entries for JMS connections 50 stopping on Windows 150 creating formatted messages 92–93 Display header option 66, 67 creating queues 55 Display queue in logical order 69 creating row filters distinguished name 147 complex 117 Do not update header format option 93 simple 116 document type declaration 97 creating unformatted messages 94–96, ??– Document Type Definitions (DTDs) 58 98 documentation set information 12 customer support 16 domain components 147 Cut command (in text editor) 93 double byte character sets 57 cutting messages 76 E D Edit command 74 DataFilters dictionary, location of 36 Edit Message dialog 86 dead letter queue Edit under syncpoint control option 67 forwarding messages from 81 editing dead-letter header 81 message properties 93 default field size, unformatted messages 35 editing connection properties 51 default namespace 60 editing formatted messages 92–93 Delete unloaded messages option 84 editing headers 90 deleting editing messages 89 column filters 126 editing unformatted messages 94–96 deleting client connections 51 editing views 22 deleting JMS connections 51 encoding field 85
196 PathWAI Editor for Messages User’s Guide, Version 200 F error messages header filters 111 client 169–175 headers, editing 90 metadata repository 168 hexadecimal editor 93, 100 server 176–178 hexadecimal messages 100–101 WebSphere MQ 179–194 Host (of queue manager) 50 Exit command 73 Expression editor 113 I idle time, server 35 F Ignore Message Formatting 93 field size, setting 35 Ignore message formatting option 67 fields in repeating groups 79 import utility 64 File menu 78 importing PQEdit format definitions 64 Filter definition 114 importing records to a Directory 153 filter names 117 filtering queue list 53 J by queue name 54 JMS connections by queue type 53 adding 50 filters 108–126 creating entries for 50 applying 111–112 deleting 51 for unformatted text 118 editing properties 51 naming conventions 117 viewing properties 51 samples 109 JMS messages sharing definitions 109 editing properties 93 finding message contents 79 JMSMD 115 format field 85 Format Structure box 115 K FORMAT.ini files, converting to message kxymsged.aud 72 format definitions 64 kxyruns.bat 40 Formats box 115 formatted messages creating 92–93 L editing 92–93 LDAP 146 Forward command 82 LDAP directory Forward Messages dialog 82 backing up the database 155, 158 forwarding messages 76, 78, 81–82 importing records 153 from dead letter queue 81 removing 162 seeding 153 H unconfiguring 161 LDAP server 22 header fields ldapadd command 155 JMS 90 ldapsearch command 159 WebSphere MQ 90 .ldf file extension 149
Index 197 M
LDIF format 149 message prolog, adding information to 95 Length field 118 Message window 70–76 Load command 74 editing commands in 73 loading messages 84 message display in 70 loading messages from a file 83 messages local queue managers browsing 76 deleting 51 copying 76 listing of 49 creating 88 local security policy, updating 39 cutting 76 logging in to server 43 deleting 76, 78 editing 89 M finding contents 79 main application window 46 formatted display 70 Maximum number of messages per display forwarding 76, 78, 81–82 option 67 from dead letter queue 81 MDR namespaces loading from a file 83, 84 :CandleInternal.MessageEditor 60 previewing 86 :CandleSamples.MessageEditor 60 printing 86 changing default 60 replacing content 80 message files, location of 83 sample 131 message filter definitions selecting storing 63 selecting messages 76 message filters 21 unformatted display 70 about 108 unloading to a file 83 message format definitions 58–64 unparsable 71 and namespaces 60 metadata repository 60 and queue names 61 MQMD 115 converting FORMAT.ini files 64 multiple byte character sets 37 description 58 distributing 63 N for non-XML (raw) messages 59 namespace for XML messages 59 default 36 in the MDR 60 namespaces referencing in message header 61 and message format definitions 60 storing 63 naming attribute 147 use of 22 No authentication option 38 Message Format Editor 58 message format, determining 60 O message header formats 115 Object Access Manager. 38 message headers objectClass attribute 146 referencing message formats definitions Open Message dialog 69 in 61 Open Queue dialog 56, 66, 111
198 PathWAI Editor for Messages User’s Guide, Version 200 P
Open read only option 69 Display header 66, 67 Operators palette 114 Display queue in logical order 69 Other Properties 51 Edit under syncpoint control 67 Ignore message formatting 67 Maximum number of message per P display 67 Paste command (in text editor) 93 reassemble segmented messages 69 PathWAI Editor description 18 opening 56, 66 PathWAI Editor server, see server opening options PDF files, adding annotations 15 open read only 69 pFormat tag 130 options 66–69 .pju extension 83 purging 56 .pmu extension 83 Port (of queue manager) 50 R PQEdit format definitions, importing 64 Reassemble segmented messages 69 previewing messages 86 referencing message format definitions 61 Print command 73, 86 Refresh command 73 Print dialog 86 remote queue managers Print Preview command 73, 86 deleting 51 printing messages 86 removing local Directory 161 printing problems 14 removing nodes Provider URL 51 in tree editor 93 purging queues 56 removing the LDAP directory 162 repeating groups 79, 108 Q Replace command 74 queue depth, changing 71 replacing message content 80 queue filters 21 resources, listing of 21 queue list retry filtering messages by queue name 53, 54 retry sending 81 by queue type 53 Retry DLQ Messages option 81 viewing 47 Retry option 82 Queue Manager Name 50 Rollback command 73, 78 queue name, filtering by 54 rolling back changes 72 Queue Type dialog 53 Row Filter dialog 108 queue type, filtering by 53 Row Filter editor 113 queues row filters creating 55 about 108 deleting 55 creating 113–119 maximum displayed 36 deleting 122 open queue options editing 120 Apply filters 66 Context 68
Index 199 S
S
200 PathWAI Editor for Messages User’s Guide, Version 200 V unconfiguring the LDAP directory XML Schema 97 server 161 XML Schemas 58 Undo command (in text editor) 93 XML tree editor 95, 98 unformatted messages creating 94–96 default field size 35 editing 94–96 setting field size 35 Unload All Messages option 83 Unload all messages option 84 Unload command 75 unloaded messages location of 83 unloading messages to a file 83 URLs, in LDAP 148 usage scenarios 24 User authentication 38 Using Forward command with dead letter queues 82 with the Filter command 82
V Variant Definitions dialog 132 Variant Definitions feature 109 variant format definitions about 109 creating 132 variant formats 128–137 creating 132 description 128 samples 130 sharing 128 sharing definitions 109
W WebSphere MQ message descriptor 68
X XML declaration 97 XML messages 97–98 XML naming conventions 97
Index 201 X
202 PathWAI Editor for Messages User’s Guide, Version 200 Glossary
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).
B program to communicate with a queue manager on a server system. backout count A count maintained by the underlying transport of the number code page An assignment of of times a message was received under displayable, printable characters and syncpoint but had to be reread because control codes to every possible binary the unit of work had to be backed out. combination of fields of a given size. In a one-byte (eight-bit) code page, there are Not all transports support the backout 256 possible binary values (called code count. points). In addition, there are seven-bit, Base64 encoding A format defined two-byte, and three-byte code pages. by standard RFC2045 for encoding commit “An operation that applies all binary data in text form; this allows the changes made during the current binary data to be included in XML unit of recovery or unit of work. After the messages. operation is complete, a new unit of recovery or unit of work begins. Contrast with backout.” [I] C connection In a JMS implementation, cardinality Indicates the number of a “connection encapsulates a virtual members in a set. In the definition of connection with a JMS provider”. A JMS message formats, cardinality indicates client uses the set of connection the number of permissible or required configuration parameters encapsulated occurrences of a field. An optional field by a connection factory to create a is defined by a minimum cardinality of 0. connection with a provider. channel See message channel. connection factory An administered object that encapsulates the set of class file A file containing Java object configuration parameter a JMS client code for a single Java class. uses to create a connection with a client connection The connection provider. used by a WebSphere MQ client
Glossary 203 conversion The process of changing a browser behavior within Web pages and message to conform to a different their elements. format. Examples include moving values With the Document Object Model core of fields in a message or combining interface, which includes XML support, several fields in one message format into programs can individually address any one field in another message format. XML element. The specification is also language-independent, built as it is upon CORBA’s Interface Definition Language D (IDL). destination “A JMS administered document type definition (DTD) A object that encapsulates the identity of a document that defines the tags in an JMS queue” [S] A destination is the XML message. DTDs have the object a client uses to specify the target advantage that they are both standard of messages it produces and the source and well understood. Compare to XML of messages it consumes. Schema. Directory Administrator A Java-based GUI application for DTD See document type definition. Windows systems that allows you to view and manage the configuration of the various elements that compose an E eBP network. These configurations are stored in an LDAP database or a external entity An XML entity such as configuration file. a document type definition (DTD) whose content is stored in a separate file, distinguished name (DN) The which may reside on a separate system. collection of attributes that form an entry’s unique symbolic name in the F directory. format See message format. Document Object Model (DOM) A programming interface specification developed by the Worldwide Web Consortium (W3C) that lets a H programmer create and modify XML hexadecimal A base-16 number documents as though they were program system. Hexadecimal encoding is a objects. With DOM, the programmer can convenient way to express binary specify how programs interact with numbers: One hexadecimal digit can documents, which encourages consistent represent the arrangement of four binary
204 PathWAI Editor for Messages User’s Guide, Version 200 digits. Two hexadecimal digits can X.500 directory standard written by the represent eight binary digits, or a byte. International Standards Organization (ISO). hexadecimal encoding A method for encoding binary data in text format in Candle supplies a version-2 LDAP which each byte is represented by two directory (CASP Directory Services) with hexadecimal digits. PathWAI Editor for Messages, which is managed by the Directory Administrator. I LDIF LDAP Data Interchange Format. A form of LDAP that stores all directory initial context “The starting point for information in a flat text file rather than a resolution of names for naming and random-access database. directory operations.” [S]
M J MDR See metadata repository. JMS Java Message Service. An application program interface (API) from message channel ““In distributed Sun Microsystems. The JMS API message queuing, a mechanism for provides Java programs with a common moving messages from one queue interface to standard messaging manager to another. A message channel protocols and to special messaging comprises two message channel agents services. (a sender at one end and a receiver at the other end) and a communication JMS provider “A messaging system link.” [I] that implements the Java Message Service as well as other administrative message format The structure of a and control functionality needed in a message or class of messages. This full-featured messaging product.” [S] 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 L field, and so on. The message format does not describe the data values in the LDAP Lightweight Directory Access message, but rather the structure of the Protocol. A subset of the X.500 directory message. standard first designed and implemented by the University of Michigan; currently Also, a record in the metadata repository at version 3. LDAP is based on the that defines a message’s format.
Glossary 205 message format definition aA Q description of the structure of a particular type or class of message. queue In messaging, a sequence of Message format definitions document messages waiting to be processed by the structure of the messages and either a sender or a receiver. In JMS provide a vehicle for describing the point-to-point messaging, a queue is the message formats to others. object (destination) a client uses to specify the target of messages it metadata Data about data. produces and the source of messages it Definitional data that provides consumes. In a WebSphere MQ information about other data managed messaging system, a queue is the object by an application. message queuing applications can put metadata definition A definition of messages on, and get messages from. A the structure and appearance of data. It queue is owned and maintained by a does not actually describe the data queue manager. values themselves. queue manager “A system program metadata repository (MDR) A that provides queuing services to hierarchially structured store of applications. It provides an application metadata—in this particular programming interface so that programs implementation, metadata that provides can access messages on the queues that information about message formats. the queue manager owns.” [I] The metadata repository can be stored raw message A message defined in a in an LDAP directory or in a format other than XML. configuration file. raw message format A message format defined in the metadata repository that is not an XML message P format. Raw message-format definitions pFormat tag The field in the message may indicate the structure of the overall header where PathWAI Editor records message format, the structure of the name of the format used to parse a subcomponents, the structure of message if it uses a format other than the individual fields, and how messages and one supplied in the Format field. Used fields are composed and understood. especially with variant formats. 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]
206 PathWAI Editor for Messages User’s Guide, Version 200 S X segmented message WebSphere MQ XML Extensible Markup Language. A messages that are too long for a queue data-description language derived from may be split into segments which are Standard Generalized Markup Language placed on the queue as separate (SGML). A tool for encoding messages messages. PathWAI Editor will so they describe their own fields. XML reassemble these segments into a single allows you to format a document as a message for display and editing if the data structure. As program objects, such Reassemble Segmented Messages documents can have their contents and option is selected when the queue is data hidden within the object, which opened. allows you to control who can manipulate the document and how. The XML standard aids in exchanging T data between applications and users. It was designed to be, among other things, transport A messaging middleware flexible, platform independent, and system (such as WebSphere MQ or understandable. WebLogic) used to carry a message. XML message format A message format that follows the W3C standard and is defined in the metadata repository U as an XML document. URI See Uniform Resource Identifier. XML namespace A tool for uniquely identifying XML tags in an XML Uniform Resource Identifier (URI) document so no name collisions can A means of identifying content located occur with other documents. on the internet. The most common form of URI is a web page address, a subtype XML Schema XML document that of URI known as a Uniform Resource describe valid XML messages in ways Locator (URL). that a document type definition (DTD) A URI typically comprises: cannot and that can therefore be referenced via the DOM (Document the mechanism used to access the resource (for example, http or ftp) Object Model) interface. In addition to supporting standard data types such as the computer on which the resource is located float and boolean, XML schemas let you define your own data types. Also, XML the name of the resource Schemas, unlike DTDs, support XML namespaces. (The metadata repository
Glossary 207 provides XML namespace support for DTDs.)
208 PathWAI Editor for Messages User’s Guide, Version 200