cressida cequest for websphere® mq - users' guide · 1 introduction welcome to cressida...

CeQuest™ for WebSphere MQ®

Users’ Guide

Version 1.1

March 9, 2005

Copyright © 2005 Cressida Technology Ltd, as an unpublished work. All rights reserved.

All company names, product names, and images in this document are trademarks and/or registered trademarks of, and/or copyrighted to their respective organizations, corporations, and associations.

The software described in this document may be used or copied only in the accordance with the terms of the software’s license agreement.

Cressida Technology contact information

Address Cressida Technology Ltd.

84A Meadrow, Suite 100

Godalming

Surrey GU7 3HT

UNITED KINGDOM

Telephone (+44) 1483-239300

Fax (+44) 1483-239383

e-mail [email protected]

The web site can be found at http://www.cressida.info

mailto:[email protected]

http://www.cressida.info

CeQuest Users’ Guide Version 1.1

Table of Contents

1 INTRODUCTION 1

1.1 Who this manual is for 2

1.2 How to use this manual 2

2 ARCHITECTURE 3

2.1 Security 4 2.1.1 CeQuest Administrator and Database Login 4 2.1.2 Controlling Access to Queue Sets 5 2.1.3 Controlling CeQuest Client Permissions 6 2.1.4 Adding User Defined Authentication 6 2.1.5 Security Configuration Checklist 7

2.2 Database Access 7

3 USER INTERFACE 8

3.1 Getting Started 8 3.1.1 Applying the Licensing Key and Seeding the Database 8

3.2 Graphical User Interface 9 3.2.1 Agents Tab 10 3.2.2 Queue Sets Tab 12 3.2.3 Filters Tab 13 3.2.4 Trace Tab 22 3.2.5 Database Tab 25 3.2.6 Admin Tab 26 3.2.7 Security Tab 27

3.3 Command Line Interface 29 3.3.1 Using the CLI 29 3.3.2 User Id and Password 29 3.3.3 Trace 29 3.3.4 Database Seeding 30 3.3.5 User Profile Management 30 3.3.6 Stopping the Agent 31 3.3.7 Getting Agent Information 31 3.3.8 Help 31

3.4 Starting and Stopping the Agent 31 NT Service 31 3.4.1 Stopping the Agent 32

4 EXIT AND AGENT CONFIGURATION 33

4.1 Agent Configuration 33

4.2 Defining the Exit to WebSphere MQ 33 4.2.1 Unix 33 4.2.2 Windows 34

4.3 Configuring the CeQuest Exit 36


4.4 Configuring WebSphere MQ 37

5 DATABASE CONTENT 39

6 ERROR MESSAGES 42


Page 1

1 Introduction

Welcome to Cressida CeQuest™ for WebSphere® MQ, our new addition to the Cressida Technology family of Message Tracking and Reporting solution offerings.

Cressida Introduced ReQuest™ for WebSphere® MQ in 2004. ReQuest provides reporting, tracking, replay and recovery capabilities based on the information in the WebSphere MQ (WMQ) recovery log files. The information in the log files includes changes to configuration items and puts and gets of persistent messages. Using ReQuest, application analysts and administrators are able to track a message across a WMQ network to see which servers it visited, exactly what the message did and how long it took to process and complete its intended unit of work. Although the message information is available as soon as it is written to a WMQ log, the collection and reporting of statistics is, by design, accomplished in a “post-processing” as opposed to “real-time” mode.

Our new solution, CeQuest™ for WebSphere® MQ, utilizes the WMQ Crossing Exit API facility to collect message related information, analyze the collected data in real time and provide real-time displays of user requested message tracking, auditing and diagnostic reports for both persistent and non-persistent messages. Additionally, users may optionally keep the collected information in a JDBC compliant database for later use.

CeQuest features and capabilities allow the user to:

1. Select and filter messages to be traced by queue and by message content (i.e. as ReQuest). CeQuest supports tracing of more than one set of queues at a time. The selection and filtering mechanisms are extremely powerful features:

a. filter on any field in the WMQ header or in the message data.

b. filter for strings using the comparisons:

i. string equals, string starts with, string ends with (and the negation of each of these).

ii. for numeric data, any of the six standard comparisons (=, ≠, >, ≥, < & ≤).

iii. combine operations by logical ANDs, logical ORs and logical NOTs.

2. Report on the progress of an application message/transaction across a WMQ network on several WMQ based platforms. This includes reporting on the message and any subsequent messages with the same message Id or correlation Id that are spawned as a result of the original message.

3. Generate reports that show the time at which each message is written to a single or set of queues and the time that the message was removed from the queue(s).

4. Develop automation scripts and functions via a Command Line Interface facility.

5. Track and report on both persistent and non-persistent messages.

6. Switch on and off ‘tracing’ as needed and display start and end times for each trace.

7. Report on the specified API call parameters and return code values.


Page 2

1.1 Who this manual is for

This manual is the reference for everyone that will implement or use any of CeQuest’s facilities. The user is assumed to be familiar with: • WebSphere MQ administration and programming concepts. • A Windows-style graphical user interface. • The concepts of the operating systems on which the software will run. • General familiarity with the WMQ Crossing Exit API facility.

1.2 How to use this manual

If you intend to install CeQuest, you should first read the “Installation Manual”.

Content of this reference manual:

Chapter 2 describes the architecture of CeQuest. It describes how CeQuest uses information provided by WebSphere MQ, how the different parts of CeQuest fit together, concepts and terminology used by CeQuest.

Chapter 3 describes the graphical and command line interfaces.

Chapter 4 describes how to configure CeQuest.

Chapters 1-4 will be enough for most users to begin working with CeQuest.

Chapter 5 describes database content.

Chapter 6 describes the error messages.


Page 3

2 Architecture

CeQuest consists of four parts:

1. A client. The client software provides the user interface and can be run on the same machine as an agent, or on a remote machine. If you want to use the graphical user interface then the client needs to run on a machine with graphics capabilities compatible with Java Swing – e.g. a Windows machine or a machine that supports X-Windows. There can be multiple clients in a network.

2. An MQ API exit. Every time your application calls MQ, MQ calls the exit (although, for many MQ calls, the exit does nothing but return immediately). The exit is told about the parameters that your application passes to MQ – for example, for an MQPUT call, the exit is given the message descriptor, the put options and the message. The exit is called twice – once before the put and once after the put. CeQuest only uses the call that is made after the put – the information passed to the exit includes the completion code and return values.

3. An agent. The agent software is responsible for communicating with the exits – there is one exit for each application using a queue manager. The agent and the exit communicate either through MQ queues or using sockets. You can configure which of these should be used. Typically there will be one agent for each machine with an MQ queue manager.

4. A data repository that holds configuration information used by the client. This repository can exist anywhere within your network. There can be multiple repositories across the network, although any specific CeQuest client is configured to use a single repository. This repository is a relational database accessible using JDBC. CeQuest definitions held in the repository can be modified using the CeQuest client GUI. The repository can be shared by multiple clients.

This is shown in the following diagram:


Page 4

Database

Client Client

AgentAgent

Application

Exit

Application

Exit

Application

Exit

Application

ExitSockets

2.1 Security

The main security concern is to prevent an unauthorised access to messages.

2.1.1 CeQuest Administrator and Database Login

Firstly, since most databases provide their own security mechanism, the CeQuest client login is linked with the database. CeQuest has the concept of an Administrator, one of whose jobs is to set up and manage access to this database. Cressida supply customers with a special Administrator password (actually a Customer Code and Password) when CeQuest is shipped. The Administrator supplies this password when they install the product, allowing them a number of privileges over and above those of a normal CeQuest user:

• The Administrator can create what we will call an authorised database. Ordinary users can create their own databases for use with CeQuest, but these will only support access to local queue managers. The authorised database supports access to remote queue managers too, but only an Administrator can modify the definitions held in the authorised database.

• The Administrator can grant or deny access to specified users.


Page 5

Cressida recommend that a single centralised JDBC-compliant data store is used, and that users are allocated passwords for access to this resource. The CeQuest client will only allow a user to submit requests if they can first login to the database. If desired, the username and password can be supplied when the CeQuest client is installed. Otherwise, the user will be prompted to supply these when they start the CeQuest client.

CeQuest uses the Java JAAS technology to manage the authentication process. This is a pluggable technology, allowing the possibility for CeQuest to be integrated with customer-specific security mechanisms.

2.1.2 Controlling Access to Queue Sets

As we’ll see, most CeQuest operations are based on the concept of a queue set. A queue set is a named collection of queues, each queue potentially belonging to a different queue manager on a different machine. Typically, a queue set is a set of queues used by a particular business application, so it is a good level at which to control access. Every time you try and do something with a queue set, CeQuest will check that your userid has appropriate permissions. However, so as not to make this too much of a burden it is also very easy to give a user full access to all queue sets if that is what is required.

Each user who wants to use CeQuest needs an access control profile. When the user attempts to do some operation, CeQuest checks that the user is allowed to do this operation on the queue set. The access control is defined by the user profile. The user profile can be defined through the CeQuest command line interface or using the security tab on the graphical user interface. Only users with system administrator privilege are allowed to create, delete or alter user profiles.

To set up the user profile through the command line interface, you need to use the –user option. If you are not the Administrator you will not be allowed to use this command. If you are using a local database, your user profile will not be checked (but remember that the local database will only support use of local queue managers).

In conjunction with –user, the Administrator uses –add (-a) to grant access to a list of queue sets, -remove (-r) to withdraw access, -clone (-c) to clone an existing user and –list (-l) to list the queue sets which a user has access to. In the examples which follow each command ends with the –l option to show the permissions which apply after the command has executed. The output from the –l option is shown in italics after each command.

// give rob access to queuesets qs1,qs2. Note there is no whitespace in the list of queue sets.

> cequest -user rob -a qs1,qs2 –l

rob can access queuesets: qs1, qs2

// withdraw access to queuesets qs1,qs2,qs3.

> cequest -user rob -r qs1,qs2,qs3 –l

rob can access no queuesets

// give rob access to everything except qs1,qs2. Note the use of the keyword _ALL_

> cequest -user rob -a _ALL_ -r qs1,qs2 -l

rob can access any queueset except: qs1,qs2,qs3

// Disallow rob access from all queue sets.

> cequest -user rob -r _ALL_ -l


Page 6

rob can access no queuesets

// give rob access to qs1,qs2

> cequest -user rob -a qs1,qs2 -l

rob can access queuesets: qs1,qs2

// create a new user tim with the same priviliges as rob.

> cequest -user tim -clone rob -l

tim can access queuesets: qs1,qs2

2.1.3 Controlling CeQuest Client Permissions

The CeQuest client software runs under a Java security manager, allowing the exact permissions for the application to be specified in a security configuration file. For instance, a particular installation could restrict the directory or directories to which files can be written.

Cressida supplies an appropriate default properties file in the config directory (the file is called CeQuest_java2.policy). By default, this file will grant all permissions to the CeQuest client. If you wish to define specific permissions you should remove or comment out the first grant statement in this file and then modify the subsequent grant statements to set the specific permissions which you want. (Note that the path names in this file may need to be changed to reflect your specific installation details.)

2.1.4 Adding User Defined Authentication

This section is only of interest if you wish to add additional user-defined authentication checks.

The user can add their own authentication checks as follows:

1. Develop or otherwise acquire one or more classes which extend LoginModule. (A simple example called UserLoginModule is provided in the samples directory).

2. Edit the CeQuest_login.config file in the config directory to add your new loginmodule(s) to the MQLA stanza. For instance:

MQLA { user.UserLoginModule required; info.cressida.mqla.MqlaLoginModule required; };

3. Edit the script which starts CeQuest (cequest.bat on Windows or cequest on Unix) to add the directory or JAR file containing your LoginModule package to the classpath. The easiest way is to edit the definition of the CP variable and add your own directory or JAR file to the end of this definition.

Refer to java.sun.com for more information on JAAS.

Notes:

• You must leave MqlaLoginModule as a required entry in the configuration file. (As well as checking the username and password it actually connects to JDBC.)

• You can use the JAAS callback supplied by CeQuest to ask for a username and password, but note that if these were supplied at install time then these values will be returned and the user will not be prompted for different values.


Page 7

2.1.5 Security Configuration Checklist

This example describes the relevant security steps as the Administrator installs CeQuest and then sets up access for a user rob.

1. The Administrator checks that a suitable JDBC-compliant database is available and creates one if necessary. During installation the installer will prompt for some database-specific information. Please refer to the Install Guide for pre-install checks. The Administrator needs to set up at least one database userid for their own use.

2. During installation the Administrator supplies the customer code and Administrator password sent from Cressida.

3. The Administrator seeds the database using the cequest –seed command as described in the Installation Guide. Because this is done with Administrator privilege, the database automatically becomes an authorised database.

4. The Administrator identifies all the servers running MQ queue managers which are to be managed by CeQuest and installs the CeQuest agent on each.

5. The Administrator adds CeQuest agent definitions for each server. Queue set definitions will usually be added over time as business needs arise. However the Administrator should initially set up at least one queue set definition for test purposes, supplying at least one known queue manager and queue name.

6. The Administrator asks the user how they normally login to the various servers. In this case the user rob uses the userid rob on each server except for test.server1, where he has the login robert. The WebSphere MQ OAM is configured to manage access on each system. The Administrator creates a dummy account rob on test.server1 and sets up the OAM for test.server1 queue managers to manage rob exactly as it did for the login robert.

7. The Administrator creates a database login of rob with a password and supplies these to the user before they install the CeQuest client.

8. The Administrator sets up a user profile for rob using the command: cequest –user rob –a _ALL_ –r corporate.finance –l

9. When user rob installs the CeQuest client he can either supply the database userid and password during installation (in which case the password will be cached in an encrypted cookie), or he can opt to be prompted for userid and password every time he starts up the CeQuest client.

2.2 Database Access

CeQuest needs to keep configuration information and uses a JDBC-compliant repository (typically a relational database) for this purpose. CeQuest also records trace information in this database.

Cressida does not supply a repository with CeQuest, but any JDBC-compliant database within your organisation may be used.

Cressida recommends that you use a central database as this means that your configuration can be shared by any system running a CeQuest client.

See the CeQuest Installation Guide for details of the JDBC related seed information required at install time.


Page 8

3 User Interface

There are two user interfaces – a graphical interface and a command line interface. You will find it convenient to use the graphical interface to maintain the CeQuest configuration. (The command line interface does not support modifications to this configuration.)

3.1 Getting Started

Before using CeQuest to get trace queues, you have to:

1. Tell CeQuest about each computer in your network that you’re interested in. You do this by defining a number of agents. Cressida recommends that you should define an agent for every machine running WebSphere MQ.

2. Define to CeQuest which queue manager and queues need to be included in an operation. You do this by adding a number of queue sets. When you use CeQuest to get a trace, you specify the queues to be included in the trace using a queue set. The idea here is that a business problem is generally related to a specific application. Since there is no reliable way to automatically detect which WebSphere MQ queues are relevant to a specific application, CeQuest lets the user specify the set of queues which are of interest to an application. You can use wildcard characters to include multiple queues with similar names.

3. If you wish to be more selective about which messages you examine, you can define a filter to narrow the focus of the trace.

3.1.1 Applying the Licensing Key and Seeding the Database

If you have installed CeQuest from the Installation Guide, you will probably have already applied your license key and seeded the database. If this is the case, please ignore the rest of this section.

If you obtained CeQuest for evaluation, you should have received a time-limited license key from Cressida. When you purchase the product you will receive a different (full) license key.

The procedure for applying the license key is the same in each case, and you must apply the key before you can carry out any CeQuest operations (including seeding the database as described in the next section).

Run the keyinstall program, either directly from the CeQuest home directory or (on Windows) via the Start menu.

If you start the keyinstall program with no command line arguments you will get a GUI prompt where you can paste your key into the field provided. Simply click on Apply to apply the license key and then close the application.

Alternatively (from the command line) you can supply a file name parameter. The keyinstall program will then try to open the file you specified and read the license key from the first line of the file. This could be useful if the license key was mailed to you as a file attachment.

NOTE: you must run keyinstall separately for each installation of CeQuest.

If CeQuest still refuses to start, please contact Cressida with the faulty license key.

Once the license key has been successfully applied you can seed the database using the command line (section 3.2), supplying the seed file Catalog.xml. Alternatively on Windows you can always run the Seed command from the Start menu.


Page 9

3.2 Graphical User Interface

The graphical interface consists of a number of tabs:

• Trace – use this to trace messages to screen or to the database.

• Database – use this to view traces in the database and to delete trace information from the database.

• Agents – use this to define the computers in your WebSphere MQ network.

• Queue Sets – use this to define the queues that you’re interested in. Typically a set of queues is related to a specific user application.

• Filters – use this to narrow the focus on reports, replays and recovery.

• Admin – use this to do administration activities (rarely used).

In addition, the graphical interface also includes a status bar which can show:

• A description of which database is being used.

• Any error message associated with the current operation.

• A green/red indicator which tells you whether the last operation was successful or failed.


Page 10

3.2.1 Agents Tab

You will need an agent installed on each computer on where you wish to trace WebSphere MQ messages. This tab lets you define both the agent and the machine. You need to define each computer that you need to access through CeQuest here. This tab includes a list of computer names, a TCP/IP address and a description for each computer. CeQuest does not use the description. The computer name is the name defined to the domain name server.

The Add button allows you to create a new entry in the list. You need to define every CeQuest agent that is running in your network – and you should run an agent on each machine running a WebSphere MQ queue manager.

The Delete button removes selected item(s) from the list. (Click on the item(s) in the list that you wish to change.) You cannot delete agents until all queue sets that refer to the agent have themselves been deleted.


Page 11

The Change button allows you to modify selected item(s).

When you select Add or Change, CeQuest presents a dialog for you to complete. The form allows you to select:

1. The agent name.

2. The TCP/IP address of the machine on which the agent runs. When you ask for a trace, CeQuest communicates with the agent software on the selected machine. It tries to connect to this machine using the TCP/IP address if one was supplied, but otherwise – and more typically – using the DNS name.

3. The port number; this is the port number that the agent is listening on. It defaults to 2498.

4. The machine power field is not currently used by CeQuest.

5. An optional description that might assist you when editing agents.

6. The number of days after a queue is deleted that the definition for that queue should be removed from the database. If you set this to “-1” (which is the default) then queues will never get deleted from the database.


Page 12

3.2.2 Queue Sets Tab

A Queue Set definition groups together a number of queues or other WebSphere MQ objects. You use this tab to define the objects to be included in a trace. The tab includes the following:

1. The Queue Set Name. You can select an existing Queue Set from a drop down list.

2. An Add, Copy and Delete button relating to the Queue Set. Use the Add and Copy buttons to create new Queue Sets, and the Delete button to remove the highlighted Queue Set.

When you select Add, CeQuest displays a dialog that allows you to enter the name of the new Queue Set.


Page 13

3. A list of the queues that are included in the Queue Set – each entry in the list consists of the Agent Name, the queue manager name and the queue name. The queue name may include asterisk (*) characters. The “*” matches zero or more characters.

4. An Add button which allows you to create a new item in the Queue Set.

5. A Delete button removes selected item(s) from the Queue Set.

6. A Change button that allows you to modify the definition of an item in the Queue Set.

When you select Add or Change, CeQuest displays a dialog for you to enter the Queue Set information – the Agent name, the queue manager name and the queue or object name. You can either use the drop-down boxes to select an entry that CeQuest knows about already or enter you own value.

3.2.3 Filters Tab

The Filters tab allows you to select a subset of the messages to include in traces. (You also specify a queue set when tracing; only activity on queues in that queue set is selected, and filtering is then applied to further restrict the selection.)


Page 14

The tab includes the following:

1. The Filter Name. You can select an existing filter from a drop down list. .

2. A New button – use this to create a new Filter.

3. A Mod button – use this to modify the definition of the selected Filter.

4. A Del button – use this to remove the selected Filter.

5. The remainder of the screen is read-only and shows the attributes of the selected Filter.

When you select New or Mod, CeQuest displays a dialog (the Filter Definition dialog) that allows you to define the filter attributes.


Page 15

Defining a Filter

CeQuest users can define filters to select messages satisfying various criteria. The filter is an expression comprising a number of constraints which are then combined using logical grouping operators such as AllOf. An individual constraint is simply a test against a field in the MQ message header (the MQMD structure) or against the MQ message data itself. The top panel of the Filter Definition dialog is concerned with defining constraints.

The filter itself is displayed as a tree structure in the bottom panel of the Filter Definition dialog. The filter name is displayed as the root of the tree. The individual constraints form the leaves of the tree and are grouped together using the AllOf, AnyOf and Not operators.

The tree can be “read” top-down, so the meaning of the example shown above is select messages whose message data starts with the string “MEGABANK-PLC” and which either have an MQ message type of 2 or an MQ feedback value of 7. Presumably whoever defined this filter believed that this combination would isolate the particular message(s) they are interested in.

The easiest way to understand filter definitions is to build an example from scratch. The actions to take are in bold. As described earlier, you can select either New or Mod on the filter tab:

• select New and you'll get a new (empty) filter definition called New, which you would typically "save as" a different name.

• select Mod and you'll get the currently selected filter. You can either save under the same name, or save under a different name.

Select New. This will display the Filter Definition dialog with an empty filter called New.

Now set up a constraint to add to the new filter.

• Select Message Format in the field drop-down list (top left of the dialog) • Select ^^ in the operator list (adjacent to the field drop-down list) • Type ABCD in the value field (the wide text box below the field drop-down list)

You need to press Enter after the ABCD (so that CeQuest knows you have finished entering data). You should see the following in the area labelled Resulting Constraint:

MessageFormat ^^ ABCD

You can now drag this constraint onto the tree using the mouse and drop it onto a node. The first node you drop onto the tree will sit immediately below the root node. Subsequent nodes will be incorporated at the location they are dropped either (by default) using an AnyOf operation (a logical OR), or (if you hold down the CTRL key - the mouse cursor shows a + sign) using an AllOf node (a logical AND).

You should see the following display.


Page 16

Now select the field MessageType in the constraint editor, select the operator == and type the value 2 into the value field. Hold down the CTRL key and drag the resulting constraint onto the “MessageFormat ^^ <ABCD>” constraint in the tree display.

You should now see the following display, which means that you want to select messages which have message type 2 and a message format which starts with ABCD.

The left-hand buttons (red and blue) above the tree diagram offer an alternative to drag and drop. (There is no drag-and-drop equivalent for the other buttons.) You highlight the node in the expression where you want to incorporate the new constraint and then click the appropriate button.

The buttons are defined as follows (from left to right):

combine the new constraint with the selected node using the AllOf operator combine the new constraint with the selected node using the AllOf operator negate the selected operator node

delete the selected node. All nodes below this node are also deleted. undo the previous editing operation (if there was one) – e.g. “un-add” a node redo the previous editing operation (if there was one) which was “undone”


Page 17

Buttons are automatically disabled if they are inapplicable at a particular time.

Try selecting the AllOf node in your example filter definition by clicking on it. The “negate” button should highlighted. Click on the negate button and you should see the following display which means that you want to select all messages except those which have message type 2 and a message format which starts with ABCD.

If you are creating a new filter, the “Save As” field will show a default name. You will usually want to edit this field to give your new filter a unique name. When you’re happy with the filter definition, click OK to save the filter under the specified name. Save your new filter with the name myFilter.

If you are modifying an existing filter, the “Save As” field will show the name of that filter. You can still change this if you wish – for instance to create a variant of an existing filter.

The table below shows each control in the constraint panel and explains its use.

Control Use

Select the name of the message field which you want to perform a test against. The other controls will be set up appropriately when a field is selected. The fields are described in detail below.

Select the comparison operator you want to use (see table below). Only operators relevant to the selected field will be offered in this drop-down list.

If this button is enabled for your field, you can use it to select from a number of predefined constants for this field.

Char means data is entered using keyboard characters. However, sometimes you will want to enter data as hex or octal. You can also mix-in Unicode escape sequences if you check the Unicode box. This is described further in the next section.

For character fields you may want to specify an offset in the data at which to perform the comparison. The first character in the data has an Offset of 0.

The comparison operators available to you depend upon on the actual field selected, but will be some subset of the following:


Page 18

Operator Meaning == Character, byte array or integer field is equal to filter data. An offset may be

applied to a character or byte field. With == (and !=) may be used with an empty data definition to signify a zero-length message. The syntax reflects standard C and Java usage.

!= Character, byte or integer field is not equal to filter data. An offset may be applied to a character or byte field.

^^ Character or byte field starts with filter data. An offset may be applied to the field. The syntax is loosely based on regular expression usage where ^ means start-of.

!^ Character or byte field does not start with filter data. An offset may be applied to the field.

$$ Character or byte field ends with filter data. No offset may be applied to the field. The syntax is loosely based on regular expression usage where $ means end-of.

!$ Character or byte field does not end with filter data. No offset may be applied to the field.

/x/ Character or byte data includes filter data. No offset may be applied to the field. The syntax is loosely based on regular expression usage where /x/ means “match x”. This is a potentially expensive operation.

> Integer field must be greater than the filter data. >= Integer field must be greater than or equal to the filter data. < Integer field must be less than the filter data. <= Integer field must be less than or equal to the filter data. Examples

Consider the string field: 123abcdef

The following filter expressions would match:

StringField ^^ 123

StringField ^^ abc at offset 3

StringField == abcdef at offset 3

StringField != 123abc

StringField $$ def

StringField !$ cde

StringField /x/ bcd

Whilst these would not match:

StringField == abc at offset 3

StringField != 123abcdef

StringField $$ cde

Note that all MQMD character fields are fixed length and are space padded on the right unless the full number of characters was provided. CeQuest interprets the first space in an MQMD field as marking the end of the field.


Page 19

More on Data Types and Conversion

CeQuest attempts to make it as easy as possible to define filters, but the potential variety of encodings used in WebSphere MQ messages sometimes means that you will need to give CeQuest some additional information about the message.

This section gives a brief overview of the encoding strategies used in typical WebSphere MQ applications and explains what this means to CeQuest.

Data Entry

Typically you would expect to be able to enter character data such as “MEGABANK” at the keyboard and have CeQuest locate this data in the MQ message. Indeed, this is often sufficient and is the default for genuine character fields. However it is important to understand that the keyboard data you enter will be interpreted in the codeset for your local machine and that it may need to be converted to match the codeset used in the MQ message. This is explained in the sections which follow, but for now we just want to explain the other options for data entry.

If you are mainly entering standard characters, but need recourse to occasional Unicode characters you can check the Unicode checkbox and then intersperse the special characters using standard Java-style Unicode escape sequence.

e.g. Union Monétaire could be entered as “Union Mon\u00E9taire”.

Some fields such as MsgId, CorrelId, and Accounting Token are essentially fixed-length binary data and will not be subject to conversion. Some applications may put character data into these fields, but if the message is being exchanged between ASCII and EBCDIC platforms (for instance), it is the responsibility of the application (or a user exit) to convert these fields explicitly. If you use such fields in a CeQuest filter definition you will have to enter them in hex or octal. You may also choose to use hex or octal for other character fields, including message data.

You do this by selecting the Hex or Octal radio button and entering the data as colon-delimited hex or octal “characters”. Message data may contain Unicode characters, so you are allowed up to 4 hex digits (6 octal digits, up to 177777) for message data, but only 2 hex digits (3 octal digits, up to 377) for other fields.

For example. Union Monétaire could be entered in hex as: 55:6e:69:6f:6e:20:4d:4f:6e:e9 etc or in octal as 125:157:156:145 etc. If less than the allowed number of digits is supplied for each “character”, these are assumed to represent the “least significant” bits.

Message Fields and Message Data

As mentioned, there are two types of character data which a CeQuest filter may specify in a constraint. The message data (also known as user data) and header fields (character fields in the MQMD message header).

If you take a look at the bottom panel of the Filter Tab or Filter Definition dialog you will see a set of conversion options for each of these types. The options are as follows:

Option Description Use CCSID CeQuest will look at the CCSID in each message and translate the filter

data to this codeset before comparison. This is usually the right thing to do for MQMD fields


Page 20

No Translation CeQuest will not attempt any conversion and will use the byte values it has directly in the comparison. This is usually the right thing to do if you defined the data as hexadecimal or octal.

Use Codeset CeQuest will translate the filter data to the specified codeset before comparison. This is usually the right thing to do for message data because CeQuest can’t assume that the CCSID in the message reflects the codeset used for the message data.

Character header fields will always be converted by MQ to the codeset of the receiving queue manager. By default, the CCSID field holds the value of this codeset although there is nothing to stop an application from overwriting this value. It is however a reasonable assumption that CeQuest can check the CCSID value and convert the filter data accordingly.

Message data may be character data, binary data or a mixture of both. A common WebSphere MQ recommendation is that the message payload should be exclusively character data and that it should be converted on the final MQGET. This has two main advantages:

• it allows WebSphere MQ to convert the data automatically • it avoids unnecessary conversion costs at intermediate queue managers

You have 3 choices for dealing with comparisons against message data.

1. Tell CeQuest which codeset the message data is held in. This allows CeQuest to automatically convert the filter data correctly before doing its comparison.

2. Tell CeQuest to get the codeset from the CCSID. This appears easier, and may be good enough if you know that all your queue managers use the same codeset and that the message data wasn’t explicitly encoded in a different codeset. Also note that the situation might change if a queue manager is moved to a different platform.

3. Tell CeQuest to do no translation. If you know what the byte values in the message are, this is fine. It is also the only reasonable way to handle binary or mixed data.

Field Definitions

MessageData A character field. CeQuest only searches the first 1000 characters in the message for a match.

Report An integer field. MessageType An integer field. Expiry An integer field. Feedback An integer field. Encoding An integer field. CCSID An integer field. MessageFormat A character field. Priority An integer field. Persistence An integer field. MessageId A binary field. CorrelationId A binary field. ReplyToQ A character field. ReplyToQM A character field. UserId A character field. Accounting A binary field. AppId A character field. PutApplType An integer field.


Page 21

PutApplName A character field. By default, MQ stores the last 28 characters of the full pathname - your application can override this default. CeQuest will look for your string within these 28 characters. The “ends-with” operator $$ is particularly applicable to this field.

PutDate A character field. CeQuest does not make any assumptions about the format for the data in this field.

PutTime A character field. CeQuest does not make any assumptions about the format for the data in this field.

AppOrigin A character field. GroupId A binary field. MsgSeqNbr An integer field. Offset An integer field. OriginalLength An integer field.

Searching on Message Data

The following search mechanisms are provided for the message data:

1. Starts with (^^), possibly with an offset. Use this if you know that your message has a particular text string in a known position.

2. Doesn’t start with (!^), possibly with an offset.

3. Equals (==). This is only useful if you the entire format of the message, and if the message is short.

4. Not equals (!=).

5. Ends with ($$).

6. Doesn’t end with (!$).

7. Contains (/x/). This is a very expensive operation for message data as CeQuest has to check to see if the string matches at every byte position in the message. To limit the search, CeQuest only searches for the string starting at the specified offset and ending at character 1000 in the message. The scope of the search can be further restricted from by editing the scanLength field in the CeQuest.xml configuration file.

It is recommended that all other mechanisms to isolate the message should be tried before resorting to this operation.


Page 22

3.2.4 Trace Tab

You can use this tab to create new traces. When you create a new trace, you have the option of either displaying the trace information on the screen or writing it to the database or both. You can also choose which information to display or store.

The tab contains the following:

1. The queue set name, which defines which queues need to be traced.

2. The filer to apply to the trace (if any). You can choose to trace all messages put and got from the queue, or to only trace those that match a specified filter.

3. Where you want to send your trace to – to the screen, the database or both.


Page 23

4. Which fields you want to trace. You can select to trace each field in the MQMD independently, and other information such as:

i) the queue name; ii) the queue manager name iii) time; iv) the operation (i.e. put, get, commit or rollback); v) the process if of the application accessing the queue; vi) whether or not the operation is transactional; vii) whether or not the message is browsed (for gets only); viiii) the completion code; ix) the return value; x) the resolved queue name. If your application uses a model queue or an alias

queue, this is the name of the queue that is actually used. 5. The amount of user data to include in the trace. The maximum amount that you can

include in the trace is 1000 characters.

6. How to display user data. You can choose to display the user data as a sequence of hexadecimal characters, or as a character stream based on the CCSID in the MQMD, or as a character stream based on a CCSID that you supply.

7. Whether or not to include failed operations.

8. Poll period. The rate at which the client will ask for more information from the agent. If the agent is not asked for information frequently enough, the agent may lose tracing information.

9. The submit button. This activates the trace. Once you have started the trace,

CeQuest displays a pop up with trace information. The content of the pop up depends upon whether or not you have requested a trace to screen.

Trace to Screen

If you have requested a trace to screen, the pop up contains a column for every field that you have requested in the trace. Up to 100 events can be displayed in a scrolling region. When the 101st event is displayed, CeQuest deletes the oldest one. Events are displayed with the newest event at the top of the list. Events scroll down the screen as they age.


Page 24

You can adjust the width of any column by pulling the header.

The pop up has the following buttons:

1. Stop. This stops the current trace operation. Stopping the trace does not close down the window – it enabled the start and close buttons.

2. Start. This is disabled unless the trace is stopped. It restarts the current trace. Note that when a trace is stopped, no trace information is collected.

3. Close. This closes the window. It is only enabled when tracing has been stopped.

Trace to Database

If you have not requested a trace to the screen, CeQuest displays a summary table showing how many puts, gets, commit and rollbacks have been added to the database for this trace.


Page 25

The pop up has the following buttons:

1. Stop. This stops the current trace operation. Stopping the trace does not close down the window – it enabled the start and close buttons.

2. Start. This is disabled unless the trace is stopped. It restarts the current trace. Note that when a trace is stopped, no trace information is collected.

3. Close. This closes the window. It is only enabled when tracing has been stopped.

3.2.5 Database Tab

You use this tab to look at any trace information that has been stored in the database and to remove unwanted information from the database.


Page 26

This tab contains the following objects:

1. A list of trace operations that are currently in the database. This is only refreshed when the client is started, and when using the delete, purge and refresh buttons. The list contains:

i) The trace name; ii) The queue set that was traced; iii) The number of records for the trace; iv) The date and time of the first record for the trace; v) The date and time of the last record for the trace.

2. The age of trace information for purges. This is used in conjunction with the purge

button. It is specified as a combination of days and hours. So, it’s possible to purge trace information that is more than 3 days old, or more than 8 hours old, or more than 1 day and 12 hours old for example.

3. The format to display user data. This is used in conjunction with the display button. The choices are hexadecimal display, using the codeset in the message descriptor, or using a specified codeset.

4. A display button. This displays the highlighted trace as a pop up.

5. A refresh button. You use this to refresh the list of traces currently held in the database.

6. A delete button. This deletes the highlighted trace from the database.

7. A purge button. This deletes all traces that are older than the specified age from the database.

3.2.6 Admin Tab

This tab allows you access to less frequently used operations.


Page 27

There is only option:

1. Get version information about the agent.

3.2.7 Security Tab

You can use this to give users access to queue sets and CeQuest functionality. To be able to log on to CeQuest, the user has to be defined in the database. You also have to define the user’s capabilities in CeQuest using the Security Tab or through the command line.


Page 28

The panel has the following elements:

1. The user name.

2. Buttons to add, delete and clone (copy) users. If you select add or clone, CeQuest displays a pop-up to allow you to enter the name of the new user.

3. A list of queue sets that the user has access to, and buttons to add and remove entries from this list.

4. A list of queue sets that the user does not have access to, and buttons to add and remove entries from this list.

Entries in either list may have wildcards. The text “_ALL_” is the same as “*”, meaning all queue sets. A user has access to a queue set if it is in the includes list, but not in the excludes list.


Page 29

5. A list of operations that the user is allowed to perform on the queue sets to which the user has access.

3.3 Command Line Interface

The command line interface allows you to trace messages and direct the output to the database. If you use the command line interface, all fields are copied to the database – that is, you can’t select to record only a subset of fields.

The command line interface is somewhat hierarchical in that there are a number of top-level options, each of which may require further qualification by other subsidiary options.

We first describe some of the general building blocks of the command-line specification and then show how these relate to the main options.

3.3.1 Using the CLI

The CLI allows the user to invoke CeQuest from a command line or script. The basic command is cequest, with the appropriate options described below. This command is a Windows batch file or Unix shell script and can be found in the CeQuest installation directory.

3.3.2 User Id and Password

The CLI allows the user Id and password to be input from the command line if it is needed. The user id and/ or password can be automatically passed into CeQuest if this is selected at install time. If the user id or password is not known, then you can enter it on the command line. If you don’t enter it on the command line, then CeQuest will prompt you.

You specify the user id and password using the following options:

–userId <user Id> –id <user Id>

–passsword <password> –pw <password>

3.3.3 Trace

The options to generate a trace are:

-trace <trace name> mandatory Specifies the name of the trace – this is recorded in the database if the trace is directed to the database.

-queueSet (qset) <queue set>

mandatory Specifies the name of the queue set to be traced.

-filter (flt) <filter> optional This is the name of the filter that should apply to limit which messages should appear in the trace.

-maxMsgLen (mml) <max message size>

optional Specifies the maximum amount of user data to be written to the database. The maximum value of this field is 1000 – that is, no more than 1000 bytes of user data will be stored in the database.

-includeFailures (fail) optional If selected, CeQuest will record failed I/O operations (puts, gets, commits and rollbacks) in the trace report.


Page 30

-duration <duration> mandatory The duration that you want to trace the queues for. The maximum duration is 23 hours, 59 minutes and 59 seconds. The format is any of the following: i) the number of seconds. ii) the number of minutes and seconds, each

value being separated by a “:” character. iii) the number of hours, minutes and

seconds, each value being separated by a “:” character.

-pollFrequency <poll rate>

optional The rate at which the client will ask for more information from the agent. If the agent is not asked for information frequently enough, the agent may lose tracing information. The poll rate is in seconds and the default value is 1 second.

3.3.4 Database Seeding

The seeding process adds tables and data to the CeQuest database. Normally this is done only once during initial installation of CeQuest.

The options to seed the database are:

-seedDatabase <file> mandatory Seeds the database, using the specified XML configuration file as the source.

-dropDatabase Drop all the database tables used by CeQuest. When you seed the database, the user issuing the command gets given access to all queue sets.

3.3.5 User Profile Management

The CeQuest Administrator can add or remove queue sets from a user profile to control the users’ access to resources. An ordinary user can ask to see which queue sets can be accessed. See 2.1.2 for examples.

The options to update the user profile are:

-user <username> mandatory Specifies the user profile which is to be updated -add <queueset list> Grant access to the listed queue-sets. The special

value _ALL_ means grant access to all queue-sets. Wildcard “*” characters are permitted. The <qset-list> should be a comma-delimited list of existing queue set names, with no white space in the list.

-remove <queueset list>

Withdraw access to the listed queue-sets. The special value _ALL_ means override any previous restrictions which were imposed. Wildcard “*” characters are permitted.

-clone <existing user> Set up the profile for the user specified with –user to be identical to the profile for this existing user.

-list List the queue set access for the specified user. If this is combined with one or more of the modifying flags above, then it shows the result after the modifications have been applied.


Page 31

-perms <perms> A comma separated list defining the permission that the user has when accessing the queue set. The options are listed in the following table.

Users have access to a queue set if it is in the “includes” list and is not in the “excludes” list.

Permissions

StopAgnt or 7 Allows the user to stop the agent using the –stop CLI option. DBA or 8 Gives the user full administration access. Trace or 9 Allows the user to trace a queue or queues. Display or 10 Allows the user to display information held in the database. Maintain or 11 Allows the user to delete or purge information from the database.

Note that this option will allow the user to remove any trace information held in the database.

3.3.6 Stopping the Agent

-stop


mandatory This will stop all agents referenced by the queue set.

3.3.7 Getting Agent Information

-about


mandatory This will display the version and build date for each agent referenced by the queue set.

3.3.8 Help

This option displays the list of options:

-help

3.4 Starting and Stopping the Agent

So far we’ve only described the CeQuest client. The user must also arrange for a suitable CeQuest agent to be running on each machine where they wish to run a CeQuest operation.

On any platform the agent can be started from the command line, using the command cequestAgent. On Unix machines it may be convenient to have this started automatically as part of the system startup. On Windows platforms, the agent can be started as a service as described below or by clicking the Start CeQuest Agent in the Start menu.

NT Service

If you wish to test the operation of the agent without actually installing it as a service, use the command:

cequestAgent –testService


Page 32

This should start the agent in the same way as a service. Use Control-C (^C) to simulate a service stop CeQuest.

Typically though you would just use the following command to install the CeQuest agent as an NT service:

cequestAgent –installService

The name of the service is CeQuest and it is displayed as “Cressida CeQuest” in the Services dialog under the Windows Control Panel (accessed via Control Panel/Administrative Tools under Windows 2000). The service is installed for Manual startup, but you can change this to start automatically if you wish.

You can now start the service, either via the Services window or using the command:

net start CeQuest

after which you should see:

The Cressida CeQuest service is starting.

The Cressida CeQuest service was started successfully.

Similarly you can stop the service via the Services windows or using the command:

net stop CeQuest

If necessary you can remove the service using this command:

cequestAgent –removeService

3.4.1 Stopping the Agent

You can stop the CeQuest agent using the CeQuest client’s command line. Use the –stop option.


Page 33

4 Exit and Agent Configuration

The CeQuest exit and the CeQuest agent communicate with other using either sockets or MQ queues. Only one of these can be used by the agent. This chapter tells you how to:

1. Configure the CeQuest agent;

2. Tell WebSphere MQ to call the CeQuest exit;

3. Configure the CeQuest exit;

4. Configure WebSphere MQ.

4.1 Agent Configuration

The agent configuration determines whether WebSphere MQ or sockets is used to communicate between the agent and the exits. These parameters are passed to the agent at start up. The complete set of configurable items is:

-Dcressida.tequest.QMgrName=<queue manager> This defines the queue manager for the agent’s input queue when the agent and exit communicate using WebSphere MQ. You must also define the queue name, and you cannot also define the port number.

-Dcressida.tequest.AgentQName=<queue name> This defines the agent’s input queue when the agent and exit communicate using WebSphere MQ. You must also define the queue manager name, and you cannot also define the port number.

-Dcressida.tequest.portNumber=<port number> This defines the port number used to communicate with the exits. You cannot define this and the queue manager or queue names.

-Dcressida.tequest.localFileLocation=<local file location> This defines the directory where CeQuest can create local files.

-Dcressida.tequest.impliedStopTime=<timeout> If, when a trace is in progress, the client does not send the agent a message to get more trace information after this time, the agent will terminate the trace. The time is in seconds and defaults to 30 seconds.

-Dcressida.request.rmiPortNumber=<port Number> Defines the port number that the CeQuest client uses to send messages to the CeQuest agent. The default is 1099. You will need to change this if you want to have multiple agents on a machine.

4.2 Defining the Exit to WebSphere MQ

Before you can use CeQuest, you have to make the CeQuest exit known to WebSphere MQ. This is described in the WebSphere MQ document “WebSphere MQ System Administration Guide”. For Unix this means editing the mq.ini file for the queue manager. For Windows, you use the WebSphere MQ Services snap in.

4.2.1 Unix

You need to define the exit in the mq.ini file. The stanza name is ApiExitLocal. The attributes that you need to define are:


Page 34

Sequence=<sequence number> Function=EntryPoint Module=<Module> Name=<exit name> Data=<configuration file>

• <sequence number> can be anything that you like. If you have multiple exits, this

value determines the order that the exits are called. The CeQuest exit can be called at any point – it makes no changes to any data structure before returning. Cressida recommends that the CeQuest exit is the last one called.

• <exit name> can be anything you like, for clarity Cressida advices "CeQuest".

• <module> is the full pathname of the CeQuest exit. This will depend upon where you installed CeQuest on your system.

• <configuration file> is the full path name of the CeQuest exit’s configuration file. Note that this must not be more than 32 characters long.

For example:

ApiExitLocal: Sequence=200 Function=EntryPoint Module=/bin/CeQuest/cq.dll Name=CeQuest Data=/bin/CeQuest/cq.cfg

4.2.2 Windows

1. Start up the WebSphere MQ Services snap in.

2. Select the queue manager where you want to install the exit. Right click on this and select the properties option. Then select the Exits tab.


Page 35

3. Select the Configure button, and then Add to create the CeQuest exit.

4. The properties that you need to enter are:

i) The name of the exit. This can be anything you like, for clarity Cressida advices "CeQuest".

ii) The function value must be “EntryPoint”. iii) The location of the module. This will depend upon where you installed

CeQuest on your system. iv) You must select the Data button. v) The data is the name of the configuration file that drives the exit/ agent

communication – the complete path name is needed. Note that this must not be more than 32 characters long.


Page 36

vi) The sequence number can be anything that you like. If you have multiple exits, this value determines the order that the exits are called. The CeQuest exit can be called at any point – it makes no changes to any data structure before returning. Cressida recommends that the CeQuest exit is the last one called.

4.3 Configuring the CeQuest Exit

The configuration defines the operation of the interface between the CeQuest exit and the CeQuest agent. There are two possible interfaces:

1. Sockets.

2. WebSphere MQ.

Lines starting with a # character in the configuration file are treated as comments.

If you are using sockets, you have to define the following objects:

a) The socket port number. For example:

portnumber: 2499

b) The polling rate. When the exit is called for the first time, it tries to establish a socket connection to the agent. If the socket connection cannot be established, the exit tries again at an interval determined by this parameter. The value is given in milliseconds. For example:

pollRate: 10000

c) Every message that the exit sends to the agent is acknowledged by the agent. The exit will only allow a limited number of unacknowledged messages to be outstanding. After this number has been reached, further put, get, commit and rollback operations are not forwarded to the agent – they will not be included in any trace report. For example:


Page 37

outstanding: 50

If you are using WebSphere MQ, you have to define the following objects:

d) The name of the agent’s input queue. This will need to be a queue on the queue manager that the exit is connecting to. It could be defined as a remote queue. For example:

agentQName: CQ.AGENT.QUEUE

e) A model queue that the exit opens to create a unique queue that the agent uses to send the exit messages. For example:

modelQName: CQ.MODEL.QUEUE

For both sockets and WebSphere MQ, you will also need to configure:

f) The location of the queue manager files. CeQuest uses this information to build the list of queues that are available on the queue manager. For example:

qmgrFiles: "C:\Program Files\MQSeries\qmgrs"

If configuration file is not specified then sockets will be used with the following default values:

portnumber: 2499

pollRate: 10000

outstanding: 50

4.4 Configuring WebSphere MQ

This section describes how to configure WebSphere MQ if you are using WebSphere MQ to transfer information between the exit and the agent.

Agent Queue

The agent requires an input queue on a specified queue manager (see Agent Configuration above). If you have multiple queue managers on your machine, you can either have a separate agent for each queue manager or define channels between your queue managers.

The exit will write messages to this queue. When the exit puts a message on the queue, it uses default values for all fields. You should consider the following fields:

• GET – must be set to enabled.

• PUT - must be set to enabled.

• MAXDEPTH – this will define the maximum number of messages that can be placed in the queue. Cressida suggests that you restrict this field to prevent the exits swamping the agent with messages. A reasonable value is between 100 and 500 messages.

• SHARE

• DEFSOPT – you must set this to shared.

• USAGE – you must set this to normal.


Page 38

• DEFPSIST – Cressida recommends that you set this to non persistent.

Exit Queues

In addition to the agent queue, you will need to create a model queue on each queue manager that is running the CeQuest exit. When the exit starts, it opens the model queue, which creates a new, temporary, dynamic queue. When the exit wants to send a message to the agent, it uses the configured queue manager and queue names.

The model queue should have the same attributes as the agent queue.

Multiple Queue Managers

If you are using multiple queue managers, you can either define a separate agent for each queue manager or configure the agent to send messages across channels.

Multiple Agents

If you want to use multiple agents, each agent will require a different port number for CeQuest client/ agent communication. To do, set the following field in the CeQuest agent command file:

-Dcressida.request.rmiPortNumber=<port Number>

You will also need to define a corresponding agent in the CeQuest database (see Agent Tab in section 3.2.1).

Using Channels

In this case you define only one agent per machine. The exits are configured with the queue manager and queue name for this agent. You need to define a channel between the queue manager that is controlling the exit and the queue manager that is running the agent.

Next you have to define a channel to run in the reverse direction – that is from the agent queue manager to the exit queue manager. Finally, you have to define a remote queue for the exit’s queue manager – so that WebSphere knows which channel to use to get messages to the exit. To do this, you can use the runmqsc command:

define qremote (<ExitQMgr>) RQMNAME(<ExitQMgr>) XMITQ(<transmission Q>)


Page 39

5 Database Content

This chapter describes the format of the database table that CeQuest writes the trace information to.

All trace information is written to the table called cq_result. Each operation – a put, a get, a commit or a rollback – has a separate row in the table. Each column corresponds to a field that can be displayed. If a field is not required in the trace, it is left as blank or set to 0 depending upon the field type.

The columns in the table are:

Field Name Field Type Notes CQ_TRACE Varchar(48) The name of the trace. This is the name that you enter

when you start the trace on the Trace tab, or as defined by the –trace parameter if you use the CLI.

CQ_QSNAME Varchar(32) The name of the queue set that was traced. CQ_FIELDS0 Integer This defines which MQMD fields have valid information.

To ensure optimum performance, CeQuest only collects the information that it needs from the exit. The following bit setting are used: CQ_STRUCTID 0x00000001 CQ_REPORT 0x00000002 CQ_VERSION 0x00000004 CQ_MSGTYPE 0x00000008 CQ_EXPIRY 0x00000010 CQ_FEEDBACK 0x00000020 CQ_ENCODING 0x00000040 CQ_CCSID 0x00000080 CQ_FORMAT 0x00000100 CQ_PRIORITY 0x00000200 CQ_PERSIST 0x00000400 CQ_MSGID 0x00000800 CQ_CORRELID 0x00001000 CQ_BACKOUT 0x00002000 CQ_REPLYQ 0x00004000 CQ_REPLYQM 0x00008000 CQ_USERID 0x00010000 CQ_ACCTOKEN 0x00020000 CQ_APPLID 0x00040000 CQ_APPLTYPE 0x00080000 CQ_APPLNAME 0x00100000 CQ_PUTDATE 0x00200000 CQ_PUTTIME 0x00400000 CQ_ORIGIN 0x00800000 CQ_GROUPID 0x01000000 CQ_SEQNUM 0x02000000 CQ_OFFSET 0x04000000 CQ_FLAGS 0x08000000 CQ_ORIGLEN 0x10000000


Page 40

CQ_FIELDS1 Integer This defines which non-MQMD fields are included for this trace item: CQ_TIME 0x00000001 CQ_QMGR 0x00000002 CQ_QUEUE 0x00000004 CQ_RESQUEUE 0x00000008 CQ_OP 0x00000010 CQ_DATALEN 0x00000020 CQ_CCODE 0x00000040 CQ_RVALUE 0x00000080 CQ_XACT 0x00000100 CQ_BROWSE 0x00000200 CQ_PID 0x00000400

CQ_TIME BigInt The time that the event was recorded. This is the number of seconds since 00:00 1st January, 1970, GMT.

CQ_QMGR Varchar(48) The name of the queue manager. CQ_QUEUE Varchar(48) The name of the queue as supplied by the application

when the queue was opened. CQ_PID Integer The process number of the process that reported the

operation. CQ_RESQUEUE Varchar(48) The name of the actual queue used.

If the queue that was opened is an alias queue, this is the name of queue that the alias queue maps to. If the queue that was opened is a model queue, this is the name of the actual queue.

CQ_OP Varchar(20) The operation, which is one of: Put Get Commit Rollback

CQ_XACT Integer Indicates whether or not a put or get is transactional. The value is 1 if the operation was performed under transaction control, or 0 otherwise.

CQ_BROWSE Integer For gets, this field is 1 if the get was a browse. 0 in all other cases.

CQ_STRUCTID Varchar(4) StrucId field in the MQMD. CQ_REPORT Integer Report field in the MQMD. CQ_VERSION Integer Version field in the MQMD. CQ_MSGTYPE Integer MsgType field in the MQMD. CQ_EXPIRY Integer Expiry field in the MQMD. CQ_FEEDBACK Integer Feedback field in the MQMD. CQ_ENCODING Integer Encoding field in the MQMD. CQ_CCSID Integer CodedCharSetId field in the MQMD. CQ_FORMAT Varchar(8) Format field in the MQMD. CQ_PRIORITY Integer Priority field in the MQMD. CQ_PERSIST Integer Persistence field in the MQMD. CQ_MSGID(†) Varchar(72) MsgId field in the MQMD. CQ_CORRELID(†) Varchar(72) CorrelId field in the MQMD. CQ_BACKOUT Integer BackoutCount field in the MQMD. CQ_REPLYQ Varchar(48) ReplyToQ field in the MQMD. CQ_REPLYQM Varchar(48) ReplyToQMgr field in the MQMD. CQ_USERID Varchar(12) UserIdentifier field in the MQMD. CQ_ACCTOKEN(†) Varchar(96) AccountingToken field in the MQMD. CQ_APPLID(†) Varchar(96) ApplIdentityData field in the MQMD. CQ_APPLTYPE Integer PutApplType field in the MQMD. CQ_APPLNAME Varchar(28) PutApplName field in the MQMD. CQ_PUTDATE Varchar(8) PutDate field in the MQMD. CQ_PUTTIME Varchar(8) PutTime field in the MQMD. CQ_ORIGIN Varchar(4) ApplOriginData field in the MQMD.


Page 41

CQ_GROUPID(†) Varchar(72) GroupId field in the MQMD. CQ_SEQNUM Integer MsgSeqNum field in the MQMD. CQ_OFFSET Integer Offset field in the MQMD. CQ_FLAGS Integer MsgFlags field in the MQMD. CQ_ORIGLEN Integer OriginalLength field in the MQMD. CQ_DATALEN Integer For puts and gets, this is the actual length of the user

data in bytes. CQ_CCODE Integer The MQ completion code. CQ_RVALUE Integer The MQ return value. CQ_REAL_CCSID Integer The CodedCharSetId. This is the CodedCharSetId field

in the MQMD. This field is always present – it is needed to display the user data correctly.

CQ_DATA The first part of the user data. Each character in the user data is represented by two hexadecimal digits (with no separators) – for example “53420831753E”. You can choose how much user data to record through the user interface. The maximum amount of data to store is 1000 bytes. The type of database object used to hold this information depends upon the database that you are using. For example, for MySQL, this is a Blob; for Oracle it is a varchar(2048).

Integer Fields

All integer fields are represented using the standard encoding of the database. The conversion between different encodings is done between the agent and the client. (Note that the agent and the exit must use the same encoding.)

String Fields

All string fields are represented in the character set of the system running the database. The conversion between different character sets is done between the agent and the client. (Note that the agent and the exit must use the same character set.)

Byte Array Fields

The fields marked with a (†) character are byte array fields. The data in these fields is not converted between the agent and the client. Each byte in the field is represented as two hexadecimal digits, and these are separated by colon characters. For example:

45:7E:8F:07


Page 42

6 Error Messages

cressida cequest for websphere® mq - users' guide · 1 introduction welcome to cressida...

Documents