installation and user’s guide - capitalware€¦ · installation and user’s guide . ... ibm...

z/ISPFMQ - ISPF MQ Message Editor for z/OS

Installation and User’s Guide

Version 1 Release 2 Modification 1

© Copyright Capitalware Incorporated 2012. All rights reserved.

Note!

Before using this information and the product it supports, be sure to read the general information under “Notices” section found in Appendices page 2.

Third Edition (Aug 28, 2012)

This edition applies to Version 1 Release 2 Modification Level 1 of Capitalware’s ISPFMQ for z/OS and to all subsequent releases and modifications until otherwise indicated in new editions.

This publication is available on the Web at:

http://www.zispfmq.com/docs/zISPFMQ_Installation_and_Users_Guide.pdf

http://www.zispfmq.com/docs/zISPFMQ_Installation_and_Users_Guide.pdf

Contents

About this document................................................................... 1 Document Topics..................................................................................1

About this document ..............................................................1 Installation Instructions ..........................................................1 Starting ISPFMQ....................................................................1 Getting started with ISPFMQ .................................................1 Edit Messages .......................................................................1 Edit Messages – File Functions.............................................2 Manage Sessions ..................................................................2 Tools 2 Preferences............................................................................2 Appendices ............................................................................2

Who should use this document? ..........................................................3 How to use this document ....................................................................4 Prerequisite and related information ....................................................4

System Prerequisites ...................................................................4 Requisite High Level Qualifier (hlq) dataset name.......................4 TSO user name conventions used...............................................4

Related Documents ..............................................................................5 ISPFMQ Introduction .............................................................5 IBM WebSphere MQ Application Programming Guide .........5 IBM WebSphere MQ Application Programming Reference ..5 IBM WebSphere MQ Systems Administration Guide ............5 IBM WebSphere MQ Script (MQSC) Command Reference..5

Summary of Changes.................................................................. 6 Version 1 Release 2 Modification Level 1 (1.2.1).................................6

Startup 6 Message Edit Functions ........................................................6 File Functions.........................................................................6

Version 1 Release 2 Modification Level 0 (1.2.0).................................6 Logging 6 Message Edit Functions ........................................................6 Tools Functions......................................................................6

Version 1 Release 1 Modification Level 0 (1.1.0).................................7 ISPFMQ load library – automatically loaded .........................7

Contents i

Message Edit Functions ........................................................7 Preferences - Logging ...........................................................7

Chapter 1. ....................................... 8 Installation InstructionsInstall ISPFMQ......................................................................................8

Obtain the install package file ......................................................9 Move the install package file to the host z/OS.......................9

TSO “RECEIVE” the install package file ......................................9 Create the target install PDS using the TSO RECEIVE

command ..................................................................9 Create the library datasets .........................................................10 ISPFMQ dataset space allocations ............................................11

ISPFMQ datasets ...............................................................................12 Startup and license dataset: “hlq.ISPFMQ12.SAMPLES” .........13

Startup procedure – member: ISPFMQ...............................13 License key – member: TEMPLIC.......................................13

Update ISPFMQ startup procedure....................................................14 ISPFMQ load library ...........................................................................16

Chapter 1. ................................................. 17 Starting ISPFMQExecute the ISPFMQ startup procedure ............................................18 ISPFMQ Primary Panel – Main Menu ................................................19 ISPF considerations ...........................................................................20

ISPF profiles ...............................................................................20 Startup Problems................................................................................21

Connect Failed ...........................................................................21 Chapter 2. ............................. 22 Getting started with ISPFMQ

What is ISPFMQ.................................................................................23 What functions does ISPFMQ have ...................................................23 Using ISPFMQ....................................................................................24 General concepts and panel navigation.............................................24

Quick Shutdown .........................................................................26 Shutdown....................................................................................26

Summary of ISPFMQ functions and panels .......................................27 Status information...............................................................................29 Getting Help........................................................................................30

Displaying field help information ................................................30 Accessing tutorial help ...............................................................30 Viewing error messages.............................................................31

Profile Information ..............................................................................31

© Copyright Capitalware Incorporated 2012. All rights reserved. ii

Connecting to the QManager .............................................................31 Selecting and opening a queue to edit messages .............................32 Licensing.............................................................................................32

Chapter 3. .................................................... 33 Edit MessagesMessage Edit - panel..........................................................................33 Editing Messages ...............................................................................34

Displaying message data ...........................................................36 Changing your view of message data ........................................37

Primary commands used to manipulate the logical view.....37 Select the field data you want to be displayed using the

SELCOL command.................................................37 Results of the SELCOL command.......................................38 Toggling your view of the data.............................................39

Scrolling to see data...................................................................39 Controlling how far you scroll...............................................39 Scrolling to the first or last record or column .......................39

Sorting the data ..........................................................................40 Finding specific message data...................................................40 Selecting a message ..................................................................41

How to select a message.....................................................41 Selection options..................................................................41

Delete message .........................................................................42 Select the record for deletion...............................................42 Updated message panel......................................................43 Block Delete.........................................................................43

Replicate message.....................................................................44 Select the record for replication ...........................................44 Updated message panel......................................................45 Block Replicate ....................................................................45

Cut message ..............................................................................46 Updated message panel......................................................47

Copy message ...........................................................................48 Updated message panel......................................................49

Paste message...........................................................................50 Updated message panel......................................................51

View message ............................................................................52 View message popup panel.................................................53

Edit message..............................................................................54

Contents iii

Working with message data ..........................................55 XML edit message......................................................................56

XML Edit message data ................................................57 Insert message...........................................................................58

Insert message panel ..........................................................59 Export message .........................................................................60

Respond to the dataset popup.............................................61 Updated message panel......................................................62 Block Export.........................................................................62

Forward message.......................................................................63 Respond to the Open Queue panel – specifying the target

queue ......................................................................64 Updated message panel......................................................64 Block Forward ......................................................................65

MQMD message ........................................................................66 MQMD selection popup panel .............................................66 Working with MQMD header properties ..............................67

General..........................................................................67 Report............................................................................68 Context ..........................................................................69 Identifiers .......................................................................70 Segmentation ................................................................71 Attributes .......................................................................72

Working with other header types................................................73 MQHRF .........................................................................73 MQHRF2 .......................................................................74 MQIMS ..........................................................................75 MQCICS ........................................................................76 MQHSAP.......................................................................77 MQDLH..........................................................................78

Chapter 4. ........................ 79 Edit Messages – File FunctionsMessage Edit - File menu drop down list ...........................................80 Opening the queue .............................................................................81

General panel instructions ...................................................82 Panel and field definitions....................................................82

Refresh the queue ..............................................................................82 Closing the queue...............................................................................82 Close All..............................................................................................83 Backup the queue...............................................................................83 Restore the queue ..............................................................................84 Clear the queue ..................................................................................85 Clear the queue by ID.........................................................................86 Clear the queue by Date/Time ...........................................................88

© Copyright Capitalware Incorporated 2012. All rights reserved. iv

Clear the queue by String...................................................................90 Chapter 5. ............................................... 92 Manage Sessions

Session Manager................................................................................92 Chapter 6. .................................................................... 93 Tools

Load Test Tools..................................................................................94 Get Server ..................................................................................94

Get Server Entry panel ........................................................95 General panel instructions ...................................................95 Panel and field definitions....................................................95

Put Server...................................................................................96 Put Server Entry panel.........................................................97 General panel instructions ...................................................97 Panel and field definitions....................................................97

Move Message Tools .........................................................................99 Drain Queue ...............................................................................99 Backup and Drain Queue.........................................................100 Backup Queue..........................................................................101 Restore Queue .........................................................................102

Monitor Tools....................................................................................102 Queue Monitor..........................................................................102

Panel and field definitions ...........................................103 Specifying the types of queues to list ................................104

Panel and field definitions ...........................................105 Modifying your view of queue data ....................................105

Using primary commands when viewing queue data..105 Scrolling to see data ..........................................................105

Scrolling to the first or last record or column...............105 Finding specific queue data ...............................................106 Select a queue ...................................................................107

Selection options .........................................................107 Select a queue ............................................................107

Chapter 7. ....................................................... 108 PreferencesModify File Options...........................................................................109

Modify File Options panel.........................................................109 General panel instructions .................................................110 Panel and field definitions..................................................110

Setup File Attributes panel .......................................................112 General panel instructions .................................................112 Panel and field definitions..................................................112

File record layout ......................................................................113

Contents v

Logging Preferences ........................................................................114 General panel instructions .................................................114 Panel and field definitions..................................................114

User Preferences..............................................................................116 General panel instructions .................................................116 Panel and field definitions..................................................117 License 118

Appendices .................................................................................. 1 Support .................................................................................................1 Notices..................................................................................................2 Trademarks ..........................................................................................3

Glossary ....................................................................................... 4 Index .....................................................................................................4

© Copyright Capitalware Incorporated 2012. All rights reserved. vi

Table of Figures

Figure 1 – Contents of the received ISPFMQ pkg dataset.................10 Figure 2 – ISPFMQ dataset space allocations...................................11 Figure 3 – Datasets required by ISPFMQ ..........................................12 Figure 4 – ISPFMQ key dataset, hlq.ISPFMQ12.SAMPLES .............13 Figure 5 – ISPFMQ startup procedure parts one and two - after hlq

change .........................................................................................14 Figure 6 – ISPFMQ startup procedure part three...............................15 Figure 7 – ISPFMQ startup procedure part two - logging preferences

area ..............................................................................................16 Figure 8 – Start ISPFMQ....................................................................18 Figure 9 – ISPFMQ Primary Panel – Main Menu...............................19 Figure 10 – ISPF profiles used by ISPFMQ .......................................20 Figure 11 – Connection failed – specify a connectable QManager ...21 Figure 12 – ISPFMQ Primary Panel – Main Menu.............................24 Figure 13 – Selecting a menu/function...............................................25 Figure 14 – Example status message on the Message Edit panel ....29 Figure 15 – Selecting and opening a queue to edit messages ..........32 Figure 16 – Message Edit panel.........................................................33 Figure 17 – Message selection and command options......................34 Figure 18 – Default message “data only” view when first editing a

queue ...........................................................................................36 Figure 19 – Message view after invoking the SELCOL command.....37 Figure 20 – View of data after invoking the “SELCOL” command .....38 Figure 21 – Delete the message ........................................................42 Figure 22 – confirm delete..................................................................42 Figure 23 – Delete the message ........................................................43 Figure 24 – Replicate the message....................................................44 Figure 25 – Replicated message........................................................45 Figure 26 – Cut the message .............................................................46 Figure 27 – Cut message ...................................................................47 Figure 28 – Copy the message ..........................................................48 Figure 29 – Copied message .............................................................49 Figure 30 – Paste the message .........................................................50 Figure 31 – Pasted message .............................................................51

Table of Figures vii

Figure 32 – View the message...........................................................52 Figure 33 – View message panel .......................................................53 Figure 34 – Edit the message ............................................................54 Figure 35 – Edit message data ..........................................................55 Figure 36 – XML edit the message ....................................................56 Figure 37 – XML edit message data page one of two........................57 Figure 38 – XML edit message data page two of two ........................57 Figure 39 – Insert the message..........................................................58 Figure 40 – Insert message panel......................................................59 Figure 41 – Insert message confirmation request..............................59 Figure 42 – Export the message ........................................................60 Figure 43 – Dataset popup – specify the file where export data will be

saved............................................................................................61 Figure 44 – Exported message ..........................................................62 Figure 45 – Forward the message .....................................................63 Figure 46 – Open queue – specify the target queue name................64 Figure 47 – Forwarded message .......................................................64 Figure 48 – Edit the MQMD header ...................................................66 Figure 49 – MQMD selection popup panel.........................................67 Figure 50 – Working with the MQMD header - General properties

panel ............................................................................................67 Figure 51 – Working with the MQMD header - Report properties panel68 Figure 52 – Working with the MQMD header - Context properties

panel ............................................................................................69 Figure 53 – Working with the MQMD header - Identifiers properties

panel ............................................................................................70 Figure 54 – Working with the MQMD header - Segmentation

properties panel ...........................................................................71 Figure 55 – Working with the MQMD header - Attributes properties

panel ............................................................................................72 Figure 56 – Working with the MQHRF data .......................................73 Figure 57 – Working with the MQHRF2 data .....................................74 Figure 58 – Working with the MQIMS data ........................................75 Figure 59 – Working with the MQCICS data ......................................76 Figure 60 – Working with the MQHSAP data.....................................77 Figure 61 – Working with the MQDLH data .......................................78 Figure 62 – Edit Messages - File menu drop down list ......................80 Figure 63 – Open queue panel...........................................................81

© Copyright Capitalware Incorporated 2012. All rights reserved. viii

Table of Figures ix

Figure 64 – Backup the queue to a data set. .....................................83 Figure 65 – Restore the queue from a data set. ................................84 Figure 66 – Clear the queue...............................................................85 Figure 67 – Clear the queue by ID. ....................................................86 Figure 68 – Confirm clearing the queue. ............................................87 Figure 69 – Clear the queue by date/time. .........................................88 Figure 70 – Confirm clearing the queue by Date/Time. .....................89 Figure 71 – Clear the queue by ID. ....................................................90 Figure 72 – Confirm clearing the queue by search string. .................91 Figure 73 – Session Manager ............................................................92 Figure 74 – Tools functions panel ......................................................93 Figure 75 – Get All Message Entry panel...........................................95 Figure 76 – Put Server entry panel ....................................................97 Figure 77 – Confirm draining the queue...........................................100 Figure 78 – Confirm draining the queue...........................................101 Figure 79 – Queue selection panel ..................................................103 Figure 80 – Queue specification panel.............................................104 Figure 81 – Select a queue - Update generated name and parameters107 Figure 82 – Preferences - Menu.......................................................108 Figure 83 – File options panel – review and update values.............110 Figure 84 – Setup file attributes panel – review and update values 112 Figure 85 – Logging Preferences .....................................................114 Figure 86 – User Preferences ..........................................................116

0. About this document

About this document This document provides guidance and installation information for users of ISPFMQ - ISPF MQ Message Editor for z/OS for working with WebSphere MQ.

The following topics are described in detail, in their own chapters within this document.

Document Topics

About this document The section currently under review provides document information.

Installation Instructions This chapter describes the installation method and the step-by-step procedures used to install ISPFMQ.

Starting ISPFMQ This chapter details the steps required to start ISPFMQ.

Getting started with ISPFMQ This chapter is designed to help the new user familiarize themselves with the user interface and to understand general concepts and panel navigation

Edit Messages This chapter describes the functions used for viewing, editing, creating, deleting, moving, importing, exporting and working with the MQMD header of messages from a WebSphere MQ queue.

To work with “Edit Messages” functions enter primary command “ME” or option “E” when on the primary options panel.

0. About this document 1

Document Topics

Edit Messages – File Functions This chapter describes the functions used in the process of selecting, opening and running utilities on a WebSphere MQ queue.

To work with “Edit Messages – File Functions” enter primary command “MF” or option “F” when on the primary options panel.

Manage Sessions The Session Manager panel displays a list of active queue sessions and provides functions used to work with those active sessions.

Enter primary command “MS1” or option “S” when on the primary panel to work with active queue sessions.

Tools ISPFMQ offers utilities that you can use to work with WebSphere MQ. This chapter provides information about and instructions for using these utilities.

To work with “Tools” functions enter primary command “MT” or option “T” when on the primary options panel.

Preferences You can customize various operational aspects of ISPFMQ via the Preferences panel (command line “MP”).

Appendices The appendices contain:

• Support and contact information

• Business information such as Notices

• Glossary - Index

1 or “M.S”

ISPFMQ for z/OS V1R2 User’s Guide 2


Who should use this document? This document is for four kinds of ISPFMQ users:

1. MQ Application programmers who need to test and debug MQ programs

2. Service support personnel who need to analyze and fix MQ problems

3. System administrators and system operators who need to do routine tasks such as controlling the MQ operational environment and manipulating queues and messages

4. Quality Assurance and Performance testers

This document assumes that you are familiar with using ISPF.

To use ISPFMQ functions you should already have some conceptual familiarity with MQ.


How to use this document

How to use this document This document can be used by the system programmer who installs and maintains ISPFMQ, ISPFMQ application users and persons wanting general ISPFMQ knowledge. Recommended next steps after completing this “About this document” section are:

1. System programmers start with “Install ISPFMQ” on page 8.

2. ISPFMQ users should start with “Starting ISPFMQ” on page 17.

3. Persons only wanting to familiarize themselves with ISPFMQ features, the user interface and general methods for working within ISPFMQ panels should read “Chapter 2. Getting started with ISPFMQ" on page 22.

Prerequisite and related information

System Prerequisites ISPFMQ will run on any z/OS which supports:

• WebSphere MQ versions V5.3.1 and higher

• z/OS 1.4 and higher

Requisite High Level Qualifier (hlq) dataset name The installation of ISPFMQ requires that you supply a “high level qualifier” or hlq dataset name. The default hlq of “ISPFMQ12” may not be a suitable hlq for your system.

This document demonstrates the changes required to use hlq = “IBMUSER”.

TSO user name conventions used Through out this document you will see reference to two TSO users:

1. “IBMUSER”– system programmer who installs and modifies ISPFMQ.

2. “MQT1” – ISPFMQ application user.



Related Documents

ISPFMQ Introduction

IBM WebSphere MQ Application Programming Guide

IBM WebSphere MQ Application Programming Reference

IBM WebSphere MQ Systems Administration Guide

IBM WebSphere MQ Script (MQSC) Command Reference


Version 1 Release 2 Modification Level 1 (1.2.1)

Summary of Changes


Startup 1. Bypass CVT checking as users may not have authority.

Message Edit Functions 1. User can specify any MQMD – ATTRIBUTE – FORMAT value.

File Functions 1. Dataset names displayed with the Dataset List “wildcard” now show the

full 36 character length.


Logging 1. Corrected startup procedure and logging preferences settings.

2. Upon startup, ISPFMQ will now use (create and add) GDG files for logging ISPFMQ activity. These files will be automatically allocated each time ISPFMQ starts up.

Message Edit Functions 1. Improved message handling performance.

2. Modified error handling routines.

3. Modified data handling routines.

Tools Functions 1. Get Server modified.


0. Summary of Changes

2. Put Server tools modified.


ISPFMQ load library – automatically loaded The ISPFMQ load library is automatically loaded via LIBDEF commands found in the ISPFMQ startup procedure. See ISPFMQ load library .

Message Edit Functions 1. Delete a newly inserted message without first refreshing the Queue.

2. The following Message Edit “block” selection functions have been added:

DD – block Delete see Block Delete.

RR – block Replicate see Block Replicate.

XX – block Export see Block Export..

FF – block Forward see Block Forward.

Preferences - Logging The Logging Preferences panel used to select which MQ API calls or ISPFMQ function calls, if any, are recorded in the log file:

MQ API calls:

1. Get Message (ReadOnly)

2. Get Message (Destruct)

3. Put Message

4. Open Queue

5. Close Queue

Tools:

1. Get Server

2. Put Server

0. Summary of Changes 7

Install ISPFMQ

Chapter 1. Installation Instructions This chapter describes the installation method and the step-by-step procedures used to install ISPFMQ.

The major tasks described in this chapter are:

• Install ISPFMQ

• ISPFMQ datasets on page 12.

• Update ISPFMQ startup procedure on page 14.

• ISPFMQ load library on page 16.

Install ISPFMQ The steps required to install ISPFMQ are summarized as follows:

1. Obtain the ‘XMIT’ format install package file and move it to the z/OS system where ISPFMQ will be run. See Obtain the install package file on page 9.

2. The install package file must be converted into its native dataset format using the “TSO RECEIVE” command. The command will generate dataset ’hlq.ISPFMQ12.DWNLDS’. This DWNLDS dataset contains seven library files. See TSO “RECEIVE” the install package file on page 9.

3. The seven library files are in turn stored in ‘XMIT’ format and must themselves be converted into their native dataset format using the aforementioned RECEIVE command. Each of seven received files will generate a library dataset. See Create the library datasets on page 10.

4. Review ISPFMQ dataset space allocations on page 11.



Obtain the install package file

Move the install package file to the host z/OS Obtain the ISPFMQ install (‘XMIT’ format) package file, PKG.ISPFMQ12.XMT and move it to the z/OS system where ISPFMQ will be installed.

IND$FILE and FTP are two of the more common methods of moving the package into z/OS.

Prior to moving the file into z/OS you may wish to first allocate the target package file with the following parameters:

1. LRECL=80

2. BLKSIZE=3120

3. DSORG=PS

4. RECFM=FB

5. Primary allocation = 2200 blocks

When moved to the host, the install package file name typically reflects the TSO-id of the programmer who moved the file. When TSO-id = IBMUSER, the install file name would be IBMUSER.PKG.ISPFMQ12.XMT.

TSO “RECEIVE” the install package file The install package file must be converted into its native format using the “TSO RECEIVE” command.

Create the target install PDS using the TSO RECEIVE command Convert the install package file into its native partitioned dataset format, using the “TSO RECEIVE” command. Enter the following command:

TSO RECEIVE INDSN (PKG.ISPFMQ12.XMT)

This command, when executed by TSO-id IBMUSER, will create the install dataset ‘IBMUSER.ISPFMQ12.DWNLDS’, contents of which are listed below.


Install ISPFMQ

Figure 1 – Contents of the received ISPFMQ pkg dataset

The generated install DWNLDS dataset contains seven library files:

• The seven libraries files are in turn stored in ‘XMIT’ format and must be converted into their native dataset format using the TSO RECEIVE command. Each of seven received files will generate a dataset.

Create the library datasets Having generated the DWNLDS file, you then receive all seven stored libraries in a manner similar to the one displayed below:2

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(IMQMLIB)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(IMQPLIB)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(IMQSLIB)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(IMQTLIB)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(LOAD)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(SAMPLES)')

• TSO RECEIVE INDSN('hlq.ISPFMQ12.DWNLDS(SYSCEXEC)')

2 Where ‘hlq’ is typically the installers TSO-id



ISPFMQ dataset space allocations

Dataset

Org

Record

Format

Record

Length

Block

Size

First extent

(blocks)

PKG.ISPFMQ12.XMT PS FB 80 3120 2200

hlq.ISPFMQ12.DWNLDS PO FB 80 3120 1600

hlq.ISPFMQ12.IMQMLIB PO FB 80 27920 4

hlq.ISPFMQ12.IMQPLIB PO FB 80 27920 50

hlq.ISPFMQ12.IMQSLIB PO FB 80 27920 4

hlq.ISPFMQ12.IMQTLIB PO FB 80 27920 4

hlq.ISPFMQ12.LOAD PO U 0 32760 100

hlq.ISPFMQ12.SAMPLES PO VB 256 27904 4

hlq.ISPFMQ12.SYSCEXEC PO FB 80 27920 40

Figure 2 – ISPFMQ dataset space allocations


ISPFMQ datasets

ISPFMQ datasets The following figure lists the seven datasets, required to run ISPFMQ.

Figure 3 – Datasets required by ISPFMQ



Startup and license dataset: “hlq.ISPFMQ12.SAMPLES”

Figure 4 – ISPFMQ key dataset, hlq.ISPFMQ12.SAMPLES

Dataset hlq.ISPFMQ12.SAMPLES contains two members listed as follows:

1. ISPFMQ - ReXX exec used to start ISPFMQ

2. TEMPLIC - Temporary license – ISPFMQ Message Edit

Startup procedure – member: ISPFMQ The startup procedure can be found in member ISPFMQ. See “Update ISPFMQ startup procedure” on page 14 for modification instructions.

License key – member: TEMPLIC The 64 byte License key is the mechanism by which ISPFMQ determines how it is to operate for any particular Queue Manager.

The license key name (TEMPLIC) can be changed to one that better fits your organizational naming standards. Note: The license key name is specified as a parameter within the ISPFMQ startup procedure and as such must reflect the actual license key name used.

ISPFMQ ships with a blank license key. Contact your ISPFMQ representative to receive your temporary or permanent license key.


Update ISPFMQ startup procedure

Update ISPFMQ startup procedure To run ISPFMQ, update the startup procedure (ISPFMQ) to reflect the:

1. High level qualifier (hlq) used for running ISPFMQ.

2. Default QManager name used upon startup.

3. Prefix used for ISPFMQ temporary queues

4. Model Queue used by ISPFMQ

5. License – ISPFMQ ships with one temporary license, “TEMPLIC”, that provides message edit functionality. Replace the temporary license name with your permanent license name.

Figure 5 – ISPFMQ startup procedure parts one and two - after hlq change



6. Log File ISPFMQ uses GDG file methodology for ISPFMQ log files. Modify:

a. gdg_create routine to specify: 1) an acceptable GDG base name and 2) the number of entries to be retained.

b. gdg_add routine to use GDG base name and to specify space parameters.

c. gdg_delete routine to delete GDG base file and all associated GDG entries.

Figure 6 – ISPFMQ startup procedure part three


ISPFMQ load library

7. Logging Preferences default settings of ‘N’ can be modified to track MQ API calls such as Open, Close, Get and Put, and ISPFMQ tools such as GetServer and PutServer. Note: settings modified by the administrator cannot be overridden by the user.

Figure 7 – ISPFMQ startup procedure part two - logging preferences area

The “sLog” parameter string is used to define which ISPFMQ functions, such as MQ API calls or Server calls, are written to the log file. The “sLog” positional field values define the default settings for all ISPFMQ users.

ISPFMQ users can update these same values via the Logging Preferences panel on page 114. However, users cannot turn off logging for fields that been turned on from within the startup procedure.

ISPFMQ load library The ISPFMQ load library is automatically loaded via the LIBDEF command found in the ISPFMQ startup procedure.


Chapter 1. Starting ISPFMQ

Chapter 1. Starting ISPFMQ ISPFMQ is an ISPF-developed application and is run from within an ISPF session. Exiting from ISPFMQ returns you to your ISPF session.

How you start ISPFMQ depends on how it has been installed on your system. Typically, it is installed as an option on the z/OS primary option menu where the z/OS menu selection executes the ISPFMQ supplied startup procedure on your behalf. The major tasks described in this chapter are:

• “Execute the ISPFMQ startup procedure”

• “ISPFMQ Primary Panel” on page 19

• “ISPF considerations” on page 20

• “Startup Problems” on page 21

NOTE: When logging onto TSO it is recommended that you allocate a TSO region size of 16MB if you are working with messages larger than 1MB.

Chapter 1. Starting ISPFMQ 17

Execute the ISPFMQ startup procedure

Execute the ISPFMQ startup procedure TSO user MQT1 can start ISPFMQ by executing the startup procedure ‘ISPFMQ’ found in the samples dataset ‘IBMUSER.ISPFMQ12.SAMPLES’.

Figure 8 – Start ISPFMQ



ISPFMQ Primary Panel – Main Menu ISPFMQ Main Menu is the first panel displayed when you start ISPFMQ.

Figure 9 – ISPFMQ Primary Panel – Main Menu


ISPF considerations

ISPF considerations

ISPF profiles By default ISPFMQ uses ‘ZIMQ’ as its ISPF application id. Each ISPFMQ user will see two members: ZIMQEDIT and ZIMQPROF in the profiles dataset.

NOTE: Deleting these two members will reset ISPFMQ to its initial state.

Figure 10 – ISPF profiles used by ISPFMQ



Startup Problems

Connect Failed When opening3 a queue, you first must specify a QManager name. ISPFMQ checks that an existing connection to the QManager exists and will attempt to connect to that QManager if no connection exists.

If the connection failed, then ISPFMQ will issue a “Could not open Queue” message displayed in the Status –short text message area found in the upper right corner and a more detailed status – long text message displaying the specific MQ return code followed and MQ return message.

MQRC_Q_MGR_NAME_ERROR or MQRC_Q_MGR_NOT_AVAILABLE are two of the more common failure to connect return messages.

You will remain on the “Open Queue Menu” panel until connection is established or you <PF3> out of the panel.

Figure 11 – Connection failed – specify a connectable QManager

3 See “Opening the queue” on page 81 for more information on opening a queue.


Startup Problems

Chapter 2. Getting started with ISPFMQ

This chapter is designed to help the new user familiarize themselves with the user interface and to understand general concepts and panel navigation.


• ”What is ISPFMQ” on page 23.

• “What functions does ISPFMQ have” on page 23 .

• “Using ISPFMQ” on page 24.

• “General concepts and panel navigation” on page 24.

• “Summary of ISPFMQ functions” on page 27.

• “Status information” on page 29.

• “Getting Help” on page 30.

• “Profile Information” on page 31.

• “Connecting to the QManager” on page 31.

• “Selecting and opening a queue” on page 32.

• “Licensing” on page 32.



What is ISPFMQ A z/OS based MQ tool used to work with MQ objects such as message queues without having to write programs to do so. Use it, so you can:

• View, edit, update and store MQ message data, message descriptor (MD) fields and header data such as MQDLH, MQRFH, MQRFH2, MQIMS, MQCICS, MQHSAP

• Work simultaneously with up to 100 queues

• Capture and playback MQ messages, including MD and MO fields, with user specified inter-message delay.

• Work with large messages (up to 4.2MB).

• Store and retrieve messages from and to files.

• Audit ISPFMQ activity by selectively logging Open, Close, Get (Destruct), Get(ReadOnly), Put MQ API calls.

• Test MQ without relying on PC based software.

• Determine response time in MQ applications.

• Isolate performance problems in MQ applications.

• Determine the performance effects of increased MQ workload.

What functions does ISPFMQ have • Manage queue functions such as Open, Backup, Restore, Clear (by Date,

String or All). Use the Manage Session functions to work simultaneously with up to 100 queues.

• Message Edit Functions such as Insert, Edit (Hex and String), XmlEdit, Duplicate, Remove, Cut, Copy, Paste, View, Forward, Import and Export. Use the Message Edit functions to manipulate message data.

• Header functions such as the list/tabular edit of MQMD fields and MQDLH, MQRFH, MQRFH2, MQIMS, MQCICS, MQHSAP header areas. Select and review MQ message and MQMD field data in user specified column format. Use the Header functions to easily review and manipulate MD field and key MQ header data.

• Preferences functions: modify ISPFMQ file attributes, logging preferences and user preferences.

• Tool functions such as Get and Put Servers, Drain, Backup&Drain, Backup and Restore Queue. Use the Get and Put server functions to work with messages using inter-message time delay and to obtain performance testing MQ response time data.

Chapter 2. Getting started with ISPFMQ 23

Using ISPFMQ

• Monitor queue function: Display queue depth, queue type, enabled for get, enabled for put, open for input and open for output information.

Using ISPFMQ The ISPFMQ interface is based upon the ISPF model. Tasks are performed by processing a function, together with its applicable parameters. Panels provide a user-friendly way of selecting a function and supplying the parameter information.

When you start ISPFMQ the main menu option panel is shown with the current version information displayed.

Figure 12 – ISPFMQ Primary Panel – Main Menu

General concepts and panel navigation You navigate around ISPFMQ panels in the same way as any other panels under ISPF. That is, you launch processing panels from menu panels, by entering the appropriate menu option number on the command line.

ISPFMQ uses a primary option menu panel to provide access to processing panels that are related to a particular function or group of functions. In some cases, an option on the primary option menu leads to another menu panel, from which you can select the required processing panel.



Figure 13 – Selecting a menu/function

When you know the menu structure well, you can quickly jump to the required panel by entering the full pathway through the menu options. For example, entering “TM” or “T.M” will take you directly to the Tools: Monitor Queue panel, whereas “TG” or “T.G” would place you on the Tools: Get Server panel. To access a panel, choose one of the following methods:

1. To access a menu element on the menu option panel under focus, type the menu element number on the command line and press Enter. Repeat for each nested menu until the required processing panel is displayed.

2. You can access a menu element on the menu option panel under focus, by placing your cursor on a menu element name and press Enter. Repeat for each nested menu until the required processing panel is displayed.


General concepts and panel navigation

3. To access a menu element on any menu option panel, type in the full two character (or three character, period “.” separated), menu path. For example, “F1” would display the Open Queue panel (option 1 on the File Menu – panel which is in turn option F on the primary options menu panel).

Quick Shutdown All commands beginning with an equal sign “=”will:

1. Result in an orderly shutdown of your ISPFMQ session.

2. Return you back to ISPF in the command destination that follows the “=”.

Shutdown You shutdown ISPFMQ:

1. From the primary options panel type command line option “X” and press <ENTER>.

2. <PF3> from the primary options panel.



Summary of ISPFMQ functions and panels The ISPFMQ functions and panels described in this document are:

• “Edit Messages” on page 33.

• “Message Edit - panel” on page 33.

• “Editing Messages” on page 34.

• “Displaying message data” on page 36.

• “Changing your view of message data” on page 37.

• “Scrolling to see data“ on page 39.

• “Sorting the data” on page 40.

• “Finding specific message data” on page 40.

• “Selecting a message” on page 41.

• “Delete message” on page 42.

• “Replicate message” on page 44.

• “Cut message” on page 46.

• “Copy message” on page 48.

• “Paste message” on page 50.

• “View message” on page 52.

• “Edit message” on page 54.

• “XML edit message” on page 56.

• “Insert message” on page 58.

• “Export message” on page 60.

• “Forward message” on page 63.

• “MQMD message” on page 66.

• “Working with other header types” on page 73.

• “Message Edit - File menu ” on page 80.

• “Opening the queue” on page 81.

• “Refresh the queue” on page 82.

• “Closing the queue” on page 82.

• “Close All” on page 83.

• “Backup the queue” on page 83.

• “Restore the queue” on page 84.


Summary of ISPFMQ functions and panels

• “Clear the queue” on page 86.

• “Clear the queue by ID” on page 86.

• “Clear the queue by Date/Time” on page 88.

• “Clear the queue by String” on page 90.

• “Session Manager” on page 92.

• “Get Server” on page 94.

• ”Put Server” on page 96.

• “Drain Queue” on page 99.

• “Backup and Drain Queue” on page 100.

• “Backup Queue” on page 101.

• “Restore Queue” on page 102.

• “Modify File Options” on page 109.

• “Setup File Attributes panel” on page 112.

• “File record layout” on page 113.

• “Logging Preferences“ on page 114.

• “User Preferences” on page 116.

• “License” on page 118.



Status information Processing panels that invoke MQ functions or invoke file I/O will display a short text message in the upper right corner of the screen. The color of the short text message is dependant upon the MQ return code or the file I/O return code.

A non-zero return code will cause the short message text to be displayed using the ISPF defined “caution text” color. While this message is displayed, pressing PFkey1 (F1) displays the expanded text of the status message in either a box at the bottom of the screen, or underneath the command line, dependant upon your setting of the ISPF option ″Long message in pop-up″.

The following “Message Edit” main panel displays Queue cleared status messages.

Figure 14 – Example status message on the Message Edit panel


Getting Help

Getting Help ISPFMQ offers two levels of help information: context-sensitive field information and tutorial help.

The field help information provides a description of your current field, lists the valid values or range of values that can be entered, and gives the default field value where applicable.

Tutorial help is a context-sensitive help system that provides detailed explanations of the ISPFMQ panels and the processes in which they are used. In addition, all error messages have an associated full text explanation, which can help you to determine the cause of a problem.

Displaying field help information To display the field help information:

• Place your cursor on the field entry line.

• Press the help function key <F1>. The field help information is displayed in a pop-up window.

• When you have finished reading the message press the exit function key <F3> to return to your starting panel.

Accessing tutorial help The tutorial help system is both context-sensitive and structurally organized. You can get directly to the information you need, using the context-sensitive access method or you can enter the Help system at a specific location and navigate to any topic information within the structure.

To access a context-sensitive tutorial help page:

• Place your cursor on the command line or anywhere in the panel that is outside of a field entry line.

• Press <F1>. The tutorial help page associated with the current panel is displayed. When you access the tutorial help in this way, the first page that is displayed may be a main topic page, with a menu listing the associated sub-topics, or it may be a sub-topic page, depending upon the context from which you started.

• Navigate through the tutorial help pages, to find the information you require (see below for a list of navigation commands).

• When you have finished, press <F3> (Exit) to return to your starting panel.



The tutorial help system is organized with a Table of Contents structure that is based upon the ISPFMQ Primary Options menu. Each entry within the Table of Contents leads to a main topic with a number of associated sub-topics.

Viewing error messages If an error occurs when ISPFMQ attempts to process a panel, a short text message displays in the upper right corner of the screen. While this message is displayed, pressing F1 displays the expanded text of the error message in either a box at the bottom of the screen, or underneath the command line, dependant upon your setting of the ISPF option ″Long message in pop-up″.

Profile Information ISPFMQ will reread your ISPF profile information upon startup and save ISPF profile information when shutting down. Profile information such as:

• QManager name

• Queue name

• File names (log, get, put, backup, restore, import and export)

Profile information is stored in your ISPF profile dataset and can be found in member ISMQPROF.

Connecting to the QManager Whenever you open a queue, ISPFMQ automatically connects to the Queue Manager specified in you Profile.

You can optionally change the QManager when:

• You monitor queues by invoking the Queue Monitor panel, command line option “TM”, see “Monitor Tools” on page 102 for additional information.

• You open a queue by invoking the Open Queue panel, command line option “F.1”, see “Opening the queue” on page 81 for additional information.


Selecting and opening a queue to edit messages

Selecting and opening a queue to edit messages From the ISPFMQ main panel, you can edit messages either by positioning your cursor on “Edit Message” and pressing <ENTER>, or by entering the command line option “E” (“ME” from other panels).

You will then be presented with the Open Queue panel where you specify a QMgr name and Queue name.

Figure 15 – Selecting and opening a queue to edit messages

Licensing You require a valid license in order to use ISPFMQ. There are two types of ISPFMQ licenses: Temporary and Permanent.

ISPFMQ will stop operating when a temporary license expires. ISPFMQ will continue to operate when a permanent license expires, but you will not be eligible for code updates or program support.

For information regarding the ISPFMQ license you are using see “License” on page 118.


Chapter 3. Edit Messages

Chapter 3. Edit Messages This chapter describes the “Edit Messages” functions used for viewing, editing, creating, deleting, moving, importing, exporting and working with the MQMD header of messages from a WebSphere MQ queue. To edit messages enter primary command “ME” or option “E” when on the primary options panel.


• “Message Edit - panel” on page 33.

• “Editing Messages” on page 34.

Message Edit - panel The Message Edit panel provides both selection options and primary commands for working with messages.

Figure 16 – Message Edit panel

Chapter 3. Edit Messages 33

Editing Messages

Press <PF1> from the Message Edit panel, where you can review the entire Message Edit tutorial or select option “1” to display “Message selection and command options”.

Figure 17 – Message selection and command options

Editing Messages To view data stored in a WebSphere queue you use the Message Editing functions to view and/or change your data.

The tasks described in this function section are:

• “Displaying message data” on page 36.

• “Changing your view of message data” on page 37.

• “Scrolling to see data“ on page 39.

• “Sorting the data” on page 40.

• “Finding specific message data” on page 40.

• “Selecting a message” on page 41.

• “Delete message” on page 42.

• “Replicate message” on page 44.

• “Cut message” on page 46.

• “Copy message” on page 48.



• “Paste message” on page 50.

• “View message” on page 52.

• “Edit message” on page 54.

• “XML edit message” on page 56.

• “Insert message” on page 58.

• “Export message” on page 60.

• “Forward message” on page 63.

• “MQMD message” on page 66.

• “Working with other header types” on page 73.

NOTE: Use the export message function when you wish select individual messages to be saved to a file. Use the block export message function when you wish select a visible block of messages to be saved to a file. Use the backup function when you want to specify a numeric range of messages to be saved to a file.


Editing Messages

Displaying message data From the ISPFMQ edit messages panel, queued messages are listed as selectable rows.

You can alter the default “message data only” view so that you can also review:

• Twenty eight MQMD fields such as Message id, Correlation id, Put Date, Put Time, etc

• Message data – the first <User Selectable> bytes – and message length (MSGLN)

The following figure lists the eight imported messages found in the example queue, CSQ1/AAAA.TESTQ1.

Figure 18 – Default message “data only” view when first editing a queue



Changing your view of message data Once your data has been displayed in the edit panel, you can optionally change the logical data view to focus on the fields of interest to you.

Primary commands used to manipulate the logical view You can enter primary commands on the command line of the edit panel to perform the following functions:

• Scroll the list with: BOTTOM, TOP, DOWN, UP

• Find a string: FIND

• Adjust the order of lines: SORT

• Change the logical view: COLS, HIDE, SELCOL, SHOW

• Scroll a field: TRIGHT, TLEFT

Select the field data you want to be displayed using the SELCOL command

Place a ‘/’ on fields you wish to be displayed and press <PF3>.

Figure 19 – Message view after invoking the SELCOL command


Editing Messages

Results of the SELCOL command Selected fields alter the default “message data only” view providing a logical view of the data. This logical view maps selected fields into columns which are in turn part of numbered screens. The number of screens depends on the fields selected.

Use primary command TRIGHT or <PF11> to tab to the screen to the right or primary command TLEFT or <PF10> to tab to the screen to the left.

Press <PF11> to see the 2nd of three screens.

Press <PF11> to see the third of three screens.

Figure 20 – View of data after invoking the “SELCOL” command



Toggling your view of the data You can switch back to the message only (default) data view using the HIDE command.

The SHOW command will re-display the SELCOL panel specified fields.

COLS will toggle between HIDE and SHOW data formats.

Scrolling to see data To scroll through your data, use the following function keys:

Use this function key To do this …

Repeat find Repeat find function key <PF5>

Scroll backward (up) Up function key <PF7>

Scroll forward (down) Down function key <PF8>

Scroll right, while cursor on field Right function key <PF11>

Scroll left, while cursor on field Left function key <PF10>

Yours truly, can also scroll using the primary commands UP, DOWN, TOP and BOTTOM.

Controlling how far you scroll Scroll amount Scrolls …

PAGE One screen at a time

HALF Half a screen at a time

CSR To the cursor position (if the cursor is not positioned on a record when the scroll is performed, then the scroll amount defaults to PAGE)

MAX To the end of the data in the direction indicated by the scrolling function key

Nnnn A number of columns (when scrolling left or right) or a number of records (when scrolling up or down) at a time

Scrolling to the first or last record or column To scroll to the first or last record or first or last column in the field, type MAX (or M) on the command line, then press one of the scroll function keys. For example, typing M then pressing the Right function key <PF11> scrolls right to the last column of the field that cursor is focused over.

You can also scroll to the first or last record by entering TOP or BOTTOM on the command line.


Editing Messages

Sorting the data Entering a SORT command without a command option returns the display to its default format. To change the order of records, you type in the SORT command followed by command option.

You can sort the displayed data based on the following fields:

• MSG Message data

• MSGID Message id

• CORID Correlation id

• MSGLEN Message length

• DATE Creation Date

For example, to sort the data by message length you would type “SORT MSGLEN” on the command line and press <ENTER>.

Finding specific message data To find one or more occurrences of a character string in the message field area listed, you can use the FIND primary command, which you can abbreviate as F.

For example, to search for the next occurrence of the string “4.1mb”, enter the following on the command line:

F “4.1mb“

NOTE: All string searches are case sensitive.

If the string is found then the displayed top of list will change to the first record containing the found string.



Selecting a message Once your data has been displayed in the edit panel you can select a message using one of the following selection options.

How to select a message You can select a message in one of two ways:

1. Enter a selection option on the selection field to specify a specific action

2. Place the cursor on any of the fields for a given message record and press <ENTER>. You will edit the message if on the edit panel or browse if on the browse panel.

Selection options On the panel selection field you enter selection options to perform the following message actions:

• Delete message D or DD (Block Delete)

• Replicate message R or RR (Block replicate)

• Cut message T

• Copy message C

• Paste message P

• View message V

• Edit message E or XX (Block Export)

• XML edit message L

• Insert a message I

• Export message X

• Forward message F or FF (Block Forward)

• MQMD M


Editing Messages

Delete message

Select the record for deletion Select the message to be deleted with “D” and press <ENTER>.

Figure 21 – Delete the message

You will receive a popup message requiring confirm or cancel of the delete.

Figure 22 – confirm delete

Cancel the delete by pressing <PF12>. Press <ENTER> to delete.



Updated message panel

Figure 23 – Delete the message

The message is deleted and message (Row) count decreased by one.

Block Delete You can block select messages to be deleted by placing a “DD” on the first and last row of the range of message rows to be deleted and press <ENTER>. You will receive a popup message requiring confirm or cancel of the block delete.

Cancel the block delete by pressing <PF12>. Press <ENTER> to delete.


Editing Messages

Replicate message

Select the record for replication Select the message to be replicated with “R” and press <ENTER>.

Figure 24 – Replicate the message.




Figure 25 – Replicated message

The CICS header formatted message has been replicated and will be flagged with “+R+” until the next REfresh command.

Block Replicate You can block select messages to be replicated by placing a “RR” on the first and last row of the range of message rows to be replicated and press <ENTER>. You will receive a popup message requiring confirm or cancel of the block replicate.

Cancel the block replicate by pressing <PF12>. Press <ENTER> to replicate.


Editing Messages

Cut message Select the message to be cut with “T” and press <ENTER>.

Figure 26 – Cut the message




Figure 27 – Cut message

The CICS header format message has been cut to the paste buffer.


Editing Messages

Copy message Select the message to be copied with a “C” and press <ENTER>.

Figure 28 – Copy the message




Figure 29 – Copied message

The 4.1MB message has been copied to the paste buffer and will be flagged with “+C+” until the next REFRESH command.


Editing Messages

Paste message Either primary command “PA” or line selection “P” can be used to paste the message stored in the paste buffer into the queue in focus. Press <ENTER>.

Figure 30 – Paste the message




Figure 31 – Pasted message

The large 4.1MB message has been pasted from the paste buffer and will be flagged with “+P+” until the next REFRESH command.


Editing Messages

View message View message is a line selection option available on the Message Edit panel. To view a message you place a 'V' in the selection area for the message you wish to view. You can also point-and-shoot view the message by placing the cursor anywhere on the message line and press <ENTER>.

When you view a message you can update:

• message data • MQMD data • message headers such as MQMD, MQRFH, MQRFH2, MQIMS,

MQCICS, MQHSAP

Figure 32 – View the message



View message popup panel

Figure 33 – View message panel

The view popup panel presents options to update MSGDATA, MQMD and OTHER4 message header data.

Place a “/” in the desired option selection field (or just place the cursor on the line – point-and-shoot) and press <ENTER>. When working with these message formats see:

• Working_with_message_data on page 55. • Working_with_the_MQMD header data Properties.

• General on page 67. • Report on page 68. • Context on page 69. • Identifiers on page 70. • Segmentation on page 71. • Attributes on page 72.

• OTHER well-known MQ messages formats o MQHRF on page 73. o MQHRF2 on page 74. o MQIMS on page 75. o MQCICS on page 76. o MQHSAP on page 77. o MQDLH on page 78.

essages 4 In this case you are viewing a MQCICS header message. M

created with MQHRF, MQHRF2, MQIMS, MQCICS, MQHSAP, MQDLH or HSAP header formats can be viewed and altered.


Editing Messages

Edit message Select the message to be edited with an “E” and press <ENTER>.

Figure 34 – Edit the message



Working with message data

Figure 35 – Edit message data

ISPFMQ stores MQ data in a temporary ISPF dataset and then invokes the ISPF editor so that you can edit your MQ message.

The ISPF editor is a full screen editor. It displays a full screen of data, and allows you to overtype any data that is being displayed.

You can scroll the data in any direction (up, down, left or right) by a half or full page, or by any number of lines (or columns). Scrolling is performed by means of the scroll commands.

You perform line-oriented editing operations by entering a line command directly on the line that is affected. For example, you type D on a line to delete it or R to replicate it. You can perform commands on several lines at the same time.

When you are finished with your data you can:

1. Enter <PF3> to exit your session. You will be prompted to save any message data changes back to the queue.

2. Enter the CANCEL command on the command line to discard all changes made to your data.


Editing Messages

XML edit message From the message edit panel select the message to be XML edited with “L” and press <ENTER>.

Figure 36 – XML edit the message



XML Edit message data XML Edit displays all of the MQMD header data in markup delimited statements. Only changes made to the message data will be saved. Changes to the MQMD header data are discarded. Use the MQMD panel functions to change the MQMD header data. See “MQMD selection popup panel” on page 66.

Figure 37 – XML edit message data page one of two

The remainder of the XML data can be viewed by paging down, <PF8>

Figure 38 – XML edit message data page two of two


Editing Messages

Insert message Either primary command “IN” or line selection “I” can be used to insert a message into the queue in focus. Press <ENTER>.

Figure 39 – Insert the message



Insert message panel

Figure 40 – Insert message panel

The insert popup panel presents options to create:

• Working_with_message_data - see page 55. • Working_with_the_MQMD header data - see page 66. • MQHRF - Rules and Formatting Header V1 - see page 73. • MQHRF2 - Rules and Formatting Header V2 - see page 74. • MQIMS - IMS Information Header - see page 75. • MQCICS - CICS Information Header - see page 76. • MQHSAP - SAP Information Header - see page 77.

Place a “/” in the message format selection field and press <ENTER>. You will jump to the desired specific panel. Once you have completed updating the message you must return to the calling panel via <PF3>.

Figure 41 – Insert message confirmation request

As last step, you will be prompted to confirm or cancel the message insert.


Editing Messages

Export message Select which message is to be exported with “X” and press <ENTER>.

Figure 42 – Export the message




Respond to the dataset popup

Figure 43 – Dataset popup – specify the file where export data will be saved

From the dataset popup panel you can:

• Accept the name of the dataset where you export the message to. • Change the name of the dataset where you export the message to. • Change the name of the dataset using the ‘*’ and ‘#’ wildcard

characters (standard wildcard usage rules apply)

If the dataset does not exist it will be created using setup panel file attributes. See “Setup File Attributes panel” on page 112.


Editing Messages


Figure 44 – Exported message

The message has been exported and will be flagged with “+X+” until the next REfresh.

Block Export You can block select messages to be exported by placing a “XX” on the first and last row of the range of message rows to be exported and press <ENTER>.

You will be prompted in the same manner as you would when exporting a single message. Namely you will receive a popup message requiring confirm or cancel of the block export followed by popup message panel where you specify the file where the export data will be saved.

Cancel the block export by pressing <PF12>. Press <ENTER> to export.



Forward message Select the message to be forwarded with “F” and press <ENTER>.

Figure 45 – Forward the message

You will be prompted to confirm message forwarding as this action will delete then insert the message. This action can not be undone!


Editing Messages

Respond to the Open Queue panel – specifying the target queue

Figure 46 – Open queue – specify the target queue name

Specify the name of the target queue and press <ENTER>. See “Opening the queue” on page 81.


Figure 47 – Forwarded message

The message has been forwarded to the target queue.

NOTE: The last message selected to be forwarded is also stored in the paste buffer.



Block Forward You can block select messages to be forwarded by placing a “FF” on the first and last row of the range of message rows to be forwarded and press <ENTER>.

You will be prompted in the same manner as you would when forwarding a single message. Namely you will receive a popup message requiring confirm or cancel of the block forward, followed by an Open target queue selection panel.

Cancel the block forward by pressing <PF12>. Press <ENTER> to forward.


Editing Messages

MQMD message Select with “M” and press <ENTER> to display the MQMD selection panel.

Figure 48 – Edit the MQMD header

MQMD selection popup panel From the MQMD popup panel select a MQMD property to work with.



Figure 49 – MQMD selection popup panel

Working with MQMD header properties MQMD header properties are divided into a set of six tabs or panels:

1. General on page 67.

2. Report on page 68.

3. Context on page 69.

4. Identifiers on page 70.

5. Segmentation on page 71.

6. Attributes on page 72.

In addition to the standard free-form input fields, most panels have modifiable list-selected fields denoted by “/” or forward slash.

General The General properties panel is displayed below.

Figure 50 – Working with the MQMD header - General properties panel

You can optionally update the panel input fields. Press <ENTER> to ensure changes are recorded.

Message Type, Message Priority and Message Persistence can only be modified by selecting the corresponding ‘“/” to list’ field which will then display a panel listing potential field values.


Editing Messages

Having reviewed or updated field specific data you must return to the calling panel via <PF3>.

Report The Report properties panel is displayed below.

Figure 51 – Working with the MQMD header - Report properties panel


Options for Report Messages and Feedback Code can only be modified by selecting the corresponding ‘“/” to list’ field which will then display a panel listing potential field values.




Context The Context properties panel is displayed below.

Figure 52 – Working with the MQMD header - Context properties panel


Put Application Type can only be modified by selecting the corresponding ‘“/” to list’ field which will then display a panel listing potential field values.



Editing Messages

Identifiers The Identifiers properties panel is displayed below.

Figure 53 – Working with the MQMD header - Identifiers properties panel





Segmentation The Segmentation properties panel is displayed below.

Figure 54 – Working with the MQMD header - Segmentation properties panel


Message Flag options can only be modified by selecting the corresponding ‘“/” to list’ field which will then display a panel listing potential field values.



Editing Messages

Attributes The Attributes properties panel is displayed below.

Figure 55 – Working with the MQMD header - Attributes properties panel





Working with other header types ISPFMQ supports other well-known MQ messages formats:

• MQHRF - Rules and Formatting Header V1 - see page 73. • MQHRF2 - Rules and Formatting Header V2 - see page 74. • MQIMS - IMS Information Header - see page 75. • MQCICS - CICS Information Header - see page 76. • MQHSAP - SAP Information Header - see page 77.

MQHRF

Figure 56 – Working with the MQHRF data

Update the panel and press <ENTER> to register the updates.

Press <PF3> to return to the Insert or View Message panel. You will be prompted to confirm message updates prior to updating the queue.


Editing Messages

MQHRF2

Figure 57 – Working with the MQHRF2 data





MQIMS

Figure 58 – Working with the MQIMS data




Editing Messages

MQCICS

Figure 59 – Working with the MQCICS data





MQHSAP

Figure 60 – Working with the MQHSAP data




Editing Messages

MQDLH

Figure 61 – Working with the MQDLH data

DLH data can only be reviewed. Press <PF3> to return to the calling panel.


Chapter 4. Edit Messages – File Functions


This chapter describes the functions used in the process of selecting, opening and running utilities on a WebSphere MQ queue.

To work with “Edit Messages – File” functions, you can:

• Select a file function action from the File drop-down menu list found on the Edit Messages panel

• Enter the function specific command “F1” (or “F.1”) through “FA” (“F.A”) on a panel command line.


• “Message Edit - File menu ” on page 80.

• “Opening the queue” on page 81.

• “Refresh the queue” on page 82.

• “Closing the queue” on page 82.

• “Close All” on page 83.

• “Backup the queue” on page 83.

• “Restore the queue” on page 84.

• “Clear the queue” on page 86.

• “Clear the queue by ID” on page 86.

• “Clear the queue by Date/Time” on page 88.

• “Clear the queue by String” on page 90.

Chapter 4. Edit Messages – File Functions 79

Message Edit - File menu drop down list

Message Edit - File menu drop down list The edit messages panel provides options for working with queues via the File menu drop down list.

Figure 62 – Edit Messages - File menu drop down list



Opening the queue There are two ways to open Queues:

a. As part of function, such as “Edit Messages” or “Backup” or “Restore” etc, where you are prompted to open a queue prior to working with messages placed on that queue.

b. Directly invoked via command “F1”5. Enter command “PF6” or option “F” from the Preferences panel to select File Preferences.

As part of the open process, you can optionally retrieve a list of queues from which you select one to work with. You can have up to 100 queue sessions open for processing at any one time.

With each queue opened, you can dynamically control the actual count of messages displayed via the Display Range option. Display Range provides a logical queue window that controls the initial message displayed (lower bound) and count of messages to be displayed (upper bound – lower bound).

Figure 63 – Open queue panel.

5 or “F.1” 6 or “P.F”


Refresh the queue

General panel instructions The Open Queue panel provides options for selecting both a Queue and a Queue Manager to work with. You can enter the names directly or select the Queue from a list by invoking the List Queues function. See “Specifying the types of queues to list” on page 104.

Panel and field definitions Display Range provides a logical queue window that controls the initial message and count of messages displayed.

Queue Monitors allows the user to first list and then select a queue to work with. You can filter the list of queues using the following filter options:

1. Mask - filter by queue name

2. Show System Queues - filter out system queue names

3. Queue Type - filter by queue type

Open Options controls:

1. Convert on Get - convert to MVS readable format

2. Open Read Only - prevents modification to messages

3. Modify Context - when selecting this field you will be presented a selectable list of context options.

Refresh the queue Enter command “F2”, “F.2” or option “2” (from the drop down file menu; found on the message edit main panel) to refresh the contents of the queue in focus. The refreshed queue data will be displayed when you next edit messages on the queue.

NOTE: When in message edit, you can also REfresh the view of messages displayed for the queue in focus by entering the “RE” command.

Closing the queue Enter command “F3”, “F.3” or option “3” (from the drop down file menu; found on the message edit main panel) to close the queue in focus.



Close All Enter command “F4”, “F.4” or option “4” (from the drop down file menu; found on the message edit main panel) to close all of the queues you are working with. You will be returned to the ISPFMQ main panel.

Backup the queue The Backup Queue function will backup messages from the queue under focus into a user specified data set. The number of messages backed up is dependent upon the display range specified when opening the queue and data set file size.


Enter command “F5”, “F.5” or option “5” (from the drop down file menu; found on the message edit main panel) to Backup the queue.

Figure 64 – Backup the queue to a data set.

The user will be prompted to supply the name of a backup data set. You can optionally display a list of filenames by overtyping the name with either the


Restore the queue

positional wild card character ‘#’ or the “match all” wildcard character '*' and then press <ENTER>.

Restore the queue The Restore Queue function restores messages onto the queue under focus. ISPFMQ will attempt to restore all of the messages contained within the file. The actual number of message restored is dependent upon how the queue was opened.

Enter command “F6”, “F.6” or option “6” (from the drop down file menu; found on the message edit main panel) to restore messages to the queue.

Figure 65 – Restore the queue from a data set.

The user will be prompted to supply the name of a restore data set. You can optionally display a list of filenames by overtyping the name with either the positional wild card character ‘#’ or the “match all” wildcard character '*' and then press <ENTER>.



Clear the queue The Clear Queue function will clear all of the messages from the queue under focus.

Enter command “F7”, “F.7” or option “7” (from the drop down file menu; found on the message edit main panel) to clear messages from the queue.

Figure 66 – Clear the queue.

Only press <ENTER> if you are sure that you want to delete the messages specified. Note: There is no undo function for Clear Queue.


Clear the queue by ID

Clear the queue by ID For the queue under focus, the Clear Queue by ID function will clear all of the messages by Message ID Correlation ID or both.

Enter command “F8”, “F.8” or option “8” (from the drop down file menu; found on the message edit main panel) to clear messages by ID from the queue.

Figure 67 – Clear the queue by ID.

Fill in the selection fields:

• Select the search “ID” check box (Message ID and/or Correlation ID) with “/”. • Type the ID “Hex” string value into the ID field. i.e., the Message ID is

selected in the example above.

Changing selection criteria options:

• Enter a forward-slash (“/”) into the “change criteria” field. • Choose a change criteria option, from the option list, by placing “/” in the

selection field. For example, click the "Remove all messages WITH matching ID", to delete all messages that do NOT contain the user specified ID string.

Enter “/” on the “clear the queue” field so as to proceed to the next step. You will be presented a pop-up display summarizing how many of the messages match selection & criteria fields.



Figure 68 – Confirm clearing the queue.

Only press <ENTER> if you are sure that you want to delete the number of messages specified. Note: There is no undo function for Clear Queue.


Clear the queue by Date/Time

Clear the queue by Date/Time For the queue under focus, the Clear Queue by Date/Time function will clear all of the messages by hours or days.

Enter command “F9”, “F.9” or option “9” (from the drop down file menu; found on the message edit main panel) to clear messages by date/time from the queue.

Figure 69 – Clear the queue by date/time.


• Type the number of time units into the “Remove messages older than:” field. i.e., number of Hours in the example above.


• Enter a forward-slash (“/”) into the “change date unit” field. • Choose a change criteria option, from the option list, by placing “/” in the

selection field. For example, click the "Days”, to delete all messages that are older then specified number Days.




Figure 70 – Confirm clearing the queue by Date/Time.



Clear the queue by String

Clear the queue by String For the queue under focus, the Clear Queue by string function will clear all of the messages that match a particular string.

Enter command “FA”, “F.A” or option “A” from the manage queue functions panel to clear messages by search string from the queue.

Figure 71 – Clear the queue by ID.


• Type in the search string i.e., “Test msg” in the example above.


• Enter a forward-slash (“/”) into the “change criteria” field. • Choose a change criteria option, from the option list, by placing “/” in the

selection field. In this case you can control whether string case is used for the string search.




Figure 72 – Confirm clearing the queue by search string.



Session Manager

Chapter 5. Manage Sessions

Session Manager Enter primary command “MS7” or option “S” when on the primary panel to work with active queue sessions.

The Session Manager panel displays a list of active queue sessions and provides functions used to work with those active sessions.

Whenever you invoke the Opening_the_queue function you create an active queue session. You can have up to one hundred active sessions. The following figure displays a scrollable session manager list with five (05) active queues.

From this list you can find, select or close active queue sessions. To select a queue to work with place a '/' in the selection area for that queue. You can also point-and-shoot select, the queue, by placing the cursor anywhere on the queue line and press <ENTER>.

Figure 73 – Session Manager

NOTE: You will jump to Editing_Messages functions panel upon the selection of an active queue.

7 or “M.S”


Chapter 6. Tools

Chapter 6. Tools ISPFMQ has two system load server tools, four move message data and one monitor tool tools. To work with these tools enter command “MT” 8 or option “T” when on the primary options panel.

This chapter provides information about and instructions for using these tools:

• “Load Test Tools” on page 94.

• “Move Message Tools” on page 99.

• “Monitor Tools” on page 102.

Figure 74 – Tools functions panel

8 or “M.T”

Chapter 6. Tools 93

Load Test Tools

Load Test Tools If you want to performance test a MQ application, consume messages in a controlled manner where you specify inter-message delay or collect messages to be replayed then you would use the “Get Server” function.

If you want to performance test a MQ application or simply load the queue in a controlled manner where you specify inter-message delay, with multiple messages stored in a file, then you would use the “Put Server” function. You can optionally put static message data on the queue via Screen Data panel field.


• “Get Server” on page 94.

• ”Put Server” on page 96.

Get Server Get Server consumes messages from the queue in a controlled manner using configurable inter-message delay times and commit intervals. It can be used to performance test a MQ application, collect messages to be replayed or simply to drain the queue. To work with Get Server: enter primary command “TG9” or option “G” on the Tools options panel.

9 or “T.G”


Chapter 6. Tools

Get Server Entry panel

Figure 75 – Get All Message Entry panel

General panel instructions Get Server will consume messages when you change “How many messages to Get?” from zero (0) to a specific message count or ‘*’ to retrieve all of the messages on the queue. The retrieved messages including MD values can be optionally stored into a file if when you type ‘/’ into the “Store messages in file?” prior to message retrieval.

You control threshold values such as number of messages to get, how often to commit, inter-message delay (i.e. wait time) and popup display of intermediate response time and message counts with the remaining panel selection fields.

Message counts, response time, MQ return code and status will be displayed when the function completes.

Panel and field definitions Get Options: How many messages to Get

Enter a “high water” message count or ‘*’ to get all of the messages on the queue. When updated, ISPFMQ will attempt to retrieve the message from the queue. The actual count is governed by User Preferences Maximum Message Count - Get Server field or by the actual count of messages upon the queue

Get Options: Drain the queue

Chapter 6. Tools 95

Load Test Tools

Destructively get the messages from the queue.

Get Options: Commit every this many messages

When ISPFMQ gets a message from a queue within a unit of work, that message is remains visible to other programs until ISPFMQ commits the unit of work.

File Options: Format of messages in file

ISPFMQ can work with two types of messages RAW or XML.

• RAW: the entire file record is treated as message data. • XML: the file record is processed as a XML structure. A structure

made up of start and finish markers, MD values and message data. • See “File record layout“, page 113, for additional information.

File Options: Store messages in file

ISPFMQ will write out message data into the Get file specified on “Modify File Options“, page 109.

Control Options: Inter-message delay

You can specify inter-message delay10 or wait time in increments of one hundredths of a second (100 = 1 second, 1000 = 10 seconds) starting with zero.

Control Options: Dashboard popup

The dashboard popup provides intermediate performance data such as response time and message counts during the running of a Get Server session.

Put Server Put Server places messages onto a queue in a controlled manner using configurable inter-message delay times and commit intervals. It can be used to performance test a MQ application or simply load the queue with multiple messages stored in a file. To work with Put Server: enter primary command “TP11” or option “P” on the Tools options panel.

10 Time difference between completing a put message request and starting the next put message

request. Also known as wait time. 11 or “T.P”


Chapter 6. Tools

Put Server Entry panel

Figure 76 – Put Server entry panel

General panel instructions Put Server will place messages onto the queue when you change “How many messages to Put?” from zero (0) to a specific message count or ‘*’ to place all of the messages on the queue. All message data must either come from a file or entered as static data on the entry screen.

The stored messages including MD values can be optionally be retrieved from a file. When you type ‘/’ into the “Load message with screen data” field, message data will reflect the static data entered on the Screen Data entry field.

You control threshold values such as number of messages to put, how often to commit, inter-message delay (i.e. wait time) and popup display of intermediate response time and message counts with the remaining panel selection fields.

Message counts, response time, MQ return code and status will be displayed when the function completes.

Panel and field definitions Put Options: How many messages to Put

Enter a “high water” message count or ‘*’ to put all of the messages, contained in the file or on the screen, onto the queue. The actual count is

Chapter 6. Tools 97

Load Test Tools

governed by User Preferences Maximum Message Count - Put Server field.

Put Options: Commit every this many messages?

When ISPFMQ Puts a message onto a queue, that message is remains invisible to other programs until ISPFMQ commits the unit of work.

File Options: Format of messages in file

ISPFMQ can work with two types of messages RAW or XML.

• RAW: the entire file record is treated as message data. • XML: the file record is processed as a XML structure. A structure

made up of start and finish markers, MD values and message data. • See “File record layout“, page 113, for additional information.

ISPFMQ will read messages from the Put file specified on “Modify File Options“, page 109.

Data Options: Load message with Screen Data

ISPFMQ tells to ignore file input and to use data specified on the Screen Data field as message data.

Screen Data

User specified data used as message data.

Control Options: Inter-message delay

You can specify inter-message delay12 or wait time in increments of one hundredths of a second (100 = 1 second, 1000 = 10 seconds) starting with zero.

Control Options: Dashboard popup

The dashboard popup provides intermediate performance data such as response time and message counts during the running of a Put Server session.

12 Time difference between completing a put message request and starting the next put message

request. Also known as wait time.


Chapter 6. Tools

Move Message Tools Move Message Tools are used to move messages from/to a queue into/from a file and to drain a queue.


• “Drain Queue” on page 99.

• “Backup and Drain Queue” on page 100.

• “Backup Queue” on page 101.

• “Restore Queue” on page 102.

Drain Queue Enter command “TD”, “T.D” or option “D” (from the Tools drop down file menu; found on the Tools main panel) to drain messages from a queue.

The actual number of messages drained is governed by:

• User Preferences Maximum Message Count - Get Server field.

• How the queue was opened.

Chapter 6. Tools 99

Move Message Tools

You will be prompted to select a queue. See “Opening the queue” on page 81 for additional information.

Once the queue is opened, you will be prompted to confirm draining the queue (DESTRUCTIVELY get messages)

Figure 77 – Confirm draining the queue.

Press <PF12> to cancel or Press <ENTER> to proceed.

Backup and Drain Queue Enter command “TU”, “T.U” or option “U” (from the Tools drop down file menu; found on the Tools main panel) to backup and drain messages from a queue

The actual number of messages, backed up and drained, is governed by:

• Attributes of the backup.




Once the queue is opened, a prompt will be displayed asking for the name of a backup data set.13

13 You can optionally display a list of filenames by overtyping the name with either the positional

wild card character ‘#’ or the “match all” wildcard character '*' and then press <ENTER>.


Chapter 6. Tools

Figure 78 – Confirm draining the queue.

Once the queue and backup file are opened, you will be prompted to confirm draining the queue (DESTRUCTIVELY get messages).

Press <PF12> to cancel or Press <ENTER> to proceed.

Backup Queue Enter command “TB”, “T.B” or option “B” (from the Tools drop down file menu; found on the Tools main panel) to backup messages from a queue.

The actual number of messages, backed up is governed by:





Once the queue is opened, a prompt will be displayed asking for the name of a backup data set.14

Press <PF12> to cancel the backup. Press <ENTER> to backup.

14 You can optionally display a list of filenames by overtyping the name with either the positional

wild card character ‘#’ or the “match all” wildcard character '*' and then press <ENTER>.

Chapter 6. Tools 101

Monitor Tools

Restore Queue Enter command “TR”, “T.R” or option “R” (from the Tools drop down file menu; found on the Tools main panel) to restore messages from a file into the queue.

The actual number of messages, backed up is governed by:





Once the queue is opened, a prompt will be displayed asking for the name of a restore data set.15

Press <PF12> to cancel the restore. Press <ENTER> to restore.

Monitor Tools

Queue Monitor

Enter command “TM16” or option “M” from the Tools functions panel to start the Queue Monitor function. With Queue Monitor you can:

• Select a queue to work with

• View all of the queues defined to the QManager. Displayed information includes:

1. Queue Name

2. Queue Depth

3. Queue Type

4. Get Enabled

5. Put Enabled

6. IpProc

7. OpProc 15 You can optionally display a list of filenames by overtyping the name with either the positional

wild card character ‘#’ or the “match all” wildcard character '*' and then press <ENTER>. 16 Or “T.M”


Chapter 6. Tools

8. Queue has an active edit session indicator

Figure 79 – Queue selection panel

Panel and field definitions Command options

In addition to entering screen navigation primary commands you can:

• Find a string in scrollable view area.

Sel

Queue column selection field used to tell ISPFMQ which queue is to be selected for update.

Queue Name

The queue name and a point and shoot selection field.

Queue Depth

Number of messages contained with in the queue.

Queue Type

Type of queue.

Get Enabled

Is the queue enabled for Get.

Put Enabled


Monitor Tools

Is the queue enabled for Put.

IpProc

Number of applications that have the queue open for Input.

OpProc

Number of applications that have the queue open for Output.

Specifying the types of queues to list Prior to seeing the list of queues you are presented with Queue Monitor specification panel that allows you to tailor the types of queues you wish to display.

Figure 80 – Queue specification panel


Chapter 6. Tools

Panel and field definitions Mask

Queue name filter.

Show System Queue

System queues are not displayed by default. Specify a ‘/’ to display system queues.

Queue Type

You can filter the queue types to be displayed.

Modifying your view of queue data Once your data has been displayed, you can optionally change the view to focus on the fields of interest to you.

Using primary commands when viewing queue data You enter primary commands on the panel command line to perform:

• Scroll the list with: BOTTOM, TOP, DOWN, UP

• Find a string: FIND

Scrolling to see data To scroll through your data, use the following function keys:

Use this function key To do this …

Repeat find Repeat find function key <PF5>

Scroll backward (up) Up function key <PF7>

Scroll forward (down) Down function key <PF8>

Scroll right, while cursor on field Right function key <PF11>

Scroll left, while cursor on field Left function key <PF10>

You can also scroll using the primary commands UP, DOWN, TOP and BOTTOM.

Scrolling to the first or last record or column To scroll to the first or last record or first or last column in the field, type MAX (or M) on the command line, then press one of the scroll function keys. For


Monitor Tools

example, typing M then pressing the Right function key <PF11> scrolls right to the last column of the field that cursor is focused over. You can also scroll to the first or last record by entering TOP or BOTTOM on the command line.

Finding specific queue data To find one or more occurrences of a character string in the names listed, you can use the FIND primary command, which you can abbreviate as F.

For example, to search for the next occurrence of the string “SYSTEM”, enter the following on the command line:

F “SYSTEM”

NOTE: All string searches are case sensitive.

If the string is found then the displayed top of list will change to the first record containing the search string. Use <PF5> to move through the list.


Chapter 6. Tools

Select a queue Once your data has been displayed in a queue selection panel, you can select a queue of interest to you.

Selection options On the panel selection field you enter selection options to perform the following queue actions:

• Select a queue: / You can also select a queue by placing the cursor on any of the fields for a given queue record and press <ENTER>.

Select a queue Select a queue using the “/” selection option or position cursor on the queue name and press <ENTER>.

Figure 81 – Select a queue - Update generated name and parameters

The queue is selected and panel focus returns to the calling process.


Monitor Tools

Chapter 7. Preferences You can customize various operational aspects of ISPFMQ via the Preferences panel (command line “MP”). There are three preference areas:

1. Modify File Options (page 109) invoked via command “PF”

2. Logging Preferences (page 114) invoked via command “PL”

3. User Preferences (page 116) invoked via command “PU”

Figure 82 – Preferences - Menu


Chapter 7. Preferences

Modify File Options Enter command “PF17” or option “F” from the Preferences panel to select File Preferences.

Sequential and PDS files are used as a data-store for many ISPFMQ functions. The Modify File Options panel is used define file names and file allocation attributes. These file attributes are stored in your ISPF profile which is reread and the attributes re-used when ISPFMQ starts up.


• “Modify File Options panel” on page 109.

• “Setup File Attributes panel” on page 112.

• “File record layout” on page 113.

Modify File Options panel Within the modify options panel you update:

• Global high-level name for all of the files • Selection area to invoke file attributes panel • Function specific files names that are created/updated/renamed either

in setup or as part their associated function process:

1. Message Edit Export function (output)

2. Get Server function (output)

3. Backup function (output)

4. Log file. (output – required file)

5. Message Edit Import function (input)

6. Put Server function (input)

7. Restore function (input)

17 Or “P.F”

Chapter 7. Preferences 109

Modify File Options

Figure 83 – File options panel – review and update values

General panel instructions Review or update file options panel data and press <ENTER> to save the data then <PF3> to exit the panel.

Panel and field definitions Modify - High level name

The high level name provides a convenient way to update the dataset names for all of the external files at the same time, with the only exception being the log file. The high level name field defaults to the users TSO id.

Modify – Modify File Attributes

Select this field to invoke the File Attributes panel

File Information - action options

Once your profile information has been displayed in the file options panel, you can work with the files (NOTE: log file cannot be edited from with ISPFMQ).

When you or a ISPFMQ function make a request to open a file for I/O (i.e. Input, Output or Edit); ISPFMQ will do so immediately if the file already exists. ISPFMQ will attempt to create the file if it doesn’t exist, using file setup information found on the File Attribute panel on page 112.



On the file action field you enter action options to perform the following file actions:

• List the file: L

• Open the file: O

• Close the file: C

• Delete a file: D

• Edit a file: E

The standard ISPF editor is used when editing a file. The file will be closed once you have finished edit.

File Information - Export file (Output)

Message Edit – Export function uses this file to store message data.

NOTE: data will be stored in its RAW format (message payload only). No header information is stored.

File Information - Get message file (Output)

Get Server function uses this information to store message data.

File Information - Backup file (Output)

Backup function uses this information to store message data.

File Information - Log file (Output)

The log file is the only required external file and will be automatically created. ISPFMQ controls access to the log file, using it to store ISPFMQ operational information.

The user has control over the log file name.

NOTE: The name change will only become active upon a restart of ISPFMQ.

File Information - Import file (Input)

Message Edit – Import function uses the message data stored in this file when putting messages on the queue.

NOTE: data should be stored in its RAW format (message payload only).

File Information - Put message file (Input)

Put Server uses the message data stored in this file when putting messages on the queue.

File Information - Restore file (Input)

Restore function uses the message data stored in this file when putting messages on the queue.


Modify File Options

Setup File Attributes panel To review or to update the default parameters for your files type a ‘/’ in the “Modify File Attributes” on the modify options panel field and press <ENTER>.

Figure 84 – Setup file attributes panel – review and update values

General panel instructions Review or update file attributes and press <ENTER> to save the data then <PF3> to exit the panel.

Panel and field definitions File allocation parameters

All files have the same LRECL=25004 and RECTYP=VB. The user can update DSORG, BLKSIZE, UNITS, SPACE and DIRBLKS parameters as required.

When starting out, most users find that the default values work for them. You may have to change the parameters if you intend to work with many messages or if they are large messages.



File record layout ISPFMQ files use a 25KB record size. The record format is variable blocked (VB) so as to effectively store variable sized messages. VB files incur a four byte minimum record size no matter the amount of data stored in that record. That is to say blank records will require four bytes of storage.

Messages greater than 25KB in size, up to the MQ maximum size of 4.2MB, span multiple 25KB records.

Messages can be written/read from the files in one of two data-store formats: RAW or XML. All message data, regardless of data-store format, must be separated by a blank line. ISPFMQ uses this blank line as a message delimiter.

RAW formatted message data is written out “as is”. In short, it only contains the message payload (message data) but none of the MD header data.

XML format stores both MD header data and message payload data in a markup language structure.

The following table lists the function and associated data format.

Function RAW XML

Backup (Y)

Export (Y)

Get Server (Y) (Y)

Import (Y)

Put Server (Y) (Y)

Restore (Y)


Logging Preferences

Logging Preferences Enter command “PL18”or option “L” from the Preferences panel to select Logging Preferences.

The Logging Preferences panel is used to select what MQ API calls or ISPFMQ function calls, if any, are recorded in the log file.

Figure 85 – Logging Preferences

General panel instructions Select fields with ‘/’ then press <ENTER> to save values or <PF3> to exit the panel.

NOTE: Administrator selected fields supersede user selected fields and as such cannot be modified by the user.

Panel and field definitions MQ API calls:

Get Message (ReadOnly)

Record the mqRc, Queue Name, Message Time, Message ID, Correlation ID, Group ID, message length and the first 64 bytes of the get message that has been non-destructively retrieved from the queue.

18 Or “P.L”



Get Message (Destruct)

Record the mqRc, Queue Name, Message Time, Message ID, Correlation ID, Group ID, message length and the first 64 bytes of the get message that has been destructively retrieved from the queue.

Put Message

Record the mqRc, Queue Name, Message Time, Message ID, Correlation ID, Group ID, message length and the first 64 bytes of the put message.

Open Queue

Record the mqRc, Queue Manager Name, Queue Name and value of the OpenOptions used to open the queue.

Close Queue

Record the mqRc, Queue Manager Name and Queue Name.

Tools:

Get Server

Record mqRc, Get Server statistics such as message count, total run time and average response time.

Put Server

Record mqRc, Put Server statistics such as message count, total run time and average response time.


User Preferences

User Preferences Enter command “PU19” or option “U” from the Preferences panel to select User Preferences.

The User Preferences panel is used to modify ISPFMQ behavior by selecting the desired behavior settings.

Figure 86 – User Preferences

General panel instructions Update fields then press <ENTER> to save values or <PF3> to exit the panel.

19 Or “P.U”



Panel and field definitions Display:

"Empty" queue message

When first opening the queue, you will be notified that the queue is empty.

Show Edit commands and options:

Queue is empty

When first opening the queue, you will be notified that the queue is empty.

Queue session comes into focus

Display available edit commands and selection options whenever a queue session comes into focus.

Modify message edit options

Message window size

Display available edit commands and selection options whenever a queue session comes into focus.

Display detailed prompt information:

When backing up a queue

Display detailed prompt information when backing up a queue to a file.

When restoring a queue

Display detailed prompt information when restoring a queue from a file.

When importing messages

Display detailed prompt information when importing messages into a queue.

When exporting messages

Display detailed prompt information when exporting messages from a queue to a file.

When getting messages

Display detailed prompt information when getting messages from a queue and writing them into a file

When putting messages

Display detailed prompt information when reading messages from a file and putting them on to a queue.


User Preferences


Modify Message Edit options:

Message window size

For each row in the ISPFMQ database, read and store the first "window size" number of characters.

Scroll Amount

The scroll amount used when paging through the list of messages.

Modify function options:

Maximum Message Count - Get Server / Clear (by ID, Date and String) / Drain

Maximum number of messages retrieved from the queue that these functions will process before user response is required.

Maximum Message Count - Put Server

Maximum number of messages placed on the queue that this function will process before user response is required.

License The License key is the mechanism by which ISPFMQ determines how it is to operate for any particular Queue Manager. The license information displayed is:

• Product type

• License type

• Status

• Expiry date

• Release version

• License version

Appendices - Support

Appendices

Support Online Help Desk Ticketing System at http://www.capitalware.biz/phpst/

By email at:

mailto:[email protected]

By regular mail:

Capitalware Inc.

Attn: ISPFMQ Support

1673 Richmond Street, Suite 524

London, Ontario

N6G 2N3

CANADA

By phone:

+1-226-980-7307

. ISPFMQ for z/OS V1R2 User’s Guide 1

http://www.capitalware.biz/phpst/

mailto:[email protected]

Appendices - Notices

Notices This information was developed for products and services offered worldwide. Consult your local Capitalware representative for information on the products and services currently available in your area. Any reference to a Capitalware product, program, or service is not intended to state or imply that only that Capitalware product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any Capitalware intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-Capitalware product, program, or service.

Capitalware may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

Capitalware Inc.

Attn: ISPFMQ Support

1673 Richmond Street, Suite 524

London, Ontario

N6G 2N3

CANADA

The information contained within this document could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. Capitalware may make improvements and/or changes in the product(s) and/or the program(s) described in this at any time without notice.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact the address listed above.

© Copyright Capitalware Incorporated 2012. All rights reserved. 2

Appendices - Trademarks

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by Capitalware under terms of the Capitalware Customer Agreement, Capitalware International Program License Agreement, or any equivalent agreement between us.

Information concerning non-Capitalware products was obtained from the suppliers of those products, their published announcements or other publicly available sources. Capitalware has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-Capitalware products. Questions on the capabilities of non-Capitalware products should be addressed to the suppliers of those products.

All statements regarding Capitalware’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

Trademarks IBM, MQSeries, MVS, OS/390, REXX, ISPF, TSO, WebSphere, WebSphere MQ and z/OS are trademarks of International Business Machines Corporation.

zISPPFMQ, ISPFMQ, zMQTSTR and MQTSTR are trademarks of Salem Software Incorporated.


Glossary - Index

Glossary

Index Backup and Drain Queue, 100 Backup Queue, 101 Drain Queue, 99 F1

Open Queue, 81 F2

Refresh Queue, 82 F3

Close Queue, 82 F4

Close All Queues, 83 F5

Backup Queue in focus, 83 F6

Restore into the Queue in focus, 84 F7

Clear Queue, 85 F8

Clear Queue by ID, 86 F9

Clear Queue by Date/Time, 88 FA

Clear Queue by String, 90 File

Functions and associated data format, 113 File Preferences, 109

Modifying file options, 109 Record layout, 113

Get Server, 94 message window count, 118

License Information, 118

Logging Preferences, 114 ME

Message Edit, 33 Message Edit

Available functions, 34 Changing your view of message data, 37 Editing messages, 34 File Function

Backing up the Queue, 83

Clear the Queue, 85 Clear the Queue by Date/Time, 88 Clear the Queue by ID, 86 Clear the Queue by String, 90 Closing all of the Queues, 83 Closing the Queue, 82 Opening the Queue, 81 Refresh the Queue, 82 Restoring the Queue, 84

File Function menu, 80 Main panel, 33 Message window, 118 MQMD, 66

Main selection panel, 66 Properties

Attributes, 72 Context, 69 General, 67 Identifiers, 70 Paste, 71 Report, 68

Working with MQMD header properties, 67

Scroll amount, 118 Select the field data you want to be displayed

using the SELCOL command, 37 Selecting a message with message action

Selection options, 41 Selection options

(C)opy, 48 (C)ut, 46 (D)elete, 42 (E)dit, 54 (F)orward, 63 (I)nsert, 58 (M)QMD, 66 (P)aste, 50 (R)eplicate, 44 (V)iew, 52 E(X)port, 60 XM(L) Edit, 56

Working with other header types, 73 MQCICS, 76

© Copyright Capitalware Incorporated 2012. All rights reserved. 4

Glossary - Index


MQDLH, 78 MQHRF, 73 MQHRF2, 74 MQHSAP, 77 MQIMS, 75

MP Preferences Main panel, 2, 108

MQCICS – CICS Information Header, 76 MQDLH – Dead Letter Header, 78 MQHRF - Rules and Formatting Header V1, 73 MQHRF2 - Rules and Formatting Header V2, 74 MQHSAP – SAP Information Header, 77 MQIMS - IMS Information Header, 75 MS

Manage Sessions, 2, 92 Other header types

MQCICS, 76 MQDLH, 78 MQHRF, 73 MQHRF2, 74 MQHSAP, 77 MQIMS, 75

PF File Preferences, 109

PL Logging Preferences, 114

Preferences Preferences Main panel, 108

PU User Preferences, 116

Put Server, 96 Message window count, 118

Queue Backup, 83 Clear, 85 Clear by Date/Time, 88 Clear by ID, 86 Clear by String, 90 Close All, 83 Closen, 82 Open, 81

Refresh, 82 Restore, 84

Queue Monitor, 102 Restore Queue, 102 Session Manager, 92 Starting ISPFMQ

Region Size, 17 TB

Backup Queue, 101 TD

Drain Queue, 99 TG

Get Server, 94 TM

Queue Monitor, 102 Tools

Backup and Drain Queue, 100 Backup Queue, 101 Drain Queue, 99 Get Server, 94 Load

Get Server, 94 Put Server, 94

Monitor Queue Monitor, 102

Put Server, 96 Queue Monitor, 102 Restore Queue, 102

TP Put Server, 96

TR Restore Queue, 102

TSO Region size use 16MB when working with MB sized

messages., 17 TU

Backup and Drain Queue, 100 User Preferences, 116

Modify what prompt information is displayed, 117