IBM CICS Explorer

Home , Explorer 19, Explorer 45

Front cover

IBM CICS Explorer

CICS Explorer is the new modern face of CICS

CICS Deployment Assistant is the new way to manage

CICS Explorer real-life usage scenarios included

Chris Rayns George Bogner Nicholas Bingell Gordon Keehn Lisa Fellows Tommy Joergensen Erhard Woerner

ibm.com/redbooks

International Technical Support Organization

IBM CICS Explorer

December 2010

SG24-7778-01

Note: Before using this information and the product it supports, read the information in “Notices” on page xi.

Second Edition (December 2010)

This edition applies to Version 4, Release 1, CICS Transaction Server. © Copyright International Business Machines Corporation 2010. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents

Notices ...... xi Trademarks ...... xii

Preface ...... xiii The team who wrote this book ...... xiii Now you can become a published author, too! ...... xv Comments welcome...... xv Stay connected to IBM Redbooks ...... xvi

Summary of changes ...... xvii August 2010, Second Edition ...... xvii

Part 1. CICS Explorer Introductions ...... 1

Chapter 1. CICS Explorer introduction ...... 3 1.1 Overview ...... 4 1.2 Base Explorer capabilities ...... 5 1.3 Plug-ins and RCP ...... 9 1.3.1 Eclipse concepts ...... 9

Chapter 2. Getting started with CICS Explorer...... 19 2.1 Using CICS Explorer with CICS TS 4.1...... 20 2.2 CICS Explorer connection to CICS ...... 20 2.2.1 Connecting CICS Explorer to a CICS region ...... 20 2.2.2 Connecting CICS Explorer to CICSPlex SM ...... 21 2.3 Setting up single-server access ...... 22 2.4 Setting up CICSPlex SM for CICS Explorer ...... 25 2.4.1 Basics of setting up CICSPlex SM for CICS Explorer...... 25 2.4.2 Changing a System into a CMAS ...... 27 2.4.3 Changing a system into a WUI server...... 33 2.4.4 Creating a CICSplex to manage your systems ...... 38 2.4.5 Modifying your existing CICS system JCL ...... 40 2.4.6 Conclusion ...... 41 2.5 Updating an existing CICSPlex SM setup for CICS Explorer ...... 42

Chapter 3. Implementing IBM CICS Explorer ...... 45 3.1 Installing CICS Explorer ...... 46 3.1.1 Installing CICS Explorer locally ...... 46 3.1.2 Installing CICS Explorer remotely ...... 57

3.2.3 Security for a stand-alone CICS Region (SMSS) connection ...... 59 3.2.4 Security for a CICSPlex SM connection ...... 59 3.2.5 Using SSL ...... 59 3.2.6 Using HTTP Basic Authentication ...... 60 3.2.7 CICSPlex Security Scenario ...... 61 3.3 Updating the CICS Explorer ...... 63 3.3.1 Updating from the Internet ...... 64 3.3.2 Updating from an archive file ...... 65 3.3.3 Updating automatically ...... 66 3.4 Enterprise deployment ...... 67 3.4.1 Providing local mirrors...... 67 3.4.2 Pre-installation customization ...... 71 3.5 Using plug-ins ...... 73

Chapter 4. CICS Explorer base familiarization ...... 77 4.1 Perspectives ...... 78 4.2 Connections and credentials ...... 78 4.2.1 Connection Manager...... 78 4.2.2 Connections and Credentials Preference pages...... 80 4.2.3 CICS Explorer connectivity ...... 83 4.3 Views...... 84 4.3.1 The CICSplex Explorer view ...... 84 4.3.2 The CICSplex Repositories view...... 85 4.3.3 CICS Object Table views ...... 86 4.4 The Resources view ...... 89 4.4.1 Properties view ...... 96 4.4.2 Status bar and Error Log...... 96 4.5 Editors ...... 97 4.6 Creating new definitions ...... 104

Chapter 5. CICS Explorer navigation walkthrough ...... 109 5.1 Navigation topics covered ...... 110 5.2 Manipulating views ...... 110 5.2.1 Adding a view ...... 110 5.2.2 Zooming in and out of a view ...... 112 5.2.3 Refreshing a view ...... 112 5.2.4 Resizing a view ...... 113 5.2.5 Repositioning a view ...... 114 5.3 Manipulating columns ...... 115 5.3.1 Customizing columns ...... 115

iv IBM CICS Explorer 5.3.2 Repositioning columns ...... 117 5.3.3 Resizing columns ...... 117 5.3.4 Equalizing column widths ...... 118

5.3.5 Resetting columns...... 118 5.4 Manipulating filters ...... 118 5.4.1 Using filters ...... 118 5.4.2 Customizing filters...... 119 5.5 Manipulating perspectives...... 120 5.5.1 Creating a perspective ...... 121 5.5.2 Opening a perspective ...... 121 5.5.3 Resetting a perspective...... 122 5.5.4 Deleting a perspective...... 123 5.6 Performing operations functions ...... 124 5.6.1 Performing a program Newcopy ...... 124 5.6.2 Altering CICS region MAXTASKS...... 126 5.7 Performing administration functions ...... 127 5.7.1 Viewing CSD resources ...... 128 5.7.2 Creating CSD resources ...... 129 5.7.3 Installing CSD resources...... 132 5.7.4 Creating BAS resources ...... 133 5.7.5 Viewing the BAS resources...... 135 5.7.6 Installing BAS resources ...... 136 5.8 Summary ...... 136

Chapter 6. CICS Explorer IA plug-in familiarization...... 137 6.1 CICS IA introduction ...... 138 6.2 What CICS IA can do for you ...... 139 6.2.1 CICS IA highlights ...... 139 6.2.2 The questions that CICS IA can answer ...... 140 6.3 Description of CICS IA ...... 140 6.4 CICS IA plug-in overview ...... 143 6.5 Toolbar searches and queries...... 143 6.5.1 Toolbar searches ...... 143 6.5.2 Queries ...... 144 6.6 Programs and Transactions windows ...... 146 6.6.1 Searching programs and transactions ...... 147 6.7 Regions window ...... 148 6.8 Properties window ...... 149 6.9 Supplied queries with CICS IA plug-in ...... 150 6.10 Creating your own queries in the CICS IA plug-in...... 156 6.10.1 Adding filters to the query ...... 158 6.10.2 Modifying an existing query...... 160 6.10.3 Saving your queries in folders...... 161

Contents v 6.10.4 Creating a query folder ...... 162 6.11 Analyzing query and search results ...... 162 6.12 Comparing query and search results ...... 164

Chapter 7. CICS Explorer CM plug-in familiarization...... 167 7.1 CICS CM plug-in overview ...... 168 7.1.1 Setting up the CICS CM plug-in ...... 168 7.2 CM perspective overview ...... 170 7.3 Configurations view ...... 172 7.4 Lists view...... 173 7.5 Groups view ...... 174 7.6 Definitional views...... 176 7.7 Creating, editing, and deleting a resource definition ...... 177 7.7.1 Creating resources ...... 177 7.7.2 Editing a resource ...... 178 7.7.3 Deleting a resource ...... 179 7.7.4 Installing a resource ...... 180 7.8 Adding and removing from groups ...... 180 7.9 History ...... 180 7.9.1 CICS CM journal ...... 180 7.9.2 History View ...... 181 7.10 Searches and the search view ...... 185 7.10.1 Specific searches ...... 185 7.10.2 Using the search dialog...... 185 7.10.3 Search results view ...... 188 7.11 Cleaning up ...... 189

Chapter 8. CICS Explorer PA plug-in familiarization ...... 191 8.1 Overview of CICS PA ...... 192 8.1.1 Runtime product ...... 192 8.1.2 The plug-in ...... 192 8.2 The PA Explorer environment ...... 193 8.3 PA views and editors in detail ...... 195 8.3.1 The Project Explorer ...... 195 8.3.2 The Sheet View...... 197 8.3.3 Pie chart view ...... 199 8.3.4 Bar charts ...... 200 8.3.5 Timeline charts ...... 201 8.3.6 Properties View ...... 204 8.3.7 Integrating with other plug-ins ...... 205 8.4 CSV data extraction process...... 205 8.4.1 Server process ...... 206 8.4.2 Plug-in process ...... 206

vi IBM CICS Explorer 8.5 Database extraction process...... 207 8.5.1 Server process ...... 207 8.5.2 Plug-in process ...... 208

Chapter 9. CICS Explorer TG plug-in familiarization ...... 215 9.1 CICS Transaction Gateway introduction ...... 216 9.1.1 CICS TG products...... 216 9.1.2 CICS Transaction Gateway components ...... 216 9.1.3 The Gateway daemon...... 218 9.2 CICS TG plug-in overview...... 218 9.2.1 CICS TG Explorer view ...... 219 9.2.2 Gateway daemon view ...... 219 9.2.3 CICS connections view ...... 220 9.2.4 Console view...... 220 9.3 Configuration ...... 221 9.3.1 Configuring the CICS TG for the plug-in ...... 221 9.3.2 Configuring the CICS TG plug-in ...... 222

Chapter 10. CICS Explorer Tivoli OMEGAMON XE plug-in familiarization . 225 10.1 Tivoli OMEGAMON XE for CICS Introduction...... 226 10.1.1 Tivoli Enterprise Monitoring Server (TEMS) ...... 226 10.1.2 Tivoli Enterprise Portal Server (TEPS) ...... 226 10.2 CICS Explorer Tivoli OMEGAMON XE plug-in ...... 226 10.2.1 Installation requirements ...... 226 10.2.2 Installing the plug-in ...... 227 10.3 Using the plug-in ...... 228 10.3.1 IBM Tivoli Monitoring Navigation Tree display ...... 228 10.3.2 IBM Tivoli Monitoring Data display ...... 229 10.3.3 IBM Tivoli Monitoring Situations display ...... 230

Chapter 11. CICS Deployment Assistant...... 231 11.1 Introduction to CICS Deployment Assistant ...... 232 11.2 The prerequisites for CICS DA ...... 232 11.2.1 CICS Explorer ...... 232 11.2.2 z/OS host component ...... 232 11.2.3 CICS Transaction Server ...... 232 11.3 Installing the CICS DA components ...... 233 11.3.1 Installing the CICS DA plug-in into CICS Explorer ...... 233 11.3.2 Establishing a connection to a host...... 233 11.3.3 Connection types ...... 236 11.4 Creating a new CICS DA project...... 236 11.4.1 Discovering and creating the system model ...... 237 11.5 Discovering your CICS assets...... 237

Contents vii 11.5.1 Discovering CICS regions ...... 237 11.5.2 Checking the CICS topology ...... 242 11.5.3 Investigating CICS initialization options ...... 243

11.5.4 Viewing CICS-related spool files...... 245 11.5.5 Working with CICS-related data sets and JCL ...... 245 11.5.6 Starting and stopping CICS regions ...... 246 11.5.7 Cloning an existing CICS region ...... 248 11.5.8 Adding a CICS to an existing CICSPlex ...... 250

Chapter 12. WebSphere MQ plug-in ...... 251 12.1 WebSphere MQ plug-in for CICS Explorer ...... 252 12.2 The WebSphere MQ Explorer ...... 252 12.3 CICS Explorer WebSphere MQ plug-in...... 252 12.3.1 Downloading SupportPac CS1Q...... 252 12.3.2 Downloading SupportPac MS0T ...... 253 12.4 Integrating MQ Explorer with CICS Explorer...... 254 12.4.1 Importing CSQ1 into CICS Explorer ...... 254 12.4.2 Copying WebSphere MQ Explorer files into CICS Explorer . . . . . 254 12.4.3 Restarting CICS Explorer ...... 254 12.5 Managing WebSphere MQ resources in CICS Explorer ...... 255 12.5.1 Starting CICS Explorer and switching to WebSphere MQ Explorer perspective ...... 255 12.5.2 Defining and connecting a Queue Manager ...... 255 12.5.3 Hints and tips ...... 258 12.6 Migration issues and versioning ...... 259 12.6.1 Multiple CICS Explorer versions coexisting ...... 259 12.6.2 WebSphere MQ plug-in with new CICS Explorer version installed259 12.6.3 Locating and changing the workspace ...... 260

Chapter 13. CICS Explorer troubleshooting ...... 263 13.1 Common Explorer connection problems ...... 264 13.1.1 Connection not available, CPSMAPI...... 264 13.1.2 Connection must be well-formed...... 266 13.1.3 Connection missing

tag ...... 267 13.1.4 Connection error forbidden ...... 268 13.2 Workspace and logs ...... 269 13.2.1 Capturing trace data ...... 270 13.2.2 Tracing options ...... 271 13.2.3 The Error Log View ...... 272 13.2.4 Viewing the error log in an external application ...... 273 13.3 Preparing error data for IBM service ...... 275 13.3.1 Collecting error data when the CICS Explorer is not usable . . . . . 275 13.3.2 Searching for IBM MustGather information...... 276

viii IBM CICS Explorer 13.4 Plug-in specific issues ...... 276 13.4.1 Performance Analyzer...... 277 13.4.2 CSV file size and CICS Explorer runtime memory ...... 277

Part 2. Scenarios...... 279 Chapter 14. CICS Explorer - MQ application migration ...... 281 14.1 Identifying MQ Applications...... 282 14.2 Obtaining more information about the MAIL transaction ...... 285 14.3 Locating the MQ Application in CICS CM ...... 290 14.4 Looking at performance data for the MAIL transaction ...... 293 14.4.1 Performance data for MAIL on CICS TS V3.1 ...... 293 14.4.2 Performance data for MAIL on CICS TS V4.1 ...... 297 14.5 Can we make the MAIL transaction threadsafe ...... 300 14.6 Using CICS PA to analyze the (threadsafe) MAIL application ...... 309

Chapter 15. CICS Explorer clean up scenario ...... 315 15.1 Orphaned resources ...... 316 15.2 Duplicate resources...... 323

Chapter 16. CICS Explorer performance scenario ...... 329 16.1 Resolving system performance problems ...... 330 16.2 Drilling down into transaction detail...... 334

Chapter 17. CICSPlex SM enablement using the CICS Explorer ...... 345 17.1 Overview of transaction affinities...... 346 17.1.1 Inter-transaction affinity...... 346 17.1.2 Transaction-system affinity ...... 347 17.1.3 Affinity relations...... 347 17.1.4 Affinity lifetimes ...... 348 17.2 Running CICS Interdependency Analyzer for affinities ...... 349 17.3 Loading the DB2 database with the collected affinity data ...... 350 17.4 Using the CICS IA plug-in to identify affinities...... 355 17.5 Workload management considerations ...... 359 17.6 Creating the definitions for workload management ...... 360 17.7 Migrating the definitions using CICS Configuration Manager ...... 362

Chapter 18. CICS Explorer resource manipulation scenarios ...... 367 18.1 Resource locking scenarios ...... 368 18.1.1 VSAM record locking...... 368 18.2 Resource state manipulation...... 372 18.3 Discarding resources...... 380

Related publications ...... 393 IBM Redbooks ...... 393

Contents ix Other publications ...... 393 Online resources ...... 393 How to get Redbooks ...... 394

Help from IBM ...... 394

x IBM CICS Explorer Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM 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: IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information 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. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. 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. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

AIX® MQSeries® Redbooks® CICS Explorer™ MVS™ Redbooks (logo) ® CICSPlex® OMEGAMON® System z® CICS® OS/390® Tivoli® DB2® POWER® VTAM® IBM® RACF® WebSphere® IMS™ Rational® z/OS®

The following terms are trademarks of other companies: Java, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Itanium, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.

xii IBM CICS Explorer Preface

IBM® Customer Information Control System (CICS®) Explorer is the new face of CICS Integration point for CICS tooling with rich CICS views, data, and methods.

Are you looking for new ways to accelerate the transfer of knowledge, skills, and best practices to the next generation of technical staff and experts? Do you need to maintain productivity and protect service-levels? CICS Explorer™ and System z® lead the way to platform simplification.

IBM CICS Explorer has a common, intuitive, Eclipse-based environment for architects, developers, administrators, system programmers, and operators. The task-oriented views provide integrated access to a broad range of data and control capabilities, and it also has powerful, context-sensitive resource editors. Integration point for CICS TS, CICS Tools, CICS TG, PD Tools, and Rational® Tools are extensible by independent software vendors (ISV), system integrators (SI), and customers who use our Software Development Kit.

In this IBM Redbooks® publication, we focus on the new CICS Explorer. The first part of the book is an overview of the CICS Explorer along with all of the CICS Tools’ plug-ins. In the second part of the book, we focus on several scenarios in which you can use the CICS Explorer with the CICS Tools plug-ins to resolve various problems.

The team who wrote this book

This book was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center.

Chris Rayns is an IT Specialist and the CICS project leader at the International Technical Support Organization, Poughkeepsie Center. He writes extensively about all areas of CICS. Before joining the ITSO, Chris worked in IBM Global Services in the United Kingdom as a CICS IT Specialist.

George Bogner is a Software IT Specialist working in IBM Sales and Distribution supporting the CICS Transaction Server product suite. George worked at IBM for 25 years, specializing in the DB/DC area, working with CICS, IMS™, and DB2®, supporting client accounts in IBM Global Services. He currently works out of Raleigh, North Carolina, supporting North American clients by providing CICS seminars, proofs of technology (POT), proofs of concept (POC), and consulting services for CICS-related topics.

© Copyright IBM Corp. 2010. All rights reserved. xiii Nicholas Bingell is a Software Engineer in CICS Level II Technical Support at Research Triangle Park, NC. His areas of expertise isnclude CICS, CICS Explorer, and CICS Tools Interdependency Analyzer. He has a Bachelors degree in Software and Information Systems from The University of North Carolina at Charlotte. Gordon Keehn is an Advisory Software Engineer in the United States. He has 18 years of experience in supporting CICSPlex® System manager. Before becoming involved with CICSPlex SM, he worked as an MVS System Programmer for several large corporations. He has a Bachelor of Arts degree in Chemistry from Hartwick College and a Master of Science degree in Organic Chemistry from the University of Pennsylvania.

Lisa Fellows is the team manager of the Bank of America CICS and MQSeries® Technology Strategy group. Lisa has worked at Bank of America for 28 years, and supported CICS, including CICSPlex, since 1990. She has been a Deputy Project Manager for the SHARE CICS Project since 2001. Lisa began presenting at SHARE in 2000 and is the recipient of multiple Best Session Awards. Her presentations cover a wide range of CICSPlex topics and recently include presentations about CICS Explorer. She currently works out of Clifton Park, New York, accessing emerging CICS and MQSeries technologies for a global Bank of America business partner demographic.

Tommy Joergensen is a Senior IT Specialist working as a Tecnical Presales Specialist for System z software in IBM Nordic with a focus on the CICS TS and WebSphere portfolio. He has more than 25 years of experience working in CICS technical support, which includes three years at IBM Hursley and two years in the New Technology Center in Montpellier. Tommy participated in writing several IBM Redbooks publications in the CICS area, and delivers ITSO workshops around the world.

Erhard Woerner is a Software Support Specialist in Germany. He has worked for IBM in CICS Level 2 Support for eleven years. He has 25 years of experience working with CICS in several roles. Before Erhard joined IBM, he worked as a CICS Systems Programmer at Deutsche Bank AG. He has excellent knowledge in the CICS programming languages COBOL, PL/I, and Assembler. He is an IBM Certifed Application Developer with IBM Enterprise PL/I. His areas of expertise include Virtual Storage Access Method (VSAM), CICS VSAM Recovery (CICSVR), CICS Web Services, and the z/OS® System Logger.

Thanks to the following people for their contributions to this project:

Richard M Conway International Technical Support Organization, Raleigh Center

Thanks to the authors of the previous editions of this book.

xiv IBM CICS Explorer The authors of the first edition, IBM CICS Explorer, published in December 2009, were:

Chris Baker, Diana Blair, Edoardo Comar, Stewart Francis, Em James, Chris Phillips, Kat Sharp, Pete Siddell, Colin Stone, Satish Tanna, Joe Winchester, Will

Ya t e s

Now you can become a published author, too!

Here's an opportunity to spotlight your skills, grow your career, and become a published author—all at the same time! Join an ITSO residency project and help write a book in your area of expertise, while honing your experience using leading-edge technologies. Your efforts will help to increase product acceptance and customer satisfaction, as you expand your network of technical contacts and relationships. Residencies run from two to six weeks in length, and you can participate either in person or as a remote resident working from your home base.

Obtain more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our books to be as helpful as possible. Send us your comments about this book or other IBM Redbooks publications in one of the following ways: Use the online Contact us review Redbooks form found at: ibm.com/redbooks Send your comments in an email to: [email protected] Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400

Preface xv Stay connected to IBM Redbooks

Find us on Facebook:

http://www.facebook.com/IBMRedbooks Follow us on Twitter: http://twitter.com/ibmredbooks Look for us on LinkedIn: http://www.linkedin.com/groups?home=&gid=2130806 Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter: https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm Stay current on recent Redbooks publications with RSS Feeds: http://www.redbooks.ibm.com/rss.html

xvi IBM CICS Explorer Summary of changes

This section describes the technical changes made in this edition of the book and in previous editions. This edition might also include minor corrections and editorial changes that are not identified.

Summary of Changes for SG24-7778-01 for IBM CICS Explorer as created or updated on December 17, 2010.

December 2010, Second Edition

This revision reflects the addition, deletion, or modification of new and changed information described below.

New information Chapter 5, CICS Explorer navigation walkthrough Chapter 9, CICS Explorer TG plug-in familiarization Chapter 10, CICS Explorer Tivoli® OMEGAMON® XE plug in familiarization Chapter 11,CICS Deployment Assistant Chapter 12, WebSphere® MQ plug-in

Changed information Chapter 2 Chapter 3 Chapter 4 Chapter 13

xviii IBM CICS Explorer

Part 1

Part 1 CICS Explorer Introductions

In this part of the book, we look at the new CICS Explorer and introduce the following CICS Tools plug-ins. CICS Explorer IA plug in CICS Explorer CM plug-in CICS Explorer PA plug-in CICS Explorer WMQ plug-in CICS Explorer Omegamon plug-in CICS Deployment Assistant

2 IBM CICS Explorer

Chapter 1. CICS Explorer introduction

In this chapter, we introduce the new Customer Information Control System (CICS) Explorer by giving you an overview before we introduce more basic capabilities.

As a newcomer into a CICS environment or as an experienced user moving roles, CICS System Management can be a daunting challenge. Prior to the CICS Explorer, to perform each task could require the use of different disconnected interfaces. These applications were often ISPF-based panels and written to do a specific function, each of which required custom knowledge to operate. If the completion of a specific task crossed application boundaries, you had to switch back and forth between the applications, which each had its own commands and user interface.

As well as basic CICS System Management, the definition and operation of regions and their installed resources, a typical CICS shop uses a number of tools, either obtained from IBM, third-party vendors, or developed in-house. These tools might have their own interfaces and way of presenting or manipulating the CICS runtime.

Providing an integration platform so that all of the tools and applications that a user needs to perform a business task work together coherently in an integrated environment was one of the driving forces behind the creation of the CICS Explorer. The benefit of CICS Explorer is to help new users become familiar with the platform, to present a single and re-usable way of accessing and manipulating CICS to promote consistency, and to allow tools that are built by IBM, vendors, and customers alike to be able to extend and enhance in a unified way. Each tool must introduce its own value to CICS management without having to reinvent or redefine the interface to the base platform itself.

As a system management tool the CICS Explorer is designed to be a scalable and intuitive way to manage a single CICS region, a collection of regions within a CICSplex, or a collection of CICSplexes. Experienced system programmers can quickly identify and tune their systems while newer users can be guided through the intuitive interface to learn how to perform standard tasks. By having a consolidated approach to system management, the number of interfaces that are required by CICS system administrators to learn to become effective is reduced, which helps to make the effort of attracting and training new developers and system programmers easier and less expensive.

The CICS Explorer is based on the Eclipse Rich Client Platform (RCP). Eclipse RCP is a cross platform framework for building and deploying PC desktop applications. One of the features of Eclipse that makes it a good choice of technology for the CICS Explorer is its plug-in architecture, which allows different components to be added that can extend and complement each other. A number of plug-ins exist that can be integrated into Eclipse environments, such as workflow, messaging clients, or development tools. One of these products is IBM

4 IBM CICS Explorer Rational Developer for Z, which is an integrated development environment for the System z platform that allows the creation of programs that access the CICS API to perform transaction processing. By both products sharing Eclipse as their common base technology, the CICS Explorer integrates within IBM Rational Developer for System z version (version 7.5 or higher) to provide system administrative capabilities to CICS application developers.

The CICS Explorer can be extended by plug-in providers using the Explorer API / SDK. Using the Explorer API / SDK customers can develop their own dedicated plug-ins to satisfy requirements particular to them. Using this framework maintains the consistency of the interface and integrates with the rest of the functionality that is provided in the Explorer and is the mechanism by which IBM and vendors provide plug-ins for their value-add tools.

Figure 1-1 shows how CICS Explorer and Eclipse RCP platform fit together.

CICS Explorer CICS Explorer

Workbench Plug-in

SWT / JFace CICS Explorer

Figure 1-1 CICS Explorer + Eclipse RCP

At this point the CICS Explorer is not a full-functional replacement for the CICSPlex System Manager Web User Interface. Users who are comfortable with the Web user interface (WUI), or the more traditional CEMT and CEDA commands in CICS, can enjoy using them as before with the CICS Explorer providing a rich way to administer and perform operational tasks on CICS systems in a fashion that allows extension and customization by tools and third-party plug-ins.

1.2 Base Explorer capabilities

The CICS Explorer provides a base set of CICSPlex SM functions to manage CICS regions, resources, and definitions. It also provides a platform on which future CICS tools that are integrated in the Eclipse RCP can perform tasks and present the information in a common way.

Chapter 1. CICS Explorer introduction 5 CICS Explorer connects to either a CICSPlex SM WUI server or a single CICS region. The functions that are available depend on which version of CICS Transaction Server for z/OS you use.

Figure 1-2 shows the different set ups.

V3.2/V3.1

CICS1 CICSPlex SM Data Interface CICS2 (read only)

e CICS3 ac rf te In ta ) V4.1 Da ly M on S x ad le e P (r S IC C CICS1 CICS Management Interface CICS2

CICS3

V4.1

CICS Management Interface CICS1

CICS2

CICS3

Figure 1-2 Different CICS setups

When connected to a CICSPlex SM WUI server, CICS Explorer operations views provide a single-system image of all of the CICS resources within a CICSplex. When the CICS Explorer is connected to a CICS Transaction Server for z/OS Version 3 system, you can only browse the resources. However, when the CICS Explorer is connected to a CICS Transaction Server for z/OS version 4 CICSPlex SM WUI or a single CICS region, you can perform the following actions on operational resources: Enable and disable resources Open and close resources

6 IBM CICS Explorer Acquire and release resources Place resources in and out of service Purge tasks that are associated with a resource Discard resource definitions from a CICS system where they are installed

The CICS Explorer displays details of the CICS and CICSPlex SM resource definitions, and when the CICS Explorer is connected to a CICS Transaction Server for z/OS version 4 CICSPlex SM WUI, you can use the administration views and the resource editor to perform the following actions: Create and update resource definitions Install or remove resource definitions

Administration operations are not supported in a single CICS region in the CICS Explorer version 1.0.

Table 1-1 to Table 1-3 on page 8 shows exactly what can you do with the Explorer, given a particular set up and CICS version.

Table 1-1 Capabilities - CICSPlex SM CICS Version 4.1 Example Views Actions

Operations Regions Large subset Enable (40+) Disable Discard

Administration Transaction All Basic Create (CSD Definitions Update Post-GA) Install Delete Add/Remove

Topology CICSPlex Subset No

RTA Events RTA Small subset No Outstanding Events

WLM Active Small subset No Workloads

Monitoring Active Monitor N/A N/A Specifications

Table 1-2 Capabilities - CICSPlex SM CICS Version 3 Example Views Actions

Operations Regions Large subset No (40+)

Chapter 1. CICS Explorer introduction 7 Example Views Actions

Administration Transaction All Basic No CICSPlex SM Definitions Only

Topology CICSPlex Subset No

RTA Events RTA Small subset No Outstanding Events

WLM Active Small subset No Workloads

Monitoring Active Monitor N/A N/A Specifications

Table 1-3 Capabilities - CICS Single Server CICS Version 4.1 Example Views Actions

Operations Regions Large subset Enable (40+) Disable Discard

Administration Transaction All Basic Create (CSD Definitions Update Post-GA) Install Delete Add/Remove

Topology CICSPlex Subset N/A

RTA Events N/A N/A N/A

WLM N/A N/A N/A

Monitoring N/A N/A N/A

The CICS Explorer also displays Events and Active Workloads in a CICSPlex or single region and Properties for CICSPlex SM Objects.

In addition, using the CICS Explorer you can define connections to multiple systems; however, only one connection can be active at a time.

The CICS Explorer shows the CICSplexes, CICS systems, and regions for your current connection, the different system and resource groups, and their related resources. Using the CICS Explorer you can navigate to resources by selecting a context, and then resources are displayed in different tabular views depending on

8 IBM CICS Explorer their type. You can customize the attributes that display, enable filtering on attributes, select resources, and perform any appropriate actions.

The CICS Explorer uses rich editors to display resource definition attributes in one or more pages. To simplify the update process for less-experienced CICS

users, attributes are logically grouped together, and each attribute has more detail provided. Every attribute benefits from field-level verification, where the entry is validated in real time. Errors are identified by the Error icon, which identifies the field in error and the page on which the field appears. Additionally, the embedded help system can provide assistance for the entire editor or for a specific field, which allows you to quickly get the information that you require.

To facilitate the move to CICS Explorer for experienced CICS users, one page in the rich editor, the Attributes page, displays the attributes in tabular form, grouped together in the same way that they appear in CEDA or in the CICSPlex SM WUI. For users on a CICS Version 3, system resource definitions are also displayed in this way; however, you cannot edit them.

The CICS Explorer has an embedded help system to provide context and more detailed help for the resources and help about using the CICS Explorer and the basic Eclipse functions. More detailed help for CICS and CICSPlex SM is at the CICS Transaction Server for z/OS Information Center.

1.3 Plug-ins and RCP

The CICS Explorer is an Eclipse RCP-based GUI application that runs on the Microsoft® Windows® and Linux® operating systems. The user interface to the applications is through the workspace, which is a graphical multi-window environment that is built into Eclipse. The Eclipse platform is structured as subsystems that are implemented in one or more plug-ins. The subsystems are built on top of a small runtime engine.

The workspace is a single window that consists of views and perspectives, and can contain other elements, such as editors, menus, and the help system.

The CICS Explorer uses a subset of the Eclipse plug-ins to build its workspace. The CICS Explorer runs completely standalone, and no prior installation of Eclipse is required; however, it is necessary to understand some of the concepts from Eclipse to make full use of all that the Explorer offers.

1.3.1 Eclipse concepts

In this section, we discuss the concepts of Eclipse.

Chapter 1. CICS Explorer introduction 9 Perspectives overview A perspective is a layout of one or more views in the workspace. You can define your own perspectives to suit your particular needs.

You can tailor a perspective by adding new views, removing existing views, moving views around, or changing the size of views. When you close CICS Explorer, any changes that you made to the perspective are saved, and the next time that CICS Explorer starts, your tailored perspective is displayed. This tailoring feature allows you to create a view of CICS that contains the set of resources that makes the most sense for a particular role and its tasks in your CICS environment.

You can restore the default perspective at any time by going to the main workspace menu bar and clicking Window  Reset  Perspective.

You can create and save multiple perspectives, for example, you might want to set up one perspective that only shows the administration views and one perspective that only shows the operation views. For further information about using perspectives, see the related links.

When you save a perspective, you save only the layout of the views and editors in the workspace. If you change the width of a column in a view, that change is applied to that column in every perspective that contains the view. Any filter attributes that you set are retained when you switch to another perspective or view because a perspective is a definition of which views should be shown and their relative position, not their contents. The content is a property of the view that crosses perspective boundaries. The ability to create multiple instances of the same view with different filter or layout criteria might be included in a future release of the CICS Explorer, but it is not currently supported.

The CICS Explorer comes with two built-in perspectives: System Management The System Management perspective is the first perspective that is presented when the Welcome page closes on first startup of the CICS Explorer. It contains information about the currently connected CICS systems, which includes the active regions, the running tasks, and so forth. If there is no active CICS system connection, all of the views in the perspective are empty. Resource The Resource perspective is the same perspective that is included with most Eclipse-based products and shows a set of files that are locally held on your computer file system. These files can be any file that you import into your Eclipse environment. In the CICS Explorer, the Resource perspective presents and allows manipulation of content that is typically destined for

10 IBM CICS Explorer deployment into an HFS folder that is associated with a CICS resource definition.

Views overview Each perspective contains one of more views. A view is a visual component and provides a way to navigate the information in your workspace.

The CICS Explorer uses some views that are provided with Eclipse itself, such as the Properties View, which shows attributes for a CICS resource or repository definition, and the Package view, which shows contents of a project for use in a CICS bundle. As well as using these existing Eclipse views, the CICS Explorer has a number of CICS-specific views that are arranged into a number of high-level conceptual categories. Views that display similar information are grouped together into tab groups. Each tab group is contained within a pane in the workspace window.

Figure 1-3 provides an example of the Views.

Figure 1-3 Views overview

Chapter 1. CICS Explorer introduction 11 Navigation: Tab Group 1 Using the CICSplex and CICSPlex Repositories view you can see a list of CICSplexes and active regions or CICSPlex repositories and defined definitional or system groups.

Resources: Tab Group 2 CICS Resources are divided into two categories: Administration Administrative resources are those that reside in a repository, such as a CSD or CICSplex SM data repository (also known as BAS) and Transaction Definition or File Definition. Each CICS resource has a specific view. Operational Operational resources represent live CICS resources that are installed into an active CICS region, such as tasks, programs, or files.

If the view that shows a particular resource is not present in the perspective, open it by clicking Window  Show View and searching for the view by name. Alternately, use the pull-down menu Administration or Operational, and locate the appropriate view by resource name. In a CICS view, the pop-up menu shows a list of tasks that can be taken against the selected resource(s), one of which is open that activates an editor. We cover this topic more in “Editors overview” on page 13.

The content of the resources views is scoped by the selected entry in one of the navigational views where appropriate. This scope is illustrated by the Tasks view, which shows all tasks for the selected sysplex, if one is selected in the CICSplex view. The Tasks view shows all tasks for the selected region if one is selected; likewise, for a view that shows CICS definitions, such as File Definitions, the scope of this is either all definitions for the selected CICSplex’s repository or for the selected resource definition group.

Extended: Tab Group 3 Using the CICS Explorer you can view additional details, such as CICS Plex SM system events or Real Time Analysis views. These details are arranged in the System Manager perspective at the bottom and are typically not scoped by the navigational views. This group also includes the Properties View, which shows all available attributes for a CICS resource.

Help: Tab group 4 You can open the help view in the perspective using function key 1 to show information from the documentation that is provided with the CICS Explorer.

12 IBM CICS Explorer Each view has a title, which is displayed in a tab at the top of the view. Where multiple views are present in a view set, they are stacked one behind the other. To activate a view, click its tab to bring the view to the front of the stack. The tab is highlighted, which indicates the active view.

All views, with the exception of the CICSplex Explorer view, can be removed from view or moved to a different tab group, and each tab group can be sized or repositioned in the workspace. The CICSplex Explorer view is a special view that you cannot close or move.

You can restore the default tab group arrangement (perspective) at any time by going to the main workspace menu bar and clicking Window  Reset Perspective.

Editors overview An editor opens in a separate tab group called the editor area, which is positioned to the right of the tabular views. The editor area shares many features with the other tab groups, but it does have some limitations that we identify later in this topic.

You open an editor from a resource definition view by right-clicking a resource, and then clicking Open. Figure 1-4 on page 14 shows the editor area, which is the active view.

Chapter 1. CICS Explorer introduction 13

Figure 1-4 Editors

The editor area appears to the right of the views. Each editor for a CICS resource has a tab that is labelled Attributes. Under the Attributes tab is a list of attributes that are arranged in a tree, which is designed to be familiar to users who are comfortable with CEDA or CEMT categorization. For some definitions there are additional tabs, such as the Overview tab for the pipeline definition, which arranges the information using rich controls to add description and grouping to help identify and explain the attributes and their contents. If the current connection is to a CICS Management Client Interface or CMCI connection, you can make changes to the definition through the editor and save the changes to update the CICS resource or definition. If the current connection is to a CICS

Plex System Manager connection, the editor only allows viewing of the resource’s attributes.

14 IBM CICS Explorer Note: CMCI Connections are only available to regions running CICS Transaction Server Version 4.1.

You can minimize, maximize, or resize the editor area, but there are some limitations on moving the editor area and the editor.

You change the size of the editor area in the same way that you size the other tab groups, but the editor area cannot be moved in the same way that you move the other tab groups. To reposition the editor area in the workspace, move the other tab groups around the editor area, for example, to reposition the editor area more to the middle of the workspace, drag the tabular views tab group, and drop it at the right side of the editor group, as shown in Figure 1-5.

Figure 1-5 Editor, changing the size

If you open more than one instance of the editor, you can move the views around in the editor area, for example, you can position them one above the other or

Chapter 1. CICS Explorer introduction 15 side-by-side, as shown in Figure 1-6, but you cannot move the editor instances into a different tab group.

Figure 1-6 Moving the views around

If you reset the perspective, the perspective is restored to the default layout; however, any open editors are unchanged and remain in the workspace. Similarly, if you change to another perspective, any open editors remain visible in the new perspective.

Embedded help system

Using the embedded help system you can browse, search, and print system documentation. The help system also provides a context-sensitive help, which you can access by pressing the ‘F1’ hotkey (Windows) or CNTRL-F1 (Linux). This help system gives an overview of the resource with which you are working and a text search capability for finding the information that you need, by keyword. The help is displayed either in a Help view in the workspace, in a separate Help Contents window, or in an external browser window.

16 IBM CICS Explorer The CICS Explorer includes detailed help information for CICS resources and their attributes that is sensitive to where it is activated from. In the Properties View or the attributes tab of an editor, when an individual attribute is selected and F1 pressed to activate help, the help contents shown are specific to the selected attribute. In some views, such as the customize columns dialog for a CICS resource view or a CICS definition creation wizard, activating help opens the help contents in the active window, again showing contents that are applicable to the selected or currently focused attribute.

Chapter 1. CICS Explorer introduction 17

18 IBM CICS Explorer

Chapter 2. Getting started with CICS Explorer

In this chapter, we describe the steps that are required to implement CICS Explorer for those who want to execute independently-managed CICS regions (the single system set up) and for those who want to use CICSPlex SM to enable you to take advantage of CICS Explorer.

CICS TS 4.1 introduces a new facility called the CICS Management Client Interface (CMCI). This interface is exploited by CICS Explorer to provide Create, Read, Update, and Delete capabilities.

In this section, we tell you how to use CICS Explorer with CICS TS 4.1.

2.2 CICS Explorer connection to CICS

CICS Explorer operates in two distinct ways: Connected to a CICS region Connected to CICSPlex SM

2.2.1 Connecting CICS Explorer to a CICS region

Small-scale users can connect CICS Explorer directly to individual CICS regions, which provides access to basic operational capabilities and resources definitions through the CSD, as shown in Figure 2-1 on page 21. Small enterprises can therefore benefit from a modern-management interface and integration with the CICS tools. Set up is minimal requiring only a few minutes with CMCI initializing the first time a request is made to the region. All that is required to gain access is a TCP/IP Service definition and the addition of the appropriate Library.

This type of usage scenario is described as a System Managed Single Server or SMSS. This term is also sometimes referred to as Single Server.

CICS Explorer lets you work with the resources on just this single system. The SMSS capabilities of CICS cannot be used if the CICS is managed by CICSPlex SM.

20 IBM CICS Explorer

Single Server Management Interface

SM API

Request CICS Response PC Based Client CICS SPI

Figure 2-1 Connected to a CICS region

If you have multiple CICS regions, each region requires a TCP/IP Connection and you must connect CICS Explorer to each CICS, in turn, to work with it.

2.2.2 Connecting CICS Explorer to CICSPlex SM

For those who exploit the extensive capabilities that CICSPlex SM provides, you can use CICS Explorer to access the CICSPlex SM environment, as shown in Figure 2-2 on page 22. In contrast to the previous support pack edition, this interface now gives you the ability to take actions on resources. Establishing access requires, again, a simple set of actions, even for a first time CICSPlex SM user. For existing CICSPlex SM users, access is virtually immediate.

If the system is managed by CICSPlex SM, you cannot use the CICS SMSS / Single Server capabilities.

Chapter 2. Getting started with CICS Explorer 21

CICSPlex SM Configuration

SM API CICS

Request CICS CICS CICS Response WUI Server CMAS PC Based Client

CICS CICS SPI

Figure 2-2 Connected to CICSPlex SM

As users migrate to the advanced facilities of CICSPlex SM, the CICS Explorer experience expands into this new set of capabilities, eliminating the relearning curve that often occurs when introducing new management tools.

2.3 Setting up single-server access

To set up a single server to access CICS Explorer: 1. Copy the IBM-supplied group DFH$WU to a user-defined group. You need one group for each CICS system that you want to manage. 2. In your user-defined group, update TCPIPService definition DFH$WUTC and the Portnumber (each CICS requires a unique value for the TCP/IP Stack being used). If the CICS is running with security (SEC=YES in the SIT), change Authenticate to Basic. 3. Install the user-defined group (URIMAP definition DFH$WUUR is installed alongside the DFH$WUTC.TCPIPSERVICE). 4. Add the CICS TS SEYULOAD data set to the CICS DFHRPL concatenation and the CICS TS SEYUAUTH data set to the STEPLIB concatenation in the CICS JCL. (Make sure that the CICS TS SEYUAUTH data set is APF authorized).

Example 2-1 on page 23 shows a JCL that needs updating, and Example 2-2 on page 23 shows an updated JCL.

22 IBM CICS Explorer Example 2-1 Update the CICS JCL (before update)

//CICS EXEC PGM=DFHSIP,REGION=240M, // PARM=('SIT=6$', // 'START=AUTO,SI') //SYSIN DD * GRPLIST=(DFHLIST,userlist1,userlist2), APPLID=CICSHTH1, .END //STEPLIB DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR //DFHRPL DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR // DD DSN=your.prog.library,DISP=SHR // DD DSN=your.table.library,DISP=SHR //DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR …

Example 2-2 Updated JCL //CICS EXEC PGM=DFHSIP,REGION=0K, // PARM=('SIT=6$', // 'START=AUTO,SI') //SYSIN DD * GRPLIST=(DFHLIST,userlist1,userlist2), APPLID=CICSHTH1, .END //STEPLIB DD DSN=CICSTS41.CPSM.SEYUAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR //DFHRPL DD DSN=CICSTS41.CPSM.SEYULOAD.DISP=SHR // DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR // DD DSN=your.prog.library,DISP=SHR // DD DSN=your.table.library,DISP=SHR //DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR

Figure 2-3 on page 24 shows the Explorer connection to a single server. The Connection type to specify is CICS Management Interface. The Server address to use is the IP address of the TCP/IP stack that the CICS will use, and the Portnumber corresponds to the port number that is specified on the DFH£WUTC tcpipservice that you installed. The interface initializes when the CICS region receives the first request.

Chapter 2. Getting started with CICS Explorer 23

Figure 2-3 Explorer connecting to a single server

Before a Connection can be created at least one Credential must exist, Figure 2-4 on page 25 shows the Credentials Preferences window where you define the UserID and Password pair to be used by the Connections profiles that you create.

24 IBM CICS Explorer

Figure 2-4 Credentials Preferences window

2.4 Setting up CICSPlex SM for CICS Explorer

In this section, we describe the steps that are required to set up CICSPlex SM to take advantage of CICS Explorer.

2.4.1 Basics of setting up CICSPlex SM for CICS Explorer

To set up CICSPlex SM, you need two new CICS systems. In this document, we turn one of these systems into a CMAS and the second into a Web User Interface (WUI) server.

A CMAS is a CICS system that manages a CICSplex. It is a dedicated system; therefore, no other workloads run inside it.

A CICSplex is a set of CICS systems that CICSPlex SM manages. You might have a number of CICSplexes in your enterprise, but an individual CICS system can only belong to (be managed by) one CICSplex.

Chapter 2. Getting started with CICS Explorer 25 A WUI server is a CICS system that acts as a Web server for the Web User Interface into CICSPlex SM. If you use the CICS Explorer with CICS TS 4.1 the Explorer uses this to acquire information about your CICS systems and resources. This is a dedicated system, so no other workloads run inside it.

As a first step, create two new CICS systems. Figure 2-5 shows an example of our environment. The assumptions that we made are: CICS systems are on a single LPAR CICSPlex SM Libraries are downloaded You have JCL for existing CICS regions

Existing set up

CICS1 CICS2 CICS3

JCL for CICS Regions

Figure 2-5 Example of existing setup

Figure 2-6 on page 27 shows our environment plus WUI and CMAS regions.

26 IBM CICS Explorer Create two new CICS regions (CMAS and WUI server)

CICS5 Use your existing CICS JCL, etc.

CICS4

CICS1 CICS2 CICS3

JCL for CICS Regions

Figure 2-6 Existing setup plus WUI and CMAS regions

2.4.2 Changing a System into a CMAS

Figure 2-7 on page 28 shows an example of creating a CMAS Repository.

Chapter 2. Getting started with CICS Explorer 27 Create CMAS repository

//DEFDREP EXEC PGM=IDCAMS //DREPINIT EXEC PGM=EYU9XDUT, CICS5 //SYSPRINT DD SYSOUT=* // COND=(8,LT), //SYSIN DD * // DEFINE CLUSTER - PARM=('CMASNAME=@cmasname@', (NAME(@newdrep@) - // 'DAYLIGHT=N', RECORDS(500,3000) - // 'TIMEZONE=@timezone@', VOLUME(@dsvol@) - // 'SYSID=@cmssysid@', CICS4 CISZ(8192) - // 'ZONEOFFSET=0') RECSZ(200,6550) - //EYUXDPRM DD * KEYS(64,0) - WUI=YES SHR(2) - WUIPLEX=WUIPLEX1 DREP INDEXED - WUINAME=@wuiname@ SPEED - WUIAPPLID=@wuiapplid@ REUSE) WUISYSID=@wuisysid@ /* CICS1 CICS2 CICS3 /* //STEPLIB DD Create DISP=SHR,DSN=@[email protected] UTH //EYUDREP DD DISP=OLD,DSN=@newdrep@ //SYSPRINT DD SYSOUT=*

Initialize

Figure 2-7 Create CMAS repository

Creating a data repository To change one of your systems into a CMAS you must first create and initialize a data repository. A data repository is a VSAM file that CICSPlex SM uses to store definitions, which is a bit like a CICS CSD. Example 2-3 shows sample syntax for creating a data repository, and Example 2-4 on page 29 provides sample JCL syntax to initialize the repository.

Example 2-3 Create the CMAS repository //DEFDREP EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE CLUSTER - (NAME(@newdrep@) - RECORDS(500,3000) - VOLUME(@dsvol@) - CISZ(8192) - RECSZ(200,6550) - KEYS(64,0) - SHR(2) - INDEXED - SPEED -

28 IBM CICS Explorer REUSE) /*

Example 2-4 Initialize the repository //DREPINIT EXEC PGM=EYU9XDUT, // COND=(8,LT), // PARM=('CMASNAME=@cmasname@', // 'DAYLIGHT=N', // 'TIMEZONE=@timezone@', // 'SYSID=@cmssysid@', // 'ZONEOFFSET=0') //EYUXDPRM DD * WUI=YES WUIPLEX=WUIPLEX1 WUINAME=@wuiname@ WUIAPPLID=@wuiapplid@ WUISYSID=@wuisysid@ /* //STEPLIB DD DISP=SHR,DSN=@[email protected] //EYUDREP DD DISP=OLD,DSN=@newdrep@ //SYSPRINT DD SYSOUT=*

There are two variables that you must specify in the JCL for creating the repository (Example 2-3 on page 28): The data set name (@newdrep@) that you want the repository to have (make a note of this name, you will need it later) The volume (@dsvol@) on which you want the data set created

Initializing the data repository Next, we must initialize the data repository, which loads the repository with some definitions that are needed for the CICSPlex to work. Example 2-4 contains some sample JCL to initialize the data repository.

There are a number of variables that you must set in the JCL. Let us start with the simplest: 1. Where @cpsmhlq@ appears, enter in the High Level Qualifier for the release of CICS TS that you are working on, for example: CTS410.CPSM.SEYUAUTH. 2. Populate @newdrep@, which this is the name that you gave to your Data Repository when you created it with IDCAMS, as shown in Example 2-3 on page 28.

Chapter 2. Getting started with CICS Explorer 29 3. Populate the @cmasname@ variable. This entry is simply a name that CICSPlex SM uses to identify the CMAS. You can use up to eight characters (A-Z and 0-9) for the name. You might want to use the APPLID of the system as a name for simplicity. Make a note of the CMAS name because you will need it later. 4. Set @timezone@ to the letter A to use your local timezone. 5. Set @cmssysid@, which is the system ID of the CICS system that you are turning into a CMAS: a. Find the SYSIDNT SIT parameter in your CICS JCL, and copy its value into this variable. If you do not have a SYSIDNT SIT parameter, create a four character identifier. The last four characters of the system's APPLID can be used for this. The value must be unique.

The next set of variables help define a CICSplex for your WUI server and tell the CMAS a bit about the CICS system that you are using as a WUI server: @wuiapplid@ is the APPLID of the CICS system that you are turning into a WUI server. This is not the same system that you are turning into a CMAS. In your CICS JCL, find the APPLID SIT parameter, and copy its value into the @wuiapplid@ variable. @wuisysid@ is the system ID of the CICS system that you are turning into a WUI server. This is not the same system that you are turning into a CMAS. In your CICS JCL, find the SYSIDNT SIT parameter, and copy its value into the @wuisysid@ variable. If you do not have a SYSIDNT SIT parameter, you must create a four character identifier. Use the last four characters of the system's APPLID. This value must be unique. @wuiname@ is a name that CICSPlex SM uses to identify the WUI server. You can use up to eight characters (A-Z and 0-9) for the name. You can use the APPLID of the system as a name. Make a note of the name because you will need it later.

Note: There is also a parameter called WUIPLEX that, in this example, was set to WUIPLEX1 because the WUI is managed inside of its own CICSplex. For this exercise, it is not important to understand why this is the case, so it is fine to just use the WUIPLEX1 value.

Both the data repository creation and initialization can be JOBSTEPS inside a single JOB.

When the JCL is submitted, you will get a return code of 0, which means that your data repository data set is created and initialized.

30 IBM CICS Explorer Modifying the CICS JCL Now we must modify the JCL of the CICS system that we are turning into a CMAS. Example 2-5 shows a CMAS JCL before modification.

Example 2-5 Update CMAS JCL (before) //CICS EXEC PGM=DFHSIP,REGION=240M, // PARM=('SIT=6$', // 'START=AUTO,SI') //SYSIN DD * GRPLIST=(DFHLIST,userlist1,userlist2), APPLID=CICSHTH1, .END //STEPLIB DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR //DFHRPL DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR // DD DSN=your.prog.library,DISP=SHR // DD DSN=your.table.library,DISP=SHR //DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR …

Example shows the JCL after modification.

Example 2-6 Update CMAS JCL (after) //CICS EXEC PGM=EYU9XECS,REGION=0K, // PARM=('SIT=6$', // 'START=AUTO,SI') //SYSIN DD * GRPLIST=(DFHLIST,userlist1,userlist2), APPLID=CICSHTH1, MXT=300, CPSMCONN=CMAS, EDSALIMIT=100M, ICVR=20000, SEC=NO, You can switch it on later SPOOL=YES, WRKAREA=2048, .END //STEPLIB DD DSN=@[email protected],DISP=SHR // DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR //DFHRPL DD DSN=@[email protected]=SHR // DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR

Chapter 2. Getting started with CICS Explorer 31 // DD DSN=your.prog.library,DISP=SHR // DD DSN=your.table.library,DISP=SHR //DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR //EYUDREP DD DISP=SHR,DSN=@newdrep@ //EYUPARM DD * NAME(@cmasname@) SEC(NO) /*

To modify the JCL: 1. In the JOBSTEP for the CICS system, change the program from DFHSIP to EYU9XECS. Also, add REGION=0K to this line. 2. Add the following data set to your STEPLIB (as before, the variables used depend on the release of CICS TS that you are using): @[email protected] 3. Add the following data set to DFHRPL: @[email protected] 4. Add the following SIT parameter: CPSMCONN=CMAS 5. Add or change the MXT SIT parameter, which is the minimum MAXTASKs value for a CMAS. (For a basic set up, 300 is an appropriate value): MXT=300 6. Change the EDSALIMIT SIT parameter, which is the minimum DSA size for a CMAS. (For a basic set up this is an appropriate value): EDSALIMIT=100M 7. Add or change the ICVR SIT parameter: ICVR=20000 8. Add or change the SEC SIT parameter. Initially we run with security off. You can run with security on at a later date: SEC=NO 9. Add or change the SPOOL SIT parameter: SPOOL=YES

10.Reserve 2048 bytes for the Common Work Area (CWA): WRKAREA=2048

32 IBM CICS Explorer 11.Change the START SIT parameter:

START=AUTO You might want to force a COLD/INITIAL start on the first startup, but an AUTO restart is fine after that.

12.Add the following DD card to the JCL, where @newdrep@ is the name of the Data Repository that you created earlier: //EYUDREP DD DISP=SHR,DSN=@newdrep@ 13.Add the following DD card: //EYUPARM DD * NAME(@cmasname@) SEC(NO) /* The example here assumes that the IBM supplied SIT 6$ is used. If you use an installation-defined SIT, you might need to modify other values that are not shown here; otherwise, incorrect results can occur.

Example on page 31 is an example of all of these changes. You are now ready to start your CMAS.

Starting the CMAS Submit the JCL you just modified. If the CMAS starts successfully, in the logs, you will see the following messages: EYUXL0007I IYK3ZDD1 CMAS Phase III initialization complete. EYUXL0007I IYK3ZDD1 CMAS Phase IV initialization complete. EYUXL0010I IYK3ZDD1 CMAS initialization complete.

If CMAS initialization does not complete, go back and make sure that all of the names, APPLIDs, and system IDs that you defined are correct.

2.4.3 Changing a system into a WUI server

The first step to creating a WUI server is to create a WUI repository, as shown in Figure 2-8 on page 34.

Chapter 2. Getting started with CICS Explorer 33 Create WUI repository

//DEFWREP EXEC PGM=IDCAMS CICS5 //SYSPRINT DD SYSOUT=* //SYSIN DD *

DEFINE CLUSTER ( - WUIREP NAME(@newwuirep@) - VOLUME(@dsvol@) - STORCLAS( STANDARD ) - RECORDS( 5000 5000 ) - CICS4 CONTROLINTERVALSIZE( 8192 ) - SPANNED - INDEXED - SHAREOPTIONS( 2 ) - DREP ) - DATA ( - NAME(@[email protected] ) - CICS1 CICS2 CICS3 KEYS( 20 20 ) - RECORDSIZE( 8192 32000 ) - ) - INDEX ( - NAME(@[email protected] ) - ) /*

Figure 2-8 Create a WUI repository

The WUI repository is a VSAM data set that holds all of the Views and Menus that the WUI serves to a browser. Example 2-7 contains some sample JCL to create a WUI repository.

Example 2-7 Create WUI repository //DEFWREP EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD *

DEFINE CLUSTER ( - NAME(@newwuirep@) - VOLUME(@dsvol@) - STORCLAS( STANDARD ) - RECORDS( 5000 5000 ) - CONTROLINTERVALSIZE( 8192 ) - SPANNED - INDEXED - SHAREOPTIONS( 2 ) -

) - DATA ( - NAME(@[email protected] ) - KEYS( 20 20 ) -

34 IBM CICS Explorer RECORDSIZE( 8192 32000 ) - ) - INDEX ( - NAME(@[email protected] ) - ) /*

The data set name that you want the WUI repository to have is @newwuirep@.

We are now ready to modify our CICS system's JCL to turn it into a WUI server.

Modifying the CICS JCL Example 2-8 shows the changes to make to CICS JCL to make it a WUI server.

Example 2-8 Change CICS JCL to make it a WUI //CICS EXEC PGM=DFHSIP,REGION=0K, // PARM=('SIT=6$', // 'START=AUTO,SI') //SYSIN DD * GRPLIST=(DFHLIST), APPLID=CICSHTH1, CPSMCONN=WUI INITPARM=(EYU9VWAN=‘ENU1’,EYU9VKEC=‘ENU’), EDSALIM=100M, MXT=120, TCPIP=YES, SEC=NO, You can switch it on later WRKAREA=2048, CWAKEY=CICS, .END /* //STEPLIB DD DSN=@[email protected],DISP=SHR // DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR // DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR //DFHRPL DD DSN=@[email protected]=SHR // DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR // DD DSN=your.prog.library,DISP=SHR // DD DSN=your.table.library,DISP=SHR //DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR

//EYUWREP DD DISP=SHR,DSN=@newdrep@ //EYUPARM DD * NAME(@wuiname@) CICSPLEX(WUIPLEX1)

Chapter 2. Getting started with CICS Explorer 35 CMASSYSID(@cmassysid@) SEC(NO) /* //EYUWUI DD * TCPIPHOSTNAME(@hostname@) TCPIPPORT(@portnumber@) DEFAULTCONTXT(@mainlex@) DEFAULTSCOPE(@mainplex@) DEFAULTCMASCTXT(@cmasname@) AUTOIMPORTDSN(@[email protected]) AUTOIMPORTMEM(EYUEA*) CMPIPORT=@portnumber@ /*

Now we must modify the JCL of the CICS system that we are turning into a WUI server: 1. Add the following data set to your STEPLIB (as before, the variables that are used depend on the release of CICS TS that you are using): @[email protected] 2. Add the following data set to DFHRPL: @[email protected] 3. Add the following SIT parameter: INITPARM=(EYU9VWAN='ENU1',EYU9VKEC='ENU') 4. Reserve 2048 bytes of CICS key storage for the Common Work Area (CWA): WRKAREA=2048 CWAKEY=CICS 5. Make sure that the TCPIP SIT parameter is set to YES and that the CICS system can run as a Web server. 6. Add the following DD card: //EYUPARM DD * NAME(@wuiname@) CICSPLEX(WUIPLEX1) CMASSYSID(@cmssysid@) SEC(NO)

36 IBM CICS Explorer Note: @wuiname@ must match the WUI name you specified when creating the CMAS Data Repository. @cmssysid@ must match the system ID of the CMAS, not the WUI server system ID.

//EYUWUI DD * TCPIPHOSTNAME(@hostname@) TCPIPPORT(@portnumber@) DEFAULTCMASCTXT(@cmasname@) DEFAULTCONTEXT(@mainplex@) DEFAULTSCOPE(@mainplex@) AUTOIMPORTDSN(@[email protected]) AUTOIMPORTMEM(EYUEA*) CMPIPORT(@cmciportnumber@) @hostname@ is the TCP/IP host name for the IP stack that CICS will use. This value is also used when configuring the connection to this WUI server in CICS Explorer. @portnumber@ is a port number that was allocated for the use of the WUI server. This value is used by web browser users. @cmasname@ is the name of the CMAS you are connecting to (for example, the name of the CMAS that you created earlier). @mainplex@ is the name of the CICSplex to which you must add your existing CICS systems. It can be any eight-character string (A-Z and 0-9). You will create this CICSplex later. In this example, we use a CICSplex name of TESTPLEX, so in our WUIPARM we will have: DEFAULTCONTEXT(TESTPLEX) DEFAULTSCOPE(TESTPLEX) @cpsmhlq@ is the High Level Qualifier for the release of CICS TS that you are working on, for example: CICSTS41.CPSM.SEYUVIEW. @CMCIPORTNUMBER@ is the port number that is allocated for the use of the CICS Management Client interface for this WUI server. This value must not be the same as the value specified in @portnumber@. This value is used when configuring the connection to this WUI server on a CICS Management Interface connection in CICS Explorer.

Example 2-8 on page 35 is an example of all of these changes. You are now ready to start the WUI server.

Chapter 2. Getting started with CICS Explorer 37 Starting the WUI Server Submit the JCL you just modified. If the WUI starts successfully, in the system log you will see messages similar to the following messages:

EYUXL0030I IYK3ZDD4 ESSS connection in progress to CICSPLEX(WUIPLEX1) for SYSID(@cmssysid@)

EYUXL0004I IYK3ZDD4 ESSS connection complete.

EYUCL0006I IYK3ZDD4 ESSS link to IYK3ZDD1 established.

EYUXL0007I IYK3ZDD4 LMAS Phase II initialization complete.

EYUNL0099I IYK3ZDD4 LMAS LRT initialization complete.

At the top of the EYULOG you will see messages similar to the following messages. There will also be additional messages after these, but do not worry about them because they mostly relate to the WUI loading the Views and Menus that it is going to use: EYUVS0101I IYK3ZDD4 Parameter service initialization complete. EYUVS0200I IYK3ZDD4 Starting CICS Web Interface. EYUVS0204I IYK3ZDD4 TCP/IP service (EYUWUI) installed successfully. EYUVS0206I IYK3ZDD4 CICS Web Interface enabled on TCP/IP port number @portnumber@. EYUVS0204I IYK3ZDD4 TCP/IP service (EYUCMCIT) installed successfully. EYUVS0209I IYK3ZDD4 URI map (EYUCMCIU) installed successfully. EYUVS0211I IYK3ZDD4 CICS Management Client Interface enabled on TCP/IP port number @cmciportnumber@. EYUVS0002I IYK3ZDD4 CICSPlex SM Web User Interface initialization complete. EYUVS0010I IYK3ZDD4 Server connected to CMAS, SYSID(@cmssysid@).

If WUI initialization does not complete, go back and make sure that all of the names, APPLIDs, and system IDs that you defined are correct.

You are now ready to create a CICSplex for all of the CICS systems that you want to manage.

2.4.4 Creating a CICSplex to manage your systems

We are now going to define a CICSplex that will be used to manage your existing CICS systems. We also define your CICS systems to the CICSplex, so that when you start those systems, CICSPlex SM knows which CICSplex they are being managed by. Example 2-9 on page 39 shows a sample JCL for creating the CICSplex and defining your CICS systems.

38 IBM CICS Explorer Example 2-9 Sample JCL to create CICSplex

//CPSMDEFN EXEC PGM=EYU9XDBT //* //STEPLIB DD DISP=SHR,DSN=@[email protected] // DD DISP=SHR,DSN=@[email protected] //* //SYSTSPRT DD SYSOUT=* //EYUTRCF DD SYSOUT=* //* //EYUCPDEF DD DISP=SHR,DSN=@[email protected](EYUCPDEF) //EYUCSDEF DD DISP=SHR,DSN=@[email protected](EYUCSDEF) //EYUCSGRP DD DISP=SHR,DSN=@[email protected](EYUCSGRP) //* //EYUSYSIN DD DDNAME=SYSIN * Set CONTEXT to CMAS CONTEXT @cmasname@ * Define the CICSplex DEFINE CICSPLEX @plexname@ * Set CONTEXT to the CICSplex CONTEXT @plexname@ * Define a CICS region DEFINE REGION @systemname@ - APPLID @systemapplid@ - SYSID @systemsysid@ - CMASID @cmasname@

To create a CICSPlex that manages your systems: 1. @cpsmhlq@ is the High Level Qualifier for the release of CICS TS that you are working on, for example: CICSTS41.CPSM. 2. @cmasname@ is the name of the CMAS you are connecting to (for example, the name of the CMAS that you created earlier). 3. @plexname@ is the name of the CICSplex that is going to manage your systems, which is any name up to eight characters long (A-Z and 0-9). For this example, TESTPLEX is a valid name to enter here. 4. @systemapplid@ is the APPLID of a CICS system that you want to manage in your CICSplex. Find the APPLID SIT parameter in the JCL for the system you want to manage, and copy its value into this variable.

5. @systemsysid@ is the system ID of the CICS system that you want to manage in your CICSplex. Find the SYSIDNT SIT parameter in your CICS JCL, and copy its value into this variable. If you do not have a SYSIDNT SIT

Chapter 2. Getting started with CICS Explorer 39 parameter, create a four-character identifier. The last four characters of the system's APPLID can be used for this. This value must be unique.

6. @systemname@ is simply a name that CICSPlex SM uses to identify the system. You can use up to eight characters (A-Z and 0-9) for the name, and you can use the APPLID of the system as a name. Make a note of the name because you will need it later. 7. Repeat the DEFINE REGION statement for every CICS system that you want to manage in your new CICSplex. Do not forget to change that variable to match the APPLID of each system. 8. Submit the job, which causes all of your new definitions to be created.

You are almost ready to manage your CICS systems through CICSPlex SM. The last step before starting your systems is to alter the JCL of your CICS systems to allow them to connect to CICSplex SM.

2.4.5 Modifying your existing CICS system JCL

Take the JCL that you have for an existing CICS system that you want to be managed by CICSPlex SM, and make the following modifications to it: 1. Add the following data set to your STEPLIB (as before the variables used depend on the release of CICS TS that you are using: @[email protected] 2. Add the following to DFHRPL: @[email protected] 3. Add the following SIT parameter: CPSMCONN=LMAS 4. Add or change the SEC SIT parameter (you can turn on security at a later date): SEC=NO 5. Add the following DD card: //EYUPARM DD * NAME(@cicsname@) CICSPLEX(@plexname@) CMASSYSID(@cmssysid@)

The variable @cicsname@ is the name of the CICS system that we defined in the WUI, which must match the name defined in the WUI; otherwise, the system will not connect to the CICSplex. In our example, our system names are the

40 IBM CICS Explorer same as our systems' APPLIDs. The variable @plexname@ is the name of the CICSplex that we created in the WUI; however, in our example, this was TESTPLEX. The variable @cmssysidcmssysid@ is the system ID of the CICS system that is acting as out CMAS.

After you make these changes, submit your JCL, and start your managed CICS system. If the CICS system successfully connects to the CICSplex, you will see the following messages in the system log:

EYUXL0030I IYK3ZDD4 ESSS connection in progress to CICSPLEX(DWDPLEX1) for SYSID(DANA).

EYUXL0004I IYK3ZDD4 ESSS connection complete.

EYUCL0006I IYK3ZDD4 ESSS link to IYK3ZDD1 established.

EYUXL0007I IYK3ZDD4 LMAS Phase II initialization complete.

EYUNL0099I IYK3ZDD4 LMAS LRT initialization complete.

If the connection to the CICSplex fails, check that the NAME in the EYUPARM in your JCL matches the CICS system definition name for the definition you defined through the WUI.

Repeat this step for all of the CICS systems that you want CICSPlex SM to manage.

2.4.6 Conclusion

To set up CICSplex SM, you: 1. Turned a CICS system into a CMAS. 2. Turned a CICS system into a WUI server. 3. Created a CICSplex. 4. Defined your CICS systems to the CICSplex. 5. Modified your existing CICS systems to allow them to connect to the CICSplex.

You can now view information about your systems through the CICSPlex SM Web User Interface.

Chapter 2. Getting started with CICS Explorer 41 To test the Web browser functionality, use a URL of http://@hostname@:@portnumber@, where:

@hostname@ is the value that you specified on the TCPIPHOSTNAME option of the EYUWUI DD

@portnumber@ is the value of @portnumber@ that you specified on the TCPIPPORT option of the EYUWUI DD

2.5 Updating an existing CICSPlex SM setup for CICS Explorer

If you are already a CICSPlex SM user, to enable the CICS Management Client interface in your CICSPlex SM Web User Interface (WUI) server, update your WUI system parameters to include the new CMCIPORT parameter. The value specified is a TCP/IP port number to use for the CMCI. Each WUI server that is to provide CMCI support needs a unique (per TCP/IP Stack) port number for the CMCIPORT.

Example 2-10 shows a WUI System Parameter file that needs updating.

Example 2-10 Update the WUI system parameters (before update) //EYUWUI DD * TCPIPHOSTNAME(MYHOST.EXAMPLE.COM) TCPIPPORT(60666) DEFAULTCONTEXT(MYPLEX) DEFAULTSCOPE(MYSCOPE) DEFAULTCMASCTXT(MYCMAS) AUTOIMPORTDSN(CTS41.CPSM.SEYUVIEW) AUTOIMPORTMEM(EYUEA*) //

Example shows an updated parameter file.

Example 2-11 Updated WUI system parameters //EYUWUI DD * TCPIPHOSTNAME(MYHOST.EXAMPLE.COM) TCPIPPORT(60666) CMCIPORT(50666) DEFAULTCONTEXT(MYPLEX) DEFAULTSCOPE(MYSCOPE) DEFAULTCMASCTXT(MYCMAS) AUTOIMPORTDSN(CTS41.CPSM.SEYUVIEW)

42 IBM CICS Explorer AUTOIMPORTMEM(EYUEA*) //

To use CICS Explorer, set up a new CICS Management Interface connection. The host name must be the value of @hostname@ that you specified on the TCPIPHOSTNAME option of the WUI system parameters. The port number to use is the value of @cmciportnumber@ that you specified on the CMCIPORT option of the WUI system parameters. See Figure 2-9.

Before a Connection can be created, at least one Credential must exist. Figure 2-4 on page 25 shows the Credentials Preferences window where you define the UserID and Password pair that will be used by the Connections profiles you create.

Figure 2-9 Explorer connecting to CICSPlex SM CMCI

Chapter 2. Getting started with CICS Explorer 43

44 IBM CICS Explorer

Chapter 3. Implementing IBM CICS Explorer

In this chapter, we discuss how to install the CICS Explorer. We focus on local and remote installation and CICS Explorer Security.

CICS Explorer offers a range of installation options. In this section, we discuss the various options. When deciding on the best approach for installing the CICS Explorer within an organization it is important to consider your corporate guidelines and security requirements for client applications.

CICS Explorer can either be installed on each users local client machine or on a remote server for all users to access. Regardless of which option you choose, a users own customized data can be saved to the user private storage area.

Both local and remote installations of CICS Explorer start with the download of the appropriate distribution for your operating system. CICS Explorer is provided as an archive file: Windows file is a compressed file Linux is a tar file

To download CICS Explorer, visit the following web location, and then click the appropriate link under Downloads. http://www.ibm.com/software/htp/cics/explorer/

3.1.1 Installing CICS Explorer locally

We are going to show you two styles of installing CICS Explorer Simple Install Private Workspace Install

The Simple install gets you up and running with minimal set up. The Private Workspace install takes a little more set up but gives you more flexibility. Review each style, and use the one that meets your needs. Both install styles can be used for the Local and Remote installs.

Simple install The idea behind the Simple install is just that, simplicity. Basically all you do is download the install package, and extract the distribution file as appropriate for the operating system. Because there is no set up application required to install CICS Explorer, it is recommended that you expand the archive file to a suitable location on the system’s file system, for example c:\program files\ on Windows

and /opt/ on linux.

Figure 3-1 on page 47 shows the structure for Windows.

46 IBM CICS Explorer

Figure 3-1 Windows view

Figure 3-2 on page 48 shows the structure for Linux.

Chapter 3. Implementing IBM CICS Explorer 47

Figure 3-2 Linux view

You can create a desktop shortcut for the CICS Explorer executable file; however, essentially at this point basic installation is complete.

Along with the distribution code at run time, CICS Explorer creates a separate directory, known as the workspace, where user specific settings and customizations are written. By default this workspace is in your home directory: On Windows, the location is usually c:\Documents and Settings\<>\.cicsexplorer\ On Linux, the location is /home/<>/.cicsexplorer

Note: On some operating systems, folders that begin with a dot are not shown by default.

Figure 3-3 on page 49 through Figure 3-7 on page 51 illustrate the process.

48 IBM CICS Explorer 1. From the download site, select and download the appropriate package to your workstation:

http://www.ibm.com/software/htp/cics/explorer/

Download the CICS Explorer package

Zip File

Figure 3-3 Download the CICS Explorer package

2. Choose a Folder or Directory to unpackage the CICS Explorer binaries into, and extract the files, as shown in Figure 3-4.

Expand the Zip file

Zip File CICS Explorer Binaries

Figure 3-4 Expand the Zip file

3. Create a Shortcut icon that references the cicsexplorer.exe file, as shown in Figure 3-5 on page 50.

Chapter 3. Implementing IBM CICS Explorer 49

Create a shortcut icon

CICS Explorer Binaries

CICS Explorer

Figure 3-5 Create a shortcut icon

4. Start the CICS Explorer, set up a connection, and start Exploring your systems.

Figure 3-6 shows how a workspace named .cicsexplorer is created and is used from now on to store information about your CICS Explorer session.

Double click and start exploring

CICS Explorer Binaries

CICS Explorer

Shared Workspace

Figure 3-6 Start exploring

All changes, connections, and customization results in data being stored in the .cicsexplorer workspace; therefore, back up for recovery purposes.

Figure 3-7 on page 51 shows you that all instances of the CICS Explorer attempt to use this same workspace.

50 IBM CICS Explorer

Using a shared workspace

CICS Explorer Binaries

CICS Explorer

Shared Workspace

Shared Workspace file located in C:\Documents and Settings\username\ Shared by all CICS Explorer Binaries folders

Figure 3-7 Using a shared workspace

If you upgrade the CICS Explorer, the upgraded binaries start to use the shared workspace, thus you might experience problems if you attempt to run the older version due to changes made to your workspace.

Additionally, if you try to start a second instance of the CICS Explorer, it will also try and use the same workspace but will encounter a sharing failure message, as shown in Figure 3-8.

Figure 3-8 Workspace Sharing Lockout Exception

The Simple install method is designed to get you up and running quickly, but if you require more flexibility, such as the ability to run multiple CICS Explorers at the same time or want to run more than one version at a time, you might want to

Chapter 3. Implementing IBM CICS Explorer 51 explore using the Private Workspace install option that we describe in the next section.

Installing the private workspace This private workspace install option is also simple. It just includes an extra step to set up a parameter to create and uses a private workspace that allows you to run multiple instances and versions of the CICS Explorer:

Figure 3-9 through Figure 3-16 on page 57 walk you through the set up process to create and use a Private Workspace: 1. Select and download the appropriate package to your workstation from the following download site: http://www.ibm.com/software/htp/cics/explorer/

Download the CICS Explorer package

Zip File

Figure 3-9 Download the CICS Explorer package

2. Choose a Folder or Directory to unpackage the CICS Explorer binaries into, and extract the files, as shown in Figure 3-10 on page 53.

52 IBM CICS Explorer

Expand the Zip file

Zip File CICS Explorer Binaries

Figure 3-10 Expand the Zip file

3. Create a shortcut icon that references the cicsexplorer.exe file, as shown in Figure 3-11.

Create a shortcut icon

CICS Explorer Binaries

CICS Explorer

Figure 3-11 Create a shortcut icon

4. Display the Properties for the shortcut icon that you just created. Figure 3-12 on page 54 shows you the format of the -data parameter that is used to point the CICS Explorer to a private copy of the workspace.

Chapter 3. Implementing IBM CICS Explorer 53

Edit the shortcut icon adding –data parameter

CICS Explorer Binaries

CICS Explorer "C:\CICS Explorer r7\cicsexplorer.exe" -data "C:\Documents and Settings\Administrator\cicsexplorerR7"

Figure 3-12 Edit the icon adding the -data parameter

5. In the Target field, add the -data parameter followed by the location and custom name of your workspace, which are enclosed in parenthesis. In Figure 3-12, we use the version name in the binaries folder and the same version name in the workspace file name, so that the two can be recognized as a pair.

Double click and start exploring

CICS Explorer Binaries

CICS Explorer

Non-shared Private Workspace

Figure 3-13 Start exploring

54 IBM CICS Explorer When you start your explorer, it uses the directory and name that are provided in the -data parameter to create your private workspace.

Tip: At this point the .cicsexplorer workspace used by the Simple install method can exist at the same time; therefore, you can use both install methods simultaneously, and any additional CICS Explorer that is started without the -data parameter will attempt to use the shared .cicsexplorer workspace.

With each additional install or shortcut icon that you create, use a different version of the workspace through the -data parameter, which allows multiple versions and running instances.

Figure 3-14 shows our running CICS Explorer pointing to its own private workspace.

Using a private non-shared workspace

CICS Explorer Binaries

CICS Explorer

Non-shared Private Workspace

Non-Shared Private Workspace Unique for this CICS Explorer Binaries folder

Figure 3-14 Using a private non-shared workspace

If you copy a shortcut icon or create a new one, you must modify the Target information to always point to a new private workspace; otherwise, you will end up with the same issues as the Simple install where you share the workspace.

Figure 3-15 on page 56 shows a new shortcut icon being created using a different binaries folder and workspace. Comparing the shortcut icon in Figure 3-12 on page 54 and the one in Figure 3-15 on page 56 you can see

Chapter 3. Implementing IBM CICS Explorer 55 that if we start both CICS Explorers up simultaneously, they use different Binaries and workspaces.

"C:\CICS Explorer r7\cicsexplorer.exe" -data "C:\Documents and Settings\Administrator\cicsexplorerR7"

The –data parameter points to a unique copy of the workspace that is private for this version of the CICS Explorer Binaries Folder

Figure 3-15 Setup of the -data parameter

6. Finally Figure 3-16 on page 57 shows how two different versions can be managed and run simultaneously. We recommend that you backup the binaries and workspaces as a pair because if one is, lost, damaged, or corrupted, you can easily recover it.

56 IBM CICS Explorer

Allows for multiple versions and concurrently running CICS Explorers

CICS Explorer Binaries CICS Explorer Binaries

V 1.0.0.6 V 1.0.0.7

Non-shared Non-shared V 1.0.0.6 V 1.0.0.7 Private Workspace Private Workspace

Backup and Recovery

Treat each pair as a single unit

Figure 3-16 Binaries / Workspace pairs

If you recover a Binary/Workspace pair, you must create a new shortcut icon using an appropriately configured -data parm to link the two together.

3.1.2 Installing CICS Explorer remotely

You can also install CICS Explorer on a remote server for clients to access. The benefits of this remote server include only having one single copy of the binary to update; however, execution might be a little slower than running the client locally.

The simplest way to install CICS Explorer remotely is to install CICS Explorer onto a shared drive. Each client machine can then access the shared drive. Individual users can then start the CICS Explorer by directly running the executable file or by creating a local shortcut for the remote executable on the local machine. When CICS Explorer is run this way, the user’s workspace is written to their local machine, unless explicitly specified. (See 3.1.1, “Installing CICS Explorer locally” on page 46). When CICS Explorer is run from a remote drive there might be a delay in the time that it takes for CICS Explorer to start because the binary data is copied over the network.

The benefits of running CICS Explorer remotely are that maintenance needs only to be applied to a single copy of the application binary, and it also removes the overhead of rolling the application out to every workstation. The disadvantage of running CICS Explorer remotely is that the initial start time of CICS Explorer can be longer than if it were running locally.

Chapter 3. Implementing IBM CICS Explorer 57 You can run CICS Explorer remotely regardless of which operating system is used because the remote server is just acting as a file store. All of the processing is performed on the local machine.

You can also run CICS Explorer from a shared Linux server using any windows

system to allow the GUI to be displayed on a user’s local terminal by installing the CICS Explorer onto a Linux server in a location that is readable by logged on users. Users can log onto the remote system using their preferred Windows package. After the users log on, they can run CICS Explorer on the remote system. When CICS Explorer is being run from a remote Linux server in this manner, the CICS Explorer binary executes on the server using the server’s memory and CPU resources. The user’s workspace is stored in the user’s home directory and not on the local workstation.

3.2 CICS Explorer security

There are several areas to consider in regards to the CICS Explorer and Security depending on which type of connection you are using. Regardless of your connection type, Link Security and Credential Authorization are also available.

In this section, we address the following four areas: Link Security Credential Authorization Security for a stand-alone CICS Region connection Security for a CICSPlex SM connection

3.2.1 Link Security

When CICS Explorer connects to any CICS system it can encrypt the link between it and the remote system. By default CICS Explorer uses unsecured HTTP requests, which means that system information flows over the network as plain text.

Secure Sockets Layer (SSL) encryption can be used to encrypt the data flow between CICS Explorer and CICS, which are both supported by changing the TCP/IP Service that is used by the CICS Explorer to connect to the CICS system.

See 3.2.5, “Using SSL” on page 59 for Link Security setup.

58 IBM CICS Explorer 3.2.2 Credential authorization

When connecting to a CICS System through CICS Explorer users must use the

same credentials they use to log directly into either the CICS region for a stand-alone CICS Region (SMSS) connection or into the CICSPlex SM Web User Interface for a CICSPlex SM connection. When the user makes a request against the system, CICS or the CMAS verifies that the credentials are correct and that the user has the correct authority to make that request.

See 3.2.6, “Using HTTP Basic Authentication” on page 60 for Authentication Security setup.

3.2.3 Security for a stand-alone CICS Region (SMSS) connection

When connecting to a single CICS region through a stand-alone CICS region (SMSS) connection, CICS Explorer uses existing CICS Command and Resources security profiles to allow or reject requests; therefore, the same level of security that is available within your existing CICS environment is available through the CICS explorer.

3.2.4 Security for a CICSPlex SM connection

When connecting to a CICSPlex through a CICSPlex SM connection, CICS Explorer uses CICSPlex System Manager to process or reject requests using CICSPlex SM security. The same level of security that is available in your existing CICSPlex SM environment is available through the CICS explorer.

Tip: CICSPlex SM security uses the CPSMOBJ profiles on top of existing Command and Resource level profiles to secure a CICSPlex SM environment; whereas, only Command and Resource level profiles are used to secure stand-alone CICS region (SMSS) connections.

3.2.5 Using SSL

CICS Explorer can use SSL to encrypt the link between it and the CICS system. However CICS Explorer cannot use a private certificate to affirm a user ID. The process is slightly different depending on if you are connecting CICS Explorer to a WUI server or a single CICS region.

Chapter 3. Implementing IBM CICS Explorer 59 SSL connection to a WUI server Add the following WUIPARMS: TCPIPSSL(YES) TCPIPSSLCERT(NAME)

The name of the TCPIPSSLCERT must be the name of a certificate that is attached to the keyring that is specified in the keyring SIT parameter. If TCPIPSSLCERT is omitted, the default certificate that is attached to the keyring is used instead.

Setting this parameters ensures that when CICS defines the TCP/IP Service resource definition for the CMCI port that the correct attributes are set for SSL operation.

SSL connection to a single CICS region Change the TCPIPService resource that you are using to connect to the CICS region:

SSL = YES

You also must ensure that you have a default certificate specified in the keyring that CICS is using.

3.2.6 Using HTTP Basic Authentication

When using HTTP Basic Authentication, when you attempt to make a connection to the TCP/IP port, you are prompted to provide a username and password before the connection is established. HTTP basic authentication can be used to provide a level of DOS attack protection because only users with valid credentials are allowed to make a connection.

To use HTTP basic authentication in your environment, you must specify the value basic for the Authenticate property of the TCP/IP Service that is used as the entry point for the CICS Explorer.

During a connection attempt, CICS Explorer uses the same credentials that you specified in the connection preferences in response to a HTTP Basic Authentication Challenge.

Tip: If the system you are connecting to does not require you to sign on, you

must enter a username into the connection preferences panel, but you can leave the password field blank.

60 IBM CICS Explorer 3.2.7 CICSPlex Security Scenario

Full details regarding CICSPlex security definitions are in the CICSPlex SM

security section, in the CICSPlex manual.

RACF® security profiles can be created based on function.type.context.scope: Function: CICSPlex function impacted by the RACF Profile, for example, ANALYSIS – Real Time Analysis, OPERATE – Operations, and so on. Type: Valid subgroup of the function, for example, for function OPERATE, a valid type is PROGRAM. Context: Either the fully qualified or generic name of a CMAS or CICSplex: • In the case of CONFIG or TOPOLOGY, the context must be a CMAS. • For all other definitions, the context must be a CICSplex. Scope: Either the fully qualified or generic name of a CICS system: • In this context, scope cannot be used to specify a CICSPlex Topology group or CICSPlex BAS logical scope. • You cannot specify scope when context is a CMAS or type is DEF unless you are defining security rules for CSD resources.

Details regarding the use of READ, ALTER, and UPDATE: READ allows users to VIEW resources. In the case of the OPERATE and BAS functions: – UPDATE allows NEWCOPY, SET, OPE, CLO, and MODIFY (including Shutdown on OPERATE.REGION). – ALTER allows INSTALL, DISCARD, CREATE, and DELETE. For all functions other than OPERATE and BAS: – UPDATE allows INSTALL, DISCARD, CREATE, DELETE, and MODIFY. – ALTER only applies to OPERATE and BAS definitions.

Details regarding the CICSPlex Security Scenario. The company Redbooks is creating CICSPlex RACF security profiles, which must achieve the following objectives: Give all users READ access to all resources. Limit administration of the following CICSPlex functions to the Company CICS team members: – ANALYSIS – BAS –CONFIG

Chapter 3. Implementing IBM CICS Explorer 61 –CSD – MONITOR – TOPOLOGY –WORKLOAD Allow the same resource access, within the CICSPlex OPERATE function rules, as currently defined within their RACF command-level security rules. This access currently differs between their Test and Production environments. Set up a rule to allow READ only access for any other CICSPlex functions and types that were not secured. This rule is intended as a fail-safe for anything not covered in their new security profiles. Create rules that can be shared across all their Test and Production environments. Currently all of their Production CICSplex environments begin with PLXP, and all of their Test environments use PLXT.

In Figure 3-17 on page 63, we can see that the following techniques were used to achieve all of the Company Redbooks objectives: User * was given READ access in all cases. The ANALYSIS, BAS, CONFIG, CSD, MONITOR, TOPOLOGY, and WORKLOAD functions were left generic with regard to type.context.scope, allowing those security rules (restricting administration access to the CICS team) to be used across all environments: – The OPERATE function was broken down by type. – In cases where the rules for the OPERATE function type are the same for all environments, no context is used. – In cases where the rules for the Test and Production environments differ, a generic context (representing the Production PLXP* and Test PLXT* environments) was used. – Company RedBooks associated the RACF user groups, appropriate to the function.type.context, based on their current RACF command level security rules. The ** rule allows READ-only access for anything that is not covered, which provides a fail-safe.

Figure 3-17 on page 63 shows Company Redbooks CICSPlex security matrix.

62 IBM CICS Explorer RACF Groups Associated with the CPSMOBJ CLASSES Any User CICS Team Operations Development SR CLASS(CPSMOBJ) Environment (USER*) (CICSGRP) (OPERGRP) (DEVGRP) ANALYSIS.** ALL Read Update BAS.** ALL Read After CONFIG.** ALL Read Update CSD.** ALL Read After OPERATE.AIMODEL.** ALL Read After Update OPERATE.BRFACIL.** ALL Read After Update OPERATE.CONNECT.PLXT*.** Test Read After Update Update OPERATE.CONNECT.PLXP*.** Prod Read After Update OPERATE.DB2D BCTL.** ALL Read After Update OPERATE.DOCTEMP.PLXT*.** Test Read After Update Update OPERATE.DOCTEMP.PLXP*.** Prod Read After Update OPERATE.ENQMODEL.** ALL Read After Update OPERATE.ENTJAVA.** ALL Read After Update OPERATE.EXIT.** ALL Read After Update OPERATE.FEPI.** ALL Read After Update OPERATE.FILE.PLXT*.** Test Read After Update Update OPERATE.FILE.PLXP*.** Prod Read After Update OPERATE.IPCONN.PLXT*.** Test Read After Update Update OPERATE.IPCONN.PLXP*.** Prod Read After Update OPERATE.JOURNAL.** ALL Read After Update OPERATE.PARTNER.** ALL Read After Update OPERATE.PROCTYPE.** ALL Read After Update OPERATE.PROFILE.** ALL Read After Update OPERATE.PROGRAM.PLXT*.** Test Read After Update Update OPERATE.PROGRAM.PLXP*.** Prod Read After Update OPERATE.REGION.** ALL Read After Update OPERATE.RQMODEL.** ALL Read After Update OPERATE.TASK.PLXT*.** Test Read After Update Update OPERATE.TASK.PLXP*.** Prod Read After Update OPERATE.TCPIPS.PLXP*.** Test Read After Update Update OPERATE.TCPIPS.PLXT*.** Prod Read After Update OPERATE.TDQUEUE.PLXT*.** Test Read After Update Update OPERATE.TDQUEUE.PLXP*.** Prod Read After Update OPERATE.TERMINAL.PLXT*.** Test Read After Update Update OPERATE.TERMINAL.PLXP*.** Prod Read After Update OPERATE.TRAN.PLXT*.** Test Read After Update Update OPERATE.TRAN.PLXP*.** Prod Read After Update OPERATE.TSQUEUE.PLXT*.** Test Read After Update Update OPERATE.TSQUEUE.PLXP*.** Prod Read After Update OPERATE.UOW.** ALL Read After Update TOPOLOGY.** ALL Read Update WORKLOAD.** ALL Read Update ** ALL Read Update Figure 3-17 Company Redbooks CICSPlex security matrix

3.3 Updating the CICS Explorer

Because CICS Explorer is built on Eclipse technology, you can automatically update it using the same mechanism that is used to update Eclipse.

Chapter 3. Implementing IBM CICS Explorer 63 3.3.1 Updating from the Internet

You can update CICS Explorer directly from a Web server. IBM hosts an update

site that contains updated versions of the CICS Explorer. Alternatively, your enterprise might provide an internal site.

CICS Explorer updates: All CICS Explorer updates are available from: http://download.boulder.ibm.com/ibmdl/pub/software/htp/cics/updates/ explorer/

To update the CICS Explorer from the IBM site: 1. From the Help menu, select Software Updates. 2. From the Installed Software tab, select IBM CICS Explorer, as shown in Figure 3-18. 3. Click Update.

Figure 3-18 Software Updates window

CICS Explorer downloads and installs the updates.

64 IBM CICS Explorer If your system administrator supplied you with a URL to use as an internal mirror of the IBM update site, alter your configuration to remove the IBM update site, and add the internal one:

1. From the Help menu, select Software Updates.

2. From the Available Software tab, select Manage Sites. 3. Select the site that points to: http://download.boulder.ibm.com/ibmdl/pub/software/htp/cics/updates/ explorer/ 4. Click Remove. The IBM site is now removed from the list of update sites. Now add your internal site, and click Add. 5. In the next dialog, enter the name of the update site as provided to you by your system administrator, and click OK.

You can now update the CICS Explorer as shown. If the Web server that is hosting the update site requires authentication, you are prompted for your credentials.

Restriction: Because of issues surrounding the update mechanism, we do not recommend that you allow CICS Explorer to save your password when connecting to an update site.

3.3.2 Updating from an archive file

If you cannot connect to the Internet to update CICS Explorer, it is possible to update from a local archive file. An archive file is a compressed file that contains the same content that the update site contains.

To update CICS Explorer from an archive file: 1. Download the archive file to your local machine. Put the file in a location that you can remember. 2. From the Help menu, select Software Updates. 3. From the Available Software tab, select Manage Sites. 4. Click Add  Archive. 5. On the next dialog, navigate to the archive file that you downloaded. 6. Click Open  OK.

You can now update the CICS Explorer, as we discussed in 3.3.1, “Updating from the Internet” on page 64.

Chapter 3. Implementing IBM CICS Explorer 65 3.3.3 Updating automatically

After you configure CICS Explorer with an update site that the software can

access, you can configure CICS Explorer to automatically search for updates on a regular basis, which ensures that you are kept up-to-date with new features of the CICS Explorer: 1. From the Help menu, select Software Updates. 2. Expand Install/Update. 3. Select Automatic Updates. Figure 3-19 is displayed.

Figure 3-19 Automatic Update dialog

4. The dialog in Figure 3-19 gives options that allow you to specify when to check the update site for new updates. After you make your selections, click Apply  OK.

66 IBM CICS Explorer 3.4 Enterprise deployment

In this section, we discuss enterprise deployment of CICS Explorer.

3.4.1 Providing local mirrors

If your enterprise does not allow for users to access the Internet, it is possible to set up an internal mirror of CICS Explorer. Users can install and receive updates from the local mirror.

The CICS Explorer installation archive file can be freely downloaded and stored on an internal server to allow internal downloads. Alternatively it can be incorporated into an automated software delivery system.

Archive sites: The archive site files are stored separately on the main update site: http://www.ibm.com/support/fixcentral/

CICS Explorer is under the product group WebSphere.

If you are providing a local mirror for users, you might also want to provide a local mirror of the IBM update site so that users can update their copy of CICS Explorer. This can either be a local copy of the update archive file or a copy of the entire update site.

The best practice is to provide a mirror of the IBM update site that is regularly updated. Using this method users can automatically update CICS Explorer from the local mirror with little intervention, ensuring that users are always using the most up-to-date version of the software.

Obtaining an archive site file To download an archive site file: 1. Go to the IBM Fix Central web site at: http://www.ibm.com/support/fixcentral/ 2. Enter the requested information, as shown in Figure 3-20 on page 68.

Chapter 3. Implementing IBM CICS Explorer 67

Figure 3-20 Fix Central site

Set the Installed Version to your current CICS Explorer release. Set the Platform to the one that is appropriate for your installation. 3. Click Continue. 4. Identify the fixes that you want to include in the archive site file, as shown in Figure 3-21 on page 69.

68 IBM CICS Explorer

Figure 3-21 Fix Central Fix Identification panel

5. Click Continue. You are presented with a fix pack containing all of the fixes that match your selection criteria, as shown in Figure 3-22 on page 70.

Chapter 3. Implementing IBM CICS Explorer 69

Figure 3-22 Fix Central Fix pack panel

You can get more information, regarding the fix pack by following the link provided. You can also choose to select the fix pack provided, or use the Refine results drop-down to further refine your search criteria. 6. Select the desired fix pack and click Continue. You are asked to specify your download options, as shown in Figure 3-23 on page 71.

70 IBM CICS Explorer

Figure 3-23 Fix Central Download Options panel

7. After selecting your download options, click Continue. You are provided with the link to download the fix pack.

You can now update the CICS Explorer, as shown in 3.3.1, “Updating from the Internet” on page 64.

3.4.2 Pre-installation customization

When considering implementing CICS Explorer within an enterprise you might want to provide some customizations that are specific to your organization, for example, pre-configured connection information to your CICS systems and custom panel layouts for specific user groups.

CICS Explorer saves customization and preferences within a folder known as the workspace. If you want to provide pre-installation customizations to the CICS Explorer, you must also provide a copy of the workspace that contains the customizations and ensure that your users start CICS Explorer correctly to use this workspace: 1. Install CICS Explorer using -data <> to specify a new workspace.

Workspace Location: Record the location of the workspace folder because you will need it later.

Chapter 3. Implementing IBM CICS Explorer 71 2. Make your customizations.

3. Export the created workspace to an archive.

Customizing perspectives

You can customize the CICS Explorer to create new perspectives. Custom perspectives can be useful to complete certain tasks, for example, when investigating why a certain resource is failing, it is useful to only see the views that are associated with that resource. Working with CICS Web services might only require the web service, pipeline, urimap, and TCP/IP operational views. Creating new application definitions require the definitional views.

Restriction: You cannot add internal update site locations to a customized workspace.

To create a new perspective, change and arrange the number of views on display by: Opening new views Closing open views Changing the position and size of a view Changing the columns that are displayed as part of a view

After the window is arranged as required: 1. On the menu bar, click Window. 2. Click Save Perspective As. 3. Enter a useful name for the new perspective, and click OK.

The perspective is now saved and available from the Window, Open Perspective dialog.

Customizing connection details You can pre-customize CICS Explorer to have predefined connection definitions to the CICS systems that your users want to connect to: 1. On the menu bar, click Window. 2. Select Preferences  Connections. 3. Enter the connection details.

Tip: When entering connection details do not enter your own user ID and password; however, you must enter some text in the userID field to ensure that CICS Explorer saves the connection. We suggest that you enter USER.

4. Click Apply, and then click OK.

72 IBM CICS Explorer After you finish customizing the CICS Explorer, you must close it before you can successfully export the workspace.

Now you can compress the workspace into an archive file to share with your users.

Important: Ensure the integrity of the archive after you create it. Some compression programs omit folders and files that begin with the ‘.’ character. Such files exist in the workspace.

To consume the customizations, extract the workspace to your local machine. When starting the CICS Explorer, specify where to extract the workspace to.

3.5 Using plug-ins

The individual plug-ins are downloaded from the appropriate support sites in the form of a site compressed file that contains the executable code and the necessary licence agreements. After the file is downloaded onto your machine, it can be integrated into the installation: 1. From the Help menu, select Software Updates, as shown in Figure 3-24.

Figure 3-24 Software Updates menu

2. Click the Available Software tab, and click Manage Sites, as shown in Figure 3-25 on page 74.

Chapter 3. Implementing IBM CICS Explorer 73

Figure 3-25 Available Software tab

3. Click Add. In the Add Site pop-up, shown in Figure 3-26 on page 75, click Archive to select the compressed file that you downloaded.

74 IBM CICS Explorer

Figure 3-26 Add Site window

4. Click OK to close the pop-up. 5. Click OK to close the Available Software Sites window. 6. In the Available Software tab, select the plug-in that you want to install, as shown in Figure 3-27 on page 76.

Chapter 3. Implementing IBM CICS Explorer 75

Figure 3-27 Plug-in check box

7. Click Install. Eclipse ensures that your selection is compatible with your installation. If everything is fine, Eclipse prompts you to accept the terms of the license agreement. 8. Agree to the terms of the license, and then click Finish. 9. After the installation is finished, you are prompted to restart CICS Explorer. Click Yes. After the installation is complete, the Welcome window is displayed to show the new functionality that was added to CICS Explorer.

76 IBM CICS Explorer

Chapter 4. CICS Explorer base familiarization

In this chapter, we look at the CICS Explorer base and discuss perspectives, connections, views, and the editor.

CICS Explorer provides two perspectives for interacting with CICS: Resource The Resource perspective is primarily concerned with the manipulation of event bindings and bundle projects. CICS SM The CICS SM perspective is concerned with the viewing and manipulation of CICS resources and is the focus of this chapter.

4.2 Connections and credentials

In this section, we discuss setting up connections and credentials.

4.2.1 Connection Manager

In the Explorer, the status of any connections are represented by the Connection Manager, which resides in the bottom right corner of the Explorer window, as shown in Figure 4-1 on page 79.

78 IBM CICS Explorer

Figure 4-1 Connection Manager location

When the CICS Explorer is configured with some connections, clicking the arrow on the connection status trim widget displays a list of available connections. Selecting one of these causes the CICS Explorer to attempt to establish that connection using the saved details. The connection manager icon represents the state of the named connection. Table 4-1 shows the Connection Manager status icons.

Table 4-1 Connection Manager status icons

Connection Status icon Connection state

Disconnected

Connecting

Chapter 4. CICS Explorer base familiarization 79 Connection Status icon Connection state

Connection Established

Secure Connection Established

Connection Error

When you click the red square, the system attempts to connect to the currently named connection. While connecting, the icon changes to a yellow diamond. A successfully established connection is represented by a green circle. When a connection is established, clicking the green circle causes the Explorer to disconnect.

4.2.2 Connections and Credentials Preference pages

Connections and Credentials provide the CICS Explorer details about the CICS system you are connecting to, such as its location and authentication requirements. The credentials provide the CICS Explorer the required UserID and Password information to complete the connection. In the CICS Explorer connection, information is managed through the Connections Preference page.

Before you can create a connection you must first define at least one credential.

To access the Connections Preference page: 1. Click the text on the connection status trim widget or use the menus Window  Preferences, to open the preferences dialog. 2. From the tree on the left side, select Credentials, as shown in Figure 4-2 on page 81.

80 IBM CICS Explorer

Figure 4-2 Credentials Preferences page

3. Click New, and enter a UserID and optionally a password, and give it a meaningful name that you will use to reference this UserId / Password pair. 4. Click Apply to store your credentials. You might need several credentials based on how many different systems you need to access. The Name and User ID fields are mandatory. Passwords can optionally be specified. If a password is not specified, CICS Explorer prompts for one when establishing a connection. After you have your credentials defined, you can continue creating your connections definitions. 5. From the tree on the left side, select Connections, as shown in Figure 4-3 on page 82.

Chapter 4. CICS Explorer base familiarization 81

Figure 4-3 Connections Preferences page

To enter details for a new connection: 1. Select the type of connection that you want to define, and click New. 2. Give your connection a meaningful name, which is displayed in the Connection Manager widget on the bottom right of the CICS Explorer. 3. Fill in the URL to your Host LPAR and the port number that either your WUI region is listening on or your single region is listening with. 4. Expand the Credentials box, and select the appropriate ID credentials. 5. After you specify your connection details, click Apply to save them. Alternately, you can click OK to save and close the preferences dialog.

Connections are categorized in the preferences page based on connection type. To view available connections for a specific connection type, in the Type combo, select the type of connection you want to examine. The Name combo is then populated with a list of connections of that type from which you can select.

The Type, Name, Host name, Port number, and Credential are mandatory.

82 IBM CICS Explorer 4.2.3 CICS Explorer connectivity

In our CICS Explorer, we click Window  Preferences, and select the

connection settings field, as shown in Figure 4-4.

Figure 4-4 Explorer preferences

We use connection type CICS management client interface (CMCI), as shown in Figure 4-5.

Figure 4-5 CICS Explorer connection options

Chapter 4. CICS Explorer base familiarization 83 Connection type: We use connection type CICS Management Interface to enable update capability. The default connection type, CICSPlex SM Data Interface, allows read-only capability.

Our Web user interface (WUI) server (Hostname: wtsc66.itso.ibm.com) has port = 16001. The CMCIPORT system initialization parameter for our WUI is set as CMCIPORT =16001.

In the CICS Transaction Server for z/OS Version 4 Information Center, read Setting up the CICS management client interface for further details: https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/ com.ibm.cics.ts.clientapi.doc/topics/clientapi_setup.html

4.3 Views

In this section, we look at the two types of views: tabular and tree.

The context limits what data is displayed in most views: The context of a view can be manipulated by the CICSplex Explorer view or the CICSplex Repositories view. The CICSplex Explorer view can be used to set the context to a CICSplex or CICS region. The CICSplex Repositories view can be used to set the context to a resource group or system group. The Resource Group Definitions view can also be used to set the context to a resource group.

CICS Object Table Views use the last appropriate context that the user selected when populating, for example, only CICS definition views repopulate using a resource group because of their context when one is selected by the user.

4.3.1 The CICSplex Explorer view

When connected to CICSPlex SM, the CICSplex Explorer view, which is shown in Figure 4-6 on page 85, displays a list of CICSplexes. When using CMCI to connect to a single CICS region, the CICSplex Explorer view shows the region to which you are connected.

84 IBM CICS Explorer

Figure 4-6 The CICSplex Explorer view

Expanding a CICSplex shows the managed regions within that CICSplex. If the icon is colored, then the managed region is active. If the icon is monochrome, the region is inactive.

Selecting a CICSplex or a managed region sets the context accordingly.

4.3.2 The CICSplex Repositories view

The CICSplex Repositories view, shown in Figure 4-7 on page 86, shows the available resource groups, the available system groups, and their members.

Chapter 4. CICS Explorer base familiarization 85

Figure 4-7 CICSplex Repositories view

Table 4-2 shows the icons for the CICSplex Repositories view.

Table 4-2 CICSplex Repositories view icons Icon CICS object

System Definition

System Group

Resource Group

Selecting any of these resources in the CICSplex Repositories view sets the context of any open CICS Object Table view where appropriate. System groups can be expanded to view their members, which might be either nested system groups or system definitions.

4.3.3 CICS Object Table views

CICS Object Table views display CICS resources of a specific type from the current context. You cannot open Resources views from the Administration, Operations, WLM, and RTA menus.

86 IBM CICS Explorer Operations views The Operations views are: Atom Services Bundles Bundle Parts Capture Specifications CMAS to CMAS Links Completed Tasks CorbaServers DBCTL Subsystems DB2 Connections DB2 Entries DB2 Transactions Document Templates Event Bindings Event Processing Files Global Dynamic Storage Areas Interval Control Requests IPIC Connections ISC/MRO Connections JVM Class Caches JVM Pools JVM Profiles JVM Servers JVM Status Libraries Library DS Name Pipelines Process Types Programs Regions RPL List Tasks Task Associations TCP/IP Services TD Queues Ter minals Transactions Transaction Classes TS Models TS Queues Unit Of Work Enqueues URI Maps

Chapter 4. CICS Explorer base familiarization 87 Web Services WebSphere MQ Connections WebSphere MQ Connection Statistics WebSphere MQ Initiation Queues XML Transforms CICSplexes CMAS Details

Administration views The Administration views are: Atom Service Definitions Bundle Definitions CICSPlex Definitions CMAS to CMAS Link Definitions CorbaServer Definitions DB2 Connection Definitions DB2 Entry Definitions DB2 Transaction Definitions Deployed JAR File Definitions Document Template Definitions Enqueue Model Definitions File Definitions IPIC Connection Definitions ISC/MRO Connection Definitions Journal Model Definitions JVM Server Definitions Library Definitions LSR Pool Definitions Map Set Definitions Partition Set Definitions Partner Definitions Pipeline Definitions Process Type Definitions Profile Definitions Program Definitions Request Model Definitions Session Definitions System Definitions System Group Definitions TCP/IP Service Definitions TD Queue Definitions Terminal Definitions Transaction Definitions Transaction Class Definitions

88 IBM CICS Explorer TS Model Definitions Typeterm Definitions URI Mapping Definitions Web Service Definitions WebSphere MQ Connection Definitions Group List Definitions Resource Group Definitions

RTA views The RTA view is: Events

WLM views The WLM view is: Active Workloads

4.4 The Resources view

Figure 4-8 illustrates the anatomy of a Resources view.

Figure 4-8 Anatomy of a Resources view

The Resources views are tabular views, where each row corresponds to a CICS resource in the current context. Each column represents a different attribute on the CICS resource type. At the top of each resource view is a status bar that is

Chapter 4. CICS Explorer base familiarization 89 specific to that view, showing the context that is being used to populate the view, the CICS name for the resource that the view is displaying, the number of records that were available the last time the content was refreshed, and the time that the view content was last refreshed. To manually refresh the content of a Resources view, click Refresh, and the view automatically refreshes, if visible when the context changes.

To minimize network traffic and server load, CICS Explorer only retrieves enough resources to fill the visible portion of the table. The remainder of the resources are retrieved as the table is scrolled. A consequence of this is that if you are viewing a resource for which a large number of records exist, you might have to wait for the table to be populated as you scroll.

CICS Explorer uses two special values to represent some attribute state, N/A and ?: If an attribute is not supported on an older release of CICS in a CICSplex, the explorer populates its cell in the column with N/A. If CICS Explorer encounters an unexpected value for an attribute, its cell in the column is populated with ?.

Values that represent attribute state: Both of these values are legitimate string values for attributes, so you must carefully determine their meaning.

Columns Each column in a CICS resource view represents a specific attribute on the type of resource that is being viewed. You can manipulate columns in a resource view, as shown in Figure 4-9 on page 91, by dragging them to a different position to change the order or by dragging the column separators to change the width. Any changes that you make to the layout of the table are persisted by CICS Explorer.

Each resource view has a predefined set of default columns to display, which you can customize by going to the view menu and selecting Customize Columns.

90 IBM CICS Explorer

Figure 4-9 The Customize Columns dialog

In the Customize Columns window, you can: Move attributes between the left list of available attributes and the right list of displayed attributes by selecting them from a list and clicking Add or Remove as appropriate. Click Close to apply your changes. Click Reset to revert the displayed columns to the predefined defaults. Reset the columns to the default state by selecting Reset Columns from the view menu.

Note: If you set the columns for a view without connecting, establish a connection and further customize the columns. Selecting reset columns resets them to the state that you established without a connection.

Filtering CICS Object Table Views can be filtered upon the value of most attributes. The filter area, Figure 4-10 on page 92, displays the currently selected filter fields and the values being used as filter criteria. Each CICS Resource view has a default filter field that is initially presented. You can select additional filter fields by checking the appropriate box from the Choose filter attributes submenu in the view menu. The submenu displays a list of check boxes that represent all currently visible columns in the view. To filter on additional attributes, you must

Chapter 4. CICS Explorer base familiarization 91 first add them to the table using the customize columns dialog. Remove filter fields by clearing them from this list.

Attribute filtering: You cannot filter on date attributes. You cannot filter on Region Name or CICS Release.

12 34

1. Filter Field Name 2. Filter Field Control 3. Apply Filter Button 4. Clear Filter Button Figure 4-10 Filter area anatomy

For each filter field that is added to the view, the filter area will display the attribute name and an appropriate control for entering a value upon which to restrict the content of the view, either a text box or a combo field.

To apply a text filter: 1. Enter the characters on which you want to filter into the text box. 2. Either press Enter or click Apply Filter. 3. Append an * character to the end of your filter string as a wildcard, matching any subsequent combination of characters.

To apply a combo filter: 1. Select one of the available options from the list, and click Apply Filter. 2. Select the blank entry to make CICS Explorer disregard that filter. 3. Click Clear Filter to set the value of all of the displayed filters to blank, but they are not removed from the view. The state of the filter area is saved by CICS Explorer and recreated when the view is opened.

CICS Object Table views with multiple types In some cases, a CICS Resource view can reflect results for multiple CICS Resources, for example, the TD Queues view can display either Indirect, Extrapartition, Intrapartition, or Remote TD Queues.

Figure 4-11 on page 93 shows the location of the toolbar from which the resource type for a view can be switched. Hover the cursor over each button to

92 IBM CICS Explorer determine the type of resource that is represented. The type of resource last used to populate the view is displayed in the view status bar.

Figure 4-11 Resource selection toolbar location

Table 4-3 shows the views that support multiple resources.

Table 4-3 Views supporting multiple resources View name Supported CICS resources

TD Queues EXTRATDQ INDTDQ INTRATDQ REMTDQ

Files LOCFILE REMFILE

Transactions LOCTRAN REMTRAN

Performing actions You can perform actions on resources from the Resources View by right-clicking and selecting the action that you want to perform from the context menu. Actions can be performed on a selection of multiple resources in a similar way. Actions can only be performed where supported by the underlying connection, which means that you must have a CMCI connection or the actions are disabled in the menus.

Upon a request to perform an action, the CICS Explorer presents you with a confirmation dialog, as shown in Figure 4-12 on page 94, which displays the selected resource names and the action to be performed.

Chapter 4. CICS Explorer base familiarization 93

Figure 4-12 Perform action confirmation dialog

Clicking OK attempts to perform the action on the displayed list of resources—one by one. If too many resources are selected to list, the total number of resources is displayed instead. A progress bar and status message are displayed as the explorer performs the action. The Cancel button remains available to halt action processing part-way through.

CICS Explorer stops processing actions if any action fails. When action processing is completed, the results are displayed in the dialog, and a status message for each action is written to the status bar and the error log. Figure 4-13 on page 95 is an example of an action processing failure message.

Stopping the Explorer: An action processing failure or cancelling action processing stops the Explorer from carrying out any further actions. It will not undo the effect of actions that already processed.

94 IBM CICS Explorer

Figure 4-13 Action processing failure

Installing definitions To install CICS definitions: 1. Right-click, and select Install from the context menu. The Install dialog shows a list of all valid install targets, which includes system groups and managed regions, as shown in Figure 4-14.

Figure 4-14 Install dialog

2. Select an install target, and click OK to install the definition into the selected target. Successful installation results in a confirmation message being written to the error log. If the install fails, an error message is displayed in the status bar and in the error log.

Chapter 4. CICS Explorer base familiarization 95 Editing CICS Resources You can open CICS Resources in an editor by right-clicking and selecting Open; alternately, you can double-click the resource. If the connection that is used to retrieve the resource is a CMCI connection, the resource is made modifiable in the resulting editor. If the underlying connection is through the CICSPlex SM Data Interface, the editor opens in a read-only mode.

4.4.1 Properties view

The Properties view, shown in Figure 4-15, displays a table of attributes for the last selected CICS Resource. The attributes are displayed by category. Changing the selection in any Resources View causes the Properties View to update itself to display the attributes for the newly selected resource.

Figure 4-15 Properties view

4.4.2 Status bar and Error Log

The status bar and the Error Log view communicate feedback to you about the success or failure of operations. The status bar is located at the bottom of the Explorer window, as shown in Figure 4-16 on page 97.

96 IBM CICS Explorer

Figure 4-16 Status bar location

To open the Error Log view, click Window  Show View  Error Log, and information is displayed about the result of CICS operations and CICS Explorer state. Figure 4-17 shows the Error Log view.

Figure 4-17 Error Log View

4.5 Editors

Using the CICS Object Editor you can make modifications to objects in CICS. You can open most CICS objects in an editor from the CICS Object view by double-clicking or right-clicking and selecting Open.

When you open an editor for a CICS object, CICS Explorer attempts to retrieve the latest version of that object from the server before displaying it in an editor, which makes sure that no stale data is represented. If the latest version of an object cannot be retrieved (for example, a TASK object no longer exists since the Tasks view was last refreshed), CICS Explorer opens an editor on the cached data in read-only mode.

Figure 4-18 on page 98 shows the CICS Object Editor.

Chapter 4. CICS Explorer base familiarization 97

Figure 4-18 CICS Object Editor anatomy

The CICS Object Editor comprises one or more pages that provide different mechanisms for modifying the values of attributes on the target object. Changes are made to the state of the representation of the object in the Explorer. When you are happy with the changes, you can save the CICS object, which applies the changes to the object in CICS. The server sends feedback that pertains to the outcome of the attempted update: either the changes were applied successfully or there were problems performing the update. The CICS Object Editor reflects the outcome by displaying a message in the status bar and in the case of errors, where possible, updates the editor pages to indicate which attribute(s) caused

the problem.

If an editor has local changes that were not yet saved to the server, the editor is said to be in dirty state. This state is indicated by an asterisk at the start of the

98 IBM CICS Explorer editor title, as shown in Figure 4-19. The save action for an editor is only enabled when it is in a dirty state. When performing an update, the only attributes that the Explorer sends to CICS are those that were modified.

Figure 4-19 Editor in dirty state

All CICS objects can be manipulated using the attributes page.

Attributes page The attributes page, shown in Figure 4-21 on page 100, displays a categorized list of attributes that are available on a CICS object, and their values, similar to the Properties view. The attributes page differs from the Properties view in that it provides an interface for manipulating the values. Attributes with the name in black can be modified, whereas attributes with the name in gray cannot. The attributes page contains a button on the toolbar, shown in Figure 4-20, to toggle the display of non-editable attributes.

Figure 4-20 Toggle Show/Hide Non-mutable attributes icon

Click in the right column for a given attribute (or press Enter when the row has the focus) to modify the attribute’s value. The editor used is appropriate for the type of attribute that is being modified: Attributes that represent CVDA/EYUDA values are edited using a combo box, and everything else is edited using a text box. Press Enter or otherwise force the focus out of the cell to apply the entered value.

Textbox cell editors use information about the underlying attribute to perform validation on any input without having to send the information to CICS. The net effect of this is that you are notified of simple validation errors as you type, on a key stroke-by-key stroke basis. The error is reflected by highlighting the cell with the editor in, and displaying an error feedback message in the page title area, as shown in Figure 4-21 on page 100. Attempting to apply the value for the text editor at this stage reverts the attribute back to its initial value.

Chapter 4. CICS Explorer base familiarization 99

Figure 4-21 Attributes page validation feedback

Attributes that were modified since the last save are highlighted on the attributes page by setting the attribute name font to bold and prefixing it with a chevron, as shown in Figure 4-22.

Figure 4-22 Modified attribute highlighting

The list of attributes on an attributes page is filtered. Attributes that are not supported by the CICS region that the object originated from (for example, they were introduced in a newer release) are removed from the list.

Rich editor pages In addition to the attributes page, eight CICS objects have specific pages that are designed to allow interaction with the attributes on a higher level: DB2 Transaction Definition, Document Template Definition, File Definition, Pipeline

100 IBM CICS Explorer Definition, Process Type Definition, Program Definition, TD Queue Definition, Transaction Definition.

Figure 4-23 shows the File Definition Editor overview page.

Figure 4-23 File Definition Editor overview page

The rich editor pages are designed to make it easier for you to understand the effect of manipulating specific CICS attributes, which is achieved by mechanisms, such as providing descriptions of what the attribute is used for, where appropriate, grouping logically connected attributes, and providing user interface that guides you away from setting conflicting values.

The same key stroke validation that is on the attributes page is present in text boxes on rich editor pages.

Chapter 4. CICS Explorer base familiarization 101 The rich editor validation behavior differs from the attributes page in that the attribute value is not reverted when the text box loses focus; instead, the erroneous state is maintained until you correct it. The ability to save changes to a CICS object is suppressed while there are outstanding errors on any rich editor page. Figure 4-24 shows rich editor validation feedback. Click the error feedback message in the page title area to link back to the attribute that is responsible for the error. The link back reveals the appropriate page and gives the keyboard focus to the text box.

Figure 4-24 Rich editor validation feedback

Field-level help Both the attributes page and rich editor pages support showing help that is appropriate to the CICS attribute currently being edited. Press F1 on Windows or Ctrl + F1 on Linux to open the help that is associated with the current view within the Explorer. If you perform this key stroke within a CICS object editor when a specific attribute has the keyboard focus, the Explorer opens the help, if it is not already open, and displays help that is specific to that attribute.

Server error feedback

When you save from within a CICS object editor, the Explorer tells CICS to update the attributes that were modified. This operation can either succeed or fail in a variety of ways. All results are communicated through the status bar;

102 IBM CICS Explorer however, for some types of failure, the CICS object editor can display specific information about the failure.

The CICS Explorer performs basic validation on the values that are supplied for CICS attributes at a generic, low level, for example, the Explorer typically performs validation, such as string length or numeric range. For any attribute, CICS performs more specific validation, for instance the value might be required to be a valid HFS path or must adhere to some relationship with another attribute. Any of these types of validation failure result in an update failure after saving in the Explorer.

In cases like these, the CICS object editor highlights the attributes that are responsible for the failure in both rich editor pages and the attributes page and displays any error message in the page title area. Figure 4-25 shows the server error indication icon.

Figure 4-25 Server Error Indication icon

Figure 4-26 shows the rich editor page server error feedback.

Figure 4-26 Rich Editor Page Server Error feedback

Figure 4-27 on page 104 shows the attributes page server error feedback.

Chapter 4. CICS Explorer base familiarization 103

Figure 4-27 Attributes Page Server Error feedback

In this case, the error is caused by the Configuration File attribute not being a valid HFS path.

Server errors do not suppress the save action; therefore, the responsible attributes can be rectified. You can resave the object.

Update failures also result in a warning being appended to the error log with the full error returned from the server.

4.6 Creating new definitions

CICS Explorer provides a set of wizards for creating new resource definitions in CICS: To access the resource definition creation wizards, select Explorer  New Wizards, and either select from the subset provided or select Other to display the New dialog. Wizards for creating resource definitions are in the CICS SM Administration group. To open a new definition wizard from a CICS resource view, for the

104 IBM CICS Explorer type of CICS object being viewed, right-click anywhere on the table, and select New.

Figure 4-28 shows the new definition wizard page.

Figure 4-28 New definition wizard anatomy

The Data Repository is the location in which the definition will be created. This field is mandatory; however, if you start the wizard from the context menu in a resource definition view, it is populated with the context from that view. The value of the field must represent a valid repository and is validated by the Explorer against a list of valid repositories that are retrieved from the server. When the Data Repository field has the keyboard focus, press Ctrl + Space to activate content assist, which provides a list of all potential repositories for the definition.

In the Resource Group field, you can specify a group for the definition to be created in.

While all resource definitions require a name to be specified on creation, and optionally a description, many have additional attributes that are mandatory on creation. Controls representing these attributes are in the definition-specific input field area, such as the Data Set Name field, which we show on the pipeline definition creation wizard in Figure 4-28.

Chapter 4. CICS Explorer base familiarization 105 Definition creation wizards have a similar validation mechanism to the CICS object editor. Fields that fail validation are highlighted with an Error icon, as shown in Figure 4-29. A message that describes the failure is displayed in the notification area.

Figure 4-29 Validation in a definition creation wizard

When all mandatory fields are completed, and no validation errors exist, the Finish button becomes enabled. Click Finish to create the definition in the specified repository. If the create fails, an error message that is associated with the failure is displayed. Where a specific attribute is responsible for the failure, CICS Explorer also highlights that attribute in the creation wizard, as shown in Figure 4-30 on page 107.

106 IBM CICS Explorer

Figure 4-30 Creation server error

In Figure 4-30, the create failed because the Data Set Name is longer than the allowed 60 characters.

Select the Open Editor option to tell the Explorer to open a successfully created definition in a CICS object editor.

Chapter 4. CICS Explorer base familiarization 107

108 IBM CICS Explorer

Chapter 5. CICS Explorer navigation walkthrough

The intent of this chapter is to provide insight into CICS Explorer navigation. The hands-on approach provides a script that can be followed in real-life. Whether doing the actual walkthrough or just reading through the chapter, the result is a firm understanding of CICS Explorer navigation.

In this section, we discuss how to: Manipulate views, columns, filters, and perspectives. This discussion includes positioning the views and their components, positioning, adding, and deleting columns, filters, and perspectives, and also creating perspectives. Perform common operations functions against CICS resources. Perform common resource administration functions against traditional CSD and CICSPLex Business Application Services (BAS) resources.

5.2 Manipulating views

In this section, we discuss how to manipulate views.

5.2.1 Adding a view

To add a view: 1. Start CICS Explorer and connect using a CMCI connection. You can use the CICSPlex SM Data Interface connection, but CMCI is needed for other sections of the walkthrough. 2. Add the Programs view by going to the Operations Menu and clicking Programs, as shown in Figure 5-1 on page 111.

110 IBM CICS Explorer

Figure 5-1 Add a view selection

The Programs view is added, as shown in Figure 5-2.

Figure 5-2 Add a view result

Note: If you click the X (on the Programs view tab) the Programs view is removed.

Chapter 5. CICS Explorer navigation walkthrough 111 5.2.2 Zooming in and out of a view

To zoom in and out of a view:

1. To zoom in on the Programs view, double-click the Programs tab. Avoid the X. The Programs view now fills the entire window, as shown in Figure 5-3.

Figure 5-3 Zoom in

2. To zoom out, double-click the Programs view tab again. Avoid clicking the X.

5.2.3 Refreshing a view

To refresh a view, either click Refresh for the view, as shown in Figure 5-4 on

page 113, or press Enter.

112 IBM CICS Explorer

Figure 5-4 Refresh Icon locations

Refresh icons: The Refresh icon on the left refreshes the currently selected CICSplex Explorer view. The Refresh icon on the right refreshes the currently selected Programs view.

5.2.4 Resizing a view

To resize a view: 1. Position your cursor at the border of a view, as shown in Figure 5-5. When positioned correctly, your cursor becomes a vertical or horizontal double arrow.

Figure 5-5 Resize a view

Chapter 5. CICS Explorer navigation walkthrough 113 2. Click and drag to achieve the desired size.

5.2.5 Repositioning a view

To change the position of a view: 1. Click the View tab and drag it to the desired location. As you are dragging the view, your cursor will change to one of the following icons in Figure 5-6.

Cursor Where the View will be moved Position above the Current View (the View that is underneath the cursor) Position Below the Current View Position to the Right of the Current View Position to the Left of the Current View Stack: The View is stacked as a Tab in the Current View Restricted: Cannot be positioned in Current Area Open a New Window. Drag outside the workbench to position in a new window. Note: Click the New Window and drag back to position it back.

Figure 5-6 Cursor designations

2. Click the Programs tab, as shown in Figure 5-7 on page 115, and drag it to the right of the window. When your cursor becomes a right arrow, release it.

114 IBM CICS Explorer

Figure 5-7 Repositioning of the Programs view

The Programs view is now next to the Regions view.

Returning the Programs view: To put the Programs view back in its original position, click the Programs tab, and drag it to the center of the Regions view. When your cursor changes to a stack, release it.

5.3 Manipulating columns

In this section, we discuss how you can manipulate columns.

5.3.1 Customizing columns

To customize columns: 1. Select the Programs view. 2. Click the View menu, and select Customize Columns, as shown in Figure 5-8 on page 116.

Chapter 5. CICS Explorer navigation walkthrough 115

View Menu

Figure 5-8 View Menu location

The Customize Columns dialog box is displayed, as shown in Figure 5-9.

1 Available attributes – These are the 1 2 3 columns that you can ADD to the view Add/Remove – When either an Available 2 attribute or Current viewer column item has been selected, the Add or Remove button will become active. You can then Add/Remove the item.

3 Current viewer columns – These are the columns that are currently in use, and can be REMOVED. If an item is grayed out, as with Name, it is fixed and can NOT be removed. 4 Help Icon – For additional information.

5 Reset – Reset the columns to the default. 5 6 4 6 Close – Close the dialog box.

Figure 5-9 Customize Columns dialog box

3. Under the Available attributes select Change User ID, as shown in Figure 5-9. 4. Click Add. The Change User ID is added to the end of the Programs view columns. 5. Under Current viewer columns, select Share Status. 6. Click Remove. The Share Status is removed from the Programs view columns.

116 IBM CICS Explorer 7. Click Reset. The default columns, for the Programs view, are now restored, and the:

– Change User ID is no longer there – Share Status has been added back

8. Click Close to close the dialog box.

5.3.2 Repositioning columns

To change the order of the columns: 1. Click and drag the column to the desired location. 2. From the Programs view, click the Language column, and drag it between the Name and Status columns, as shown in Figure 5-10. The Language column is now positioned between the Name and Status columns.

Figure 5-10 Reposition Language column

5.3.3 Resizing columns

To resize a column: 1. Position your cursor at the border of the column. When your cursor turns into a horizontal double arrow, bisected by a vertical line, you can click and drag the column border to the desired width. 2. From the Programs view, position your cursor on the border of the Use Count column, as shown in Figure 5-11. 3. Click and drag the column border, expanding the column width.

Figure 5-11 Resize Use Count column

Chapter 5. CICS Explorer navigation walkthrough 117 5.3.4 Equalizing column widths

To make all of the columns the same width:

1. From the Programs view, click the View menu.

2. Select Equalize Column Widths. All the columns are now of equal width, including the Use Count column.

Figure 5-12 Equalize column widths

5.3.5 Resetting columns

Resetting the columns will restore all of the columns to the default location, size, and so on: 1. From the Programs view, click the View menu. 2. Select Reset columns. All the columns are back in their starting state, including the location of Language

5.4 Manipulating filters

In this section, we show you how to filter your information.

5.4.1 Using filters

Filters set the search criteria for the CICS resources that you want to display. To use the filters: 1. Click the Programs tab. 2. In the Name field, type DFH*, as shown in Figure 5-13 on page 119, and either press Enter or click Refresh. Now, only programs beginning with DFH* are displayed.

118 IBM CICS Explorer

Figure 5-13 Using a program name filter of DFH*

5.4.2 Customizing filters

To customize filters: 1. In the Programs view, click the View Menu, and select Choose filter attributes, as illustrated in Figure 5-14.

Figure 5-14 Choose filter attributes

Chapter 5. CICS Explorer navigation walkthrough 119 In Figure 5-14 on page 119, notice that:

– The Region is unavailable, indicating that it cannot be used as a filter for the Programs view. – Name has a check mark next to it, indicating that the Name filter is already

part of the view. – You can see a list of the other, currently available filters. 2. Click the available Language filter, and notice that: – The Language filter now has a check mark next to it. – The Language filter is next to the Name filter in the view. 3. Leave the Name filter set to DHF*, and set the Language filter to Cobol. Use the Language filter drop-down menu to set it. 4. Refresh the window. Use the Refresh icon, Enter, or the Apply filter icon, shown in Figure 5-15, to refresh.

Apply filter

Figure 5-15 Add Language filter

As a result, only COBOL programs that start with DFH* are displayed. 5. To remove an existing filter, go to the View Menu, click Filter Attributes, and deselect it.

5.5 Manipulating perspectives

If you log off of CICS Explorer, all of the settings (view additions/deletions, column settings, filters, and so on) that are in place at logoff time are preserved in your individual CICS Explorer workspace file. At logon time you return to the exact same display configuration.

Perspectives can be used to save a set of screen settings, so that you can manipulate your working screen settings, but still return to a desired screen configuration at any time. As with any customization, perspectives are saved to the your individual workspace file.

120 IBM CICS Explorer 5.5.1 Creating a perspective

To create a perspective:

1. Click the Programs tab, open the Window menu, and select Save Perspective as. 2. When prompted for a Name type CICS NavLab, and click OK, as illustrated in Figure 5-16.

Figure 5-16 Save Perspective As dialog box

5.5.2 Opening a perspective

The current perspective is highlighted in the shortcut bar. There are three ways that you can open a perspective: Access the Open Perspective screen by selecting the Window tab  Open Perspective  Other. Access the Open Perspective screen by clicking the Open Perspective Icon, and selecting Other.

Click the desired perspective button from the shortcut bar.

Chapter 5. CICS Explorer navigation walkthrough 121 The new CICS NavLab perspective might not show up on the shortcut bar until you toggle to the CICS SM (default) perspective, as shown in Figure 5-17.

Figure 5-17 Methods for opening a perspective

When you open the CICS SM (default) perspective, notice that the CICS SM (default) perspective is now in the state it was in prior to the walkthrough, for example, the Programs view is no longer there.

Reopen the CICS NavLab Perspective. All of the customization you applied during the walkthrough is still included in that perspective.

5.5.3 Resetting a perspective

You can reset a perspective, to its default settings by selecting the Window menu and choosing Reset Perspective. 1. From the CICS NavLab Perspective, select the Operations menu, and add the RPL List view. 2. Reset the CICS NavLab Perspective by selecting the Window menu and choosing Reset Perspective. The RPL List view is removed and all other customization (Programs view, filters, and so on) in place, at the time the CICS NavLab perspective was created, are still there.

122 IBM CICS Explorer 5.5.4 Deleting a perspective

To delete a perspective:

1. Make a copy of the CICS NavLab perspective

a. From the CICS NavLab perspective, select the Window menu and choose Save Perspective As. b. Enter a Name of “CICS NavLab2”. 2. Reopen the CICS NavLab perspective a. We are going to delete the new CICS NavLab2 perspective and it shouldn’t be active at the time of deletion. 3. Select the Window menu, and choose Preferences. 4. Expand Eclipse Platform. 5. Select Perspectives. 6. Select the CICS NavLab2 perspective. 7. Click Delete. 8. Click Yes to confirm deletion. 9. Click OK to close the Preferences dialog

Chapter 5. CICS Explorer navigation walkthrough 123

Figure 5-18 Delete perspective

5.6 Performing operations functions

You must be connected using a CMCI connection, and have security authorization to perform the following tasks.

5.6.1 Performing a program Newcopy

In this section, we work with resources that are associated with the IBM NACT sample application: 1. From the Programs view: a. Set your Name filter to DFH0CNA1. b. You can use a Language filter of COBOL or leave that field empty.

124 IBM CICS Explorer 2. Refresh your window.

3. Select all instances/region entries for the DFH0CNA1 program: a. Click the first entry. b. Hold down the Shift key, and click the last entry. c. To select individual entries, that are not next to each other i. Click the first entry. ii. Hold down the Ctrl key, and click each subsequent entry to select it. 4. With all desired instances selected, right-click, and select New Copy. 5. From the Perform Operation dialog window, click OK to confirm that you want to Newcopy all the entries, as shown in Figure 5-19.

Figure 5-19 Perform Operations dialog box

Individual Newcopy results: A green check mark appears next to each successful Newcopy. A red X appears next to each unsuccessful Newcopy. Associated error details

are provided.

Chapter 5. CICS Explorer navigation walkthrough 125 5.6.2 Altering CICS region MAXTASKS

To alter CICS region MAXTASKS:

1. Select the Regions view.

2. Double-click to select a desired Region. A window is displayed that details the Region Attributes. 3. Scroll down to the Transaction Activity attributes, and increase Maximum Tasks by 5. 4. Press Enter. As soon as you press Enter a “>” is displayed next to Maximum Tasks, which indicates that there is a pending change. 5. Click Save to make the change, as shown in Figure 5-20.

Figure 5-20 Change CICS region MAXTASKS

126 IBM CICS Explorer 5.7 Performing administration functions

In this section, we work with CICS resources that are contained in the CSD and resources housed in the CICSPlex Data Repository as part of the CICSPlex BAS component.

CICSPlex BAS (Business Application Services) is an alternative method for deploying CICS resources. Resources are housed in the CPSM Data Repository and installed through EXEC CICS CREATE commands.

CICS CSD CPSM BAS

CICS System CPSM WUI • JCL includes a reference to the CSD. • Commands available to initiate dynamic install of Resources. • Resources defined to the CSD can be installed at region startup or dynamically via CICS commands. EYUDREP CPSM CMAS • JCL includes a reference to the CPSM • Trandef Data Repository (EYUDREP). • Progdef CSD • At Region Startup CPSM looks for • Filedef definitions associated with the Region. • Transactions •etc. • Programs • Files CCICS System •etc. • ALL resource installs (startup or dynamic) are done in the form of EXEC CICS Create commands.

Figure 5-21 Resource Repository: CICS CSD versus CPSM BAS

Note: The Scope you choose determines where the resources are with which you are working: If scope equals the entire CICSplex you are working with BAS resources. If scope equals an individual CICS region, you are working with resources contained within that specific region CSD.

You must be connected using a CMCI connection and have security authorization.

Chapter 5. CICS Explorer navigation walkthrough 127 In this section, CICSPlex BAS resources are dynamically installed. To set up the install of BAS resources, at region startup time, additional BAS resources must be defined. See the CICS TS Manual for full details.

5.7.1 Viewing CSD resources

To view CSD resources: 1. Choose a scope that is equal to an individual region. 2. Add the Group List Definition view: a. Open the Administration menu, and select Group List Definitions. With the scope set to an individual region, the display shows CICS group lists in the region CSD (CSDLIST). 3. Add the Resource Group Definition view: a. Open the Administration menu, and select Resource Group Definitions. The display shows CICS groups in the individual region CSD (CSDGROUP) 4. Add the Program Definitions view: a. Open the Administration menu, and select Program Definitions. b. From the View menu, select Customize Columns. c. Select the CSDGroup attribute, and click Add, to add it to the Program Definitions view. d. Click Close to close the Customize Columns dialog.

Figure 5-22 on page 129 shows the CSD resources views.

128 IBM CICS Explorer Program Definitions view

View Menu  Customize Group List Resource Columns  Add Definitions Group CSDGroup view Definitions view

Figure 5-22 View CSD resources

5.7.2 Creating CSD resources

To create resources, use the CICS Explorer New Wizard: 1. There are a few methods for opening the New Wizard: – Click the down arrow for the New Wizard icon. – From the CICSplex Explorer view, select a scope, right-click, and select New. – Open a resource definition view (example: The Program Definitions view), right-click (in the view), and select New. – Open the Explorer menu, and select New Wizards, as shown in Figure 5-23 on page 130.

Chapter 5. CICS Explorer navigation walkthrough 129

Figure 5-23 New Wizards

2. Create a CSD Program definition in a New CSD Group: a. Confirm that your scope is still set to an individual region. b. Select Explorer  New Wizards  Program Definition. c. Set the values for the Program definition, as shown in Figure 5-24.

Data Repository and Region CSD will already be filled in, and specific to you

Figure 5-24 New Program Definition dialog box

d. Click Finish. 3. View the results, as shown in Figure 5-25 on page 131: a. Click X to close the Program Definition Overview. b. Set the Program Definitions view Name filter to NAV*.

130 IBM CICS Explorer c. Set the Resource Group Definitions view filter to NAV*. d. Refresh the views.

The NAVCSDPG Program Definition has been created in the New NAVCSDGP CSDGROUP

Figure 5-25 Program definition overview

Figure 5-26 on page 132 shows the display of new CSD program definition.

Chapter 5. CICS Explorer navigation walkthrough 131

The NAVCSDPG Program is not installed, but we can see it reflected along with its associated CSDGROUP

Figure 5-26 Display of new CSD program definition

5.7.3 Installing CSD resources

To install CSD resources: 1. Verify that you have the same single region scope selected that was used during the creation of the NAVCSDPG Program Definition. 2. From the Program Definitions view, right-click the NAVCSDPG Program Definition, click install, as shown in Figure 5-27 on page 133, and select the Single Region Target. Click OK.

132 IBM CICS Explorer

Figure 5-27 Perform CSD program definition install

3. From the Programs view: a. Set the Name filter to NAV*. b. Set the Language filter to NOTDEFINED. c. Refresh the view. You will see the NAVCSDPG Program installed in the single, target scope region

5.7.4 Creating BAS resources

In the event that there are no BAS resources currently defined, you can create new BAS resources, prior to viewing: 1. Set the scope to an appropriate CICSplex, rather than an individual region. 2. Create a New BAS resource group. Unlike the creation of CSD Resources, the BAS resource group must exist before resources can be added to it:

a. From the Resource Group Definitions view: i. Right-click inside the view, and select New. ii. Select Resource Group Definition.

Chapter 5. CICS Explorer navigation walkthrough 133 iii. Set the Create Resource Group Definition attributes to the those shown in Figure 5-28, and click Finish. The Resource Group Definition attributes view is displayed, confirming the creation of the new BAS Resource Group. NAVBASGP is displayed in the Resource Group Definitions view.

The Data Repository will already be filled in, and specific to you

Figure 5-28 Create Resource Group definition

3. Click X to close the Resource Group Definition (NAVBASGP) Attributes view. 4. Create the new BAS program definition in the new BAS NAVBASGP Resource Group: a. Select Explorer  New Wizards  Program Definition: i. Set the Data Repository to the CICSplex scope.

134 IBM CICS Explorer ii. Do not select the Region CSD option.

iii. Set Resource Group to NAVBASGP. iv. Set Name to NAVBASPG. v. Set Description to NavLab BAS Program Def. vi. Click Finish. b. Notice that: i. The Program Definition (NAVBASPG) Overview is displayed, confirming creation of the new BAS Program Definition. ii. When you select the Program Definitions view, the new NAVBASPG program definition will be displayed. 5. Click X to close the Program Definition (NAVBASPG) Overview.

5.7.5 Viewing the BAS resources

To view the BAS resources: 1. Confirm that you still have the appropriate CICSplex selected, as your scope. 2. Refresh your views, as shown in Figure 5-29.

The new BAS Program Definition The absence of a CSDGroup value, confirms that this is a BAS Program Definition

The new BAS Resource Group Definition

Figure 5-29 BAS program definition display

Chapter 5. CICS Explorer navigation walkthrough 135 5.7.6 Installing BAS resources

To install BAS resources:

1. Confirm that you still have the CICSplex set as your scope.

2. From the Program Definitions view, right-click the NAVBASPG Program Definition, and select Install. You are presented with a list of CICS Regions that are currently active in the CICSplex. 3. Select the appropriate Target(s), and click OK. 4. Select and refresh the Programs view. 5. Confirm that the Name filter is still set to NAV*. 6. Confirm that the Language filter is still set to NOTDEFINED. The NAVBASPG Program Definition is now installed in the Target(s) you selected.

5.8 Summary

You now have a solid working knowledge of CICS Explorer Navigation.

The walkthrough provided detailed information regarding: View manipulation View column manipulation View filter manipulation Perspective manipulation Performance of operations functions Performance of administration functions, against CSD and BAS Resources

136 IBM CICS Explorer

Chapter 6. CICS Explorer IA plug-in familiarization

The CICS Explorer IA plug-in provides a graphical user interface (GUI) to CICS IA that runs toolbar searches on common resources and helps you to build detailed queries to interrogate the Dependency and Affinity database objects. The CICS IA plug-in also provides a number of sample queries.

IBM CICS Interdependency Analyzer for z/OS V2.2 identifies resource interdependencies in your CICS systems, automates detection of your CICS runtime relationships, records data in a DB2 database, and helps you analyze the collected information for use in your daily processes.

Some benefits of CICS IA are: The resources that are identified by this runtime tool are those that are associated with transactions, programs, Basic Mapping Support maps, files, temporary storage queues, transient data (TD) queues, 3270 Bridge facility, web services, CorbaServer, and Enterprise JavaBeans (EJBs). Reports on DB2, IMS, and WebSphere MQ resources that CICS uses are also generated. A CICS IA plug-in is now available for the CICS Explorer to offer the same intuitive way to query CICS relationship data, manage queries, and navigate through complex application relationships, now from a standard interface. The CICS IA plug-in integrates with other CICS Explorer perspectives, for example, to click a transaction in a CICS PA bar chart and drill right-down to see its dependencies, relationships, affinities, and more. Sample queries assist you by highlighting those applications that are currently running in previous levels of CICS TS that are most sensitive to CICS API and SPI command changes. Version 2.2 includes support for modernizing your key CICS applications for deployment in a service-oriented architecture (SOA) by identifying applications that are suitable for exposure as web services, and it provides initial integration with WebSphere Studio Asset Analyzer. Support for CICS resources used by Software AG Natural gives you new insight into the behavior of your Natural applications.

138 IBM CICS Explorer 6.2 What CICS IA can do for you

There are many business reasons for using CICS IA and they vary by industry. Here are some of the business imperatives facing corporations today: Mergers and acquisitions Many banks are involved in mergers and acquisitions. The result is that they must consolidate workloads and move CICS applications around for isolation reasons or to spread the workload for performance reasons. Because these applications might not be well understood by the acquiring bank and documentation might be inadequate, there is a need to understand all of the resources that are associated with a given application. Outsourcing Large outsourcing companies are continually facing the problem of running CICS applications with which they are unfamiliar. Often, naming standards are lacking or conflict with other applications that are running on the same LPAR. Documentation might be nonexistent or incomplete. Again, there is a need for a tool to facilitate the understanding of the resource interdependencies and affinities that are involved. Maintenance or enhancement of applications During the normal application life cycle, CICS applications require maintenance and enhancement. When a programmer who is unfamiliar with the application that they are required to modify starts the modification process, much time can be spent trying to understand the application and the inherent flow of transactions. This learning curve can be greatly reduced using CICS IA, which identifies the resources that are affected directly and indirectly.

6.2.1 CICS IA highlights

Using CICS IA you can: Automate detection of runtime resource relationships Understand application flow with flexible resource-relationship reports Accumulate resource-relationship data in a DB2 database Build relationship maps to help improve the speed of application maintenance and to help reduce the time to resolve problems Compare applications and resources across regions Migrate, reuse, and extend CICS applications more quickly Support SOA implementations with deep application understanding

Chapter 6. CICS Explorer IA plug-in familiarization 139 Make informed decisions about the best way to split workloads

Minimize the impact of routine application maintenance for the user

6.2.2 The questions that CICS IA can answer

These are some of the questions that can be answered with CICS IA, and we offer them to give you a sense of what is possible with CICS IA: What region(s) does a particular CICS application run in? What are all of the CICS resources used by a given application? What are all of the CICS resources used by a given transaction? What transactions belong to a given application? What programs does a given transaction invoke? What transactions access a particular file and how? What resources are used by a specific program? How is a file accessed by a particular program? Which affinities does a transaction have? How do you query on DB2, MQ, or IMS resource use?

6.3 Description of CICS IA

IBM CICS Interdependency Analyzer for z/OS is the IBM discovery tool for CICS Transaction Server for z/OS, offering a wide range of new capabilities and supporting completely new functions in CICS Transaction Server, Version 3.2. New capabilities, such as threadsafe and affinity analysis, a new user interface, and support for Software AG Natural, make it possible to achieve better reuse, management, and control of your applications through improved understanding of an even wider range of CICS systems and resources. CICS Interdependency Analyzer facilitates projects, such as CICS version-to-version migration, affinity removal, and Web service refactoring that depend on deep knowledge of application, system, and resource relationships for their success.

CICS IA is a runtime and batch system for use with CICS Transaction Server for z/OS and CICS Transaction Server for OS/390®. It has two purposes: To identify CICS application resources and their interdependencies. This function enables you to understand the makeup of your application set, such as: – Which transactions use which programs – Which programs use which resources (files, maps, queues) – Which resources are no longer used – What applications does a CICS region contain

140 IBM CICS Explorer CICS IA captures interdependency information while CICS is running and stores it in VSAM files. Detailed reports can be produced from the VSAM files, if desired. Subsequently, the VSAM files load the DB2 database.

To analyze transaction affinities

Affinities require particular groups of transactions to be run either in the same CICS region or in a particular region. Affinities information is useful in a dynamic routing environment because you must know of any restrictions that prevent particular transactions from being routed to particular application-owning regions (AORs) or that require particular transactions to be routed to particular AORs. CICS IA captures and loads the Affinity data into its DB2 databases. The data can then be queried with the CICS IA plug-in, the CICS IA online transaction CINQ, with batch SQL queries, or with other SQL query software tools. Through batch SQL processing, detailed reports can be produced.

Many large organizations have used CICS since the early 1970s, their systems growing and evolving with the business. During this time, many techniques of implementing applications were used—as a result of new function, changing corporate standards, technical requirements, and business pressures.

Frequently, this growth was not as structured as it might have been with the result that many applications and services share common resources and changes in one area typically affect many other areas. This issue can reach such a level that the system can no longer develop in a controlled manner without a full understanding of these interrelationships. CICS IA can help you achieve this understanding, for example, if you need to change the content or structure of a file, you must know which programs use this file because they must be changed too. CICS IA can tell you this information and the transactions that drive the programs. CICS IA records the interdependencies between resources (such as files, programs, and transactions) by monitoring programming commands that operate on resources.

The application that issues such a command has a dependency on the resource that is named in the command, for example, if an application program issues the command EXEC CICS WRITE FILE (myfile), it has a dependency on the file called myfile. It might have similar dependencies on transient data queues, temporary storage queues, transactions, other programs, and so on.

The commands that are monitored are typically CICS application programming interface (API) and system programming interface (SPI) commands that operate

Chapter 6. CICS Explorer IA plug-in familiarization 141 on CICS resources; however, you can also instruct CICS IA to monitor some types of non-CICS command that operate on non-CICS resources; for example:

MQ calls to WebSphere MQ resources EXEC DLI calls to IMS database resources DB2 calls Dynamic COBOL calls to other programs

Potentially, the inclusion of any non-CICS resources gives you a fuller picture of the resources that a transaction uses.

The Collector component of CICS IA collects the dependencies that apply to a single CICS region, that is, a single application-owning region (AOR) or a single, combined routing region-AOR. It can be run against production CICS regions and is also useful in a test environment to monitor possible dependencies that new or changed application suites or packages introduce.

From the interactive interface of CICS IA you can control Collectors running on multiple regions.

CICS IA with your entire workload: To ensure that you monitor as many potential dependencies as possible, use CICS IA with all parts of your workload, including rarely-used transactions and abnormal situations. CICS IA collects these dependencies into a database. You can store the dependency information from several CICS regions into the same database. You can review the collected dependencies using the CICS IA Query interface, or list them using the Reporter.

142 IBM CICS Explorer 6.4 CICS IA plug-in overview

Figure 6-1 shows all of the views that are available in the new CICS IA plug-in.

List of all Regions Breakdown of resources used

Results of queries

Saved query definitions

Where Call tree of List of all resource program Transactions is used execution

List of all Programs

Figure 6-1 Views of CICS IA plug-in

6.5 Toolbar searches and queries

The CICS IA plug-in has two methods of interrogating data that the CICS IA Collector collects: toolbar searches and queries.

6.5.1 Toolbar searches

The CICS IA plug-in has four toolbars that you can use to search for common resources, programs, transactions, and regions, which you can see in Figure 6-2 on page 144. Toolbar searching is a quick way of interrogating a limited amount of data because the resources that you can interrogate are fixed by the menu options.

You can search by name and region only, or you can use the Regions toolbar to search by regions only; however you can restrict or expand the search criteria by

Chapter 6. CICS Explorer IA plug-in familiarization 143 using the wildcard. The structure of the results that are displayed in the Resources window is also fixed. The description of the toolbar search that you run is shown above the results in the Resources window. You cannot save the results of a toolbar search. Figure 6-2 shows the toolbar search.

Figure 6-2 Toolbar search

6.5.2 Queries

The CICS IA plug-in provides you with a number of defined queries, which you can edit, and helps you to build detailed queries of your own. When you create a query, you can define the structure of the results that are displayed in the Resources window. The structure is not fixed. You can query any resources in any combination. You can also add filters to the query to further refine the results. The description of the query that you run is shown above the results in the Resources window. You can save queries that you edit or create.

When you run a query, you can save the search results in a list under the query name in the Queries window for future reference. You can copy the definition of a

144 IBM CICS Explorer query to the clipboard and paste it into the same folder, or a different folder, in the Query window. If you want to run your own SQL, you can paste the query definition into a text editor to view the raw SQL strings that run against the DB2 tables. Figure 6-3 shows the CICS IA plug-in main window.

Figure 6-3 Main CICS IA plug-in menu

The Explorer has an implicit wildcard (*) that is added to the end of all search values. The wildcard is not visible, for example, when you search using the toolbar or define queries; instead, if you type FIN as a value, it is read as FIN*. The wildcard is denoted by the *. In this way, the search is for all resources that begin with FIN.

If you require an explicit wildcard, you can add it anywhere in the search definition; however, the implicit wildcard at the end of the search value remains, for example: To search for resources that begin with FIN and include 01, enter FIN*01.

To search for resources that contain 01, enter *01. To narrow your search as much as you want, you can use as many wild cards as required, for example, A*0*3* is also acceptable.

Chapter 6. CICS Explorer IA plug-in familiarization 145 The implicit wildcard is nearly always added to the end of the search value, for example, searching for PROG*AF can return:

PROGAAAF PROGAAFA PROGAFAA

Note: A wildcard is not always added. If it is a transaction, and we enter FINA, we do not add an *.

Use the toolbar at the top of the CICS IA plug-in to search for common resources. You can search by name and region only. You can restrict or expand the search using the wildcard.

To run a toolbar search for common resources: 1. Use the menu in the Find field to select a resource to search. 2. Use the ID field to limit the search to a particular ID, or you can leave the field blank. 3. Use the Region field to limit the search to a particular region or regions. 4. To run the search, click Search  Run, click the green toolbar button, or press Enter. The result of the search is shown in the Resources window.

6.6 Programs and Transactions windows

When you first open the CICS IA plug-in and connect to the database the information in the Programs window and Transactions window is retrieved from the data that is extracted to the database by the CICS IA Collector. The information is displayed in an alphabetic list and is static.

You can use the toolbar search, which is located at the top of the Queries and Regions window, to explore the programs and transactions. Figure 6-4 on page 147 shows an example of the Programs and Transactions window.

The information in the Programs window is a list of all of the programs that are known to CICS IA, which are: Programs that are the sources of interactions Programs that are the results of interactions

Programs that are CICS resource types

146 IBM CICS Explorer The information in the Transactions window is a list of all of the transactions that are known to IA, which are:

Transactions in which programs are running Transactions that are the results of interactions Transactions that are CICS resources of TRANSID type

Figure 6-4 Programs and Transactions window

6.6.1 Searching programs and transactions

You can search the programs that are listed in the Programs window. The data is stored in the database by the CICS IA Collector and is retrieved when you first open the CICS IA plug-in and connect to the database.

To search the programs list for particular programs that you want to analyze further: 1. Click the Programs tab to bring the Programs window to the front. 2. To filter the search, in the left field, enter the name of the search criteria, and in the Region field, enter the region search criteria. An implicit wildcard is appended to the end of the search criteria, and you can add wild cards at the beginning and in the middle. You can search by name only, region only, or name and region. 3. Press Enter, or click Search  Run to run the search. The results are displayed in the Programs window.

Transactions: This is the same process for transactions except that you search transactions in the Transactions window.

Chapter 6. CICS Explorer IA plug-in familiarization 147 6.7 Regions window

When you run a toolbar search or a query, the Regions window displays all of the regions for which the CICS IA Collector stored data in the database. The results are displayed in an alphabetic list. You have only one search field, which is for the region name. Figure 6-5 shows an example of this window.

Figure 6-5 Regions window

You can search the regions list for particular transactions that you want to analyze further. To search in the Regions window: 1. Click the Regions tab to bring the Regions window to the front. 2. To filter the search, in the search field, enter the region name search criteria. An implicit wildcard is appended to the end of the search criteria, and you can add wildcards at the beginning and in the middle. 3. Press Enter or click Search  Run to run the search. The results are displayed in the Transactions window.

4. Right-click the name of the region you want to analyze. 5. From the menu, select the resource that you want to search.

148 IBM CICS Explorer 6.8 Properties window

The Properties window gives you details about programs, transactions, files, TD queues, TS queues, and exits, as shown in Figure 6-6 and Figure 6-7 on page 150.

Figure 6-6 Properties window

Chapter 6. CICS Explorer IA plug-in familiarization 149

Figure 6-7 Properties window Part 2

6.9 Supplied queries with CICS IA plug-in

There are a number of predefined queries that are supplied with the CICS IA plug-in for each resource. You can edit the queries to suit your requirements. Figure 6-8 on page 151 and Figure 6-9 on page 152 show examples of the window that you see with the queries all expanded.

150 IBM CICS Explorer

Figure 6-8 CICS supplied queries

Chapter 6. CICS Explorer IA plug-in familiarization 151

Figure 6-9 DB2 IMS and MQ supplied queries

To run a predefined query in the Queries window: 1. In the Queries window, select the resource that you want to query, as shown in Figure 6-10 on page 153. 2. To view the query names, click the plus sign to expand the list of queries, as shown in Figure 6-11 on page 154. 3. To run the query, right-click the query name, and click Run, or click the query you want to run, and click Search  Run. The results are displayed in the Resources window.You can save the results for future reference and further analyze the results. Figure 6-12 on page 155 is an example of you clicking Run, and Figure 6-13 on page 155 shows the results.

Next, we show a step-by-step example of running the supplied query: all transactions by region. Figure 6-10 on page 153 shows the selected CICS queries.

152 IBM CICS Explorer

Figure 6-10 CICS query selected

Next, we look at general queries underneath the CICS heading. Figure 6-11 on page 154 shows the general queries expanded.

Chapter 6. CICS Explorer IA plug-in familiarization 153

Figure 6-11 General queries expanded

Click Run to execute the query, as shown in Figure 6-12 on page 155.

154 IBM CICS Explorer

Figure 6-12 Click run to execute

Figure 6-13 shows results of the all transactions by region query.

Figure 6-13 All transactions by region results

Chapter 6. CICS Explorer IA plug-in familiarization 155 6.10 Creating your own queries in the CICS IA plug-in

To create a query:

1. Click Explorer  New, or right-click in the Queries window, and select New, as shown in Figure 6-14. If you want to save the query, right-click the folder name under which you want the query to be listed.

Figure 6-14 Create new query

2. From the menu, select the resource type that you want to query. We selected CICS, as shown in Figure 6-15 on page 157.

156 IBM CICS Explorer

Figure 6-15 Create CICS query

3. In the Create Query window, go to the Name field, and enter a query name. We called ours test1. 4. In the Show panel, click the green plus sign button to select the resource or resources that you want to query, as shown in Figure 6-16 on page 158.

Chapter 6. CICS Explorer IA plug-in familiarization 157

Figure 6-16 Query resource selection

5. Click the red X button to remove resources. 6. Click the yellow arrows to move the selected resources up and down the tree so that the query results are presented in the required order. The resources tree that is created from your selections is in the format in which the results are displayed in the Resources View when you run the query.

6.10.1 Adding filters to the query

When you create a query, you can further refine your query by editing the right pane in the Create Query window. When you select an expression, the right pane changes allow you to further define your query: 1. Select is or is not for the values in the query. If the expression that you selected has a known set of values, for example, Resource Type, the values are listed. These properties are added to the left pane so that you can view the query string for each line easily. If you need both is and is not values to be included in the query for the same resource, you require two lines for the same resource because you cannot combine is and is not values.

158 IBM CICS Explorer 2. Define the expressions you selected by arbitrary values, for example, Resource Name. Use the editable table to define the values. These properties are added to the left pane so that you can easily view the query string for each line. An implicit wildcard is appended to the end of the value, and you can add wildcards at the beginning and in the middle. To our test1 query, we selected resources as being transactions. We then further filtered this down to being a particular transaction. So for the filter, we select Transaction. We then select transaction is EMS1, as shown in Figure 6-17.

Figure 6-17 Filter query

When we run this query, we get the results shown in Figure 6-18.

Figure 6-18 Results of Test1

Chapter 6. CICS Explorer IA plug-in familiarization 159 6.10.2 Modifying an existing query

You can modify existing queries whether they are supplied predefined queries or

queries that you created.

To modify an existing query: 1. Right-click the query that you want to edit, and click Edit, or click the query that you want to edit, and click Edit  Edit Query. The Edit Query window is displayed, as shown in Figure 6-19.

Figure 6-19 Edit query

2. Edit any aspect of the query that you want. To save the edited query as a new query, change the name. Figure 6-20 on page 161 shows the Edit CICS query window.

160 IBM CICS Explorer

Figure 6-20 Edit CICS query window

3. Click OK to save the query. The query is saved in the same folder that the original query is saved.

6.10.3 Saving your queries in folders

When you create and define your queries, you can save them in the Queries window for future use.

To save your queries: 1. Before you create a query, in the Queries window, click the folder name under which you want the query to be listed. You cannot move a query after it is saved. 2. After you name and define your query, click OK, and the query is saved in the query folder that you selected. 3. To delete a query, in the Queries window, right-click the query name, and click Delete.

Chapter 6. CICS Explorer IA plug-in familiarization 161 6.10.4 Creating a query folder

You can save queries and query results in the existing folders or create a new

folder.

You can create folders under any of the existing folders as a subfolder. To create a folder: 1. In the Queries window, click the position where you want the folder to be created, and select File  New  New Folder, or right-click, and select New  New Folder, as shown in Figure 6-21. A folder called New Folder is created in the Queries window.

Figure 6-21 Create new folder

2. Change the name New Folder to the required folder name. 3. To delete a query folder, in the Queries window, right-click the query folder name, and click Delete. You cannot move an existing folder in the structure.

6.11 Analyzing query and search results

You can further analyze the results of any query or search that are displayed in the CICS IA plug-in windows. You can view the programs and transactions that are used as a resource and the region in which they are using that resource. You

162 IBM CICS Explorer have the option to analyze the resource in the region in which it is being used. You can analyze the use of each resource across all regions or specific regions.

To further analyze any query or search results: 1. Right-click any resource that is displayed in any window in the CICS IA plug-in. 2. Click Used By or Uses Resources, as shown in Figure 6-22. Only programs and transactions have the Uses Resources option.

Figure 6-22 Used By and Uses Resources options

3. Click All Regions or a specific region that is shown in the menu: – The results for the Used By option are displayed in the Used By window. – The results for the Uses Resources option are displayed in the Uses windows. 4. Repeat steps 1 to 3 to further analyze the results in the Used By and the Uses windows. If you select a resource in the Uses window, the lower panel in the Uses window shows the names of the programs that are using that resource. You can navigate the program tree that is displayed in the lower panel by using the yellow up and down arrows, which move between each resource in order. 5. To recall previous search results in your current CICS IA plug-in session, use the yellow back and forward arrows. The resource currently being analyzed is displayed at the top of the window, as shown in Figure 6-23 on page 164.

Chapter 6. CICS Explorer IA plug-in familiarization 163

Figure 6-23 After clicking Used By

6.12 Comparing query and search results

When you have a number of query or toolbar search results, you might want to compare two or more results. You can select any number of results in the history using the Compare search results window. You can also compare saved query results.

The Compare search results window relies on complete searches being of the same structure. For large amounts of data, it is more efficient to create a query. You can compare query and search results using the Compare search results window, which is shown in Figure 6-24 on page 165: 1. Click the compare torch icon to open the Compare search results window, shown in Figure 6-24 on page 165. Both panels contain a list of all query results. Select the results in the left panel to Show resources in those results and compare with the results that you select in the right panel to show resources that are not in those results.

164 IBM CICS Explorer

Figure 6-24 Compare search results

If you want to compare saved query results, you must view the saved query results in the Resources window so that the Compare window can include the saved query results in your selection of choices. 2. Click the boxes next to the results that you want to compare. 3. Click OK. The Resources window displays the results. The comparison that was run is identified in the grey section of the Resources window. If there are no results, the comparison information is shown but the results window is empty. 4. Optional step: To clear the history of query results from the Compare search results dialog box, click the down arrow next to the torch icon to display the menu items. Click Clear History.

Chapter 6. CICS Explorer IA plug-in familiarization 165

166 IBM CICS Explorer

Chapter 7. CICS Explorer CM plug-in familiarization

In this chapter, we discuss the CICS Explorer CM plug-in.

CICS Configuration Manager (CM) provides a single point-of-control for editing, reporting, and migrating CICS resource definitions across an enterprise. CICS CM is a CICS application that can read from and write to a CICS system definition (CSD) file and CICSPlex SM contexts.

The CICS CM plug-in provides an Eclipse-based infrastructure to view and manage CICS CM resource definitions across an enterprise. It supports a subset of the function that is available in CICS CM.

CICS CM introduces the concept of a configuration that can be backed by either a CSD file or a CICSPlex SM context, which means that the question of how a resource is stored is removed from you because CICS CM provides a single experience regardless of whether you are dealing with a CSD or a CICSPlex SM context.

Configurations contain lists, which contain groups, which contain resources. Using CICS CM you can manage these resources using create, read, update, and delete operations.

Using the powerful search facility that CICS CM provides you can search for resources with common criteria across one or many configurations.

CICS CM records operations on resources and journals. This information is then available as part of the history of a resource and is also searchable on a configuration and a group level.

CICS CM also provides some clean up operations to identify potentially redundant resources and those resources that cannot be properly used.

7.1.1 Setting up the CICS CM plug-in

When you install the CICS CM plug-in, you must define a connection to CICS CM: 1. Open the preference page, and select the Connections option. 2. In the connections pane, select the CICS Configuration Manager option from the Type pull-down list, as shown in Figure 7-1 on page 169.

168 IBM CICS Explorer

Figure 7-1 Connections pane

When you start using your CICS CM Connection, all of your administration of CICS definitional resources occurs through CM and as a result is recorded in the journal.

You might also want to manage operational resources, which you can do by associating a CMCI or a WUI server connection with your CICS CM Connection, as shown in Figure 7-2 on page 170.

Chapter 7. CICS Explorer CM plug-in familiarization 169

Figure 7-2 Manage operational resources

Now you can view operational resources from your region/WUI and definitional resources from CM. You can also install CICSPlex SM Context resources to be installed, added, and removed from groups.

7.2 CM perspective overview

Installing CICS CM, Figure 7-3 on page 171, provides a new perspective to the CICS Explorer workspace.

170 IBM CICS Explorer

Figure 7-3 CICS CM perspective

Within this configuration there are views for configurations, lists, groups, History, Search, and some SM Administration views.

You can customize this perspective like you can with any other plug-in. Your changes are saved when you exit the Explorer.

You might want to open or close any of the views. You can find a particular view through the Operations, Administration, or Window  show view routes.

Chapter 7. CICS Explorer CM plug-in familiarization 171 7.3 Configurations view

The Configurations view displays all CICS CM Configurations: both those representing CSDs and those representing CICSPlex SM Contexts. Figure 7-4 shows configurations.

Figure 7-4 Configurations

The configuration information is retrieved from the server when you connect to CICS CM and is displayed in an alphabetic table by configuration name. The table also contains details of the CSD or Context that the configuration represents.

The different types of configuration are denoted by several icons.

You can filter the table of configurations by configuration name using the filter box at the top of the view. This box includes an implicit wildcard, so, for example, searches for C returns all configurations with a name beginning with C. You can also use the asterisk (*) to match any number of wildcard characters and the plus sign (+) to match exactly one wildcard character. You must press Enter to apply your filter.

You can refresh the configurations view using the Refresh button, which forces the view to retrieve the information from the server again.

Select a configuration in the table to populate the Lists and Groups Views and also display information about the selected configuration in the Properties View. If you select more than one configuration, only the selection that is closest to the top of the table is used to populate these views.

172 IBM CICS Explorer Select and right-click one or more configurations to display a context menu with several options for searching and clean up operations. We discuss this further in later sections.

7.4 Lists view

The Lists View, Figure 7-5, displays all lists in the currently selected configuration. The configuration information is displayed alphabetically, in the text in the top of the view.

Figure 7-5 Lists view

For a configuration that represents a CSD, lists represent the Group Lists in the configuration.

For a configuration that represents a CICSPlex SM Context, lists represent the ResDescs in the configuration.

You can prevent the lists view from changing its content by turning the Link to Selection option off. As a result, the view will no longer change contents when you select a configuration. You can turn this functionality back on by turning the Link to Selection option back on, as shown in Figure 7-6 on page 174.

Chapter 7. CICS Explorer CM plug-in familiarization 173

Figure 7-6 Lists view

You can filter the lists by name using the filter box at the top of the view. This box includes an implicit wildcard, for example, a search for C returns all lists with a name that begins with C. You can also use the asterisk (*) to match any number of wildcard characters and the plus sign (+) to match exactly one wildcard character. You must press Enter to apply your filter.

You can refresh the Lists View using the Refresh button, which forces the view to retrieve the information from the server again.

Selecting a List populates the Groups View and also displays information about the selected list in the Properties View.

7.5 Groups view

The Groups view, Figure 7-7 on page 175, displays all Groups in either the currently selected configuration or the currently selected list. The last selection of either of these types is used to populate the view. This information is displayed in an alphabetic list. The information about where the view is being populated from is in text at the top of the view.

174 IBM CICS Explorer

Figure 7-7 Groups view

For a configuration that represents a CSD, groups represent the csdgroups.

For a configuration that represents a CICSPlex SM Context, groups represent the ResGroups.

You can prevent the lists view from changing its content by toggling the Link to Selection button to the off position. The view will no longer change its contents when you select a configuration. You can easily turn this functionality back on by toggling the Link to Selection button to the on position.

You can filter the Lists by name using the filter box at the top of the view. This box includes an implicit wildcard, for example, a search for C returns all lists with a name beginning with C. You can also use the asterisk (*) to match any number of wildcard characters and the plus sign (+) to match exactly one wildcard character. You must press Enter to apply your filter.

Chapter 7. CICS Explorer CM plug-in familiarization 175 You can refresh the groups view using the Refresh button, which forces the view to retrieve the information from the server again.

Selecting a group in the list populates any open definitional views with the resource definitions that are contained in the selected group.

Selecting a group also displays information about the selected group in the Properties View. If you select more than one group, only the selection that is closest to the top of the list is used to populate these views.

Selecting and right-clicking one or more groups displays a context menu with several options for searching and creating new definitions. See later sections for more information.

7.6 Definitional views

By default, in the CM Perspective, shown in Figure 7-8, the following definitional views are already open: Transaction Definitions, Program Definitions, File Definitions, and TD Queue Definitions. You can customize the perspective in any way that you want, including closing these views and opening others. Other definitional views can be found through the Administration menu.

Figure 7-8 CM Perspective

CICS CM populates these views when a group is selected and all resources for the group are retrieved from the server.

You can manipulate these views by changing the order of columns, configuring which columns to display, and applying various filters.

More detailed information about how to manipulate views is in Chapter 1, “CICS Explorer introduction” on page 3.

176 IBM CICS Explorer 7.7 Creating, editing, and deleting a resource definition

In this section, we discuss how to create, edit, and delete a resource definition.

7.7.1 Creating resources

CICS CM uses the Creation Wizards that are provided in the Base CICS Explorer to enable creation of resources. There are a number of different routes that you can take to create a resource definition.

To create a resource definition: 1. From a Group, in the context menu, select New. 2. From the list, select a specific type or Other, which displays more resource types. Select one of these resource types to create a definition of that type. Figure 7-9 shows the creation of a bundle definition.

Figure 7-9 Resource creation

Chapter 7. CICS Explorer CM plug-in familiarization 177 3. From a definitional view, locate the context menu, and select New. The creation wizard for that type is displayed. Figure 7-10 is an example of creating a TD Queue.

Figure 7-10 New TD queue

Each type of resource definition displays a different creation wizard because each type has different basic attributes that must be entered. For details about the creation wizards, see Chapter 1, “CICS Explorer introduction” on page 3.

When a definition is created it is then displayed in an editor where further editing can occur.

7.7.2 Editing a resource

You can use CICS CM to edit your resource definitions in configurations that are backed by both CSDs and CICSPlex SM Contexts.

178 IBM CICS Explorer Editors CICS CM uses the editors that are provided in the Base CICS Explorer to display resource definitions, as shown in Figure 7-11. The same framework is used to display and edit resource definitions; however, any changes that you make go through the CM server, which ensures that journaling takes place.

Figure 7-11 Transaction definition

To open editors on a particular resource definition select the Open option from the context menu or double-click the resource. The Editors provide some attribute validation, undo capabilities, and context help. Refer to Chapter 1, “CICS Explorer introduction” on page 3 for further information about the Editors and how to get the most out of them.

7.7.3 Deleting a resource

To delete a resource definition, select the resource, and from the context menu, click Delete.

Chapter 7. CICS Explorer CM plug-in familiarization 179 7.7.4 Installing a resource

It is possible to install resources from a CICSPlex SM Configuration into one or

more active CICS systems, if you also defined an operational connection to work alongside the CICS CM connection.

If the operational connection is defined, the Install option is enabled in the context menu for these resources. See 3.1, “Installing CICS Explorer” on page 46 for instructions about installing the CICS Explorer.

7.8 Adding and removing from groups

You can add and remove resources from groups within a CICSPlex SM Configuration, if you also defined an operational connection to work alongside the CICS CM connection.

If the operational connection is defined, the Add to Group option is enabled in the context menu for these resources. The Remove from Group option is only enabled if the resource definition already belongs to a group.

See section Chapter 4, “CICS Explorer base familiarization” on page 77 for details about adding and removing from groups.

7.9 History

In this section, we discuss History. You can review what changed.

7.9.1 CICS CM journal

In its journal, CICS CM records information about changes that are made to definitions. To keep track of these changes, you must make the changes using CICS CM. If you bypass CICS CM using CEDA, the CICSPlex SM WUI, or a CMCI Explorer connection, your changes are not recorded in the journal.

If you use the CICS CM plug-in within the CICS Explorer to make changes to definitions through a connection to CICS CM, these changes are recorded in the journal. This connection can still be used in conjunction with a CMCI or a CICSPlex SM Data Interface connection for operational resources.

180 IBM CICS Explorer 7.9.2 History View

The History View displays changes that are made to definitions, as shown in

Figure 7-12. This view is populated by the current selected definition, group, or configuration.

When a resource definition is selected the History View displays all changes for that definition, within the scope of the group that the definition is in.

Figure 7-12 History view

When a group or a configuration is selected the History View displays all changes within that group or configuration for the last three months. This is a default value that you can alter through the Date Range dialog.

You can prevent the lists view from changing its content by toggling the Link to Selection button to the off position. The view will no longer change its contents when you select a configuration. You can turn this functionality back on by toggling the Link to Selection button to the on position.

The History View displays information in a table. Each entry in the table represents a change made. Maximizing an entry shows the details of which attributes were changed: their before and after values. Table 7-1 on page 182 provides details about the History View.

Chapter 7. CICS Explorer CM plug-in familiarization 181 Table 7-1 History view

Field Description

Revision Time Shows the date and time of changes made to the resource definition. You can click a date entry in

this column to display the change properties in the Properties View.

Resource When the row is collapsed the only the resource Name/After name is displayed. If you click the plus sign to expand the row, the value of the resource attributes after the change is displayed.

Resource When the row is collapsed the resource type only Type/Before is displayed. If you click the plus sign to expand the row, the value of the resource attributes before the change is displayed.

Group Shows the group name.

User Name Shows the user who made the change and the change that was made to the data.

Command Shows the command that was used to make the change, for example, Rename, Update, Delete.

Change Shows the change package that was used to make Package the change.

Scheme Shows each entry in the journal for the selected objects.

The data in the table is initially arranged by Revision Time; however, clicking any of the column headers sorts the data by that column.

Use the Group By Date toolbar button to turn on and off showing the entries group into date categories: Today, This week, Older than this week, Older than this month, Older than this year, as shown in Figure 7-13 on page 183.

182 IBM CICS Explorer

Figure 7-13 Group by date

You can filter the entries in the History View by selecting one or more filters from the view menu. The available filters are: Name Type Group User ID Command Change Package ID Scheme

Selecting one of these filters creates an input field in the History View. You can then enter in a filter value, select is, is not, equals, or apply. Figure 7-14 shows the filters.

Figure 7-14 Filters

Chapter 7. CICS Explorer CM plug-in familiarization 183 The History View might contain many entries. If you know that you are only interested in entries within a specific set of dates, you can filter the view by date range. You can change the date range through the Set Date Range dialog, which is also available from the View menu, as shown in Figure 7-15.

Figure 7-15 Set Date Range

You can restore some changes in the History View, and this options is displayed in the context menu of an entry in the History View. The resource definition is restored to the values before the change that you selected, as shown in the Resource Type/Before column.

If you restore an entry that was deleted, the resource definition is recreated. If you restore a create entry, the resource definition values are restored to the values when the resource definition was first created.

The restore option is not currently available for rename, add, or remove entries.

You can open a particular entry in the table in an editor, which displays the after attributes of the entry in the editor for the particular type and is in read-only mode.

To search for the current version of a resource definition, select an entry in the History View, and then select the Find Current Version.

184 IBM CICS Explorer Use the Refresh button to refresh the History View, which forces the view to retrieve the information from the server again.

7.10 Searches and the search view

CICS CM provides a number of different ways to search for resource definitions.

CICS CM provides some specific searches and a completely customizable search through the search dialog. Search results are displayed in the Search Results View.

Searches can be run against one or more groups within a particular configuration. They can also be run against one or more configurations in the current CM connection.

7.10.1 Specific searches

For any group or configuration you can run the Show All Resources search, which you can also run on more than one group or configuration. Simply select one or more of either groups or configurations, and select Show All Resources.

On any resource definition certain specific search options are displayed under the Find context menu. All resource types have an option to search for Similar resources. This feature searches for all resource definitions that have the same name and type as the resource definition that is selected, within in the same configuration.

Program Definitions have an additional specific search option. You can search for transactions that reference the selected Program.

LSR Pool Definitions have an additional option. You can search for files that reference the selected LSR Pool.

7.10.2 Using the search dialog

Using the search dialog you can perform more powerful searches to be run with filter criteria.

The search dialog is available from the Search icon in the toolbar or from the context menu when you select a configuration or a group.

Figure 7-16 on page 186 shows the Search Definitions.

Chapter 7. CICS Explorer CM plug-in familiarization 185

Figure 7-16 Search Definitions

You can filter by resource name and resource type. You can also select which configurations you want to search and (if appropriate) which groups to search within a configuration.

You must enter a resource name; however, you can use wildcards (*) to match any name or any number of characters within a string and (+) to match exactly one character.

Further filtering is enabled only when you select a specific resource type, as shown in Figure 7-17 on page 187. After which you can select filters from the filter pull-down menu, which allows filtering on every attribute for this type. After you select a filter, you must enter a value and where appropriate choose operators. Filters are joined together in an and clause.

186 IBM CICS Explorer

Figure 7-17 Additional filtering

Configurations might be pre-populated if you selected them when the search dialog was opened. You can add or remove Configurations from the search scope by editing the list that displays when you click the Choose button in the Configurations area.

Chapter 7. CICS Explorer CM plug-in familiarization 187

Figure 7-18 Configurations area

Groups might also be pre-populated if any were selected when the search dialog was opened. You can add or remove any groups from the search scope by editing the list that is displayed when you click the Choose button in the Groups area. You can only specify groups within the same configuration. If a group is specified, you can only select one configuration. If more than one configuration is chosen, groups default to wildcard all groups (*), and the option to choose group(s) is disabled. This option is only re-enabled when exactly one configuration is selected.

7.10.3 Search results view

The search results view displays the results of any searches, as shown in Figure 7-19 on page 189.

188 IBM CICS Explorer

Figure 7-19 Results of searches

The displayed resources are organized in tree form. If more than one configuration is selected, the top level element is a configuration. If all resource types are searched, by default results are grouped by type. Definitions that appear in more than one group are shown together.

You can introduce a new layer into the tree, separating the results into their resource groups by toggling the Show Groups icon.

You can navigate to the results of previously run searches through the Show Previous Searches toolbar menu within the Search results view.

Any definitions that appear in the search results view can be further manipulated by being deleted, opened, or edited. Any actions you can perform on the resource definition when navigated to in a specific resource definition view can also be performed from the search results view.

7.11 Cleaning up

CICS CM provides some options to help in resource definition clean up. For every configuration the options in Table 7-2 are available.

Table 7-2 Resource definition cleanup options Show Resources With Unique Shows all resources within the selected configuration Names that have a unique name.

Chapter 7. CICS Explorer CM plug-in familiarization 189 Show Duplicate Resources By Shows all resources within the selected configuration

Name and Type that are potentially duplicates, based on name and type. Show Orphaned Groups Shows all groups within a configuration that do not

belong to a list.

For CICSPlex SM-based configurations, the additional options in Table 7-3 are also available.

Table 7-3 CICSPlex SM additional options Show Shared Resources Shows resource definitions that are associated with two or more groups.

Show Orphaned Resources Shows resource definitions that are not associated with any group. You cannot edit these definitions.

The results of these queries are displayed in the search results view.

Properties view CICS CM populates the Properties view with the current selection. For resource definitions, the Properties view displays the attributes for the definition.

For Configurations, Lists, and Groups the Properties view displays additional information.

190 IBM CICS Explorer

Chapter 8. CICS Explorer PA plug-in familiarization

In this chapter, we discuss CICS PA, mainly focusing on the CICS Explorer plug-in for CICS PA.

In this section, we provide an overview of CICS PA.

8.1.1 Runtime product

The mainframe product provides system analysts assistance in a wide range of performance-related measurement scenarios with particular focus on: System performance analysis System tuning Capacity planning

The runtime product benefits CICS architects, developers, system managers, and administrators.

8.1.2 The plug-in

The CICS PA plug-in differs from the other CICS Explorer plug-ins because it does not utilize a published API on the host; instead, it uses data extracts from the PA runtime. from these data extracts targeted reports and analysis can be made.

Analysts can visualize their transaction performance data more easily using the graphing and tree views so that they can navigate and identify issues, such as Threadsafe, more readily and with less experience and skill.

At the time of writing, the CICS PA plug-in takes advantage of a subset of the main CICS PA runtime reporting functionality, presenting transaction performance summary data to you in a more understandable and intuitive way.

You can access performance data summaries and reporting scenarios through CSV files or database (DB2).

Information is extracted from the CICS PA runtime by a number of routes and can be saved either as CSV data or using a database. The data represents various measurements that are summarized over a defined time period.The CSV file is a simple portable form of data and is ideal when focused at a very specific data volume level. The database strategy is preferred for the analysis of larger data volumes not only because it can contain so much more historical data, but the performance is better from an application point-of-view rather than handling large CSV files in memory.

192 IBM CICS Explorer Presenting performance data in the context of CICS Explorer allows integration with the base explorer and other tools which compliments the historical performance information by presenting it alongside see the live data and definitions.

8.2 The PA Explorer environment

The Eclipse views that the CICS PA plug-in provides, Figure 8-1, can be used in a number of perspectives including the standard Eclipse resource perspective.

Tree view of data Properties of an individual transaction summary record

Outline (Taxonomy) Charts and view of data sheet views *csv only

Figure 8-1 CICS PA Eclipse views

Most users' first point of contact is the Project Explorer view in the top left of Figure 8-1. The Project Explorer is a standard Eclipse view presenting resources

Chapter 8. CICS Explorer PA plug-in familiarization 193 such as files and folders to a user. In the context of the PA plug-in, files, such as a CSV file extracted from the PA runtime, are contained within a project and folders. There are numerous ways to import these files into the explorer, including Drag-and-Drop, Copy-and-Paste, plus Import. Consult the online help for more detail. A similar mechanism to the CSV files is used for database references, which allows a consistent interface. The specification and configuration of database connectivity is described elsewhere.

The data that is contained through the CSV or database link is broken down by date, time, Applid, and transaction. This type of taxonomy makes it easy to navigate to a specific point of time to find a particular area of focus. Figure 8-2 shows data exposed using the CSV.

Figure 8-2 Data using CSV

After you identify an area of interest, you can see more information by opening a Sheet View or one of a series of charts, as shown in Figure 8-3 on page 195.

194 IBM CICS Explorer

Figure 8-3 Bar chart with overlay

To accompany the main views, you can choose to complement your data picture by showing a taxonomy or outline view. This is a sort of a "where am I?" aid. This view is only enabled with a CSV file because the database equivalent can be immense and adversely affect performance.

You can also use the standard Eclipse Properties View, which shows every detail being held about a transaction instance. Data is organized based upon categorizations, which describe later.

8.3 PA views and editors in detail

In this section, we discuss the PA views and editors.

8.3.1 The Project Explorer

The Project Explorer, Figure 8-4 on page 196, is a standard Eclipse component within the Resource perspective, which is also standard Eclipse. When the PA plug-in is installed the Project Explorer displays conventional projects, folders,

Chapter 8. CICS Explorer PA plug-in familiarization 195 and files, but if these files end with a suffix of CSV or CPA further information can be obtained from them, providing that they were created on the PA runtime.

Because we are using summary data with a unique key we can drill into these files and obtain a useful date, time, and applid transaction name taxonomy.

Note: Project Explorer can also be used to view and manipulate IA queries and bundles.

Figure 8-4 Project Explorer

Contextual menus, Figure 8-5 on page 197, are available on the project explorer view depending upon whether you selected one or more of the following options: Date Time Applid Transaction name

196 IBM CICS Explorer

Figure 8-5 Contextual menu

8.3.2 The Sheet View

The Sheet View provides access to the raw detail information that is available from a summary report. The data is keyed based upon Start date, Time, the Applid, and Transaction name, which uniquely identifies a record instance.

Those four fields are essential for the PA Explorer to be able to read the CSV or database provided data. If these fields are not present, the application will not provide any functionality over simply displaying raw data.

You can choose the columns that are extracted from the PA runtime, but following the four columns that form the unique record key is the task termination count column. Although not part of the primary key, this value is always required in reports as additional information. Omission of this column limits further functionality.

The subsequent columns are as defined by the data extraction process on the server.

Using standard Eclipse functionality you can sort the retrieved columns and the columns can themselves be moved so that associated data can be placed side by side for visual comparison. However, remember that the sort function,

Chapter 8. CICS Explorer PA plug-in familiarization 197 Figure 8-6, only sorts what was retrieved and does not cause a subsequent fetch of data to be executed.

Figure 8-6 Sort function

Other standard Eclipse functionality includes the ability to copy the data in an individual cell to the clipboard to be pasted into a document. Figure 8-7 is an example of how to copy data.

Figure 8-7 Copy data

You can also select and copy complete rows, as shown in Figure 8-8.

Figure 8-8 Copy complete rows

198 IBM CICS Explorer 8.3.3 Pie chart view

Pie charts are displayed in the Transaction detail view, as shown in Figure 8-9.

The pie charts contain a detailed breakdown of a single transaction ID in the time period selected. To display the Transaction detail view: 1. Select a single transaction in the Project Explorer view or a Sheet View. 2. Right-click the selection, hover over Performance history, and select Detail breakdown. The Transaction detail view is displayed. 3. Click a pie chart to show the details for a specific analysis type. In Figure 8-9, the Transaction detail view is shown with the CPU time pie chart selected, displaying detailed CPU time information for the selected transaction ID.

Figure 8-9 Transaction detail view

The Transaction detail view displays the following information: A view tab that shows the analysis type and the name of the transaction ID. An information bar below the view tab that contains further details about the transaction ID. A pie chart for each type of analysis. You can select each analysis by clicking the relevant pie chart.

Chapter 8. CICS Explorer PA plug-in familiarization 199 The Transaction detail view contains one or more pie charts depending on the data selected and categorization enablement, for example, if the Storage categorization enablement is not selected, the Storage pie is not displayed. Similarly, if there is no file usage data in the selected sample, the File usage pie chart is not displayed.

8.3.4 Bar charts

A bar chart, Figure 8-10, displays a bar for each transaction that is selected. Each bar contains one or more sectors, and each sector represents different information depending on the selection type.

You can access the bar chart through the Performance History Context menu. It is identified by a sub-menu that displays the bar graphic, as shown in Figure 8-10.

Figure 8-10 Creating a bar chart

The charts are described by scenarios, which give a pointer to what type of data is of specific interest. Figure 8-10 shows Threadsafe, which means that the fields that will be analyzed and displayed are important when considering a Threadsafe issue or concern: 1. Select two or more transactions or select a higher tree node, such as an application ID that contains two or more transactions, either in the Project Explorer view or a Sheet View. 2. Right-click the selection, hover over Performance history, and select the type of analysis to perform.

A new view opens displaying a bar chart for the selected analysis. In Figure 8-11 on page 201, a storage analysis is selected, and the Storage view is shown with

a bar chart for each of the selected transaction IDs.

200 IBM CICS Explorer

Figure 8-11 Bar chart

The bar chart view displays the following information: A view tab, containing the name of the analysis in this case, Storage. You can hover over the tab to show the data source file and number of records in the sample. An information bar below the view title, that contains the path and name of the data source file that contains the data. Stacked bars that consist of one bar for each transaction ID selected. Each bar in a stack consists of one or more sectors, each representing a different field. You can hover over a sector to show further information about the field. A Legend icon in the top left corner of the chart. Click this icon to display the chart legend. The legend shows only the colors in use in the current chart.

You can select one or more bars and perform a further analysis on the information by right-clicking and selecting a new analysis from the menu.

8.3.5 Timeline charts

A timeline chart displays all instances of a transaction ID in the selected application ID across either the whole data file or a range of dates specified using the Date dialog when selecting the data, for example, selecting the single record with a transaction ID of CRTP in an application ID of IYCYZC20 displays a bar for every instance of the transaction ID in the application. To display a timeline chart: 1. Select a single transaction, either in the Project Explorer view or a Sheet View. 2. Right-click the selection, hover over Performance history, and select the type of timeline analysis to perform. The restrict analysis time period dialog is displayed, as shown in Figure 8-12 on page 202.

Chapter 8. CICS Explorer PA plug-in familiarization 201

Figure 8-12 Restricting analysis time period

3. Select the time period to restrict the display to show only data between the two dates. Click OK. A new view opens displaying a timeline chart. In Figure 8-13, an analysis of transaction ID CRTP in application ID IYCYZC20 is selected.

Figure 8-13 Transaction ID CRTP in application ID IYCYZC20

The timeline chart displays the following information:

A view title that contains the name of the analysis, in this case, Response time. You can hover over the tab to show the data source file and number of records in the sample.

202 IBM CICS Explorer An information bar below the view title that contains the name of the CSV or database file that contains the data, the application ID, and the transaction ID.

Stacked bars that consist of one bar for each instance of the selected transaction ID in the application ID. Each bar in a stack consists of one or more sectors, each representing a different time field. You can hover over a sector to show the average time value for the CPU time field. A Legend icon in the top left corner of the chart. Click this icon to display the chart legend.

You can select one or more bars and perform a further analysis on the information by right-clicking and selecting a new analysis from the pop-up menu.

By using multiple timeline charts you can compare the way transactions are performing in one CICS region against the way they perform in another CICS region and identify potential problems. Figure 8-14 shows the timelines for the same transaction ID over the same period of time but running under different applications.

Figure 8-14 Multiple timeline charts

For more information about the details in specific timeline charts, see the related links at the end of this book.

Chapter 8. CICS Explorer PA plug-in familiarization 203 8.3.6 Properties View

Another Eclipse view. You can select a single transaction ID from the Project

Explorer view or from a chart, and display all of its properties in the Properties View. 1. From the workspace menu, click Window  Show View  Properties. The Properties View is displayed. 2. Select a single transaction in the Project Explorer view, Sheet View, or a chart view.

All of the details for the selected transaction ID are displayed in the Properties View, as shown in Figure 8-15.

Figure 8-15 Properties view

204 IBM CICS Explorer 8.3.7 Integrating with other plug-ins

The CICS Explorer provides contextual menus that are populated based upon

what type of object is currently selected and what other plug-ins are currently loaded.

A single selection is represented by a row in the Sheet View, a column in a bar chart, and a detail view or a single transaction in the Project Explorer, which represents a single instance of a summary record and has specific information regarding the transaction ID and Applid. Consequently those parameters can be used as contextual parameters within the Interdependency Analyzer plug-in or the System Management plug-in, as indicated in Figure 8-16.

Figure 8-16 Contextual menus

Figure 8-17 shows the dependencies.

Figure 8-17 Dependencies

8.4 CSV data extraction process

In this section, we discuss the CSV data extraction process.

Chapter 8. CICS Explorer PA plug-in familiarization 205 8.4.1 Server process

CICS PA provides report forms to enable a CSV data extract to be created using

the Extract and Export option of the CICS PA Report Sets panel.

For CICS PA V2.1 users, a new Sample Summary Extract Report Form EXPLORE3 is provided by APAR PK71846.

For CICS PA V3.1 users, a new Sample Summary Extract Report Form EXPLORE4 is provided with the product.

When you create the CSV extract report, make sure that the Extract Format delimiter is set to a comma rather than the default semicolon. You can then download the CSV file to your workstation to be used within the CICS PA plug-in.

8.4.2 Plug-in process

You can load CSV data into the CICS PA plug-in using three ways: Copy and paste Drag and drop The import function of CICS PA plug-in

Other plug-ins: Using an application other than CICS PA plug-in to make changes to the CSV file might cause errors and make the data unusable by CICS PA plug-in.

Locate the performance data file that you want to analyze and follow one of the methods below to load the data into the CICS PA plug-in.

Using copy and paste To copy and paste a file into PA Explorer: 1. Copy the data file by right-clicking and selecting copy from the menu. 2. In the Project Explorer view, select the folder where you want to store the data. 3. Right-click, and select Paste from the menu.

A copy of the data file is now in the CICS PA plug-in and available for analysis.

For further information about loading data and other Eclipse functions, see the Eclipse workspace User Guide.

206 IBM CICS Explorer Using drag and drop To drag a file from your file manager and drop it into PA Explorer: 1. In your file manager, select the data file.

2. Use your mouse to drag the file across to the Project Explorer view. 3. Put the cursor over the folder where you want to store the data file, and release the mouse to drop the file into the folder.

A copy of the data file is now in the CICS PA plug-in and available for analysis.

Using the Import function To import a file into PA Explorer from your local file system using the Eclipse import function: 1. Right-click anywhere in the white space of the Project Explorer view, and select Import. 2. In the Import dialog box, select File System. To assist in locating the file system, you can type File System in the text field. Click Next. 3. In the Import wizard, enter the directory path of the data, or click Browse, and select the directory from the list. All of the files in the directory are displayed in the Import wizard. 4. Select the data file to be imported. 5. In the Into folder text box, type the name of the folder where the data will be stored, or click Browse, and select the target from the list. Click Finish.

A copy of the data file is now in the CICS PA plug-in and available for analysis.

8.5 Database extraction process

In this section, we discuss the database extraction process.

8.5.1 Server process

CICS PA also enables SMF data to be loaded into a DB2 table by first loading the data into a Historical Database (HDB). From the HDB, you can export the data to a DB2 table or to a CSV file to use in the CICS PA plug-in.

The steps to Load CICS performance data from an SMF file into an HDB and exporting the data from an HDB file to a DB2 table or a CSV file are in Chapter 4 of the User’s Guide for CICS PA Version 3.1. See IBM CICS Performance Analyzer for z/OS User’s Guide Version 3 Release 1, SC34-7046-00 for more details.

Chapter 8. CICS Explorer PA plug-in familiarization 207 8.5.2 Plug-in process

You can analyze CMF performance data that is produced by CICS Performance

Analyzer for z/OS and stored in a database: 1. From the workspace menu bar, click Window  Preferences. 2. Click IBM CICS Performance Analyzer  Data sources. The Data sources dialog for CICS Performance Analyzer is displayed in the Preferences view. If it was pre configured, you see the connection details displayed; otherwise, the fields are blank. Figure 8-18 shows the PA Data sources dialog, which contains sample connection details to a DB2 database.

Figure 8-18 CMF performance data

208 IBM CICS Explorer 3. Click New to create a new connection.

4. Complete the fields with the details that your system administrator provided. Table 8-1 provides a description of the fields. Table 8-1 Option description

Option Description Name The local name that is used to identify this database connection. The name can be anything you choose and is used only to help you distinguish between different database connections.

Preferred Denotes the default data connection when accessing the plug-in from another plug-in. Server The TCP/IP host name of your database server. Address TCP/IP Port The port used to access the server. Number Database The name of the database on the server. Name Schema The name of the schema that is used for the (Qualifier) database. Userid Your authorized user ID for the database. Password Your password for the system. If you leave this field blank, you are asked to enter your password when the connection is attempted. Save Clicking this box saves your password on your Password computer.

5. Click Apply to save the configuration. 6. Click Test Connection.

When Test Connection is clicked CICS PA plug-in attempts to connect to the database that you configured. If you did not previously enter your password, you are asked to enter it now.

If the connection is successful, a message box opens at the bottom of the Data sources dialog showing the status, and you can now select data for analysis.

Chapter 8. CICS Explorer PA plug-in familiarization 209 If the connection is not successful, the message box displays an error message that provides a reason for the failure. Check the values in the fields, correct any errors, and click Connect to test the corrections.

When the connection is successful, click OK to close the Preferences view.

If you did not click Apply, you can cancel the process and close the Preferences view without saving the new connection, by clicking Cancel. If you already clicked Apply, you must click Delete to remove the connection.

You can use the Data sources preference page to maintain multiple connections, which allows you to specify many different databases

Project Explorer CPA file definitions To use the database table in the Resources View you must define the table based upon the database connection that you previously defined: 1. From the Project Explorer, select either a Project or Folder in which you want to create a link file. 2. Select New  Other (Shortcut Ctrl-n) to display Figure 8-19 on page 211.

210 IBM CICS Explorer

Figure 8-19 CPA file definitions

Figure 8-20 on page 212 shows the data source.

Chapter 8. CICS Explorer PA plug-in familiarization 211

Figure 8-20 CICS Data source

3. Select New CICS Data Source Node, which displays Figure 8-21 on page 213 with default values populated, where available. 4. The Data source defaults to the Default Data Context but can be changed to another. The filename defaults to the data source with an additional cpa extension. The table name defaults to EXPLORER_SUMMARY in accordance with the server data extraction requirements. 5. Press Finish.

A link to the database table is now in CICS PA plug-in and available for analysis.

Click the Properties menu option on a cpa file (Alt-Enter shortcut) to access methods to alter some of these settings and test that the connection with the

table works.

212 IBM CICS Explorer

Figure 8-21 Properties

Default data context It is important to note that when CICS PA plug-in is accessed from another plug-in, a default data context is used based upon the Data source that is specified as preferred. In addition, the table name must be described as EXPLORER_SUMMARY.

Chapter 8. CICS Explorer PA plug-in familiarization 213

214 IBM CICS Explorer

Chapter 9. CICS Explorer TG plug-in familiarization

In this chapter, we discuss CICS Transaction Gateway (CICS TG), focusing on the CICS Explorer plug-in for CICS TG.

The CICS Transaction Gateway is a set of client and server software components that allow a remote client application to invoke services in a CICS region. The client application can be either a Java™ application or a non-Java application. Depending on the platform, the non-Java application might use either a C (ECIv1 and ECIv2), C++, COBOL, COM, or .NET interface.

9.1.1 CICS TG products

The CICS TG is available through the following two products: CICS TG for z/OS CICS TG for z/OS V8 is the latest version for the z/OS platform. It is supported on z/OS V1R9 and later and supports connectivity to a CICS TS for z/OS V3R1 or later release. The CICS TG for z/OS provides comprehensive support for two phase-commit transactions along with support for SSL connections, high availability topologies, and advanced systems monitoring. It uses either the external communication interface (EXCI) or the IP Interconnectivity (IPIC) protocol to communicate with CICS regions for z/OS. It provides API support for Java and non-Java applications making ECI calls to COMMAREA or channel- and container-based CICS applications. CICS TG for Multiplatforms CICS TG for Multiplatforms V8 is supported on the following range of operating systems and platforms and is designed to support connectivity to any release of CICS on any platform: – Linux on System z – Linux on Intel® –Linux on POWER® –AIX® – HP-UX (on PA-RISC and Itanium®) – Sun Solaris (on SPARC) – Windows XP, Windows 2003 and Windows Vista

9.1.2 CICS Transaction Gateway components

In this section, we describe the key components of the CICS TG product. Figure 9-1 on page 217 shows the components of CICS TG for Multiplatforms product and its positioning in the product architecture. The resource adapters are

216 IBM CICS Explorer shipped as part of the CICS TG product for deployment to a WebSphere Application Server in support of JCA clients.

WAS CICS TG Components

Gateway Daemon IPIC JCA Resource Driver Adapters Protocol Handler Java Clients CICS1

ECI v2 C Clients

C,C++, COBOL Client and .NET Daemon Clients

ctgcfg Tool

Figure 9-1 Components of CICS TG for multiplatforms

The CICS TG for z/OS platform, unlike the distributed platforms, does not include the Client daemon. The CICS TG on z/OS does not require a Client daemon because it communicates with the CICS TS using either the IPIC or EXCI functions that CICS TS provides. Figure 9-2 on page 218 shows the components of CICS TG on z/OS.

Chapter 9. CICS Explorer TG plug-in familiarization 217

WebSphere CICS TG for z/OS Application Platform Components Server Gateway Daemon IPIC Driver Resource Adapters CICS Protocol Java Clients Handler

E X ECI v2 C Clients C I

ctgcfg Tool

Figure 9-2 Components of CICS TG for z/OS

In this book we use CICS TG for z/OS.

9.1.3 The Gateway daemon

The Gateway daemon listens for incoming remote client requests and manages the threads and connections necessary to ensure good performance. The performance and the features provided by the Gateway daemon running on the z/OS platform differ from the Gateway daemon running on distributed platforms. The Gateway daemon handles remote client requests using its protocol handlers component. The Gateway daemon can be configured to support both TCP/IP and SSL protocols.

9.2 CICS TG plug-in overview

The CICS TG plug-in provides a Gateway daemon’s view and a CICS connection’s view in the CICS TG perspective of the CICS Explorer. You can view

the status and activity of one or more Gateway daemons running on any platform in the Gateway daemons view. Use the CICS connections view to see the connectivity between CICS servers and one or more Gateway daemons.

218 IBM CICS Explorer When you switch to the CICS TG perspective, you obtain fast access to the new views. Each view includes a number of attributes by default. You can add or remove attributes as required. You can see the full set of attributes in the Properties view. The attributes are grouped into predefined categories.

The ability to create a composite perspective is a powerful feature of the CICS Explorer. You can add the views provided by the CICS TG plug-in for CICS Explorer to other perspectives. You can customize the CICS TG perspective to add other CICS Explorer views.

9.2.1 CICS TG Explorer view

The CICS TG Explorer view, Figure 9-3, displays the CICS Transaction Gateways that are being used and the CICS server connections associated with the CICS Transaction Gateway. You can test Gateway and CICS connections and refresh the status of the CICS Transaction Gateways.

Figure 9-3 The CICS TG Explorer view

9.2.2 Gateway daemon view

The Gateway daemons view, Figure 9-4, displays status and activity information for Gateway daemons that are both defined and available. The columns in the Gateway daemon view can be customized according to needs.

Figure 9-4 The Gateway daemon view

Chapter 9. CICS Explorer TG plug-in familiarization 219 9.2.3 CICS connections view

The CICS connections view, Figure 9-5, displays status and activity information

for the defined CICS server connections and active CICS server connections. The columns in the view can be customized.

Figure 9-5 The CICS connection view

9.2.4 Console view

The console view displays the output from the test facilities that are available with the CICS TG plug-in.

Testing the Gateway connection To test the Gateway connection, right-click the Gateway daemon, and click Test Gateway connection, as shown in Figure 9-6.

Figure 9-6 Testing the Gateway connection

Figure 9-7 shows the result of the test in the Console view.

Figure 9-7 The Console view - testing the Gateway connection

Testing the CICS TS server connection To test the connection to the CICS TS server, right-click the CICS server, and click Test CICS connection, as shown in Figure 9-8 on page 221.

220 IBM CICS Explorer

Figure 9-8 Testing the CICS connection

Figure 9-9 shows the result of the test in the Console view.

Figure 9-9 Console view - testing the CICS connection

Attention: Testing the CICS connection requires supportpac CH50 to be installed.

9.3 Configuration

In this section, we show how to configure the CICS TG daemon and the CICS Explorer TG plug-in.

Note: A basic knowledge of CICS TG is assumed. We explain how to configure CICS TG for use with the plug-in, not the CICS TG itself.

9.3.1 Configuring the CICS TG for the plug-in

In this section, we discuss how to configure CICS TG for the plug-in.

Statistics API protocol settings

We use the parameters shown in Example 9-1 on page 222 to define a statistics API protocol handler in the ctg.ini file.

Chapter 9. CICS Explorer TG plug-in familiarization 221 Example 9-1 Enabling the statistics API protocol handler

[email protected]=connecttimeout=2000;\ port=9091;\ maxconn=5;

The valid parameters are: Bind address The bind parameter sets the IP address or name of the host to which the protocol handler is to be bound. Port The port parameter specifies the number of the TCP/IP port on which the protocol handler listens for incoming client requests. Connection timeout The connect timeout parameter specifies how long the protocol handler waits in milliseconds for a connection manager thread to become available. Maximum number of connectionst The maxconn parameter specifies the maximum number of applications that can be connected at the same time to perform statistic queries.

We see the message in Example 9-2 after the successful start of the CICS TG daemon.

Example 9-2 Daemon message after successful start CTG6524I Successfully started handler for the statsapi: protocol on port 9091

9.3.2 Configuring the CICS TG plug-in

Next, we configure CICS Explorer to connect to the daemon: 1. Start the Explorer, and switch to the CICS TG perspective. 2. Select Window  Preferences, and enter the following values, as shown in Figure 9-10 on page 223: Connection Type CICS TransactionGateway Connection Name Name for this connection Location Host name Host name or IP address of the system where the CICS TG daemon runs Location Port Port number as specified in the statistics API protocol handler. See Example 9-1

222 IBM CICS Explorer

Figure 9-10 CICS Explorer TG plug-in connection definition

3. With all parameters populated, click connect, as shown in Figure 9-11 on page 224.

Chapter 9. CICS Explorer TG plug-in familiarization 223

Figure 9-11 Connect to the Gateway

224 IBM CICS Explorer

Chapter 10. CICS Explorer Tivoli OMEGAMON XE plug-in familiarization

In this chapter, we focus on the CICS Explorer OMEGAMON XE plug-in and the functionality that it provides.

Tivoli OMEGAMON XE for CICS provides the ability to proactively monitor basic and complex CICS systems. It provides performance and availability information that can be leveraged to pinpoint bottlenecks, and avoid downtime. OMEGAMON XE provides insight into currently occurring issues, which allows the user to choose an informed course of action.

10.1.1 Tivoli Enterprise Monitoring Server (TEMS)

The Tivoli Enterprise Monitoring Server (TEMS) gathers data from the Tivoli Enterprise Monitoring Agent (TEMA), and acts as a collection and control point, for alerts. Data received is sent to Tivoli Enterprise Portal clients, where it can then be displayed in tabular or graphic views. Requests for information or action, from Tivoli Enterprise Portal clients can be accepted and distributed to the agents for processing.

10.1.2 Tivoli Enterprise Portal Server (TEPS)

The Tivoli Enterprise Portal (TEP) is a Java-based interface. It provides access to the data monitoring and management resources within IBM Tivoli Monitoring. The TEP is installed on its own server, which is the Tivoli Enterprise Portal Server (TEPS). The server performs common TEP functions that reduce the processing that the Tivoli Enterprise Portal client must perform.

10.2 CICS Explorer Tivoli OMEGAMON XE plug-in

The plug-in provides the ability to view OMEGAMON data in Eclipse-based applications, such as CICS Explorer.

Most Tivoli monitoring systems, including their status information, can be displayed. Monitoring data from Tivoli OMEGAMON XE for CICS and Tivoli OMEGAMON for CICS TG can also be accessed. The plug-in can also display a list of currently active situations.

10.2.1 Installation requirements Consult the IBM Tivoli Monitoring: Administrators Guide for specifics regarding the Tivoli configuration steps.

226 IBM CICS Explorer The installation requirements are:

TEMS SOAP Interface: The plug-in communicates with the TEMS server through the TEMS SOAP Interface: – A version 6.1 (or later) TEMS server is required.

– The TEMS server SOAP Interface must be configured and enabled. – Currently the plug-in does not support Secured Socket Layer (SSL) connections to the TEMS SOAP Interface. – It is important that a fixed TEMS port is assigned as part of the configuration. If a fixed port is not set, the port number changes each time the TEMS address space is recycled. TEPS Client Files: The plug-in utilizes files shipped with the TEP client. The files are not required, but failure to use them results in severely curtailed functionality. If you choose to use the TEPS Client Files they must either reside on, or be copied to the machine that will run the plug in. – The files are named dockpp, where pp is a two character product code. Example: dockcp, dockgw, dockn3, and so on. – The files can be found on the machine where TEPS is installed: • For Windows platforms look in the \CNPS directory • For other platforms look in the //cq/data directory – The files can also be found on the host z/OS platform, in the RKANDATV library. In this instance, you can FTP the files, in ASCII mode (not binary), to the machine that will run the plug-in.

10.2.2 Installing the plug-in

1. Go to the CICS Explorer Download Site at: www.ibm.com/software/cics/explorer/download 2. From the Other Downloads section, select the OMEGAMON XE for CICS plug-in link. 3. Select Download, and download the zip file. 4. Unzip the zip file. The contents include a documentation file with detailed installation instructions and another zip file. 5. Follow the detailed installation instructions in the documentation file to install the plug-in. The documentation also covers connection configuration and how to access the new IBM Tivoli Monitoring perspective.

Chapter 10. CICS Explorer Tivoli OMEGAMON XE plug-in familiarization 227 10.3 Using the plug-in

When the connection is made to the SOAP sever, information regarding the monitored systems is used to construct a navigation tree.

The IBM Tivoli Monitoring perspective is made up of three panels, as shown in Figure 10-1.

Figure 10-1 Multiple TEMS and Products

10.3.1 IBM Tivoli Monitoring Navigation Tree display

Contained in the left panel, this display is similar to the TEP client topology display. It performs a function that is similar to the CICS Explorer CICS SM perspective topology panel. Clicking an item in the tree controls the scope of the resources that are displayed in the query results view.

Currently the plug-in only supports query information for Tivoli OMEGAMON for CICS and Tivoli OMEGAMON for CICS TG resources.

228 IBM CICS Explorer This view supports the launching of the TEP browser client. TEP launching is available by clicking Launch TEP, which is in the topology view's toolbar or as a right-click menu option.

Expand all and Collapse all actions are also available as toolbar or right-click

menu options.

10.3.2 IBM Tivoli Monitoring Data display

The top-right panel contains query results. This panel displays the results of a request for data from the SOAP server. The request is issued by selecting the report in the topology tree.

Some reports are not currently supported by the plug-in. Unsupported reports typically require additional parameters that specify the data to be returned. This category of reports is usually only available as a link target in Tivoli.

Enterprise Portal (TEP) client. Most reports on the TEP client topology tree (for CICS and CICS TG) are supported by the plug-in.

Note that some OMEGAMON reports contain a large amount of data. Driving these reports might result in a large amount of data being requested from the TEMS SOAP interface.

Currently some data types, used by the IBM Tivoli Monitoring servers are not fully supported, by the plug-in. Some values might be displayed without appropriate scaling, for example, some fields that must be shown as three decimal places are left-shifted three places and shown as integer values 1,000 times larger than their actual value.

The plug-in supports the exporting of the table data as a Comma Separated Values (CSV) file. The CSV file can then be imported into a spreadsheet (or other application) for further processing or charting. The export function is driven by clicking the appropriate action in the toolbar or as a right-click menu option.

Figure 10-2 on page 230 shows CICS transaction analysis, Launch TEP, Expand all, and Collapse all.

Chapter 10. CICS Explorer Tivoli OMEGAMON XE plug-in familiarization 229

Figure 10-2 CICS transaction analysis, Launch TEP, Expand all, and Collapse all

10.3.3 IBM Tivoli Monitoring Situations display

Located in the bottom-right panel, displays the current TEMS situation events. The view is updated every 30 seconds.

The data is displayed in a tabular form. Clicking a column header causes the table to be sorted by that column's value. Clicking the column header again reverses the sort order.

The active situations can be exported as a CSV file. The export function is driven by clicking the appropriate action in the table's toolbar or as a right-click menu option.

230 IBM CICS Explorer

Chapter 11. CICS Deployment Assistant

In this chapter, we provide an introduction to the CICS Deployment Assistant. This new, tightly integrated plug-in for the CICS Explorer works together with host components to give you a powerful toolkit to manage your CICS deployment and to discover your CICS assets.

The CICS Deployment Assistant (CICS DA) is a new tool designed to help you to discover, model, visualize, and deploy new and existing CICS regions. With CICS DA you can visualize and control all your CICS resources. You can also visualize and manage all key relationships from a single point of control. With CICS DA you can automate and standardize your CICS environment.

CICS DA is an interactive control system that allows CICS systems programmers to create and maintain a CICS environment easily. CICS DA is a part PC and a part mainframe based graphical user interface (GUI). The CICS PC part is incorporated into the CICS Explorer as a plug-in.

11.2 The prerequisites for CICS DA

In this section, we discuss the components that are required to run CICS DA.

11.2.1 CICS Explorer

The CICS DA plug-in must be installed in the CICS Explorer V1.0.1.

11.2.2 z/OS host component

IBM z/OS version 1.9 or higher is required. If access to the MVS™ system log is needed by users of CICS DA, z/OS V1.11 is required. JES3 user must have z/OS version 1.10 or higher.

11.2.3 CICS Transaction Server

CICS/TS version 3.1 or higher is required. Recommended is CICS/TS V4.1. APAR PM15583 with PTF UK60398 and APAR PM15214 with PTF UK60399 provide the ability for CICS/TS V4.1 server, to access the System Initialization Parameters (SIT) and any overrides with CICS DA.

232 IBM CICS Explorer 11.3 Installing the CICS DA components

There are three main steps that are necessary to install the CICS DA:

1. Install the CICS DA host component. 2. Perform the post-installation configuration for CICS. 3. Download and install the CICS DA plug-in.

Note: We did the installation according to the instructions in the Release Notes for CICS Deployment Assistant, and we recommend that you use the release notes as a guide to install the products host component.

You will find the release notes and the zip file for the CICS DA plug-in on the CICS Explorer download page. To download both files: 1. Enter in your browser ibm.com/cics/explorer/download. 2. Click Link to Download page, and then logon with your IBM ID. 3. Select CICS Explorer plug-in for CICS Deployment Assistant V1.1 or CICS Explorer plug-in release notes for download. 4. Save the compressed file in a temporary directory, and do NOT extract the file. The CICS Explorer automatically extracts the contents.

The download does not include the host components; instead, they must be ordered separately. CICS Deployment Assistant for z/OS Version 1 Release 1 Compid 5655-W4800.

11.3.1 Installing the CICS DA plug-in into CICS Explorer

In this section, we describe how to install the CICS DA plug-in: 1. Download the CICS DA plug-in zip file from the IBM server. Do NOT extract it. 2. Start the CICS Explorer (must be CICS Explorer V1.0.1), and click Help  Software updates  Available Software  Add Site. A window opens entitled Add Site. There you can enter the location of the zip file. 3. Click Archive, and select the previously downloaded CICS DA plug-in zip file.

11.3.2 Establishing a connection to a host

In this section, we describe how to create a CICS DA type connection: 1. Start your CICS Explorer and open the CICS DA perspective. You can open the CICS DA perspective if you click the CICS DA icon on the right-upper

Chapter 11. CICS Deployment Assistant 233 corner. Alternatively you can navigate through Windows  Open perspective  Other. There you can select CICS DA.

2. If you changed the perspective to CICS DA the first time, you see on the right-lower corner (see Figure 11-1) that no CICS DA connection is open. Refer to Table 4-1 on page 79 to read more about connection manager status icons.

Figure 11-1 No connection defined

3. Click the text to open the preference connection window. From there you can define your connection.

Note: First define your credentials, specifying user ID and password. Later in the connection definition you can refer to these credentials.

4. Start by selecting the connection type you want to define. In this case it is a CICS Deployment Assistant type of connection. 5. Press New, and give a name for this connection. Also, specify the host name and the port name. Refer to the previously defined credentials (user ID and password). 6. Additionally specify the z/OS system ID, console name, and the CICS DA data sets HLQ.

Note: After the installation of the CICS DA host component, there are three data sets cataloged on your z/OS system. The of this data sets are SCPHAUTH, SCPHINST and SCPHLOAD. The CICS DA HLQ means, that all qualifiers before must be specified. See Figure 11-3 on page 235 for an example.

7. When the connection is defined, click the red square at the lower right corner to connect to the host. A successful connection is indicated by a green circle as shown in Figure 11-2.

Figure 11-2 Connection established

In Figure 11-3 on page 235, you can see how we defined our connection.

234 IBM CICS Explorer

Figure 11-3 Defining a connection for CICS Deployment Assistant

The CICS DA connected window is divided into multiple frames.

Note: If you resized the frames or you closed one, perhaps by accident, and you want to reopen or resize it, you can use the Window  Reset Perspective function at any time.

In the lower window on the right side you might see the error message shown in Figure 11-4 on page 236. In this case your z/OS level is not V1.11 (see

Chapter 11. CICS Deployment Assistant 235 prerequisites for browsing the MVS system log in 11.2.2, “z/OS host component” on page 232).

Figure 11-4 Error message when z/OS version is lower than V1.11

11.3.3 Connection types

At this point, we do a brief description into connection types because it is important to select the right connection type. Early versions of the CICS Explorer were using the CICSPlex SM Data Interface only, which was a kind of read-only access. The CICS Management Interface (CMCI) followed soon to connect also stand-alone CICS regions that are not part of a CICSPLex. This interface allows update access. To connect successfully to the CICS DA host component, a new CICS DA type connection is required. Table 11-1 provides an overview of the connection types that are currently available. For further information, refer to 4.2, “Connections and credentials” on page 78.

Table 11-1 Connection types System Connection type

System z/OS System z - FTP

CICPlex CICSPlex SM Data Interface (read-only)

CICSPlex & CICS Management Interface (CMCI) CICS

CICS DA CICS Deployment Assistant

11.4 Creating a new CICS DA project

The Eclipse platform is project oriented, and the CICS Explorer is based on Eclipse. So if you want to start new work, you must have a CICS DA project open. A CICS DA project is used as the repository where the system configuration data that is collected by CICS DA is saved. This system information in the project is known as the model. CICS DA projects are created during the

236 IBM CICS Explorer system discovery process. You cannot create a CICS DA project without performing a system discovery:

1. Select Explorer  New Wizards  CICS Deployment Assistant Project. 2. Specify a name for your project. Select the connection to use for your

discovery. By default it is the connection currently in use. 3. Click Discover MVS Images to let the system start to discover your z/OS sysplex.

11.4.1 Discovering and creating the system model

When you perform a discovery operation you import the discovered system information into your CICS DA project. The system information that is contained in the project is known as the system model. When you run discovery, CICS DA submits a job through FTP to execute a discovery program. The first thing the discovery program does is identify all of the MVS systems in the sysplex. You then select the MVS images on which to perform the next stage of the discovery process. The discovery program then looks at the regions that are running on each selected MVS image and identifies supported releases of CICS and other running instances, such as CICSPlex SM CMASes, Web User Interface servers, and DB2 and MQ servers, as well as CICS Temporary Storage, Coupling Facility Data Tables (CFDT), and Named Counter Server.

Note: Only active instances are discovered. If a CICS region or another CICS asset is not active, it will NOT be discovered.

The Finish button ends the process, creating a new project. The project is now visible in the left upper frame. Expand the folder and, click the plus sign to see your CICS assets.

11.5 Discovering your CICS assets

In this section, we review some figures to give you an overview of how CICS DA discovers CICS assets.

11.5.1 Discovering CICS regions

The main CICS asset is a CICS region. CICS DA can discover CICSPlex managed and un-managed CICS regions with a few clicks. Figure 11-5 on page 239 gives you an overview how powerful CICS DA is.

Chapter 11. CICS Deployment Assistant 237 To discover CICS regions:

1. On the left-upper side window, select CICS Regions  Managed by CICSPlex SM and CICS regions  Unmanaged. 2. Double-click the EPRED3 region to bring all the information you see in the

right-upper window, such as, the CICS versions running in that region (660), the MVS system ID (SC66), the name of the CICSPlex (EPRED), and the name of the CMAS (EPREDC). You can see issues to stop and start that region with a mouse click (see 11.5.6, “Starting and stopping CICS regions” on page 246). You can even clone the region from that window (see 11.5.7, “Cloning an existing CICS region” on page 248) by simply moving and using your mouse. You can see some blue hypertext (blue underlined text), for instance, Data set name. Others are MVS Image, DB2, WebSphere MQ, CICSPlex, and so on. Simply clicking that hypertext gives you more information about that topic. If you click Data set name, for example, you can edit your CICS startup JCL. You can change it, save it, stop CICS, and re-start CICS to activate your changes with a few clicks from one window. No need to switch back to TSO or SDSF. Figure 11-5 on page 239 shows the CICS regions.

238 IBM CICS Explorer

Figure 11-5 Discovering CICS regions

Let us discuss the two windows on the lower part of Figure 11-5. On the left window, you can see jobs in your system. The jobs can be running or they are already in the held output queue.

Look at figure Figure 11-6 on page 240, you can see five jobs in the system with jobname EPRED3. The first job (JOB02783) was canceled (notice the RC=S222). The following three jobs are in the held output queue for further review or processing (print or delete). The last job (JOB03997) is currently running, indicated by the small green triangle. A double-click opens the whole job. Expanding the plus sign gives you all the available JES data sets (for example, the JESMSGL, JESJCL, MSGUSR). Clicking the plus sign is comparable to the ? in SDSF just before the job. Clicking a specific data set (for example, MSGUSR) opens the CICS TDQ CSMT on the right-upper window,

where you can investigate specific messages. You get the same functionality by clicking the z/OS job tab in the opposite window.

Chapter 11. CICS Deployment Assistant 239

Figure 11-6 Jobs in the system

The window on the lower-right side shows the MVS syslog (if you are on z/OS version 1.11; otherwise, see Figure 11-4 on page 236). When you double-click the Syslog Tab, the small window expands to a full window. See Figure 11-7 on page 241. Now you can easily go through the syslog using the mouse and the scroll bar on the right side.

Notice, the top of the Window, where you can see which MVS syslog you are browsing. This also shows the date and start time of the syslog currently viewed.

240 IBM CICS Explorer

Figure 11-7 Syslog view full window size

You can enter z/OS commands by clicking the z/OS command tab. In Figure 11-8, we entered the z/OS command d iplinfo for demonstration purposes.

Figure 11-8 Enter z/OS commands

Chapter 11. CICS Deployment Assistant 241 The results of this command are displayed underneath the command line.

Figure 11-9 shows that the Console tab is activated. We edited and changed the start-up JCL and viewed the confirmation message. Next, we tried to shutdown CICS and get the response that the CICS was not up at that time. Finally, we

started the CICS and got the message that a job has been submitted. No need to go back to TSO, or switch to SDSF. This all can be done from a single point of control.

Figure 11-9 The Console view

11.5.2 Checking the CICS topology

You can distribute CICS applications and the resources they use between interconnected CICS regions. You can group CICS regions into CICS system groups and CICSPlexes and distribute regions across the z/OS systems on a sysplex. That is your CICS topology. Without CICS DA, it requires several steps per CICS, plus inside knowledge of the expected CICS topology to get an overview of your CICS topology. With CICS DA, you are almost only a couple of clicks away to manage the configuration for ALL CICS systems within the CICSplex.

A CICS topology must be well documented. However, the documentation is sometimes neglected and often not up-to-date. With the CICS DA, you can easily get an up-to-date picture of your current CICS topology. Make the CICS DA project window on the left-upper side of your CICS DA perspective your active window. Open the CICSPlexes folder and double-click the CICSplex you want to investigate.

To give you an example on how easy you can get up-to-date topology information about your CICSPlex, we added Figure 11-10 on page 243. We opened the ALLTORS folder to see which CICS regions are dedicated as Terminal Owning

242 IBM CICS Explorer Regions (TOR). Clicking any item gives you further information or the possibility to change your topology.

Figure 11-10 Discover the CICS topology

The CICSPlex topology frame is divided into four sub-areas: Groups Regions CMASes WUIs

The information provided in each sub-area works like a hyperlink. Double-click the EPREDC (MP) in the CMAS area for example, opens the CMAS view where you get further information and the ability to dig deeper into your CICS topology.

11.5.3 Investigating CICS initialization options

CICS initialization options can be at various places. You must have a SIT table or at least a pre-generated table with all of the default initialization values. You can

Chapter 11. CICS Deployment Assistant 243 have initialization options specified in the SYSIN data set. You can also specify initialization options in the JCL. To check all of these options for all CICS regions can be cumbersome and time consuming. Additional expert knowledge is necessary, for instance, you must know the location of the SIT source and the location for the overrides. By contrast, using CICS DA, you can stay on one window and make the necessary changes to the initialization options, for example, select a CICS region, right-click, and highlight Show SIT Parameters. A new menu is displayed which then you can select a CICS initialization option location. In Figure 11-11, we show how we selected the CICS initialization options specified in the SYSIN data set for CICS region EPRED3.

Figure 11-11 Investigate the CICS initialization options

244 IBM CICS Explorer Note: To access the CICS Transaction Server startup initialization table parameters (SIT) and any overrides, you must be on CICS/TS version 4.1 with UK60398 and UK60399 applied.

11.5.4 Viewing CICS-related spool files

If you work with CICS-related spool files, CICS DA eases the handling of this process. There is no need to switch back to another interface anymore. Stay within the CICS Explorer environment.

If you refer back to Figure 11-11 on page 244 you see in the lower-right side the MVS syslog. Remember that z/OS 1.11 is mandatory for viewing the syslog; otherwise, you will see the error message shown in Figure 11-4 on page 236. The next tab on the right of System Log is z/OS Job. If you click this tab, you see all the spool files for the currently selected region, in this case region EPRED3. We selected JESMSGLG, as shown in Figure 11-12 to find the Control is being given to CICS message.

Figure 11-12 Find message Control is being given to CICS in spool file

In the lower left-side window, you can easily change your selection by clicking the job you want to see. Alternatively, you can view spool files in that window by clicking the plus sign.

11.5.5 Working with CICS-related data sets and JCL

Working with data sets is similar to the spool files. An important thing to mention here is, you must change the perspective. But you still stay in the CICS Explorer. For demonstration purposes, we show Figure 11-13 on page 246. We switched back to the CICS SM perspective and opened the Files tab. We selected the file STOCK to be closed.

Chapter 11. CICS Deployment Assistant 245 Notice in the right-upper corner that the CICS SM perspective is now in the foreground and the CICS DA perspective is in the background.

Figure 11-13 Closing a file from the CICS SM perspective

11.5.6 Starting and stopping CICS regions

In this chapter, we demonstrate that you can start and stop your CICS regions with CICS DA. Switch to the CICS DA perspective.

Defining a start policy Before you can start a CICS region with CICS DA, you must define a policy to CICS DA. If you start your CICS systems as batch jobs, select the Batch Job option, and add the fully-qualified name of the PDS or the PDS/E, and append the member name in round brackets. See example in Figure 11-14.

Figure 11-14 Start policy for a batch started CICS system

246 IBM CICS Explorer When CICS is started as a started task, select the Started Task option, and add the start command in the free area after Start Command.

Starting a CICS region To start a CICS region: 1. Click Start Region, which is located after the green triangle. 2. When you are prompted whether you really want to start this region, reply with yes. Notice the confirmation message in the console tab in the lower window. It confirms that a job (including job number) was submitted.

Stopping a CICS region To stop a CICS region: 1. Click Stop Region, which is located right after the red square. CICS DA submits a job and uses the MVS MODIFY command to shutdown the CICS region.

2. CICS DA uses the console name that was specified in the connection definition (see Figure 11-3 on page 235). You must define this console in CICS; otherwise, you will receive an error in the CICS DA console, as shown in Figure 11-15. An alternative to this is to allow autoinstall for MVS consoles (SIT option AICONS=YES). In the CICS Resource Definition Guide, Chapter 42 Autoinstall, you find further information about implementing autoinstall for MVS consoles.

Figure 11-15 Error message when console is not defined to CICS

Note: Only Managed Address Spaces (MAS) and stand-alone CICS regions are eligible for CICS DA shutdown. CMASes or WUI servers are NOT allowed to be shutdown with CICS DA.

Chapter 11. CICS Deployment Assistant 247 Checking region status: Refreshing the window On the left-side, upper window, you can see all of your CICS regions. The regions that are up and running have a small green triangle. However, this status does not change until you refresh this window. You can do a refresh either by pressing the PF5 key or by right-clicking and selecting Refresh.

11.5.7 Cloning an existing CICS region

If your workload grows and you need an additional CICS system, you can use CICS DA to clone a region. The CICS region you want to clone must be a CICSPlex SM-managed region and it must be up and running. To clone an existing CICS region: 1. Double-click the region you want to clone. 2. Select Clone CICS Region Wizard. When a new window opens, specify all essential values, such as new applid, sysid, start policy, as shown in Figure 11-16.

Figure 11-16 Clone a CICS region from EPRED3 to EPRED9

248 IBM CICS Explorer 3. Click Next. A new dialog window shows all of the CICS-related data sets as they currently exist and new data set names.

4. If you have a shared CSD, click that option to indicate that the CSD name for both CICS regions is the same. If the new data set name is greyed out and the Share option is selected but also greyed out, then the data set must be shared, as shown in Figure 11-17.

Figure 11-17 New data set names

5. Click Finish to confirm your choices. CICS DA performs a check to ensure that the new data set names and batch job do not already exist. If the check is successful, the data sets are allocated and initialized. CICS DA then adds the new region to your CICSPlex SM definitions and to the system model. Finally, the CICS region editor opens showing details of the CICS region, and a report is shown in the Console view.

Chapter 11. CICS Deployment Assistant 249 There are some operations in which CICS DA cannot execute, such as defining the region to your security policy, connectivity steps, MVS system logger setup, and so on. This action must occur before CICS can start.

Hint: CICS DA provides a User Guide. The User Guide is incorporated into the CICS Explorer Help function when the CICS DA plug-in is installed. It is a valuable source of documentation and information for how-to questions.

11.5.8 Adding a CICS to an existing CICSPlex

Using CICS DA you can install the CICSPlex SM definitions in an unmanaged CICS region, and add the region to an existing CICSplex and, optionally, one or more of the system groups in the CICSplex. CICS DA can add a CICS region to a CICSplex only if the region is started by a batch job. For further information, refer to the CICS DA User Guide. Remember that you find the CICS DA User Guide in the CICS Explorer Help  Help Contents when the CICS DA plug-in is installed.

250 IBM CICS Explorer

Chapter 12. WebSphere MQ plug-in

In this chapter, we provide an overview of the WebSphere MQ plug-in. We discuss both the WebSphere MQ Explorer and the WebSphere MQ plug-in for CICS Explorer. Additionally, we explain how to integrate WebSphere MQ Explorer with CICS Explorer and how to manage MQ resources from this interface.

The WebSphere MQ plug-in for CICS Explorer provides an integration of the WebSphere MQ Explorer into the CICS Explorer. Therefore it is possible to operate CICS systems and WebSphere MQ resources from the same desktop application, providing benefit if you carry out cross system administration, monitoring, and problem determination.

12.2 The WebSphere MQ Explorer

The WebSphere MQ Explorer, like the CICS Explorer, is an Eclipse-based graphical tool that you can use to explore and configure all WebSphere MQ objects and resources. The WebSphere MQ Explorer is included with the WebSphere MQ server installation. SupportPac MS0T is also available for download, separately from the WebSphere MQ Explorer. Having WebSphere MQ Explorer installed on your system is a prerequisite to the CICS Explorer MQ plug-in.

12.3 CICS Explorer WebSphere MQ plug-in

Although you can use CICS Explorer and WebSphere MQ Explorer independently, it shows considerable advantages in using the WebSphere MQ plug-in into the CICS Explorer. From a single point of control, you can manage your CICS resources and your WebSphere MQ resources.

12.3.1 Downloading SupportPac CS1Q

To get the latest version of the SupportPac: 1. Type ibm.com/cics/explorer into your browser. This directs you to the IBM web page. 2. Select Click here to get CICS Explorer - Free Product Download to start the download. On the next page you find the download link for SupportPac CS1Q. 3. Accept the software licence agreement, and then the download will start.

After the download, do not extract the file at that time.

252 IBM CICS Explorer 12.3.2 Downloading SupportPac MS0T

To download SupportPac MS0T:

1. To download the SupportPac you must have a IBM registered user ID. If you have no such user ID, register yourself on the web page before you start the download. When you have resolved the registration, you are ready to download the 2 files mst0_eclipse331_windows.zip and mst0_explorer7013_windows.zip. 2. Type ibm.com/webspheremq/explorer into your browser, and download the MST0 SupportPac. Note the installation instructions on that web page. 3. After the SupportPac is downloaded, navigate to the directory where you saved the files, and first unpack the Eclipse .zip file. Double-click Setup.exe, and follow the on screen instructions to install Eclipse. 4. After Eclipse is successfully installed, unpack the MQ Explorer .zip file. Double-click Setup.exe, and follow the on screen instructions to install MQ Explorer.

Note: IBM WebSphere Eclipse Platform and IBM WebSphere MQ Explorer are installed as real Windows application. If you want to uninstall it, you can enter the Windows Control Panel subfolder Add or Remove Programs to remove it from your PC.

The CICS Explorer is installed in a normal folder, which you can remove by deleting that folder.

Chapter 12. WebSphere MQ plug-in 253 12.4 Integrating MQ Explorer with CICS Explorer

In this section, we describe how to integrate MQ Explorer into CICS Explorer.

12.4.1 Importing CSQ1 into CICS Explorer

To install the MQ Explorer integration pack into the CICS Explorer: 1. Select the menu option HELP of CICS Explorer, and click Software updates. 2. Select Software Updates  Available Software  Add Site button  Archive. 3. Specify the previously downloaded csq1.zip file as the input file name, and click Open. 4. Select the appropriate options, and click Install to install the SupportPac.

12.4.2 Copying WebSphere MQ Explorer files into CICS Explorer

You must copy two MQ Explorer files into the CICS Explorer. If you did not change the installation path, the files are in: C:\Program Files\IBM\WebSphere MQ\eclipseSDK33\eclipse\links

The two file names are com.ibm.mq.explorer-feature-ms0t.link and com.ibm.mq.explorerhelp-feature-ms0t.link

Copy the files into this directory or wherever you installed CICS Explorer: C:\Program Files\IBM\CICS_Explorer\links

Remember that you can install CICS Explorer in any folder.

12.4.3 Restarting CICS Explorer

The MQ plug-in installation is now finished and ready to use when you restart CICS Explorer.

Note: For detailed installation instructions, read the HTML Document CS1Q Release Notes - Readme. This readme file is included in the cs1q.zip file.

254 IBM CICS Explorer 12.5 Managing WebSphere MQ resources in CICS

Explorer

In this section, we describe how to manage WebSphere MQ resources.

12.5.1 Starting CICS Explorer and switching to WebSphere MQ Explorer perspective

After you successfully install the WebSphere MQ plug-in into the CICS Explorer and restart CICS Explorer, locate the MQ Explorer button, which is in the right upper corner, as shown in Figure 12-1. It is now listed under all available perspectives. Click the icon to open the WebSphere MQ Explorer perspective.

Figure 12-1 WebSphere MQ Explorer plug-in button

12.5.2 Defining and connecting a Queue Manager

Now you must enter some WebSphere MQ-specific credentials. The basic information you must have available is to which queue manager you want to connect to and what is the port number.

Chapter 12. WebSphere MQ plug-in 255 To enter this information:

1. Right-click the folder Queue Manager in the left window, titled MQ Explorer Navigator. 2. When the pop-up window appears, select Add Remote Queue Manager,

enter your queue manager name, and click Next. A window opens, where you can specify the host name or the IP address and the Port number and some additional information. In our example in Figure 12-2, we used the queue manager name MQCR. The example host name is wtsc66.itso.ibm.com with a port name of 1415.

Figure 12-2 Enter queue manager name, host address, and port number

3. Click Finish complete the process. The system automatically connects you to the queue manger, as shown in Figure 12-3 on page 257 and Figure 12-4 on page 258.

256 IBM CICS Explorer

Figure 12-3 Connect to queue manger successful

Chapter 12. WebSphere MQ plug-in 257

Figure 12-4 Left-click the queue manager name to show the details

12.5.3 Hints and tips

Be careful when entering the WebSphere MQ credentials. A wrong port number, for example, can lead to messages that are not necessarily directly pointing you to the correct cause of the problem.

Figure 12-5 shows the error message that you get when the port number is not valid.

Figure 12-5 Invalid Port number message

258 IBM CICS Explorer 12.6 Migration issues and versioning

In this section, we describe how to manage different versions and automatic software upgrades.

12.6.1 Multiple CICS Explorer versions coexisting

You can have several CICS Explorer versions installed on your system. You can have more than one instance of CICS Explorer running simultaneously; however, each instance must have its own workspace. If you, nevertheless, start two CICS Explorers using the same workspace, you will get the message displayed in Figure 12-6.

Figure 12-6 Workspace is looked at by another CICS Explorer instance (version)

Note: We strongly recommend that you use different workspaces for each CICS Explorer version!

12.6.2 WebSphere MQ plug-in with new CICS Explorer version installed

Before you start the newly installed CICS Explorer for the first time, we strongly recommend that you allocate a new workspace. See 3.3, “Updating the CICS Explorer” on page 63.

After you allocate a new workspace and the CICS Explorer is restarted, re-import CSQ1 into the CICS Explorer (see 12.4.1, “Importing CSQ1 into CICS Explorer” on page 254), and then copy the WebSphere MQ Explorer files (see 12.4.2, “Copying WebSphere MQ Explorer files into CICS Explorer” on page 254).

Chapter 12. WebSphere MQ plug-in 259 12.6.3 Locating and changing the workspace

By default CICS Explorer allocates the workspace on Microsoft Windows

operating system in C:\Documents and Settings\username\ .cicsexplorer. You can use any name for additional workspaces. If the workspace does not exist, CICS Explorer creates it. To change a workspace: 1. Create a shortcut to CICS Explorer as shown in Figure 12-7.

Figure 12-7 Create a shortcut

2. Right-click the shortcut, and select Properties. 3. Append your new workspace to the target, as shown in Figure 12-8 on page 261. In this example, we decided to allocate a workspace in c:\CICS_Explorer_V1007\workspace. You must not preallocate this folder because CICS Explorer automatically does it.

Note: A shortcut is mandatory. You cannot provide the -data option from the primary cicsexplorer icon.

260 IBM CICS Explorer

Figure 12-8 Append -data

An alternative way to provide different workspaces is to start explorer from a Microsoft Windows command prompt.

Chapter 12. WebSphere MQ plug-in 261

262 IBM CICS Explorer

Chapter 13. CICS Explorer troubleshooting

If a problem occurs with the CICS Explorer, you might be able to resolve it yourself. If you cannot resolve the problem yourself, you must gather the necessary information or documentation before contacting your IBM Support Center.

In this chapter, we describe some of the most common errors that are experienced with the CICS Explorer. Also, we explain where the CICS Explorer stores diagnostic data and how this data can be displayed or collected prior to calling IBM Support.

Table 13-1 lists some of the known connection problems. Although this is not a comprehensive list, these are some of the more common problems.

Table 13-1 Common connection problems CNX Messages Description Section

CNX0104E Connection failed with exception NOTAVAILABLE, 5.1.1 CPSMAPI

CNX0104E Connection failed with exception The markup in the 5.1.2 document preceding the root element must be well-formed

CNX0104E Connection failed with exception The element type 5.1.3 “HR” must be terminated by the matching end tags

CNX0106E Connect failed with error Forbidden 5.1.4

13.1.1 Connection not available, CPSMAPI

The CICS Explorer is attempting to connect using the System Management Single Server (SMSS) connection. The Explorer fails with the message in Figure 13-1 on page 265.

264 IBM CICS Explorer

Figure 13-1 CNX0104E Connection failed with exception NOTAVAILABLE, CPSMAPI

With this error there are a few things you must verify: Is the SMSS active in the CICS region? If you view the JESMSGLG, you will want to see the following messages: – EYUX0001I applid SMSS initialization program starting – EYUXL0003I applid CPSM Version 410 SMSS startup in progress – EYUXL0022I applid SMSS Phase I initialization complete – EYUXL0007I applid SMSS Phase II initialization complete – EYUNL0099I applid SMSS SMSS LRT initialization complete

Also, make sure the TCPIPServices and URIMAP are created and installed. You can check MSGUSR in the CICS SMSS region to confirm this. Additionally, make sure SEYUAUTH or SEYULOAD are included in your start-up JCL. If it is not, the Explorer will fail with the same CNX0104E error

Chapter 13. CICS Explorer troubleshooting 265 message in Figure 13-1 on page 265. Ensure that SEYULOAD is in DFHRPL, and not in the STEPLIB.

13.1.2 Connection must be well-formed

The CNX0104E message, Figure 13-2, can have multiple reason why it is generated.

Figure 13-2 CNX0104E Connection failed with exception... element must be well-formed

The error might be because the CICS Explorer is trying to connect to a CICS region with a TCP/IPService port of 9037. The failure occurs because the URIMAP, with path /CICSSystemManagement/*, installed does not reference the TCP/IPService of port 9037. Figure 13-3 shows that there is a mismatch in the TCP/IPSerivce name (EXPLORER and XPLORER).

Figure 13-3 Mismatch in the TCP/IPService name

266 IBM CICS Explorer Another potential reason for this error to occur is because of the CICS-Supplied Group DFHWU not being installed. This supplied group contains the resource definitions for CICS Management Client Interface (CMCI), and therefore, it is essential for it to be installed. Figure 13-4 shows DFHWU is installed in the region.

Figure 13-4 Installed Supplied Group DFHWU

13.1.3 Connection missing

tag

When the message in Figure 13-5 on page 268 is displayed, the connection type is set for CMCI, but the specified port number that is being used applies to the CICSPlex SM Data Interface. Ensure that you are using the correct port number for the connection type you are trying to establish.

Chapter 13. CICS Explorer troubleshooting 267

Figure 13-5 CNX0104E Connection failed with exception...

Figure 13-6 shows the correct port number for each of the two interfaces.

Figure 13-6 Port numbers the connection types use

13.1.4 Connection error forbidden

A connection is attempting to be made with the CMCI to a single CICS region; however, this region is contained within a CICSPlex environment. The error in Figure 13-7 on page 269 is displayed.

268 IBM CICS Explorer

Figure 13-7 CNX0106E Connect failed with error Forbidden

Because there are multiple regions within a CICSPlex environment a single connection cannot be made to this CICS region. For this connection to be successful, you must remove this single CICS region from the CICSPlex environment.

If none of the errors or messages pertain to your problem, or you cannot correct your problem, the next step is for you to contact IBM Support to further investigate the issue. The remaining sections of this chapter explain where the diagnostic data is located and what information/data to collect prior to contacting IBM Support.

13.2 Workspace and logs

The CICS Explorer uses a folder, known as the workspace, to save all of its settings between user sessions and to store a log of its activity, including any errors that might occur.

On Microsoft Windows operating systems, the default CICS Explorer workspace is located at: C:\Documents and Settings\\ .cicsexplorer

On Linux operating systems, the default CICS Explorer workspace is located at: /home//.cicsexplorer

Chapter 13. CICS Explorer troubleshooting 269 If you are not using the default settings but are starting the CICS Explorer with the -data command line (or shortcut on Microsoft Windows operating systems) option to use an alternate workspace location, you probably already know what workspace folder you are using.

The workspace folder contains, among other data, two logs: The Eclipse log is where errors, which are internal to the Eclipse platform that the CICS Explorer uses, can be recorded. It is contained in the file: /.metadata/.log This log is accessible from the UI (See 13.2.4, “Viewing the error log in an external application” on page 273). The IBM CICS Explorer’s own set of tracing files: /.metadata/.cicsexplorer.trace.NN.log

IBM CICS Explorer’s tracing files: There might be up to 10 files like this one with NN=0 for the most recent to NN=9 for the oldest one and up to 1 MB in size each.

13.2.1 Capturing trace data

When the CICS Explorer is running it is constantly recording trace information in its trace buffers. If there is an unexpected failure, the CICS Explorer automatically writes the trace information out to the error log to help identify the cause of the failure. You can force the current information in the trace buffers to be written to disk using the Explorer  Trace  Flush menu option.

The tracing information is written to disk in the set of tracing files /.metadata/.cicsexplorer.trace.NN.log.

Because the tracing facility is built using the standard Java logging API, the same tracing information can also be sent to a custom Handler, which you can achieve by launching the CICS Explorer with a command line (or shortcut on On Microsoft Windows operating systems), such as: cicsexplorer -vmargs -Djava.util.logging.config.file=myfile

In the example, myfile, is the name of a Java Properties file that is written according to the Java logging API.

The myfile configuration can, for instance, specify additional FileHandlers with different formatting or filtering than the default tracing; however, this is likely to have a detrimental performance effect if buffering is not adequate.

270 IBM CICS Explorer 13.2.2 Tracing options

The default tracing granularity is adequate, but it can be further enhanced:

1. Create a text file, and in the same directory where the CICS Explorer executable file resides, name it .options. 2. Inside the text file, add the lines that IBM service requests, as shown in Example 13-1.

Example 13-1 Options text file #Example .options file for CICS Explorer # com.ibm.cics.core.ui/general=true com.ibm.cics.core.ui/selection=false com.ibm.cics.core.ui/draganddrop=false com.ibm.cics.core.ui/resources=false com.ibm.cics.core.ui/connection=false com.ibm.cics.core.ui/adapters=false com.ibm.cics.core.ui/preferences=false com.ibm.cics.core.ui/decorators=false com.ibm.cics.core.ui/properties=false # com.ibm.cics.core.model/general=true com.ibm.cics.core.model/selection=false com.ibm.cics.core.model/resources=false com.ibm.cics.core.model/adapters=false # com.ibm.cics.core.ui.editors/markWithColors=false com.ibm.cics.core.ui.editors/controls=false com.ibm.cics.core.ui.editors/bindings=false com.ibm.cics.core.ui.editors/propertysheet=false com.ibm.cics.core.ui.editors/actions=false # com.ibm.cics.model/attributes=false # com.ibm.cics.sm.comm/general=true com.ibm.cics.sm.comm/record=false # com.ibm.cics.sm.comm.cpsm/general=true

3. To use the .options file, start the CICSExplorer with the command line option -debug.

Chapter 13. CICS Explorer troubleshooting 271 On Microsoft Windows operating systems, instead of using a command prompt window, you can append the -debug option to a shortcut created for the CICS Explorer executable.

Another alternative to specifying a command line option, on all the platforms, is to

edit the cicsexplorer.ini file.

File backup: Saving a cicseplorer.ini file that contains syntax errors or is missing essential options, can cause CICS Explorer to fail to start. Create a back up of the file before you edit it.

13.2.3 The Error Log View

The Error Log View displays information messages, warnings, and errors that the CICS Explorer logs. The underlying log file is where errors that are internal to the Eclipse platform that the CICS Explorer uses, can be recorded. It is contained in the file:

/.metadata/.log

The Error Log View is accessed from the Window  Show View  Error Log menu option.

The Error Log View is provided for information only. Figure 13-8 shows information messages and error messages. The error messages are simulated for this example because typically the log does not contain errors. If the view contains errors, contact your IBM Service representative for advice.

Figure 13-8 Error Log View

The CICS Explorer help contains a detailed description of the sorting, filtering, and export capabilities of the Error Log View.

272 IBM CICS Explorer 13.2.4 Viewing the error log in an external application

You can view the Eclipse log in an external application, such as a text editor or a

browser. 1. From the menu bar, click Help  About IBM CICS Explorer. The About IBM CICS Explorer window is displayed, as shown in Figure 13-9.

Figure 13-9 About IBM CICS Explorer

2. Click Configuration Details. The Configuration Details view is displayed, as shown in Figure 13-10 on page 274.

Chapter 13. CICS Explorer troubleshooting 273

Figure 13-10 Configuration Details window

3. Click View Error Log. You are presented with a list of programs that can be used to open and display the log. 4. Select a text editor or browser from the list, and then click OK.

The Configuration Details is a comprehensive set of information about your CICS Explorer installation that can be of great help to IBM Service when an error report is submitted.

274 IBM CICS Explorer 13.3 Preparing error data for IBM service

If you have a problem with the CICS Explorer, you might be asked to send the error logs and other information to the IBM service representative. The CICS Explorer collects all necessary error information in a single-compressed file that is ready for sending.

To prepare error data for IBM service: 1. From the workspace menu bar, click Explorer  Trace  Collect Service Data. 2. In the Save Service data as file dialog, select the location where you want to save the compressed file, and click Save.

The service data is saved as a compressed file. The filename is in the format CICSExplorerServiceData-20090701-080311.zip, where the numbers indicate the date and time of the collected data.

The zip file contains all of the diagnostic information that we described so far: Eclipse log CICS Explorer traces Configuration details

It also contains the CICS Explorer configuration settings, such as your defined connections and the set of columns to display in the resource views. It does NOT contain your saved passwords, which are stored encrypted on disk.

Remember to record the actions that you were performing at the time the failure occurred, which assists the IBM service representative if the problem requires further analysis.

13.3.1 Collecting error data when the CICS Explorer is not usable

If you cannot use the CICS Explorer user interface to collect service data, for example, because of a start up failure or because the user interface is unresponsive, you can at least create an archive file (for example in zip format on Microsoft Windows and in tar format on Linux) of all the traces, logs, and settings. This archive file does not include the comprehensive Configuration details that are available through the user interface.

Simply use an archiving utility to collect the directory content of your workspace location.

Chapter 13. CICS Explorer troubleshooting 275 You might want to remove the file where the passwords are stored because although they are encrypted, they can be recovered:

/.metadata/.plugins/com.ibm.cics.eclipse.common/com.ibm.cics .core.ui.secure_storage

If the user interface is up but hanging and unresponsive, creating a Java Thread Dump might be useful.

Creating a Java Thread Dump on Linux: 1. Obtain the process ID of the CICS Explorer using any system tool, for example, from a shell (command line) enter: $ ps -ef | grep cicsexplorer 2. From a shell, invoke kill -QUIT , and a file named javacore.YYYYMMDD..txt is created in the CICS Explorer directory. 3. Add the file to the archive that contains the workspace data.

Creating a Java Thread Dump on Windows: 1. The CICS Explorer must have been started with the -consolelog parameter, which in addition to the graphical UI window, also opens a shell (command line) window only for output. 2. If a dump was not taken, enter the key combination CTRL-BREAK from that command line window to request a dump. 3. From the console log window, you will see a message that includes the location and name of the dump that you send to IBM, for example: JVMDUMP010I Java dump written to C:\...\CICS Explorer\javacore.20090610.092732.6908.0001.txt 4. Add the file to the archive that contains the workspace data.

13.3.2 Searching for IBM MustGather information

The IBM support website contains additional documentation for preparing data for service. You can search the IBM website for CICS Explorer MustGather.

13.4 Plug-in specific issues

In this section, we describe special cases that affect the plug-ins.

276 IBM CICS Explorer 13.4.1 Performance Analyzer

In this section, we discuss the Performance Analyzer.

CSV file corruption It is critical that the csv file that is used in the PA plug-in was created by the PA runtime and was not modified in any way. Unfortunately, this includes a situation when a csv file is viewed using Excel. Excel restructures the time field in a manner that makes it relatively unusable by the PA plug-in. If when the application is closed Excel offers to save updates even though none were knowingly made, the file is corrupted and must be downloaded from the server again.

13.4.2 CSV file size and CICS Explorer runtime memory

The CSV file is held in java memory and is therefore restricted by factors that are external to the Explorer, including system memory. If you are using csv files, this might cause OutOfMemory Exceptions when an inadequate Java heap size is allocated. There is no hard rule to what needs to be allocated and many users find that the default maximum heap size is perfectly sufficient. However, it might be necessary in some circumstances to increase the value: 1. In a Windows or Linux command line, change the directory to the directory where the cicsexplorer.exe (cicsexplorer on Linux) file is located. 2. Start the CICS Explorer by typing the following command: cicsexplorer -vmargs -Xmx512m 3. Alternatively, you can modify the cicsexplorer.ini file in the CICS _Explorer subdirectory to add the following information: – -vmargs –-Xms128m –-Xmx512m 4. Start the CICS Explorer as normal.

Chapter 13. CICS Explorer troubleshooting 277

278 IBM CICS Explorer

Part 2

Part 2 Scenarios

In this part, we cover the following scenarios: MQ application migration CICS resource cleanup CICS Performance CICSPlex SM enablement using the CICS Explorer CICS resource manipulation

280 IBM CICS Explorer

Chapter 14. CICS Explorer - MQ application migration

In CICS TS V3.2, MQ calls are now run on the open L8 TCB; therefore, you must be aware of the MQ applications that you have and the implication of defining the programs as THREADSAFE.

In this chapter, we show how you can use the CICS Explorer and CICS Tools plug-ins to assist you in identifying MQ applications to migrate from CICS TS V3.1 to CICS TS V4.1. The same benefits can be obtained if migrating to CICS TS V3.2.

We use: The CICS IA and CICS CM plug-ins to identify MQ applications that can benefit from migrating to CICS TS V4.1. The CICS IA plug-in to investigate threadsafe requirements. The CICS PA plug-in to view before and after performance measurements.

We also show the integration between the plug-ins themselves and the base CICS TS Explorer.

In this section, we use the CICS IA plug-in to identify programs and transactions that contain MQ commands. We assume that you captured CICS IA data collector data with the ‘Detailed’ option on for ‘Programs’ and that we collected ‘Command flow’ detail for transaction MAIL.

For more information about data collection in CICS IA, refer to the CICS IA V3.1 User Guide, SC34-6992-00.

Before using the CICS IA Explorer plug-in, first ensure that you are connected to the CICS IA database. See 3.5, “Using plug-ins” on page 73 in Chapter 3 Implementing CICS Explorer.

Selecting the IA perspective To select the IA perspective: 1. After you are connected go to the CICS IA perspective, from the Explorer select Window  Open Perspective  Other  CICS IA. See Figure 14-1.

Figure 14-1 Open IA Perspective

2. In the IA perspective, create a new query to identify transactions and programs that use MQ resources. Select the Queries folder, right-click the MQ folder, and select New  MQ Query, as shown in Figure 14-2 on page 283.

282 IBM CICS Explorer

Figure 14-2 Create a new MQ query

3. Press Enter, and select the query name, the columns to show, and the filter criteria, as shown in Figure 14-3.

Figure 14-3 MQ Query edit panel

Chapter 14. CICS Explorer - MQ application migration 283 4. Select OK to save the query, and then run the query, as shown in Figure 14-4.

Figure 14-4 Run the MQ Query

The results of the query are shown in the resources folder, as shown in Figure 14-5 on page 285.

284 IBM CICS Explorer

Figure 14-5 Results of the MQ query

We have one transaction, MAIL, in region IYDZEJ0B. To migrate this transaction and the associated resources we must obtain more information before using the CICS CM plug-in.

14.2 Obtaining more information about the MAIL transaction

The CICS IA exits can collect detailed information about a number of resources, which include: CICS Applid Transactions Programs Exits TSqueues TDqueues Webservices Files

Chapter 14. CICS Explorer - MQ application migration 285 For more information about data collection in CICS IA, refer to the CICS IA V3.1 User Guide, SC34-6992-00.

To show the detailed information, we must turn on the Properties View. Select Window  Show Property View, as shown in Figure 14-6.

Figure 14-6 Select property view

A new view is displayed in your perspective and it is populated when ever you select a resource type for which detailed information is captured. In Figure 14-7, we selected the applid, IYDZEJ01.

The CICS region uses a CSD file called REDTOOLS.REDDEV31.DFHCSD, which we use later when we look at the CICS CM plug-in.

Figure 14-7 Detail view for APPLID IYDZEJ0B

We can also see the properties for a program, for example, in Figure 14-8 on page 287 we selected program TST4CVD1. For CICS TS V3.2 and above we show the Library database name and library.

286 IBM CICS Explorer

Figure 14-8 Program Properties view

We also must know what resources are used by transaction MAIL to migrate them to CICS TS V4.1: 1. Right-click the MAIL transaction, and select Uses Resource  Specific region, as shown in Figure 14-9 on page 288.

Chapter 14. CICS Explorer - MQ application migration 287

Figure 14-9 Show resource to transaction MAIL

2. Select region IYDZEJ0B, as shown in Figure 14-10.

Figure 14-10 Select region IYDZEJ0B

The results are shown in the Uses view, as shown in Figure 14-11 on page 289.

288 IBM CICS Explorer

Figure 14-11 Resources used by transaction MAIL

Notice that there are a number of resources used by the MAIL application. For more information about how to navigate the Uses view, refer to Chapter 6, “CICS Explorer IA plug-in familiarization” on page 137.

We gathered the information that we require for using the CICS PA plug-in.

Chapter 14. CICS Explorer - MQ application migration 289 14.3 Locating the MQ Application in CICS CM

Now that we identified our MQ application, we can use the CICS CM plug-in to search for its resource definition. In this example, our application consists of: One transaction: –MAIL Five programs: –TST4CVD1 –TST4CVD2 –TST4CVD3 –TST4CVD4 –TST4CVD5

Before using the CICS CM Explorer plug-in, first ensure that you are connected to the CICS CM server. See 3.5, “Using plug-ins” on page 73.

To locate the MQ Application in CICS CM: 1. Select the CM perspective, and from the Explorer select Window  Open Perspective  Other  CICS CM. 2. First we must select a configuration to work with. From CICS IA we know that the CSD in use is REDTOOLS.REDDEV31.DFHCSD. We must select this configuration in the CICS CM perspective. In the Configurations view, select the configuration for CSD REDTOOLS.REDDEV31, as shown in Figure 14-12.

Figure 14-12 Select configuration

290 IBM CICS Explorer 3. To search for a resource, click the torch in the top left corner of your perspective, as shown in Figure 14-13, and enter the resource name for MAIL.

Figure 14-13 Search for MAIL

4. The results of the search are displayed in the Search Results. To show the group, click Show Groups, as highlighted in Figure 14-14. We can see that transaction MAIL is in MAILGRP.

Figure 14-14 Results of the search

5. We now need to look at what other resources are stored in this group. Right-click the group, and select Show all resources, as shown in Figure 14-15 on page 292.

Chapter 14. CICS Explorer - MQ application migration 291

Figure 14-15 Show all resources for group MAILGRP

The results are shown in the same view, as shown in Figure 14-16.

Figure 14-16 All resources in group MAILGRP

We have now established what resource group we need to migrate to CICS TS V4.1. We can now use the CICS CM ISPF to package and migrate this group to our CICS TS V4.1 development region. For more information about using change packages, refer to the CICS CM User Guide, GC34-7048-00.

292 IBM CICS Explorer 14.4 Looking at performance data for the MAIL transaction

Before migrating the MAIL application, we used CICS PA to gather performance data on the CICS region REDDEV31. For more information about collecting CICS PA performance data, read the CICS PA User’s Guide, SC34-7046-01.

14.4.1 Performance data for MAIL on CICS TS V3.1

For a given transaction, you can link to the CICS PA performance data from the IA or CM perspective. In the following example, we go from the CM perspective: 1. In the Search Results view, right-click the MAIL transaction, and select Performance History  CPU Time, as shown in Figure 14-17.

Figure 14-17 LInk to Performance Data from CICS CM

2. A Restrict analysis time period is displayed. Select the date and time, as shown in Figure 14-18 on page 294.

Chapter 14. CICS Explorer - MQ application migration 293

Figure 14-18 Select date and time options

3. After you select the time range, click OK. You should now see a graph similar to the one in figure Figure 14-19 on page 295.

294 IBM CICS Explorer

Figure 14-19 CICS PA CPU time for transaction MAIL in REDDEV31

4. For more information, double-click any of the columns, and then maximize the

view. Figure 14-20 on page 296 shows the Threadsafe report for transaction MAIL. As you can see from Figure 14-20 on page 296, you can choose other report types, such as CPU time or response times.

Chapter 14. CICS Explorer - MQ application migration 295

Figure 14-20 Detailed report for transaction MAIL in REDEV31

Notice that our MQ Mail transaction in REDEV31 runs in the QR mode only.

296 IBM CICS Explorer 14.4.2 Performance data for MAIL on CICS TS V4.1

We migrated the MAIL application to CICS TS V4.1 on region REDEV41. We

must collect new PA and IA data for this region.

For CICS IA, we also captured Command Flow data for transaction MAIL.

We now return to the IA perspective and look at the MAIL transaction in region REDEV41: 1. Select the IA perspective, and in the ‘regions’ folder, select the transactions used in region IYDZEJ02, as shown in Figure 14-21.

Figure 14-21 Select transaction in region IYDZEJ02

2. In the Transactions folder, in the input area enter M* to show only transactions that start with M*, as shown in Figure 14-22 on page 298, which also shows the properties for region IYDZEJ02. We can see that it is a CICS TS V4.1 region, and the CSD is called REDTOOLS.REDDEV41.DFHCSD.

Chapter 14. CICS Explorer - MQ application migration 297

Figure 14-22 Transactions folder

3. We now look at some CICS PA data for the MAIL transaction in region REDDEV41. This time we link from the IA perspective. Right-click the MAIL transaction, and select Performance History  CPU time, as shown in Figure 14-23.

Figure 14-23 Show PA data for transaction MAIL in CICS TS V4.1

4. Enter the date and time for the CICS PA collection in region REDDEV41, and then double-click the instance to obtain the threadsafe report, as shown in

Figure 14-22.

298 IBM CICS Explorer

Figure 14-24 Threadsafe report for MAIL transaction in CICS TS V41

We can now see that the MAIL transaction spends nearly half of its time on an open L8 TCB, which reduces the time on the QR TCB.

We can also see 46 TCB mode switches. We now need to ask the following question:

Can we reduce the amount of TCB mode switches?

To answer this, we must understand the resources and commands that are issued by the MAIL transaction. We also must know how the transaction is currently defined.

Chapter 14. CICS Explorer - MQ application migration 299 14.5 Can we make the MAIL transaction threadsafe

First we obtain how the MQ programs that are associated with the MAIL application are defined. In particular, we are interested to see the ‘Concurrency’ value for the programs. We use the base CICS Explorer to look at the attributes of these programs: 1. Select the default CICS SM perspective. We explain how to connect to the base server in Chapter 2, “Getting started with CICS Explorer” on page 19. 2. In the CICS Explorer view, select region REDDEV41, as shown in Figure 14-25.

Figure 14-25 Select region REDDEV41

3. Select the transaction view with a filter of M*, as shown in Figure 14-26.

Figure 14-26 Transaction view

4. Before looking at CICS IA data, we can look at the program attributes for program TST4CVD1. Right-click the entry for transaction MAIL, select Open Related  Program, as shown in figure Figure 14-27 on page 301.

300 IBM CICS Explorer

Figure 14-27 Show program attributes

The program attributes are displayed, as shown in figure Figure 14-28 on page 302.

Chapter 14. CICS Explorer - MQ application migration 301

Figure 14-28 Program details for TST4CVD1

We can see that the program is defined with a concurrency of QUASIRENT.

To ascertain whether we can define the programs that are associated with MAIL as THREADSAFE, we can now use CICS IA: 1. We can link to the CICS IA data and view resources that are used by this transaction from the Transaction view. Right-click the transaction mail, and select Dependencies  Uses Resources, as shown in figure Figure 14-29 on page 303.

302 IBM CICS Explorer 2. Alternatively, we can open the CICS IA perspective and interrogate the IA data from there, as we described in “Using the CICS IA Command flow feature” on page 305.

Figure 14-29 Select CICS IA resource view

3. You can now see a Uses View with resource information for the MAIL transaction collected by the CICS IA product. You can expand the Resources Used view to show the resource names and commands, as shown in figure Figure 14-30 on page 304.

The first task when looking for programs that we can make threadsafe is to look for shared resources, such as the CWA. In an open TCB environment, multiple tasks can potentially access shared resources simultaneously, which could lead to loss of data integrity. We must examine the MAIL application programs to ensure that they do not use any of the following CICS commands: ADDRESS CWA EXTRACT EXIT GETMAIN SHARED

As shown in Figure 14-30 on page 304, for installations that have an application standard that allows the use of assembler data tables as a form of shared storage, add:

LOAD PROGRAM

Chapter 14. CICS Explorer - MQ application migration 303

Figure 14-30 CICSIA resource view in the CICS SM perspective

In the case of the MAIL application, we can see that it consists of only four programs, as shown in figure Figure 14-31.

We can see from Figure 14-31 that there are no CWA, EXIT, or STORAGE resources.

Figure 14-31 Programs used

We can fully expand the program calls to look for any LOAD commands, as shown in Figure 14-32 on page 305. You see that some of the programs have a

304 IBM CICS Explorer ‘blank’ command that indicates that the program was started as a result of a transaction start, and the transaction was MAIL.

Figure 14-32 Program commands

So by exploring the MAIL transaction, we can ascertain that it is a good candidate to be made threadsafe because it contains MQ commands, and it has no shared resources.

In the next section, we use the CICS PA plug-in to review the performance data after making the MAIL programs THREADSAFE.

Using the CICS IA Command flow feature In CICS IA V3.1, we provide a new feature to capture CICS API and APIs, MQ calls, IMS calls, and DB2 calls in chronological order. For information about how to capture command and load command flow data, refer to the CICS IA User Guide. To use the CICS IA Command flow feature: 1. From the Transactions folder, right-click the MAIL transaction, and select Show Command Flow runs, as shown in Figure 14-33 on page 306.

Chapter 14. CICS Explorer - MQ application migration 305

Figure 14-33 Select Command Flow runs

2. The Resources View is populated. Expand the tree for MAILTS41, as shown in Figure 14-34.

Figure 14-34 Command Flows for transaction MAIL

3. Right-click the TASKID, and select Show Execution, as shown in Figure 14-35 on page 307.

306 IBM CICS Explorer

Figure 14-35 Select Show Execution

A new Command Flow view is opened, as shown in Figure 14-36.

Figure 14-36 Command Flow view

The Command Flow view, Figure 14-36, consists of three sections: The left most section shows the commands that the TCB Modes use. In Figure 14-36, we show the commands used in the ‘L8’ TCB.

Chapter 14. CICS Explorer - MQ application migration 307 The middle section shows the commands that cause a TCB switch. In this case, we are looking at the commands that caused a switch from L8 back to QR. We can see that these are SEND maps and text.

The third right most view shows the execution tree itself. We can see here that transaction MAIL starts program TST4CVD1. If we select a command in either of the other views, it highlights this command in the execution tree. In this example, we selected the SEND CSQ4VD1 command in the TCB Mode Switches view. Notice in the execution tree that this SEND MAP occurs after an MQOPEN is running on TCB ‘L8’.

308 IBM CICS Explorer 14.6 Using CICS PA to analyze the (threadsafe) MAIL application

We use the Resource perspective to look at data stored in CSVs. You can store your data in a DB2 database. For more information about setting up the CICS PA data, refer to Chapter 8, “CICS Explorer PA plug-in familiarization” on page 191. 1. The CICS PA performance data collected after making the MAIL application threadsafe is stored in the REDTOOLS.MAIL41TH.CSV. We select this CSV file, as shown in Figure 14-37.

Figure 14-37 Select CSV file

You can expand each time slot further by region and the transaction, as shown in Figure 14-38 on page 310.

Chapter 14. CICS Explorer - MQ application migration 309

Figure 14-38 Select time and transaction

2. Select a CICS PA ‘CPU time’ report. Right-click the MAIL transaction, as shown in Figure 14-39.

Figure 14-39 Select CPU time report

A new folder for the ‘CPU time’ report is displayed, as shown inFigure 14-40 on page 311.

310 IBM CICS Explorer

Figure 14-40 CPU Time report for MAIL

3. For more information about a particular instance, right-click an entry, and select Detailed breakdown, as shown in Figure 14-41 on page 312.

Chapter 14. CICS Explorer - MQ application migration 311

Figure 14-41 Select Detailed breakdown

The Detailed breakdown shows us the ‘Threadsafe’ chart for the MAIL application after it is made threadsafe, as shown in Figure 14-22 on page 298.

Figure 14-42 Threadsafe chart for transaction MAIL

312 IBM CICS Explorer We can see from this chart that by making the MAIL programs threadsafe, we reduced the number of TCB switches from 46 to 18. We can also see that the application spends more time on the open L8 TCB, which frees up the QR TCB.

Chapter 14. CICS Explorer - MQ application migration 313

314 IBM CICS Explorer

Chapter 15. CICS Explorer clean up scenario

In this chapter, we discuss a scenario that shows the use of the CICS Explorer and CICS Tools plug-ins to analyze CICS resource definitions with a view to cleaning up or tidying these up.

In most CICS environments, whether it is development, test, or even production (in some cases), there are redundant definitions that remain on CSDs for years. Often, systems programmers were reluctant to delete any definitions because there was no easy way for them to determine if the definitions were occasionally used.

In this chapter, we show that with the help of the CICS Explorer and the plug-ins for CICS CM and CICS IA, you can quickly identify duplicate or orphaned resources and then obtain if they are in use now or if they were ever used.

We first look at how with using CICS CM, you can identify all orphaned groups of resources within one or more CSDs. To identify all orphaned groups of resources: 1. Using the CICS CM plug-in, first ensure that you are connected to the CICS CM server. See Figure 15-1 on page 316 for details. 2. Open the CICS CM perspective by clicking Window  Open Perspective  Other  CICS CM. Figure 15-1 shows the CICS CM perspective.

Figure 15-1 Selecting the CICS CM perspective

3. Within the CICS CM perspective, select the CICS CM configuration (CSD) that you want to work with. We select CSD REDCSD41.

Note: If you want to work with several configurations at a time, you can

select multiple configurations, including CICSPlex SM Contexts and CSDs.

Figure 15-2 on page 317 shows the CICS Explorer full screen with the CICS CM perspective.

316 IBM CICS Explorer

Figure 15-2 CICS CM perspective

4. Right-click, and select Cleanup  Show Orphaned Groups, as shown in Figure 15-3 and Figure 15-4 on page 318. This action populates the bottom right view with all of the orphaned groups within this CSD, as shown in Figure 15-5 on page 318.

Figure 15-3 Clean-up option

5. Let us look at orphaned group Mail. Click this group in the list of orphaned groups, and the history of changes to definitions in this group is populated in the middle pane, shown in Figure 15-5 on page 318.

Chapter 15. CICS Explorer clean up scenario 317 6. Expand each entry in the History View to see what changes were made to these resource definitions, including the create date and change date.

Figure 15-4 Orphaned Groups option

Figure 15-5 Orphaned groups in configuration REDCSD41

7. In the Resources View, select the Transaction Definitions tab, and the Mail transaction is displayed. Right-mouse click the Mail transaction definition, and select Dependencies  Uses Resources to seamlessly invoke CICS IA and see the resources used by this transaction and the call tree of program execution, as shown in Figure 15-6 on page 319.

318 IBM CICS Explorer

Figure 15-6 Resources used and call tree of program execution

8. We now invoke the CICS IA perspective for further analysis of this application. Click the CICS IA tab on the top right side of the perspective, which we show in Figure 15-6. 9. In the CICS IA perspective, click the Transactions tab, and specify a filter of M* in the box to narrow your search for this transaction, as shown in Figure 15-7 on page 320.

Chapter 15. CICS Explorer clean up scenario 319

Figure 15-7 Mail transaction in CICS IA perspective

10.Right-mouse click the Mail transaction, and select Show View and Transactions, as shown in Figure 15-8.

Figure 15-8 Show View and Transactions in the CICS IA perspective

We invoke the CICS SM perspective and determine which regions this application runs in.

320 IBM CICS Explorer In Figure 15-9, the view on the far right side of the perspective shows the CICS regions in which transaction MAIL is installed.

Figure 15-9 Details of regions in which the MAIL transaction is installed

11.From the CICS IA perspective, select Show Properties View, as shown in Figure 15-10.

Figure 15-10 Access the Show Properties view

Chapter 15. CICS Explorer clean up scenario 321 Figure 15-11 shows details about the First run and Last run of the transaction.

Figure 15-11 Details of First run and Last run of the transaction

By working through this scenario, we determined that the MAIL application group, although orphaned, is still used. The cleanup action here is to add the group to a grouplist for the relevant CICS region.

By working through the other groups in the list of orphaned groups and following the instructions in this section, we can quickly obtain if the groups are in use and then take the appropriate action.

322 IBM CICS Explorer 15.2 Duplicate resources

Another capability that the CICS CM plug-in provides is finding duplicate resources in a CSD or CICSPlex SM BAS repository. To find duplicate resources in a CSD or CICSPlex SM BAS repository: 1. From the CICS CM perspective, right-click the configuration that you want to work with. Select Cleanup  Show Duplicate Resources by Name and Type, as shown in Figure 15-12 and Figure 15-13.

Figure 15-12 Cleanup

Figure 15-13 Duplicate Resources by Name and Type

A list of resource definitions within groups that have duplicate resources of the same name and type within the repository is displayed, as shown in Figure 15-14 on page 324.

Chapter 15. CICS Explorer clean up scenario 323

Figure 15-14 Duplicate Definitions found

2. Expand each group, right-click a resource definition, and select Find  Similar resources to list all resources of the same name and type within the repository, as shown in Figure 15-15 on page 325.

324 IBM CICS Explorer

Figure 15-15 Finding similar resources

In Figure 15-16 on page 326, notice that the file ACCTFIL was found in three different groups.

Chapter 15. CICS Explorer clean up scenario 325

Figure 15-16 Duplicate file

3. From here you can right-click, and delete the file definition in group XXX, if you believe that this definition is not used. Figure 15-17 on page 327 shows an example of deleting a duplicate file.

326 IBM CICS Explorer

Figure 15-17 Delete a duplicate definition

4. When you select the Delete option, the Confirm Delete prompt is displayed, as shown in Figure 15-18. Click OK to delete the resource definition.

Figure 15-18 Delete confirmation

Chapter 15. CICS Explorer clean up scenario 327

328 IBM CICS Explorer

Chapter 16. CICS Explorer performance scenario

In this chapter, we discuss how you can use the CICS Explorer together with the CICS PA plug-in to navigate through the large amount of performance data that is available in a complex CICS configuration.

As we described in Chapter 8, “CICS Explorer PA plug-in familiarization” on page 191, using CICS Performance Analyzer for z/OS V 3.1 you can create performance data extracts in the form of CSV files or DB2 tables. These data extracts are typically for a subset of the large amount of SMF data that is recorded in most CICS installations.

By using the CICS Explorer, you can identify CICS system level performance problems without having to delve into large amounts of CICS monitoring and statistics data.

Using the CICS PA plug-in to analyze the data extracts that CICS PA creates you can create charts and reports that can help to identify performance bottlenecks within specific transactions.

The CICS Explorer provides a number of alerts for performance problems at the system level, such as: Short on Storage System dump in progress Transaction dump in progress System has reached MAXTASKS limit Tasks stalling because of resource contention

In Figure 16-1, we create a Short on Storage condition using transaction SOS7, which GETMAINs large amounts of CICS DSA.

After running the transaction, we immediately see the alert in the CICS Explorer view, as shown in Figure 16-1.

Figure 16-1 SOS Condition

330 IBM CICS Explorer If we invoke the Operations and Tasks view and specify a Transaction name filter of SOS7, we can display the status of this task, as shown in Figure 16-2.

Figure 16-2 Status of task

Right-click the task to select the option to Purge, Force Purge, or Kill the task, as shown in Figure 16-3.

Figure 16-3 Options to remove the task causing SOS

Chapter 16. CICS Explorer performance scenario 331 We tried the Purge option and received the response in Figure 16-4.

Figure 16-4 Purge response

We then used the Force Purge option, and the task was purged successfully. The SOS condition was rectified as confirmed by the Event view in the CICS Explorer.

To investigate the problem further, you can click the Transactions tab in the CICS Explorer and look at the attributes of the SOS7 transaction. We double-clicked transaction SOS7 and could see all of the runtime attributes of this transaction, as shown in Figure 16-5 on page 333.

332 IBM CICS Explorer

Figure 16-5 Runtime attributes of transaction SOS7

Chapter 16. CICS Explorer performance scenario 333 16.2 Drilling down into transaction detail

To obtain further information about transaction SOS7, we right-click the transaction in the CICS CM perspective, and select Dependencies  Uses Resources, as shown in Figure 16-6.

Figure 16-6 Finding details of Resources used

The CICS IA perspective is invoked and provides further details about this transaction. As shown in Figure 16-7 on page 335, transaction SOS7 runs program REDTSOS7, which issues a number of API commands including a GETMAIN.

334 IBM CICS Explorer

Figure 16-7 Detailed view of transaction SOS7

To look at the performance profile for this transaction, from the CICS CM perspective and the Transaction view, right-click transaction SOS7, and select Performance history  Storage.

Looking at the transaction detail, we can see that the EUDSA high-water-mark was reached four times, and the ECDSA high-water-mark was reached five times.

Figure 16-8 on page 336shows the storage usage detail for transaction SOS7.

Chapter 16. CICS Explorer performance scenario 335

Figure 16-8 Storage usage detail for transaction SOS7

Analyzing transaction performance

In this scenario, we provide an example of navigating through the CICS PA plug-in to analyze the performance characteristics of a transaction.

We first ensure that the connection from the CICS PA plug-in to the DB2 database that contains the CICS PA HDB data is active. See Chapter 8, “CICS Explorer PA plug-in familiarization” on page 191.

Next, we invoke the CICS PA perspective. We expand the CICS Explorer Redbooks System.cpa folder to see the dates on which SMF data was loaded into a CICS PA HDB and then exported to a DB2 table.

336 IBM CICS Explorer We want to analyze a set of transactions that executed on the 11th of June 2009, so we right-click the folder for this date, and select Sheet View. Figure 16-9 shows the Sheet View.

Figure 16-9 Invoke Sheet view

From the Sheet View, we can select a set of transactions for a particular date and time and start further analysis. To do this, we simultaneously press the Shift key and the Scroll Down key to select a set of transactions to analyze.

Having selected our set of transactions, we right-click and invoke other views to drill down into the performance profile for these transactions, as shown in Figure 16-10 on page 338.

Chapter 16. CICS Explorer performance scenario 337

Figure 16-10 Drilldown into performance analysis from the Sheet view

In our case, we wanted to start with details of response times for these transactions, so we click Response time to invoke the bar chart view for these transactions.

Looking at the response times for the MAIL transaction, we immediately see a significant difference in response times for this transaction during two separate time intervals.

338 IBM CICS Explorer By hovering the mouse cursor over the bars, we saw that the suspend time average during one interval was 14.531239 seconds and during another it was 8.996642 seconds.

Figure 16-11 shows the response times for the Mail transaction.

Figure 16-11 Response times for Mail transaction

By double-clicking each bar we can invoke the detail breakdown view. Then we select Response time to get the complete Response time breakdown for that interval.

As we can see from the detailed breakdown for the 10:10 am interval, the User Dispatch time was 0.026304 seconds and the suspend time was 14.531239

seconds, as shown in Figure 16-12 on page 340.

Chapter 16. CICS Explorer performance scenario 339

Figure 16-12 Response time breakdown for 10:10 interval

As we can see from the detailed breakdown for the 10:15 am interval, Figure 16-13 on page 341, the User Dispatch time was 0.015940 seconds and the suspend time was 8.996642 seconds.

From the detailed breakdown views, we can determine a lot of information about the performance profile for this transaction during the two intervals using the Threadsafe, CPU time, Storage, and File usage views if appropriate.

340 IBM CICS Explorer

Figure 16-13 Response time breakdown for 10:15 interval

To determine the cause of the long Suspend time during the 10:10 interval, we can look again at the Sheet View by clicking the appropriate tab.

As we can see from the Sheet View and by scrolling right to the “Terminal Control I/O wait time average” column the difference in Suspend time for the MAIL transaction for the two intervals is entirely due to Terminal Control I/O wait, as shown in Figure 16-14 on page 342.

Chapter 16. CICS Explorer performance scenario 341

Figure 16-14 Terminal Control I/O Wait details for MAIL transaction

To complete our analysis and to confirm our findings, we submit a Wait Analysis report using the CICS PA ISPF dialogue for the intervals that we looked at here.

The output from the wait analysis report confirms what we see in the CICS PA plug-in Sheet View. The large response time differences are due to differences in values for Terminal Control I/O waits for the two intervals we analyzed.

Example 16-1 shows the wait analysis for MAIL transaction at 10:00. Example 16-2 on page 343 shows the wait analysis for MAIL transaction at 10:15.

Example 16-1 Wait analysis for MAIL transaction at 10:00

Start=10:10:00 APPLID=IYDZEJ02 Tran=MAIL Interval=00:05:00 Summary Data ------Time ------Count ------Ratio ------Total Average Total Average # Tasks 65 Response Time 946.2403 14.5575

342 IBM CICS Explorer Dispatch Time 1.7098 0.0263 3650 56.2 0.2% of Response CPU Time 0.3530 0.0054 3650 56.2 20.6% of Dispatch Suspend Wait Time 944.5306 14.5312 3650 56.2 99.8% of Response Dispatch Wait Time 1.4515 0.0223 3585 55.2 0.2% of Suspend Resource Manager Interface (RMI) elapsed time 1.3208 0.0203 1625 25.0 0.1% of Response Resource Manager Interface (RMI) suspend time 0.0000 0.0000 0 0.0 0.0% of Suspend

Suspend Detail ------Suspend Time ------Count ----- Total Average %age Graph Total Average TCIOWTT Terminal wait for input time 943.1267 14.5096 99.9% |******************* 585 9.0 DSCHMDLY Redispatch wait time caused by change-TCB mode 1.2319 0.0190 0.1% | 2990 46.0 DSPDELAY First dispatch wait time 0.1243 0.0019 0.0% | 65 1.0 N/A Other Wait Time 0.0384 0.0006 0.0% | 8 0.1 TSIOWTT VSAM TS I/O wait time 0.0093 0.0001 0.0% | 2 0.0

Example 16-2 Wait Analysis for MAIL transaction at 10:15

Start=10:15:00 APPLID=IYDZEJ02 Tran=MAIL Interval=00:05:00 Summary Data ------Time ------Count ------Ratio ------Total Average Total Average # Tasks 140 Response Time 1261.7614 9.0126 Dispatch Time 2.2316 0.0159 7840 56.0 0.2% of Response CPU Time 0.7461 0.0053 7840 56.0 33.4% of Dispatch Suspend Wait Time 1259.5298 8.9966 7840 56.0 99.8% of Response Dispatch Wait Time 1.7214 0.0123 7700 55.0 0.1% of Suspend Resource Manager Interface (RMI) elapsed time 1.5895 0.0114 3500 25.0 0.1% of Response Resource Manager Interface (RMI) suspend time 0.0000 0.0000 0 0.0 0.0% of Suspend

Suspend Detail ------Suspend Time ------Count ----- Total Average %age Graph Total Average TCIOWTT Terminal wait for input time 1258.0697 8.9862 99.9% |******************* 1260 9.0 DSCHMDLY Redispatch wait time caused by change-TCB mode 1.3667 0.0098 0.1% | 6440 46.0 DSPDELAY First dispatch wait time 0.0934 0.0007 0.0% | 140 1.0

Chapter 16. CICS Explorer performance scenario 343

344 IBM CICS Explorer

Chapter 17. CICSPlex SM enablement using the CICS Explorer

One of the functions of CICSPlex SM is to implement dynamic workload management within CICS. In this chapter, we review the various factors that you must take into account when delivering such a solution. We also discuss how we can identify these solutions and address them using the CICS Explorer.

When a program or transaction in CICS uses an external resource, such as a file or temporary storage, this creates an affinity within the transaction to that resource. CICS Interdependency Analyzer gives us the ability to analyze affinity data. The affinity data is loaded into DB2 databases, on which you can perform SQL queries and from which you can produce detailed reports.

CICS transactions use many different techniques to pass data from one transaction to another. Some techniques require that the transactions that are exchanging data must execute in the same CICS region and therefore impose restrictions on the dynamic routing of transactions. If transactions exchange data in ways that impose such restrictions, there is said to be an affinity between them.

There are two categories of affinity: Inter-transaction affinity Transaction-system affinity

The restrictions on dynamic routing caused by transaction affinities depend on the duration and scope of the affinities. Clearly, the ideal situation for a dynamic routing program is for there to be no transaction affinity at all, which means there is no restriction in the choice of available target regions. However, even when transaction affinities do exist, there are limits to the scope of these affinities that are determined by the: Affinity relations Affinity lifetime

CICS IA cannot detect affinities in the following types of dynamically routed requests: Non-terminal-related START requests Distributed program link (DPL) requests Method requests for enterprise beans or CORBA stateless objects

For these types of dynamically routed requests, review your application to determine whether it is suitable for dynamic routing.

17.1.1 Inter-transaction affinity

An inter-transaction affinity is an affinity between two or more CICS transactions. It is caused by the transactions using techniques to pass information between one another or to synchronize activity between one another in a way that requires the transactions to execute in the same CICS region.

346 IBM CICS Explorer Inter-transaction affinities that impose restrictions on the dynamic routing of transactions, can occur in the following circumstances:

One transaction terminates, leaving “state data” in a place that a second transaction can access only by running in the same CICS region as the first transaction. One transaction creates data that a second transaction accesses while the first transaction is still running. For this to work safely, the first transaction usually waits on an event, which the second transaction posts when it has read the data that the first transaction created. This synchronization technique requires that both transactions are routed to the same CICS region.

17.1.2 Transaction-system affinity

A transaction-system affinity is an affinity between a transaction and a particular CICS region. It is caused by the transaction interrogating or changing the properties of the CICS region.

Transactions with an affinity to a particular CICS region, rather than to another transaction, are not eligible for dynamic transaction routing. Typically, they are transactions that use CICS SPI commands, such as EXEC CICS INQUIRE or SET or that depend on global user exit programs.

17.1.3 Affinity relations

When a transaction is associated with an affinity, the affinity relation determines how the dynamic routing program selects a target region for an instance of the transaction. An affinity relation can be classified as one of the following relations: Global A group of transactions in which all instances of all transactions in the group that are initiated from any terminal, or are BTS or Link3270 transactions, must execute in the same target region for the lifetime of the affinity. The affinity lifetime for global relations can be “system” or “permanent.” BAPPL All instances of all transactions in the group are associated with the same CICS Business Transaction Services (BTS) process. There might be many different user IDs and terminals that are associated with the transactions that are included in this affinity group. LINK3270 All instances of all transactions in the group are associated with the same Link3270 bridge facility.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 347 LUname A group of transactions in which all instances of all transactions in the group that are initiated from the same terminal must execute in the same target region for the lifetime of the affinity. The affinity lifetime for LUname relations can be “pseudoconversation,” “logon”, “pseudoconversational”, “system,” or “permanent.” UserID A group of transactions in which all instances of the transactions that are initiated from a terminal and executed on behalf of the same user ID must execute in the same target region for the lifetime of the affinity. The affinity lifetime for userID relations can be “pseudoconversation,” “signon,” “system,” or “permanent.”

17.1.4 Affinity lifetimes

The affinity lifetime determines when the affinity is ended. An affinity lifetime can be classified as one of: System The affinity lasts for as long as the target region exists and ends whenever the target region terminates (at a normal, immediate, or abnormal termination). The resource shared by transactions that take part in the affinity is not recoverable across CICS restarts. Permanent The affinity extends across all CICS restarts. (The resource shared by transactions that take part in the affinity is recoverable across CICS restarts.) This is the most restrictive of all the inter-transaction affinities. Process The affinity exists until the BTS process completes. Activity The affinity exists until the BTS activity completes. Facility The affinity exists until the Link3270 bridge facility is deleted. Pseudoconversation The (LUname or userID) affinity lasts for the whole pseudoconversation and ends when the pseudoconversation ends at the terminal. Logon The (LUname) affinity lasts for as long as the terminal remains logged on to CICS and ends when the terminal logs off. Signon The (userID) affinity lasts for as long as the user is signed on, and ends when the user signs off. Note that this lifetime is only possible in those situations where only one userID is permitted. Signon lifetime cannot be detected if

348 IBM CICS Explorer multiple users are permitted to be signed on with the same userID at the same time.

Note: If an affinity is both “userID” and “LUname” (that is, all instances of all transactions in the group were initiated from the same terminal and by the same user ID), “LUname” takes precedence.

17.2 Running CICS Interdependency Analyzer for affinities

In the first instance, we must run the collector component of CICS Interdependency Analyzer for z/OS against our candidate application. We chose a single application to analyze to prepare this for CICSplex enablment.

We need to set the correct parameters in the collector panel through the transaction CINT, as shown in Figure 17-1.

CIU290 CICS Interdependency Analyzer for z/OS - V3R1M0 2009/06/01 Resource Options for 09:28:10AM CICS Sysid: EJ02 CICS Applid: IYDZEJ02

Type action code then press ENTER:

1 = General Options 2 = Time/Date Options

Interdependency Options Affinity Options 3 = CICS Options for APIs 8 = Affinity Options 4 = CICS Options for SPIs 5 = DB2/IMS/MQ Options 6 = Task Options 7 = Natural Options

CICS Sysid: EJ02 CICS Applid: IYDZEJ02 TermID: TC47

F1=Help F2= F3=Exit F4= F5= F6= F7= F8= F9= F10= F11= F12=Exit

Figure 17-1 CICS IA CINT transaction

To set the collection for Affinity options, we much choose Option 8, which then displays the panel in Figure 17-2 on page 350.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 349 CIU270 CICS Interdependency Analyzer for z/OS - V2R2M0 2009/06/01 CICS Affinities Options for 09:44:56AM CICS Sysid : EJ02 CICS Applid : IYDZEJ02

Modify the options and press Enter to update, or PF12 to Cancel.

Detect affinity types: Y=Yes, N=No or blank=default

Inter-Transaction ENQ, DEQ . . . .. Y TS QUEUE . . . . Y ADDRESS CWA. . . Y RETRIEVE WAIT. . Y LOAD ...... Y GETMAIN SHARED . Y CANCEL . . . . . Y

Transaction-System INQUIRE, SET . . Y ENABLE, DISABLE. Y EXTRACT. . . . . Y COLLECT STATS . Y PERFORM . . . . Y RESYNC . . . . . Y WAIT ...... Y DISCARD . . . . Y CREATE . . . . . Y CSD ...... Y

CICS Sysid: EJ02 CICS Applid: IYDZEJ02 TermID: TC47

F1= F2= F3=Exit F4= F5= F6= F7= F8= F9= F10= F11= F12=Cancel

Figure 17-2 Resource options panel for CICS IA

From this panel, we can set the Affinity detection options on for both Inter-Transaction and Transaction System Affinities, which enables us to scope the amount of effort that is required to resolve any affinities. It is worth noting that you can resolve an affinity by making a system-related change, as opposed to an application-related change, for example, having to amend program code. One example of this is to move any queue related activity, for example, TS or TD, to a queue-owning region.

17.3 Loading the DB2 database with the collected affinity data

CICS Interdependency Analyzer provides you with a number of supplied jobs to load your collected data into the DB2 tables. The CICS IA Affinity data is loaded by the sample job CIUAFFLD, as shown in Example 17-1.

Example 17-1 CICS IA CIUAFFLD sample JCL

//CIUAFFLD JOB USER=JAMESE,NOTIFY=JAMESE,

350 IBM CICS Explorer // CLASS=A,MSGCLASS=Y,REGION=0M //* //* //********************************************************************* //* * //* JCL NAME = CIUAFFLD * //* * //* DESCRIPTIVE NAME = IBM CICS INTERDEPENDENCIES UTILITY * //* LOAD THE AFFINITY TABLES FROM AFFINITIY VSAM * //* FILES , CIUAFF1/2/3 * //* AFFINITY FILES CREATED BY CICS/IA * //* * //* CHANGES TO BE MADE * //* PLEASE CONSULT WITH YOUR DB2 ADMINISTRATOR * //* * //* 1) CHANGE THE JOB CARD TO SUIT YOUR SYSTEM CONVENTIONS * //* 2) CHANGE THE FOLLOWING PARAMETERS:- * //* * //* DG2F * //* THE DB2 ID * //* * //* CICSTS.CICS.IA.V31.INC38 * //* THE HLQ FOR CIU PRODUCT * //* * //* SYS2.DB2.V810.SDSNLOAD * //* THE DATASET HLQ FOR DB2 SDSNLOAD * //* * //* REDTOOLS.CICSIA * //* THE HLQ FOR THE CIA AFFINITY FILES. THESE FILES ARE * //* CREATE AS PART OF THE CICS AFFINITIES UTILITY * //* * //* 81 * //* FOR THE PLAN SHOULD BE REPLACED WITH THE FIRST 2 DIGITS * //* OF THE DB2 VERSION NUMBER * //* * //* DSN8102F.RUNLIB.LOAD * //* TO THE DATASET HLQ FOR DB2 RUNLIB.LOAD * //* * //* YOU MAY ALSO WISH TO REVIEW THE SCIUSQL(CIUSPCDB)MEMBER. * //* * //* 3) EDIT THE SCIUCLIS MEMBER CIUDB2BT AND CHANGE THE FOLLOWING:- * //* * //* ANTZ.CICS.IA.V31.INC38 * //* THE HLQ FOR CIA PRODUCT * //* * //* 4) IF YOU WISH TO UPDATE THE DATABASE WITH THE LAST USAGE * //* COUNTS THEN CHOOSE PARM(UPDATE) * //* * //* 5) You can load Affinities for a region by selecting an APPLID * //* Enter ALL for all APPLIDs or the APPLID to be loaded * //* No entry is treated the same as ALL * //********************************************************************* //********************************************************************* //* @start_copyright@ *

Chapter 17. CICSPlex SM enablement using the CICS Explorer 351 //* Licensed Materials - Property of IBM * //* * //* "Restricted Materials of IBM" * //* * //* 5697-J23 * //* * //* (c) Copyright IBM Corp. 2004, 2007 All Rights Reserved. * //* * //* US Government Users Restricted Rights - Use, duplication or * //* disclosure restricted by GSA ADP Schedule Contract with * //* IBM Corp. * //* @end_copyright@ * //********************************************************************* //* * //* CHANGE HISTORY * //* * //* PN= REASON REL YYMMDD HDXIII: REMARKS * //* ------* //* £L0= H274130 300 040601 hdej: Date Created * //* £P1= 00050 300 040725 hdej: Load affiniy data tables * //* £P2= 00079 300 040725 hdej: Set region to 0M * //* £P3= PK02704 300 050505 hdej: New affinity files * //* £P4= 00230 2100 050606 hdej: Update to CIUBTCH4 * //* £P5= 00244 2100 050628 hdej: Change CAU to CIU all * //* £L6= 00235 2100 050923 hdej: Add new jobcard. * //* £P6= 00363 2100 051003 hdej: COrrect EXEC in STEP00 * //* £P7= 00478 2100 051026 hdjah: Add DD for SCIULODE * //* £L7= 00806 2200 070516 hd-nsm: Add step - total number of rows * //* £P8= 00822 2200 070606 hd-mxs: Add DB2 plan customization * //* £P7= PK72394 2200 081002 hd-ej: New update for CIU_RESOURCE * //* £P8= 01158 2200 081216 hd-ej: Add SYSREC06 * //* £M1= 001189 3100 090128 hdej: Remove .SDSNLOAD and.RUNLIB.LOAD* //********************************************************************* //****************************************************************** //JCLLIB JCLLIB ORDER=DSN8102F.PROCLIB //JOBLIB DD DSN=ANTZ.CICS.IA.V31.INC38.SCIULOAD, // DISP=SHR // DD DSN=ANTZ.CICS.IA.V31.INC38.SCIULODE, // DISP=SHR // DD DSN=SYS2.DB2.V810.SDSNLOAD, // DISP=SHR // DD DSN=DSN8102F.RUNLIB.LOAD, // DISP=SHR //********************************************************************* //*------//* RUN THE BATCH PROGRAM CIUUREG //*------//STEP000 EXEC PGM=IKJEFT1B, // DYNAMNBR=20, // PARM=('%CIUDB2BT','SYS(DG2F)','PROG(CIUUREG)', // 'PLAN(REDIADD)') //*------//* IF YOU WISH TO UPDATE THE DATABASE WITH THE LAST USED //* TIME STAMP FOR EACH DB2 ROW THEN CHOOSE PARM(UPD)

352 IBM CICS Explorer //*------//SYSPROC DD DSN=REDTOOLS.REDTST41.SCIUCLIS, // DISP=SHR //SYSUDUMP DD SYSOUT=* //SYSTSIN DD DUMMY //SYSTSPRT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CIUCNTL DD DSN=REDTOOLS.CICSIA.CIUCNTL, // DISP=SHR //****************************************************************** //STEP010 EXEC PGM=IKJEFT1B, // DYNAMNBR=20, // PARM=('%CIUDB2BT','SYS(DG2F)','PROG(CIUAFFL1)', // 'PLAN(REDIADD)','PARM(UPDATE)') //* 'PLAN(REDIADD)') //*------//* IF YOU WISH TO UPDATE THE DATABASE WITH THE LAST USAGE //* COUNTS THEN CHOOSE PARM(UPDATE) //*------//SYSPROC DD DSN=REDTOOLS.REDTST41.SCIUCLIS, // DISP=SHR //SYSUDUMP DD SYSOUT=* //SYSTSIN DD DUMMY //SYSTSPRT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CIUAFF1 DD DSN=REDTOOLS.CICSIA.CIUAFF1, // DISP=SHR //CIUAFF2 DD DSN=REDTOOLS.CICSIA.CIUAFF2, // DISP=SHR //CIUAFF3 DD DSN=REDTOOLS.CICSIA.CIUAFF3, // DISP=SHR //CIUCNTL DD DSN=REDTOOLS.CICSIA.CIUCNTL, // DISP=SHR //* Enter ALL for all APPLIDs or the APPLID to be loaded //* No entry is treated the same as ALL //APPLID DD * /* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //*------//* RUN SQL QUERIES FOR DB2 TABLES //*------//CIUSPACE EXEC PGM=IKJEFT01 //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DG2F) RUN PROGRAM(DSNTEP2) PLAN(DSNTEP81) PARMS('/ALIGN(LHS) MIXED') - LIB('DSN8102F.RUNLIB.LOAD') END /* //SYSIN DD DSN=REDTOOLS.REDTST41.SCIUSQL(CIUSPCAF),

Chapter 17. CICSPlex SM enablement using the CICS Explorer 353 // DISP=SHR //*------//* UPDATE THE CIU_RESOURCE TABLE //*------//CIUUNLD EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSREC DD DUMMY //SYSTSIN DD * DSN SYSTEM(DG2F) RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB81) PARMS('SQL') - LIB('DSN8102F.RUNLIB.LOAD') //SYSPRINT DD SYSOUT=* //SYSPUNCH DD DUMMY //SYSUDUMP DD SYSOUT=* //SYSREC00 DD DSN=&&DATA0,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC01 DD DSN=&&DATA1,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC02 DD DSN=&&DATA2,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC03 DD DSN=&&DATA3,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC04 DD DSN=&&DATA4,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC05 DD DSN=&&DATA5,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC06 DD DSN=&&DATA6,DISP=(,PASS), // UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSPUNCH DD SYSOUT=* //SYSIN DD DSN=REDTOOLS.REDTST41.SCIUSQL(CIURSV8U), // DISP=SHR //*------//CIURLD EXEC DSNUPROC, // SYSTEM=DG2F, // UID='CIUAFFLD', // UTPROC='' //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTOUT DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTWK02 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTWK03 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTWK04 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SORTWK05 DD UNIT=SYSDA,SPACE=(CYL,(200,15),RLSE) //SYSREC00 DD DSN=&&DATA0,DISP=(OLD,DELETE) // DD DSN=&&DATA1,DISP=(OLD,DELETE) // DD DSN=&&DATA2,DISP=(OLD,DELETE) // DD DSN=&&DATA3,DISP=(OLD,DELETE) // DD DSN=&&DATA4,DISP=(OLD,DELETE) // DD DSN=&&DATA5,DISP=(OLD,DELETE) // DD DSN=&&DATA6,DISP=(OLD,DELETE) //SYSIN DD DSN=REDTOOLS.REDTST41.SCIUSQL(CIURSV8L), // DISP=SHR //

354 IBM CICS Explorer After the data is loaded into DB2, we can then use the CICS IA plug-in to view the affinities that were collected.

17.4 Using the CICS IA plug-in to identify affinities

After we have our data loaded into DB2, we can connect using the CICS IA plug-in to review all of the data that was collected. When we use the CICS IA perspective, as a default we should be presented with a panel that is similar to Figure 17-3.

Figure 17-3 CICS IA plug-in Supplies Samples queries

The Supplied Samples that are available in the CICS IA plug-in are displayed. We are interested in the Affinities folder under the CICS samples, so we expand that to see what queries are predefined for us, as shown in Figure 17-4 on page 356.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 355

Figure 17-4 CICS IA Supplied Sample Affinity queries

There is one particularly useful query to run, so we highlighed it. If we run that query as it stands, we should be presented with a list of programs that have affinity statements, as shown in Figure 17-5.

Figure 17-5 All programs with potential affinities

Now that we decided that we need to address the affinity issues, we must make decisions regarding the ability of the transactions to be CICSplex enabled.

First, we must understand what resource relationships our candidate programs are involved with. In Figure 17-6 on page 357, we can see that program DRIVERP has some transactions that are associated with it and another

356 IBM CICS Explorer program, a TSQUEUE, and another as yet unidentified resource. If we expand that display, we can see the full list of resources.

Figure 17-6 Affinities by program

We must address all of the affinity issues that are identified here, so to begin with, we want to make sure that we have all of the relevant resources that are required for this program to run successfully within a CICSplex. This lists additional transactions and an additional program. We must run the same exercise on the additional program to make sure that we covered all possibilities. If we look at program WORKP, Figure 17-7 on page 358, we can see that this program uses a TSQUEUE also. Fortunately for us, it is the same TSQUEUE that our DRIVERP program uses.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 357

Figure 17-7 Program WORKP affinities

The CICS IA collector derived this information from a running CICS region, and there might be some other commands that were not detected. In this case, it is recommended that you use the load library scanner component of CICS IA to run against the statically defined program to ensure that no commands were excluded during this exercise.

We have two affinity issues that we must address: ADDRESS CWA Our DRIVERP program uses the ADDRESS CWA command, and therefore we must examine the program further to see what type of access is used. If the CWA is being addressed in read-only mode, for example, to obtain the contents of a table, then we must ensure that the table is available to all of our target regions when we implement the workload. If you want to restrict write access to the CWA, you can specify CWAKEY=CICS, which means that CICS allocates the CWA from CICS-key storage, restricting application programs that are defined with EXECKEY(USER) to read-only access to the CWA. The only programs that are allowed to write to a CWA that is allocated from CICS-key storage are those programs that you define with EXECKEY(CICS). TSQUEUE AUX Again, if we write to temporary storage, we must determine if there is a requirement for that to be read by any other program that is executing as past of this workload. If that is the case, we can resolve this problem by one of two methods:

358 IBM CICS Explorer – Implementing a Queue Owning Region: To define a queue as remote you must include an entry for the queue in a temporary storage table (TST) or use an appropriate TSMODEL. TS queue names are frequently generated dynamically, but they can also be unique fixed names. – Defining a Share Temporary Storage Server: By defining Temporary Storage pools that reside in the Coupling Facility, the queues can be shared across a sysplex.

17.5 Workload management considerations

The easiest part of workload management is setting up the definitions and installing them. However, it is much more complex than that because we must understand the current configuration and what affect our changes will have on it. The first part is to decide where our dynamic workload is going to run. There is plenty of technical material that is available to help you make those decisions, so we do not go into detail here, but we summarize the steps in Figure 17-8.

VTAM Generic resource balancing

TOR/AOR TOR TOR TOR TOR

AOR AOR AOR AOR AOR

Existing Static Dynamic routing single TOR Dynamic routing multi TOR system routing

Figure 17-8 Dynamic routing exploitation

In Figure 17-8, we show (from left to right) the stages that we can go through to fully enable our transactions to be part of a dynamic workload. The stages are:

1. Existing System: This is where our transaction runs and accesses all resources that are local to the CICS region that the transaction(s) and program(s) are defined in.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 359 2. Static Routing: The transaction is defined with a remote attribute of Dynamic=NO in our Terminal Owning Region and is defined as Local in the Application Owning Region. The program is not normally defined in the TOR and defined as Local in the AOR. There is a RemoteSystem attribute set to the SYSID of the AOR and, optionally, a RemoteName attribute set if you want to run the transaction under a different name in the AOR. 3. Dynamic Routing Single TOR. The transaction is defined with a remote attribute of Dynamic=YES in our Terminal Owning Region and is defined as Local in the Application Owning Region. At this point, our target AORs were referenced by a TRANGRP definition within the Workload Management feature of CICSPlex SM.

17.6 Creating the definitions for workload management

After we decide that we have all of the relevant resources defined for our application, we must create definitions within CICSPlex SM so that we can exploit workload management. From CICS Transaction Server V3.2, the only method of creating and managing these definitions is through the CICSPlex SM Web User Interface.

CICSPlex SM uses a routing program to process all routing requests that are made to it. This program, EYU9XLOP, is specified in the System Initialization Table parameters DSRTPGM and DTRPGM for any CICS region that wants to participate in dynamic transaction routing.

Figure 17-9 on page 361 shows the elements that are required to define the workload management criteria for balancing, separation, and affinity processing.

360 IBM CICS Explorer

WLMSPEC TORS

Trangrp=(txns), affinity relations TRANGRP (Userid,luname,trangrp,processtype) =>AORSET

WLMDEF

AORS

Figure 17-9 Workload management model

The elements are: TRANGRPS These define the transactions that take place in dynamic routing and also their affinity relations. They are also used to define transactions for workload separation. WLMDEFS These specify workload and separation criteria. TrangrpName, LUname, Userid, and Process Type. WLMGROUP These are purely for administration purposes, for example, assigning WLMGRPS to specifications. WLMSPEC These define default routing criteria, the routing algorithm to be used, and whether abend avoidance is activated (diverts workloads from a region if it is deemed to be unstable). The workload criteria are made known to the relevant regions by association of the WLMSPEC to the region, usually through a System Group.

Figure 17-10 on page 362 shows Transactions in Transaction Groups.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 361

Figure 17-10 Transactions in Transaction Groups

In this group, Figure 17-10TXNGRP, we defined the six transactions that are part of our application. They can now be associated with target AORs by defining the relationship to the WLMGROUP and the WLMSPEC.

17.7 Migrating the definitions using CICS Configuration Manager

Now that we selected our application for CICSplex enablement, we must migrate the selected definitions from our existing single region into their target regions. If we look at the resources, Figure 17-11 on page 363, that are being used by our candidate application, we can then prepare them to be migrated.

362 IBM CICS Explorer

Figure 17-11 Resources captured

We can see that our application is going to require a number of programs, some mapsets, and then we have three datasets that must access from each region that the application runs in. Our decision on the datasets is to use a file-owning region so that our definitions must be migrated, which changes the attributes to remote.

From this information, we can prepare a package to be migrated in CICS Configuration Manager. To do this, we must select the resources that are identified by the data that we collected in CICS Interdependency Analyzer. These resources are then placed into a package, ready to be migrated between differing environments.

Figure 17-12 on page 364 shows the resource packaging.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 363 File Menu Settings Help ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss List - All resources Change Package TXNGRP Row 1 to 8 of 8 Command ===> Scroll ===> PAGE

To prepare Scheme views, enter a Scheme on the previous panel

Change Package resources ssssssssssssssssssssssssssssssssssssssssssssss

Filter * * + * *

/ Name Type Group Status Config DRIVERP PROGRAM WORKSHOP Not ready, new object REDTST41 TXNA TRANSACTION WORKSHOP Not ready, new object REDTST41 TXNB TRANSACTION WORKSHOP Not ready, new object REDTST41 TXNC TRANSACTION WORKSHOP Not ready, new object REDTST41 TXND TRANSACTION WORKSHOP Not ready, new object REDTST41 TXNE TRANSACTION WORKSHOP Not ready, new object REDTST41 TXN0 TRANSACTION WORKSHOP Not ready, new object REDTST41 WORKP PROGRAM WORKSHOP Not ready, new object REDTST41 ******************************* Bottom of data ********************************

Figure 17-12 Resource packaging

We defined a package called NACTGRP and placed all of the required resources into it. We must now apply some transformation rules to the package before we try to migrate it. Our prime concern is that the files that we use must now be defined as REMOTE, so we can build a Transformation Rule to include in the package.

Figure 17-13 on page 365 shows a Transformation Rule.

364 IBM CICS Explorer File Menu Settings Help ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss

Edit Transform Rule Command ===>

Name . . . . : TXNGRP Description . .

Qualification criteria Scheme . . . . . TXNGRP + Source Config . . REDTST41 + Target Config . . REDPRD41 + Group ...... WORKSHOP Resource Type . . TSMODEL + Resource Name . . OUTPUTP Check Field . . . + Check Operator + Check Value . . . +

Choose a Processing Option 1 1. Transform and continue 2. Transform and lock field 3. Transform and lock record 4. Stop migration of this resource

Transform Field and Values Change Field . . POOLNAME + Change From . . . * + Change To . . . . TSPOOL1 +

Figure 17-13 Transformation Rule

As we migrate our resources between environments, any TSQUEUE that we find in the Group that has the name of OUTPUTP has its POOLNAME field changed to the name of the pool that it needs to reside in, which in this case is TSPOOL1.

Chapter 17. CICSPlex SM enablement using the CICS Explorer 365

366 IBM CICS Explorer

Chapter 18. CICS Explorer resource manipulation scenarios

The CICS Explorer is described as “The New Face of CICS”. One of the main assets of the Explorer and the plug-ins is to introduce a whole new community to CICS and the System z in general. Traditionally, the accepted interface to CICS was always through the 3270, with its ability to perform operational tasks through the CEMT transaction (“The Master Terminal”) and resource definition tasks through the CEDA transaction (“RDO - Resource Definition Online”). With the advent of the CICS Web User Interface, CICSPlex SM users can perform these tasks by an implementation of Web Services utilizing the CICSPlex SM API.

The CICS Explorer, with its Eclipse-based environment, took this to another level by presenting CICS and CICSplex through a Graphical User Interface, thus giving it a very modern “look and feel” and enabling integration with a multitude of IBM Enterprise Software Portfolio products.

In this chapter, we discuss how we can manipulate resource definitions using the CICS Explorer to manage some of the scenarios that typically confront us when supporting CICS environments.

Resource locking is a constant factor that affects the day-to-day running of CICS applications all over the world. One of the best examples of locks being held on resources is that of the VSAM file, which has multiple users trying to update the same copy of a record. There are many programming techniques that are available today to circumvent this problem; however, they still occur on a daily basis.

18.1.1 VSAM record locking

We have an application that updates records on a VSAM file on a regular basis. In general, this runs satisfactorily throughout most of the day. However, a user calls us to say that his transaction appears to be suspended, so we must investigate. The initial window from the CICS Explorer shows us the transactions in region REDDEV41, and it appears that our problem transaction is one of the the ones shown in Figure 18-1.

Figure 18-1 Transactions suspended

368 IBM CICS Explorer Initially, we customize the columns so that we can see the reason for the suspend on each of our transactions. We do this by selecting the Customize Columns tab in the top right corner of the perspective, as shown in Figure 18-2.

Figure 18-2 Customize columns

From here, we can add SuspendType and SuspendValue so that we have a much more efficient view of where the problem is, which results in Figure 18-3.

Figure 18-3 Suspend Types display

Chapter 18. CICS Explorer resource manipulation scenarios 369 Now we can see that it appears that task 10401 issued some form of request against a dataset and is suspended with an ENQUEUE. The SuspendValue of FCDSRECD tells us there is a wait for a record lock in a VSAM file or CICS-maintained data table. If a transaction attempts to access a record that is locked by another transaction, it is suspended on resource type ENQUEUE until the lock is released. This can be a long wait because an update might depend on a terminal operator typing in data. Also, the suspended transaction relinquishes its VSAM string and, perhaps, its exclusive control of the CI, and has to wait again for those resources.

If transactions are commonly made to wait for this reason, review the programming logic of your applications to see if the record-locking time can be minimized.

So in our case, we have an earlier task, 10378, that is running the same transaction. In this case, this task has a suspend type of EDF, which means that someone is debugging this transaction and failed to release the record lock. Because we must resolve the situation quickly, we PURGE the task and see if that sorts out the problem. By right-clicking the task, we can select the option to remove the task, as shown in Figure 18-4.

Figure 18-4 Force Purge a Task

Before we do this, we get a confirmation window to ensure that we selected the right task, as shown in Figure 18-5 on page 371.

370 IBM CICS Explorer

Figure 18-5 Confirm Force Purge

The operational view of our tasks now shows that the task causing the wait was purged, Figure 18-6 on page 372, and that our suspended transaction has (hopefully) completed successfully.

Chapter 18. CICS Explorer resource manipulation scenarios 371

Figure 18-6 Transactions resumed

One final task we could do is to reset the columns back to their original settings, which we do by selecting the same drop-down list from the right corner and using the Reset Columns option.

18.2 Resource state manipulation

When connecting the CICS Explorer for the first time, the initial perspective you get is the System Management view, shown in Figure 18-7 on page 373.

372 IBM CICS Explorer

Figure 18-7 CICS Explorer System management view

From the view in Figure 18-8 on page 374, you can display all of the resources that are relevant to the CICS regions within the CICSplex. CICS regions can be individually selected just by clicking on the region name, which dynamically displays those details, or you can view the whole CICSplex by selecting the CICSplex name.

Across the top of this perspective is a list of resources that can be displayed. The default view contains a number of resources, one of them being transactions, as shown in Figure 18-8 on page 374.

If we select the Transactions tab, we are presented with a list of transactions that are defined, dependent upon the scope that is selected. In Figure 18-8 on page 374, we selected the CICS region REDDEV41, to reduce the amount of data displayed.

Chapter 18. CICS Explorer resource manipulation scenarios 373

Figure 18-8 Transaction list

We still have a large list of transactions, so what we need to do is filter this down until we are presented with the transactions that we actually want to work with, which we do by entering the criteria in the filter window, shown in Figure 18-9.

Figure 18-9 Filter window

Figure 18-10 on page 375 shows the resulting filter criteria.

374 IBM CICS Explorer

Figure 18-10 Filter criteria

If we now select the Apply Filter button, the results should display the transactions that we are interested in. In this case, we look for all transactions in CICS region REDDEV41 that begin with the characters NA. After applied, we get a much shorter list of transactions to work with, as shown in Figure 18-11.

Figure 18-11 Filter criteria applied

There is more than one method of changing the state of a particular resource. In our case, we want to disable one of our transactions. The quickest method of doing this is to select the resource in question, and then right-click, as shown in Figure 18-12 on page 376.

Chapter 18. CICS Explorer resource manipulation scenarios 375

Figure 18-12 Disable a Transaction

A window is displayed that offers us a number of options, and one option is to DISABLE the transaction. If we choose that option, we receive a confirmation dialog box, Figure 18-13.

Figure 18-13 Figure 16-13 Confirm disable window

Our transaction display should automatically refresh to display the new status of the transaction, as shown in Figure 18-14 on page 377.

376 IBM CICS Explorer

Figure 18-14 Transaction disabled

Let us assume that we inadvertently disabled the wrong transaction. We can use the alternative method of altering the resource to get it back into its correct state by double-clicking the resource in question. We disabled transaction NACT, so by double-clicking Figure 18-15 on page 378 is displayed.

Chapter 18. CICS Explorer resource manipulation scenarios 377

Figure 18-15 Transaction Attributes

In Figure 18-15, we scroll to the attribute that we want to change and update. In this instance, it is Transaction Status that we want to alter. When we select the attribute field, we are presented with a list of the only options that are available for this resource. In the case of Status, it can only be DISABLED or ENABLED, as shown in Figure 18-16 on page 379.

378 IBM CICS Explorer

Figure 18-16 Transaction Status Attributes

We select the ENABLED status and receive a confirmation message to save the changes. On confirming this, we should have a display of our transaction list, similar to Figure 18-17 on page 380.

Chapter 18. CICS Explorer resource manipulation scenarios 379

Figure 18-17 Confirmation of Save Changes

18.3 Discarding resources

One of the abilities of the CICS Explorer is to discard resources from a running CICS region. The command executes under the CICS API, effectively performing a CEMT DISCARD command.

The DISCARD command deletes the definition of a resource installed in the local CICS system, so that the system no longer has access to the resource. It reverses the effect of the installation of the resource, which can occur at system startup, through a subsequent CREATE command or CEDA transaction, by an automatic installation process or by a CICSPlex SM BAS command.

380 IBM CICS Explorer Each DISCARD command removes the definition of one resource. You can remove definitions for the following types of resources.

Autoinstall models for terminals: Connections CorbaServer (CORBASERVER) DB2Conns DB2Entrys DB2Trans Deployed JAR files (DJAR) Document templates ENQ models Files Journals and journal models LIBRARY concatenations Partners PIPELINEs Process types Profiles Programs, map sets, and partition sets Request models TCP/IP service Temporary storage queue models Ter minals Transaction classes Transactions Transient data queues URIMAPs WEBSERVICEs

You cannot discard a resource that is currently in use, for example, you cannot discard a PROFILE definition if some installed TRANSACTION definition still points to it, or a FILE that is open, or a TRANSACTION that is scheduled for execution.

In addition, some resources are not eligible for discard at all, which include resources whose names begin with the letters DFH (reserved for CICS-supplied definitions) and transactions with names that begin with C (also reserved for CICS).

Some DISCARD commands cause a sync point on behalf of the issuing task, as the CREATE commands do.

Chapter 18. CICS Explorer resource manipulation scenarios 381 DISCARD commands are recorded in the CICS catalog so that their effects persist over a warm or emergency restart, but they do not modify the CSD file and thus are lost on a cold or initial start

If we return to our list of transactions, we can use the previous transaction, NACT,

as our target. With the filter criteria still in place, refer to Figure 18-18 to see that there are two transactions in the list.

Figure 18-18 Transaction List

Select the NACT transactions, and right-click it to bring up the pop-up window that displays our options. In this case, we DISCARD the transaction, as shown in Figure 18-19.

Figure 18-19 Discard a Transaction

When selecting the DISCARD option, you will get a confirmation window before you can proceed, as shown in Figure 18-20 on page 383.

382 IBM CICS Explorer

Figure 18-20 Confirm Discard window

After you confirm your action, you are presented with the transaction list again minus the resource you just discarded, as shown in Figure 18-21.

Figure 18-21 Transaction List after Discard

Let us assume that we made another mistake. We want to re-instate the transaction that we just discarded. How would we go about that? Select the Administration View from the toolbar. We receive a list of resource types that we can choose from, as shown in Figure 18-22 on page 384.

Chapter 18. CICS Explorer resource manipulation scenarios 383

Figure 18-22 Administration resource options

If we select Transaction Definitions, then we are presented with a list of transactions that match our criteria. The filter that we applied in the Transaction View perspective still applies here, so we only see our filtered list.

By selecting the transaction that we just discarded, NACT, we now have an option to INSTALL it, as shown in Figure 18-23 on page 385.

384 IBM CICS Explorer

Figure 18-23 Install transaction

After we select the Install option, we are presented with a list of available regions to install it into. We choose our current region, REDDEV41, as shown in Figure 18-24 on page 386.

Chapter 18. CICS Explorer resource manipulation scenarios 385

Figure 18-24 Region selection

You should receive a message indicating the success of your install, as shown in Figure 18-25.

Figure 18-25 Successful install

Let us return to our transaction list, shown in Figure 18-26 on page 387. We should see that both of our transactions are now displayed. Also, if we select the Properties View, we can see that the Resource Signature details are updated to reflect the install. These attributes were introduced in CICS Transaction Server V4.1.

386 IBM CICS Explorer

Figure 18-26 Transaction Install and Resource Signature

As we discussed earlier, you can DISCARD a number of resources. However, these resources must be in an acceptable state before we can successfully remove them. So what happens when we try to remove a resource that is currently in use by the CICS region? Let us consider the case of the CONNECTION. What conditions must exist for the connection to be successfully discarded?

The DISCARD CONNECTION command removes a CONNECTION definition from the local CICS system. When a connection is removed, all of the associated sessions also are removed.

For deletion to be successful: The connection can have no active sessions if it is remote (that is, has a

REMOTESYSTEM value other than the name of the local region) and must be in OUTSERVICE status if it is not remote. The interregion communications facility must be closed if the connection is an MRO connection. You can use the SET IRC CLOSED command to close it.

Chapter 18. CICS Explorer resource manipulation scenarios 387 If the connection is an APPC connection and the local CICS system is a member of a VTAM® generic resource group, there can be no deferred work pending. Deferred work occurs when a failure causes a unit of work, which used a session on the connection at SYNCLEVEL 2, to be "shunted" (held for later disposition because recovery action is required before disposition can be completed).

Other types of connection can be discarded, even if there is recovery work outstanding for them; however, it is recommended that you do not discard them if there is. You can use the INQUIRE CONNECTION RECOVSTATUS command to check.

There can be no indirect CONNECTION definitions pointing to the connection to be discarded.

Note: In unusual circumstances, the discard of an LU6.1 connection can fail, even when it is out-of-service, if some of its sessions are still in-service. If this happens, set the connection status to INSERVICE, then OUTSERVICE, and then reissue the DISCARD command.

CICS completes successful DISCARD CONNECTION processing with an implicit sync point on behalf of the issuing task, committing changes to recoverable resources made up to that point in the task. If the discard processing fails, CICS raises the INVREQ exception condition with a RESP2 value of 27, and does a SYNCPOINT ROLLBACK instead, rolling back changes to recoverable resources. For all other exception conditions, however, discard processing is not attempted and SYNCPOINT nor SYNCPOINT ROLLBACK is issued.

So our attempt to DISCARD a CONNECTION should fail if it is in use. First, select a suitable connection in our current CICS region, REDDEV41, as shown in Figure 18-27 on page 389.

388 IBM CICS Explorer

Figure 18-27 Connection list

So now let us try to DISCARD the connection. Right-click to display the pop-up window with all of the options available. Notice in Figure 18-28 on page 390 that there are many more options for this resource than there were for our transaction.

Chapter 18. CICS Explorer resource manipulation scenarios 389

Figure 18-28 Discard a connection

We receive a confirmation panel for the command that we are trying to execute, as shown in Figure 18-29 on page 391.

390 IBM CICS Explorer

Figure 18-29 Confirm Discard connection

This time, our DISCARD command will fail, and we should receive a message telling us the reason why, as shown in Figure 18-30 on page 392.

Chapter 18. CICS Explorer resource manipulation scenarios 391

Figure 18-30 Discard connection failure

We receive a message in the pop-up panel telling us that our DISCARD command was not successfully executed, but the information bar on the perspective details more of the failed command. It describes the failure and includes the RESP and RESP2 values that were recorded. In this instance, our RESP code has a value of 16, which signals the INVREQ condition, and the RESP2 code has a value of 29, which signals that the connection is an MRO connection and the IRC is not closed.

392 IBM CICS Explorer Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.

IBM Redbooks

For information about ordering these publications, see “How to get Redbooks” on page 394. Note that some of the documents referenced here may be available in softcopy only: Migration Considerations for CICS Using CICS CM, CICS PA, and CICS IA, SG24-7294-00 IBM CICS Interdependency Analyzer, SG24-6458-01 CICS Performance Analyzer, SG24-6063-00 Threadsafe Considerations for CICS, SG24-6351-02

Other publications

These publications are also relevant as further information sources: CICS Interdependency Analyzer for z/OS, User’s Guide and Reference, SC34-6790-02 IBM CICS Configuration Manager for z/OS, User’s Guide, GC34-6777-04 IBM CICS Performance Analyzer for z/OS, User’s Guide, SC34-7046-01

Online resources

This Web site is also relevant as further information sources:

Installation Guide:

https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp

You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks publications, at this Web site: ibm.com/redbooks

Help from IBM

IBM Support and downloads ibm.com/support

IBM Global Services ibm.com/services

394 IBM CICS Explorer

IBM CICS Explorer

(0.5” spine) 0.475”<->0.875” 250 <-> 459 pages

Back cover ®

IBM CICS Explorer ®

CICS Explorer is the IBM Customer Information Control System (CICS) Explorer is INTERNATIONAL new modern face the new face of CICS Integration point for CICS tooling with of CICS rich CICS views, data, and methods. TECHNICAL SUPPORT Are you looking for new ways to accelerate the transfer of CICS Deployment knowledge, skills, and best practices to the next generation ORGANIZATION Assistant is the new of technical staff and experts? Do you need to maintain way to manage productivity and protect service-levels? CICS Explorer and System z lead the way to platform simplification. BUILDING TECHNICAL CICS Explorer IBM CICS Explorer has a common, intuitive, Eclipse-based INFORMATION BASED ON real-life usage environment for architects, developers, administrators, PRACTICAL EXPERIENCE scenarios included system programmers, and operators. The task-oriented views provide integrated access to a broad range of data and IBM Redbooks are developed by control capabilities, and it also has powerful, the IBM International Technical context-sensitive resource editors. Integration point for CICS Support Organization. Experts TS, CICS Tools, CICS TG, PD Tools, and Rational Tools are from IBM, Customers and extensible by independent software vendors (ISV), system Partners from around the world create timely technical integrators (SI), and customers who use our Software information based on realistic Development Kit. scenarios. Specific recommendations are provided In this IBM Redbooks publication, we focus on the new CICS to help you implement IT Explorer. The first part of the book is an overview of the CICS solutions more effectively in Explorer along with all of the CICS Tools’ plug-ins. In the your environment. second part of the book, we focus on several scenarios in which you can use the CICS Explorer with the CICS Tools plug-ins to resolve various problems. For more information: ibm.com/redbooks

SG24-7778-01 ISBN 0738434973