ibml - lightyear consultinglightyr.com/redbooks/sg245274 - cics ts v1 r3.pdf · ibml cics...

IBML

CICS Transaction Server for OS/390:Version 1 Release 3 Implementation Guide

Eugene Deborin, Jane Bennett, Steve Burghard,Dave Jeffries, Karl-Heinz Marquardt

International Technical Support Organization

http://www.redbooks.ibm.com

This book was printed at 240 dpi (dots per inch). The final production redbook with the RED cover willbe printed at 1200 dpi and will provide superior graphics resolution. Please see “How to Get ITSORedbooks” at the back of this book for ordering instructions.

SG24-5274-00

International Technical Support Organization

CICS Transaction Server for OS/390:Version 1 Release 3 Implementation Guide

March 1999

SG24-5274-00

IBML

Take Note!

Before using this information and the product it supports, be sure to read the general information inAppendix B, “Special Notices” on page 265.

First Edition (March 1999)

This edition applies to Version 1 Release 3 of CICS Transaction Server for OS/390, Program Number 5655-147 foruse with the OS/390 Version 2 Release 5.

Note

This book is based on a pre-GA version of a product and may not apply when the product becomes generallyavailable. We recommend that you consult the product documentation or follow-on versions of this redbookfor more current information.

Comments may be addressed to:IBM Corporation, International Technical Support OrganizationDept. QXXE Building 80-E2650 Harry RoadSan Jose, California 95120-6099

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1999. All rights reserved.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure issubject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvThe Team That Wrote This Redbook . . . . . . . . . . . . . . . . . . . . . . . . . xvComments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 New Functions and Package Contents . . . . . . . . . . . . . . . . . . . . . 11.2 CICS As an Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.1 Year 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Description of New Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.3.1 Application Enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.2 e-Business Enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3.3 Enterprise Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.3.4 Enterprise Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3.5 Base CICS Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.6 New CICS Clients and Gateway . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 2. Hardware and Software Prerequisites . . . . . . . . . . . . . . . . . 132.1 Hardware Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2 OS/390 Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 Database Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3.1 IMS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.3.2 DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.4 IBM MQSeries for MVS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5 IBM Telecommunications Access Methods . . . . . . . . . . . . . . . . . . 142.6 External Security Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.7 Forward Recovery Software . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.8 Java Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.9 Java Client Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.10 Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.10.1 Execution-Time Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3. Migration in a CICSPlex SM Managed CICSplex Environment . . . 173.1 CICSPlex SM Managed CICSplex . . . . . . . . . . . . . . . . . . . . . . . . 17

3.1.1 Managed Application System . . . . . . . . . . . . . . . . . . . . . . . . 173.1.2 CICSPlex SM Address Space . . . . . . . . . . . . . . . . . . . . . . . . 183.1.3 Coordinating Address Space . . . . . . . . . . . . . . . . . . . . . . . . 183.1.4 Environment Services System Services . . . . . . . . . . . . . . . . . . 193.1.5 CICSPlex SM User Interface . . . . . . . . . . . . . . . . . . . . . . . . . 193.1.6 Batched Repository-Update Facility . . . . . . . . . . . . . . . . . . . . 193.1.7 Application Programming Interface . . . . . . . . . . . . . . . . . . . . 193.1.8 Business Application Services . . . . . . . . . . . . . . . . . . . . . . . 19

3.2 Migrating CICSPlex SM to a New Release . . . . . . . . . . . . . . . . . . . 193.2.1 CMAS and MAS Migration . . . . . . . . . . . . . . . . . . . . . . . . . . 203.2.2 Data Repository Migration . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.3 Split CICSplexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.4 Backing up the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.5 Utilities Using the CICSPlex SM Application Programming Interface . . . 263.6 Data Repository Definitions across Releases . . . . . . . . . . . . . . . . . 283.7 Workload Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Copyright IBM Corp. 1999 iii

3.8 Business Application Services . . . . . . . . . . . . . . . . . . . . . . . . . . 333.9 Resource Object Data Manager Interface . . . . . . . . . . . . . . . . . . . 343.10 Tivoli Global Enterprise Manager Interface . . . . . . . . . . . . . . . . . . 34

Chapter 4. Coupling Facility Data Tables . . . . . . . . . . . . . . . . . . . . . . 354.1 CICS Data Table Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2 Coupling Facility Data Table Support . . . . . . . . . . . . . . . . . . . . . . 364.3 Overview of Informal Shared Data . . . . . . . . . . . . . . . . . . . . . . . . 37

4.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384.3.2 Methods of Sharing Informal Data . . . . . . . . . . . . . . . . . . . . . 38

4.4 CFDT Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384.5 Restrictions and Cautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394.6 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394.7 How CFDTs Are Accessed . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404.8 Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.9 Setting Up CFDT Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4.9.1 Plan How Many Tables and Pools are Needed . . . . . . . . . . . . . 424.9.2 Define List Structure in CFRM Policy . . . . . . . . . . . . . . . . . . . 424.9.3 Activate CFRM Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424.9.4 Initialize AXM Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424.9.5 Start DFHCFMN Server Regions . . . . . . . . . . . . . . . . . . . . . . 434.9.6 Change File Definitions to Use CFDT . . . . . . . . . . . . . . . . . . . 44

4.10 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.10.1 Server Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.10.2 Server Unload and Reload . . . . . . . . . . . . . . . . . . . . . . . . . 45

4.11 Sample CFDT Server Command . . . . . . . . . . . . . . . . . . . . . . . . 464.12 Initial Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.13 Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.14 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.15 CEMT Transaction and SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.16 Recovery Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.17 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.18 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.19 User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.20 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544.21 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.22 When to Use CFDT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.22.1 Scratchpad Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.22.2 Shared Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584.22.3 Control Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584.22.4 Keyed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.23 Simple Demonstration of Using CFDTs . . . . . . . . . . . . . . . . . . . . 584.23.1 First Open Causes Initial Load of CFDT . . . . . . . . . . . . . . . . . 594.23.2 Example of Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604.23.3 Remote Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4.24 Access to Original Data Set . . . . . . . . . . . . . . . . . . . . . . . . . . . 614.25 Same File Name, Different Table . . . . . . . . . . . . . . . . . . . . . . . . 614.26 Example of Contention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624.27 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 5. Global Enqueue Dequeue . . . . . . . . . . . . . . . . . . . . . . . . 655.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.2 Benefits of Sysplex Enqueue . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.3 ENQMODEL Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5.3.1 ENQName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

iv CICS Transaction Server for OS/390: Version 1 Release 3

5.3.2 ENQScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.4 Installing ENQMODELS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.5 INQUIRE ENQ SPI Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.6 New CEMT and SPI INQUIRE and SET ENQMODEL . . . . . . . . . . . . . . 685.7 New CREATE and DISCARD ENQMODEL . . . . . . . . . . . . . . . . . . . . 695.8 API Semantic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695.9 XNQEREQ and XNQEREQC Exits . . . . . . . . . . . . . . . . . . . . . . . . . 695.10 ENQ Deadlock Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

5.10.1 Without CICSPlex SM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705.10.2 With CICSPlex SM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

5.11 GRS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.12 Enqueuing from Outside CICS . . . . . . . . . . . . . . . . . . . . . . . . . 725.13 CICS Affinity Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735.14 Additional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 6. The Named Counter Sequence Number Server . . . . . . . . . . . . 756.1 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756.2 EXEC CICS Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766.3 CALL Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776.4 DFHNCOPT Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 7. External CICS Interface Enhancements . . . . . . . . . . . . . . . . 797.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797.2 Sample EXCI Client Implementation Using RRMS . . . . . . . . . . . . . . 83

7.2.1 Preparing the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847.2.2 The EXCI Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867.2.3 The Server Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.4 Running the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.5 Test 1 - Extended UOW with Implicit Syncpointing, Client Normal End 997.2.6 Test 2 - Extended UOW with Implicit Syncpointing, Client Abend . . 1037.2.7 Test 3: Mixing EXCI Calls with and without SYNCONRETURN . . . . 1077.2.8 Test 4: Extended UOW with Explicit Syncpointing . . . . . . . . . . . 108

7.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Chapter 8. Temporary Storage Facilities on CICS TS . . . . . . . . . . . . . . 1158.1 Overview of CICS Shared Temporary Storage . . . . . . . . . . . . . . . 1158.2 Resource Definition Online for Temporary Storage . . . . . . . . . . . . . 1178.3 Defining a TSMODEL with RDO . . . . . . . . . . . . . . . . . . . . . . . . 1188.4 Generic Name Specification . . . . . . . . . . . . . . . . . . . . . . . . . . 1188.5 Steps for Migrating to RDO for TST . . . . . . . . . . . . . . . . . . . . . . 1198.6 Long Names for Temporary Storage Queues . . . . . . . . . . . . . . . . 1218.7 QUEUE and QNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218.8 Restrictions on Long Names . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Chapter 9. CICS Business Transaction Services . . . . . . . . . . . . . . . . . 1239.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239.2 Setup Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

9.2.1 Process Type Resource Definition . . . . . . . . . . . . . . . . . . . . 1269.2.2 Local Request Queue Data Set . . . . . . . . . . . . . . . . . . . . . . 1279.2.3 CICS BTS Repository Data Set . . . . . . . . . . . . . . . . . . . . . . 1279.2.4 Distributed Routing Program . . . . . . . . . . . . . . . . . . . . . . . 1299.2.5 Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

9.3 Running the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . 1329.4 CICS BTS Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Contents v

Chapter 10. Dynamic Routing of START and LINK Requests . . . . . . . . . 14110.1 Static Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14110.2 Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14110.3 Extended Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14210.4 Dynamic Routing Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

10.4.1 Hub Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14210.4.2 Distributed Routing Model . . . . . . . . . . . . . . . . . . . . . . . . 144

10.5 Routing Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14410.5.1 Dynamic Routing Program . . . . . . . . . . . . . . . . . . . . . . . . 14410.5.2 Distributed Routing Program . . . . . . . . . . . . . . . . . . . . . . . 148

10.6 Using the COMMAREA When Writing a DTRPROG or DSTRPRG . . . . 15110.6.1 COMMAREA Passed to Dynamic Routing Program . . . . . . . . . 15110.6.2 COMMAREA Passed to Distributed Routing Program . . . . . . . . 155

10.7 Managing Dynamic and Distributed Routing with CICSPlex SM . . . . 15710.7.1 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16010.7.2 Changes to CICSPlex SM Definitions . . . . . . . . . . . . . . . . . . 16010.7.3 Modifying EYU9WRAM . . . . . . . . . . . . . . . . . . . . . . . . . . 16510.7.4 Ensuring DTRPROG and DSRTPGM Are Set . . . . . . . . . . . . . 169

10.8 Dynamic Routing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17010.8.1 Dynamic Routing of Program Link Requests . . . . . . . . . . . . . 17110.8.2 Routing Terminal-Initiated START Requests . . . . . . . . . . . . . 18910.8.3 Routing CICS BTS Processes and Activities . . . . . . . . . . . . . 20110.8.4 Routing EXCI Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 21410.8.5 Affinity Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 22310.8.6 Using MVS/WLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

10.9 Additional Issues to Consider with Dynamic and Distributed Routing . 23210.9.1 Mixed CICSPlex SM Release Environments . . . . . . . . . . . . . . 23210.9.2 Connection Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . 23210.9.3 Service Classes and TRANSIDs . . . . . . . . . . . . . . . . . . . . . 233

Appendix A. CICSPlex SM New and Changed Views . . . . . . . . . . . . . . 235A.1 Operational Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

A.1.1 CICS Region Related Views . . . . . . . . . . . . . . . . . . . . . . . . 235A.1.2 Temporary Storage Related Views . . . . . . . . . . . . . . . . . . . 236A.1.3 TCP/IP Related Views . . . . . . . . . . . . . . . . . . . . . . . . . . . 240A.1.4 Request Model Related Views . . . . . . . . . . . . . . . . . . . . . . 241A.1.5 Task Related Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242A.1.6 Data Table Related Views . . . . . . . . . . . . . . . . . . . . . . . . . 247A.1.7 CICS BTS-Related Views . . . . . . . . . . . . . . . . . . . . . . . . . 249A.1.8 CFDT Pool Related Views . . . . . . . . . . . . . . . . . . . . . . . . . 250A.1.9 Enqueue Related Views . . . . . . . . . . . . . . . . . . . . . . . . . . 251A.1.10 Monitored Transaction Related Views . . . . . . . . . . . . . . . . . 253A.1.11 CICS Web Interface Related Views . . . . . . . . . . . . . . . . . . . 254A.1.12 Program Related Views . . . . . . . . . . . . . . . . . . . . . . . . . 255A.1.13 Transaction Related Views . . . . . . . . . . . . . . . . . . . . . . . 255

A.2 Administration Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256A.2.1 CICS System Related Views . . . . . . . . . . . . . . . . . . . . . . . 256A.2.2 Workload Management Related Views . . . . . . . . . . . . . . . . . 257

A.3 Application Definition Panels . . . . . . . . . . . . . . . . . . . . . . . . . . 259A.3.1 Transaction Definition Panels . . . . . . . . . . . . . . . . . . . . . . . 259A.3.2 Program Definition Panels . . . . . . . . . . . . . . . . . . . . . . . . 260A.3.3 File Definition Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260A.3.4 Document Template Definition Panel . . . . . . . . . . . . . . . . . . 261A.3.5 Global Enqueue Model Definition Panel . . . . . . . . . . . . . . . . 262A.3.6 Process Type Definition Panel . . . . . . . . . . . . . . . . . . . . . . 262

vi CICS Transaction Server for OS/390: Version 1 Release 3

A.3.7 Request Model Definition Panel . . . . . . . . . . . . . . . . . . . . . 263A.3.8 TCP/IP Service Definition Panel . . . . . . . . . . . . . . . . . . . . . 263A.3.9 Temporary Storage Model Definition Panel . . . . . . . . . . . . . . 264

Appendix B. Special Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Appendix C. Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . 267C.1 International Technical Support Organization Publications . . . . . . . . 267C.2 Redbooks on CD-ROMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267C.3 Other Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269IBM Redbook Fax Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Contents vii

viii CICS Transaction Server for OS/390: Version 1 Release 3

Figures

1. CICSPlex SM Managed CICSplex . . . . . . . . . . . . . . . . . . . . . . . 18 2. Recommended CICSPlex SM Migration Process . . . . . . . . . . . . . . 21 3. CICSPlex SM Data Repository Migration JCL . . . . . . . . . . . . . . . . 21 4. CICSPlex SM Configuration Where Maintenance Points Are Split . . . . 22 5. Reduced Complexity Configuration . . . . . . . . . . . . . . . . . . . . . . 23 6. Ideal CICSPlex SM Configuration . . . . . . . . . . . . . . . . . . . . . . . 24 7. Suggested Backup Process for CICSPlex SM Data Repository . . . . . . 25 8. Possible Utility Applications Running with CICSPlex SM API . . . . . . . 27 9. CICSPlex SM API CONNECT Verb . . . . . . . . . . . . . . . . . . . . . . . 2710. Cross-Release Operation of CICSPlex SM CMASs . . . . . . . . . . . . . 2811. CICSPlex SM New Attributes for the CICS BTS . . . . . . . . . . . . . . . 2812. CICSPlex SM WLMSPEC and TRANGRP Definition Processing . . . . . . 2913. CICSPlex SM WLMDEF Definition Processing . . . . . . . . . . . . . . . . 3014. CICSPlex SM Workload Build Processing Rules . . . . . . . . . . . . . . . 3115. CICSPlex SM Workload Build Processing . . . . . . . . . . . . . . . . . . . 3116. CICSPlex SM Workload Join Processing . . . . . . . . . . . . . . . . . . . 3217. CICSPlex SM WLMDEF or TRANGRP Install Processing . . . . . . . . . . 3218. Owning CMAS Reference on WLMAWORK View . . . . . . . . . . . . . . 3319. Coupling Facility Data Tables within a Sysplex . . . . . . . . . . . . . . . 3720. DISPLAY of Initialization Parameters . . . . . . . . . . . . . . . . . . . . . 4121. Sample CFRM List Structure Definition . . . . . . . . . . . . . . . . . . . . 4222. Sample JCL to Start CFDT Server . . . . . . . . . . . . . . . . . . . . . . . 4323. Messages Issued during Startup of CFDT Server . . . . . . . . . . . . . . 4324. AXM Storage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4425. Sample JCL for Unload of CFDT . . . . . . . . . . . . . . . . . . . . . . . . 4626. Output from Two DISPLAY TABLE Commands . . . . . . . . . . . . . . . . 4627. Excerpts from an RDO Definition of a File Using a CFDT . . . . . . . . . 4928. Number of Accesses to Coupling Facility per Function . . . . . . . . . . . 5329. Sample Output from the CICS Statistics Report . . . . . . . . . . . . . . . 5430. Results of a DISPLAY POOLSTATS Command . . . . . . . . . . . . . . . . 5531. Summary of When to Use CFDTs . . . . . . . . . . . . . . . . . . . . . . . . 5732. Layout of Test Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 6033. Message Produced for Lock on Key . . . . . . . . . . . . . . . . . . . . . . 6034. Mirroring Task in CFDTWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . 6135. Descriptions of FILEA per Region . . . . . . . . . . . . . . . . . . . . . . . 6236. RDO Definition of an ENQMODEL . . . . . . . . . . . . . . . . . . . . . . . 6637. Results of CEMT I ENQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7038. Results of D GRS,RES=(DFHE*,*) . . . . . . . . . . . . . . . . . . . . . . . 7139. GRS Enqueuing in a Sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . 7240. Sample Named Counter Server List Structure Definition . . . . . . . . . 7541. Sample JCL to Start Named Counter Server . . . . . . . . . . . . . . . . . 7642. Default Supplied DFHNCOPT Table . . . . . . . . . . . . . . . . . . . . . . 7743. EXCI Overview. An EXCI Client Connects to CICS Target Region, Using

the CICS MRO Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7944. Overview of the New EXCI Support Using RRMS . . . . . . . . . . . . . . 8045. Design Options for EXCI Client Applications . . . . . . . . . . . . . . . . . 8146. Mixing with and without SYNCONRETURN Calls in an EXCI Client . . . . 8247. Functions of Our Sample Application . . . . . . . . . . . . . . . . . . . . . 8348. Sample Input Screen from the Test Driver . . . . . . . . . . . . . . . . . . 8449. Resulting Output Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8450. Early RX Domain Initialization Messages . . . . . . . . . . . . . . . . . . . 85

Copyright IBM Corp. 1999 ix

51. RRS Resynchronization Message . . . . . . . . . . . . . . . . . . . . . . . 8552. Program Listing for the EXCI Driver . . . . . . . . . . . . . . . . . . . . . . 8753. Program Listing of EXCI13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9354. RRMS CEMT INQUIRE RR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9855. RRS Main Menu Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9856. RRS Resource Manager Selection Panel . . . . . . . . . . . . . . . . . . . 9857. RRS Resource Manager List . . . . . . . . . . . . . . . . . . . . . . . . . . 9858. RRS Resource Manager Details Panel for PAA1 . . . . . . . . . . . . . . 9959. RRS Resource Manager Details Panel for PAA4 . . . . . . . . . . . . . . 9960. RRS Unit of Recovery List Panel . . . . . . . . . . . . . . . . . . . . . . . 10061. Result of CEMT INQUIRE EXCI for a Call without SYNCONRETURN . . 10062. Result of CEMT INQUIRE UOWLINK . . . . . . . . . . . . . . . . . . . . . 10063. RRS Unit of Recovery Details Panel . . . . . . . . . . . . . . . . . . . . . 10164. RRS Unit of Recovery IDs Panel . . . . . . . . . . . . . . . . . . . . . . . 10165. CEMT I UOW Display in PAA1 . . . . . . . . . . . . . . . . . . . . . . . . 10166. RRS URI Details Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10267. RRS Unit of Recovery Details Panel for PAA4 . . . . . . . . . . . . . . . 10268. RRS URI Details for PAA4 . . . . . . . . . . . . . . . . . . . . . . . . . . . 10369. Results of CEMT INQUIRE EXCI for PAA4 . . . . . . . . . . . . . . . . . . 10370. Results of CEMT INQUIRE UOW for PAA4 . . . . . . . . . . . . . . . . . 10371. Final EXCI Call Before Client Abend . . . . . . . . . . . . . . . . . . . . . 10572. Client Abend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10673. RRS Unit of Recovery Details Panel: Test 3 . . . . . . . . . . . . . . . . 10774. RRS Unit of Recovery Work IDs . . . . . . . . . . . . . . . . . . . . . . . 10875. CEMT I TASK Display Showing Two Instances of CSMI . . . . . . . . . 10876. CEMT INQUIRE EXCI Display for a Call with SYNCONRETURN . . . . . 10877. RRS Unit of Recovery Details Panel: Test 4 . . . . . . . . . . . . . . . . 10978. PAA1 Joins the Extended Unit of Recovery . . . . . . . . . . . . . . . . . 10979. CICS Connections to RRS and the EXCI client: PAA1 Region . . . . . . 11080. CICS Connections to RRS and the EXCI client: PAA4 Region . . . . . . 11081. The Test Front End Showing the Commit Result . . . . . . . . . . . . . 11082. Prepare to Commit for PAA1 . . . . . . . . . . . . . . . . . . . . . . . . . 11183. Prepare to Commit for PAA4 . . . . . . . . . . . . . . . . . . . . . . . . . 11184. Commit Phase One Starting in PAA1 . . . . . . . . . . . . . . . . . . . . 11185. Commit Phase Two for PAA1 . . . . . . . . . . . . . . . . . . . . . . . . . 11286. Commit Phase Two for PAA1: UR Committed . . . . . . . . . . . . . . . 11287. Commit Phase Two for PAA1: Recovery Manager Initiates Logging . . 11288. TS Servers within a Sysplex . . . . . . . . . . . . . . . . . . . . . . . . . 11689. TST Defining a Shared Temporary Storage Queue . . . . . . . . . . . . 11790. A TSMODEL Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11891. Sample TST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11992. Output from MIGRATE of TST . . . . . . . . . . . . . . . . . . . . . . . . . 12093. A TSMODEL Definition Showing a Long Name . . . . . . . . . . . . . . 12194. CEMT I TSQUEUE Command Output . . . . . . . . . . . . . . . . . . . . . 12295. CICS BTS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12496. CEDA View a Process Type . . . . . . . . . . . . . . . . . . . . . . . . . . 12697. JCL to Create a Local Request Queue Data Set . . . . . . . . . . . . . . 12798. JCL to Create a CICS BTS Repository Data Set . . . . . . . . . . . . . . 12899. File Control Resource Definition for the CICS BTS Repository Data Set 129100. JCL to Update the Logger Policy for the Audit Log . . . . . . . . . . . . 130101. Journal Model Resource Definition for the Audit Log . . . . . . . . . . . 131102. JCL to Print the Audit Log Contents . . . . . . . . . . . . . . . . . . . . . 131103. Sample Audit Log Printout . . . . . . . . . . . . . . . . . . . . . . . . . . 132104. CICS BTS Sample Application . . . . . . . . . . . . . . . . . . . . . . . . 133105. Sample Application Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

x CICS Transaction Server for OS/390: Version 1 Release 3

106. The CBAM List of Current Process Types . . . . . . . . . . . . . . . . . 137107. Current Processes of a Selected Type . . . . . . . . . . . . . . . . . . . 137108. Details of Process SALES333111 . . . . . . . . . . . . . . . . . . . . . . . 137109. Details of the Root Activity . . . . . . . . . . . . . . . . . . . . . . . . . . 138110. Resource Display (Container) of an Activity . . . . . . . . . . . . . . . . 138111. Events Known by the Root Activity . . . . . . . . . . . . . . . . . . . . . . 138112. Timer Event Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139113. Traditional Dynamic Transaction Routing Model . . . . . . . . . . . . . 143114. Hub Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143115. Distributed Routing Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 144116. Pre-CICS TS 1.3 START Processing . . . . . . . . . . . . . . . . . . . . . 145117. CICS TS 1.3 START Processing . . . . . . . . . . . . . . . . . . . . . . . . 146118. Terminal-Initiated Dynamic Transaction Routing . . . . . . . . . . . . . 147119. Dynamic Routing of Program Link Requests . . . . . . . . . . . . . . . . 148120. Non-Terminal-Initiated START Processing . . . . . . . . . . . . . . . . . 149121. Dynamic Router or Distributed Router . . . . . . . . . . . . . . . . . . . 150122. COMMAREA Passed to a Dynamic Routing Program . . . . . . . . . . . 154123. COMMAREA Passed to a Distributed Routing Program . . . . . . . . . 156124. Combined Hub and Distributed Models: A Perspective . . . . . . . . . 157125. ITSO Hub Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158126. ITSO Distributed Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159127. CICSSYS Create System View . . . . . . . . . . . . . . . . . . . . . . . . 161128. New Program Definition Panel . . . . . . . . . . . . . . . . . . . . . . . . 161129. New Transaction Definition Panel . . . . . . . . . . . . . . . . . . . . . . 162130. Create WLM Specification Panel . . . . . . . . . . . . . . . . . . . . . . . 163131. Create Trangroup Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164132. WLMAWORK View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164133. EYURWCOM Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166134. When Does CICSPlex SM Route? . . . . . . . . . . . . . . . . . . . . . . 170135. Dynamic Routing of Program Link Requests: CICS Region

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171136. Program Link Sample Application: DPLP2PST Program . . . . . . . . . 172137. Program Link Sample Application: DPLPGM01 Program . . . . . . . . . 173138. Program Link Sample Application: DPLPGM02 Program . . . . . . . . . 174139. Program Link Sample Application: DPLPGM03 Program . . . . . . . . . 175140. Program Link Sample Application: DPLPGM04 Program . . . . . . . . . 176141. Program Definition: DPLP2PST Page 1 . . . . . . . . . . . . . . . . . . . 177142. Program Definition: DPLP2PST Page 2 . . . . . . . . . . . . . . . . . . . 177143. Program Definition: DPLPGM01 Page 1 . . . . . . . . . . . . . . . . . . . 178144. Program Definition: DPLPGM01 Page 2 . . . . . . . . . . . . . . . . . . . 179145. Transaction Definition: DP2P . . . . . . . . . . . . . . . . . . . . . . . . . 180146. Transaction Definition: DP01 . . . . . . . . . . . . . . . . . . . . . . . . . 180147. Transaction Definitions for DPLP2P Application . . . . . . . . . . . . . . 181148. Resource Group for DPLP2P Application . . . . . . . . . . . . . . . . . . 181149. Resource Description for DPLP2P Application . . . . . . . . . . . . . . . 182150. MAP View of DPLP2P Application . . . . . . . . . . . . . . . . . . . . . . 182151. Resource Assignment: DPLP2PPR . . . . . . . . . . . . . . . . . . . . . . 183152. Resource Assignment: DPLP2PTR . . . . . . . . . . . . . . . . . . . . . . 183153. LOCTRAN View for DPLP2P Application . . . . . . . . . . . . . . . . . . 184154. PROGRAM View for DPLP2P Application . . . . . . . . . . . . . . . . . . 184155. WLMSPEC View for DPLP2P Application . . . . . . . . . . . . . . . . . . 185156. WLMDEF View for DPLP2P Application . . . . . . . . . . . . . . . . . . . 185157. WLMAWORK View: SCSCWS1D . . . . . . . . . . . . . . . . . . . . . . . 186158. Checking DTRPROG Settings in a Hub Router Region . . . . . . . . . . 186

Figures xi

159. Checking DSRTPGM and DTRPROG Settings in a Distributed RouterRegion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

160. Showing the Use Counts of the DPLP2P Application . . . . . . . . . . . 187161. Testing the DPLP2P Application . . . . . . . . . . . . . . . . . . . . . . . 188162. Updated Use Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188163. Using CEBR to Review the DPLP2P Application . . . . . . . . . . . . . . 188164. DPLP2P Application Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189165. Dynamic Routing of Terminal-Initiated START Requests: CICS

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190166. Dynamic START Request Sample Application . . . . . . . . . . . . . . . 191167. Transaction Definition: DST1, Page 1 . . . . . . . . . . . . . . . . . . . . 192168. Transaction Definition: DST1, Page 2 . . . . . . . . . . . . . . . . . . . . 192169. Transaction Definition: DST1, Page 4 . . . . . . . . . . . . . . . . . . . . 193170. TRANDEF View with DST1 Transaction . . . . . . . . . . . . . . . . . . . 193171. Program Definition: DSTART01 . . . . . . . . . . . . . . . . . . . . . . . . 194172. Resource Assignment: DSTARTPR . . . . . . . . . . . . . . . . . . . . . 195173. Resource Assignment: DSTARTTR . . . . . . . . . . . . . . . . . . . . . . 195174. Resource Description: DSTART . . . . . . . . . . . . . . . . . . . . . . . . 196175. MAP View of DSTART Resource Description . . . . . . . . . . . . . . . . 196176. WLMDEF View Including DSTART Application . . . . . . . . . . . . . . . 197177. WLM Specification: SCSWS01Q . . . . . . . . . . . . . . . . . . . . . . . . 197178. Creating a SCREEN for the DSTART Application . . . . . . . . . . . . . 198179. Testing the DSTART Application . . . . . . . . . . . . . . . . . . . . . . . 198180. DSTART Application Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198181. Use Count Increase in SCSCPAA1 for DSTART Application . . . . . . . 199182. CICSPlex SM Screen with WLMAOR View . . . . . . . . . . . . . . . . . 199183. Quiescing the SCSCPAA1 Region . . . . . . . . . . . . . . . . . . . . . . 200184. Transaction DST1 Executing in SCSCPAA7 Region . . . . . . . . . . . . 200185. Use Count Increase in SCSCPAA7 for DSTART Application . . . . . . . 201186. CICS BTS Sample Process: BTS Set Configuration . . . . . . . . . . . . 202187. CICS BTS Sample: PROCDEF ORDER . . . . . . . . . . . . . . . . . . . . 202188. CICS BTS Sample: RESGROUP DCBTSFL . . . . . . . . . . . . . . . . . 203189. CICS BTS Sample: RESGROUP DCBTSPRC . . . . . . . . . . . . . . . . 203190. CICS BTS Sample: RASGNDEF DCBTSPRC . . . . . . . . . . . . . . . . 203191. CICS BTS Sample: RASGNDEF DCBTSFL . . . . . . . . . . . . . . . . . . 204192. CICS BTS Sample: RESGROUP DCBTSSYN . . . . . . . . . . . . . . . . 204193. CICS BTS Sample: RESGROUP DCBTSASY . . . . . . . . . . . . . . . . 205194. CICS BTS Sample: RASGNDEF DCBTSATR . . . . . . . . . . . . . . . . 205195. CICS BTS Sample: RASGNDEF DCBTSSTR . . . . . . . . . . . . . . . . 206196. CICS BTS Sample: Map of RASGNDEF DCBTSATR . . . . . . . . . . . . 206197. CICS BTS Sample: Map of RASGNDEF DCBTSSTR . . . . . . . . . . . . 206198. CICS BTS Sample: Contents of TRANGRP DCBTSSYN . . . . . . . . . . 207199. CICS BTS Sample: TRANGRP DCBTSASY . . . . . . . . . . . . . . . . . 207200. CICS BTS Sample: WLMDEF DCBTSSYN . . . . . . . . . . . . . . . . . . 207201. CICS BTS Sample: SYSGRP PROTSAOR . . . . . . . . . . . . . . . . . . 208202. CICS BTS Sample: WLMDEF DCBTSASY . . . . . . . . . . . . . . . . . . 208203. CICS BTS Sample: Map of RESDESC DCBTS . . . . . . . . . . . . . . . 208204. CICS BTS Sample: TRANGRP CBTSTRAN . . . . . . . . . . . . . . . . . 209205. CICS BTS Sample: WLMDEF CBTSTRAN . . . . . . . . . . . . . . . . . . 209206. CICS BTS Sample: Initial Input Screen . . . . . . . . . . . . . . . . . . . 210207. CICS BTS Sample: Initial Transaction Use Counts . . . . . . . . . . . . 211208. CICS BTS Sample: Process Completion Screen . . . . . . . . . . . . . . 212209. CICS BTS Sample: Trace Output from Region PAA4 . . . . . . . . . . . 212210. CICS BTS Sample: Trace Output from Region PAA7 . . . . . . . . . . . 213211. CICS BTS Sample: Post-Process Transaction Use Counts . . . . . . . . 213

xii CICS Transaction Server for OS/390: Version 1 Release 3

212. EXCI Sample Program VSAMSER1: PROGDEF View . . . . . . . . . . . 215213. EXCI Sample Transaction VSRV: TRANDEF View Page 1 . . . . . . . . 215214. EXCI Sample Transaction VSRV: TRANDEF View Page 2 . . . . . . . . 216215. EXCI Sample Transaction VSRV: TRANDEF View Page 3 . . . . . . . . 216216. EXCI Sample Transaction VSRV: TRANDEF View Page 4 . . . . . . . . 216217. EXCI Sample: Browsed View of RASGNDEF DEXCIPR . . . . . . . . . . 217218. EXCI Sample: Browsed View of RASGNDEF DEXCITR . . . . . . . . . . 217219. EXCI Sample: Map View of RESDESC DEXCI . . . . . . . . . . . . . . . . 218220. EXCI Sample: TRANGRP Panel . . . . . . . . . . . . . . . . . . . . . . . . 218221. EXCI Sample: WLMDEF View . . . . . . . . . . . . . . . . . . . . . . . . . 219222. EXCI Sample: Display of SYSGRPC PROTSAOR . . . . . . . . . . . . . . 219223. EXCI Sample: Map of TRANGRP VSRVTRAN View . . . . . . . . . . . . 219224. EXCI Sample - Program Use-Count View before Testing Started . . . . 220225. EXCI Sample: TSO Front-End Input (Screen 1) . . . . . . . . . . . . . . . 220226. EXCI Sample: TSO Front-End Input (Screen 2) . . . . . . . . . . . . . . . 221227. EXCI Sample: Program Use-Count View after First Test . . . . . . . . . 221228. EXCI Sample: Program Use-Count View after Second Test . . . . . . . 222229. EXCI Sample: Program Use-Count View after Third Test . . . . . . . . 222230. MVS WLM Initial Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225231. MVS WLM Choose Service Definiton Panel . . . . . . . . . . . . . . . . 225232. MVS WLM Main Definition Menu . . . . . . . . . . . . . . . . . . . . . . . 226233. MVS WLM Service Class Selection List . . . . . . . . . . . . . . . . . . . 226234. MVS WLM Create a Service Class . . . . . . . . . . . . . . . . . . . . . . 227235. MVS WLM Choose a Goal Type . . . . . . . . . . . . . . . . . . . . . . . 227236. MVS WLM Average Response Time Goal . . . . . . . . . . . . . . . . . 228237. MVS WLM Response Times Defined . . . . . . . . . . . . . . . . . . . . . 228238. MVS WLM Service Class FAST Created . . . . . . . . . . . . . . . . . . 229239. MVS WLM Add VSRV to Service Class FAST (1) . . . . . . . . . . . . . 229240. MVS WLM Add VSRV to Service Class FAST (2) . . . . . . . . . . . . . 230241. MVS WLM Add VSRV to Service Class FAST (3) . . . . . . . . . . . . . 230242. MVS WLM Add VSRV to Service Class FAST (4) . . . . . . . . . . . . . 231243. WLMSPEC View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232244. Same Transaction Name for Client and Server Program: CICSPlex SM

Can Select Required Service Class . . . . . . . . . . . . . . . . . . . . . 233245. Different Transaction Names: CICSPlex SM Cannot Select Required

Service Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234246. CICSRGND View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235247. CICSRGN4 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236248. TSMODEL View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236249. TSMODELD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237250. TSMODELS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237251. TSQSHR View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238252. TSQSHRD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238253. TSQSHRS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238254. TSPOOL View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239255. TSQNAME View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239256. TSQNAMED View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240257. TSQNAMES View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240258. TCPIPS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240259. TCPIPSD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241260. RQMODEL View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241261. RQMODELD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242262. RQMODELS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242263. TASKD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243264. TASK2 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Figures xiii

265. TASK3 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244266. TASK4 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244267. TASK5 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245268. TASK6 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245269. TASK7 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246270. TASK8 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246271. TASK9 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247272. CMDTD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248273. CMDT2 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248274. CMDT3 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249275. CMDTS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249276. PROCTYP View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250277. PROCTYPD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250278. PROCTYPS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250279. CFDTPOOL View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251280. CFDTPOOD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251281. CFDTPOOS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251282. ENQMDL View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252283. ENQMDLD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252284. ENQMDLS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252285. MLOCTRAD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253286. MLOCTRA4 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253287. DOCTEMP View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254288. DOCTEMPD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254289. DOCTEMPS View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255290. PROGRAMD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255291. LOCTRAND View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256292. CICSSYS Browse View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256293. WLMSPEC View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257294. WLMDEF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257295. WLMAWORK View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257296. WLMAWORD View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258297. WLMAWDEF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258298. Transaction Group Definition Panel . . . . . . . . . . . . . . . . . . . . . 259299. New Transaction Definition Panel (4) . . . . . . . . . . . . . . . . . . . . 259300. New Program Definition Panel . . . . . . . . . . . . . . . . . . . . . . . . 260301. New File Definition Panel (2) . . . . . . . . . . . . . . . . . . . . . . . . . 261302. New File Defintion Panel (3) . . . . . . . . . . . . . . . . . . . . . . . . . . 261303. New Document Template Definition Panel . . . . . . . . . . . . . . . . . 262304. New Enqueue Model Definition Panel . . . . . . . . . . . . . . . . . . . . 262305. New Process Type Definition Panel . . . . . . . . . . . . . . . . . . . . . 263306. New Request Model Definition Panel . . . . . . . . . . . . . . . . . . . . 263307. New TCP/IP Service Definition Panel . . . . . . . . . . . . . . . . . . . . 264308. New Temporary Storage Model Definition Panel . . . . . . . . . . . . . 264

xiv CICS Transaction Server for OS/390: Version 1 Release 3

Preface

This redbook is primarily intended for CICS customers who plan to implementCICS Transaction Server for OS/390 Version 1 Release 3 (CICS TS) and its newfeatures. It includes an overview and detailed implementation steps for many ofthe new features introduced in this release of CICS TS.

You will become familiar with the new system availability features and newapplication development facilities introduced in this CICS release. You will seehow CICS provides support for MVS Recoverable Resource ManagementServices (RRMS) through extensions to its External Call Interface (EXCI). Youwill learn how to start with CICS Business Transaction Services (CICS BTS) - anew paradigm for development of business applications. For more informationabout CICS BTS, refer to Business Process Model Implementation with CICSBusiness Transaction Services.

Java application development and CORBA client support are covered in anotherredbook publication, Java Application Development for CICS: Base Services andCORBA Client Support.

CICSPlex System Manager is now supplied as an exclusive element of CICS TS.More and more customers use it to manage their CICSplex systems. You willlearn from this redbook how CICSPlex SM can be used to provide workloadmanagement for non-terminal initiated requests: distributed program link (DPL),START, EXCI, and others.

The Team That Wrote This RedbookThis redbook was produced by a team of specialists from around the worldworking at the ITSO San Jose Center.

Eugene Deborin is an Advisory Information Technology Consultant at theInternational Technical Support Organization, San Jose Center. He writesextensively and teaches IBM classes worldwide on all areas of CICS TransactionServer for OS/390. He has 22 years of experience with the CICS product, 12 ofthese as an IBM Systems Engineer.

Jane Bennett is a CICS system programmer from IBM UK. She has worked forIBM for 15 years, including 11 years at the IBM Support Center. Currently sheprovides technical support for IBM Europe, Middle East and Africa and forexternal customer sites. She holds a honors degree in Computing Science andFrench.

Steve Burghard is a CICS Systems Support Specialist from IBM UK. Having 16years experience of CICS, he has spent the last 3 years with IBM, mostlysupporting IBM internal accounts. He has also contributed to the design ofseveral outsourcing solutions. Steve ′s areas of expertise include CICSPlex SM,CICS for OS/2, and CICS application programming.

Dave Jeffries is a CICS, CICSPlex SM and MQSeries specialist at the IBMParallel Solutions Support Center in Montpellier, France. He has worked withCICS for the last 10 years, spending 5 years in CICSPlex SM developmentoffering technical support to customers worldwide. He is now responsible for

Copyright IBM Corp. 1999 xv

assisting customers implement CICS in S/390 Parallel Sysplex environmentsthroughout Europe, the Middle East and Africa.

Karl-Heinz Marquardt is an Advisory Information Technology Consultant forTransaction Systems, working as second-level field support for IBM Germany.He has more than 25 years of experience with IBM, most recently working withCICS customers throughout Germany. Karl-Heinz prepares and holds workshopsand briefings for customers throughout Germany. His areas of expertise includeMVS, CICSSPlex SM, CICS, and client/server architecture.

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

Barry Dickinson ,IBM UK, Hursley Laboratories

Robert Haimowitz ,International Technical Support Organization, Raleigh Center

Paul Johnson ,IBM UK, Hursley Laboratories

Jonathan Hoare ,IBM UK, Hursley Laboratories

Alyn Iorwerth ,IBM UK, Hursley Laboratories

Vasilis Karras ,International Technical Support Organization, Poughkeepsie Center

Peter Klein ,IBM Germany

Ian Mitchell ,IBM UK, Hursley Laboratories

Catherine Moxey ,IBM UK, Hursley Laboratories

Antonius Inggil Paripurnanto ,IBM Indonesia

Jonathan Scott ,IBM UK, Hursley Laboratories

Thanks also to the following people for the time they spent reviewing this book,and for their suggestions for improvement:

Jean Paul Caron ,IBM France

Ian Rose ,IBM UK, Hursley Laboratories

Norbert Verbestel ,IBM Belgium

xvi CICS Transaction Server for OS/390: Version 1 Release 3

Nigel Williams ,IBM France, Parallel Solutions Support Center

Bob Yelavich ,Consultant

Comments WelcomeYour comments are important to us!

We want our redbooks to be as helpful as possible. Please send us yourcomments about this or other redbooks in one of the following ways:

• Fax the evaluation form found in “ITSO Redbook Evaluation” on page 275 tothe fax number shown on the form.

• Use the online evaluation form found at http://www.redbooks.ibm.com/

• Send your comments in an Internet note to [email protected]

Preface xvii

xviii CICS Transaction Server for OS/390: Version 1 Release 3

Chapter 1. Introduction

With the explosion of the Internet and an ever-increasing need for reliablee-Commerce in the enterprise, CICS takes on a new form as the e-Businessapplication server for enterprise computing. CICS Transaction Server for OS/390(CICS TS) 1.3 contains the richest set of functions compared to any of theprevious releases. It is the base for the future growth of general-purpose andlarge-scale or complex transaction processing systems. As the two previousreleases, CICS TS 1.3 contains CICS-enabling functions, orderable with oneprogram number and delivered as one product, with one price.

1.1 New Functions and Package ContentsFour main areas in CICS TS 1.3 provide a balance of solutions to meet customerneeds. These are the major new functions in each of these areas:

• Application enablement

− Java application support

− Object-oriented interface to CICS services for C++

− CICS business transaction services

− Long temporary storage queue names

• e-Business enablement

− Common Object Request Broker Architecture (CORBA) client support

− CICS Web Interface (CWI) enhancements

− The external CICS interface (EXCI) enhancement for resource recovery

− 3270 bridge interface enhancements

− New CICS Transaction Gateway and CICS Universal Clients

• Enterprise scalability

− Dynamic routing and load balancing of distributed program link (DPL)and EXEC CICS START requests

− Coupling facility data table (CFDT) support

− Sysplexwide enqueue (ENQ) and dequeue (DEQ)

− Named counter server

• Enterprise management

− CICSPlex System Manager (CICSPlex SM) enhancements

− Resource definition online (RDO) for CICS temporary storage

− Autoinstall for MVS consoles

− Enhancements to CICS monitoring and statistics

Similar to the previous two releases, CICS TS 1.3 has both exclusive andnonexclusive elements. The base CICS element of CICS TS 1.3, the third releaseof the latest CICS version, is exclusive and includes features and productsavailable with previous CICS versions and releases:

• CICSPlex SM

Copyright IBM Corp. 1999 1

• CWI

• Open Network Computing Remote Procedure Call (ONC RPC)

• CICS Transaction Affinities utility

• CICS-DB2 attachment facility

The nonexclusive elements of the product, also available as separate products,are:

• REXX Development System for CICS/ESA

• REXX Runtime Facility for CICS/ESA

• CICS Distributed Data Management (DDM)

• CICS Application Migration Aid Version 1.1

• CICS Universal Clients Version 3.0

A nonexclusive element of the product, but not available as a separate product,is:

• CICS Transaction Gateway Version 3.0

1.2 CICS As an Application ServerThe transaction processing strengths of CICS in an enterprise computingenvironment are appreciated and exploited worldwide. But today, CICS is morethan an exceptionally capable transaction processor—it is an application serverthat enables you to distribute applications and data flexibly across your networkin any way that your changing enterprise may need.

CICS is a family of modern transaction processing products that enables yourbusiness to exploit applications and data on many different hardware andsoftware platforms. It is a truly robust and open platform on which to build yourenterprise systems. With this release you should get a greater return oninvestment for your technology by increasing productivity and performance,especially through Web technologies.

CICS views an application and all its associated services as an entity. Itmanages and coordinates all the different resources needed by applications,such as databases, files, and message queues, to ensure completeness andintegrity of data. CICS is a true application server.

Each of the four main areas of CICS TS 1.3 - application enablement, e-Businessenablement, enterprise scalability, and enterprise management - containsspecific product items that provide the following potential business benefits inresolving critical business issues:

• Reduced costs - Development productivity

• Improved time to market - Programmer productivity, design, and reuse

• Reduced production costs - Efficient use of existing skills and components,efficient integration and reuse of existing data and processes

• Improved business efficiency - Efficient design and reuse of business andinformation technology (IT) processes

• Extended reach to market - Extending business processes to the Web

2 CICS Transaction Server for OS/390: Version 1 Release 3

• Improved user productivity, look and feel - Intuitive look and feel of thegraphical user interface (GUI)

• Improved performance and manageability

• Increased scalability of business

With CICS TS 1.3 and OS/390, customers can make the correct decision fordeveloping applications for S/390, leveraging the best mix of features in which anorganization can invest, bringing real business benefits.

CICS TS 1.3 provides improved productivity for application developers throughthe CICS Business Transaction Services (BTS), better operational and systemsmanagement capabilities, and increased price performance and manageability,while also attracting customers and vendors to new technologies through theInternet and Java.

Additional enterprise integration facilities bridge system boundaries to allowyour customers to connect to systems wherever they may be and free yourenterprise to grow the way you want.

Parallel computing support makes the benefits of parallelism and newtechnology immediately available. The first release of CICS TS providedadditional data sharing. It made more use of VTAM generic resource functionand used IBM′s coupling technology for improved handling of log streams. Italso enhanced recovery for data sharing. This release extends that support withmore functions, such as the dynamic routing of DPL and EXEC CICS STARTrequests.

Substantial enhancements have been made to CICS and other systemcomponents with the use of the MVS logging function, the new recovery manager(CICS TS 1.1), and CICS data tables in a coupling facility (CICS TS 1.3), improvingavailability and capacity in a Parallel Sysplex.

Enhanced systems management facilities increase your operational efficiencyand enable you to improve your service level commitments. Enhancementsinclude: resource definition online (RDO) for DB2 resources (CICS TS 1.2),temporary storage (CICS TS 1.3), transient data, and centralized logmanagement (CICS TS 1.1).

1.2.1 Year 2000This product is Year 2000 ready. When used in accordance with its associateddocumentation, it is capable of correctly processing, providing, and/or receivingdate data within and between the twentieth and twenty-first centuries, providedthat all other products (for example, software, hardware, and firmware) used withthe product properly exchange date data with it.

1.3 Description of New FunctionsIn this section we describe in more detail the new functions in the four majorareas.

Chapter 1. Introduction 3

1.3.1 Application EnablementInformation technology departments are constantly required to reduce costs andmake better use of existing investments. At the same time, they are expected tohelp the enterprise become more competitive by exploiting the new ways ofdoing e-Business. CICS has developed new sets of tools to help reconcile thesetwo conflicting requirements.

1.3.1.1 CICS TS Support for JavaCICS TS 1.3 supports the Java programming language. It provides a library ofJava classes for access to the important CICS services. A CICS program writtenin Java can be run under a JVM or compiled to machine code and executed as aLanguage Environment (LE) run unit. DB2 can also be accessed from compiledJava programs through the SQLJ interface.

The CICS TS support for Java:

• Allows a CICS program to be written in Java

• Allows CICS Java programs to interoperate with CICS programs written inany of other CICS supported languages

• Allows a CICS application written in Java to access CICS services

• Provides a Java version of the CICS API known as the JCICS class library

• Supports Java development tools such as VisualAge for Java

The CICS translator is not required for Java. The application program isdeveloped and compiled, using a Java compiler on a workstation or under theOS/390 UNIX System Services on MVS. The bytecode output of this process maybe interpreted by a JVM running in CICS or it may be further compiled to S/390machine code by the HPJ compiler provided by the ET/390 component ofVisualAge for Java, Enterprise Edition 2.0.

For more information about the CICS support for the Java language refer to JavaApplication Development for CICS.

1.3.1.2 Object-Oriented Interface to CICS Services for C++CICS introduces a new C++ object-oriented (OO) API, enabling applicationprogrammers to have access to those CICS services previously available onlyusing the CICS command-level API. The CICS OO API, based on the CICS C++foundation classes, gives a C++ programmer the choice of writing CICSapplication programs with either the traditional CICS command-level API or theCICS OO API classes.

By using OO techniques in the design and development of your CICSapplications, you can reflect your business model more accurately, make rapidchanges to any mission-critical application, and improve your programmingproductivity through greater reuse of application components.

1.3.1.3 CICS Business Transaction ServicesCICS BTS provides a significant new programming model for building businesstransactions that closely reflect a business process, while generally simplifyingthe task of building complex e-Business solutions. There is no compromise ontraditional CICS reliability, integrity, performance, scalability, and availability.


A CICS business transaction is a self-contained business function, for example,the booking of a holiday package. Traditionally, in CICS a business transactionmight be implemented as one or more CICS transactions. CICS BTS controls theoverall progress of the business transaction, managing interrelationships,ordering, parallel execution, commit scope, and recovery/restart. A businesstransaction can have an indefinite lifetime spanning restarts of the CICS system.Existing CICS transactions can be reused as an activity within a CICS businesstransaction.

A business transaction is implemented as a control program that expresses aset of rules and actions within a business process. Activities can beimplemented sequentially or in parallel, or in any combination, and persistentdata can be passed between activities. Both control programs and activities canbe implemented in any programming language supported by CICS.

CICS BTS is implemented as a set of new EXEC CICS commands that extend thecurrent CICS API to make it easier to model, control, and execute complexbusiness transactions. Business transactions are treated in essentially the sameway as any CICS transaction. They can be initiated from the same sources,including CICS Clients, remote CICS systems, and Web browsers. They can bedistributed accross a Parallel Sysplex. They can be defined, managed,monitored, and controlled with CICS services, including CICSPlex SM, and areenabled for workload separation and workload balancing across a sysplex.

Key Features of CICS BTS

• Pseudo-conversational mechanisms are extended to non-terminal-initiatedtransactions, such as those initiated by Web browsers, aliases started forRPC requests, and transactions initiated by incoming MQSeries messages.

• Management and control are maintained at the business transaction andaction level.

• Business logic is separated from control logic.

• Individual CICS transactions are transparent from the ″before and after″actions.

• The ability to develop encapsulated business logic improves programmerproductivity.

• The processes and activities of CICS BTS can be monitored and/or statisticalinformation gathered.

• Resources can be analyzed at the business or CICS transaction level.

• In a CICSplex, CICS BTS processes and actions can take full advantage ofCICSPlex SM facilities.

• Systems management workload separation and workload balancing areavailable.

• CICS BTS processes can be used as servers in a client/server environment.

• An efficient concurrency model is implemented.

• Contextual information is separated from the business logic.

• Existing transactions can be accessed from the CICS BTS environment.

• CICS BTS is not limited by any 32 KB restriction that other communicationmethods, such as COMMAREA, may have had.


1.3.1.4 Long Temporary Storage Queue NamesThe CICS temporary storage (TS) facility is enhanced to allow TS queues to havenames up to 16 characters long, providing great flexibility in user applicationprograms. For example, with 16-character names you can generate queuenames of the form ttttSuuuuuuuu, where tttt is the transaction identifier, Srepresents a sequence character (allowing you to have more than one queue foreach transaction), and uuuuuuuu is the user ID.

Support for longer TS queue names removes many of the restrictions anddifficulties imposed by the eight character limit.

1.3.2 e-Business EnablementCICS TS 1.3 brings major enhancements in this area.

1.3.2.1 CORBA Client SupportThe Internet Inter-ORB protocol (IIOP) is a standard when providingcommunication between OO application programs executing on differentprocessors. It is part of the CORBA 2.0 specification.

In an e-Business environment, CORBA interoperability is important because itallows the use of vendor-independent client platforms, giving true separation ofserver and client environments.

A distributed object model ensures well-defined interfaces for applications withobject characteristics, so better checking at compile time and run time reducesthe number of errors compared with the use of communication areas(COMMAREAs) in external call interface (ECI) calls.

CICS TS 1.3 supports inbound requests to Java application programs, using IIOP.CICS has implemented a subset of CORBA services suitable for distributedobjects that have evolved from existing CICS applications and therefore have thefollowing characteristics:

• The state of the objects is not managed by the Object Request Broker (ORB).The state is initialized with the Java class constructor or at the start of eachmethod call and referenced by explicit method parameters.

• Transaction and security contexts are managed by CICS facilities, so theseCORBA services are not provided.

• CICS services are used to reference distributed applications, so outboundobject references are not supported.

• Applications and their interfaces are predefined, so the Dynamic SkeletonInterface (DSI) is not supported.

Each method call is implemented as a CICS transaction, retaining the existingterminal owning region (TOR) / application owning region (AOR) structure.

CORBA Client Support Features

CICS support for inbound requests using IIOP provides:

• Improved application development productivity. Use of a distributed objectmodel gives well-defined (strongly typed) interfaces for applications withinheritance and polymorphism characteristics.


• Stronger type checking at compile time and reduction in application errorscompared with the use of untyped COMMAREAS used in CICS ECI calls.Run-time type checking is also enabled for use in polymorphicimplementations.

• The use of vendor-independent client platforms, giving true separation ofserver and client environments.

1.3.2.2 CICS Web Interface EnhancementsThe CWI is enhanced with a number of major improvements, including supportfor workload management (WLM):

• All CICS TCP/IP support has been restructured as a new Sockets domain.As a result, the CWI provides improved reliability and serviceability.

• New EXEC CICS API commands for the manipulation of Web entities havebeen added.

• Improvements have been made to the definition and management of HTMLtemplates.

• CWI work can be sysplex-enabled.

• More than 32 KB of data can be handled, inbound and outbound.

• The CWI uses the 3270 bridge enhancements in a Web 3270 environment.

1.3.2.3 CICS EXCI Enhancement for Resource RecoveryThe EXCI has been enhanced to allow the CICS recovery manager to coordinatewith the MVS recovery manager by enabling changes to CICS recoverableresources as part of the total unit of work originating outside CICS. The MVSrecovery manager component is called MVS Recoverable ResourceManagement Services (RRMS). Thus applications using EXCI can participate infull recovery of a distributed unit of work, enabling integration with other workmanagers within the enterprise.

In earlier releases, EXCI enforces a syncpoint by the CICS server region beforereturning control to the EXCI client program. With the use of MVS RRMS, anextended mode of EXCI operation (transactional) now provides:

• The unit of work within which the CICS server program changes recoverableresources becomes part of the MVS unit of recovery associated with theEXCI client program.

• The CICS server unit of work is not committed when the server programreturns control to the client. This unit of work continues over multiple EXCIcalls, until the EXCI client decides to commit or back out the unit of recovery.

1.3.2.4 3270 Bridge Interface EnhancementsThe 3270 bridge function was introduced in CICS TS 1.2. It provides an interfaceto 3270-based CICS transactions without the use of a 3270 terminal. Existing3270 transactions can therefore be accessed from non-CICS environments, suchas the Web, MQSeries, or Lotus Notes.

In CICS TS 1.3 the bridge function has been enhanced to extend the set of 3270applications that can be accessed and to make it easier to write bridgeprograms for specific purposes:


• New options of the START command are provided to initiate a usertransaction and to establish the bridge environment. A separate definitionfor a bridge transaction is no longer needed for this purpose.

• Some restrictions on the CICS commands used by a user 3270 transactionare removed. Support is added for:

− START TRANSID TERMID commands, where TERMID is the bridgefacility, and TRANSID is local

− RETURN IMMEDIATE

− INPUTMSG on RETURN, XCTL, and LINK

− SET TERMINAL ATISTATUS

Applications written for 3270 terminals can be run on CICS systems withoutVTAM. The bridge can provide fast processing of Terminal Control and BasicMapping Support (BMS) commands, because the terminal emulation is part ofthe same CICS transaction. There is only a single unit of work, simplifyingrecoverability.

1.3.3 Enterprise ScalabilityThe S/390 Parallel Sysplex environment provides a uniquely scalable, shareddata, clustered server architecture. Data in DB2, IMS-DB, and VSAM as well asin CICS temporary storage queues can be shared by all nodes, and CICSapplications can run on any node in the cluster with full access to all data, or ona single node S/390 system.

CICS TS 1.3 extends support for Parallel Sysplex environments with the followingnew functions:

• Dynamic routing and load balancing of DPL and EXEC CICS START requests

The CICS dynamic routing facility is extended to provide mechanisms fordynamically routing transactions initiated by DPL requests, and by a subsetof eligible START commands. This facility also covers:

− EXCI requests from an MVS client

− ECI requests from any of the CICS Client workstation products

The routing mechanisms allow workload balancing to be managed byCICSPlex SM, providing integrated workload balancing for EXCI clients, CICSclients, and started tasks.

The ability to dynamically route all types of program link requests improvesthe performance and reliability of:

CWI

CICS Gateway for Java

EXCI calls

CICS Client ECI calls

DCE/RPC

ONC/RPC

Any function that issues an EXEC CICS LINK Program request

Applications that use the subset of START commands, which can bedynamically routed.


• Coupling facility data tables support

CFDT support allows user applications running in different CICS regions thatreside in one or more MVS images within a Parallel Syplex to share workingdata with update integrity.

Data in a CFDT is accessed through the CICS file control API, enablingexisting applications to use it, either without any modification, or withminimum changes, depending on the level of function required. CFDTprovides efficient sharing of data with integrity and behaves much like asysplexwide equivalent of user-maintained data tables. Key lengths greaterthan 16 bytes are not supported. This is a restriction of the coupling facilityarchitecture.

• Sysplexwide ENQ and DEQ

The sysplexwide (global) enqueue and dequeue function enables CICStransactions running in the same region, or in different regions within asysplex, to serialize on a named resource using the existing CICS API. Byextending the scope of the CICS enqueue mechanism, a major source ofintertransaction affinity is removed, enabling better exploitation of ParallelSysplex environments, improving price-to-performance ratio, capacity, andavailability.

For example, serialization allows concurrent updates to shared TS queues bymultiple CICS transaction instances, while locking a shared TS queue againstconcurrent updates.

• Named counter server

A utility program is provided for the efficient generation of unique sequencenumbers (for example, the next order number) in a Parallel Sysplexenvironment.

1.3.4 Enterprise ManagementThe enhancements in this area are provided by CICSPlex SM and by the baseCICS component.

1.3.4.1 CICSPlex SM EnhancementsCICSPlex SM has been enhanced to work with the new CICS functions of thisrelease.

CICSPlex SM is now an exclusive element of CICS TS and is fully integrated withthe base CICS product. Stand-alone releases of the CICSPlex SM product do notsupport CICS TS 1.3. All of the CICSPlex SM functions are available, including:

• Business Application Services (BAS) for defining and installing CICSresources across multiple CICS occurrences on S/390 systems

• Generating messages and generic alerts for triggering automation actions

• Real time analysis (RTA) for detecting potential CICS problems and takingautomatic corrective actions

• CICSPlex SM can manage not only CICS systems in different MVS imagesbut also CICS/VSE 2.3 (5686-026) and CICS Transaction Server for OS/2 Warp4.1 (5622-808).


1.3.4.2 Resource Definition Online for CICS Temporary StorageInstead of coding macros to define a temporary storage table (TST), CICSprovides TSMODEL resource definitions for TS queues in the CICS systemdefinition (CSD) file. The DEFINE command on the CEDA transaction is used forthis RDO facility, and in the DFHCSDUP utility program. TS model definitions canalso be discarded while CICS is running.

RDO for temporary storage eliminates the need to prepare a temporary storagetable (TST) for batch assembly and link-edit. There is now no need to shut downand restart CICS in order to make changes to TS queue definitions. RDOsupport for TS queues is part of the CICS high availability and continuousoperations strategy.

1.3.4.3 Autoinstall for MVS ConsolesAutoinstall for terminals is extended to include MVS consoles, removing theneed to define MVS consoles to CICS. Autoinstall for consoles can use the sameautoinstall control program as for terminals. This saves a considerable amountof system programmer effort for defining and maintaining individual consoleresource definitions.

1.3.4.4 Enhancements to CICS Monitoring and StatisticsAdditional information is provided by CICS monitoring and statistics for many ofthe changes and new functions introduced in CICS.

1.3.5 Base CICS EnhancementsThere are additional enhancements in various areas that:

• Provide support for long-lived TCP/IP connections. The CPU costs involvedin setting up a TCP/IP connection for each incoming request or data post tothe CICS server are high. In a conversational or pseudo-conversationalbusiness transaction, which has multiple requests and posts, a considerablesaving in CPU can be made if all flows after the first are made without theneed to reestablish the connection. With this support, performance of boththe CWI and the IIOP interface is improved.

• Provide support for BMS maps on LU6.2 sessions, through newMAPPINGDEV option. The new API enables applications to perform BMSdata mapping in the absence of a suitable principal facility terminal.

• Enhance the CICS-DBCTL operator transaction (CDBM) to support issuingIMS commands from a file rather than just screen input, with the ability toupdate and maintain the file.

• Enable run-unit work area storage to be reused for EXEC CICS LINK forprograms running under LE.

• Provide support for an explicit TCP/IP address per IP service.

• Provide support for including the new euro-capable code pages.

1.3.6 New CICS Clients and GatewayCICS TS 1.3 package includes CICS Universal Clients Version 3.0 and CICSTransaction Gateway Version 3.0.


1.3.6.1 CICS Universal Clients Version 3.0The IBM CICS Universal Clients 3.0 are developed from the CICS Clients V 2.They are an all 32-bit product, delivered for the OS/2, Windows NT, Windows 98,AIX and Solaris platforms. They bring the any-to-any communication capabilitiespreviously available only on Intel-based platforms to AIX and Solaris.

The CICS Universal Clients also provide a range of functional enhancements,including a security API, improvements to installation, and an application forworkload management.

The CICS Universal Clients 3.0 can be copied for use with any IBM CICS server.

1.3.6.2 CICS Transaction Gateway Version 3.0The IBM CICS Transaction Gateway provides powerful mechanisms for enablingaccess from the Internet to the tried and trusted transactional capabilities of IBMCICS servers (including CICS Transaction Servers and TXSeries servers). TheCICS Transaction Gateway uses the latest technologies, both Hypertext TransferProtocol (HTTP) and Java-based, to link the open, OO world of Web browsers onthe Internet or an intranet to the power, flexibility, integrity and robustness ofCICS enterprise computing.

The CICS Transaction Gateway is provided for the OS/2, Windows NT, AIX, andSolaris platforms. It also supports Windows 98 for application development. Itruns on the same system as the Web server and is capable of supporting a largenumber of concurrent users. It is an integrated product that incorporates thefunctions provided by the CICS Universal Clients Version 3.0, enablingcommunication with a wide range of CICS servers.

The CICS Transaction Gateway enables any Internet-connected desktopworkstation or network computer to provide your customers, Business Partners,or distributed sales force with access to your business-critical, core, corporateapplications on CICS.

For more information about CICS Transaction Gateway 3.0 and CICS UniversalClients 3.0, refer to Revealed! CICS Transaction Gateway with More CICS ClientsUnmasked.


Chapter 2. Hardware and Software Prerequisites

In this chapter we provide information about the hardware and softwareenvironments required to use CICS TS 1.3. We address the following topics:

• Hardware prerequisites• OS/390 operating system• Database products• IBM MQSeries for MVS/ESA• IBM telecommunications access methods• External security manager• Forward recovery software• Java language support• Java client support• Programming languages

For more documentation on these subjects, see the following publications:

• CICS Release Guide

• CICS Migration Guide

2.1 Hardware PrerequisitesCICS TS runs on any Enterprise Systems Architecture/390 (S/390) processor thatsupports OS/390 2.5 or higher and has enough processor storage to meet thecombined requirements of the host operating system, CICS TS, the accessmethods, and your application programs.

CICS TS is dependent on the MVS logging function, requiring either the directaccess storage device (DASD) logging function for a single system image or acoupling facility. In a Parallel Sysplex, CICS TS requires one or more couplingfacilities with their associated coupling links installed. Your coupling facility canbe an Integrated Coupling Migration Facility (ICMF), an Internal Coupling Facility(ICF), or one of the following:

• A stand-alone IBM S/390 Coupling Facility 9674 (IBM 9674)

• A logical partition on an IBM S/390 Parallel Enterprise Server 9672 (IBM9672)

• A logical partition on an ES/9000 9021 711-based processor or an ES/90009121 511-based processor

A stand-alone coupling facility is recommended for a production environment.Two coupling facilities are recommended for high availability and to eliminate asingle point of failure.

2.2 OS/390 Operating SystemThe minimum required level of the operating system to support CICS TS 1.3 isOS/390 Version 2 Release 5.

You need SMP/E (5668-949) Release 8 to install CICS TS.


If you have a requirement to share VSAM data sets between batch and CICS,install the latest level of the language environment run-time libraries. Batch jobscan read and update, concurrently with CICS, nonrecoverable data sets that areopened by CICS in record level sharing (RLS) mode. Batch jobs can read, butnot update, a recoverable data set in RLS mode when it is concurrentlyaccessed by CICS in RLS mode.

With PTF UW40778 for DFSMS/MVS 1.3 or UW40779 for DFSMS 1.4, recoverabledata sets defined with cross-region SHROPTIONS(2) can be concurrentlyaccessed for input by batch programs using non-RLS mode and by CICS forinput or output in RLS mode.

2.3 Database ProductsCICS TS 1.3 supports the following IBM database managers: IMS/ESA Version 5(5695-176) and Version 6 (5655-158) and DB2 Version 3 (5685-DB2), Version 4(5695-DB2), Version 5 (5655-DB2), and Version 6 (5645-DB2).

2.3.1 IMS/ESACICS TS does not support the local DL/I interface to IMS/ESA DatabaseManager. You must use the DBCTL interface, which is available in IMS/DMVersion 3 Release 1 or later. However, IMS/ESA Versions 3 and 4 do not supportthe Year 2000. Therefore, local DL/I customers will need to have migrated toDBCTL and IMS/ESA Version 5 before the Year 2000. Another reason to migrateis to exploit IMS database sharing among many CICS regions on several MVSimages within a Parallel Sysplex configuration.

2.3.2 DB2The minimum release level supported is DB2 Version 3 Release 1. If you want toexploit DB2 database sharing among many CICS regions on several MVS imageswithin a Parallel Sysplex configuration, you require DB2 Version 4 Release 1 orlater.

2.4 IBM MQSeries for MVS/ESAThe minimum release level supported is MQSeries/ESA Version 1 Release 1,Modification 3 (5695-137).

Support of in-doubt wait handling requires MQSeries/ESA Version 1 Release 1,Modification 4.

The MQSeries messaging mechanism for use with the CICS TS 3270 bridge isprovided by MQSeries/ESA Version 1 Release 2 with APAR PQ13387.

2.5 IBM Telecommunications Access MethodsCICS TS 1.2 requires VTAM Version 3 Release 4, Modification 2 (5685-085) orlater. However, if you want to have a single network name for multiple TORs onseveral MVS images within your Parallel Sysplex, you require VTAM Version 4Release 2 (5695-117) or later.


If you plan to use VTAM multinode persistent session support, install VTAMVersion 4 Release 4. This release of VTAM is supplied as part of OS/390 Version1 Release 3 or OS/390 Version 2 Release 4.

TCP/IP-attached systems or workstations are supported by CICS TS, if either theONC RPC function of CICS or the CICS basic TCP/IP sockets feature of OS/390Version 2 is used. Access through TCP/IP is also provided with CICS TS Internetsupport and with TCP62 protocol support.

2.6 External Security ManagerIf you use Resource Access Control Facility (RACF) as your external securitymanager for CICS, you need RACF Version 2 Release 1 (5695-039) plus PTFUW05554 for APAR OW02759, to provide the required support for the newLOGSTRM general resource class, and PTF OW15975, to enable generalresource class profile names for CICS journals to be up to 17 characters long.

You need RACF 2.2 to support long TS queue names, and you need PTFsUW91119 and UW91120 for RACF certificate support.

2.7 Forward Recovery SoftwareIf you use CICS VSAM Recovery (CICSVR) for forward recovery of VSAM files(including RLS files), you need CICSVR Version 2 Release 3 (5695-010).

Any other forward recovery utility should be compatible with the new log recordsformat introduced in CICS TS.

2.8 Java Language SupportTo support compilation, binding, and execution of Java language programs in aCICS TS environment, you need IBM VisualAge for Java, Enterprise Edition forOS/390 (5655-JAV) Version 2.0.

2.9 Java Client SupportTo provide support for a Java client with a gateway on OS/390 platform, youneed OS/390 Version 2 Release 5 with Java Developer′s Kit/Runtime 1.1 andCICS Gateway for Java (MVS) Version 2 Release 1.

2.10 Programming LanguagesCICS TS supports the following programming languages and environments:

• High Level Assembler/MVS (5696-234)

• IBM COBOL for MVS and VM (5688-197)

• IBM PL/I for MVS and VM (5688-235)

• VS/COBOL II (5668-958 and 5688-023). No support is provided for NORESprograms (CICS or batch). The PTF for APAR PN43097 (Abend0c4 caused byIGZECIC returning to CICS with an incorrect mode) is required.

• C/370 (5688-040 and 5688-187)

Chapter 2. Hardware and Software Prerequisites 15

• IBM C/C++ for MVS/ESA Version 3 Release 1 or later (5655-121)

• CSP Version 3 or later (5688-813)

• OS PL/I Optimizing Compiler Version 2 Release 1 or later (5668-910)

• OS PL/I Optimizing Compiler Version 1 Release 5.1 or later (5734-PL1)

CICS also supports IBM SAA AD/Cycle Language Environment/370 Version 1Release 1 and Release 2 run-time environment (5688-198) with the followingCOBOL, C/370, and PL/I SAA AD/Cycle compilers:

• SAA AD/Cycle COBOL/370 (5688-197)

• SAA AD/Cycle C/370 (5688-216)

• SAA AD/Cycle PL/I (5688-235)

2.10.1 Execution-Time SupportCICS TS retains translation and execution-time support for application programsassembled by MVS Assembler H Version 2 (5668-962).

CICS TS retains execution-time support for application programs compiled by thefollowing unsupported COBOL compilers:

• Full American National Standard COBOL Version 4 (5734-CB2)

• OS/VS COBOL (5740-CB1)

Execution-time support is withdrawn for applications compiled by the old OS/VSCOBOL compilers, 360S-CB-545 and 5734-CB1.


Chapter 3. Migration in a CICSPlex SM Managed CICSplexEnvironment

In this chapter we discuss methods of migrating a CICSPlex SM managedCICSplex from one release to another, and associated issues. We then presentsome techniques to consider to ensure a smooth migration.

3.1 CICSPlex SM Managed CICSplexIn this section we recap base CICSPlex SM concepts and terminology. Foradditional information refer to CICS Transaction Server for OS/390: Version 1Release 2 Implementation Guide, CICSPlex SM Business Application Services: ANew Way to Manage CICS Resources, and to the product documentation.

In a CICSPlex SM environment the term CICSplex describes the largest set ofCICS regions or systems to be manipulated as a single CICSPlex SM entity.CICS regions in a CICSPlex SM managed CICSplex do not have to be connectedto each other.

The grouping of CICS systems for management purposes is purely logical. Forexample, a CICSplex could comprise all CICS systems on a particular MVSimage, all CICS systems running a particular application, or all CICS systemsaccessible by a subset of your users.

The most significant characteristics of a CICSplex managed by CICSPlex SM are:

• The CICSplex is the largest unit you can work with.

• You cannot copy CICSPlex SM data from one CICSplex to another.

• CICSplexes are mutually exclusive, so no CICS system can belong to morethan one CICSplex.

3.1.1 Managed Application SystemA CICS system managed by CICSPlex SM is called a managed applicationsystem (MAS). A MAS is local (LMAS) if it runs on the same MVS image withthe CICSPlex SM address space (CMAS) to which it connects.

Figure 1 on page 18 illustrates the concepts introduced in this section.


Figure 1. CICSPlex SM Managed CICSplex

A MAS is remote (RMAS) if it runs on a system where there is no CMAS and if itis remotely attached to a CMAS by MRO or APPC link.

The MASs permanently run some CICSPlex SM agent code. MASs can be TORs,AORs, FORs, QORs, or any other CICS region.

3.1.2 CICSPlex SM Address SpaceThe CMAS is a CICS system dedicated to running the CICSPlex SM code. TheCMAS has a data repository data set to hold the data that controls its operation.A CMAS is required on every MVS system where the MASs must be connectedlocally to a CMAS. Several CMASs running on the same or different MVSimages can be connected through either LU 6.2 or MRO connections toparticipate in the management of the same CICSplex.

3.1.3 Coordinating Address SpaceThe coordinating address space (CAS) is used to set up the CICSPlex SMcomponent infrastructure and to support the MVS/TSO ISPF user interface toCICSPlex SM. A CAS is required on every MVS image where operators oradministrators want to use the ISPF user interface to manage the CICSplex.Several CASs running on different MVS images can be connected to give ISPFaccess to the CMASs participating in the management of the CICSplex.


3.1.4 Environment Services System ServicesThe environment services system services (ESSS) is an address space owningall data spaces used by CICSPlex SM to hold all data accumulated from theMASs. It makes the accumulated CICSPlex SM data impervious to events inMASs and the CMAS. The ESSS is created automatically by the first CMAS tostart on an MVS image.

3.1.5 CICSPlex SM User InterfaceThe CICSPlex SM user interface is an MVS/TSO Interactive System ProductivityFacility (ISPF) end user interface (EUI) supported by the CAS. The ISPF interfaceis used to define and maintain the CICSPlex SM configuration and to specifyBAS, workload management (WLM), real-time analysis (RTA), and monitoringrequirements. The CICSPlex SM EUI also provides the functions of CEMT andother CICS-supplied transactions and can be used to monitor and control theresources of individual CICS systems. The EUI provides an immediate,interactive look at your resource definitions. It enables you to create an isolatedresource for testing purposes, alter attributes in multiple definitions, or install anew version of a definition in a running system.

3.1.6 Batched Repository-Update FacilityThe data repository associated with each CMAS contains the definitions thatestablish your CICSPlex SM environment. You can create and maintain thesedefinitions by using either the CICSPlex SM EUI views or the batchedrepository-update facility. This facility is invoked from the EUI for the bulkapplication of CICSPlex SM definitions to a CMAS data repository.

Instead of using multiple view screens repeatedly to create a large number ofdefinitions, you can create an input file to add the definitions to the datarepository all at one time.

3.1.7 Application Programming InterfaceCICSPlex SM provides an API that allows applications to access informationabout CICS and CICSPlex SM resources and to invoke the services of CICSPlexSM. The API is another way of accessing CICSPlex SM, and you can combine itsuse with the CICSPlex SM user interface.

3.1.8 Business Application ServicesBusiness Application Services (BAS) is a component of CICSPlex SM that isresponsible for managing the CICS resource definition and installation processfor business applications. BAS, an alternative to resource definition online(RDO), enables you to manage CICS resources in terms of the businessapplication to which they belong, rather than by their physical location in theCICSplex.

3.2 Migrating CICSPlex SM to a New ReleaseAs CICSPlex SM becomes more and more prevalent throughout the industry interms of dynamic transaction routing and CICS systems management, there areseveral issues surrounding the operational characteristics of the product. Moreand more users are finding different ways of using the CICSPlex SM and hencemigration of the product no longer centers around migrating the CICSPlex SMcomponents, CAS, CMAS, and MAS. Migration also involves the migration of the

Chapter 3. Migration in a CICSPlex SM Managed CICSplex Environment 19

supporting environment where CICSPlex SM is used, including such routines asalert processing, environment backup, and region automation. In particular theCICSPlex SM API is now being used for greater control of the CICS environmentand therefore brings its own migration procedures and guidelines.

3.2.1 CMAS and MAS MigrationThe first subject we discuss is the main CICSPlex SM migration procedure. Thisprocedure was explained in detail in the CICS Transaction Server for OS/390:Version 1 Release 2 Implementation Guide redbook. We do not discuss theprocedure at length here as the principles remain the same. However, whenmigrating CICSPlex SM to any new release, it is important to follow a few simpleguidelines:

1. The maintenance point CMAS must always be migrated first.

2. The connected CAS, CMAS, and MASs set must be running at the same levelper MVS.

These ″restrictions″ obviously impose certain ways in which migration can becarried out so as to avoid migrating the whole MVS environment at one time.

The correct migration path is to implement temporary CMASs and selectivelymigrate regions one at a time to the new CAS/CMAS environment as shown inFigure 2 on page 21. The steps of the migration process are:

1. Create a temporary CMAS on the MVS where the maintenance point existsand add it to the CMAS topology of the CICSplex (for example, ADD it to theCPLEXDEF for PRODPLEX).

2. Create a temporary CAS.

3. Move the local MASs to the new temporary CMAS by specifying theCMASSYSIDNT parameter in the EYUPARMS.

4. Migrate the maintenance point CMAS to CICSPlex SM level that is providedby CICS TS 1.3.

5. Migrate the CICSPlex SM agent code in the MASs one by one and thenswitch them back to the newly migrated CMAS.

6. Remove the temporary CMAS when complete.

Repeat these steps for each MVS image where a CMAS resides.


Figure 2. Recommended CICSPlex SM Migration Process

3.2.2 Data Repository MigrationThe data repository migration process has remained the same through most ofthe releases of CICSPlex SM. The process consists of running EYU9XDUT withthe old data repository and creating a new one (see Figure 3).

//DREPCNVT EXEC PGM=EYU9XDUT,// COND=(8,LT),// PARM=(′ TARGETVER=0140′ )//STEPLIB DD DISP=SHR,// DSN=CICSLA13.CPSM.SEYUAUTH//EYUDREP DD DISP=OLD,// DSN=CICSSYSF.CPSM130.EYUDREP.SCSCPCA1//NEWREP DD DISP=OLD,// DSN=CICSSYSF.CPSM140.EYUDREP.SCSCPCA1//SYSPRINT DD SYSOUT=*//*

Figure 3. CICSPlex SM Data Repository Migration JCL

Note: It is easier to migrate the data repository if the CICSPlex SM releasenumber is somewhere in the data set name, as in the example in Figure 3. Thisensures that you can have two ″l ive″ data repositories if necessary, and the JCLcan remain the same if you use a symbol for the CICSPlex SM release qualifier(for example, CPSM140).


3.3 Split CICSplexesOne of the biggest issues surrounding the migration of CICSPlex SM is the needto migrate in a piecemeal fashion. When migrating CICSPlex SM take care not tomigrate the product directly into production. Being ″in production″ can havemany meanings when discussing CICS and CICSPlex SM. Conventionally a CICSsystem is in production when it is being used for a production workload,something on which the business depends. However, CICSPlex SM can be saidto be ″in production″ even when it is managing a ″test″ CICSplex. Why?Because the TESTPLEX may have service level agreements to be attainedand/or be deemed a ″production system″ for application developers. Thereforeyou should understand what ″in production″ means to you and migrate CICSPlexSM accordingly.

Consider the example in Figure 4. Here we have an environment where twoMVS images are being used to distribute the work from three environments:production, test, and development.

Figure 4. CICSPlex SM Configuration Where Maintenance Points Are Split

In this example we can see that the CMASs are arranged in such a way as toprovide an almost impossible migration path. The CMASs share the workloadacross all defined CICSplexes,and as such the maintenance points are alsoshared across the two CMASs. This causes problems when migrating CICSPlexSM. If the rules already outlined are to be obeyed, the new version of CICSPlexSM will be migrated directly to the production environment—something to avoidwhenever possible. Figure 5 on page 23 shows a slightly less complexenvironment where the maintenance points for all CICSplexes are now withCMAS1. Although the complexity of migration is reduced, we are still left withthe fact that CMAS1 is the maintenance point for all CICSplexes. Therefore


when we migrate the CICSplexes, we migrate them directly to production, so wehave to migrate the maintenance point CMAS first. Other issues here concernreliability and stability relating to mixing CICSplexes with the same CMAS.Ideally you should operate on the premise that the production environmentremains independent of the development and test environments, so that you canisolate changes from the production platform. After all, migration is not the onlyactivity you will perform against the CMASs; there can also be regularmaintenance and/or service updates to apply.

Figure 5. Reduced Complexity Configuration

Figure 6 on page 24 shows an ideal environment where production,development, and test have been split at the CMAS level.


Figure 6. Ideal CICSPlex SM Configuration

You may want to further split your CMASs and have one per CICSplex. Thisapproach is not unusual and typically depends on the characteristics and servicelevel agreements that are in place for your test environment. Some users treattest almost as a preproduction environment and expect the same stability goals.

In general, however, users tend to split to at least two levels of CMAS, one forproduction and one development and test. Medium-size enterprises tend tomaintain no more than about three CICSplexes. It is not our intention to go intogreat detail about how many CICSplexes you should define. The numberdepends on your environment and what you feel comfortable managing. Followthe guidelines in the CICSPlex SM Concepts and Planning Guide. In addition tothe advice given there, consider the following:

• Before creating your CICSplex environment, have a plan for migration - will itwork with what you have created?

• Are you going to use BAS to control your resource definitions? How will youhandle moving CICS definitions from one CICSplex to another? The fewerCICSplexes you have, the easier this is.

• If your operation spans multiple countries, do you need to physically split theCICSplexes to one per country?

• When deciding on the maintenance point CMAS, remember that you cannotchange this at a later date unless you delete the entire CICSplex. Also,ensure that the maintenance point CMAS has one of the lowest CICSSYSIDNTs of the connected CMASs, to reduces the ″chatter″ that passesfrom CMAS to CMAS.


3.4 Backing up the EnvironmentMore and more CICSPlex SM sites are now invoking methods to protect theirCICSPlex SM resources. In particular, the CICSPlex SM Data Repository is seenas one of the fundamental resources to back up.

There are a number of ways to back up the CICSPlex SM data repository:

• Close the EYUDREP file and REPRO it to another data set.

This is a fairly risky backup method as the CICSPlex SM data repository is acontinually used file. More data is written to EYUDREP than just CICSPlexSM definitions.

• Use CICS backup while open (BWO) processing.

Because this is a straight file copy it would also copy any corruption in thefile.

• Extract the definitions through BATCHREP, using the CICSPlex SM DUMPcommands.

This method is reliable but involves user interaction.

• Extract the definitions from the BATCHREP, using the API.

This process can be executed from batch easily as part of an automatedprocess, and it copies only the extracted definition, not any corruption in thefile.

Figure 7 illustrates a suggested backup process.

Figure 7. Suggested Backup Process for CICSPlex SM Data Repository


For sample code to back up and restore the CICSPlex SM data repository, seethe CICSPlex SM Web site,http://www.software.ibm.com/ts/cicsplex/downloads/api .The examples there perform two tasks, BACKUP and RESTORE:

• CPSMBACK

To be run against the CICSPlex SM environment frequently (for example,once per day) to extract the CICSPlex SM resource definitions from the datarepository and write them to a sequential data set. The data set namingconvention should be changed inside the EXEC. The system date isautomatically concatenated to the data set name, hence the suggestion torun CPSMBACK once a day.

Usage: CPSMBACK

• CPSMREST

To be run when required, to restore the CICSPlex SM data repository to thelevel of the backup sequential data set. Run CPSMREST only against anewly initialized repository or a repository where the existing CICSplex canbe deleted. This EXEC deletes the existing CICSplex.

Usage: CPSMREST

• CPSMRES2

Similar to CPSMREST, except it can take a parameter of RESET. CPSMRES2with no parameter ″merges″ the definitions on the sequential data set withan existing CICSplex definition. CPSMRES2 with the RESET option deletesthe CICSplex if it already exists before redefining it with the old definitionsstored on the sequential data set.

Usage: CPSMRES2 <parameter>

where <parameter> = RESET i f required

All of these samples have been created fairly easily on the basis of EYU#API3supplied sample that is shipped in CPSM140.SEYUSAMP.

3.5 Utilities Using the CICSPlex SM Application Programming InterfaceThe following utilities used with CICSPlex SM are either created by the userthrough the API or downloaded from the CICSPlex SM pages on the Internet (seeFigure 8 on page 27):

Such utilities are:

• CMAS shutdown

The recommended way of shutting down a CMAS is through either the CMASEnd User Interface view or an appropriate API program.

• Application quiesce

• MAS shutdown

• Data repository backup/restore

As discussed in the previous section.

• Automated alert response

An automated mechanism for responding to and performing actions whenCICSPlex SM alerts are issued to the console or NetView.


Figure 8. Possible Util i ty Applications Running with CICSPlex SM API

When you migrate utilities that use CICSPlex SM functions, the only issue iswhether or not the procedure uses the CICSPlex SM API. If the automationprocedure does not use the CICSPlex SM API, no migration action is necessary.If the automation procedure uses the API, the procedure might be updated onlywhen the CMAS with which the API is communicating has itself been migrated.

Follow these rules for API migration:

• If you do not want to enhance your application to exploit new CICSPlex SMfunctions, you do not have to do anything.

• If you want to change your application to use new functions:

1. Compare the resource table sizes in the old and and new releases. Usethe CICSPlex SM Resource Table Reference and refer to the length valuefor the required base table (object). Change this value where necessary.

2. Change the CICSPlex SM version number specified on the VERSIONparameter of the CONNECT verb (Figure 9).

EXEC CPSM CONNECTCONTEXT(W_CONTEXT)SCOPE(W_SCOPE)VERSION(0130)THREAD(W_THREAD)RESPONSE(W_RESPONSE)REASON(W_REASON) ;

Figure 9. CICSPlex SM API CONNECT Verb

Once these changes have been made, you can use the new version of the utilitywith CICSPlex SM.


3.6 Data Repository Definitions across ReleasesOne migration issue is how CICSPlex SM handles cross-releases workingtogether in the same CICSplex. Suppose we have the example shown inFigure 10, where two CMASs take part in the management of PRODPLEX. Withthe advent of CICS TS 1.3, new CICS BTS attributes have been added (seeFigure 10 and Figure 11).

Figure 10. Cross-Release Operation of CICSPlex SM CMASs

Figure 11. CICSPlex SM New Attributes for the CICS BTS

The main events that alter how the new definitions are handled can be dividedinto what happens at definition time and what happens at workload build time.Definition time is when your WLMSPEC, TRANGRP, and WLMDEFs are actually


created and the definitions spread out to other CMASs from the maintenancepoint. Workload build time is when the first CMAS starts up and sees that it hasa workload to install against a router, or a target, or a conventional TOR.

3.6.1.1 Definition TimeWhat happens when CICSPlex SM resources are defined has remained the samesince CICSPlex SM 1.1. Resources are defined to the maintenance point andpropagated out to the various other CMASs in the CICSplex for addition to theirdata repositories. But what happens if the other CMASs are at a backlevel anddo not support some of the new attributes defined at the new CMAS? Thenonsupported attributes are ″transformed out″ at the target CMAS so that theCMAS stores only the information on its data repository that it actually knowsabout or understands. Now suppose the following:

1. CICS regions on MVS1 use CICS BTS functionality and hence can takeadvantage of the new affinity types and durations.

2. CICS regions on MVS2 are still at CICS TS 1.2 (or below) and hence knownothing about CICS BTS affinities and durations.

3. All regions take part in workload NEWWORK.

4. The CMAS on MVS1 is the maintenance point and owns the definitions forthe workload.

5. When NEWWORK workload is defined on CMAS1, it has a WLMDEF assignedto it that contains a PROCESSTYPE. This PROCESSTYPE is defined as ′*′,that is, this WLMDEF does not relate to a specific PROCESSTYPE.

6. A TRANGRP is defined and specified as having a BAPPL affinity type with aPROCESS lifetime.

7. Now, when the workload definitions are shipped across to CMAS2 (CICSPlexSM 1.3), the remote CMAS does not know anything about CICS BTS processtypes or affinities and the definitions are added to the remote CMAS DREPusing the rules for WLMSPEC and TRANGRP definitions in Figure 12 and forWLMDEF in Figure 13 on page 30.

Figure 12. CICSPlex SM WLMSPEC and TRANGRP Definition Processing

Note: Currently the definitions are handled according to the rules outlinedin Figure 12. However, there are plans to ship an APAR to CICSPlex SM 1.3to alter the way in which the processtype is transformed out of the definitionand to improve the related messages issued at the console.


Figure 13. CICSPlex SM WLMDEF Definition Processing

3.6.1.2 Workload Build TimeHow the workload is actually built depends on which requester, router or TORregion is started first and to which CMAS it is connected. Referring to Figure 13,you can see that the process and resulting installed workload will be different.The rules in Figure 14 on page 31 are then followed.


Figure 14. CICSPlex SM Workload Bui ld Processing Rules

When the workload has been correctly built, further regions may be started onother MVSs and thereby affect processing. Depending on the level of the owningCMAS, the workload may behave differently from what you expect.

3.6.1.3 Detailed Flows of CICSPlex SM WLM ProcessingFigure 15 shows the flow of CICSPlex SM build processing.

Figure 15. CICSPlex SM Workload Bui ld Processing

Figure 16 on page 32 shows the flow of CICSPlex SM join processing.


Figure 16. CICSPlex SM Workload Join Processing

Figure 17 shows the flow during the ad hoc WLMDEF or TRANGRP installationinto an active workload.

Figure 17. CICSPlex SM WLMDEF or TRANGRP Install Processing

To enable seemless migration of your CICSplex from CICSPlex SM 1.3 toCICSPlex SM level provided by CICS TS 1.3, keep your CICS BTS workload


separate from other workloads. Thus you can share your existing workloadsacross CICSPlex SM releases. Otherwise you will have to understand whycertain definitions are rejected or ignored when you try to install CICSBTS-related definitions. Alternatively the two types of definitions can live side byside if you have more than one workload active. Perhaps you can create a newCICS BTS-related workload and have that workload installed in the CICSplex.This workload would of course be active against a new BTS set of(requester/router/target) regions.

3.7 Workload ManagementWLM in general behaves like any other part of CICSPlex SM. However CICSPlexSM WLM also has a concept of an owning CMAS for the workload, and, shouldcommunication to the owning CMAS be lost, the workload elsewhere is put intoa FROZEN state. This FROZEN state indicates that you cannot change anycharacteristic of the workload until contact with the owning CMAS is restored.The owning CMAS is defined as the CMAS whose TORs become active first forthe workload (WLMSPEC). This may or may not be the maintenance pointCMAS. So there are a few points to remember when migrating the CMAS as faras WLM is concerned:

• Ensure that you know where the owning CMAS is. The location can be foundin the WLMAWORK view under the Ownr column (see Figure 18).

� �30/11/1998 19:01:09 ----------- INFORMATION DISPLAY ---------------------------COMMAND ===> SCROLL ===> HALFCURR WIN ===> 1 ALT WIN ===>>W1 =WLMAWORK==========SCSPLEX==ALLCICS==30/11/1998=19:01:08====CPSM==========1CMD Name Ownr Rout Targ Affinity Lifetime Target Event Status Cre Alg--- -------- ---- Cnt- Cnt- -------- --------- Scope--- Name---- ------ Aff --- SCSWS01Q PCA1 2 5 NONE NONE SCSCG001 ACTIVE N/A QUE� �

Figure 18. Owning CMAS Reference on WLMAWORK View

• Ensure that you understand the effects of bringing down this CMAS.

• Ensure that you do not try to install work into the workload while this regionis unavailable, otherwise you will get a FROZEN response on the WLMDEFinstall.

• The owner of the workload will remain the same until all MASs using theworkload have been quiesced and the CMASs recycled.

3.8 Business Application ServicesBusiness Application Services definitions behave in much the same way as WLMdefinitions in terms of new attributes. If new attributes or new resources areavailable to a new release of CICSPlex SM, those attributes and resources areavailable only to systems that also run on that same release of CICSPlex SM.


3.9 Resource Object Data Manager InterfaceThe resource object data manager (RODM) interface capability of CICSPlex SMhas been available since CICSPlex SM 1.2. It is implemented as a set ofNetView automation tasks (AUTOTSKs). The key to migrating a RODMimplementation is to migrate the RODM communication components as soon asthe RODM CMAS has been migrated. The activities involved are:

1. Upgrade the RODM CMAS in the normal fashion.

2. Upgrade the NetView procedure (CNMPROC) to include the new CICSPlexSM load libraries.

It is not necessary to upgrade or stop or restart the GMFHS component(CNMGMFHS).

3. Upgrade any RODM AUTOTSK changes necessary as a result of the newCICSPlex SM level. (See the CICSplex SM Setup Guide for information aboutthe RODM setup procedure).

4. Stop and restart the NetView procedure (CNMPROC) to include the newlibraries and restart the AUTOTSK.

5. Stop and restart the NetView Subsystem to Subsystem Interface (CNMPSSI).

Note: It is not possible to run a CICSPlex SM 1.3 RODM environment against aCMAS on the CICS TS 1.3 level of CICSPlex SM because the communication flowis outbound from the CMAS. The NetView AUTOTSK is not a CICSPlex SM APIprogram.

3.10 Tivoli Global Enterprise Manager InterfaceThe Tivoli Global Enterprise Manager (GEM) for CICS (TGMC) became availablein mid-1998 and is now shipped with CICS TS 1.3. The TGMC works as anapplication program within NetView, using the CICSPlex SM API forcommunication with CICSPlex SM. Therefore the migration issues andtechniques discussed earlier are also applicable here.

Note: It is possible to run a TGMC from a CICSPlex SM 1.3 environment againsta CMAS on CICS TS 1.3 level of CICSPlex SM because the communication flowis inbound to the CMAS using the API.


Chapter 4. Coupling Facility Data Tables

CICS CFDT support is designed to provide rapid sharing of working data within asysplex, with update integrity.

4.1 CICS Data Table SupportCICS data table support has evolved over the years to provide optimized accessto different types of data.

The original data table support (which was available as a separate orderablefeature of CICS/MVS V2 and as an integral part of CICS/ESA V3) was optimizedfor direct access to keyed data.

Two kinds of data tables are supported: CICS Maintained Tables (CMTs) andUser Maintained Tables (UMTs). CMTs provide high performance for read-onlyaccess to the data set, and any changes made to the data are reflected in theunderlying VSAM source data set. UMTs provide high performance for all of theallowed types of access to the data (direct reads and updates), but any changesmade to the data apply only for the lifetime of the data table and are notreflected in the underlying VSAM source data set. This support was thereforecomplementary to the normal use of VSAM, providing highly efficient access to aspecific kind of data.

Shared data table support (which was available as a separate orderable featureof CICS/ESA 3.3 and now as an integral part of CICS/ESA V4 and CICS TS) isoptimized for shared access, both sequential and direct, to keyed data. Itachieves this using cross-memory sharing, so that all CICS regions within anMVS image can read and browse a data table without the overhead of functionshipping.

Shared data table support superseded the original support but still provided twotypes of shared data tables. CICS-maintained shared data tables provide highperformance for read-only operations (both direct and sequential) and normalperformance for update operations (through function shipping for other CICSregions in the MVS image, or through VSAM access within the region that ownsthe CMT). User-maintained shared data tables provide high performance forread-only operations (again, both direct and sequential) from other CICS regionsin the MVS image, and for all allowed operations within the region that owns theUMT.

Shared data table support also extended the subset of allowed operations for aUMT, and this subset was further extended in CICS TS so that almost all of thefile control API relevant for access to VSAM key-sequenced data set (KSDS) datais now supported (only WRITE with MASSINSERT and the use of the RBA optionare not allowed).

For more details on shared data table support, refer to the CICS Shared DataTables Guide.


4.2 Coupling Facility Data Table SupportCFDT support provides a means of sharing data with update integrity across aParallel Sysplex, by storing the data in a coupling facility list structure andaccessing it through the coupling facility services provided by MVS. Figure 19on page 37 shows the use of CFDTs within a Parallel Sysplex.

A CFDT is a new kind of data table. It is an adjunct to the existing CMTs andUMTs, which use shared data table support. It behaves rather like asysplexwide form of UMT, but it does not provide any equivalent of the CMTwithin a sysplex. The functional equivalent of a CMT within a sysplex isachieved through VSAM RLS.

CFDT support is tailored toward the sharing of ″informal″ data (this term isexplained in more detail later). It provides access to data that is based on keyedrecords, which is of particular use where the information has to be indexed,accessed directly by an identifier (the key), browsed in key sequence order, oraccessed imprecisely by an identifier (that is, by specifying key GTEQ orGENERIC). It allows shared read and write access to the data. Keyed data alsomeans that there is a large name space within each CFDT by which resources(records) can be identified, so separate applications can each use a separatetable and identify different pieces of information within the table, using the key.

CFDT support uses the file control API, an existing API that provides a rich set offeatures, including update integrity (READ UPDATE) and imprecise key access(READ GTEQ, READ GENERIC) and browsing (STARTBR, READNEXT). With thefile control API, applications that use CFDT support within a sysplex can also rununchanged on other releases of CICS or on other CICS platforms.

CFDT support offers particular advantages to customers who have already beenusing UMTs to share informal data with key lengths of up to 16 bytes, becausethe existing applications can run in a sysplex simply by changing the filedefinition to specify a CFDT rather than a UMT.

In the same way that user-maintained shared data tables offer a fasteralternative to function shipping for sharing informal data within an MVS, CFDTsoffer a faster alternative to RLS for sharing informal data within a sysplex.

CFDT support is not intended to provide the same level of function as VSAMRLS. It provides optimized access to shared data with a subset of the RLSfunction. Some of the features that CICS support for RLS provides, but CFDTsupport does not include, are guaranteed permanency of the data, support foralternate indexes, and forward recovery logging.

Shared data table support provides sharing within a single MVS image by usingMVS cross-memory services to access data stored in an MVS data table. Thepathlengths involved are very short. CFDTs provide sharing across a ParallelSysplex by using coupling facility interfaces to access data stored in a couplingfacility structure. It is to be expected that the pathlengths involved here aresomewhat longer.

CFDTs do have an advantage that should be of particular benefit for theirintended use. The performance of update requests is comparable to that of read(and browse) requests, whereas with shared data table support the performanceof read requests is much better than that of updates.


Figure 19. Coupling Facility Data Tables within a Sysplex

4.3 Overview of Informal Shared DataThe characteristics of informal shared data are that it is not very long-term (it iseither created as the application is running or initially loaded up from somesource); there are not usually very large amounts of it; access to it needs to befast; and often the loss of the data, or the absence of commit consistency, can betolerated by the application.

It is also a common requirement that the data can be read by one transactionand written to by another at the same time, and that it provides update integrity;that is, if one transaction updates the data, another will not be allowed to make aconflicting update.

The term ″informal shared data″ encompasses a variety of data, includingscratchpad data, control records, keyed data, and shared queues, and a variety

Chapter 4. Coupling Facility Data Tables 37

of data access, including read-only, single or multiple updaters, sequential orrandom access, and random insertion and deletion.

4.3.1 ExamplesHere are some examples of ″informal shared data″.

• A unique number to be allocated each time an application performs aparticular function

• A look-up table of items to which an application needs access, such astelephone numbers or the numbers of stolen credit cards

• Working data consisting of a few items, such as the set of customers fromthe full customer list who are currently of interest

• Small amounts of data, taken from some larger file or data base, that needfurther processing

• Information that ″belongs″ to the user of the application or relates to theterminal where the application is running

4.3.2 Methods of Sharing Informal DataThese are traditional ways to share informal data.

• CICS common work area (CWA) (application-oriented and applies within asingle CICS region)

• MVS common storage area (CSA) (widely used, but not recommended)

• COMMAREA (terminal-oriented)

• UMTs

• TS data sharing

• VSAM RLS (geared more toward formal permanent data)

4.4 CFDT BenefitsA primary benefit offered by CFDT support is performance, which will be good forall normal operations (read, write, rewrite, delete) for reasonable record lengths(up to around 4 KB) in comparison with other means of sharing data within asysplex.

Access requests to CFDTs use the existing file control EXEC level API, using asimilar subset to that supported for UMTs. Thus CFDT support is easy to useand offers an easy migration path. The support provides compatibility withexisting applications; if applications are written to take advantage of new CFDTfeatures, they can run unchanged against files that do not use CFDT support.

The required lifetime of informal data depends on how it is used, but it is usuallydesirable for the lifetime to last at least as long as the transactions running theapplication that uses the data are likely to be active. In a sysplex environment,where applications may run on any CICS region, the lifetime of the informal dataclearly should not depend on any one region (such as the region that originallycreated it). A CFDT will persist in the coupling facility until either it is explicitlydeleted or the coupling facility structure in which it resides fails (which is thetype of rare event that is usually regarded as acceptable for informal data).


If a CICS region fails, most access from other regions can continue withoutimpact. With nonrecoverable CFDTs, all access can continue. With recoverableCFDTs, some records may remain locked (thus ensuring data integrity). If anMVS system fails, the CICS regions running in other MVS systems in the sysplexcan continue to access the CFDT, and new work can be routed to those systems.

4.5 Restrictions and CautionsProbably the most significant restriction of CFDT support is that it applies only todata that has keys of up to 16 bytes. This is a restriction of the coupling facilityarchitecture.

Any applications that use CFDTs must recognize that the CFDT will not survive ifthere is a failure of the coupling facility or of the coupling facility structure wherethe CFDT resides.

Although CFDTs are similar in behavior to UMTs, there are a number ofdifferences that you have to take into consideration when migrating applicationsthat use UMTs to CFDTs:

• When a file defined as a UMT is closed, the data table is deleted. When thefile is next opened, a new UMT is created and reloaded from its source dataset. With a CFDT, there can be more than one file that refers to a table, andwhen any or all of the files are closed, the CFDT will continue to exist. Inthis respect, a CFDT is more like a CMT. (A CMT is deleted when the last ofthe files in the file-owning region (FOR) that refers to it is closed, but when itis next opened it is loaded with the same data it contained when it wasdeleted.)

• The access rule for a UMT that is being loaded is that any direct readrequest will be satisfied (from either the table or the source data set), butany update or imprecise read or browse will be rejected with the LOADINGcondition. For a CFDT, any request is allowed during loading, but only thosethat can be satisfied from the range of records already loaded will succeed.

• With UMTs, the performance of read accesses is a little better than theperformance of updates within a single region and quite significantly betterthan for updates with cross-region sharing. In contrast, the performance ofCFDT update requests is similar to that of read requests, so it is notnecessary for an application to access data with a high read-to-update ratioin order for it to benefit from CFDT support.

4.6 FeaturesTo obtain the maximum performance while still providing update with integrity,CFDT support allows a table to elect to use an update strategy that avoids theoverhead of acquiring locks and guarantees no lock waiting. This option isknown as the contention update model, and it can be selected on an individualtable basis. It applies to all accesses to the CFDT, rather than being an optionspecified on each request.

A requirement that Parallel Sysplex users have identified is the need to separateproduction and development data and control structures within the sysplex.CFDT support satisfies this requirement by allowing groups of CFDTs to be heldin entirely separate coupling facility structures, called CFDT pools, eachmanaged by separate CFDT server regions.


It is not necessary for the user to take any action to create a CFDT. This will bedone automatically when the first file that references the table within the sysplexis opened.

Because informal shared data is often created by the applications as they run,CFDT support offers the choice (for each table) either to load the CFDT withsome initial data from a source data set (after which the CFDT is detached fromthe source data set, as also occurs for UMTs) or to start with a ″clean sheet″ andnot have to specify a source. If the first option is chosen, this will be doneautomatically by CICS when the CFDT is first opened and created.

Recoverability of a CFDT can be provided. This is again selectable on aper-CFDT basis. Unit of work recovery is provided from all types of failures(including transaction failures and CICS failures) except from a failure of thecoupling facility structure or the coupling facility where the table resides, inwhich case all CFDT data is lost.

4.7 How CFDTs Are AccessedCFDTs are held in coupling facility structures. These structures allow relatedgroups of CFDTs to be kept separate from other tables by storing them inseparate pools; for example, an installation might use one pool for productionand another for test. From an application point of view, a pool is similar to anFOR and may contain any number of tables, provided that each table has aunique name.

A CFDT pool is a coupling facility list structure, and access to it is provided by aCFDT server. A CFDT server is similar to a shared data table ′s FOR in terms ofthe function it performs, and it is operationally similar to a TS data sharingserver. For any given CFDT pool, there must be a CFDT server in each MVS thatwants to access it. CFDT pools are defined in the coupling facility resourcemanagement (CFRM) policy, and the pool name is then specified in the startupJCL for the CFDT server. Refer to Figure 19 on page 37 for a conceptual view ofCFDTs within a sysplex.

A CFDT is accessed from CICS through file control API commands. The filename specified on the command identifies the file through which the CFDT isaccessed, and the file definition specifies which CFDT is to be accessed. TheCFDT is uniquely identified by its name and the name of the pool where itresides. Both the pool name and table name are specified on the file definition;the pool name is always specified explicitly, and the table name can be specifiedeither explicitly or implicitly by allowing it to default to be the same as the filename.

When the first file that specifies a given CFDT name and pool name is opened,the CFDT is automatically created. After this, any other file definitions thatspecify that CFDT name and pool name access the same CFDT, with a separateopen established for each file (even when the files are within the same CICSregion).


4.8 ServersThe CFDT server runs as a separate address space within an MVS image, aseither a started task or a batch job. If all of the CFDTs are in a single pool, onlyone CFDT server is needed in each MVS image in the sysplex. If the CFDTs aredivided into two separate pools, two CFDT servers are needed in each MVS, andso on.

The CFDT server runs in a non-CICS address space, so it requires littlemanagement or maintenance. The execution environment for CFDT serverregions is provided by a run-time package called the Authorized Cross-Memory(AXM) server environment. The AXM server supports CFDT server regions andcross-memory connection services. This environment is also used by the TSdata sharing server.

The CFDT servers have a small number of parameters that are usually alwaysspecified. These include the pool name, the security checking that is required,and the statistics to be produced. Also, the pool size and maximum number oftables within the pool can be specified when the list structure is first created(otherwise the parameters take the default values). Figure 20 shows the initialvalues of the parameters. (Note that SECURITY usually defaults to YES, but itwas changed to NO in this sample while testing was in progress.)

� �14.30.48.56 DFHCF0201I Processing DISPLAY INIT14.30.48.56 DFHCF0211I Parameter value: POOLNAME=TESTCFT114.30.48.56 DFHCF0211I Parameter value: SECURITY=NO14.30.48.56 DFHCF0211I Parameter value: SECURITYPREFIX=NO14.30.48.56 DFHCF0211I Parameter value: STATSOPTIONS=NONE14.30.48.56 DFHCF0211I Parameter value: ENDOFDAY=00:0014.30.48.56 DFHCF0211I Parameter value: STATSINTERVAL=03:0014.30.48.56 DFHCF0211I Parameter value: POOLSIZE=512K14.30.48.56 DFHCF0211I Parameter value: MAXTABLES=5

� �Figure 20. DISPLAY of Initialization Parameters

The CFDT server regions typically do not require any special tuning, but a full setof tuning parameters is provided to allow the servers and CFDT pools to betuned if required. There are parameters to turn on debug tracing, to specify alist element size different from the default, to determine the proportions of thecoupling facility structure space that are allocated to data elements and list entrycontrols, and to determine the actions when the structure is becoming too full(that is, at which point warning messages will be issued and at which point theCFDT server will automatically start performing XCF ALTER actions).

Apart from specifying parameters in the startup JCL, you can also manage CFDTservers through MVS operator commands that enable you to stop (gracefully) orcancel (suddenly) the servers and display table status, statistics, and otherinformation.

The CFDT server issues messages of the form DFHCFnnnn. These messagesalso appear where appropriate in the CICS job log. Messages are also issuedby AXM.


4.9 Setting Up CFDT SupportFollow these steps to set up CFDT support:

1. Plan how many tables and pools are needed.

2. Define the list structure in the CFRM policy.

3. Activate the CFRM policy.

4. Initialize AXM services.

5. Start DFHCFMN server regions.

6. Change file definitions to use CFDT.

Steps 4, 5, and 6 need not be done in the order given, but all three steps mustbe completed for CFDT support to become active.

4.9.1 Plan How Many Tables and Pools are NeededThe initial step in using CFDTs should be to plan the setup, including whichapplications need to use CFDTs, and whether the CFDTs are to be divided upinto separate pools, or whether a single CFDT pool will be used at theinstallation.

4.9.2 Define List Structure in CFRM PolicyBefore a CFDT pool can be used, a definition statement for the list structuremust be added to the current CFRM policy, specifying the size of the structureand the preference list of coupling facilities where it should be stored. Figure 21shows a sample definition that serves as input to the IXCMIAPU utility.

� �STRUCTURE NAME(DFHCFLS_TESTCFT1)

SIZE(2048)INITSIZE(512)PREFLIST(CF01,CF02)

� �Figure 21. Sample CFRM List Structure Definit ion

4.9.3 Activate CFRM PolicyThe name of the list structure must be of the form DFHCFLS_poolname, whereDFHCFLS_ is a predicated prefix, and poolname is the user-chosen name of theCFDT pool. The CFRM policy is defined through the IXCMIAPU utility. After thenew policy has been created, it is activated by this command:

SETXCF START,POLICY,POLNAME=policy_name,TYPE=CFRM

4.9.4 Initialize AXM ServicesBefore any cross-memory connections can be established within an MVS image,AXM services must be initialized in that image. To initialize AXM services, youdefine a subsystem called AXM whose initialization routine, AXMSI, sets upsome appropriate definitions from the master scheduler region. The AXMsubsystem is usually defined statically in the IEFSSNxx member of


SYS1.PARMLIB with the following command to ensure that AXM system servicesautomatically become available at IPL time:

SUBSYS SUBNAME(AXM) INITRTN(AXMSI)

If an installation is already using TS data sharing, AXM services will already bein use, and no further action is necessary for CFDT support. You can also defineAXM dynamically, using this command:

SETSSI ADD,SUBNAME=AXM,INITRTN=AXMSI

4.9.5 Start DFHCFMN Server RegionsA CFDT server region can be started either as a started task or as a batch job,defined by startup JCL (see Figure 22).

� �//CFSERVER EXEC PGM=DFHCFMN//STEPLIB DD DISP=SHR,DSN=CICSTS13.CICS.SDFHAUTH//SYSPRINT DD SYSOUT=*//SYSIN DD *POOLNAME=TESTCFT1SECURITY=NOMAXTABLES=5/*

� �Figure 22. Sample JCL to Start CFDT Server

The server region program is DFHCFMN, and it must be loaded from anauthorized library, such as the CICS SDFHAUTH library. The startup JCLspecifies the program name as DFHCFMN, the authorized library, the pool name,and a few other parameters. To ensure that all pool-related parameters areconsistent across MVS images, use the same SYSIN parameter data set forservers for that pool (and specify server-specific parameters in the PARM field).Figure 23 shows a typical startup.

� �11.41.07 DFHCF0101I CF data table server initialization is in progress.11.41.12 DFHCF0401I Connected to CF structure DFHCFLS_TESTCFT1.11.41.12 IXL014I IXLCONN REQUEST FOR STRUCTURE DFHCFLS_TESTCFT1

WAS SUCCESSFUL. JOBNAME: SC53CFD1 ASID: 00A3CONNECTOR NAME: DFHCFCF_SC61 CFNAME: CF01

11.41.12 AXMSC0051I Server DFHCF.TESTCFT1 is now enabled for connections.11.41.12 DFHCF0102I CF data table server for pool TESTCFT1 is now active.

� �Figure 23. Messages Issued during Startup of CFDT Server

Use the JCL REGION parameter to ensure that the CFDT server region hasenough storage to process the maximum number of data table requests that canexecute concurrently.

If a task in the server region or a cross-memory request runs out of storage,AXM is likely to terminate that task or request using a simulated abend withsystem completion code 80A to indicate a GETMAIN failure. Although the servercan usually continue processing other requests in this case, running out of


storage in a critical routine can cause the server to terminate. Therefore, it isbest to ensure that the REGION size is large enough to eliminate this risk.

The number of CFDT requests that each connected CICS region can have activeat a time is limited to about 10. Each request requires about 40 KB, so theREGION parameter should specify at least 400 KB for each connected CICSregion, plus a margin of about 10% for other storage areas. For a serversupporting up to five CICS regions, you would need to specify REGION=2200K.

During server initialization, the server acquires all available storage above 16MB, as determined by the REGION parameter (and restricted by the IEALIMITand IEFUSI exit routine modules), and then releases 5% of it for use by operatingsystem services. It also acquires 5% of the free storage below 16 MB for use inroutines that require 24-bit addressable storage, for example, sequential file readand write routines.

After initialization, the server uses AXM page allocation services to manage itsstorage. Server statistics indicate how much storage is actually allocated andused within the storage areas above and below 16 MB, which are calledAXMPGANY and AXMPGLOW, respectively.

Figure 24 shows the messages issued at initialization for a server region thathas been started with region size of 96MB and the subsequent statistics for AXMfrom a DISPLAY POOLSTATS command.

� �AXMPG0001I The main free area above 16M was at address 08E2A000, size 98136K.AXMPG0003I Storage page pool AXMPGANY created, address 08E2A000, size 93108K.AXMPG0002I The main free area below 16M was at address 008000, size 7856K.AXMPG0003I Storage page pool AXMPGLOW created, address 008000, size 388K.

AXMPG0004I Usage statistics for storage page pool AXMPGANY:Size In Use Max Used Free Min Free

93108K 636K 640K 92472K 92468K100% 1% 1% 99% 99%

Gets Frees Retries Fails26 2 0 0

AXMPG0004I Usage statistics for storage page pool AXMPGLOW:Size In Use Max Used Free Min Free388K 12K 12K 376K 376K100% 3% 3% 97% 97%

Gets Frees Retries Fails3 0 0 0

� �Figure 24. AXM Storage Statistics

4.9.6 Change File Definitions to Use CFDTNew file definitions should be created, or old ones changed, to specify the filesthat are to access CFDTs. You can use RDO or use SET FILE to change aninstalled file to specify that it will use a CFDT until the next CICS cold or initialstart. See 4.13, “Definition” on page 48 for a description of how to use RDO todefine a CFDT.


4.10 OperationsOnce you have set up the CFDT pools and CFDT servers, very little effort shouldbe required to keep things running smoothly. The only time the CFDT server islikely to fail and need to be restarted is when the coupling facility or couplingfacility structure that it uses fails. The CFDT server always terminates if itdetects a coupling facility failure or coupling facility connectivity failure. Youmust restart the server manually once the failure has been resolved.

The CFDT server provides a number of commands that enable you to control andmanage the server and its CFDTs. You issue the commands through the MVSMODIFY command (for which the abbreviation is F), specifying the job name orstarted task name of the server region and the function to be performed. Thegeneral form of the commands is therefore:

/F server,command parameter, parameter. . . comments.

4.10.1 Server CommandsThe server commands include:

• SET commands to change parameter values or the server ′s recovery status

• DISPLAY commands to display information about tables, connections, UOWs,parameters, and statistics

• PRINT - same output and keywords as DISPLAY, but output appears on theprint file only

• DELETE TABLE=name - deletes a named CFDT, provided that it is not inuse; that is, no regions have files open against that table

• STOP command to terminate the server (waiting for any active connectionsto terminate first)

• CANCEL command to terminate the server immediately

4.10.2 Server Unload and ReloadA mechanism is provided for doing a nondestructive unload of the contents of aCFDT pool to a sequential file and for subsequently reloading the contents backinto a coupling facility structure. A CFDT pool is unloaded by running the serverprogram, DFHCFMN, with a FUNCTION parameter of UNLOAD, rather than thedefault of FUNCTION=SERVER. Similarly, reload involves running the serverwith FUNCTION=RELOAD.

Figure 25 on page 46 shows some sample JCL for running an unload.


� �//CFSERVER EXEC PGM=DFHCFMN//STEPLIB DD DISP=SHR,DSN=CICSTS13.CICS.SDFHAUTH//DFHCFUL DD DSN=CICSRS1.CFDT.UNLOAD3,// DISP=(NEW,CATLG),// SPACE=(4096,(1000,500))//SYSPRINT DD SYSOUT=*//SYSIN DD *POOLNAME=TESTCFT1FUNCTION=UNLOAD/*

� �Figure 25. Sample JCL for Unload of CFDT

You can use the unload mechanism to preserve the CFDT pool across a plannedcoupling facility outage (for maintenance, for example) or to move the pool to adifferent coupling facility. No other access to the coupling facility list structure ispossible during unload or reload, so all CFDT servers must be stopped duringthe UNLOAD/RELOAD.

A CFDT server cannot be stopped while CICS regions are connected to it, but itis possible to use the CFDT server CANCEL command to terminate the server ifthe CICS regions cannot be brought down. If no tables are in use at the time ofthe CANCEL, this will be the equivalent of a clean shutdown.

4.11 Sample CFDT Server CommandFigure 26 shows the output from issuing commands to display two named tables.

� �DFHCF0201I Processing DISPLAY TABLE=FILEADFHCF0363I Details for table FILEA: Attributes: Recsize Keylength Max recs Upd Model Init Load

80 6 1000 LOCK YESStatus: Available Open mode Access Sharing Loaded

YES R/W SHR R/W YESStatistics: Users Servers Opens Records

3 0 5 45DFHCF0303I DISPLAY command has been processed.

DFHCF0201I Processing DISPLAY TABLE=FILECONDFHCF0363I Details for table FILECON: Attributes: Recsize Keylength Max recs Upd Model Init Load

80 6 1000 CONT NOStatus: Available Open mode Access Sharing Loaded

YES NONE SHR NONE YESStatistics: Users Servers Opens Records

0 0 2 4DFHCF0303I DISPLAY command has been processed.

� �Figure 26. Output from Two DISPLAY TABLE Commands

The FILEA data table was created when the first file referring to it was opened.Init Load is YES, which indicates that the data table was preloaded from asource data set.


The Recsize (80) and Keylength (6) are taken from the file definition when it wascreated. Note that the original source file had a record format of fixed, but therecord format had to be changed to variable when it was redefined as a CFDT.The Max recs figure shows that an upper limit of 1000 records has been placedon this data table. Max recs would be NO if no limit were placed on the numberof records.

The Upd Model of LOCK indicates that this table uses the locking model. TheCFDT server displays one of three update models: CONT (for the contentionmodel), LOCK (for the nonrecoverable locking model), or RECOV (for therecoverable locking model).

The Status line shows that this CFDT is available for new opens, that its openmode allows read/write access, that it is currently open with shared access (asopposed to exclusive access, which would be seen while a loadable CFDT wasbeing loaded), and that it allows a shared access level of R/W sharing. TheCFDT server supports a rich set of options for the types of access and sharingallowed by a data table, but CICS uses only a subset of these options.

Loaded is set to YES, if this table had just been opened for the first time.Loaded would be displayed as NO until the data table completed loading fromthe source data set.

In the statistics line, the Users column shows that three files are open againstthis table (probably, but not necessarily, indicating that three separate CICSregions have the table open). The Servers column is zero because this is anonrecoverable table. This figure would be nonzero only for a recoverable tableand the number then indicates the number of server regions that have the tableopen for internal access. The Opens column shows that the data table has beenopened five times since it was created. There are 45 records currently in thetable.

The FILECON data table was created based on the file definition for FILEA butwith LOAD(NO), so Init Load is NO, indicating that the table does not needpreloading from a source data set, and Loaded is YES from the first open of thetable.

Because this is a nonloadable CFDT, the Recsize and keylength will have beentaken from the file definition when it was created. The Max recs figure showsthat an upper limit of 1000 records has been placed on this data table. Max recswould be NO if there were currently no limit placed on the number of records.

The Upd Model is CONT for a table using the contention model.

The Status line shows that this CFDT is available for new opens, but the NONE inthe Open mode column as well as the zero in the Users column indicate that thistable is not currently open.

The Opens column shows that the table has been opened twice since it wascreated. There are four records currently in the table.


4.12 Initial LoadWith CFDT support, it is no longer necessary (as it is with shared data tables) tospecify a source data set from which the table is to be initially loaded. If a CFDTis defined as LOAD(NO), it does not have to be loaded, but it will start off emptyand be populated by the application programs as they run. Some attributes ofthe data table are obtained from the source data set when one exists. Anexample would be the keylength. Such attributes must therefore be specified onthe file definition for a nonloadable CFDT. All file definitions in the sysplex thatrefer to this CFDT must have matching attributes.

CFDT support also allows a CFDT to be initially loaded with data from a sourcedata set. A CFDT will automatically be loaded with records from a source VSAMKSDS when the first file that references the table in the sysplex is opened. A filethat uses a CFDT can be defined either as load-capable, in which case it willspecify LOAD(YES) and a data set name on the file definition (or in a DD card onthe CICS startup JCL), or as requiring the data table to have already beenpreloaded before it can open, in which case the file definition would specifyLOAD(YES) but no source data set. In the latter case, the file opens will fail untilone of the load-capable files for this CFDT has been opened. This option couldbe used if only certain CICS regions in the sysplex have access to the sourcedata set, or as a means of determining which will be the file that causes theCFDT to be created.

The rules about access to a CFDT that is still being loaded differ slightly fromthose for a UMT: All types of requests are allowed, including updates, butrequests will only be satisfied if they are for a key that is within the range ofrecords that have been loaded. Requests for keys that have not yet been loadedwill fail with a LOADING condition. Applications might therefore want to waituntil loading is complete before starting, to ensure a consistent result on allrequests. To determine whether a CFDT is still loading, an application couldissue a read for a key of all X′FF′s. If the read returned a record or (more likely)a NOTFND condition, that would indicate that the CFDT had completed loading.If it returned a LOADING condition, that would indicate that the CFDT was stillbeing loaded, and if the file failed to open, that would indicate that the CFDT hadnot yet started loading.

Remember that once it has been created, a CFDT persists until it is deleted orthe coupling facility fails, so the initial preload of a CFDT should be a relativelyrare event, rather than being required on every CICS startup.

4.13 DefinitionRDO is used both to define CFDTs and to define files that will use those CFDTs.A CFDT is created when the first file that names it in its file definition is opened.The attributes of the CFDT will be taken from that file definition (together withattributes from the source data set if there is one). Figure 27 on page 49 showsan abbreviated RDO definition with those parameters that are relevant for CFDT.


� �CEDA View File( FILEA ) File : FILEA Group : CFTESTF DEScription :VSAM PARAMETERS DSNAme : CICSSYSF. CICS530. PAA1. FILEA

.

.

.REMOTE AND CFDATATABLE PARAMETERS RECORDSize : 00080 1-32767 Keylength : 006 1-255 (1-16 For CF Datatable)CFDATATABLE PARAMETERS Cfdtpool : TESTCFT1 TABLEName : FILEA UPDATEModel : Locking Contention | Locking LOad : Yes No | YesDATA FORMAT RECORDFormat : V V | F

.

.

.RECOVERY PARAMETERS RECOVery : None None | Backoutonly | All Fwdrecovlog : No No | 1-99

� �Figure 27. Excerpts from an RDO Definition of a File Using a CFDT

Once a CFDT has been created, other files that name it will access and use it. Ifany of these other files have attributes in their file definition that conflict withthose of the CFDT, an error will occur when the file is opened (or a warning inthe case of the MAXNUMRECS attribute).

A file will either create or use a CFDT if the TABLE parameter is specified as CF.If TABLE(CF) is specified and any of the other required parameters have beenomitted, an error will be raised. However, it is permissible to specify some ofthe CFDT parameters on a file definition that does not currently specifyTABLE(CF), to make it easy to switch file definitions between CFDTs, UMTs, andnon-data-table files.

A CFDT is identified by its name and its CFDT pool name (in other words, if thereare two CFDTs of the same name, but in different CFDT pools, they are distinctand separate tables).

If the file definition does not explicitly give a CFDT name, the name will, bydefault, be the same as the file name. This example explicitly gives file FILEA atable name of FILEA in the pool TESTCFT1, but it would have defaulted to thatanyway.

If the CFDT is loadable, its recordsize and keylength will be taken from thesource data set when it is opened. Otherwise, the recordsize and keylengthmust be supplied by the file definition. Because these two parameters alsoapply to remote file definitions, the RDO DEFINE FILE panel has been altered tosplit these two parameters off from the other two remote file attributes. Notethat CFDTs can only have a variable record format, the definition will fail with anerror message if F is given as the record format, even if that is the format of thesource file.


Consideration needs to be given to parameters on the file resource definitionthat allow the system programmer to control such items as the maximumnumber of records in a CFDT (which may be set to some ceiling value to avoid a″runaway″ CFDT using up all the coupling facility storage).

The Update Model parameter is used to specify whether a CFDT will use thecontention model (which is optimized for performance) or the locking model(which provides full API compatibility). If the Locking model has been specified,then the file may also be defined to be recoverable (RECOVERY ofBACKOUTONLY can be specified, but not RECOVERY(ALL) - forward recovery isnot supported for CFDTs.)

A ″mismatch of attributes″ error will occur if an attempt is made to open a filethat refers to an existing CFDT and the file definition contains attributes thatdiffer from those of the CFDT.

4.14 APIThe API for CFDTs is based almost exactly on that used by UMTs, which is itself(having been slightly enhanced in CICS TS 1.1) very close to the standard filecontrol API.

CFDT support offers two different update strategies. Each CFDT can choosewhich of these strategies (or ″update models″) to adopt:

The LOCKING model is the default. It allows existing applications to run in asysplex simply by changing the file definition to specify a CFDT rather than aUMT, offering an easy migration path. With the locking model, records arelocked when they are read for update so that no other UOWs can change themuntil the update has been completed. With the locking model, it is possible for aCFDT to be defined as recoverable.

The CONTENTION model avoids the overhead of acquiring locks and guaranteesno lock waiting. In this novel approach, a transaction attempting to update arecord is informed whether the record has been changed (or deleted) since itwas read for update, rather than the transaction locking the record to preventchanges. This model introduces a new condition, CHANGED, which can bereturned on REWRITE or DELETE if the record has been changed by anothertransaction since it was read for update, and indicates that a NOTFND conditioncan be returned on REWRITE or DELETE if the record has been deleted byanother transaction since being read for update. As well as allowing newapplications to benefit from the optimized performance (by coding them tohandle the response indicating the record has changed), the option could alsobenefit any existing applications which are designed such that they could neverencounter any contentions (for example, because each transaction only everupdates the record or records that relate to the terminal at which it is running).If new applications are written to exploit this optimization, they can then rununchanged with a file definition which does not specify CFDT support.


4.15 CEMT Transaction and SPIThe INQUIRE and SET FILE commands have been extended to provide supportfor CFDTs, and a new INQUIRE command has been introduced to provideinformation on connected CFDT server pools.

On INQUIRE FILE, new parameters have been added to report on thecharacteristics of the file that are related to CFDT support:

• A TYPE of CFTABLE indicates that this file uses a CFDT.

• The TABLENAME parameter returns the name of the CFDT.

• The CFDTPOOL parameter returns the name of the CFDT pool in which thetable resides.

• The LOADTYPE indicates whether or not the CFDT requires loading from asource data set.

• The UPDATEMODEL indicates whether the CFDT is using the LOCKING orCONTENTION model.

• The LOADTYPE and UPDATEMODEL return NOTAPPLIC for non-CFDT files.

• The KEYLENGTH and RECORDSIZE return either the value from the filedefinition, or, if the file is open and the CFDT is loadable, the values are fromthe source data set.

• The BASEDSNAME and DSNAME will be blank for a file that is notload-capable.

All of the new parameters can be set using SET FILE. If the file is not currentlydefined as a CFDT, the CFDT-specific parameters can still be set, and theirvalues will take effect if the file is changed so that it is defined as a CFDT.

A new INQUIRE CFDTPOOL command will return information on CFDT pools thatthis CICS region knows about (that is, all CFDT pool names that are referred toin installed file definitions). If the command is used in browse mode, it willreturn the names of all CFDT pools that are known to this CICS and theirconnection status. If a specific CFDT pool is named on the command, itsconnection status will be returned if it is known to CICS, or POOLERR will bereturned if it is not.

The connection status can be:

• CONNECTED: CICS is currently connected to the pool.

• NOTCONNECTED: The CFDT server for this pool is available (that is, up and running), but CICS is not connected to it.

• UNAVAILABLE: The server for the pool is not currently available.

A list of all the files using a given CFDT pool (and the names of the tables theyare using) can be obtained by issuing INQUIRE FILE(*) CFDTPOOL(poolname).


4.16 Recovery SupportIt is possible to specify that a CFDT (that uses the locking model) is recoverable.The level of recovery is backout only; forward recovery is not supported.Although the performance of a recoverable form of informal data will notcompare favorably with that of a nonrecoverable form, some applications requirerecoverability; that is, it is important to them that the informal data is not affectedby loss of a CICS or an MVS, and that transactions that have updated suchinformal data will back out the updates if they fail and will be able to participatein in-doubt failure support.

The level of recovery support provided for CFDTs is referred to as ″unit of workrecovery″ or ″transactional integrity″. Support is provided for recovery fromfailures of transactions, CICS regions, and MVS systems. The recovery supportfor CFDTs does not include recovery from a failure of the coupling facility or ofthe coupling facility structure in which the CFDTs reside. If either of these fails,all information for the CFDTs is lost, and they will be created afresh the nexttime they are opened.

Unit of work recovery is provided for CFDTs by recovery support within the CFDTserver, and by code within CICS file control that makes use of the CICS RecoveryManager. Recoverable access to a CFDT pool from a UOW is represented withinCICS as an RMC (Recovery Manager Connector) link. If a UOW fails, the state ofthe unresolved CFDT recovery work will be displayed on the INQUIRE UOWLINKcommand.

4.17 PerformanceThe primary function of CFDT support is to enable information to be sharedbetween CICS regions within a Parallel Sysplex with better performance thanfull-function file-sharing solutions and with better availability than functionshipping solutions.

The performance of CFDT requests is primarily determined by the number ofcoupling facility accesses (see Figure 28 on page 53). As a rough example(assuming a typical complimentary metal-oxide semiconductor (CMOS)configuration), the pathlength of a request might be of the order of 5-7 thousandper coupling facility access plus an additional figure of around 2 thousand perrequest, depending on the operation being performed and the processing thatthe CFDT server has to do.

The figures for recoverable operations include the processing that is performedat syncpoint for each operation. There is also some processing that isperformed at syncpoint for the UOW as a whole, and this is shown in a separaterow.

The performance of recoverable CFDTs will also incur additional overheadswithin CICS. Note that when the record length exceeds 4094 bytes (which is 4096bytes less an internal 2-byte prefix), the coupling facility access will becomeasynchronous, and the performance will be degraded as a result.


Figure 28. Number of Accesses to Coupling Facility per Function

4.18 SecurityAccess to CFDT pools is controlled with RACF (or an equivalent external securitymanager). Each CFDT server region must be given access to its associatedcoupling facility list structure by giving it ALTER access to a RACF resource inthe FACILITY class called IXLSTR. structure. The server region also needsCONTROL access to a resource called DFHCF. poolname, and any CICS regionthat is to be allowed to access CFDTs in that pool must be given UPDATE accessto that resource.

Access to CFDTs can optionally be controlled by performing security checkseach time a CICS region connects to a new CFDT within a pool to which italready has access. This resource checking is based on that adopted for shareddata tables, using class FCICSFCT with the CFDT name, optionally prefixed bythe server region′s userid if the SECPREFIX=YES option is specified for theserver. Therefore a RACF level that supports cross-memory FASTAUTH is aprerequisite.

Normal CICS file security will apply to the files that refer to CFDTs.

4.19 User ExitsThe existing data table global user exit points are invoked by CFDT support.XDTRD is invoked when a CFDT is being loaded from its source data set, aseach record is added to the table, and can be used to select records forinclusion in the CFDT, and to modify the record so that its contents in the CFDTdiffer from those on the source data set. Therefore XDTRD is invoked only in theregion that first opens and loads the CFDT and will never be invoked for a CFDTthat is not loaded from a source data set.


XDTLC is invoked at the completion of loading a CFDT, whether successful orotherwise, and can be used to decide whether to accept a partially loaded CFDT(in which case requests no longer get the LOADING condition for records thatare not in the table). If the XDTLC exit is not enabled, the default action is not toaccept the CFDT if loading failed. The partially loaded CFDT will still exist in theCFDT pool unless it is explicitly deleted (so another open might be able to pickup and complete the load), but this file will be closed, thus preventing access tothe CFDT by applications that use it. XDTLC will only ever be invoked for a filethat performs the initial load of a CFDT.

XDTAD is invoked when a record is being written to a CFDT by an applicationprogram request, and it can be used to decide whether or not to include therecord in the CFDT.

A new indicator in the flags byte of the data table′s user exit parameter list,DT_UE_PLIST, indicates whether the exit has been invoked by CFDT support.User exit programs may need to be aware when the exit has been invoked byCFDT support. The table name parameter in DT_UE_PLIST will contain the nameof the CFDT and not the name of the file (unless they are the same).

4.20 StatisticsStatistics are gathered for a CFDT in the same way as for other kinds of datatables. Statistics relating to use of the CFDT are included in the data table fieldsof the File Control statistics record, which is mapped by the DSECT DFHA17DS.The statistics report produced by DFHSTUP, the statistics utility program, has aseparate portion within the file control section that shows data table statistics.

The example in Figure 29 shows an extract from a hypothetical solicitedstatistics report. It shows the header for the data table portion along with thestatistics for two data tables.

Figure 29. Sample Output from the CICS Statistics Report

MYSDT is a shared data table. It is mainly used for read access (so it may wellbe a CMT). The type of data table is actually shown in the ′ResourceInformation′ portion of the statistics, which includes such information as the timethe file was opened and the data set name (if there is one). The Adds fromReads figure shows the records being added when the source data set wasloaded.

CFDT2 is a file that is defined to use a CFDT. It is a contention CFDT that is notloaded from a source data set. Note that the statistics shown for CFDT2 reflectaccesses to the CFDT made through filename CFDT2 from this CICS region. Thefigures for Read Requests and Add Requests show that it is used for quite a bitof updating in addition to read accesses. If this were an unsolicited statisticsreport, produced as a result of closing CFDT2, the Close Type would be K,indicating that the statistics have been gathered as the result of closing a filethat uses a contention-model CFDT (L would indicate a locking-model CFDT file).


There are a few differences between the statistics for a shared data table andthose for a CFDT.

The last column in the statistics report shows the number of changed responsesfor a contention CFDT, like CFDT2 (this is the number of REWRITES or DELETESrejected because the record had changed). For CFDTs using the locking model,this column shows the number of lock waits (and for shared data tables it wouldshow the number of read retries).

The count of records not in the table (Recs ¬ in Table) indicates for a shareddata table the number of times a read had to be satisfied by accessing thesource data set rather than the table. For a CFDT it just indicates the number ofNOTFND responses received on requests to the CFDT server.

For a shared data table, the majority of the statistics appear in the data-table-owning region, with only a few of the statistics in the AOR (such as thenumber of Get Requests) being nonzero. For CFDTs, the statistics in all regionsthat access the CFDT will show a similar pattern.

In addition to the CICS statistics, the CFDT server provides table andpool-related statistics, for example, through the DISPLAY POOLSTATS commandas shown in Figure 30

� �DFHCF0432I Table pool statistics for CF structure DFHCFLS_TESTCFT1: Structure: Size Max size Elem size Tables: Current Highest

512K 2048K 256 3 3 Lists: Total In use Max used Control Data

42 40 40 37 3100% 95% 95% 88% 7%

Entries: Total In use Max used Free Min free Reserve457 59 59 398 398 100100% 13% 13% 87% 87% 22%

Elements: Total In use Max used Free Min free Reserve443 52 52 391 391 300100% 12% 12% 88% 88% 68%

Fwdrecovlog : No No | 1-99

� �Figure 30. Results of a DISPLAY POOLSTATS Command

4.21 MonitoringMonitoring of record management accesses to CFDTs is through the existing filemonitoring fields. Some new performance class data fields have been added tomonitor waits for CFDT processing. Field-ID 176 in the DFHFILE group(CFDTWAIT) monitors the time spent waiting for a request to a CFDT to completein the server. This includes waits on open or close requests, recordmanagement requests, and statistics requests. Waits for such requests will onlyoccur if the request has to be processed asynchronously. Field-ID 177 in theDFHSYNC group (SRVSYWTT) monitors the time spent waiting for a syncpointrequest to complete in the server, or for the server to completeresynchronization processing.


New exception data is also written for CFDTs if the maximum number of requestslots is exceeded. To control the flow of work to the coupling facility, a limit isplaced on the number of requests each CICS region can have active in the CFDTserver at any one time. If this maximum is exceeded, any new requests mustwait until one of the existing requests frees up a slot by completing itsprocessing within the server. These request slots are divided up into two types,to ensure that requests that go into lock waits do not prevent other types ofrequests from being accepted.

4.22 When to Use CFDTIn this section we consider when CFDTs would be the best technique to use forsharing data. We cover four main kinds of informal data (scratchpad, sharedqueues, control records, and keyed data), along with a number of techniques forsharing the data (see Figure 31 on page 57). The techniques available forsharing informal data using CICS include the TWA, CWA, and MVS CSA, whichare for the most part historical techniques that have been replaced by better ormore flexible alternatives: TS queues, UMTs, and now CFDTs. In the case of TSqueues, these may be either local (accessed directly within the same region),remote (accessed through function shipping), or shared (accessed through TSdata sharing servers). Similarly, UMTs may be either local (either accessedwithin the same region or directly using shared data table cross-memorysharing), remote (accessed through function shipping, which is, for example,required to update a shared UMT), or replicated (individual shared UMTs withineach MVS image in a sysplex).

The choice of technique depends primarily on whether sharing is required purelywithin a single region, between CICS regions running within a single MVS image,or across a Parallel Sysplex. The choice of technique also depends on anumber of constraints, such as the kind of access required, for example, is it justread-only, is update from multiple regions required, will records be inserted anddeleted randomly, is unit of work recovery support required? Provided that otherconstraints will be satisfied, the decision also depends on the technique that isin use by existing applications, because it is easier to migrate an application to atechnique that uses the same or a similar API.

The following considerations also affect the decision to use CFDTs for any of thefour kinds of informal shared data:

• The CFDT maximum key length is 16 bytes.

• CFDT performance is best when the coupling facility access is synchronous,which is only possible for record lengths that do not exceed 4094 bytes (4096less an internal 2-byte prefix).

• Contention CFDTs perform better than locking CFDTs, typically requiring onlyone coupling facility access for each request. However, the contentionmodel does require application logic to handle the CHANGED condition,unless if the application structure automatically ensures that only one taskcan update each record at a time (for example, if the record relates to aspecific terminal session).

• Shared TS queue performance degrades when coupling facility accessbecomes asynchronous, which occurs when the total queue size exceeds4096 bytes (which includes a 2-byte prefix per item). Further overheadsoccur when the total queue size exceeds 32768 bytes, at which point thequeue is converted to use the large queue format. (for more details on


shared TS queues, refer to the CICS Release Guide for CICS TS Release 1and CICS System Definition Guide.

• TS data sharing does not support any form of serialization that allows morethan one task to update a queue without risking to lose updates, so it is notsuitable for applications that require update integrity.

Figure 31. Summary of When to Use CFDTs

4.22.1 Scratchpad DataScratchpad data is typically used to pass data from one part of a transaction toanother part of the same transaction. Only one task accesses the data at a time,but the data may be passed from a task in one region to a task in another.

Note that the term Remote UMT means a shared UMT that is accessed fromAORs either through function shipping where this is necessary (that is, for allupdate accesses) or shared data table cross-memory sharing where possible(which will be for most nonupdate accesses).

Figure 31 shows that within a Parallel Sysplex, CFDTs are the best solutionwhere random insertion and deletion of data are required and where multipletypes of data need to be stored. Without these constraints, shared TS queuesare a more appropriate choice if the applications are currently using temporarystorage.


4.22.2 Shared QueuesThis case covers applications where information is stored in a specific sequence,and is to be processed by another program or task in the same sequence.Although the techniques recommended in many cases are the traditional CICSqueuing facilities, namely transient data and temporary storage, there are someinstances of sequenced data where data tables provide a more appropriatesolution.

4.22.3 Control RecordsThis case covers applications where a central control record is used to makeinformation visible to all transactions. For example, this record may contain thenext unused order number or customer number, to make it easier for programsto create new records in a keyed file or database.

Figure 31 on page 57 shows that within an MVS image, if there is a singleregion that makes all the updates to a single record, a UMT can be used withoutany function shipping overhead.

Where there are multiple regions updating the control record or there is morethan one control record to update, a CFDT is the only solution within a ParallelSysplex environment, and it may be that it is more effective than functionshipping the updates to a UMT within a single MVS.

CICS TS 1. 3 also introduces the named counter server, which is a sort ofspecialized form of CFDT server that is of use for certain applications that needa shared control record to provide a counter. For appropriate applications, thenamed counter server provides the best technique for sharing control records ina Parallel Sysplex. See Chapter 6, “The Named Counter Sequence NumberServer” on page 75 for more details.

4.22.4 Keyed DataThis case covers applications that use information similar in structure to aconventional keyed file, but the information does not have to be storedpermanently, and the performance benefits are sufficient to justify the use ofmain storage or coupling facility resources to store the relevant data.

Keyed data is most appropriately accessed through techniques that use the filecontrol API, so that within a Parallel Sysplex the solution is to use replicatedUMTs where the highest performance is required and where access is eitherread-only or it can be arranged that updates are only made from a single region.Otherwise use a CFDT.

Note that the recovery support for UMTs is limited to transaction backout after afailure. For CFDTs, recovery across CICS or CFDT server failures and forin-doubt failures is also provided.

4.23 Simple Demonstration of Using CFDTsSee 4.9, “Setting Up CFDT Support” on page 42 for the steps to follow to makeCFDT support available.

We used FILEA sample applications and definitions as a basis for testing CFDTs.These applications are described in the CICS Sample Applications Guide.


The records in FILEA are particularly suitable for this CFDT demonstrationbecause they are few in number (43 on initial load) and they have a keylength of6. Refer to Figure 32 on page 60 for the configuration we used during the test.

We defined and loaded FILEA using the supplied programs in library SDFHSAMP.

4.23.1 First Open Causes Initial Load of CFDTWe RDO-defined FILEA in region PFA1. We:

• Supplied the DSNAME

• Specified TESTCFT1 as the pool name

• Explicitly defined the tablename as FILEA

• Chose Locking as the Updatemodel

• Set Load to Yes

• Specified no recovery

We then ran one of the sample transactions (AINQ). This caused the file to beopened. CICS determined that the file was a CFDT and, because this was theinitial access, loaded the data into table FILEA in pool TESTCFT1. The tablecould then be read and written to. Note that after the initial load, the file dataset is no longer accessed, and any changes to the data are not reflected back tothe data set.

We then RDO-defined FILEA in region PAA4 with exactly the same definition aswe used on PFA1. (This definition can omit the DSNAME because the data hasalready been loaded, but all other attributes have to match exactly.)


Figure 32. Layout of Test Configuration

4.23.2 Example of LockingWith FILEA defined as a table with an Updatemodel of Locking we ran some teststo illustrate that a record cannot be updated while another transaction isupdating it.

Using CECI transaction we did a a READ for UPDATE on record ′005005′ in FILEAin region PAA4 and then in PFA1 we attempted to run the AUPD transaction onthe same record. Because the transaction was defined with a timeout value, itabended with an AFCY and the message shown in Figure 33 was produced tohelp diagnosis.

DFHFC7130 10/23/98 16:04:11 SCSCPFA1 AUPD 00186 068C CICSUSER. Unit of work X′ B13F39D391E42C05′ running in regionSCSCPAA4 in MVS system SC62 holds a lock on key X′ F0F0F5F0F0F5′ in coupling facility data table FILEA in poolTESTCFT1, which caused this request to wait.

Figure 33. Message Produced for Lock on Key


4.23.3 Remote AccessCFDT tables can be accessed from regions that do not have CFDT support bydefining a table as remote and owned by a region that does have CFDT support.

FILEA was defined in region PAA2 (a CICS 4.1 region) as a remote file owned byPFA1. The sample transactions could then be run in PAA2 and access the CFDTtable FILEA without PAA2 being aware that CFDT support was being used. Allthe accesses to the table are done by PFA1.

Although this does enable CICS 4.1 regions to participate in CFDT support, theusual remote file access restrictions are in place. The file access is done as afunction ship, and the mirroring task is used in the remote system. So, when aLocking test is done using CECI, the CSMI task waits, as does the AUPD task inthe originating PAA2 region. Figure 34 shows the wait on PFA1.

� �Tas(0000199) Tra(CSMI) Fac(X21 ) Sus Ter Pri( 001 )Sta(TO) Use(CICSUSER) Uow(B13F45A382F46105) Hty(CFDTWAIT)

� �Figure 34. Mirroring Task in CFDTWAIT

4.24 Access to Original Data SetIf you decide to load a CFDT from a data set, you must realize that the data inthe table and the data set will diverge from that moment.

In region PAA3 (a CICS 4.1 region) the definition for FILEA was unchanged fromthat provided in supplied RDO group DFH$FILA, with the exception that theDSNAME was completed. Any access in PAA3 was to that data set alone,changes made to CFDT by CICS TS 1.3 regions are not reflected to the originaldata set. On the other hand, those regions that accessed the CFDT FILEA afterthe initial load (CICS TS 1.3 regions) will not see any of the updates done byPAA3 (a CICS 4.1 region).

4.25 Same File Name, Different TableAlthough CICS programs will refer to a file name, the file could point to adifferent table name in the CF pool. (Also, although not illustrated in thisexample, the file could point to the same tablename but in a different CF pool.)

FILEA was RDO-defined in region PAA1. We:

• Did not provide a DSNAME.

• Specified the Poolname as TESTCFT1.

• Defined the Tablename as FILECON.

• Chose the Updatemodel to be Contention.

• Set Load to No.

• Specified no recovery.


Programs that access FILEA in region PAA1 will access an empty table calledFILECON in pool TESTCFT1 that uses the contention update model.

To emphasize this point, if FILEA is closed in PAA4 and PFA1, and it is thenredefined with the same definition as used in PAA1, the regions will access tableFILECON.

4.26 Example of ContentionUsing PAA1 and PAA4, which both have FILEA defined as table FILECON with anupdate model of contention, we ran the following test:

• We used CECI in PAA1 to issue a READ for UPDATE on a record in FILECON.

• We used CECI in PAA4 CECI to issue a READ for UPDATE on the samerecord in FILECON.

• We did an update in PAA4 to the record and a REWRITE was issued whichcompleted successfully.

• We did an update in PAA1 to the record and issued a REWRITE which failedwith a response of CHANGED (EIBRESP ′105′ and EIBRESP2 ′109′).

There are two points to note about this CHANGED error code. On a remotesystem running CICS TS, the EIBRESP2 is not returned and on a remote systemrunning CICS 4.1, the error code is simply ERROR. Figure 35 shows how FILEAwas defined in various regions.

Figure 35. Descriptions of FILEA per Region

4.27 ConclusionsCFDT provides a simple and robust method of sharing informal data. It can beused by applications that previously used other methods of sharing data, but youshould consider how applications will react in different scenarios. Here are somepoints to consider:

• Differences between locking and contention


• How remote access affects transactions

• Accessing a data set as a CFDT or a file

• One and only one load of table

• A filename maps to a unique poolname.tablename

• Table will exist until explicitly deleted


Chapter 5. Global Enqueue Dequeue

Sysplexwide enqueue extends the CICS TS API to provide an enqueuemechanism that serializes access to a named resource across a specified set ofCICS regions contained within a Parallel Sysplex.

Before CICS TS 1.3 ENQs issued within CICS had a ′scope′ that was applicableto the local CICS region only. Therefore for applications that required the use ofenqueuing, all of the enqueuing transactions had to run in the same CICS regionand as such constituted an affinity. With sysplex enqueue, the specific regionaffinity is no longer a restriction, as an ENQ can be issued and held across theentire MVS sysplex.

5.1 OverviewLocal enqueues within a single CICS region are still managed within the addressspace. Sysplexwide enqueues that affect more than one CICS region are nowmanaged by global resource serialization (GRS). This applies equally to aCICSplex within a single MVS image and to a CICSplex that resides in more thanone MVS. Existing applications can use sysplex enqueues simply by definingappropriate ENQMODELs, without any change to the application programs. Themain changes to the CICS enqueue and dequeue mechanism are:

• Sysplex enqueue and dequeue expand the scope of an EXEC CICS ENQ/DEQcommand from region to sysplex, by introducing a new CICS resourcedefinition type, ENQMODEL, to define resource names that are to besysplexwide.

• ENQSCOPE, an attribute of the ENQMODEL resource definition, defines theset of regions that share the same enqueue scope.

• When an EXEC CICS ENQ (or DEQ) command is issued for a resource whosename matches that of an installed ENQMODEL resource definition, CICSchecks the value of the ENQSCOPE attribute to determine whether the scopeis local or sysplexwide:

− If the ENQSCOPE attribute is left blank (the default value), CICS treats theENQ or DEQ as local to the issuing CICS region.

− If the ENQSCOPE attribute is nonblank, CICS treats the ENQ or DEQ assysplexwide, and passes a queue name and the resource name to GRSto manage the enqueue. The resource name is as specified on the EXECCICS ENQ/DEQ command, and the queue name is made up by prefixingthe four-character ENQSCOPE with the letters DFHE.

• All CICS regions that need to use the sysplexwide enqueue or dequeuefunction must have the required ENQMODELs defined and installed. Therecommended way to ensure this is for the CICS regions to share a CSD,and for the initialization GRPLISTs to include the same ENQMODEL groups.


5.2 Benefits of Sysplex EnqueueSysplex enqueue provides the following benefits:

• Eliminates the most significant remaining cause of intertransaction affinity.

• Enables better exploitation of a Parallel Sysplex, providing betterprice-to-performance ratio, capacity, and availability.

• Reduces the need to provide intertransaction affinity rules to any dynamicrouting mechanism, thereby lowering the systems management cost ofexploiting Parallel Sysplex.

• Removes a significant migration inhibitor by removing anotherintertransaction affinity problem.

• Makes it possible to serialize concurrent updates to shared TS queues bymultiple CICS transaction instances.

• Makes it possible to prevent interleaving of records written by concurrenttasks in different CICS regions to a transient data queue accessed byfunction shipping.

• Allows the single-threading and synchronization of tasks across the sysplex.It is not designed for locking recoverable resources.

5.3 ENQMODEL DefinitionTo take advantage of the new sysplexwide enqueue, no changes need to bemade to the application program. Instead, the system programmer uses a newdefinition to control the scope of an enqueue. RDO facilities (both CEDA andEXEC CICS CREATE) are used to define sysplexwide enqueues. Existingapplication ENQ requests can be modified from local to sysplex scope by theCICS system programmer defining a generic (or specific) ENQ name and acorresponding four-character ENQSCOPE name.

Figure 36 shows a sample RDO definition of an ENQMODEL.

� �CEDA View Enqmodel( GMODEL1 ) Enqmodel : GMODEL1 Group : GENQTEST Description : ENQScope : TES1 Status : Enabled Enabled | Disabled ENQName : GLOB*

::::

� �Figure 36. RDO Definit ion of an ENQMODEL


5.3.1 ENQNameThe ENQMODEL enqueue names will be from 1 to 255 characters to match theEXEC CICS ENQ RESOURCE length.

The ENQMODEL resource names can be generic names starting with a fixedprefix. Names ending in an asterisk (*) are treated as generic; that is ABC*would match a resource name of ABC or ABCDEF but not AB or ABED.

The asterisk is treated as a generic wildcard only when it appears as the lastcharacter of the ENQMODEL resource name. No other form of wildcard namematching is supported.

Unless specified by the XNQEREQ global user exit, the scope of a user stringenqueue is defined by the ENQSCOPE value of the most specific matchingENQMODEL.

5.3.2 ENQScopeThe value of ENQSCOPE defines to which group of CICS regions the enqueuebelongs. For instance ENQSCOPE could be set to TEST for all test regions andPROD for all production regions. If a resource were to be shared across theTEST and PROD regions, ENQSCOPE could be set to BOTH.

The four-character ENQSCOPE name for an enqueue or dequeue can be suppliedby either the ENQMODEL RDO table or the ENQ/DEQ global user exit. (See 5.9,“XNQEREQ and XNQEREQC Exits” on page 69 for further details.)

5.4 Installing ENQMODELSWhen installed, the ENQMODEL is put into the WAITING state until there are noenqueues in the local system that match the ENQNAME pattern. It is thenENABLED or DISABLED, as specified in the definition. When ENQMODEL isDISABLED or WAITING, matching ENQ requests are rejected, and the issuingtask abended with abend code ANQE (ENQ_DISABLED). WAITING indicates thatthere are matching INSTALL, CREATE, or DISCARD requests waiting to beprocessed.

An ENQMODEL definition can be removed from an active system by issuing of aCEMT DISCARD command or by removing it from the GRPLIST and restartingCICS either INITIAL or COLD.

ENQMODELs forming nested generic ENQNAMEs must be installed either in thedisabled state, or in order, from the most to the least specific. This restriction isnecessary to ensure data integrity. For example, if an ENQMODEL with AB* isenabled, it must be disabled or discarded before an ENQMODEL with ABCD* isinstalled. This restriction does not apply to GRPLIST install during a cold start.

5.5 INQUIRE ENQ SPI ChangesThe INQUIRE ENQ or UOWENQ command retrieves information about enqueues.Enqueues are used by CICS to lock recoverable resources such as file recordsor queues to the UOW that is updating them. User enqueues obtained by theEXEC CICS ENQ command are also returned.

Chapter 5. Global Enqueue Dequeue 67

The browse operation initiated by the START option of the INQUIRE commandcan be filtered in three ways:

• Supply a value for UOW on the INQUIRE START command to return only theenqueues held or waited on by the specified UOW.

• Supply a value for RESOURCE on the INQUIRE START command to returnonly information about UOWs owning or waiting on the specified enqueue.

• Supply a value for ENQSCOPE on the INQUIRE START command to returnonly enqueues with the specified ENQSCOPE. If ENQSCOPE is specified asblanks, only local enqueues will be returned.

A CICS-wide browse occurs when you do not supply a value for UOW,RESOURCE, or ENQSCOPE on the INQUIRE UOWENQ START command. Allenqueue owners and enqueue waiters on the local system are returned by thebrowse. They are returned by considering each UOW in turn. After all theenqueues owned by one UOW have been returned, those owned by the nextUOW in the system are considered.

As well as returning information about the owners of the enqueues, thecommand also returns information about UOWs that are waiting on theseenqueues. Thus you can diagnose enqueue deadlocks between tasks wanting toupdate the same resources. There is a significant performance improvementover the current method of answering the question: Which UOW is holding theenqueue? The user can then analyze the cause of the delay. User ENQs are notto be used to lock recoverable resources, as they are not held across a CICSfailure.

Note that INQUIRE ENQ or UOWENQ only returns information about UOWs on thelocal system. For enqueues with SYSPLEX SCOPE, the OWNER may be on thelocal system with some or all of the waiters elsewhere, or the OWNER may beelsewhere in the sysplex with some or all of the waiters on the local system. Inthis case, only the local waiters are returned.

5.6 New CEMT and SPI INQUIRE and SET ENQMODELThe INQUIRE ENQMODEL command retrieves information about ENQMODELresource definitions on the local system.

An explicit INQUIRE for a given ENQMODEL is provided as well as a browsemechanism using the standard syntax. All ENQMODEL definitions on the localsystem are returned by the browse.

The SET ENQMODEL command allows you to ENABLE or DISABLE ENQMODELresources installed on the local system. An ENQMODEL must be enabled toallow matching EXEC ENQ requests to be processed. It must be disabled toallow a more specific ENQMODEL to be enabled.

ENQMODELs forming nested generic ENQNAMEs must be enabled in order, fromthe most to the least specific.

You cannot enable or disable an ENQMODEL that is in the waiting state. Ifattempted, ′ INVREQ′ ′ENQMODEL_WAITING′ is returned to the caller.


5.7 New CREATE and DISCARD ENQMODELThe CREATE ENQMODEL command builds an ENQMODEL definition, withoutreference to data stored on the CSD. If an ENQMODEL of the name you specifyexists in the local CICS region, the new definition replaces the old one; if not, thenew definition is added. When CREATE is issued, the ENQMODEL is put into theWAITING state until there are no enqueues in the local system that match theENQNAME pattern. It is then ENABLED or DISABLED, as specified on CREATE.

ENQMODELs forming nested generic ENQNAMEs must be installed either in thedisabled state, or in order, from the most to the least specific. If anotherENQMODEL with the same or a less specific nested ENQNAME is alreadyinstalled enabled, ′ INVREQ′ ′DUPLICATE_ENQNAME′ is returned to the caller.

The DISCARD ENQMODEL command removes an ENQMODEL definition from thelocal CICS system. When DISCARD is issued, the ENQMODEL is put into theWAITING state until there are no enqueues in the local system that match theENQNAME pattern. It is then removed from the local system. Adding orremoving a definition does not affect enqueues already held, only EXEC ENQsissued after the definition is added or removed.

5.8 API SemanticThe API semantic is changed only if the resource name refers to a sysplexwideresource. Then the enqueue applies across the sysplex and the FIFO orderingfor dequeues is not necessarily preserved. The semantic of deadlock timeout ismaintained.

Sysplex and region scope enqueues use separate namespaces. A region scopeenqueue will never wait on a sysplex enqueue, and a sysplex scope enqueuewill never wait on a region enqueue.

There is no support for sysplex scope enqueue on an address.

Both UOW and TASK lifetimes for the enqueue are supported.

Conditional (using NOSUSPEND) and unconditional sysplexwide ENQUEUEs aresupported. The NOSUSPEND option ensures that the invoking CICS task is notput into a CICS WAIT.

Multiple enqueues on the same resource name issued by the same CICStransaction instance are allowed with the same semantics for dequeue that applyto the current single CICS region scope mechanism.

5.9 XNQEREQ and XNQEREQC ExitsThere is a new global user exit (XNQEREQ) to be invoked by DFHEKC before theexecution of an EXEC CICS ENQ or DEQ API call. This exit has been added toallow the four-character scope name to be added to an EXEC CICS ENQ or DEQrequest with a resource name. If ENQSCOPE is added by the exit, the RDO tableis not used. The exit can be used to specify the ENQSCOPE for thoseapplications that generate an ENQ name on the fly, where an ENQMODEL cannotbe defined in advance. The default scope, if not overidden by the exit and ifthere is no matching ENQMODEL definition, is local.


The new global user exit XNQEREQC can be invoked on completion of anenqueue API request to change a response.

Both region and sysplex scope are supported for string ENQs, but sysplex scopeis not supported for address ENQs. Sysplex enqueue assists only thoseapplication ENQs that are specified by name, and not those specified by address.

Use of XNQEREQ and XNQEREQC exits is a safe way to prevent test systemsenqueuing on resources used by production systems.

5.10 ENQ Deadlock HandlingBecause sysplex scope ENQUEUE supports deadlock timeout, there should be nopossibility of an unresolved deadlock across CICS systems.

If a CICS task fails, the ENQ domain releases all MVS ENQs held on behalf ofthat CICS task.

If a CICS system fails, MVS releases all MVS ENQs owned by that CICS region.This applies even if the reason for the CICS system failure was an MVS failure.

When there is a rogue task with enqueues held, which hangs or spins on thespot (but is not subject to runaway), the entire region can grind to a halt and theoperator will probably need to track down the chain of enqueues. This can bedone without, or more easily with, CICSPlex SM.

5.10.1 Without CICSPlex SMCEMT can be used to display all outstanding ENQs within a local CICS region.Figure 37 shows two tasks waiting; the first task owns a resource,GLOBALRESOURCE1, and has held it for 61 seconds (the Duration value). Thesecond task has been waiting for the same resource for 10 seconds. (The timespent waiting in this example is minimal but serves as an illustration of anowner and waiter within the same region.)

� �I ENQSTATUS: RESULTS Enq Uow(B144220A9DFA8700) Tra(CECI) Tas(0000441) Act Exe

Own Dur(00000061) Res(GLOBALRESOURCE1 ) Rle(015) Enqs(TES1) Enq Uow(B144223AF36BB003) Tra(RECI) Tas(0000446) Act Exe

Wai Dur(00000010) Res(GLOBALRESOURCE1 ) Rle(015) Enqs(TES1)

� �Figure 37. Results of CEMT I ENQ

If an enqueue is held by an owner outside a local CICS region, the operator candisplay resources within GRS. The DISPLAY command can be used with theRES=(qname,rname) parameter. For CICS enqueues, the qname always startswith DFHE and the last four characters are the ENQSCOPE name. The resourcename is the name of the resource enqueued upon. Figure 38 on page 71 showsthe result of a DISPLAY command to show all current enqueued resourcesowned by CICS. Note that this display shows only resource owners, not waiters.


� �D GRS,RES=(DFHE*,*)ISG343I 18.29.21 GRS STATUS 380S=SYSTEMS DFHETES1 GLOBALRESOURCE1SYSNAME JOBNAME ASID TCBADDR EXC/SHR STATUSSC61 SC53PFA1 0093 007DA3A0 EXCLUSIVE OWNS=SYSTEMS DFHETES1 GLOBALRES1SYSNAME JOBNAME ASID TCBADDR EXC/SHR STATUSSC62 SC53PAA4 0063 007D8308 EXCLUSIVE OWNS=SYSTEMS DFHETES2 GENQTESTSYSNAME JOBNAME ASID TCBADDR EXC/SHR STATUSSC61 SC53PFA1 0093 007DA3A0 EXCLUSIVE OWN

� �Figure 38. Results of D GRS,RES=(DFHE*,*)

Once the owner and waiter are identified, the operator can determine whetherone of these tasks needs to be purged to free the region. The effective use ofDTIMOUT on transactions should prevent this situation from occurring.

5.10.2 With CICSPlex SMCICSPlex SM tries to assist in determining which task to purge to free up thesystem. CICSPlex SM alows the customer to put out an alert when a task ′ssuspend time is outside the anticipated bounds of reasonableness. Once thishas occurred, the operator has to find the rogue task that is causing theproblem, by:

1. Displaying the suspended task′s details, seeing what the suspend reason is(CICSPlex SM uses EXEC CICS INQUIRE TASK internally), and noting theinternal UOW id.

If the suspend reason is ENQUEUE, we have to find out on which enqueuethe task is waiting.

2. Displaying the enqueues held and the enqueue this task is waiting for, usingthe UOWENQ display (which CICSPlex SM build from EXEC CICS INQUIREUOWENQ(uow) browse facility for this UOWid). From this display we can getthe enqueue name for which this task is waiting.

3. Displaying the details of this enqueue (CICSPlex SM uses EXEC CICSINQUIRE UOWENQ RESOURCE(name) browse facility to see which UOWs areinterested in this enqueue (holder and waiters). Without theRESOURCE(name) filter, we had to use the EXEC CICS INQUIRE UOWENQbrowse facility to browse through all UOWs in the system, looking for thoseinterested in this enqueue.

You can now analyze the cause of the delay.

5.11 GRS ServicesSysplex ENQ and DEQ support uses OS/390 GRS services to achieve locking thatis unique across multiple MVS images in a sysplex.

GRS can be configured in one of two ways:

GRS=STAR When GRS is initialized as a star configuration, all informationabout resource serialization is held in the coupling facility. GRSaccesses the coupling facility when a requester issues an ENQ or


DEQ on a global named resource. Figure 39 on page 72 shows GRSwithin a sysplex using the star configuration.

GRS=RING When GRS is initialized as a ring configuration, all information aboutresource serialization is passed around from MVS to MVS in amessage through XCF services.

The RESLIM parameter in GRSCNFxx controls how long the messageresides in one MVS before it is passed to the next in the ring. Thisdelay can have a serious effect on CICS performance and is notrecommended!

Figure 39. GRS Enqueuing in a Sysplex

Initialize your GRS as GRS=STAR if your configuration supports it.

5.12 Enqueuing from Outside CICSBecause GRS manages the enqueues on behalf of CICS, it is possible forregions other than CICS regions to enqueue on these resources. GRS does notsee these resources as belonging exclusively to CICS, so it allows other regionsto access them. For example, a batch program could enqueue on a resourceassociated with a file that CICS is using.

Enqueuing from outside CICS is not recommended because the deadlockhandling that is built into CICS and CICSPlex SM does not extend to non-CICSregions.


5.13 CICS Affinity UtilityChanges have been made to the CICS Affinity Utility to make it easier to createaffinity groups for enqueues by address separately from enqueues by name.The scanner and the reporter now distinquish between ENQ NAME and ENQADDRESS in their reports, where previously only ENQ was shown. Similarly,DEQ is now reported as either DEQ NAME or DEQ ADDRESS.

If there is a nonblank ENQSCOPE name in a ENQMODEL definition, the detectordisregards any matching EXEC CICS ENQ/DEQ (because use of the ENQMODELmakes the ENQ or DEQ sysplexwide, removing the implied affinity).

If there is no ENQMODEL definition, or one with a blank ENQSCOPE name, theENQ or DEQ is local and so continues to be reported as an affinity.

5.14 Additional ConsiderationsAssume a situation where we want to create an ENQMODEL for a particularresource. If a particular resource should require sysplex scope enqueuingfacilities, that resource, whether it is, for example, a file, a field within a file, or aTS queue, will be defined as the ENQNAME, for example, ENQNAME=PAYFILEA.If a set of resources should require sysplex scope enqueuing facilities, theENQNAME may be generic, for example, ENQNAME=PAYFILE*.

Assume that we have several specific CICS regions across which the particularresource may have sysplex scope. We may give this particular set of CICSregions an arbitrary four character name such as TEST. This name is thendefined as the ENQSCOPE, for example, ENQSCOPE=TEST.

We now have an ENQMODEL that is specific to a particular resource, PAYFILEA,and to a particular set of CICS regions, which we have called TEST, althoughthere is no definition of TEST that specifies the collective CICS regions.

We now give the ENQMODEL for our first resource a name, say TESTRES1, anddefine and install it in all CICS regions in all of the TEST regions where it isrequired.

We can now define an ENQMODEL for a second resource. If it applies to exactlythe same CICS regions to which the ENQMODEL for the first resource applies,again the ENQSCOPE can be given the name TEST and installed in the sameCICS regions.

If another ENQMODEL resource definition is to be applied to a different set ofCICS regions, whether it is a completely different set, a subset, or another setthat may overlap with TEST, a new ENQSCOPE name must be defined, and theENQMODEL must then be installed in all CICS regions that apply to thatENQSCOPE.

Overlapping generic ENQMODELS must be enabled in order from the mostspecific definition to the most generic. Therefore if a generic definition thatoverlaps with a more generic definition is to be enabled, the more genericdefinition must be disabled, and the definitions must be enabled in a specificorder such that the more generic definition is enabled last.


ENQMODELs can be installed in any order. However, an ENQMODEL is installedwith the default state of ENABLED. If ENQMODELs are not installed with a stateof DISABLED, the restricted order of enabling the definitions also applies toinstalling the definitions.

Now assume that we have an ENQMODEL called ENQRES1 that applies to AORs1-4, an ENQMODEL called ENQRES2 that applies to AORs 5-8, and anENQMODEL called ENQRES3 that applies to AORs 2-6.

If the multiple connected CICS regions do not share a CSD, then each CICSregion must have the required ENQMODELs defined and installed.

If the multiple connected CICS regions share a CSD, the ENQMODELs can be putinto CSD GRPLISTs. One authorized CICS region can define the ENQMODELSinto the common CSD, and then each CICS region can install the requiredENQMODELs by specifying a GRPLIST in the region′s system initialization table(SIT), and consequently only the required ENQMODELS will be installed.

It may be that the ENQMODELs are defined by CICSPlex SM, but the installselection will still be by CICSPlex SM ′s Resource Lists, the equivalent of theCSD′s GRPLISTs.

When a CICS region applies an enqueue to a resource, the presence of anENQSCOPE in the installed ENQMODEL tells CICS that the enqueue is of sysplexscope. In this instance the enqueue is actioned as an MVS ENQ, and informationregarding the ENQSCOPE is retained in the MVS namespace.

When a CICS region encounters an enqueue of sysplex scope, the region checkswhether an MVS ENQ is already held on the resource and whether the CICSregion is in the same ENQSCOPE.

If an ENQMODEL defined in a CICS region has no ENQSCOPE name, theenqueue is deemed to be local, and the information regarding the ENQSCOPE isretained in the CICS namespace.

An ENQMODEL having no ENQSCOPE can be used where a generic resource isdefined across regions but you want to force a more specific resource, whichfalls within the scope of the generic definition, to be local on particular CICSregions.

The MVS ENQ/DEQ namespace is separate from any namespace used by RLS,so there should be no conflict where enqueue resources are defined down to arecord level.


Chapter 6. The Named Counter Sequence Number Server

The named counter sequence number server (referred to as the named counterserver in the rest of this chapter) provides a facility for generating sequencenumbers for use by application programs, both CICS and batch, in a ParallelSysplex.

The named counter server is modeled on the other coupling facility servers usedby CICS and has many features in common with the CFDT server. The uniquenumber generated could typically be used for an order or invoice number andimplemented as a new key in a keyed file. Each named counter is held in a poolof named counters, which resides in a coupling facility list structure. Retrieval ofthe next number in sequence from a named counter is through a callableprogramming interface available to CICS and batch programs. Availability of anEXEC CICS API for CICS programs is planned.

Each named counter consists of:

• A 16-byte name

• A current value

• A minimum value

• A maximum value

The values are stored internally as 8-byte (double-word) binary numbers, but theuser interface allows them to be treated as any length from 1 to 8 bytes.

The first request by a CICS region to a named counter pool establishes aconnection to the server for that pool.

6.1 SetupSetting up the named counter server involves steps similar to those for theshared TS or CFDT server:

1. Define a list structure in the CFRM policy with a name of the formDFHNCLS_poolname (see Figure 40). The INITSIZE can be set to theminimum of 256 KB, which should be sufficient for most customers becauseit will hold approximately 1000 counters. A structure of a size of 512 KB willhold tens of thousands.

� �STRUCTURE NAME(DFHNCLS_TESTNC1)

SIZE(512)INITSIZE(256)PREFLIST(CF01,CF02)

� �Figure 40. Sample Named Counter Server List Structure Definit ion

2. Activate the CFRM policy with this command:SETXCF START,POLICY,POLNAME=policy_name,TYPE=CFRM

3. Initialize AXM services if not already in use for shared TS or CFDTs.


4. Start the DFHNCMN server regions by running the DFHNCMN program (seeFigure 41 on page 76). The region size for this job is less important than inother servers because of the small structure size.

� �//CFSERVER EXEC PGM=DFHNCMN//STEPLIB DD DISP=SHR,DSN=CICSTS13.CICS.SDFHAUTH//SYSPRINT DD SYSOUT=*//SYSIN DD *POOLNAME=TESTNC1/*

� �Figure 41. Sample JCL to Start Named Counter Server

The commands and parameters to control the named counter server are similarto, but simpler than, those for the CFDT server. There is also an unload/reloadfunction, which can be used to unload the pool for planned maintenance or amove to a different coupling facility.

6.2 EXEC CICS InterfaceCICS TS 1.3 introduces new EXEC CICS commands to access the named counterserver. Although all named counter values are held internally as doublewordunsigned binary numbers, the EXEC CICS API provides both a fullword(COUNTER) and doubleword (DCOUNTER) set of commands, which you shouldnot mix. With these EXEC CICS commands you can perform the followingoperations on named counters:

• DEFINE

This command defines a new named counter, setting minimum andmaximum values, and specifying the current number at which the counter isto start.

• DELETE

This command deletes a named counter from its named counter pool.

• GET

This command gets the current number from the named counter, providedthe maximum number has not already been allocated.

• QUERY

This command queries the named counter to obtain the current, minimum,and maximum values.

• REWIND

This command rewinds a named counter back to its defined minimum value.

• UPDATE

This command updates the current value of a named counter to a newcurrent value.

For more information about the new API refer to CICS Application ProgrammingGuide and CICS Application Programming Reference.


6.3 CALL InterfaceYou can also access the named counter server through a callable interface,which can be used in CICS applications or in batch jobs. The interface does notdepend on CICS services, so it can be used in applications running under anyrelease of CICS.

The syntax of the named counter server call is:

CALL DFHNCTR(function,return_code,pool_selector,counter_name,size,value_length,current_value,minimum_value,maximum_value,options,upd,lower,upper);

Any trailing parameters after the counter_name can be omitted.

To use the named counter server callable interface, follow these steps:

1. Ensure that your application programs include the appropriate copybook thatdefines the parameter list definition for the programming language. Fiveversions of the copybook are available :

• DHFNCASM and DFHNCEQU for Assembler

• DFHNCC for C or C++

• DFHNCCOB for COBOL

• DFHNCPLI for PL/I

2. Ensure that the application program is link-edited with the callable interfacelinkage routine, DFHNCTR.

3. Ensure that the named counter server interface module, DFHNCIF, and theoptions table, DFHNCOPT, are available to the CICS region or any batch jobthat is using the interface. These objects must be in a STEPLIB library, in alinklist library, or in the link pack area (LPA). The supplied versions are inthe SDFHLINK library.

6.4 DFHNCOPT TableUnless you specify a pool name on each call, you will have to code and use theDFHNCOPT options table. A sample of this table is available in the SDFHSAMPlibrary and is used as the default table (see Figure 42). This default table ispresent in the CICS linklib, so when creating your own version, remember toeither delete or replace the supplied one.

� �DFHNCO TYPE=CSECTDFHNCO POOLSEL=DFHNC*,POOL=YESDFHNCO POOL=DFHNC001END DFHNCOPT

� �Figure 42. Default Supplied DFHNCOPT Table

These definitions assume that any pool selection parameter matching the patternDFHNC* is an actual pool name, and that any other pool selection parameter(including all spaces) maps to pool name DFHNC001.

Chapter 6. The Named Counter Sequence Number Server 77

It is possible to code a table that will select a pool name based on the APPLID orjobname of the region issuing the call.


Chapter 7. External CICS Interface Enhancements

In this chapter we describe the EXCI extensions introduced with CICS TS 1.3 tosupport OS/390 Recoverable Resource Management Services (RRMS).

7.1 OverviewOriginally the EXCI was introduced in CICS/ESA 4.1 and it is also known as thebatch client for CICS. The basic function of EXCI is to provide an API fornon-CICS address spaces in MVS to invoke programs in CICS and thus enableaccess to resources under CICS control. Data is exchanged through aCOMMAREA and the invoked CICS program has to adhere to the DPLrestrictions. Figure 43 shows a general overview of the EXCI function.

Figure 43. EXCI Overview. An EXCI Client Connects to CICS Target Region, Using the CICS MRO Protocol

Communication between the EXCI client and the target CICS regions is providedby the standard CICS interregion program (DFHIRP), which uses the CICS MROprotocol. In a Parallel Sysplex environment, XCF/MRO is used to connect totarget regions in different OS/390 images.

CICS provides two flavors of the API, a command level API and a callable API.The command level API is recommended for infrequent CICS access within aclient program; the callable API is suited for continuous CICS access within aloop for example. For more information about the EXCI, see the CICS ExternalInterfaces Guide.

Before CICS TS 1.3, one of the limitations of the EXCI was that syncpointprocessing had to be performed upon completion of the CICS program (enforcedSYNCONRETURN option). Any CICS resources that were updated were thereforeeither committed or rolled back when the EXCI client program regained control.This limitation has been lifted with the EXCI extensions introduced in CICS TS1.3. (see Figure 44 on page 80). In addition to the existing support with


SYNCONRETURN, you now have the option of extending a single UOW to spanseveral invocations of one or several CICS programs, as well as calls to otherresource managers such as DB2 or IMS (DBCTL), that is, resource managersthat use the OS/390 RRMS support.

Figure 44. Overview of the New EXCI Support Using RRMS

RRMS, a generalized resource recovery manager in OS/390, providessyncpointing services based on a two-phase commit protocol for any resourcemanager in OS/390. RRMS consists of three components:

• Syncpoint manager - Resource Recovery Services (RRS) is the RRMScomponent that provides the syncpointing services based on the two-phasecommit protocol.

• Registration services - The registration server coordinates thecommunication between a resource manager and RRMS (CICS, for example,is a resource manager in this context). A resource manager must registeritself with RRMS before it can request any RRMS services.

• Context server - This server provides data constructs and primitives that aresource manager needs to identify specific work requests and the eventsthat can occur for such a work request. A context represents a specific UOWand the components involved in processing it, such as programs, resourcemanagers, and recoverable resources.

For more information about RRMS, see MVS Programming: Resource Recovery.

CICS TS 1.3 uses RRMS to provide syncpoint coordination for the EXCI. Becausethe RRMS support currently implemented in the EXCI is limited to a singleOS/390 image, the EXCI client can only issue calls in a spanned UOW toresource managers that run in the same image, including CICS, if RRMSservices are needed. To implement a spanned UOW from an EXCI client, yousimply omit the SYNCONRETURN option in the EXCI call.


When the EXCI client program ends (normal or abend), an implicit syncpoint istaken. However, we do not recommend using implicit syncpointing becausethere can be situations when the EXCI client program cannot determine theactual result of an implicit syncpoint. Furthermore high level languages (HLLs)suppress errors that should result in a backout. Therefore we recommend usingexplicit syncpointing in a production environment. Explicit syncpointing iscontrolled by coding the RRMS APIs for commit or rollback in the client program.Once you decide in the client program that the current UOW has come to an end,use the following RRMS APIs for syncpointing:

• To commit, use SRRCMIT (return code)

• To back out, use SRRBACK (return code)

For more information about these callable services, see MVS Programming:Callable Services for High-Level Languages.

Figure 45 shows the design options discussed below for applications that usethe EXCI interface.

Figure 45. Design Options for EXCI Client Applications

Note: Although you can use the EXCI without SYNCONRETURN only to targetswithin one OS/390 image, the target server program can still be daisy chained toa CICS region in a different image within a Parallel Sysplex.

1. With SYNCONRETURN

This design option works the same as before: Neither CICS nor the EXCI APIuses RRMS services in this case. The advantages of this option are:

• Programming model is simple.

• It works with backlevel CICS releases (starting with CICS/ESA 4.1) -RRMS is not a prerequisite.

• The EXCI client and the target CICS server can reside in different OS/390images in a Parallel Sysplex.

The disadvantage of course is that CICS commits resource updates everytime it returns to the requesting EXCI client. Therefore you cannot

Chapter 7. External CICS Interface Enhancements 81

implement spanned UOWs, and you possibly need sophisticated applicationcode for error situations if you have a requirement to perform severalupdates with more than one EXCI call.

2. Without the SYNCONRETURN option

Omitting SYNCONRETURN means that you are using RRMS services tocontrol syncpointing within the EXCI client. The major advantages of thisnew support in CICS TS 1.3 are:

• You can support an extended UOW that spans multiple EXCI calls.

• While you access CICS resources through EXCI, you can also updateresources controlled by other resource managers that support the RRMSinterface in the same UOW.

• You decide in the EXCI client program at which point in time a syncpointshould be taken. Thus you control syncpointing among diverse resourcemanagers, including several CICS regions.

• If you use explicit syncpointing as recommended, you can implementmultiple spanned UOWs in one instance of an EXCI client by using theRRMS commit API.

Note: The CICS server program cannot take its own explicit syncpoint inthis case (through an EXEC CICS SYNCPOINT command).

Mixing the two options, with and without SYNCONRETURN, in the same EXCIclient is possible as well (see Figure 46).

Figure 46. Mixing with and without SYNCONRETURN Calls in an EXCI Client

Note, however, that each time you issue an EXCI call (or LINK) withSYNCONRETURN you create a new UOW separate from the UOW that is createdby an EXCI call without SYNCONRETURN. For each such call, a new instance of


a mirror transaction is created. A UOW that is a result of an EXCI call withSYNCONRETURN will not use RRMS.

Calls that are issued without SYNCONRETURN use RRMS, and for each call thesame instance of the mirror transaction is used. This instance is suspendedonly during times of inactivity.

7.2 Sample EXCI Client Implementation Using RRMSIn this section we describe our sample application for the EXCI tests. Figure 47shows the logical functions of the application.

Figure 47. Functions of Our Sample Application

The front-end program is executed under TSO Interactive System ProductivityFacility (ISPF) and provides a simple user interface for the tests. See Figure 48on page 84 for a sample input screen and Figure 49 on page 84 for the resultingoutput screen.


� � Test Driver for EXCI Pgm 10/98 - Redbook SG24-5274 Enter S=SYNC.ON Return, N=no SYNC.on Return X=exitn Enter C=RRS-Comit, R=RRS-Rollbk, A=Abend client,

E=normal End, N=keep going(same UOW)n Enter CICS Sys.-Id (e.g. PAA1)paa4 Enter CICS Server Pgm(e.g. VSAMSERV)vsamserv Enter Account Operation Code: 1=read, 2=add, 3=update, 4=delete, 9=Abend Server2 Enter Account Number (5 Char.num)12001 Enter First NameDouglas Enter Last NameSlotte Enter Address: Street + NrHoover rd. Enter Address: zip code + CityLexington 12345 Enter Address: State, CountryN.Carolina� �

Figure 48. Sample Input Screen from the Test Driver

� � now calling EXCI13 Returned from EXCI13, Ret.Codes are: EXCI13 RC: 0 RESP : 0 RESP2 : 0 Account Nr. : 12001 Acc. Owner : Douglas Slotte Address : Hoover rd. ,Lexington 12345 N.Carolina

NEW RECORD WAS CREATED FOR CUSTOMER NUMBER 12001

please press Enter to continue� �Figure 49. Resulting Output Screen

The front end driver remains active unless explicitly ended by selecting an endoption. The user can select a target region as well as a target CICS program forthe next EXCI call. The type of call can be varied as well by selecting with orwithout SYNCONRETURN. After the user enters the remaining input (accountinformation for the CICS server program), the frontend calls module EXCI13,which contains the EXCI calls and the RRMS calls. EXCI13 then performs therequested function and returns the results. See 7.2.2, “The EXCI Client” onpage 86 for the assembler program sources.

7.2.1 Preparing the TestsWe performed the following setup tasks for the EXCI tests:

• CICS setup (see CICS Resource Definition Guide and CICS System DefinitionGuide)

1. Specified RRMS=YES in the SIT. This is a new SIT parameter and itcauses CICS to register with RRMS during CICS initialization.


2. Defined session and connection definitions for the EXCI.

3. Installed the highest level of DFHIRP (the interregion program).

4. Changed the VSAM file definitions to include at least BACKOUTONLY asa recovery parameter.

5. Provided the EXCI client program to include the RRMS APIs for commitand rollback (see 7.2.2, “The EXCI Client” on page 86).

− Included the RRMS calls for syncpointing.

− Compiled and linked the client program; included SYS1.CSSLIB in thelinklib concatenation.

− Before execution, concatenated the CICSTS13.SDFHEXCI library inthe job step. We had to include this library in the ISPLOAD-libconcatenation.

• RRMS setup

− Set up log streams to be used for the RRMS log. You can define eitherDASD-only log streams or a log structure for RRMS in the couplingfacility.

− A set of ISPF panels is provided with RRMS to enable management anderror tracking for UOWs and the resource managers involved. Includethese panels in your ISPF environment.

− Defined RRMS as a subsystem in IEFSSNxx parmlib member (SUBSYSSUBNAME(RRS)).

If RRMS fails, it can be restarted warm or cold, where normally a warm restart isrecommended to enable RRMS to resynchronize with resource managers. Youcan also include RRMS in an automatic restart management (ARM) policy toenable automatic restart of RRMS.

When CICS starts up, it initializes its RX domain and registers with RRMS,writing the messages shown in Figure 50 on the log. If RRS is not running atthis time, DFHRX0105 message is displayed instead of DFHRX0104.

+DFHRX0100I SCSCPAA1 RX domain initialization has started. +DFHRX0104I SCSCPAA1 The Resource Recovery Services (RRS) exit manager ATR.EXITMGR.IBM is now available. +DFHRX0101I SCSCPAA1 RX domain initialization has ended.

Figure 50. Early RX Domain Initialization Messages

In a later stage of the second CICS initialization phase, CICS resynchronizes withRRMS to clean up possibly pending UOWs and writes the messages shown inFigure 51 to the log.

+DFHRX0106I SCSCPAA1 Restart processing with Resource Recovery Services (RRS) is beginning. +DFHRX0107I SCSCPAA1 Restart processing with Resource Recovery Services (RRS) has ended.

Figure 51. RRS Resynchronization Message


7.2.2 The EXCI ClientIn this section we list the source of the TSO driver for EXCI13 and the EXCI clientmodule EXCI13 that contains the EXCI LINK commands and the RRMS API calls.See Figure 47 on page 83 for a functional overview.

Our EXCI module (EXCI13) is driven by the front-end program, EXCID, runningunder ISPF. Figure 52 on page 87 shows the driver source.


* Program: driver for EXCI13PRINT GENEXTRN EXCI13COPY EXCI13CA

** Driver for EXCI Program EXCI13 - runs under TSO ISPF* In ISPF select option 6 and enter for example* call ′ cicssysf.appl.loadlib(excid)′* in the commandline to execute the driver.* Register usage: 15 branch addr and retcode* 14 return addr* 13 Save area pointer* 12 pgm base register* 11 pointer to getmained area (CA)* 1 parameter address* other: workregister* Pgm StartEXCID CSECTEXCID AMODE 31EXCID RMODE 24* must be in low storage due to TPUTs

USING EXCID,12 BASEREG 12STM 14,12,12(13) chain saverareasLR 12,15B START

*DC C′ Testdriver - Oct. 1998 Rbk SG-5274′DC C′ Assembly: &SYSDATE &SYSTIME ′

*START DS 0H

ST 13,SAVE_R+4LA 8,SAVE_RST 8,8(13)LR 13,8

*L 0,=F′512′ CA needs roughly 512 bytesGETMAIN R,LV=(0) get the storageLTR 15,15BZ GM_OK getmain ok?TPUT EGMAIN,L′ EGMAINST 15,RC ..no, send msg and endB FINI

GM_OK DS 0HST 1,GMADDR ..yes, save storage addressLR 11,1USING CA,11 CA addressabilityMVC CAAPPLID,=CL8′ SCSCPAA1′ set defaultsMVC CASERVER,=CL8′ VSAMSERV′

AGAIN DS 0HSR 1,1 clear Return CodesST 1,RCST 1,CARCST 1,CARC1ST 1,CARC2ST 1,CAMSGPTR and EXCI Msg Addr

STLINENO LINE=1 clear screenTPUT TITEL,L′ TITELTPUT PSYORET,L′ PSYORETTGET CASYORET,L′ CASYORETOI CASYORET,X′ 40 ′ force upper caseCLI CASYORET,C′ S′ SYNCONRETURN requested?BE GETAPPLID ..yes, get next itemCLI CASYORET,C′ X′ immediate exit?BE FINIMVI CASYORET,C′ N′ assume NO Synconreturn

Figure 52 (Part 1 of 6). Program Listing for the EXCI Driver


GETCMIT DS 0HTPUT PCMIT1,L′ PCMIT1TPUT PCMIT2,L′ PCMIT2TGET CACOMIT,L′ CACOMIT get commit indicatorOI CACOMIT,X′ 40 ′ force upper case

CKCMIT CLI CACOMIT,C′ E′ normal client endBE FINICLI CACOMIT,C′ C′ commit requestedBE REPINPUTCLI CACOMIT,C′ R′ rollback requestedBE REPINPUTCLI CACOMIT,C′ N′ continue same UOWBE GETAPPLIDCLI CACOMIT,C′ A′ client abend requestedBE REPINPUTTPUT PINERR,L′ PINERRB GETCMIT if input error repeat

*GETAPPLID DS 0H

MVC IAPPLID,=CL4′ PAA1′TPUT PCICS,L′ PCICSTGET IAPPLID,L′ IAPPLID get target APPLIDOC IAPPLID,=XL4′40404040′MVC CAAPPLID(4),=CL4′ SCSC′MVC CAAPPLID+4(4),IAPPLIDTPUT PSERV,L′ PSERVTGET CASERVER,L′ CASERVER get target server pgmOC CASERVER,=XL8′4040404040404040′CLI CASERVER,C′ ′BNE GETACCTOPMVC CASERVER,=CL8′ VSAMSERV′

GETACCTOP DS 0HTPUT PACCTOP1,L′ PACCTOP1TPUT PACCTOP2,L′ PACCTOP2TGET CAACCTOP,L′ CAACCTOP get account operationCLI CAACCTOP,C′ 1 ′ readBE GETACCTCLI CAACCTOP,C′ 2 ′ addBE GETACCTCLI CAACCTOP,C′ 3 ′ updateBE GETACCTCLI CAACCTOP,C′ 4 ′ deleteBE GETACCTCLI CAACCTOP,C′ 9 ′ abend in serverBE GETACCTMVC OUTLINE,=CL80′ ′MVC OUTLINE(L′ PACCTOPE),PACCTOPEMVC OUTLINE+20(1),CAACCTOPTPUT OUTLINE,L′ OUTLINEB GETACCTOP

*



GETACCT DS 0HTPUT PACCT,L′ PACCTTGET CAACCT,L′ CAACCT get account number

* clear input fieldsMVI CAFNAME,C′ ′MVC CAFNAME+1(L′ CAFNAME-1),CAFNAMEMVI CALNAME,C′ ′MVC CALNAME+1(L′ CALNAME-1),CALNAMEMVI CAADDR1,C′ ′MVC CAADDR1+1(L′ CAADDR1),CAADDR1MVI CAADDR2,C′ ′MVC CAADDR2+1(L′ CAADDR2),CAADDR2MVI CAADDR3,C′ ′MVC CAADDR3+1(L′ CAADDR3),CAADDR3MVC CABALNC,=F′ 0 ′MVI CAMSG,C′ ′MVC CAMSG+1(L′ CAMSG),CAMSG

*CLI CAACCTOP,C′ 1 ′ If read we don′ t needBE REPINPUT other inputCLI CAACCTOP,C′ 4 ′ delete neitherBE REPINPUT

*TPUT PFNAME,L′ PFNAME get fist nameTGET CAFNAME,L′ CAFNAMETPUT PLNAME,L′ PLNAMETGET CALNAME,L′ CALNAME get last nameTPUT PADDR1,L′ PADDR1TGET CAADDR1,L′ CAADDR1 get address 1 - 3TPUT PADDR2,L′ PADDR2TGET CAADDR2,L′ CAADDR2TPUT PADDR3,L′ PADDR3TGET CAADDR3,L′ CAADDR3

* re-show input for verificationREPINPUT DS 0H

STLINENO LINE=1 clear screenTPUT PREP,L′ PREPMVI ENTER,C′ ′MVI OUTLINE,C′ ′MVC OUTLINE+1(L′ OUTLINE-1),OUTLINEMVC OUTLINE(14),=CL14′ SYNCONRETURN:′MVC OUTLINE+15(1),CASYORETMVC OUTLINE+20(14),=CL14′ Comit/RollBk:′MVC OUTLINE+35(1),CACOMITMVC OUTLINE+40(13),=CL13′ Acc.Op.Code :′MVC OUTLINE+55(1),CAACCTOPTPUT OUTLINE,L′ OUTLINE

*MVI OUTLINE,C′ ′MVC OUTLINE+1(L′ OUTLINE-1),OUTLINEMVC OUTLINE(13),=CL13′ CICS Target :′MVC OUTLINE+14(8),CAAPPLIDMVC OUTLINE+25(10),=CL10′ CICS Pgm :′MVC OUTLINE+36(8),CASERVERTPUT OUTLINE,L′ OUTLINE

*BAL 9,SHOWDATA show rest of data

*XC CABALNC,CABALNC clear balance areaMVI CAMSG,C′ ′ and message areaMVC CAMSG+1(L′ CAMSG-1),CAMSG

*MVI ENTER,C′ ′TPUT PALLOK,L′ PALLOK is all input ok?TGET ENTER,L′ ENTER get Y/NOI ENTER,X′ 40 ′CLI ENTER,C′ Y′



BE GONOWB AGAIN if not Y repeat input

*GONOW DS 0H

TPUT PGO,L′ PGOSR 15,15LOAD EP=EXCI13 load EXCI13 pgmLTR 15,15BZ LOADOK was load ok?TPUT PLE,L′ PLEB AGAIN

LOADOK LR 15,0L 1,GMADDR ADDRESS CABASSM 14,15 execute ECXI13MVC OUTLINE,=CL80′ ′ clear format areaMVC OUTTXT1(L′ TEXCIRC),TEXCIRCSR 2,2ST 2,FWHELP1ST 2,FWHELP2L 3,CARC get EXCI13 responseCVD 3,DW_HELP convert to decimalMVC OUTDAT1(6),EDITPATED OUTDAT1(6),FWHELP2+1 EDIT CARCMVC OUTTXT2(7),=CL7′ RESP :′ST 2,FWHELP1ST 2,FWHELP2L 3,CARC1 load RESP codeCVD 3,DW_HELP convert to decimalMVC OUTDAT2(6),EDITPATED OUTDAT2(6),FWHELP2+1 EDIT RESP to format areaMVC OUTTXT3(L′ TRESP2),TRESP2ST 2,FWHELP1ST 2,FWHELP2L 3,CARC2 load RESP2CVD 3,DW_HELP convert ot decimalMVC OUTDAT3(6),EDITPATED OUTDAT3(6),FWHELP2+1 EDIT RESP2 to format areaTPUT PRETS,L′ PRETSTPUT OUTLINE,L′ OUTLINE show return codes

*L 6,CAMSGPTRLTR 6,6 valid ptr ?BNZ SAYERR1 yes, then show the messageB CHECKRC else skip show message

SAYERR1 LH 5,CAMSGLENLH 7,=H′ 80 ′CR 7,5BH LENOKLR 5,7 limit msg to 80 bytes

LENOK DS 0HLA 4,OUTLINEMVC OUTLINE,=CL80′ ′MVCL 4,6 load message (len is in R5 and R7)TPUT OUTLINE,L′ OUTLINE

CHECKRC DS 0HL 15,CARC check EXCI13 RC and give explanationLTR 15,15 what happened if not 0BZ CONTINULA 4,19CR 15,4BH EXCIERRTPUT PINE,L′ PINE Input inconsistencyB CONTINU



EXCIERR DS 0H error inEXCI call, check RESPLA 4,29CR 15,4BH SERVERRTPUT PEXCIE,L′ PEXCIEB CONTINU

SERVERR LA 4,39CR 15,4 server errorsBH RRSERRTPUT PSERR,L′ PSERRB CONTINU

RRSERR DS 0HTPUT PRRSE,L′ PRRSE error in RRS call

CONTINU DS 0H* now show results from VSAMSERV

BAL 9,SHOWDATA*

MVC OUTLINE,=CL80′ ′MVC OUTLINE,CABALNCMVC OUTLINE+L′ CABALNC(L′ CAMSG),CAMSGTPUT OUTLINE,L′ OUTLINE

TPUT PSEEREST,L′ PSEERESTTGET ENTER,L′ ENTERB AGAIN

***********************************************************SHOWDATA DS 0H

MVI OUTLINE,C′ ′MVC OUTLINE+1(L′ OUTLINE-1),OUTLINEMVC OUTLINE(13),=CL20′ Account Nr. :′MVC OUTLINE+14(L′ CAACCT),CAACCTTPUT OUTLINE,L′ OUTLINE

*MVC OUTLINE,=CL80′ ′MVC OUTLINE(13),=CL20′ Acc. Owner :′MVC OUTLINE+14(L′ CAFNAME),CAFNAMEMVC OUTLINE+33(L′ CALNAME),CALNAMETPUT OUTLINE,L′ OUTLINE

*MVC OUTLINE,=CL80′ ′MVC OUTLINE(9),=CL20′ Address :′MVC OUTLINE+10(L′ CAADDR1),CAADDR1MVI OUTLINE+26,C′ , ′MVC OUTLINE+27(L′ CAADDR2),CAADDR2MVC OUTLINE+45(L′ CAADDR3),CAADDR3TPUT OUTLINE,L′ OUTLINEBR 9

********************************************************************FINI EQU *FREE DS 0H

L 1,GMADDRFREEMAIN RU,A=(1),LV=512,SP=0 FREE StorageL 13,SAVE_R+4 restore callers regsLM 14,12,12(13)SR 15,15 return okBR 14 go back



**********************************************************************-------------------------------------------------------------------** Declarations **-------------------------------------------------------------------**SAVAREA DS 0F SAVEAREA BEGINSAVE_R DS 18F Reg. SaveareaRC DS F local return codeGMADDR DS F Comarea Address getmained*IAPPLID DS CL4ENTER DS CL1DW_HELP DS D

ORG DW_HELPFWHELP1 DS FFWHELP2 DS FOUTLINE DS CL80

ORG OUTLINEOUTTXT1 DS CL10OUTDAT1 DS CL8

DS CL2OUTTXT2 DS CL10OUTDAT2 DS CL8

DS CL2OUTTXT3 DS CL10OUTDAT3 DS CL8

DS CL22* ConstantsEGMAIN DC C′ Error in Getmain for CA storage′TITEL DC C′ Test Driver for EXCI Pgm 10/98 - Redbook SG24-5274′

PSYORET DC C′ Enter S=SYNC.ON Return, N=no SYNC.on Return X=exit′PCMIT1 DC C′ Enter C=RRS-Comit, R=RRS-Rollbk, A=Abend client,′PCMIT2 DC C′ E=normal End, N=keep going(same UOW)′PINERR DC C′ Input error, please enter C, R, A, N or E′PCICS DC C′ Enter CICS Sys.-Id (e.g. PAA1)′PSERV DC C′ Enter CICS Server Pgm(e.g. VSAMSERV)′PACCTOP1 DC C′ Enter Account Operation Code: ′PACCTOP2 DC C′1=read, 2=add, 3=update, 4=delete, 9=Abend Server′PACCTOPE DC C′ sorry, Account Op. is invalid, please try again′

PACCT DC C′ Enter Account Number (5 Char.num)′ PLNAME DC C′ Enter Last Name′ PFNAME DC C′ Enter First Name′ PADDR1 DC C′ Enter Address: Street + Nr′ PADDR2 DC C′ Enter Address: zip code + City′ PADDR3 DC C′ Enter Address: State, Country′

PREP DC C′ ok done, lets check again what you entered′PALLOK DC C′ All ok? Enter Y for yes, anything else to repeat′PGO DC C′ now calling EXCI13′PLE DC C′ LOAD ERROR when loading EXCI13′PRETS DC C′ Returned from EXCI13, Ret.Codes are:′PINE DC C′ its some kind of input error, check your input′PEXCIE DC C′ Error from EXCI call, check RESP codes′PSERR DC C′ Server reports an error, check sever msg.′PRRSE DC C′ Error from RRMS call, check 2nd RC′PSEEREST DC C′ please press Enter to continue′

TEXCIRC DC C′ EXCI13 RC:′ TRESP2 DC C′ RESP2 :′ * EDITPAT DC XL6′402020202120′ EDIT pattern *

LTORG *

END


For simplicity we used the link API rather than the call API.

Figure 53 on page 93 shows the program that we used on the client side toissue EXCI LINK requests.


//EXCIASM JOB (POK,9999),′ ASM EXCI′ , CLASS=A,MSGCLASS=S,REGION=4M,// NOTIFY=&SYSUID//ASL EXEC DFHEXTAL,PROGLIB=′ CICSSYSF.APPL.LOADLIB′ , <-output lib// DSCTLIB=′ CICSSYSF.APPL53.SOURCE′ <-copybooks//TRN.SYSIN DD **ASM XOPTS(EXCI)************************************************************************ PROGRAM: EXCI13 - EXCI Links to CICS and Calls to RRMS ** LANGUAGE: ASSEMBLER ** FUNCTION: PROVIDE CICS EXCI DYNAMIC PROGRAM LINK ** AND COMMIT / ROLLBACK CALLS TO RRMS ** PARAMETERS Comarea (CA), CA Address in Reg.1 callers parms ** COMMAREA for CICS Server included in CA ** RETURN CODES: (RESULT) ** 0 = PROGRAM RECEIVED NORMAL RETURN FROM CALLED FUNCTIONS ** 1-10= Parameter errors ** 20-29= Errors in EXCI Link Calls ** 30-39= Errors returned from CICS Server Pgm ** 40-49= Errors from RRMS Calls (SRRCMIT / SRRBACK) ** REGISTER USAGE: ** 1 - Parameter Address ** 9 - BRANCH AND LINK REGISTER TO SUBROUTINES ** 10 - DFHEISTG REGISTER (DYNAMIC STORAGE AREA) ** 11 - Pointer to CA (commarea of caller) ** 12 - BASE REGISTER ** other- WORK REGISTER ************************************************************************* INCLUDE THE RRMS COPYBOOKS ***********************************************************************

COPY ATRSASM EJECT

************************************************************************ Comarea from Caller, includes COMMAREA for CICS ************************************************************************CA DSECTCARC DS F EXCI13-RCCARC1 DS F + Function RCCARC2 DS F + RESP2*CAABCODE DS F EXCI ABCODECAMSGLEN DS F EXCI RC MSGLENCAMSGPTR DS F EXCI RC MSGPTR*CASYORET DS CL1 SYNCONRETURN REQUEST Y/NCACOMIT DS CL1 C=commit, R=rollbackCAAPPLID DS CL8 TARGET CICS APPLIDCASERVER DS CL8 TARGET CICS SERVER PROGRAMCOMPTR DS F ADDRESS OF ″REAL″ COMMAREA FOR SERVER PGMCACOMLEN DS H LENGTH OF ″REAL″ COMMAREA FOR SERVER PGM*COMMAREA DS 0CL200 VSAMSERV COMMAREACAACCTOP DS CL1 ACCOUNT OPERATION (1-4=read,add,update,del.)CA_SRC DS CL3 RC from VSAMSERVCAACCT DS CL5 ACCOUNT KEYCALNAME DS CL15 Last NameCAFNAME DS CL10 First NameCAADDR1 DS CL15 Address 1CAADDR2 DS CL15 Address 2CAADDR3 DS CL15 Address 3CABALNC DS CL4 BalanceCAMSG DS CL50 Msg from VSAMSERVCALEN EQU *-COMMAREA

Figure 53 (Part 1 of 5). Program Listing of EXCI13


************************************************************************ INCLUDE THE STANDARD COPYBOOKS FOR EXCI DSECTS ************************************************************************

COPY DFHXCRCDCOPY DFHXCPLDEJECT

************************************************************************ EXCI13 PROGRAM START ************************************************************************EXCI13 DFHEIENT CODEREG=(12),DATAREG=(10)EXCI13 AMODE 31EXCI13 RMODE 24

B STARTDC C′ EXCI13 - EXCI Link Sample for GG24-5274′DC C′ Assembly: &SYSDATE &SYSTIME ′

START DS 0HLR 11,1 SET R11 TO CAUSING CA,11SR 1,1 CLEAR WORK REGISTERST 1,CARC SET ZERO RETURN CODEST 1,CARC1 SET ZERO RETURN CODEST 1,CARC2 SET ZERO RETURN CODEMVI RCAREA,X′ 00 ′ clear EXCI RC-AreaMVC RCAREA+1(L′ EXCI_EXEC_RETURN_CODE__LEN-1),RCAREA

************************************************************************ MAIN CODE FOR PROGRAM ************************************************************************

MVC COMALEN,=X′0000′SR 5,5LA 5,CALEN(5)STH 5,COMALENMVC CICSPGM(8),CASERVERMVC CICSSYS(8),CAAPPLID

*CLI CASYORET,C′ S′ SYNCONRETURN REQUESTED ?BNE WOS ..noBAL 9,SY_EXCI ..yes,ISSUE EXCI LINK TO CICSBAL 9,EVAL_XCI evaluate resultsB RETURN

*WOS DS 0H Without SYNCONRETURN

CLI CACOMIT,C′ C′ RRMS Commit REQUESTED ?BNE ROLLBAL 9,CALLRRS perform SSRCMITB RETURN

*ROLL DS 0H

CLI CACOMIT,C′ R′ RRMS rollback REQUESTED ?BNE NSYBAL 9,CALLRRS perform SSRBACKB RETURN

*NSY DS 0H exci call w/o synconreturn

CLI CACOMIT,C′ A′ ABEND requested ?BE ABNORMEBAL 9,NSY_EXCI EXCI w/o SY.O.RETBAL 9,EVAL_XCIB RETURN

*ABNORME DS 0H

CLI CACOMIT,C′ A′ Abend Client requested ?BNE INPERRDC F′ 0 ′

*INPERR LA 1,1 don′ t know what to do, so return

ST 1,CARC handling errorB RETURN



********************************************************************* evaluate Result of EXCI call and RCs of called Server Pgm********************************************************************EVAL_XCI DS 0H R4 set in call routine

CLC RCRESP,DFHRESP(NORMAL)BE CKSERVER if exci was ok check result from serverLR 15,4 else set EXCI13 RCST 15,CARCL 1,RCRESPST 1,CARC1 return RESPL 1,RCRESP2ST 1,CARC2 return RESP2L 1,RCABCODEST 1,CAABCODE return ABEND CodeL 1,RCMSGLENST 1,CAMSGLEN return message lengthL 1,RCMSGPTRST 1,CAMSGPTR return message addressB ENDEVAL

CKSERVER DS 0HLA 4,10(4) set EXCI13 RCCLI CA_SRC,C′ ′ did VSAMSERV send an error ?BE ENDEVALCLI CA_SRC,C′ 0 ′BE ENDEVAL ..no, return to callerMVC CARC1(1),CA_SRC ..yes, return error codeLR 15,4ST 15,CARC

ENDEVAL BR 9 GO BACK******************************************************************* EXCI LINK TO CICS******************************************************************SY_EXCI DS 0H EXCI Link with SYNCONRETURN** NOTE: Commarea length must be H (halfword) as opposed to the* length F passed in the EXCI-CALL Interface

EXEC CICS LINK PROGRAM(CICSPGM) XRETCODE(RCAREA) XCOMMAREA(COMMAREA) XLENGTH(COMALEN) XAPPLID(CICSSYS) XSYNCONRETURN

*LA 4,20 set function codeBR 9 GO BACK

******************************************************************NSY_EXCI DS 0H EXCI Link W/O SYNCONRETURN** NOTE: Commarea length must be H (halfword) as opposed to the* length F passed in the EXCI-CALL Interface

EXEC CICS LINK PROGRAM(CICSPGM) XRETCODE(RCAREA) XCOMMAREA(COMMAREA) XLENGTH(COMALEN) XAPPLID(CICSSYS)

*LA 4,21 set function codeBR 9 GO BACK



******************************************************************** Routines to perform RRMS Commit / Rollback *********************************************************************CALLRRS DS 0H*

LA 4,40 set EXCI13 RC*

CLI CACOMIT,C′ C′ RRMS Commit REQUESTED ?BNE RMSBACK

*CALL SRRCMIT,(RCRESP),MF=(E,SRRPLIST),LINKINST=BASSM

B RRS_END go back*RMSBACK DS 0H RRMS Rollback a UOW

CALL SRRBACK,(RCRESP),MF=(E,SRRPLIST),LINKINST=BASSMB RRS_END go back

********************************************************************* evaluate Result of RRS callRRS_END DS 0H

ST 15,CARC1L 15,RCRESP load RRS return codeST 15,CARC2 and store it in CALTR 15,15 if RRS-RC = 0BZ RRSGOOD .. return ok msgST 4,CARC else return fail msg + EXCI13 RCCLI CACOMIT,C′ C′BNE *+8MVC CAMSG,=CL50′ Commit Request failed′B RRSRETMVC CAMSG,=CL50′ Backout Request failed′B RRSRET

RRSGOOD DS 0HCLI CACOMIT,C′ C′BNE *+8MVC CAMSG,=CL50′ Resources Committed OK′B RRSRETMVC CAMSG,=CL50′ Resources Backed Out OK′B RRSRET

RRSRET DS 0HBR 9

******************************************************************* RETURN TO CALLER *******************************************************************RETURN DS 0H

SR 15,15 SET RETURN CODE TO ZERODFHEIRET RCREG=(15)



******************************************************************DFHEISTG DSECT******************************************************************* Local Variables *******************************************************************RCAREA DS 0CL(EXCI_EXEC_RETURN_CODE__LEN)RCRESP DS F RETCODE RESP AREARCRESP2 DS F RETCODE RESP2 AREARCABCODE DS F RETCODE ABCODE AREARCMSGLEN DS F RETCODE MSGLEN AREARCMSGPTR DS F RETCODE MSGPTR AREA*RSAVE DS 18F Caller Save AreaCOMALEN DS HCICSSYS DS CL8CICSPGM DS CL8SRRPLIST CALL ,(RCRESP),MF=L

LTORGEND

/*//LKED.SYSLIB DD// �DD DISP=SHR,DSN=SYS1.CSSLIB�//LKED.SYSIN DD *

NAME EXCI13(R)/*


7.2.3 The Server ProgramThe EXCI client connects to the target CICS regions and invokes theCICS-supplied mirror transaction CSMI (unless you specify your own). DFHMIRS,which must be the underlying program for the mirror transaction, invokes theCICS server program (VSAMSERV in our case, written in COBOL) requested bythe client. (This DPL technique is well known, so we do not describe it here.)

VSAMSERV simply receives the COMMAREA from the client and accesses aVSAM file to read, add, update, or delete a requested record. Then it returns theCOMMAREA back to the client, passing the results of the operation.

7.2.4 Running the TestsIn this section we describe the EXCI tests we performed and show the respectiveresults in the form of screen captures or trace fragments where appropriate. Weperformed the following tests:

1. The client program accesses two different CICS regions (PAA1 and PAA4)(extended UOW), and terminates normally thus causing an implicit syncpointto be taken

2. Same as test 1, but we abended the client as the last action, thus causing animplicit backout

3. Mix with and without SYNCONRETURN calls in one UOW

4. Same as tests 1 and 2, but we used RRMS API to explicitly commit or rol lback.

To ″slow down″ the system long enough to provide screen captures, we put theCSMI mirror transaction under CEDX control. Before starting we made sureCICS had successfully registered with RRMS by issuing a CEMT INQUIRE RR asshown in Figure 54 on page 98.


� �I RRSTATUS: RESULTS - OVERTYPE TO MODIFY Rms(Ope)� �

Figure 54. RRMS CEMT INQUIRE RR

You can also use the RRMS ISPF panels to verify that RRMS knows therespective CICS region as shown in Figure 57. To get to this panel select RR inthe ISPF Main menu (or whatever your system administrator has set up at RRMSinstallation time). In the RRS panel shown in Figure 55, select option 2.

� �RRS

Option ===> 2

Select an option and press ENTER:

1 Browse an RRS log stream 2 Display/Update RRS related Resource Manager information 3 Display/Update RRS Unit of Recovery information 4 Exit� �

Figure 55. RRS Main Menu Panel

Press Enter to get the RRS Resource Manager Selection panel as shown inFigure 56. Here you provide the resource manager name for CICS if you knowit.

� �RRS Resource Manager Selection

Command ===>

Optionally provide a resource manager name and press Enter:

RM name . . . . DFHRXDM.SCSCPAA1.ibm� �Figure 56. RRS Resource Manager Selection Panel

If you do not know the resource manager name, simply press Enter to get a listof resource managers known to RRMS as shown in Figure 57.

� �RRS Resource Manager List

Command ===>

Commands: v-View Details u-View URs r-Remove Interest

S RM Name StateDFHRXDM.SCSCPAA1.IBM Run DFHRXDM.SCSCPAA9.IBM ResetDFHRXDM.SCSCPAA4.IBM Run DFHRXDM.SCSCPTA2.IBM RunDFHRXDM.SCSCPAA6.IBM Reset� �

Figure 57. RRS Resource Manager List


Run state means that a CICS region has successfully connected to RRMS duringstartup, has received a resource manager token, as shown in Figure 59 onpage 99, and is for service.

7.2.5 Test 1 - Extended UOW with Implicit Syncpointing, Client Normal EndSteps:

1. Start the client and perform an EXCI call without SYNCONRETURN to targetCICS PAA1, adding a new record to VSAM file-1.

2. Perform a second EXCI call without SYNCONRETURN to target CICS PAA4,updating an existing record in VSAM file-2.

3. End the EXCI client normally.

Results:

1. Looking first at the RRS Resource Manager Details panels (Figure 58 andFigure 59) we see that PAA1 and PAA4 are known to RRMS, and each regionhas received an RM Token during startup.

� �RRS Resource Manager Details

Command ===>

Press Enter to return to the previous panel

RM name . . . : DFHRXDM.SCSCPAA1.IBM RM Token . . : 0100000102C709F00000000500000006 RM state . . : Run� �

Figure 58. RRS Resource Manager Details Panel for PAA1

� �RRS Resource Manager Details

Command ===>

Press Enter to return to the previous panel

RM name . . . : DFHRXDM.SCSCPAA4.IBM RM Token . . : 0100000102C709F0000000070000000D RM state . . : Run� �

Figure 59. RRS Resource Manager Details Panel for PAA4

The resource manager names for CICS as known to RRMS are made up ofthe program name DFHRXDM concatenated with the CICS APPLID and thequalifier IBM.

2. Now the EXCI client requests to add a record to VSAM file-1 in PAA1,omitting SYNCONRETURN in the EXCI call. Because this is the first EXCI callof this client instance, the EXCI requests a unit of recovery (UR) Identifierfrom the RRS which it then passes to the target CICS regions in each DPLrequest. Note that the UR Identifier is provided by the EXCI APIimplementation, you do not have to code it in your EXCI client program. RRSassigns a UR Identifier which exists until the entire UOW comes to an end.The UR Identifier can now be displayed in the RRS Unit of Recovery Listpanel as shown in Figure 60 on page 100.


� �RRS Unit of Recovery List

Command ===>

Commands: v-View Details c-Commit b-Backout r-Remove Interest

S UR Identifier State Type Co v B145A34D7EB9700000000057010D0000 InFlight Prot� �

Figure 60. RRS Unit of Recovery List Panel

The panel shows the units of recovery (URs) known by RRMS and theircurrent status. The EXCI client has issued its first EXEC CICS LINK, so thereis an active session with CICS, and the CSMI mirror has invoked the CICSserver program.

You can verify existence of the EXCI session by issuing a CEMT I EXCIcommand which displays the current EXCI details in CICS (Figure 61).

� � I EXCI

Exci(CICSRS3.IKJACCT.IKJACCNT - SC62)Task(0000764)Urid(B145A34D7EB9700000000057010D0000)RESPONSE: NORMAL TIME: 00.00.00 DATE: 10.28.98SYSID=PAA1 APPLID=SCSCPAA1� �

Figure 61. Result of CEMT INQUIRE EXCI for a Call without SYNCONRETURN

The first line shows from where the EXCI request originates: the userID(CICSRS3) in TSO (IKJACCT) from OS/390 image SC62. If you have to solvea problem, make sure the UR Identifier matches the one displayed in theRRS panels, so you know you are looking in the correct system and at thecorrect problem.

Another indication of an extended EXCI UOW is provided with the INQUIREUOWLINK command (Figure 62).

� �F SC53PAA1,′ CEMT I UOWL′

Uowl(01000000) Uow(B145A34D8A964106) Con Lin(RRS )Unk Rrms Ok

Uowl(01010000) Uow(B145A34D8A964106) Con Lin( DFHGEN )Unk Irc Sys(EXCG)� �

Figure 62. Result of CEMT INQUIRE UOWLINK

The controlling CICS UOW indicated in Figure 62 is the UOW of the CSMImirror transaction that handles this extended UOW in this CICS region. Thefirst link-UOW (Uowl 01000000) is the link between CICS and RRMS. This linkis established when the first extended EXCI client request arrives in CICS.CICS receives the UR Identifier and can now express interest in it. The linkremains active until the UOW is ended. The second link-UOW (Uowl01010000) is the connection between the EXCI client and CICS.

If you now enter v (for view) in the RRS Unit of Recovery List panel(Figure 60), you will receive more detailed information about a UR Identifier(Figure 63 on page 101).


� �RRS Unit of Recovery Details

Command ===>

Commands r-Remove Interest v-View URI Details

UR identifier : B145A34D7EB9700000000057010D0000 Create time : 1998/10/28 22:26:50.040956 Comments : UR state : InFlight UR type : Prot ASID : 0000 v Display Work IDs / Display IDs formatted

Luwid . : PresentEid . . : Not PresentXid . . : Not Present

Expressions of Interest: S RM Name Type Role _ DFHRXDM.SCSCPAA1.IBM Prot Participant� �

Figure 63. RRS Unit of Recovery Details Panel

Here you see that our CICS region, PAA1, has registered interest in theselected UR Identifier which shows that the extended EXCI call hassuccessfully delivered the requested UR Identifier to PAA1 in the DPLrequest. The create time displayed in this panel is Greenwich mean time(GMT).

Enter v next to Display Work IDs to get the logical unit of work (LUW) detailson the RRS Unit of Recovery Work IDs panel (Figure 64). This panel showsthe logical unit of work ID (LUWID) that has been assigned by CICS andgiven to RRMS.

� �RRS Unit of Recovery Work IDs

UR identifier : B145A34D7EB9700000000057010D0000

Logical Unit of Work Identifier (LUWID)USIBMSC.SCSCPAA1 45A34D8A7B65 0001

NetID.LuName : USIBMSC.SCSCPAA1TP Instance : 45A34D8A7B65SeqNum . . . : 0001� �

Figure 64. RRS Unit of Recovery IDs Panel

The TP Instance is an Advanced Program-to-Program Communication (APPC)term and represents the CICS CSMI instance that is processing this LUW.Note that the LUWID contains the TP instance ID, and in turn this ID ispartially made up of the CICS UOW ID for the corresponding CSMI (bytes 1 -4 match bytes 2 - 5 of the UOW ID). You can verify this, using the CEMT IUOW command. This CSMI instance is used for all resource access requeststo PAA1 that come from the same EXCI client instance within one extendedUOW. Figure 65 shows the CEMT display of the extended UOW in PAA1region.

� �F SC53PAA1,′ CEMT I UOW′

Uow(B145A34D8A964106) Inf Act Tra(CSMI) Tas(0000764)Age(00000314) Ter(RG1 ) Use(CICSUSER)� �

Figure 65. CEMT I UOW Display in PAA1


If you now select (v) the resource manager PAA1 from the RRS Unit ofRecovery Details panel (Figure 63), you get to the RRS URI Details panel(Figure 66 on page 102).

� �RRS URI Details

Command ===>

UR identifier : B145A34D7EB9700000000057010D0000 URI token . . : 7EA97000000000670000000000000000 RM name . . . : DFHRXDM.SCSCPAA1.IBM Type . . . . : Prot Role . . . . : Participant� �

Figure 66. RRS URI Details Panel

This panel gives you the last RRMS details about the current operation. Yousee the URI token that has been assigned to the requested resource accesswithin the current UR.

With each first operation on a new recoverable resource during the sameUOW such a URI token is assigned. Thus the URI token represents to RRMSthe resource that is accessed during the life of a UR. The attribute Prot (forprotected) indicates that the resource identified by the URI token is arecoverable resource. This information will be useful for syncpointdecisions.

3. Now we issue a second add request in the EXCI client, this t ime to add anew record in VSAM file-2 that is controlled by the PAA4 region. Note thatwe are still within the same UOW. In the RRS Unit of Recovery Details panel(Figure 67), you see that PAA4 now has ″joined the party″ by expressinginterest in the same UR Identifier that was assigned during the first EXCI call.


Command ===>


UR identifier : B145A34D7EB9700000000057010D0000 Create time : 1998/10/28 22:26:50.040956 Comments : UR state : InFlight UR type : Prot ASID : 0000

Display Work IDs / Display IDs formattedLuwid . : PresentEid . . : Not PresentXid . . : Not Present

Expressions of Interest: S RM Name Type Role

DFHRXDM.SCSCPAA1.IBM Prot Participant v DFHRXDM.SCSCPAA4.IBM Prot Participant� �

Figure 67. RRS Unit of Recovery Details Panel for PAA4

The type of interest is protected because this is a request that can update arecoverable resource.

Viewing the details, we see that a new URI token is assigned for this secondEXCI call within the same UR (Figure 68 on page 103).


� �RRS URI Details

Command ===>

UR identifier : B145A34D7EB9700000000057010D0000 URI token . . : 7EA97440000000680000000000000000 RM name . . . : DFHRXDM.SCSCPAA4.IBM Type . . . . : Prot Role . . . . : Participant� �

Figure 68. RRS URI Details for PAA4

The CEMT I EXCI command in PAA4, followed by the CEMT I UOW command,gives us the corresponding information in CICS showing the CSMI that isnow instantiated in PAA4 to process from now on all NOSYNCONRETURNrequests arriving from this EXCI client for the lifetime of the extended UOW(Figure 69 and Figure 70).

� � F SC53PAA4,′ CEMT I EXCI′

Exci(CICSRS3.IKJACCT.IKJACCNT - SC62)Task(0000549)Urid(B145A34D7EB9700000000057010D0000)RESPONSE: NORMAL TIME: 00.00.00 DATE: 10.28.98SYSID=PAA4 APPLID=SCSCPAA4� �

Figure 69. Results of CEMT INQUIRE EXCI for PAA4

� � F SC53PAA4,′ CEMT I UOW′

Uow(B145A59B286AE203) Inf Act Tra(CSMI) Tas(0000549)Age(00000262) Ter(RG1 ) Use(CICSUSER)� �

Figure 70. Results of CEMT INQUIRE UOW for PAA4

4. After ending the client normally without issuing the explicit commit call toRRMS, we observe that an implicit syncpoint is taken. However, rememberthat you should use explicit syncpointing as shown in 7.2.7, “Test 3: MixingEXCI Calls with and without SYNCONRETURN” on page 107 in a productionenvironment.

We verified the correct result of the file updates by printing the file contents.Additional proof can be found in a trace. In 7.2.6, “Test 2 - Extended UOWwith Implicit Syncpointing, Client Abend” and 7.2.8, “Test 4: Extended UOWwith Explicit Syncpointing” on page 108 we provide sample trace entriesfrom a generalized trace facility (GTF) trace.

7.2.6 Test 2 - Extended UOW with Implicit Syncpointing, Client AbendTest 2 is basically the same as test 1 described in 7.2.5, “Test 1 - Extended UOWwith Implicit Syncpointing, Client Normal End” on page 99, except at clienttermination, so we do not repeat the screen captures here. Instead we providefragments of the trace entries produced by GTF tracing in CICS as well as for theEXCI to review the actions performed when the EXCI client abends.

To turn on GTF tracing for the EXCI you have to change the EXCI options table,DFHXCOPT:


DFHXCO TYPE=CSECT, *TIMEOUT=0, No timeout *TRACE=2, off, 1 or 2 (2=exc.+lvl1 + lvl2 *

TRACESZE=1024, 16K trace table *DURETRY=30, Retry SDUMPS for 30 seconds *TRAP=OFF, DFHXCTRA - OFF *GTF=ON, GTF - OFF or on *

MSGCASE=MIXED, Mixed case messages *CICSSVC=0, EXCI will obtain CICS SVC number *

CONFDATA=SHOW, Show user commarea data in trace *SURROGCHK=NO Perform surrogate-user check @P1C

END DFHXCOPT

Make sure that your private loadlib (where you link the new table) is in front ofSDFHEXCI. Otherwise you will not see any GTF trace entries for the EXCI sincethe default is in effect.

Note that the component ID for the EXCI trace entries is EX and that all of theentries show TASK-XCI for task ID and KE_NUM-0000 for the kernel number.

The example in Figure 71 on page 105 contains trace entries produced for theEXCI when the EXCI client receives data from CICS PAA1 as a result of the finalEXCI call before the client abends.


The EXCI client is notified of response from PAA1.The trace record contains the commarea sent back to the client.

USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 2006 XCPRH EVENT RESPONSE_RECEIVED FROM CICS(SCSCPAA1) BY USER(DFHXCEIP)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C79B84 TIME-22:50:26.8574901882 INTERVAL-00.00017825071-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 08C5EB24 08C5EBC2 00067360 08C5EB2C *.E...E.k.E..E...E...E.B...-.E.B*

0020 00000000 00000000 00000000 00000000 08C5EBA6 88C5EBCF *.................E.whE.. *2-0000 00000006 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 E2C3E2C3 D7C1C1F1 *SCSCPAA1 *5-0000 0000009E *.... *6-0000 0810400C 430E0200 00000400 00000000 8F06F2F0 00000000 008CF1F0 F5F5F5E3 *.. ...............20.....105553*

0020 C8C9E240 E2C8D6E4 D3C44040 4040D5D6 E340C24B C8C5D9C5 E7E7E7E7 E7E7E7E7 *HIS SHOULD NOT B.HEREXXXXXXXX*0040 E7E7E7E7 E74040C3 C1E4E2C5 40C940C1 C2C5D5C4 4040E3C8 C540C3D3 C9C5D5E3 *XXXXX CAUSE I ABEND THE CLIENT*0060 404040D5 C5E640D9 C5C3D6D9 C440E6C1 E240C3D9 C5C1E3C5 C440C6D6 D940C3E4 * NEW RECORD WAS CREATED FOR CU*0080 E2E3D6D4 C5D940D5 E4D4C2C5 D9400000 008CF140 40404040 40404040 0000 *STOMER NUMBER ....1 . *

GMT-10/28/1998 22:50:26.857529 LOC-10/28/1998 17:50:26.857529USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 1001 XCPRH EXIT - DPL RESPONSE(OK) REASON(OK) DPL_RETAREA(NORMAL 00000000 40404040)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C7A428 TIME-22:50:26.8575656257 INTERVAL-00.00007543751-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 08C5EB24 08C5EBC2 00067360 08C5EB2C *.E...E.k.E...E...E...E.B..-.E.B*

0020 00000000 00000000 00000000 00000000 08C5EBA6 88C5EBCF *.................E.whE.. *2-0000 00000006 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 00000000 00000000 00000000 00000000 00000000 *.................... *5-0000 00000000 00000000 40404040 *........ *6-0000 88C6EC46 *hF.. *

GMT-10/28/1998 22:50:26.857574 LOC-10/28/1998 17:50:26.857574

since this is an EXEC CICS LINK call the pipe (session) to CICS is brokenand the inter region program disconnects the client from CICS:

USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 1000 XCPRH ENTRY - CLOSE_PIPE TOKEN(08D7E8B0) TO CICS(SCSCPAA1) BY USER(DFHXCEIP)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C7A33A TIME-22:50:26.8575966257 INTERVAL-00.00003100001-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 88C5EB24 *.E...E.k.E...E..hE.. *2-0000 00000004 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 E2C3E2C3 D7C1C1F1 *SCSCPAA1 *5-0000 08D7E8B0 *.PY. *6-0000 88C6EF5A *hF.! *

GMT-10/28/1998 22:50:26.857604 LOC-10/28/1998 17:50:26.857604USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 2002 XCPRH EVENT IRP_DISCONNECT FROM CICS(SCSCPAA1) BY USER(DFHXCEIP)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C77C6C TIME-22:50:26.8576347507 INTERVAL-00.00003812501-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 88C5EB24 *.E...E.k.E...E..hE.. *2-0000 00000004 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 E2C3E2C3 D7C1C1F1 *SCSCPAA1 *5-0000 08D7E8B0 *.PY. *

GMT-10/28/1998 22:50:26.857643 LOC-10/28/1998 17:50:26.857643USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 1001 XCPRH EXIT - CLOSE_PIPE RESPONSE(OK) REASON(OK)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C7A484 TIME-22:50:26.8576542507 INTERVAL-00.00001950001-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 88C5EB24 *.E...E.k.E...E..hE.. *2-0000 00000004 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 00000000 00000000 00000000 00000000 00000000 *.................... *5-0000 88C6EF5A *hF.! *

GMT-10/28/1998 22:50:26.857661 LOC-10/28/1998 17:50:26.857661USREF F6C ASCB 00FB5C80 JOBN CICSRS3EX 1000 XCPRH ENTRY - DEALLOCATE_PIPE TOKEN(08D7E8B0) FROM CICS(SCSCPAA1) BY USER(DFHXCEIP)

TASK-XCI KE_NUM-0000 TCB-EXCI /007F92C8 RET-88C7A33A TIME-22:50:26.8576758132 INTERVAL-00.00002156251-0000 08C5EB1C 08C5EB92 08C5EB20 08C5EB28 88C5EB24 *.E...E.k.E...E..hE.. *2-0000 00000005 *.... *3-0000 C4C6C8E7 C3C5C9D7 *DFHXCEIP *4-0000 E2C3E2C3 D7C1C1F1 *SCSCPAA1 *5-0000 08D7E8B0 *.PY. *6-0000 88C6F13E *hF1. *

GMT-10/28/1998 22:50:26.857683 LOC-10/28/1998 17:50:26.857683

Figure 71. Final EXCI Call Before Client Abend

The results are displayed at the front end. Now we request the client to abend.From the trace entries produced after the client abends (Figure 72 on page 106),you see that the new RX domain in CICS receives the order to back out andinitiates the backout actions taken in the respective CICS region.


The backout exit is driven from RRS as a result of the client ABEND.The UR (see highlighted URI) is backed out.Note that this URI does not match the URI from the RRS panels shown in7.2.5, “Test 1 - Extended UOW with Implicit Syncpointing, Client Normal End” on page 99because we created a new URI when starting the abend test.

USREF F6C ASCB 00F95880 JOBN SC53PAA1RX 0501 RXXRM ENTRY - BACKOUT_EXIT

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB21FB4 TIME-22:51:00.9387572500 INTERVAL-00.2320801875*1-0000 00000005 *.... *2-0000 B145A773 7EB97000 00000058 010D0000 *..x.=...........3-0000 42200000 *.... *

GMT-10/28/1998 22:51:00.938781 LOC-10/28/1998 17:51:00.938781USREF F6C ASCB 00F95880 JOBN SC53PAA1RX 0502 RXXRM EXIT - BACKOUT_EXIT RETURN_CODE(00000030)

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB226B0 TIME-22:51:00.9388313125 INTERVAL-00.00007406251-0000 00000005 *.... *2-0000 B145A773 7EB97000 00000058 010D0000 *..x.=........... *3-0000 00000030 *.... *

GMT-10/28/1998 22:51:00.938838 LOC-10/28/1998 17:51:00.938838

Now the CICS recovery Manager is being told that, because a backout request was receivedfrom RRS, the UOWLINK representing the RRS Unit of Recovery is going to be involved in thenext syncpoint.

RM 0301 RMLN ENTRY - FUNCTION(SET_LINK) LINK_TOKEN(01610015) RECOVERY_STATUS(NECESSARY)TASK-00804 KE_NUM-00EE TCB-QR /007D8318 RET-890DA478 TIME-22:51:00.9390088134 INTERVAL-00.0000505000

1-0000 00980000 000000E5 00000000 00000000 B8000001 00000000 04120130 01610015 *.q.....V..................../..*0020 08C2264A 8912608E 0000044F 09A13B94 D9D9E261 D4E5E240 099FEB00 891E7C88 *.B.¢i.-....|...mRRS/MVS ...i.@h*0040 08F261E8 09A13AA0 08010080 09AF0CF0 09AF47F0 0004FD70 C5E7C9E3 40404040 *.2/Y...........0...0....EXIT *0060 40404040 40404040 02050505 00050018 44440000 0C000000 0000D80A 80165920 * ..................Q....*0080 000001E0 09A13AA0 00C2015A 892901A8 88C00280 000002CB *...\.....B.!i..yh{...... *

GMT-10/28/1998 22:51:00.939015 LOC-10/28/1998 17:51:00.939015USREF F6C ASCB 00F95880 JOBN SC53PAA1RM 0302 RMLN EXIT - FUNCTION(SET_LINK) RESPONSE(OK)

TASK-00804 KE_NUM-00EE TCB-QR /007D8318 RET-890DA478 TIME-22:51:00.9390326884 INTERVAL-00.00002387501-0000 00980000 000000E5 00000000 00000000 B8000001 00000000 04120130 01610015 *.q.....V..................../..*

0020 08C2264A 8912608E 0000044F 09A13B94 D9D9E261 D4E5E240 099FEB00 891E7C88 *.B.¢i.-....|...mRRS/MVS ...i.@h*0040 08F261E8 09A13AA0 08010080 09AF0CF0 09AF47F0 0004FD70 C5E7C9E3 40404040 *.2/Y...........0...0....EXIT *0060 40404040 40404040 02050505 00050018 44440000 0C000000 0000D80A 80165920 * ..................Q....*0080 000001E0 09A13AA0 00C2015A 892901A8 88C00280 000002CB *...\.....B.!i..yh{...... *

GMT-10/28/1998 22:51:00.939039 LOC-10/28/1998 17:51:00.939039

The CICS RX domain receives information from RRS about the reason forthis exception:

RX 0402 RXUW EXIT - FUNCTION(GET_CLIENT_REQUEST) RESPONSE(EXCEPTION) REASON(BACKOUT) CLIENT_TOKEN(00000000 , 00000000) CLIENT_()

TASK-00804 KE_NUM-00EE TCB-QR /007D8318 RET-894A1354 TIME-22:51:00.9390476884 INTERVAL-00.00001500001-0000 00700000 00000193 00000000 00000000 B0340000 00000000 02000202 00000000 *.......l.......................*

0020 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*0040 00000000 00000000 00000000 00000000 00000000 00000000 00000000 08F26180 *............................2/.*0060 00000000 00000000 00000000 01000100 *................ *

GMT-10/28/1998 22:51:00.939054 LOC-10/28/1998 17:51:00.939054USREF F6C ASCB 00F95880 JOBN SC53PAA1AP D802 SPP ENTRY - ROLLBACK

TASK-00804 KE_NUM-00EE TCB-QR /007D8318 RET-894A13F8 TIME-22:51:00.9390673134 INTERVAL-00.00001962501-0000 09 *. *2-0000 00 *. *

GMT-10/28/1998 22:51:00.939074 LOC-10/28/1998 17:51:00.939074USREF F6C ASCB 00F95880 JOBN SC53PAA1RM 0201 RMUW ENTRY - FUNCTION(BACKOUT_UOW) CONTINUE(YES)

TASK-00804 KE_NUM-00EE TCB-QR /007D8318 RET-891D7748 TIME-22:51:00.9390845634 INTERVAL-00.00001725001-0000 00D00000 000000E2 00000000 00000000 B0100000 00000000 0B000202 C5C4C640 *.}.....S...................EDF *

0020 4040C5C4 D802C4D3 000560E0 00010001 000561EA 01000001 00000000 00000000 * EDQ.DL..-\....../............*0040 00000000 C4C2E4C7 E4E2C5D9 40404040 40404040 08F22090 00000000 00000000 *....DBUGUSER .2.........*0060 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*0080 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*00A0 00000000 00000000 00680000 00000028 00000000 89178410 893DD180 E5E2C1D4 *...................i.d.i.J.VSAM*00C0 C6C9D3C5 C4C6C8D4 C9D9E240 08F1F09F *FILEDFHMIRS .10. *

GMT-10/28/1998 22:51:00.939091 LOC-10/28/1998 17:51:00.939091

Figure 72. Client Abend

This GTF trace fragment does not contain any entries from the EXCI task controlblock (TCB). Instead CICS, or rather the new RX domain, takes care of thebackout. RRMS recognizes the abend and drives CICS′s backout exit. CICSthen initiates the backout routines that perform the local backout.


Note: During one of the runs for test 2 we let the CICS server program abendartificially (not shown in the examples). As a consequence, and as expected,CICS backed out the updates this server had performed. However, we did nothave routines in the client program to deal with server errors, so the updatesmade on the other CICS system were committed. This note should make it clearwhy we do not recommend implicit syncpointing.

7.2.7 Test 3: Mixing EXCI Calls with and without SYNCONRETURNSteps:

1. Perform an EXCI call without SYNCONRETURN to target CICS PAA1.Updates are to VSAM file-1.

2. Perform a second EXCI call without SYNCONRETURN to target PAA4.Updates are to VSAM file-2.

3. Try an update EXCI call with SYNCONRETURN to VSAM file-1, using thesame key as in the first call. Is the file locked (note that we are not usingRLS in this test)?

4. Try to add a new record to this file again with SYNCONRETURN.

5. End the client program normally.

Results:

This time we begin the test with the extended UOW, without putting the mirrortransaction under CEDX control because CEDX allows only one transaction at atime. After the first call is issued (without SYNCONRETURN), we activate CEDXfor CSMI, so that CEDX picks up the CSMI for the SYNCONRETURN call.

1. We have an active UR Identifier from the first EXCI call, and PAA1 has aninterest in it (see Figure 73 and Figure 74 on page 108).


Command ===>


UR identifier : B1498D207EBAB00000000004010B0000Create time : 1998/11/01 01:08:54.669790 Comments :UR state : InFlight UR type : Prot ASID : 0000


Expressions of Interest:S RM Name Type Role

DFHRXDM.SCSCPAA1.IBM Prot Participant� �Figure 73. RRS Unit of Recovery Details Panel: Test 3


� �RRS Unit of Recovery Work IDs

UR identifier : B1498D207EBAB00000000004010B0000

Logical Unit of Work Identifier (LUWID)USIBMSC.SCSCPAA1 498D200D795C 0001

NetID.LuName : USIBMSC.SCSCPAA1TP Instance : 498D200D795CSeqNum . . . : 0001� �

Figure 74. RRS Unit of Recovery Work IDs

2. A CEMT I TASK shows two active CSMIs, where one, the CSMI that handlesthe extended UOW (task 204), is halted with halt type RRS/MVS. The otherCSMI (task 206) handles the EXCI call with SYNCONRETURN (Figure 75).

� � I TA STATUS: RESULTS - OVERTYPE TO MODIFYTas(0000204) Tra(CSMI) Sus Tas Pri( 001 )

Sta(TO) Use(CICSUSER) Uow(B1498D200D95F003) Hty(RRS/MVS )Tas(0000206) Tra(CSMI) Fac(RG1 ) Sus Ter Pri( 001 )

Sta(TO) Use(CICSUSER) Uow(B1498E09989FAF05) Hty(EDF )Tas(0000208) Tra(CEDF) Fac(070B) Sus Ter Pri( 001 )

Sta(SD) Use(CICSUSER) Uow(B1498E09AE38B103) Hty(ZCIOWAIT)Tas(0000209) Tra(CEMT) Fac(070C) Run Ter Pri( 255 )

Sta(TO) Use(CICSUSER) Uow(B1498E1125EC1403)� �Figure 75. CEMT I TASK Display Showing Two Instances of CSMI

3. The INQ EXCI command gives us the EXCI information as known from earlierreleases of CICS, that is, we do not have a UR Identifier (Figure 76).

� � I EXCI STATUS: RESULTSExc(CICSRS3.IKJACCT.IKJACCNT - SC62 ) Tas(0000206)� �

Figure 76. CEMT INQUIRE EXCI Display for a Call with SYNCONRETURN

4. Trying to update the same record with a SYNCONRETURN call caused adeadlock. We had to kill the SYNCONRETURN CSMI, using FORCE, becausethe CSMI does not normally have a deadlock timeout set. So this is anadditional point of consideration when designing your EXCI application.

5. After ending the client normally we printed the file contents and observedthat all changes to the files were committed except the one that tried toupdate the locked record.

7.2.8 Test 4: Extended UOW with Explicit SyncpointingSteps:

1. Perform an EXCI call without SYNCONRETURN to target CICS PAA4.Updates are to VSAM file-2.

2. Perform a second EXCI call without SYNCONRETURN to target PAA1.Updates are to VSAM file-1.


3. Perform an explicit commit, using the SRRCMIT API from RRMS.

Results:

With the first call without SYNCONRETURN we receive a UR Identifier from RRS(see Figure 77).


Command ===>


UR identifier : B14FAD137EBAB0000000001F010B0000Create time : 1998/11/05 22:03:47.990716 Comments :UR state : InFlight UR type : Prot ASID : 0000


Expressions of Interest:S RM Name Type Role

DFHRXDM.SCSCPAA4.IBM Prot Participant� �Figure 77. RRS Unit of Recovery Details Panel: Test 4

Now we issue the second EXCI call without SYNCONRETURN. Figure 78 showsthe PAA1 region having an expressed interest in the UR Identifier.


Command ===>


UR identifier : B14FAD137EBAB0000000001F010B0000 Create time : 1998/11/05 22:03:47.990716 Comments UR state : InFlight UR type : Prot ASID : 0000


Expressions of Interest: S RM Name Type Role

DFHRXDM.SCSCPAA4.IBM Prot ParticipantDFHRXDM.SCSCPAA1.IBM Prot Participant� �

Figure 78. PAA1 Joins the Extended Unit of Recovery

The INQUIRE UOWLINK command for both regions shows the currently activeconnections each region has (see Figure 79 on page 110 and Figure 80 onpage 110). Because the second EXCI call to PAA1 is not completed yet (it isheld up by CEDX), you see two links for PAA1, whereas PAA4 shows only thelink to RRMS. When viewing the details of a uowlink, you also see thecorresponding UR Identifier as shown in the display for PAA4.


� �F SC53PAA1,′ CEMT I UOWLINK′

Uowl(01000000) Uow(B14FAE04590D5B04) Con Lin(RRS )Unk Rrms Ok

Uowl(01010000) Uow(B14FAE04590D5B04) Con Lin( DFHGEN )Unk Irc Sys(EXCG)

RESPONSE: NORMAL TIME: 17.11.16 DATE: 11.05.98SYSID=PAA1 APPLID=SCSCPAA1� �

Figure 79. CICS Connections to RRS and the EXCI client: PAA1 Region

� �F SC53PAA4,′ CEMT I UOWLINK′

Uowlink(01000002)Uow(B14FAD1333C69400)Type(Connection)Link(RRS)Action( )Role(Unknown)Protocol(Rrms)Resyncstatus(Ok)Sysid()

+ Rmiqfy() 909Netuowid(..USIBMSC.SCSCPAA4|........)Urid(B14FAD137EBAB0000000001F010B0000)RESPONSE: NORMAL TIME: 17.11.56 DATE: 11.05.98SYSID=PAA4 APPLID=SCSCPAA4� �

Figure 80. CICS Connections to RRS and the EXCI client: PAA4 Region

Now we request to commit the UOW by issuing the SRRCMIT call in the client.The test front end (Figure 81) tells us the resources are committed.

� � Returned from EXCI13, Ret.Codes are: EXCI13 RC: 0 RESP : 0 RESP2 : 0 Now press Enter to see output from Server

Resources Committed OK� �Figure 81. The Test Front End Showing the Commit Result

To prove this we print the files and analyze the trace. We show only fragmentsof the trace here.

The CICS exit running on the RRMS TCB is invoked as a consequence of theSRRCMIT call in the EXCI client. In Figure 82 on page 111, you see the URIdentifier to be committed in the second trace segment of trace point 501. FirstRRS requests PAA1 to prepare for commit, which is picked up in the RX domainof PAA1.


USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0501 RXXRM ENTRY - PREPARE_EXIT

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB29F84 TIME-22:23:18.5137760639 INTERVAL-00.7826051889* =004352=1-0000 00000002 *.... *

2-0000 B14FAD13 7EBAB000 0000001F 010B0000 *.|..=...........3-0000 00000000 *.... *

GMT-11/05/1998 22:23:18.513804 LOC-11/05/1998 17:23:18.513804USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0502 RXXRM EXIT - PREPARE_EXIT RETURN_CODE(00000030)

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB2A680 TIME-22:23:18.5138526264 INTERVAL-00.0000765625 =004353=1-0000 00000002 *.... *2-0000 B14FAD13 7EBAB000 0000001F 010B0000 *.|..=........... *3-0000 00000030 *.... *

GMT-11/05/1998 22:23:18.513859 LOC-11/05/1998 17:23:18.513859

Figure 82. Prepare to Commit for PAA1

Now the same happens in PAA4, because that region is a participant in the URas well (Figure 83).

USREF F6C ASCB 00FAA080 JOBN SC53PAA4RX 0501 RXXRM ENTRY - PREPARE_EXIT

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB21F84 TIME-22:23:18.5141491889 INTERVAL-00.0000201882 =004362=1-0000 00000002 *.... *2-0000 B14FAD13 7EBAB000 0000001F 010B0000 *.|..=...........3-0000 00000000 *.... *

GMT-11/05/1998 22:23:18.514166 LOC-11/05/1998 17:23:18.514166

Figure 83. Prepare to Commit for PAA4

Eventually the recovery managers in each participating CICS region issuecommit phase one (Figure 84).

USREF F6C ASCB 00FAA880 JOBN SC53PAA1RM FA11 RMUO ENTRY - FUNCTION(COMMIT_UOW) CONTINUE(YES)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-891D76BA TIME-22:23:18.5142516257 INTERVAL-00.0000200000 =004368=1-0000 00D00000 000000E2 00000000 00000000 B0100000 00000000 06000204 C5C4C640 *.}.....S...................EDF *

0020 4040C5C4 D802C4D3 00054060 00010001 0005416A 01000001 00000000 00000000 * EDQ.DL.. -...................*0040 00000000 C4C2E4C7 E4E2C5D9 40404040 40404040 08F24040 00000000 00000000 *....DBUGUSER .2 ........*0060 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*0080 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*00A0 00000000 80086C60 00087C5F 0008A130 0008B12F 8917B9D0 893DD010 E5E2C1D4 *......%-..@¬ . . . . . . . i..}i.}.VSAM*00C0 C6C9D3F1 C4C6C8D4 C9D9E240 08F2101F *FIL1DFHMIRS .2.. *

GMT-11/05/1998 22:23:18.514259 LOC-11/05/1998 17:23:18.514259USREF F6C ASCB 00FAA880 JOBN SC53PAA1RM F20B RMUO EVENT - About_to_call Client(APEF) Local_UOW_Id(B14FAE04590D5B04)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-891D76BA TIME-22:23:18.5142738132 INTERVAL-00.0000221875 =004369=1-0000 00000000 00000000 08F0FD40 08F0FE60 C1D7C5C6 00000000 C1D7C5C6 40404040 *.........0. .0-APEF....APEF *

0020 00000000 00000000 08F0B140 00000000 01010000 00000010 00000034 00000000 *.........0. ...................*0040 00000000 00000000 00000000 00000000 08F0FE18 08F0FE18 00000000 00000000 *................0...0..........*0060 08F0FE28 08F0FE28 00000000 00000000 00000000 00000000 00000000 00000000 *.0...0.........................*0080 00000000 00000000 *........ *

2-0000 B14FAE04 590D5B04 *.|....$. *GMT-11/05/1998 22:23:18.514283 LOC-11/05/1998 17:23:18.514283

Figure 84. Commit Phase One Starting in PAA1

RRS starts commit phase 2, and the CICS regions receive the order to confirmtheir commits. For PAA1 this is shown in the trace fragments in Figure 85 onpage 112. In the first trace entry (RX entry point 0401), you find the link tokendisplayed earlier with a CEMT I UOWLINK command. This trace entry alsoshows the recovery manager connector (RMC) token used to communicate withRRS, indicating that CICS can reuse some of its functions originally implementedfor CICS-to-CICS communication.


USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0401 RXUW ENTRY - FUNCTION(REPLY_DO_COMMIT) RMC_TOKEN(08F28180) CONTINUE(YES) SINGLE_UPDATER(NO) LINK_TOKEN(01000000)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-88C7BE8A TIME-22:23:18.5191396259 INTERVAL-00.0000178750 =004439=1-0000 00680000 0000011B 00000000 00000000 B8E02100 00000000 04CE0100 08F28180 *.................\..........2a.*

0020 890B1B80 00000001 09AFD380 09B0E5E8 09CE2078 890AF530 09CE2000 090B052F *i.........L...VY....i.5........*0040 090B152E 090B252D 090B352C 09CE3000 0102E020 090B36BF 00054000 09CE2000 *..................\...... .....*0060 01000000 090B36BF *........ *

GMT-11/05/1998 22:23:18.519146 LOC-11/05/1998 17:23:18.519146USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0211 RXUW SVC ENTRY - FUNCTION(VOTE) UR_INDEX(0CB2B220) COMMIT(YES)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-88C7BE8A TIME-22:23:18.5191548759 INTERVAL-00.0000152500 =004440=1-0000 00980000 00000192 00000000 00000000 B00A5000 00000000 0B000000 00000000 *.q.....k..........&............*

0020 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*0040 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *...............................*0060 00000000 00000000 00000000 00000000 00000000 0CB2B220 00000000 00000000 *...............................*0080 00000000 00000000 00000000 00000000 00000001 00020000 *........................ *

GMT-11/05/1998 22:23:18.519162 LOC-11/05/1998 17:23:18.519162

Figure 85. Commit Phase Two for PAA1

Now feedback is given to RRS that PAA1 has committed the UR (Figure 86).

USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0501 RXXRM ENTRY - COMMIT_EXIT

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB29F84 TIME-22:23:18.5208581259 INTERVAL-00.0009730000 =004446=1-0000 00000004 *.... *

2-0000 B14FAD13 7EBAB000 0000001F 010B0000 *.|..=...........3-0000 00000000 *.... *

GMT-11/05/1998 22:23:18.520870 LOC-11/05/1998 17:23:18.520870USREF F6C ASCB 00FAA880 JOBN SC53PAA1RX 0502 RXXRM EXIT - COMMIT_EXIT RETURN_CODE(00000030)

TASK-RXX KE_NUM-0000 TCB-RRMS /00000000 RET-0CB2A680 TIME-22:23:18.5209015634 INTERVAL-00.0000434375 =004447=1-0000 00000004 *.... *2-0000 B14FAD13 7EBAB000 0000001F 010B0000 *.|..=........... *3-0000 00000030 *.... *

GMT-11/05/1998 22:23:18.520908 LOC-11/05/1998 17:23:18.520908RM 0362 RMLSD EXIT - Decide RESPONSE(OK) CONTINUE(YES) READONLY(NO) VOTE(YES)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-88C9D7E6 TIME-22:23:18.5211091259 INTERVAL-00.0000181250 =004453=1-0000 01 *. *2-0000 00 *. *3-0000 01 *. *4-0000 00000001 *.... *

GMT-11/05/1998 22:23:18.521116 LOC-11/05/1998 17:23:18.521116

Figure 86. Commit Phase Two for PAA1: UR Committed

Now the recovery manager (RM) of PAA1 initiates logging to log the fact that ithas committed (Figure 87).

USREF F6C ASCB 00FAA880 JOBN SC53PAA1RM 02E1 RMSLW ENTRY - Write - Remark(COMMITTD)

TASK-00032 KE_NUM-00ED TCB-QR /007D82C8 RET-88C9DE74 TIME-22:23:18.5211300634 INTERVAL-00.0000209375 =004454=1-0000 88C7BE4A *hG.¢ *2-0000 C3D6D4D4 C9E3E3C4 *COMMITTD *

GMT-11/05/1998 22:23:18.521136 LOC-11/05/1998 17:23:18.521136

Figure 87. Commit Phase Two for PAA1: Recovery Manager Initiates Logging

7.3 SummaryThe EXCI provides easy access from non-CICS address spaces to resourcesunder CICS control. When you use this interface, you can avoid, for example,closing files in CICS so they could be accessed from a batch job. Therefore thisinterface can support your requirements for continous availability of your CICSapplications.


Furthermore the EXCI can be used for automation applications. With the newsupport for extended UOWs applications like these are even more attractive.You can now update CICS resources as well as a DB2 or IMS database, forexample, in one UOW and thus preserve data integrity.

The support for extended UOWs is a major enhancement for customers who wishto develop applications using products that provide Web access to CICS data,such as CICS Gateway for Java (MVS) or OS/390 Domino GO Webserver. Thelimitation of single UOWs caused by enforcement of SYNCONRETURN was asignificant inhibitor in the development of such applications prior to CICS TS 1.3.


Chapter 8. Temporary Storage Facilities on CICS TS

CICS TS 1.1 introduced the function of shared TS using a coupling facility. CICSTS 1.3 adds two new functions for TS - defining TS queues through RDO, and theuse of long queue names.

8.1 Overview of CICS Shared Temporary StorageA comprehensive overview of the shared TS service is provided in the CICSSystem Definition Guide, In this section we provide a quick review.

TS data sharing allows your CICS applications to access nonrecoverable TSqueues from multiple CICS regions running on any MVS image within a ParallelSysplex.

CICS stores a set of TS queues that you want to share across the ParallelSysplex in a TS pool. Each TS pool corresponds to a coupling facility DFHXQLSlist structure defined in the CFRM policy.

Access to a TS pool by CICS transactions running in an AOR is through a TSdata sharing server that supports a named pool. In each MVS image in theParallel Sysplex, you need one TS server for each pool defined in a couplingfacility which can be accessed from that MVS image (see Figure 88 onpage 116).

CICS regions using TS data sharing access the TS data sharing servers throughcross-memory connection services. These services (AXM server environmentservices) are defined using the MVS subsystem interface (SSI). AXM uses theSSI definition to schedule initialization in the master scheduler address space.


Figure 88. TS Servers within a Sysplex

As in previous releases of CICS, you can provide multisystem access forrecoverable queues within the Parallel Sysplex by creating a queue-owningregion (QOR) and function shipping TS requests from the AORs to the QOR.

You can also define a QOR that accesses shared TS queues so that previousreleases of CICS can function ship TS requests for shared TS queues.

With the addition of TS data sharing, there are now three possible locations forTS queues. You can define your TS queues as:

• Local• Remote• Shared

All of these TS queues can be supported concurrently. To define a sharedqueue, you need a DFHTST TYPE=REMOTE entry and a DFHTSTTYPE=SHARED entry in your TST. The TYPE=REMOTE entry specifies that TSrequests with the queue names specified by the DATAID parameter should berouted to the system specified by the SYSIDNT parameter. To route theserequests to a TS server, you need a TYPE=SHARED entry with a matching


SYSIDNT to that used in the TYPE=REMOTE entry. The TYPE=SHARED entryalso specifies a POOLNAME. This POOLNAME specifies which TS server is to beused for any TS requests for such queue names. Figure 89 on page 117 showsthe required definitions.

� �DFHTST TYPE=INITIAL, X

SUFFIX=A1DFHTST TYPE=REMOTE,SYSIDNT=PQA1, X

DATAID=SHRDFHTST TYPE=SHARED,SYSIDNT=PQA1,POOL=TSQSPQA1DFHTST TYPE=FINALEND

� �Figure 89. TST Defining a Shared Temporary Storage Queue

Note that if the SYSID parameter is specified on any TS API calls, thisspecification takes precedence over any TYPE=REMOTE definitions specified inthe TST. Should the SYSID parameter used in such a call belong to a TS server,the TS request is sent to the TS server.

The TS server can replace any TS owning regions (TSORs) that would have beennecessary to provide shared temporary storage for previous releases of CICS.(Note that a TSOR is still needed if the TS queues are to be recoverable.)

8.2 Resource Definition Online for Temporary StorageIn this release CICS continues its policy of removing the need for macro-definedcontrol tables, by extending RDO support to TSTs.

You do not have to define a TST to use temporary storage, but it provides thecapability of assigning attributes (such as recovery or security) to queuesaccording to a naming convention. CICS TS 1.1 also introduced theTYPE=SHARED entry which was the only way of identifying a shared TS pool ina coupling facility.

The RDO facility is provided by the DEFINE command on the CEDA transaction,and in the DFHCSDUP program for the new TSMODEL resource. You can alsouse CEMT to discard TS queue resource definitions while CICS is running. Thisremoves the need to shut down and restart CICS to make changes to TS queuedefinitions.

Because TSMODELs can be changed while CICS is running, inconsistencieswithin a UOW could result. Therefore, once a queue name has been matchedwith a TSMODEL, that model is cached for that UOW so that subsequent matchesfor that queue name give the same results. Any changes to the cachedTSMODELs are seen only at UOW end.

TSMODELs cannot be installed unless you are running with a TST assembledwith the MIGRATE option or no TST at all. This may cause a problem with somesupplied groups; for example, DFHWEB (which is installed if WEB=YES isspecified on the SIT) contains a TSMODEL for a TS queue that is required forsome of the Web processing.

Chapter 8. Temporary Storage Facilities on CICS TS 117

The switch between TST and RDO is permitted only on a cold start, otherwise amessage is issued, and the previous mode is used.

8.3 Defining a TSMODEL with RDOA TSMODEL is used to determine the attributes of a TS queue when it is created.Figure 90 shows the CEDA screen for a TSMODEL.

� �CEDA View TSmodel( TSTRDAAZ ) TSmodel : TSTRDAAZ Group : TSTRD Description : Example definition PRefix : Z Location : Auxiliary Auxiliary | MainRECOVERY ATTRIBUTES RECovery : No No | YesSECURITY ATTRIBUTES Security : Yes No | YesSHARED ATTRIBUTES POolname : TSQSPQA1REMOTE ATTRIBUTES REMOTESystem : REMOTEPrefix :

� �Figure 90. A TSMODEL Definit ion

Here are some points to note about various parameters:

• The PRefix specifies the character string that can be used for matchingqueue names. It can contain wildcard characters and not just the leadingcharacters for a queue. (See 8.4, “Generic Name Specification” for adiscussion of how the generic names are used for matching queue names.)It is the equivalent of the DATAID parameter for the TST but will not allow alist of character strings.

• The Location of a queue can be specified as Auxiliary or Main. Whateverlocation is given on an API command is ignored, and that given by theTSMODEL is used. Note that any definition that has been migrated will haveAuxiliary filled in as the Location.

• RECovery and POolname are mutually exclusive because it is not possible tohave recoverable queues in shared TS.

• POolname and any of the REMOTE ATTTRIBUTES are mutually exclusive, soyou cannot associate a SYSID with a shared TS pool.

8.4 Generic Name SpecificationIn the PRefix parameter of the TSMODEL it is possible to use a plus sign (+) asa generic character within a character string to indicate that any valid characteris possible in that position. For example, you could have a PRefix ofYEAR++RESULTS, which would match with a queue of YEAR98RESULTS butnot YEARENDRESULTS.


Note that if you have generic characters in a PRefix, and the TSMODEL has aREMOTEPRefix entry, the generic characters must be in the same positions inthis parameter.

If there are several TSMODEL definitions that match a specific name, CICSchooses the best match as follows:

• If there is a TSMODEL with a specific name that exactly matches, CICS usesthis model.

• If there is no exact match, the queue name is compared with the matchinggeneric entries, and the most specific entry is used.

• In comparing names to see which one is more specific, the names arecompared character by character. Where they first differ, if one has adiscrete character and the other has a generic character, the one with thediscrete character is used.

8.5 Steps for Migrating to RDO for TSTFollow these steps to migrate to RDO for TST:

1. Assemble the TST with the MIGRATE option on the TYPE=INITIAL macro.You will probably want to change the suffix for this table, so you can easilydistinquish it from the previous one. Figure 91 shows the table we used fortesting with this option specified.

� �DFHTST TYPE=(INITIAL,MIGRATE), X

SUFFIX=RD* *

DFHTST TYPE=RECOVERY, XDATAID=R

* *DFHTST TYPE=LOCAL, X

DATAID=(C,D,E,X)* *

DFHTST TYPE=REMOTE, XDATAID=AB, XSYSIDNT=PFA1, XRMTNAME=LC

* *DFHTST TYPE=REMOTE, X

DATAID=(), XSYSIDNT=PQA1

* *DFHTST TYPE=SHARED, X

SYSIDNT=PQA1, XPOOL=TSQSPQA1

* *DFHTST TYPE=SECURITY, X

DATAID=SAQ* *

DFHTST TYPE=FINALEND

� �Figure 91. Sample TST

2. Run DFHCSDUP with the MIGRATE command. Note that the output from thiscommand (Figure 92 on page 120) does not show the contents of the


TSMODELs created, so you may want to list the new group after creating it.The default name of the new group is TSTxx, where xx is the suffix.

Note that TSTRDAAA contains a TSMODEL with a PREFIX of R, which isdefined as nonrecoverable and using pool TSQSPQA1. This may seemincorrect, but it accurately reflects the behavior of the DFHTST definitions.Any queue created with this TST and beginning with an R would in fact havebeen nonrecoverable because of the all-encompassing DATAID() on theTYPE=REMOTE entry pointing to the TYPE=SHARED entry for poolTSQSPQA1. (It would, in fact, have been impossible to define anyrecoverable queues in the original TST.)

Multiple prefixes are not allowed on the TSMODEL definitions, so theTYPE=LOCAL definition in Figure 91 on page 119 creates four separateTSMODELs (TSTRDAAB, TSTRDAAC, TSTRDAAD, and TSTRDAAE inFigure 92).

TSTRDAAH contains a TSMODEL with Security set to Yes and using poolTSQSPQA1 (again due to the DATAID() mentioned above).

� �DFH5120 I PRIMARY CSD OPENED; DDNAME: DFHCSDDFH5144 I MIGRATION OF TABLE DFHTSTRD IN PROGRESS. DEFAULT GROUP IS TSTRDDFH5143 I GROUP TSTRD CREATED.DFH5159 I TSMODEL TSTRDAAA DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAB DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAC DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAD DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAE DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAF DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAG DEFINED IN GROUP TSTRDDFH5159 I TSMODEL TSTRDAAH DEFINED IN GROUP TSTRDDFH5140 I TOTAL TSMODEL DEFINITIONS CREATED: 8DFH5101 I MIGRATE COMMAND EXECUTED SUCCESSFULLY.DFH5123 I PRIMARY CSD CLOSED; DDNAME: DFHCSD

� �Figure 92. Output from MIGRATE of TST

3. Start CICS pointing to a TST with the MIGRATE option. This must be a coldstart or else this message is issued: DFHTS0103 Invalid attempt to switchbetween a TST and RDO for Temporary Storage. The attempt is ignored.

4. INSTALL the new group that has been created, if it has not been added tothe GRPLIST.

You cannot discard the TST entirely if you have programs that use the SYSID oncommands to access shared queues. It is not possible to define a TSMODELthat has both a POolname and a REMOTESystem, so the SYSID cannot point to ashared TS pool without the relevant TST definitions. The support for TSTs will beremoved in the next release, so you should consider changing any applicationprograms that currently use SYSID to access shared TS.


8.6 Long Names for Temporary Storage QueuesThe CICS TS facility is enhanced to allow TS queue names to be 16 characterslong, providing greater flexibility for generating TS queue names that are uniqueacross a CICSplex. Note that TS queue names are restricted to 16 characters bythe use of the coupling facility for TS data sharing, which imposes a maximumkey length of 16 characters.

In previous releases of CICS it was sometimes difficult to generate uniquenames by using the conventional eight character TS queue names. This problemwas exacerbated with the introduction of TS queues shared across ParallelSysplex. For example, TS queue names that relied on the convention ofincorporating a terminal ID could not expect this termid to be unique within aparallel Sysplex.

Areas such as monitoring, statistics, messages, traces, dumps, and CEBR havebeen changed to reflect the new longer names. CEDA accepts a PREFIX of 16characters, but note that the DATAID in the TST is still restricted to 8 characters.Figure 93 shows the CEDA screen for a TSMODEL with a long name.

� �CEDA View TSmodel( TSTRDAzZ ) TSmodel : TSTRDAzZ Group : TSTRD Description : Example definition PRefix : YEAR++RESULTS Location : Auxiliary Auxiliary | MainRECOVERY ATTRIBUTES RECovery : No No | YesSECURITY ATTRIBUTES Security : No No | YesSHARED ATTRIBUTES POolname : TSQSPQA1REMOTE ATTRIBUTES REMOTESystem : REMOTEPrefix :

� �Figure 93. A TSMODEL Definit ion Showing a Long Name

8.7 QUEUE and QNAMETo distinquish between the two lengths of name, they are referred to by differentoptions on commands. The QUEUE option continues to refer to the existing eightcharacter names, so existing applications do not have to be changed.

QNAME is used to refer to the new 16-character names. When writing any newapplications, use the QNAME option, which finds both short and long names.

This naming convention is followed on the API and SPI commands, so, forexample, an INQUIRE TSQUEUE only accepts names up to eight characters long,so you have to issue an INQUIRE TSQNAME for the new long names.

Note that CEMT accepts an INQUIRE TSQUEUE or INQUIRE TSQNAME and inboth instances shows all long and short names because it is inquiring onQNAME at all times (Figure 94 on page 122).


� � I TSQUEUE(*) POOL(TSQSPQA1) STATUS: RESULTS - OVERTYPE TO MODIFYTsq(SHARED ) Num(00001) Len(0000000018) Aux

Tra(CECI) Max(00018) Min(00018) Las( 00534053 )Tsq(SHAREDLONG ) Num(00013) Len(0000000234) Aux

Tra(CECI) Max(00018) Min(00018) Las( 00001787 )Tsq(..EDCSMI ) Num(00001) Len(0000000144) Aux

Tra(CEDF) Max(00144) Min(00144) Las( 00511402 )

� �Figure 94. CEMT I TSQUEUE Command Output

8.8 Restrictions on Long NamesThere are several places where the long queue names cannot be used, andthese should be noted when writing programs to take advantage of this newfeature:

• The EIB block. The length of the EIBRSRCE name field is unchanged at eightcharacters. If a long queue name is used, the EIBRSRCE field contains thefirst eight characters of the queue name.

• The REQID on the START command for BMS and interval control requestsremains unchanged at eight characters.

• The QUEUE option on START requests remains unchanged at eightcharacters.

• The RACF SCICSTST class is unchanged at 17 characters when running onOS/390 V2.5. Support will be provided for the longer queue names onOS/390 V2.6 by a PTF.

• Do not try function shipping long QNAMES to pre CICS TS 1.3 systems.


Chapter 9. CICS Business Transaction Services

In this chapter we give an overview of CICS BTS and describe the setup tasksneeded to use CICS BTS for your applications.

9.1 OverviewIn this section we provide only a brief overview of CICS BTS. For more detailssee CICS Business Transaction Services.

CICS BTS is implemented as a set of new EXEC CICS commands that extend thecurrent CICS API to make it easier to model, control, and execute complexbusiness transactions. The distinction between a business transaction and aCICS transaction is that a business transaction typically is longer lived, forexample, days, month, even years. A business transaction can live from thetime some kind of business contract is agreed on until the final payment fordelivered goods is booked and completed. A CICS transaction typically takesseconds or fractions of a second to complete.

You have implemented your business transactions in the past using a collectionof CICS transactions as the technical vehicle. Most likely these CICStransactions were scattered over a set of different applications. Moreover youhad to include a significant percentage of control logic in the program designand often in the database design as well. Some tasks needed to complete abusiness transaction required some sort of manual intervention, so the systemsupport for the business transaction was interrupted.

CICS BTS can help you to implement more system support for your businesstransactions. You can clearly seperate control logic from business logic, whichin turn promotes reuse of business logic parts in several different applications.Figure 95 on page 124 shows the major components of CICS BTS, using asimplified example of a business transaction (based on the sample SALESapplication that comes with CICS TS 1.3).


Figure 95. CICS BTS Components

Here is a short description of the components and their function. In 9.3,“Running the Sample Application” on page 132, we explain how the sampleapplication uses the components.

• To start a CICS BTS process you need an initiating CICS transaction, such asa Menu transaction as known from the past, where you have to add someCICS BTS commands that instantiate a CICS BTS process. The significantcommands here are to DEFINE the process and then request CICS BTS toRUN it.

• The RUN command causes CICS BTS to instantiate a new task invoking theroot activity program you name in the define process API. This programcontains the control logic for a particular process type. See below for anexplanation of the root activity.

• A process is the instantiation of a particular business transaction in CICS.Each process belongs to a certain process type that you define to CICS (see9.2.1, “Process Type Resource Definition” on page 126). You have to specifya unique process ID when defining the process in the initiating transaction.A process is comprised of all the activities you have implemented tocomplete a specific business transaction, for example, selling goods tocustomer X (number 111111) for his or her order number 123. A process isnot always active, but it stays alive in CICS until it is entirely completed, thatis, until all its activities have completed.

• An activity can be compared to a pseudo-conversational CICS transaction. Itimplements a specific part of the business logic that is necessary tocomplete the business transaction. An example of an activity is producingan invoice for a specific purchase.

There are two commands to invoke an activity: LINK ACTIVITY and RUNACTIVITY. LINK ACTIVITY executes a CICS BTS activity synchronously withthe requestor, in the same UOW, and under the same TRANSID and USERIDas the requestor uses. RUN ACTIVITY can be used in two distinct ways:


− RUN ACTIVITY SYNCHRONOUS invokes an activity synchronously withthe requestor but it executes as a separate UOW. It can run underTRANSID and USERID differerent from those of the requestor. Thesubordinate UOW can roll back changes that it makes to recoverableresources, but only the original UOW can commit changes made by both.

− RUN ACTIVITY ASYNCHRONOUS invokes an activity asynchronously fromthe requestor and it executes as a separate UOW. It can run underTRANSID and USERID different from those of the requestor and it isallowed to commit. This command can be seen as an evolution of theSTART command but with assurance of response through the completionevent.

For more information about this subject, see 9.3, “Running the SampleApplication” on page 132.

• A special type of activity is the root activity. This is the main controlprogram for a process, so this is where your control logic for the businesstransaction goes. The root activity is always the first activity of a process. Itspins off the (child) activities as needed and thus controls processing of thebusiness transaction through the system. The creation and running of childactivities is not limited to the root activity, however; any activity can do that.Thus you can split up the control logic in meaningful blocks.

• Events are another important component of CICS BTS applications. Youdefine at least one event for each activity, which is the activity ′s completionevent. When the completion event is fired, an activity ends, which causesthe root activity, for example, to be awakened and react to this event.

If a process needs some input from outside, such as a confirmation from aclerk, you specify an INPUT event.

• A special type of event is the timer event. CICS BTS allows you to defineyour own timer event by giving it a name and specifying how long it shouldtake before the event is fired. This is the mechanism used, for example, toimplement an automatic reminder procedure as demonstrated in the sampleapplication.

• To provide the well-known transactional support in CICS for CICS BTSapplications, there has to be a means of keeping state data on a recoverableresource. For this reason you have to create a repository data set (VSAMKSDS) and specify it in a CICS BTS process type resource definition (see9.2.1, “Process Type Resource Definition” on page 126). This data set alsoholds copies of data (from containers) exchanged among the differentactivities within a process.

• Containers are storage areas that can be passed from one activity toanother. You can place any data of any size into such a container. There isno 32 KB limitation as it is with COMMAREA length. If the stored data isneeded from other activities, you simply PUT and GET the container (one ofthe new API commands), and to be recoverable CICS BTS writes its contentsto the repository data set. You do not have to code any GETMAINS forcontainer storage; CICS BTS does that for you. You use the standard notionof SET, FROM, and INTO, with PUT and GET commands as you do with manyother EXEC CICS commands.

See 9.3, “Running the Sample Application” on page 132 to gain a betterunderstanding of how these components work together. You can read more

Chapter 9. CICS Business Transaction Services 125

about the new terms and about the new commands needed for a CICS BTSapplication in CICS Business Transaction Services.

9.2 Setup TasksBefore you can use CICS BTS for your applications you have to set up the CICSBTS environment. The setup consists of the following tasks, some of which areoptional:

1. The process type resource definition

2. The local request queue data set

3. The CICS BTS repository data set

4. Workload Management Environment (optional)

5. The audit log (optional)

9.2.1 Process Type Resource DefinitionOne of the first definitions you provide is the process type. The process type isa means of categorizing your various business transactions to distinguish themfrom one another, and it is also useful for accounting or error tracking. Youdefine the process type, using the new RDO object, PROCESSTYPE, as shown inFigure 96.

� � OBJECT CHARACTERISTICS CICS RELEASE = 0530 CEDA View PROCesstype( ORDER )

PROCesstype : ORDERGroup : CBTSDescription : PROCESS TYPE DEF. FOR TYPE SALES ORDER

INITIAL STATUSStatus : Enabled Enabled | Disabled

DATA SET PARAMETERSFile : PTYPSALE

AUDIT TRAILAUDITLOg : CBTSLOGAUDITLEvel : Full Off | Process | Activity | Full

SYSID=PAA1 APPLID=SCSCPAA1

� �Figure 96. CEDA View a Process Type

The file name defined here (PTYPSALE) names the repository file used for allCICS BTS processes of the type ORDER. See 9.2.3, “CICS BTS Repository DataSet” on page 127 for more details.

Optionally you can specify an audit log journal name on the CEDA panel(Figure 96). If you do, a corresponding journal model definition must beprovided as well. Audit log entries are produced at the level you specify forAUDITLEvel. The level can be:

• Off - if you do not want an audit trace to be produced

• Process - produces a trace entry only at a process level, for example, atinstantiation or reinstantiation of a process or the end of a process

• Activity - produces trace entries for each invocation and ending of an activity

• Full - you get the maximum trace entries in the audit log, including suchinformation as events that have fired.

For more details, see 9.2.5, “Audit Log” on page 130.


9.2.2 Local Request Queue Data SetThe local request queue data set should already be set up, it is one of theinstallation tasks for CICS TS 1.3. In CICS TS 1.3 CICS BTS is the only user ofthis data set, but in the future it may be used by CICS functions other than BTS.The local request queue holds a copy of pending requests destined for thisspecific CICS region, thus providing recoverability for such requests as CICSBTS timer events.

Note that you cannot define the local request queue data set DUMMY even if youdo not intend to use CICS BTS. If you do that, you will get the DFHSH0109 errormessage every minute. This data set cannot be shared among CICS regions,there must be one data set per region.

Figure 97 shows a copy of the JCL that creates the local request queue data set.

//DEFLRQDS JOB (999,POK),′ CICSTS13′ , MSGCLASS=T,CLASS=A,// NOTIFY=&SYSUID//*//DEFINE EXEC PGM=IDCAMS,REGION=1M//SYSPRINT DD SYSOUT=*//SYSIN DD * /* */ /* DEFINE A LOCAL REQUEST */ /* QUEUE DATASET */ /* */ DEFINE CLUSTER(NAME(CICSSYSF.CICS530.PAA1.DFHLRQ)-

INDEXED-LOG(UNDO)-CYL(1 1)-VOLUME(TOTCI3)-RECORDSIZE( 1024 4096 )-KEYS( 40 0 )-FREESPACE ( 5 5 )-SHAREOPTIONS( 2 3 ))-

DATA (NAME(CICSSYSF.CICS530.PAA1.DFHLRQ.DATA))-INDEX (NAME(CICSSYSF.CICS530.PAA1.DFHLRQ.INDEX))

/*

Figure 97. JCL to Create a Local Request Queue Data Set

The local request queue data set must be defined as a recoverable VSAM KSDS,and you have to define one per CICS TS 1.3 region. For that reason we addedthe CICS SYSID as a data set qualifier.

9.2.3 CICS BTS Repository Data SetThe CICS BTS repository data set holds state information about the CICS BTSprocesses as well as application data (container contents) that is passed amongactivities or different activations of the same activity. You can define only onedata set to hold information for all of your CICS BTS process types, or you candefine a separate data set for each process type (see 9.2.1, “Process TypeResource Definition” on page 126), or any combination of these two options.

Figure 98 on page 128 shows the JCL to create a CICS BTS repository data set.


//DEF#CBTS JOB (999,POK),′ CICSTS13′ , MSGCLASS=T,CLASS=A,// NOTIFY=&SYSUID//* ************************************************************//*//* DELETE/DEFINE THE CLUSTER FOR A CICS BTS REPOSITORY DATASET//* NOTE://* THIS DS IS USED TO HARDEN PROCESS STATE DATA//* IT CAN HOLD MORE THAN 1 PROCESSTYP, THEREFORE IT MIGHT//* BE A GOOD IDEA TO CHOOSE A NAME THAT IS NOT RELEASE OR//* SYSTEM DEPENDENT, BUT RATHER CATEGORIZES A CERTAIN PROCESS//* TYPE.//* ************************************************************//DEFINE EXEC PGM=IDCAMS,REGION=1M//SYSPRINT DD SYSOUT=*//SYSIN DD * /* */ /* DEFINE A CBTS PROCESS REPOSITORY DATASET */ /* FOR PROCESS TYPE SALE */ /* */ DEFINE CLUSTER (NAME (CICSSYSF.CBTS.PTYPSALE) -

LOG(UNDO) -CYL(2 1) -CISZ(4096) -SPANNED -VOLUMES(TOTCI4) -STORCLAS(CICSRLS) -KEYS(50 0) -INDEXED -RECORDSIZE(4096 16384) -FREESPACE( 5 5 ) -SHAREOPTIONS( 2 3 ) -

) -DATA (NAME (CICSSYSF.CBTS.PTYPSALE.DATA) -

) -INDEX (NAME (CICSSYSF.CBTS.PTYPSALE.INDEX) -

)/*

Figure 98. JCL to Create a CICS BTS Repository Data Set

Note that we defined the data set in an SMS storage class for RLS data sets. Ifyou are planning to execute CICS BTS activities that belong to the sameprocess, and you want to distribute these activities to several CICS regions, youmust access the repository in RLS mode. This is true even if you run all of theCICS regions in the same MVS image. CICS BTS does not support remote fileaccess to an FOR (attempt fails with abend AEZX). When you use CICS BTSfrom a single region, RLS is not required.

Next you have to define the file control resource definition for the CICS BTSrepository data set to CICS. Figure 99 on page 129 shows the file controlresource definition we need for the sample application.


� � OBJECT CHARACTERISTICS CICS RELEASE = 0530 CEDA View File( PTYPSALE )

File : PTYPSALEGroup : CBTSDEScription : CBTS REPOSITORY FILE

VSAM PARAMETERSDSNAme : CICSSYSF.CBTS.PTYPSALEPassword : PASSWORD NOT SPECIFIEDRLsaccess : Yes Yes | NoLSrpoolid : 1 1-8 | NoneREADInteg : Consistent Uncommitted | Consistent | RepeatableDSNSharing : Allreqs Allreqs | ModifyreqsSTRings : 001 1-255Nsrgroup :

REMOTE ATTRIBUTES REMOTESystem : REMOTEName :

REMOTE AND CFDATATABLE PARAMETERSRECORDSize : 1-32767Keylength : 1-255 (1-16 For CF Datatable)

INITIAL STATUSSTAtus : Enabled Enabled | Disabled | UnenabledOpentime : Firstref Firstref | StartupDIsposition : Share Share | Old

BUFFERSDAtabuffers : 00002 2-32767

Indexbuffers : 00001 1-32767DATATABLE PARAMETERSTABLE : No No | CIcs | User | CFMaxnumrecs : Nolimit Nolimit | 1-99999999

CFDATATABLE PARAMETERSCfdtpool :TABLEName :UPDATEModel : Locking Contention | LockingLOad : No No | Yes

DATA FORMAT RECORDFormat : V V | F

OPERATIONSAdd : Yes No | YesBRowse : Yes No | YesDELete : Yes No | YesREAD : Yes Yes | NoUPDATE : Yes No | Yes

AUTO JOURNALLINGJOurnal : No No | 1-99JNLRead : None None | Updateonly | Readonly | AllJNLSYNCRead : No No | YesJNLUpdate : No No | YesJNLAdd : None None | Before | AFter | ALl

JNLSYNCWrite : Yes Yes | NoRECOVERY PARAMETERSRECOVery : Backoutonly None | Backoutonly | AllFwdrecovlog : No No | 1-99BAckuptype : Static Static | Dynamic

SECURITYRESsecnum : 00 0-24 | Public

� �Figure 99. File Control Resource Definit ion for the CICS BTS Repository Data Set

You should define the read integrity to be consistent read, because access fromdifferent activities of a process to the same record must be serialized. It wouldbe fatal if, for example, activity 1 updated a record while activity 2, which runs inparallel, reads the same record and receives old information (for example eventX fired / not fired). In a real production environment it is probably also a goodidea to define the recovery attribute as ALL and specify a forward recovery log,because the repository holds vital data for the process including application data(your containers).

9.2.4 Distributed Routing ProgramIf you plan to balance CICS BTS activities among several CICS regions, you needlogic to provide the distribution. CICS TS 1.3 provides a new peer-to-peerrouting mechanism that enables workload management of CICS BTS processesand activities.

Refer to Chapter 10, “Dynamic Routing of START and LINK Requests” onpage 141 for a description of a new routing mechanism and, specifically, to


10.8.3, “Routing CICS BTS Processes and Activities” on page 201 for CICSBTS-related considerations.

9.2.5 Audit LogOptionally you can define an audit log for some or all of your CICS BTS processtypes. See 9.2.1, “Process Type Resource Definition” on page 126 for thecorresponding attributes in the process type resource definition. CICS BTSprovides audit points much like CICS provides trace points. However, the auditlog entries for the same process can come from different CICS regions when youbalance the workload of your processes in a Parallel Sysplex. Therefore theseentries include the CICS system ID in each record. The purpose of having anaudit log is, for example, accounting or tracking processes that are stuck. Stuckprocesses typically indicate an application design problem, however, and usuallyshould not occur.

The audit log is a CICS journal that is written by the CICS to the MVS logger.Therefore you need a log stream definition in your logger policy for the audit log.Figure 100 shows the JCL we used to update our logger policy.

//DEFALOG JOB (999,POK),′ CICSTS3′ , CLASS=A,MSGCLASS=T,// NOTIFY=&SYSUID//*//* JOB TO ADD LOGSTREAM DEFS FOR CBTS AUDIT LOG//*//* ONCE THIS IS DONE YOU SHOULD CEDA DEFINE A JOURNALMODEL//* NAME(YOURNAME) LOGSTREAM=CICSTS13.CBTS.XNAME//* SAMPLE IN GROUP(CBTS) IS CICSTS13.CBTS.CBTSLOG//*//IXCMIAPU EXEC PGM=IXCMIAPU//SYSPRINT DD SYSOUT=*//SYSIN DD *

DATA TYPE(LOGR) REPORT(YES)DEFINE LOGSTREAM

NAME(CICSTS13.CBTS.MODEL)STRUCTNAME(LOG_GENERAL_001)STG_DUPLEX(NO)LS_SIZE(2000)HLQ(CICS)HIGHOFFLOAD(60)LOWOFFLOAD(10)MODEL(YES)

/*

Figure 100. JCL to Update the Logger Policy for the Audit Log

Note that we define the log stream to be written to a coupling facility structure(LOG_GENERAL_001) that has already been defined. If you do not have anexisting structure in the coupling facility, you have to update your CFRM policyas well to include a structure with a matching name. You may of course use aDASD-only log stream for the audit log as well, in which case you do not need acoupling facility structure. If DASD-only log stream is used, it is accessible onlyfrom CICS regions running on the same MVS image. For more information aboutlogger policy definitions, see Setting Up a Sysplex.


Having defined the log stream, you now have to define a corresponding journalmodel in CICS. Figure 101 on page 131 shows the journal model for our sampleapplication.

� � OBJECT CHARACTERISTICS CICS RELEASE = 0530 CEDA View Journalmodel( CBTSLOG ) Journalmodel : CBTSLOG Group : CBTS

Description : AUDIT LOG FOR CICS BTS PROCESSESJournalname : CBTSLOGType : Mvs Mvs | Smf | DummyStreamname : CICSTS13.CBTS.CBTSLOG� �

Figure 101. Journal Model Resource Definit ion for the Audit Log

The Streamname we chose is rather generic and not specific for a CICS regionor a process type. This way we could write audit logs from any process runningin any CICS region to the same logstream. You may of course provide a moregranular naming convention if you need separate audit logs and want to avoidany contention caused by the serialization when writing the logstreams.

CICS TS 1.3 provides a utility to print the contents of the audit log. Figure 102shows the JCL we used to print the audit log.

//JATUP JOB (999,POK),′ CICSTS13′ , MSGCLASS=T,CLASS=A,// NOTIFY=&SYSUID//*******------------------------------------------**************//****** DFHATUP - CBTS AUDIT LOG UTILITY PROGRAM **************//*******------------------------------------------**************//ATUP EXEC PGM=DFHATUP,PARM=′ N(EN),P(60),T(M)′//STEPLIB DD DISP=SHR,DSN=CICSTS13.CICS.SDFHLOAD//SYSPRINT DD SYSOUT=*,DCB=RECFM=FBA <-- OUTPUT//AUDITLOG DD DSN=CICSTS13.CBTS.CBTSLOG, <-- LS NAME// SUBSYS=(LOGR,DFHLGCNV)//SYSIN DD *AUDITLOG(AUDITLOG)

/*

Figure 102. JCL to Print the Audit Log Contents

Note the subsystem exit program name, DFHLGCNV, which is different from thename known from earlier releases of CICS TS (DFHLG520 for example).

Figure 103 on page 132 shows an excerpt of the audit log printout. You can seethe beginning of our tests when process 500666 is instantiated by the EXEC CICSDEFINE PROCESS command in program DFH0SAL1. The auditlog entries showthe GMT time.


CICS BTS Audit Trail Utility - Parameter Validation Page 000001Exec Parm Options: Natlang (EN)

Translate (mixedcase)Pagesize (60)

AUDITLOG(AUDITLOG)System(PAA1) - Event - Function(Define Process) Process(Unknown)

Date(1998.317) Time(18:13:29.973776)System(PAA1) - Event - Function(Put Acq Container) Process(Unknown)

Date(1998.317) Time(18:13:33.119504)System(PAA1) - Entry - Function(Run Activity) Process(Unknown)

Date(1998.317) Time(18:13:33.119504)System(PAA1) - Event - Function(Define Activity) Process(Unknown)

Date(1998.317) Time(18:13:33.119504)System(PAA1) - Event - Function(Run Activity) Process(Unknown)


Date(1998.317) Time(18:13:33.119504)System(PAA1) - Exit - Function(Run Activity) Process(Unknown)





Date(1998.317) Time(18:13:33.119504)System(PAA1) - Event - Function(Put Container) Process(Unknown)















Date(1998.317) Time(18:13:34.168080)System(PAA1) - Event - Function(Acquire Process) Process(Unknown)


Date(1998.317) Time(18:13:51.993872)System(PAA1) - Event - Function(Delete Container) Process(Unknown)


Date(1998.317) Time(18:13:51.993872)

Figure 103. Sample Audit Log Printout

9.3 Running the Sample ApplicationIn this section we provide some details about CICS BTS processing based on theCICS BTS sales sample application provided with CICS TS 1.3. For more details,see CICS Business Transaction Services.


Refer to Figure 95 on page 124, which illustrates the major components of CICSBTS using the sample application as a base. Figure 104 on page 133 shows thecomponents of the sample application.

Figure 104. CICS BTS Sample Application

The sample application is a simple sales application, and the logic contains thefollowing steps:

1. A clerk requests an order entry screen to take a new order by calling theMENU transaction.

2. Having entered the new order data, the MENU transaction (or rather the nextpseudo-conversational step SAL1) defines a new process and requests itsexecution, using the EXEC CICS RUN ACQPROCESS command.

3. Each process is started with the root activity, which is implemented byprogram DFH0SAL2, transaction SALE in the sample. This program containsall of the control logic that is needed for the sample business transaction.After some initialization tasks, the root activity invokes the credit checkactivity, followed by the stock check activity, and then informs the user ofacceptance or rejection of the order.

Note: You have to define the transactions used for the activities beforeexecution in the normal way (RDO). If you specify DYNAMIC=YES for asynchronous activity, CICS will ignore this parameter. It honours it if theactivity is to be run asynchronously.

4. The root activity defines a composite event named INV-DEL-OK. This createsa new event in CICS BTS that is fired when both the invoicing task and thedelivery task have completed. By specifying this composite event, the rootactivity will be reinstantiated when this event fires.

The root activity defines and runs the delivery task and the invoice taskbefore it returns to CICS. From now on its status is dormant waiting onsome event to occur and reinstantiate it. Note that it is not suspended theway normal CICS tasks are, so you will not see a dormant activity with theCEMT I TASK command because it currently does not exist in the system.


We can compare the dormant state of an activity with the state of apseudo-conversational sequence when CICS waits for terminal input. In caseof a pseudo-conversation, there is nothing in the system but a COMMAREAand TCTTE state; in the CICS BTS case, there is nothing except for therecords in the repository data set.

One way to find out about a dormant activity is to use the new CICS-suppliedtransaction, CBAM, which scans the repository data set and more or lessdisplays the information stored there.

5. The credit check and stock check activities are run with the synchronousattribute. Therefore they are run synchronously to the caller and in the sameUOW.

The invoice and the delivery activities are invoked with the asynchronousattribute. Therefore these two activities run simultaneously in the system,and each has its own UOW. When the invoice activity ends, all updates ithas performed on recoverable resources are committed or backed out. Thesame is true for the delivery activity.

Note: It is important to understand that CICS BTS does not formalizecompensation. Therefore, if the customer decides to cancel the order afteryou have already sent the goods and possibly the invoice, you have toimplement one or several compensation activities to reset your databaseand reflect the new situation. It would not be a good idea to hold locks onrecords until the business transaction completes as a whole, which would bethe prerequisite for an automatic compensation mechanism. If you alreadyhave compensation procedures today to take care of such situations, all youhave to do is to include them in the CICS BTS process.

Now back to the sample application, where the invoice and the deliveryactivities eventually finish, each one firing its completion event. Because theroot activity defined the composite event, INV-DEL-OK, to consist of theinvoice complete event combined (bool AND) with the delivery completeevent, INV-DEL-OK (the composite event) is fired now.

6. Firing the composite event wakes up the root activity, which now preparesfor the reminder procedure by defining and setting a timer event to a certainamount of time. If no payment occurs before this time has expired, the rootactivity will again be instantiated—due to the timer event being fired. Then itwill invoke the reminder procedure.

7. If a payment occurs in time, an external input event is fired from the paymenttransaction. An input event must be defined in the activity that expects suchan event. This again causes a reactivation of the root activity, which nowcan do some cleanup before ending the process.

To better illustrate the flow of activities, we changed the root activity program ofthe sample application (DFH0SAL2) to produce trace records in the CICS log.Figure 105 on page 135 shows the trace entries produced from two of our tests.


With the first instantiation of a new process type you see the messages thatindicate the allocation of the repository dataset you defined for it, andthe installation of the respective audit log.

DFHFC0200 11/13/98 13:14:24 SCSCPAA1 RLS file PTYPSALE has been allocated to data set CICSSYSF.CBTS.PTYPSALE. ModuleDFHFCRO.

DFHLG0302 11/13/98 13:14:24 SCSCPAA1 Journal name CBTSLOG has been installed. Journal type: MVS CICSTS13.CBTS.CBTSLOG. DFHPG0209 11/13/98 13:14:24 SCSCPAA1 CICSUSER SALE PPT entry for DFH0SAL2 has been autoinstalled using model DFHPGAPG.

CICS BTS process for order number 500 666 initialises.That means a new task (SALE) is attached and the root program DFH0SAL2is loaded. Nevertheless this new task executes under the UOW of thecalling task (SAL1-the task with the terminal) because SAL1 requeststo run the process synchronous.The process name in the sample application is made up of the constantSALES concatenated with the order number:

SAL2:SALES500666 13:14:24entry BEGIN-PROCESS SAL2:SALES500666 13:14:24entry INITIAL-ACTIVITY SAL2:SALES500666 13:14:24entry CHECK-CREDIT-STOCK SAL2:SALES500666 13:14:24about to run Credit-CHECK Activity

now the Credit Check activity is executed synchronous, which meansthe root activity waits in the system until Credit-check returns

DFHPG0209 11/13/98 13:14:24 SCSCPAA1 CICSUSER RED1 PPT entry for DFH0RED1 has been autoinstalled using model DFHPGAPG. DFH0RED1RAN OKAY - RED1 - 13:14:24 - 13111998

credit check has finished, so the root now invokes the Stock-check activitysynchronous as well:

SAL2:SALES500666 13:14:24Credit-CHECK Activity run ok SAL2:SALES500666 13:14:24about to run Stock-CHECK Activity DFH0STOCRAN OKAY - STOC - 13:14:24 - 13111998 SAL2:SALES500666 13:14:24Stock-CHECK Activity run ok

now the order is confirmed to the user at the terminal SAL2:SALES500666 13:14:24entry ORDER-ACCEPTED-PROC

now 2 activities are invoked, the delivery note creation and the programthat produces the invoice. Both activities execute asynchronous to the callerBefore actually invoking the 2 activities the composite event DEL-INV-COMPLETEis established which is composed of invoice-ok AND delivery-ok.

SAL2:SALES500666 13:14:24entry DEL-NOTE-AND-INVOICE-ACTIVITY SAL2:SALES500666 13:14:24about to run INVOICE-BUILD async. SAL2:SALES500666 13:14:24about to run DELIV-NOTE async.

now the root activity returns to CICS and CICS BTSsets the process status to dormant.

eventually the invoice and the delivery activities end, each firing its completionevent (the actual firing cannot be shown here).

DFHPG0209 11/13/98 13:14:24 SCSCPAA1 CICSUSER INV1 PPT entry for DFH0INV1 has been autoinstalled using model DFHPGAPG. DFH0INV1RAN OKAY - INV1 - 13:14:24 - 13111998 DFHPG0209 11/13/98 13:14:25 SCSCPAA1 CICSUSER DEL1 PPT entry for DFH0DEL1 has been autoinstalled using model DFHPGAPG. DFH0DEL1RAN OKAY - DEL1 - 13:14:25 - 13111998

The composite event DEL-INV-OK fires now and re-invokes the process.Note that this now is a complete new task that CICS attaches, so inan AUX-trace you would see an new task number.After verifying why it was called the root now checks the completionstatus of both activities, because firing the completion event doesnot say if an activity has done its work correct or not.

SAL2:SALES500666 13:14:25entry BEGIN-PROCESS SAL2:SALES500666 13:14:25entry DEL-INV-CHECK SAL2:SALES500666 13:14:25entry DELIVERY-CHECK SAL2:SALES500666 13:14:25DELIV-NOTE Activity run ok SAL2:SALES500666 13:14:25entry INVOICE-CHECK SAL2:SALES500666 13:14:25INVOICE-BUILD run ok

Since both have completed ok the root now prepares the reminder activityby defining and setting a timer event.Then the root activity returns again to CICS and process SALES500666 isdormant again.

SAL2:SALES500666 13:14:25Inv.+Del.ok, prepare Reminder SAL2:SALES500666 13:14:25entry SET-TIMER-EVENT

Figure 105 (Part 1 of 2). Sample Application Trace


Now we enter a new order which instantiates a new process of the same type (SALES). SAL2:SALES333111 13:23:06entry BEGIN-PROCESS SAL2:SALES333111 13:23:06entry INITIAL-ACTIVITY SAL2:SALES333111 13:23:06entry CHECK-CREDIT-STOCK SAL2:SALES333111 13:23:06about to run Credit-CHECK Activity DFH0RED1RAN OKAY - RED1 - 13:23:06 - 13111998 SAL2:SALES333111 13:23:06Credit-CHECK Activity run ok SAL2:SALES333111 13:23:06about to run Stock-CHECK Activity DFH0STOCRAN OKAY - STOC - 13:23:06 - 13111998 SAL2:SALES333111 13:23:06Stock-CHECK Activity run ok SAL2:SALES333111 13:23:06entry ORDER-ACCEPTED-PROC SAL2:SALES333111 13:23:06entry DEL-NOTE-AND-INVOICE-ACTIVITY SAL2:SALES333111 13:23:06about to run INVOICE-BUILD async. SAL2:SALES333111 13:23:06about to run DELIV-NOTE async. DFH0INV1RAN OKAY - INV1 - 13:23:07 - 13111998 CBTSDEL1RAN OKAY - DEL1 - 13:23:07 - 13111998 SAL2:SALES333111 13:23:07entry BEGIN-PROCESS SAL2:SALES333111 13:23:07entry DEL-INV-CHECK SAL2:SALES333111 13:23:07entry DELIVERY-CHECK SAL2:SALES333111 13:23:07DELIV-NOTE Activity run ok SAL2:SALES333111 13:23:07entry INVOICE-CHECK SAL2:SALES333111 13:23:07INVOICE-BUILD run ok SAL2:SALES333111 13:23:07Inv.+Del.ok, prepare Reminder SAL2:SALES333111 13:23:07entry SET-TIMER-EVENT

So we have now 2 payments outstanding and if they do not come in time thereminder procedure is invoked. For the tests we set the time to 10 minutesand did not invoke the payment transaction, so here is the reminder for thefirst order 500 666.

SAL2:SALES500666 13:24:25entry BEGIN-PROCESS SAL2:SALES500666 13:24:25entry SEND-REMINDER SAL2:SALES500666 13:24:25about to run SEND-REMINDER async

Process SALES500666 goes back to dormant state.

DFHPG0209 11/13/98 13:24:25 SCSCPAA1 CICSUSER REM1 PPT entry for DFH0REM1 has been autoinstalled using model DFHPGAPG. DFH0REM1RAN OKAY - REM1 - 13:24:25 - 13111998

The reminder activity fires its completion event which causes reactivation.of process SALES500666 and the root now sets the time for the second reminder.

SAL2:SALES500666 13:24:25entry BEGIN-PROCESS SAL2:SALES500666 13:24:25entry DEL-REM-COMPLETE SAL2:SALES500666 13:24:25entry DELETE-TIMER-EVENT SAL2:SALES500666 13:24:25entry SET-TIMER-EVENT

Meanwhile also the time for process SALES333111 has expired, so another reminderis sent (only the beginning trace entries shown for this process):

SAL2:SALES333111 13:33:08entry BEGIN-PROCESS SAL2:SALES333111 13:33:08entry SEND-REMINDER

Now we finally invoke the payment transaction (PAYM) ″paying″ both orders:PAYM acquires the process stating the input event DELETE-TIMER.So the processes are reinvoked and after some cleanup actions the root ends them.

DFHPG0209 11/13/98 13:35:36 SCSCPAA1 070B CICSUSER PAYM PPT entry for DFH0PAY0 has been autoinstalled using modelDFHPGAPG.

DFHPG0209 11/13/98 13:35:36 SCSCPAA1 070B CICSUSER PAYM PPT entry for DFH0PASM has been autoinstalled using modelDFHPGAMP.

DFHPG0209 11/13/98 13:35:36 SCSCPAA1 070B CICSUSER PAYM PPT entry for DFH0PAS has been autoinstalled using modelDFHPGAMP.

DFHPG0209 11/13/98 13:35:36 SCSCPAA1 070B CICSUSER PAY1 PPT entry for DFH0PAY1 has been autoinstalled using modelDFHPGAPG.

SAL2:SALES500666 13:35:36entry BEGIN-PROCESS SAL2:SALES500666 13:35:36input event from PAYM received SAL2:SALES500666 13:35:36entry DELETE-TIMER-AND-EVENTS SAL2:SALES500666 13:35:36entry DELETE-PROCESS-CONTAINER

Process SALES500666 ends here. SAL2:SALES333111 13:37:15entry BEGIN-PROCESS SAL2:SALES333111 13:37:15input event from PAYM received SAL2:SALES333111 13:37:15entry DELETE-TIMER-AND-EVENTS SAL2:SALES333111 13:37:15entry DELETE-PROCESS-CONTAINER

Process SALES333111 ends here.

Figure 105 (Part 2 of 2). Sample Application Trace

Now let us see the information we can draw from the new CICS-supplied CBAMtransaction. When you enter CBAM on a CICS screen, you get a list of theprocess types known to this CICS region (see Figure 106 on page 137).


� �CBAM

Processtype File Status Auditlevel

ORDER PTYPSALE Enabled Full� �Figure 106. The CBAM List of Current Process Types

If you place the cursor under the Processtype (ORDER in this sample), CBAMdisplays a list of the currently known processes of the selected type. Figure 107shows the two processes that are currently in the system, including their status.The term ″currently in the system″ only means that CICS BTS knows about thisprocess and has some state information stored in the repository, but the processhas not completed. It does not necessarily mean that there is an activity runningthat you would see with the CEMT I TASK command. Once a process hascompleted, it is removed from the repository and the only proof that it has runwould be an audit log (or some other trace of course).

� �CBAM Processtype ORDER

Process Mode Comp Susp

SALES333111 Dormant Incomplete NoSALES500666 Dormant Incomplete No� �

Figure 107. Current Processes of a Selected Type

Placing the cursor on a process (for example, process SALES333111), andpressing Enter, you get the details of the selected process, as shown inFigure 108.

� �CBAM Process SALES333111 Processtype ORDER

Activity Mode Comp Susp

DFHROOT Dormant Incomplete NoINVOICE-BUILD Complete Normal NoDELIV-NOTE Complete Normal NoSTOCK-CHECK Complete Normal NoCREDIT-CHECK Complete Normal No� �

Figure 108. Details of Process SALES333111

CBAM displays the activities that have been defined so far in this selectedprocess and the current status and completion information of the activities. Thereminder activity is not shown yet because it is not yet defined.

Select the root activity, for example, and press Enter to display the details of theroot activity (Figure 109 on page 138).



Activity DFHROOT

Program DFH0SAL2Transid SALEUserid CICSUSER

ContainersEventsTimers� �

Figure 109. Details of the Root Activity

This screen shows the program that implements the activity, the transaction ID ituses, and the user ID under which the activity runs. It also shows the otherresources an activity may have, namely containers, events, and timers.

Each of these resources can now be selected to see whether the respectiveresource is used and the current status of each resource. Figure 110 shows thatthere is a 4-byte container in use.


Activity DFHROOT

Container Datalength

TEMP-CONTAINER 4� �Figure 110. Resource Display (Container) of an Activity

Figure 111 shows the events known by the root activity.


Activity DFHROOT

Event Type Fired Composite Timer

DELETE-TIMER Input NoDFHINITIAL System NoSEND-PAY-REM Timer No REM-TIMER� �

Figure 111. Events Known by the Root Activity

We have three events here, all with a status of not fired. This status can indicatethat:

1. The event has not yet occured for this activity instance.

or

2. The event has been reset.

We know that the DFHINITIAL event must have occurred once when the processwas started. So here you see that the initial event is reset when the activity


goes dormant. You also see that the SEND-PAY-REM event is a timer event, andthe timer is called REM-TIMER. REM-TIMER is set to a specific value, and, whenit expires, the SEND-PAY-REM event is fired.

Selecting the timer event gives you additional information about the timer, asshown in Figure 112.


Activity DFHROOT

Timer Status Event Date Time

REM-TIMER Unexpired SEND-PAY-REM 11131998 133307� �Figure 112. Timer Event Details

9.4 CICS BTS SummaryCICS BTS helps you to implement your business transaction in CICS and let thesystem control the execution times and steps that are needed to complete it. Aprocess can be acquired from any known outside source, it does not have to bea 3270 terminal. Therefore you can, for example, include CICS BTS activities inyour Internet applications and benefit from the CICS BTS state management.

The reminder handling in the sample application is a good example of how youcan simplify and improve your applications using CICS BTS. Most likely youhave implemented a weekly or monthly batch database scan that collects all theoverdue payments. Now with CICS BTS support you do not need the batch scan,because a reminder can be produced for each specific business transaction onthe spot and at the exact due date and time.

To use CICS BTS you have to change your existing application to include thenew API commands for CICS BTS. Some applications might require a moresignificant change, depending on how close the design adheres to the CICS BTSrules. However, you can reuse programs that use EXEC CICS LINK todaywithout change; that is, you can use the LINK command to link to an existingprogram from any activity. Bear in mind, however, how the UOW syncpointingrules can affect the results of an application.


Chapter 10. Dynamic Routing of START and LINK Requests

In this chapter we provide an introduction to the CICS dynamic routing functionas it is implemented in CICS TS 1.3.

10.1 Static RoutingA traditional CICSplex environment with TORs, AORs, and FORs has staticresource definitions. For example, a transaction definition in the TOR mustdescribe to which AOR it can be routed. In this case we have static routing, thatis, the transaction will always use the same remote region. Typically, whenstatic routing is used, the location of the resource is specified in the installedresource definition. There are some disadvantages with such environments:They are single points of failure, and they are not very flexible.

10.2 Dynamic RoutingWhen you use dynamic routing, you decide which AOR to use during run time.To select a suitable remote region, you can use a CICS-supplieduser-replaceable routing program. You could customize this program to balanceyour workload dynamically. However, the workload balancing capabilities of thisprogram are very limited. Therefore we suggest that you use CICSPlex SM andthe CICSPlex SM-provided routing program, EYU9XLOP, to dynamically routeyour workload.

If you are on CICS/ESA 4.1, CICS TS 1.1, or CICS TS 1.2 you can dynamicallyroute only terminal-initiated transaction workload (logical unit (LU) 0, 2, or 6.2).

The dynamic routing interface of CICS TS 1.3 and CICSPlex SM that comes withthis release of CICS support workload management of the following workloadelements:

• Terminal-initiated transactions

• Transactions invoked by a subset of the EXEC CICS START command,invoked with or without a terminal (but restrictions apply)

• CICS-to-CICS DPL requests

• Some program link requests received from outside CICS (for example, ECIcalls received from CICS Clients)

• Transactions that implement CICS BTS activities

• EXCI requests

• CICS Web Interface requests

• CICS Gateway for Java requests

• DCE RPCs

• ONC RPCs


10.3 Extended TerminologyThe dynamic routing interface has been extended in CICS TS 1.3 to supportdynamic routing for DPL and START requests, so dynamic routing can now beoriginated by all regions, not just the TOR. Therefore, the terms TOR and AORhave been replaced by new terms that we explain below.

10.3.1.1 Requesting RegionThe requesting region is the region where a transaction initiation or a programlink request is issued. Here are some examples of what we mean by″requesting region″:

• For transactions initiated from terminals, it is the TOR.

• For transactions started by EXEC CICS START commands, it is the regionwhere the START command is issued.

• For ″traditional″ CICS-to-CICS DPL calls, it is the region where the EXECCICS LINK PROGRAM command is issued.

• For program link calls received from outside CICS, it is the system out in thenetwork.

• For transactions that implement CICS BTS activities, it is the region wherethe EXEC CICS RUN ACTIVITY ASYNCHRONOUS command is issued.

10.3.1.2 Routing RegionThe routing region is the region where the routing program runs. The requestingregion and the routing region are usually the same region. The only exceptionto this is when the new transaction is STARTed by an EXEC CICS STARTcommand with a TERMID parameter (terminal-related START requests). Thiscommand can be issued by a program executing in an AOR, but the STARTrequest is processed in the TOR. In this case, therefore, the requesting region(AOR) and the routing region (TOR) are two different regions.

10.3.1.3 Target RegionThe target region is the region where the routed transaction or a program linkrequest executes.

For environments that use peer-to-peer DPL requests, the requesting, routingand target regions are usually AORs.

10.4 Dynamic Routing ModelsTwo possible dynamic routing models are available for dynamic routing of DPLand EXEC CICS START requests: the hub model, and the distributed routingmodel. Routing of traditional terminal-initiated transactions conforms to the hubmodel.

10.4.1 Hub ModelFigure 113 on page 143 shows the traditional CICSplex dynamic transactionrouting environment. TOR PTA1 owns a dynamic routing program that routestransactions between a set of AORs. The CICS-supplied dynamic routingprogram is DFHDYP. In CICS releases before CICS TS 1.3, DFHDYP was knownas the dynamic transaction routing program. Because region PTA1 runs the


dynamic routing program and also issues the routing request, it is both therequesting region and the routing region. The AORs are target regions.

Figure 113. Traditional Dynamic Transaction Routing Model

The hub model is an extension of a traditional model (Figure 114) and applies to:


• Transactions STARTed by terminal-related START commands

• Program link requests received from outside CICS

Figure 114. Hub Model

Chapter 10. Dynamic Routing of START and LINK Requests 143

10.4.2 Distributed Routing ModelIn the distributed routing model (Figure 115), every region can be both a routingregion and a target region. This is the model used for the dynamic routing ofpeer-to-peer DPL requests, EXEC CICS START requests that are not related to aterminal (no TERMID parameter), and CICS BTS processes and activities. Arouting program runs in each participating region and is called a distributedrouting program.

The distributed routing model applies to the routing of:

• Peer-to-peer (CICS-to-CICS) DPL requests

• EXEC CICS START requests that are not related to terminals

• Transactions that implement CICS BTS activities

Figure 115. Distributed Routing Model

10.5 Routing ProgramsThe names of two different routing programs that are now available, the dynamicrouting program and the distributed routing program, are specified with separateSIT parameters. The DTRPGM SIT parameter is used to specify the dynamicrouting program. The DSRTPGM SIT parameter is used to specify the distributedrouting program.

Both programs get passed the same COMMAREA, which is mapped byDFHDYPDS DSECT. Therefore you do not have to write separate routingprograms for both dynamic routing and distributed routing, because the sameprogram can provide the two functions, using two different subroutines.However, if you are using CICSPlex SM provided with CICS TS 1.3, you do nothave to write your own dynamic routing or distributed routing program at all,because the EYU9XLOP routing program can provide both functions if youspecify its name on both the DTRPGM and DSRTPGM SIT parameters.

10.5.1 Dynamic Routing ProgramYou can use the dynamic routing program to route:


• Transactions initiated by a subset of terminal-related EXEC CICS STARTcommands (see Figure 116 on page 145 and Figure 117 on page 146)


• Program link requests

You cannot use the dynamic routing program to route transactions that areinitiated by non-terminal-related EXEC CICS START commands or transactionsthat implement CICS BTS activities.

The dynamic routing program must be specified on the DTRPGM SIT parameter.

Figure 116. Pre-CICS TS 1.3 START Processing

Before CICS TS 1.3, an EXEC CICS START TRAN(nnnn) TERMID(nnnn) issued in atarget region would be routed back to run in the initiating region, as shown inFigure 116.


Figure 117. CICS TS 1.3 START Processing

In CICS TS 1.3, the transaction referred to in the EXEC CICS START TRAN(nnnn)TERMID(nnnn) statement can now be defined as routable and does not have tobe routed back to the initiating region to run, as shown in Figure 117.

10.5.1.1 Invocation for Terminal-Initiated Dynamic TransactionRoutingFor transactions initiated from user terminals or by eligible EXEC CICS STARTcommands, CICS invokes the dynamic routing program as follows:

• CICS looks at the transaction definition for the transaction named in theinitiation request. If the definition specifies DYNAMIC(YES), the dynamicrouting program is invoked; otherwise, CICS looks for a static definition of aremote system, and the dynamic routing program is not invoked.

• If a transaction definition is not found in the routing region, CICS uses thecommon transaction definition specified on the DTRTRAN SIT parameter andinvokes the dynamic routing program. The DTRTRAN parameter is usedwhen you want to eliminate the need for resource definitions for individualtransactions in the routing region. The default value for the DTRTRANparameter is CRTX. This default CICS-supplied sample transaction resourcedefinition is provided in the DFHISC CSD group.

• If a transaction defined as DYNAMIC(YES) is initiated by an EXEC CICSSTART command that is ineligible for dynamic routing, the routing programis invoked for notification only. It cannot route the transaction.

• If an error occurs in route selection

• After the routed transaction has completed, if the initial invocation requestsreinvocation at termination

• If a routed transaction abends, and the initial invocation requestedreinvocation at termination


Figure 118 on page 147 illustrates how the dynamic routing program is invokedfor dynamic transaction routing.

Figure 118. Terminal-Initiated Dynamic Transaction Routing

10.5.1.2 Invocation for Dynamic Routing of Program Link RequestsFor a program link request to be eligible for dynamic routing, the remoteprogram must either:

• Be defined to the local system as DYNAMIC(YES)

or

• Not be defined to the local system, in which case:

- If program autoinstall is inactive, the dynamic routing program is invoked.

- If program autoinstall is active, the autoinstall user program is invoked.The dynamic routing program is then invoked only if the autoinstall userprogram installs a program definition that specifies DYNAMIC(YES) or doesnot install a program definition.

Figure 119 on page 148 illustrates how the dynamic routing program is invokedfor program link requests.


Figure 119. Dynamic Routing of Program Link Requests

Figure 119 is also true for the following types of program link requests that canbe dynamically routed:

• Calls received from the CICS Web Interface

• Calls that passed through CICS Gateway for Java

• Calls from EXCI client programs

• ECI calls from any of the CICS Client workstation products

• DCE RPCs

• ONC RPCs

10.5.2 Distributed Routing ProgramThe distributed routing program uses the distributed routing model (seeFigure 115 on page 144). Its name is specified on the DSRTPGM SIT parameter.A distributed routing model is actually a peer-to-peer system. The dynamicrouting program itself is distributed.

You can use the distributed routing program to route transactions that:

• Implement CICS BTS activities


• Are initiated by non-terminal-related EXEC CICS START commands

You cannot use the distributed routing program to route:


• Transactions initiated by terminal-related EXEC CICS START commands

• Program link requests

To route these types of transactions you must use the program named on theDTRPGM SIT parameter. The dynamic routing program is invoked only if theresource is defined as DYNAMIC(YES). The distributed routing program isinvoked even if the transaction is defined as DYNAMIC(NO). Figure 120 showsthe method of routing non-terminal initiated START requests.

Figure 120. Non-Terminal-Initiated START Processing

For CICS BTS processes and activities started by EXEC CICS RUNASYNCHRONOUS commands, CICS invokes the distributed routing program atthe following points:

• For routing the activity. This occurs when the transaction associated withthe activity is defined as DYNAMIC(YES). The distributed routing program isinvoked by the router region.

• For notification of a statically routed request. This occurs when thetransaction associated with the activity is defined as DYNAMIC(NO), and the


routing program is unable to route the activity. The distributed routingprogram is invoked by the router region.

The routing program could, however, do other things such as update a countof activities that are currently executing on the target region. If the RUNcommand specifies a delay, the routing program is invoked after the delayexpires.

• If an error occurs in route selection, for example, if the target region chosenby the routing program on the route selection call is unavailable. This givesthe routing program the opportunity to specify an alternative target. Thisprocess iterates until the target program selects a target that is available orsets a nonzero return code. The distributed routing program is invoked bythe router region.

• When the activation starts on the target region (that is, when the routedtransaction starts), if the initial invocation specified reinvocation. Thedistributed routing program is invoked by the target region.

• At the end of the routed transaction (activation), if the initial invocationspecified reinvocation. The distributed routing program is invoked by thetarget region.

• If the routed transaction (activation) abends, if the initial invocation specifiedreinvocation. The distributed routing program is invoked by the targetregion.

To determine whether the dynamic routing program or the distributed routingprogram is invoked, and what kind of routing then takes place, see Figure 121,which summarizes which router is invoked in which kind of request.

Figure 121. Dynamic Router or Distributed Router


10.6 Using the COMMAREA When Writing a DTRPROG or DSTRPRGThe same COMMAREA is passed to both the dynamic routing program and thedistributed routing program. Some parameters are meaningful to one routingprogram but not to the other. Some parameter values may be passed to onerouting program but not to the other.

10.6.1 COMMAREA Passed to Dynamic Routing ProgramWe must distinguish here between two cases: dynamic transaction routing anddynamic routing of DPL requests.

10.6.1.1 Dynamic Transaction RoutingFor transaction routing, DFHAPRT, the relay program, passes a COMMAREA tothe dynamic routing program. Figure 122 on page 154 shows the COMMAREApassed to the dynamic routing program. For transaction routing, the datapassed to the dynamic routing program in the COMMAREA includes:

• The SYSID of the remote CICS region specified when the transaction wasinstalled

• The netname of the remote region

• The name of the remote transaction

• The dispatch priority of the remote transaction (MRO only)

• Whether or not the request is to be queued if no sessions are immediatelyavailable to the remote CICS region

• The address of the remote transaction′s COMMAREA

• The address of a copy of the transaction′s terminal input output area (TIOA)

• A task local user data area

The dynamic routing program can accept these values, or change them, or tellCICS not to continue routing the transaction.

If you decide to develop your own dynamic transaction routing logic, you can usethe parameters passed to the dynamic routing program to do the following:

• Change the default target CICS region

SYSID (SYSID) and DYRNETNM (NETNAME) are the relevant parametersused to change the target region. You can change the SYSID and/ornetname that is passed in the COMMAREA. The following algorithms areused to determine the region to which the transaction is routed:

− If the NETNAME and the SYSID are not changed

CICS uses the SYSID specified in the COMMAREA.

− If the NETNAME is not changed, but the SYSID is changed

CICS updates the COMMAREA with the NETNAME corresponding to thenew SYSID and tries to route to the new SYSID.

− If the NETNAME is changed, but the SYSID is not changed

CICS updates the COMMAREA with a SYSID corresponding to the newNETNAME and tries to route to the new SYSID.

− If the NETNAME is changed and the SYSID is changed


CICS overwrites the COMMAREA with a SYSID corresponding to the newNETNAME and tries to route to that new SYSID.

• Change the program name

Parameter DYRLPROG contains the name of an initial program that can beused as an alternative. For example, if all target regions are unavailable,you can run the transaction locally, using the program specified inDYRLPROG. The alternative program can be used to handle the situation.

• Tell CICS whether to route or terminate a transaction

When the dynamic routing program gets control, you can specify a nonzerovalue in parameter DYRRETC if you do not want to route the transaction. Ifyou supply a return code of x ′08′, the transaction is terminated with anabend and a message. If you supply a return code of x′04′, the transaction isterminated without a message or abend.

• If the system is unavailable or unknown

The dynamic routing program gets control again if the request could not berouted. The remote system name might be invalid or unknown. In this caseyou can specify a return code to abend the transaction or retry the routingrequest by setting the return code to zero and DYRQUEUE to Y. To retry therequest, you can also change the SYSID and issue a return code of zero.

• Invoke the dynamic routing program at end of routed transactions

You can set DYROPTER to Y to get control again when the routed transactionhas completed.

• Invoke the dynamic routing program on abend

If you have set DYROPTER to Y, you also get control if the routed transactionabends. You could use this to initiate error handling.

• Modify the application ′s COMMAREA

Parameter DYRACMAA points to the application′s COMMAREA. Thus youcan make changes against the application′s COMMAREA. For example, ifyour routing program has changed the remote transaction ID, it may alsohave to change the input COMMAREA passed to the routed transaction.

Refer to the CICS TS Customization Guide for a full description of how to writedynamic routing programs.

10.6.1.2 Dynamic Routing of a Distributed Program Link RequestYou can also use the parameters in the COMMAREA for dynamic routing of DPLrequests. If you want to develop your own version of the dynamic routingprogram, you could use the information in the COMMAREA to do the following:

• Change the target CICS region

The COMMAREA initially contains the default SYSID and NETNAME of theCICS region to which the link request is to be routed. The region to whichthe link request is routed is determined as follows:

− If the NETNAME and the SYSID are not changed

CICS uses the SYSID specified in the COMMAREA

− If the NETNAME is not changed, but the SYSID is changed

CICS updates the COMMAREA with the NETNAME corresponding to thenew SYSID and tries to route to the new SYSID.


− If the NETNAME is changed, but the SYSID is not changed

CICS updates the COMMAREA with a SYSID corresponding to the newNETNAME and tries to route to the new SYSID.

− If the NETNAME is changed and the SYSID is changed

CICS overwrites the COMMAREA with a SYSID corresponding to the newNETNAME and tries to route to that new SYSID.

• Change the program name

Parameter DYRLPROG contains the name of the program to be linked. If youspecified the REMOTENAME option of the installed program definition,DYRLPROG contains that name. If you have not specified REMOTENAME,the name from the PROGRAM option of the EXEC CICS LINK command isused. By overwriting the DYRLPROG field, you can specify that analternative program is to be linked.

• Change the transaction ID

CICS obtains the transaction ID, using the following sequence:

− From the TRANSID option on the LINK command

− From the TRANSID option on the program definition

− If neither of the TRANSID options is specified, the generic mirrortransaction CSMI is used.

Parameter DYRTRAN can be changed to specify a different transaction ID.

• Tell CICS whether to route or terminate a DPL request

When the dynamic routing program gets control for routing (but not fornotification only), you can decide whether the request should be rejected orrouted to the target system. To reject the routing request, you return anonzero value in DYRRETC of the COMMAREA. The program that issued theLINK request is returned a PGMIDERR condition.


If, for whatever reason, the route request fails, the dynamic routing programgets control again. When this happens, you can give up routing the requestby returning a nonzero value in DYRRETC, or you can set DYRQUEUE to Y toretry. You can also change the SYSID and issue a return code of zero to tryto route the request again.

• Invoke the dynamic routing program at end of routed requests

If you specify DYROPTER of the COMMAREA to Y, the dynamic routingprogram gets control again after the request has completed. If the linkedprogram abends and DYROPTER is set to Y, the dynamic routing programgets control to notify it of the abend.

• Modify the application ′s input COMMAREA

For example, if your routing program changes the name of the remoteprogram, it may also have to change the input COMMAREA passed to theprogram. The pointer to the application′s COMMAREA is held inDYRACMAA of the routing program′s COMMAREA.


DFHDYPDS DSECTDYRFUNC DS CL1 FUNCTION CODEDYRCOMP DS CL2 COMPONENT CODEDYRFILL1 DS CL1 (RESERVED)DYRERROR DS CL1 ROUTE SELECTION ERROR CODEDYROPTER DS CL1 TRANSACTION TERMINATION OPTIONDYRQUEUE DS CL1 QUEUE-THE-REQUEST INDICATORDYRFILL2 DS CL1 (RESERVED)DYRRETC DS F RETURN CODEDYRSYSID DS CL4 DEFAULT/SELECTED SYSIDDYRVER DS H VERSION OF THE INTERFACEDYRTYPE DS CL1 TYPE OF ROUTING REQUESTDYRFILL3 DS CL2 (RESERVED)DYRTRAN DS CL8 DEFAULT/SELECTED REMOTE TRANIDDYRCOUNT DS F NUMBER OF INVOCATIONS COUNTDYRBPNTR DS F ADDRESS OF INPUT BUFFERDYRBLGTH DS F LENGTH OF INPUT BUFFERDYRRTPRI DS CL1 PASS PRIORITY TO AOR?DYRFILL4 DS CL1 (RESERVED)DYRPRTY DS H PRIORITY TO BE PASSED TO AORDYRNETNM DS CL8 NETNAME MATCHING SYSIDDYRLPROG DS CL8 PROGRAM TO BE RUN IF ROUTED* LOCALLYDYRDTRXN DS CL1 DTRTRAN INDICATORDYRDTRRJ DS CL1 DTRTRAN REJECT?DYRFILL5 DS CL2 RESERVEDDYRSRCTK DS XL4 MVS WLM SRC TOKENDYRABNLC DS XL4 ABNORMAL EVENT CODEDYRABCDE DS CL4 TRANSACTION ABEND CODEDYRCABP DS CL1 CONTINUE ABEND PROCESSING?DYRFILL6 DS CL1 RESERVEDDYRFILL7 DS CL2 RESERVEDDYRACMAA DS F APPLICATION COMMAREA ADDRESSDYRACMAL DS F APPLICATION COMMAREA LENGTH* THE FOLLOWING 6 FIELDS APPLY TO CICS BTS TRANSACTIONSDYRCBTS DS 0CL124DYRPROCN DS CL36 CBTS PROCESS NAMEDYRPROCT DS CL8 CBTS PROCESS TYPEDYRACTN DS CL16 CBTS ACTIVITY NAMEDYRACTID DS CL52 CBTS ACTIVITY IDDYRACTCMP DS CL1 CBTS ACTIVITY COMPLETINGDYRACTCCMP DS CL1 CBTS PROCESS COMPLETINGDYRFILL8 DS CL2 RESERVEDDYRFILL9 DS CL8 RESERVEDDYRUAPTR DS F ADDRES OF USER AREADYRUSER DS CL128 USER AREA*DYRCLEN EQU *-DFHDYPDS SIZE OF COMMAREA

Figure 122. COMMAREA Passed to a Dynamic Routing Program


10.6.2 COMMAREA Passed to Distributed Routing ProgramIn this section we explain how you can use the information in the COMMAREAthat is passed to the distributed routing program to develop your own routinglogic. Figure 123 on page 156 shows the communications area passed to thedistributed routing program. For example the following actions could beperformed:

• Change the target CICS region

Unlike the dynamic routing program, the distributed routing program cannotselect a target region by supplying a netname. Therefore any value set inthe DYRNETNM field of the COMMAREA is ignored. The target must bespecified by the SYSID.

When the COMMAREA is passed to the distributed routing program, itinitially contains the SYSID of the default CICS region to which thetransaction is to be routed. This SYSID is derived from the value of theREMOTESYSTEM option of the installed transaction definition. When thedistributed routing program gets control for route selection, the SYSID canbe changed.

• Tell CICS whether to route the transaction

You can influence whether the transaction should be routed to a targetregion or run locally. If you set a return code of zero in DYRRETC of theCOMMAREA, the transaction gets routed. If you want the transaction to runlocally, specify a nonzero return code.


If a request can not be routed, for whatever reason, the distributed routingprogram is invoked again. When this happens you can either run thetransaction locally by setting a nonzero value in DYRRETC or change theSYSID and issue a return code of zero in DYRRETC to try to route thetransaction to a different target region.

• Invoke the distributed routing program on the target region

The initial call invokes the distributed routing program on the requesting orrouting region. The distributed routing program can be reinvoked on thetarget region by setting DYROPTER to Y. On the target region the distributedrouting program is reinvoked when:

− The routed transaction is about to be initiated on the target region.

− The routed transaction terminates.

− The routed transaction abends.


DFHDYPDS DSECTDYRFUNC DS CL1 FUNCTION CODEDYRCOMP DS CL2 COMPONENT CODEDYRFILL1 DS CL1 (RESERVED)DYRERROR DS CL1 ROUTE SELECTION ERROR CODEDYROPTER DS CL1 TRANSACTION TERMINATION OPTIONDYRQUEUE DS CL1 QUEUE-THE-REQUEST INDICATORDYRFILL2 DS CL1 (RESERVED)DYRRETC DS F RETURN CODEDYRSYSID DS CL4 DEFAULT/SELECTED SYSIDDYRVER DS H VERSION OF THE INTERFACEDYRTYPE DS CL1 TYPE OF ROUTING REQUESTDYRFILL3 DS CL2 (RESERVED)DYRTRAN DS CL8 DEFAULT/SELECTED REMOTE TRANIDDYRCOUNT DS F NUMBER OF INVOCATIONS COUNTDYRBPNTR DS F ADDRESS OF INPUT BUFFERDYRBLGTH DS F LENGTH OF INPUT BUFFERDYRRTPRI DS CL1 PASS PRIORITY TO AOR?DYRFILL4 DS CL1 (RESERVED)DYRPRTY DS H PRIORITY TO BE PASSED TO AORDYRNETNM DS CL8 NETNAME MATCHING SYSIDDYRLPROG DS CL8 PROGRAM TO BE RUN IF ROUTED* LOCALLYDYRDTRXN DS CL1 DTRTRAN INDICATORDYRDTRRJ DS CL1 DTRTRAN REJECT?DYRFILL5 DS CL2 RESERVEDDYRSRCTK DS XL4 MVS WLM SRC TOKENDYRABNLC DS XL4 ABNORMAL EVENT CODEDYRABCDE DS CL4 TRANSACTION ABEND CODEDYRCABP DS CL1 CONTINUE ABEND PROCESSING?DYRFILL6 DS CL1 RESERVEDDYRFILL7 DS CL2 RESERVEDDYRACMAA DS F APPLICATION COMMAREA ADDRESSDYRACMAL DS F APPLICATION COMMAREA LENGTH* THE FOLLOWING 6 FIELDS APPLY TO CICS BTS TRANSACTIONSDYRCBTS DS 0CL124DYRPROCN DS CL36 CBTS PROCESS NAMEDYRPROCT DS CL8 CBTS PROCESS TYPEDYRACTN DS CL16 CBTS ACTIVITY NAMEDYRACTID DS CL52 CBTS ACTIVITY IDDYRACTCMP DS CL1 CBTS ACTIVITY COMPLETINGDYRACTCCMP DS CL1 CBTS PROCESS COMPLETINGDYRFILL8 DS CL2 RESERVEDDYRFILL9 DS CL8 RESERVEDDYRUAPTR DS F ADDRES OF USER AREADYRUSER DS CL128 USER AREA*DYRCLEN EQU *-DFHDYPDS SIZE OF COMMAREA

Figure 123. COMMAREA Passed to a Distributed Routing Program

One of the parameters passed to the dynamic routing program and thedistributed routing program is the service and reporting class token. Thedynamic and distributed routing programs can make intelligent routing decisionsbased on the workload goal and the current performance of the system. Once


the program makes a decision, it alters either the SYSID or the NETNAME to tellCICS which is the target region when the COMMAREA is returned.

10.7 Managing Dynamic and Distributed Routing with CICSPlex SMIn this section we suggest ways of implementing dynamic routing of DPL andSTART requests and CICS BTS activities provided in CICS TS 1.3. The approachwe took when writing this section was to assume that:

• Customers want to avoid changing their applications whenever possible.

• There are no affinities in the system as data sharing is provided.

• Customers want to avoid changing their configuration whenever possible.

This section is based on our experiences and our configuration, but you shouldbe able to match various aspects of our environment with yours.

One of the first issues we encountered was how to map existing regions to huband distributed models when dealing with multiple releases of CICS. In ourenvironment we had a mix of CICS TS 1.3 and CICS/ESA 4.1 regions. This posedchallenges when we defined routing sets for dynamic STARTs and CICS BTSsets.

During our initial planning of hub and distributed designs we found the diagramin Figure 124 helpful in terms of understanding exactly who does what within thetwo models.

Figure 124. Combined Hub and Distributed Models: A Perspective


Taking the ITSO environment we arranged the CICS TS regions in the twomodels. Most regions are common across the two models, which will usually bethe case.

The Hub model (Figure 125) shows that we left the traditional environment aloneand have a conventional TOR-AOR environment. But we decided to create anew AOR set for all of the CICS TS regions that support the new functions wewill use.

Figure 125. ITSO Hub Model

The distributed model (Figure 126 on page 159) maps the new model to the oldenvironment. It is not expected that users will change their configuration much ifat all. The only addition now is that we have connectivity between the AORs inthe configuration.


Figure 126. ITSO Distributed Model

CICSPlex SM workload management optimizes processor capacity in anenterprise by dynamically routing transactions and programs to whichever CICSregion is the most appropriate at the time, taking into account any transactionaffinities that may exist. Workload management can dynamically route:

• Transactions invoked at a terminal

• Transactions invoked using terminal-related START commands

• CICS-to-CICS DPL requests

• Inbound client LINK requests, including those originating from:

− The CWI

− The CICS Gateway for Java

− Other MVS address spaces (EXCI)

− CICS Client (ECI)

− DCE RPCs

− ONC RPCs

− IIOP interface

− Any program that issues an EXEC CICS LINK

− CICS BTS processes and activities.


10.7.1 LimitationsAny CICS system may act as a requesting region, a routing region, or a targetregion, as long as:

• All of the CICS systems associated with a workload are part of the sameCICSplex or, for CICS BTS processes and activities, part of the sameCBTSplex. They do not have to reside in the same MVS image in theParallel Sysplex.

• For dynamic routing of EXEC CICS START commands, the routing regionsand target regions are running at the CICS TS 1.3 level.

• For dynamic routing of DPL requests, the routing regions are running at theCICS TS 1.3 level. The target regions can be any level of CICS.

• For dynamic routing of transactions and static routing, the CICS systemacting as either a requesting region or a routing region is CICS/ESA 3.3 orlater. The CICS systems acting as target regions can be running any versionof any CICS platform supported by CICSPlex SM.

• The CICS system is defined as local to a CMAS involved in managing theCICSplex; that is, it cannot be a remote MAS. It must use CICSPlex SMfacilities to communicate with that CMAS.

A CICS system can act as a target region in one or more workloads. However, itcan act as a routing region in one and only one workload. A CICS system canact as routing region and a target region in the same workload.

When a CICS system acting as a target region is combined with other targetregions to form a CICS system group, each of the target regions should haveaccess to all of the resources required by any transactions that may be routed tothat CICS system group.

10.7.2 Changes to CICSPlex SM DefinitionsIn Appendix A, “CICSPlex SM New and Changed Views” on page 235, wediscuss and show all of the new and altered CICSPlex SM views and screens inthis release. The majority of the changes have been made to reflect theenhancements to dynamic routing. In sections that follow, we explain thechanges that are relevant to the examples we will present.

10.7.2.1 CICSSYS Definition As we have already discussed, the terms ′TOR′ and ′AOR′ have now beenreplaced in dynamic routing terminology by the terms Requesting Region orRequester, Routing Region or Router, and Target Region or Target. Therefore,when you create a CICS system definition in CICSPlex SM, the WorkloadAttributes view reflects this terminology change, as shown in Figure 127 onpage 161.

If you specify YES for Routing support active, you are indicating that this regionis a routing region, and is associated with an appropriate workload definition.The default is NO.

If you specify YES for Target routing at startup, you are indicating that theregion is a potential target for workload routing at startup. The default is NO.


Because in this example YES is specified for both options, the region will be botha router and a target. It would more likely have been an AOR in previousreleases.

� �------------- Create System - Workload Attributes - for SCSPLEX ---------COMMAND ===>

System name SCSCPAA1 Description AOR1 for plex SCSPLEX

Routing support active ===> YES (YES, NO)

Target routing at startup ===> YES (YES, NO)� �Figure 127. CICSSYS Create System View

10.7.2.2 PROGDEF DefinitionWhen you create a program definition in CICSPlex SM BAS now, you are askedto determine whether it will be dynamic or not (see Figure 128). If you specifyYES for Dynamic, you are indicating that an EXEC CICS LINK to this program willinvoke the dynamic routing program. The default is NO.

� �------------------ Create Program Definition for SCSPLEX ----------------COMMAND ===>

Name ===> PFC1PRG Version ===> 0

Description ===> RESGROUP ===> User Data ===>

Language ===> COBOL (ASSEMBLER, C, COBOL, LE370, PLI, RPG, N/A) Reload ===> NO New copy of program loaded (NO, YES) Resident ===> NO Resident status (NO, YES) Usage ===> NORMAL Storage release (NORMAL, TRANSIENT) UseLPAcopy ===> NO Program used from LPA (NO, YES) Status ===> ENABLED Program status (ENABLED, DISABLED) Cedf ===> YES CEDF available (YES, NO) Datalocation ===> BELOW Data location (BELOW, ANY) Execkey ===> USER Program key (USER, CICS) Executionset ===> FULLAPI Program run mode (FULLAPI, DPLSUBSET) Remotesystem ===> CICS region for shipped DPL request Remotename ===> Program name in remote CICS region Transid ===> Transid for remote CICS to attach Rsl ===> Resource security value (0-24,PUBLIC,blank) Dynamic ===> NO Dynamic routing (NO, YES) Concurrency ===> N/A Concurrency (N/A, QUASIRENT, THREADSAFE)

� �Figure 128. New Program Definit ion Panel


10.7.2.3 TRANDEF DefinitionWhen you create a transaction definition in CICSPlex SM BAS now, you have tospecify whether or not the transaction will be routable (see Figure 129). If youspecify YES for Routable, you are indicating that this transaction, when invokedwith an EXEC CICS START, should be dynamically routed. The default is NO.

� �------------ Create Transaction Definition for SCSPLEX Page 4 -----------------COMMAND ===> Name PFC1 Version 0

Brexit ===> Name of bridge exit

Tclass ===> Task class (NO, 1-10, blank) PrimedSize ===> Primed storage allocation size (0-65520,blank) Extsec ===> N/A External security manager used (NO, YES, N/A) Transec ===> Transaction security value (1-64, blank)Rsl ===> Resource security value (0-24, PUBLIC, blank) Routable ===> NO Routable (NO, YES)

� �Figure 129. New Transaction Definit ion Panel

10.7.2.4 WLMSPECWhen you create a workload management specification (Figure 130 onpage 163), you are asked to specify the name of a CICS system or CICS systemgroup that is to be the target for any transactions or programs not associatedwith a transaction group. This name is entered in the Target Scope field.

Additionally, you can now optionally specify a new affinity relationship fortransactions that are not associated with a transaction group, based on the CICSBTS application. Use the BAPPL option for the Affinity Relation field.

If you specify BAPPL for the Affininty Relation, you must also indicate whetherthe affinity lifetime of the transactions, will be for the duration of a CICS BTSactivity or a CICS BTS process. This is indicated by the ACTIVITY, PROCESS,PERMANENT, or SYSTEM option of the Affinity Lifetime field.


� �-------------------- Create WLM Specification for SCSPLEX ---------------COMMAND ===>

WLM Spec Name ===> Description ===> Distributed Routing Spec

Affinity Relation ===> Default Affinity Relation(USERID, LUNAME, GLOBAL, BAPPL)

Affinity Lifetime ===> Default Affinity Lifetime(SIGNON, LOGON, SYSTEM, PERMANENT, PCONV, DELIMIT,ACTIVITY, PROCESS)

Match Key ===> USERID Default Primary search criteria(USERID, LUNAME)

Create Affinity ===> N/A Create auto affinity (YES, NO, N/A) Target Scope ===> DISTCICS Default CICS System,Group or Generic

Event Name ===> RTADEF, STATDEF or Generic

Abend Health ===> 0 Target ABEND Health Factor (0 - 99) Abend Load ===> 0 Target ABEND Load Factor (0 - 99) Algorithm Type ===> QUEUE Algorithm Type (GOAL, QUEUE)� �

Figure 130. Create WLM Specification Panel

10.7.2.5 TRANGRPThe TRANGRP CREate screen has been altered so that you can now specifyadditional affinities, based on the CICS BTS application (see Figure 131 onpage 164).

You can now optionally specify a new affinity relationship for transactions thatare not associated with a transaction group, based on the CICS BTS application.Use the BAPPL option for the Affinity Relation field.

If you specify BAPPL for the Affininty Relation, you must also indicate whetherthe affinity lifetime of the transactions, will be for the duration of a CICS BTSactivity or a CICS BTS process. Use ACTIVITY, PROCESS, PERMANENT, orSYSTEM option of the Affinity Lifetime field.


� �------------------------ Create Trangroup for SCSPLEX -------------------COMMAND ===>

Trangroup name ===> Description ===> Transactions for RLS mode file

Status ===> ACTIVE Transaction Group Status(ACTIVE,DORMANT)

Match Key ===> LUNAME Primary WLMDEF search criterion(USERID,LUNAME)

Affinity Relation ===> Optional affinity relation may be:(USERID,LUNAME,GLOBAL,BAPPL)

Affinity Lifetime ===> Optional affinity lifetime may be:(SIGNON,LOGON,PCONV,DELIMIT,SYSTEM,PERMANENT,ACTIVITY,PROCESS)

Create Affinity ===> N/A Create Auto Affinity (YES, NO, N/A) Event Name ===> RTADEF/STATDEF or generic

Abend Health ===> 0 Target ABEND Health Factor (0 - 99) Abend Load ===> 0 Target ABEND Load Factor (0 - 99)

� �Figure 131. Create Trangroup Panel

10.7.2.6 WLMAWORKThe WLMAWORK view (Figure 132) has been amended to show a Rout Cntinstead of a TOR Cnt in earlier releases, and a Targ Cnt instead of an AOR Cnt.The Rout Cnt field indicates the number of active CICS systems in the workloadthat are identified as routing regions. The Targ Cnt field indicates the number ofactive CICS regions in the workload that are identified as target regions.

Because it is possible that this workload can be shared with another CMASrunning at an earlier release of CICSPlex SM, certain options could be specifiedin the various components of the workload in this CMAS (such as CICSBTS-related definitions), that are not supported in the other CMAS.

If Shared status field is set to Yes, the workload contains no CICS BTS data andthe workload exists on CMASs that are at release level 1.4 and lower releases.No CICS BTS data can be installed into a Shared(YES) workload.

If Shared status field is set to No, the workload may or may not have CICS BTSdata.

>W1 =WLMAWORK==========SCSPLEX==ALLCICS==30NOV1998==14:42:11====CPSM=====================================1CMD Name Ownr Rout Targ Affinity Lifetime Target Event Status Cre Algorith Description Shared--- -------- ---- Cnt- Cnt- -------- --------- Scope--- Name---- ------ Aff -------- ---------------status SCSWS01Q PCA1 2 5 NONE NONE SCSCG001 ACTIVE N/A QUEUE NO

Figure 132. WLMAWORK View


10.7.2.7 BTS SetsA BTS set defines the set of interconnected regions across which related BTSprocesses and activities can execute.

The definition of a BTS process is discussed in detail in the CICS BusinessTransactions Services manual. The ″rules″ governing the participating regions ina BTS set are that each region in the set must:

• Be interconnected with each other

• Be in the same CICSplex

• Have access to the BTS repository data sets in RLS mode

• Be within the same MVS Parallel Sysplex

Once the BTS set is established, BTS processes and activities can bedynamically routed across the regions in the set. However, only asynchronousactivities and processes, that is, those initiated by a RUN ASYNCHRONOUScommand, can be dynamically (or statically) routed. Processes and activitiesthat are activated synchronously with the requester, that is, through the RUNSYNCHRONOUS or LINK command, must be run locally, and cannot be routed,either dynamically or statically.

If you issue a LINK command to an activity whose associated transaction isdefined as DYNAMIC(YES), this attribute is ignored, and the activity runs locally.However, if you issue a RUN SYNCHRONOUS command against an activitywhose associated transaction is defined as DYNAMIC(YES), the activityterminates with a transaction abend.

10.7.3 Modifying EYU9WRAMFor users who currently modify EYU9WRAM to influence or change the routingdecision made by CICSPlex SM, a number of changes have been made to theCOMMAREA (copybook) passed. EYURWCOM has been changed to add newfields to support dynamic routing of DPL and START requests. The newCOMMAREA is highlighted in Figure 133 on page 166.

If you plan to use this module with distributed routing models, ensure that theEYURWCOM module is accessible to your router regions, which can of course bethe AORs.


/*******************************************************************/ 00400000/* */ 00800000

/* CONTROL BLOCK NAME = EYURWCOM */ 01200000 /* */ 01600000 /* NAME OF MATCHING ASSEMBLER CONTROL BLOCK = EYURWCOM */ 02000000 /* C CONTROL BLOCK = EYUCWCOM */ 02400000 /* PLI CONTROL BLOCK = EYUPWCOM */ 02800000 /* COBOL CONTROL BLOCK = EYULWCOM */ 03200000 /* */ 03600000 /* DESCRIPTIVE NAME = %PRODUCT EYU9WRAM Commarea Copybook */ 04000000 /* */ 04400000 /* %COPYRIGHT */ 04800000 /* */ 05200000 /* STATUS = %CP00 */ 05600000 /* */ 06000000 /* FUNCTION = */ 06400000 /* COMMAREA Passed to a Workload Manager Routing */ 06800000 /* Action Module (WRAM). */ 07200000 /* */ 07600000 /* This copybook may be included in a user written */ 08000000 /* Routing Action Module in order to facilitate */ 08400000 /* communication between the Action module and the CPSM */ 08800000 /* Services. */ 09200000 /* */ 09600000 /* Copybook EYURWCOD may be used to define the values for */ 10000000 /* the INDICATORs, RESPONSES and REASONS defined in this */ 10400000 /* copybook. */ 10800000 /* */ 11200000 /* NOTES : */ 11600000 /* DEPENDENCIES = S/370 */ 12000000 /* RESTRICTIONS = None */ 12400000 /* MODULE TYPE = Control block definition */ 12800000 /* PROCESSOR = PL/X */ 13200000 /* */ 13600000 /* --------------------------------------------------------------- */ 14000000 /* */ 14400000 /* CHANGE ACTIVITY : */ 14800000 /* */ 15200000 /* $SEG(EYURWCOM),COMP(WLM),PROD(%PRODUCT): */ 15600000 /* */ 16000000 /* PN= REASON REL YYMMDD BDXIII : REMARKS */ 16400000 /* $L2= 707 %JU 980929 HD1LPJ : Non term routed starts */ 16600000/* $L0 SM1 %S0 910123 BDEJWB : BASE RELEASE */ 16800000

/* $L1= 709 %JU 980929 HD1LPJ : CBTS changed the spec */ 16800100 /* $P0= M28866 %JU 980623 HDGOGS : Generate Copybook */ 17200000 /* $P1= M28720 %JU 980612 HD0PIHR : Force samples to be rebuilt */ 17600000 /* $P2= M28866 %JU 980622 HDGOGS : Fix Commarea Length */ 18000000/* $L1 SM1 %JU 970110 HD1LPJ : CICS 5.3 support */ 18400000/* */ 18800000/*******************************************************************/ 19200000

DCL 1 EYURWCOM BASED(EYURWCOM_POINTER), 19600000/* Control Block Prefix */ 20000000

2 WCOM_PREFIX, 204000003 WCOM_SLENGTH FIXED BIN(15), /* Structure Length */ 208000003 WCOM_ARROW CHAR(1), /* ″>″ delimiter */ 212000003 WCOM_NAME CHAR(8), /* ″EYURWCOM″ */ 216000003 WCOM_BLANK CHAR(1), /* ″ ″ */ 220000003 WCOM_PGMNAME CHAR(8), /* ″EYU9WRAM″ */ 22400000/* Call Type Indicator: @NEW */ 22800000/* 0 = ROUTE SELECTION @NEW */ 23200000/* 1 = ERROR IN ROUTE SELECTION @NEW */ 23600000/* 2 = ROUTED TRANSACTION TERMINATED @NEW */ 24000000/* 3 = ROUTED TRANSACTION ABENDED @NEW */ 24400000/* 4 = ROUTE NOTIFY @NEW */ 24800000

Figure 133 (Part 1 of 4). EYURWCOM Changes


2 WCOM_CTYPE CHAR(1), 25200000/* Route Selection Error Code: @NEW */ 25600000/* 0 = SYSID NOT FOUND @NEW */ 26000000/* 1 = SYSID OUT OF SERVICE @NEW */ 26400000/* 2 = NO SESSIONS IMMEDIATELY AVAILABLE @NEW */ 26800000/* 3 = TIMEOUT ON ALLOCATE @NEW */ 27200000/* 4 = QUEUE PURGED ON ALLOCATE @NEW */ 27600000/* 5 = Function not supported @NEW */ 28000000/* 6 = DPL - LENGERR @NEW */ 28400000/* 7 = DPL - PGMIDERR @NEW */ 28800000/* 8 = DPL - INVREQ @NEW */ 29200000/* 9 = DPL - NOTAUTH @NEW */ 29600000/* A = DPL - TERMERR @NEW */ 30000000/* B = DPL - ROLLBACK @NEW */ 30200000/* C = NTIS - Transiderr @NEW */ 30250000/* D = NTIS - ioerr @NEW */ 30300000/* E = NTIS - useriderr @NEW */ 303500002 WCOM_ERR_ROUTE CHAR(1), 30400000/* Initial Call Type Indicator @NEW */ 308000002 WCOM_INIT_CTYPE CHAR(1), 31200000/* Workload Manager Caller Indicator: @NEW */ 31600000/* 0 = CICS/ESA Relay Program @NEW */ 32000000/* 1 = External Service Program @NEW */ 32400000/* 2 = Scheduler Services @NEW */ 326000002 WCOM_CALLER CHAR(1), 32800000/* Default Remote SYSID @NEW */ 332000002 WCOM_REM_SYSID CHAR(4), 33600000/* Default Remote TRANSID @NEW */ 340000002 WCOM_REM_TRANID CHAR(8), 34400000/* Default Remote APPLID @NEW */ 348000002 WCOM_REM_APPLID CHAR(8), 35200000/* Invocation Count @NEW */ 356000002 WCOM_CALL_COUNT FIXED BIN(31), 36000000/* Input Buffer Pointer @NEW */ 364000002 WCOM_INP_BUFF PTR, 36800000/* Input Buffer Length @NEW */ 372000002 WCOM_INP_BUFFL FIXED BIN(31), 37600000/* Task Priority @NEW */ 380000002 WCOM_TASK_PRIO CHAR(2), 38400000/* Task Service Class Token @NEW */ 388000002 WCOM_SCLASS CHAR(4), 39200000/* Request Type: @NEW */ 39600000/* 0 = Dynamic routing request @NEW */ 40000000/* 1 = Notify request @NEW */ 40400000/* 2 = Dynamic transaction START request @NEW */ 40800000/* 3 = Dynamic transaction START with data request @NEW */ 41200000/* with data request @NEW */ 41600000/* 4 = Dynamic routing of DPL @NEW */ 42000000/* 5 = Dynamic routing of CBTS request @NEW */ 42200000/* 6 = Non terminal START request @NEW */ 423000002 WCOM_DYRTYPE CHAR(1), 42400000/* Reserved @NEW */ 428000002 WCOM_FILL2 CHAR(1), 43200000/* DPL Program name @NEW */ 436000002 WCOM_DYRLPROG CHAR(8), 44000000/***************************************************************/ 44400000/* */ 44800000/* WCOM_WORK_AREA and WCOM_WORK_LNTH are for the use of the */ 45200000/* WRAM program. If the WRAM program requires work area, it */ 45600000/* can obtain storage and anchor the address and length. Each */ 46000000/* Time the WRAM program is called for a specific transaction */ 46400000/* instance, the two fields will be properly set by CPSM. In */ 46800000/* this fashion, the WRAM program can obtain and manage */ 47200000/* storage which is persistent for the duration of the routed */ 47600000/* transaction. It is the responsibility of the WRAM program */ 48000000/* to free the area, as appropriate. */ 48400000/* */ 48800000/***************************************************************/ 49200000



2 WCOM_WORK_AREA PTR, 49600000/* Persistent Storage Length @NEW */ 500000002 WCOM_WORK_LNTH FIXED BIN(31), 50400000/* CPSM Service Status Indicator: @NEW */ 50800000/* 0 = CPSM SERVICES ARE AVAILABLE @NEW */ 51200000/* 1 = SM_SCOPE AND SM_BALANCE are NOT AVAILABLE @NEW */ 516000002 WCOM_STATUS CHAR(1), 52000000/* Terminal Type @NEW */ 52400000/* 0 = TERMINAL IS LU2 TYPE @NEW */ 52800000/* 1 = TERMINAL IS LU6 TYPE @NEW */ 53200000/* 2 = TERMINAL TYPE IS UNKNOWN @NEW */ 53600000/* 3 = TRANSACTION HAS NO TERMINAL @NEW */ 540000002 WCOM_TERM_TYPE CHAR(1), 54400000/* Reserved @NEW */ 548000002 WCOM_FILL3 CHAR(2), 55200000/* API Token Value @NEW */ 556000002 WCOM_DA_TOKEN FIXED BIN(31), 56000000/* WRAM Return Code to CPSM @NEW */ 564000002 WCOM_RET_RESP FIXED BIN(31), 56800000/* Applid of Last Selected AOR @NEW */ 572000002 WCOM_ERR_APPLID CHAR(8), 57600000/* Sysid of Last Selected AOR @NEW */ 580000002 WCOM_ERR_SYSID CHAR(4), 58400000/* Transaction Id for Task @NEW */ 588000002 WCOM_TRANSID CHAR(8), 59200000/* Userid @NEW */ 596000002 WCOM_USERID CHAR(8), 60000000/* Luname @NEW */ 604000002 WCOM_LUNAME CHAR(17), 60800000/* Reserved @NEW */ 612000002 WCOM_FILL4 CHAR(3), 61600000/* CPSM API Response Code @NEW */ 620000002 WCOM_API_RESP FIXED BIN(31), 62500000/* CPSM API Reason Code @NEW */ 630000002 WCOM_API_REASON FIXED BIN(31), 63500000/* Scope Vector Element List Pointer @NEW */ 640000002 WCOM_SCOP_VECT PTR, 64500000/* Scope Vector Count @NEW */ 650000002 WCOM_SCOP_CNT FIXED BIN(31), 65500000/* APPLID of SM_BALANCE Selected AOR @NEW */ 660000002 WCOM_SEL_AOR CHAR(8), 66500000/* SYSID of SM_BALANCE Selected AOR @NEW */ 670000002 WCOM_SEL_SYSID CHAR(4), 67500000/* Affinity State Indicator: @NEW */ 68000000/* U = AFFINITY IS NOT DEFINED @NEW */ 68500000/* C = AFFINITY IS ACTIVE AND IS COMMITTED @NEW */ 69000000/* D = AFFINITY IS DEFINED @NEW */ 69500000/* A = AFFINITY IS ACTIVE @NEW */ 70000000/* BLANK = AFFINITY STATUS IS UNKNOWN @NEW */ 705000002 WCOM_AFF_STAT CHAR(1), 71000000/* DTRTRAN Status Indicator @NEW */ 71500000/* 0 = TRANSACTION IS NOT A DTRTRAN @NEW */ 72000000/* 1 = TRANSACTION IS A DTRTRAN @NEW */ 725000002 WCOM_DTRTRAN_IND CHAR(1), 73000000/* DTRTRAN Rejection Indicator @NEW */ 73500000/* 0 = DO NOT REJECT THE TRANSACTION (DEFAULT) @NEW */ 74000000/* 1 = REJECT THE TRANSACTION @NEW */ 745000002 WCOM_DTRREJ_IND CHAR(1), 75000000/* Affinity AOR Status @NEW */ 75500000/* BLANK = NOT APPLICABLE @NEW */ 76000000/* 0 = THE AOR IS OK @NEW */ 76500000/* 1 = THE AOR IS DOWN @NEW */ 77000000/* 2 = THE AOR IS ACTIVE BUT HAS TERMINATED AND RESTARTED */ 77500000/* SINCE THE AFFINITY WAS INITIALLY CREATED @NEW */ 78000000/* 3 = THE AOR IS ACTIVE BUT THE LINK TO IT IS NOT */ 78500000/* AVAILABLE @NEW */ 79000000



2 WCOM_AFFAOR_STAT CHAR(1), 79500000/* Transaction Group Affinity Type @NEW */ 80000000/* 0 = NONE @NEW */ 80500000/* 1 = GLOBAL @NEW */ 81000000/* 2 = USERID @NEW */ 81500000/* 3 = LUNAME @NEW */ 82000000/* 4 = BAPPL @NEW */ 825000002 WCOM_AFF_TYPE CHAR(1), 83000000/* Transaction Group Affinity Lifetime @NEW */ 83500000/* 0 = NOT APPLICATION @NEW */ 84000000/* 1 = PSEUDO CONVERSATION @NEW */ 84500000/* 2 = SIGNON @NEW */ 85000000/* 3 = LOGON @NEW */ 85500000/* 4 = SYSTEM @NEW */ 86000000/* 5 = PERMANENT @NEW */ 86500000/* 6 = DELIMIT @NEW */ 87000000/* 8 = ACTIVITY @NEW */ 87500000/* 9 = PROCESS @NEW */ 880000002 WCOM_AFF_LIFE CHAR(1), 88500000/* WLM Automatic Affinity Create Status @NEW */ 89000000/* 0 = WLM WILL NOT AUTOMATICALLY CREATE AFFINITY AT */ 89500000/* SM_BALANCE @NEW */ 90000000/* 1 = WLM WILL AUTOMATICALLY CREATE AFFINITY AT */ 90500000/* CREATE AFFINITIES AT @NEW */ 91000000/* SM_BALANCE @NEW */ 91500000/* 2 = NOT APPLICABLE @NEW */ 920000002 WCOM_AFF_AUTO CHAR(1), 92500000/* Reserved */ 930000002 WCOM_FILL5 CHAR(1), 93500000/* Workload Name */ 940000002 WCOM_WORK_NAME CHAR(8), 94500000/* Transaction Group Name */ 950000002 WCOM_TGRP_NAME CHAR(8), 95500000/* Event Name */ 960000002 WCOM_EVENT_NAME CHAR(8), 96500000/* Transaction Commarea Address */ 970000002 WCOM_COMMAREA PTR, 97500000/* Length of Transaction Commarea */ 980000002 WCOM_COMMAREAL FIXED BIN(31), 98500000/* CBTS Process Name */ 985200002 WCOM_PROCESS_NAME CHAR(36), 98540000/* CBTS Process Type */ 985600002 WCOM_PROCESS_TYPE CHAR(8), 98580000/* CBTS Process Id */ 986000002 WCOM_PROCESS_ID CHAR(52), 98620000/* CBTS Activity Id */ 986400002 WCOM_ACTIVITY_ID CHAR(52), 98670000/* CBTS Activity Name */ 987000002 WCOM_ACTIVITY_NAME CHAR(16), 98730000/* CBTS Process completing Indicator @NEW */ 98760000/* N = Process completing, NO @NEW */ 98790000/* Y = Process completing, YES @NEW */ 988200002 WCOM_PROCESS_COMP CHAR(1), 98850000/* CBTS Activity completing Indicator @NEW */ 98880000/* N = Activity completing, NO @NEW */ 98910000/* Y = Activity completing, YES @NEW */ 989400002 WCOM_ACTIVITY_COMP CHAR(1); 98970000

99000000DCL EYURWCOM_POINTER PTR; 99500000


10.7.4 Ensuring DTRPROG and DSRTPGM Are SetWhen using dynamic or distributed transaction routing, it is important to havefallback plans just in case the routing does not work as you had planned. Whenyou use CICSPlex SM as the router, it is even more important to ensure that theCICSPlex SM environment is built before any dynamic routing advice isrequested. In this section we briefly discuss ways in which you can ensure thatCICSPlex SM is available before any routing takes place. One of the biggestquestions always raised is, ″what happens to DTR if the CMAS is unavailable?″

Figure 134 on page 170 shows the various scenarios where routing will takeplace depending on CICSPlex SM availability.


Figure 134. When Does CICSPlex SM Route?

As you can see the key areas where some external intervention is necessary arewhere the MVS image has just been IPLed, the CMAS (and associated ESSS)have yet to start, and hence the workload has yet to be built on that MVS image.There are two ways to ensure that routing does not take place until the CMAS,ESSS, and workload are ready:

1. Ensure that, through job scheduling packages (for example, OPC/A), the TORis never started before successful initiation of the CMAS. The final messageissued by the CMAS is ″EYUXL0008I CICSplex registration complete″.

2. Initially set the DTRPROG and DSRTPGM names to your own dynamicrouting program, potentially running locally in the requester region. Thismethod has the effect of running transactions and programs locally untilrouting is available. When CICSPlex SM is available, use RTA todynamically reset the DTRPROG and DSRTPGM names to EYU9XLOPthrough an RTADEF, RTAGROUP, and RTASPEC assigned to the regions.With this method your regions are not keyed to the success of the CMASstartup. Because RTA cannot start in the region until the CICSPlex SMenvironment has been built and connectivity gained to the CMAS, theDTRPROG and DSRTPGM names cannot be reset until after that event.

To sum up, careful consideration of the various potential failure scenarios helpsto ensure a smooth and well-policed dynamic routing environment.

10.8 Dynamic Routing ExamplesThe examples in this section demonstrate the many dynamic routing capabilitiesavailable with CICS TS 1.3. We tested all the examples in the ITSO environment.


10.8.1 Dynamic Routing of Program Link RequestsIn this section we cover the setting up and testing of a simple application thatwill use dynamic routing of program link requests. The example shows whichresources you have to define, change, and reinstall to ensure that a DPL requestcan pass through the dynamic routing program. For the purposes of thisexample we assume that:

• CICSPlex SM is used to provide routing information.

• CICSPlex SM BAS is used for resource definitions.

• The configuration shown in Figure 135 is in place.

Figure 135. Dynamic Routing of Program Link Requests: CICS Region Configuration

10.8.1.1 The ITSO Test Application: DPLP2PxxThe applications we wrote for this test consisted of four programs that simplyexecuted, wrote a message to a shared TS queue (using the new QNAMEformat), and LINKed to the new program (see Figure 136 on page 172 throughFigure 140 on page 176). The starting transaction, DP2P, is dynamically routedto an AOR through normal dynamic transaction routing and then the DPLs arerouted from the AOR. To run the application we had to set up a number ofdefinitions in CICSPlex SM as we describe below.


TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** ** MODULE NAME = DPLP2PST ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** STARTS THE DYNAMIC PEER TO PEER APPLICATION** DPLPGM01 ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** STATUS = %SP00 ** **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ** ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8MSG2 DS 0CL30MSG02 DS CL30*DPLP2PST CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*

MVC APPL,=8C′ X′MVC MSG01,=C′ DPL PEER-PEER PROG ST EXECUTED ON APPL => ′

*EXEC CICS ASSIGN X

APPLID(APPL)** SEND A MESSAGE BACK TO THE USER*

EXEC CICS IGNORE CONDITION QIDERR*

EXEC CICS DELETEQ TS QNAME(′ DPLPEERTOPEERTES′ )*

EXEC CICS WRITEQ TS QNAME(′ DPLPEERTOPEERTES′ ) XFROM(MSG) LENGTH(50)

*MVC MSG02,=C′ . . . ISSUING START FOR TRAN DP01′

*EXEC CICS WRITEQ TS QNAME(′ DPLPEERTOPEERTES′ ) X

FROM(MSG2) XLENGTH(30)

*EXEC CICS START TRANSID(′ DP01′ )

*MVC MSG02,=C′ . . . START ISSUED FOR TRAN DP01 ′



*EXEC CICS RETURNEJECT

*END

Figure 136. Program Link Sample Application: DPLP2PST Program


TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** ** MODULE NAME = DPLPGM01 ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** INITIAL PGM THAT CALLS DPLPGM02 ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** FLOW = DPLPGM01 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM02) ** DPLPGM02 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM03) ** DPLPGM03 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS LINK PGM(DPLPGM04) ** DPLPGM04 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** ** STATUS = %SP00 ** **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ** ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8MSG2 DS 0CL30MSG02 DS CL30*DPLPGM01 CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*

MVC APPL,=8C′ X′MVC MSG01,=C′ DPL PEER-PEER PROG 01 EXECUTED ON APPL =>′

*EXEC CICS ASSIGN X


EXEC CICS WRITEQ TS QNAME(′ DPLPEERTOPEERTES′ ) XFROM(MSG) XLENGTH(50)

MVC MSG02,=C′>>>ISSUING LINK FOR PROGRAM 02′*

EXEC CICS WRITEQ TS QNAME(′ DPLPEERTOPEERTES′ ) XFROM(MSG2) XLENGTH(30)

* EXEC CICS LINK PROGRAM(′ DPLPGM04′ ) X* TRANSID(′ DP04′ )

EXEC CICS LINK PROGRAM(′ DPLPGM02′ )*

MVC MSG02,=C′<<<RETURNING FROM LINK PROG 02′*


EXEC CICS RETURNEJECT

*END

Figure 137. Program Link Sample Application: DPLPGM01 Program


TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** MODULE NAME = DPLPGM02 ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** PGM THAT CALLS DPLPGM03 ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** FLOW = DPLPGM01 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM02) ** DPLPGM02 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** ** EXEC CICS LINK PGM(DPLPGM03) ** **BYPASSED DPLPGM03 ** ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS LINK PGM(DPLPGM04) ** DPLPGM04 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** ** STATUS = %SP00 ** **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8MSG2 DS 0CL30MSG02 DS CL30*DPLPGM02 CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*


*EXEC CICS ASSIGN X



*MVC MSG02,=C′>>>ISSUING LINK FOR PROGRAM 03′



* EXEC CICS LINK PROGRAM(′ DPLPGM03′ ) X* TRANSID(′ DP03′ )





*END



TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** MODULE NAME = DPLPGM03 ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** PGM THAT CALLS DPLPGM04 ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** FLOW = DPLPGM01 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM02) ** DPLPGM02 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM03) ** DPLPGM03 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS LINK PGM(DPLPGM04) ** DPLPGM04 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** ** STATUS = %SP00 **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8MSG2 DS 0CL30MSG02 DS CL30*DPLPGM03 CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*


*EXEC CICS ASSIGN X



*MVC MSG02,=C′>>>ISSUING LINK FOR PROGRAM 04′



** EXEC CICS LINK PROGRAM(′ DPLPGM04′ ) X* TRANSID(′ DP04′ )




EXEC CICS RETURNEJECTEND



TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** ** MODULE NAME = DPLPGM04 ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** PGM THAT CALLS ENDS THE DPL CHAIN ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** FLOW = DPLPGM01 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM02) ** DPLPGM02 ** EXEC CICS WRITEQ TS(CSMT) FROM(HERE I AM) ** EXEC CICS LINK PGM(DPLPGM03) ** DPLPGM03 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS LINK PGM(DPLPGM04) ** DPLPGM04 ** EXEC CICS WRITEQ TS(CSMT) ... ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** EXEC CICS RETURN ** ** STATUS = %SP00 ** **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ** ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8*DPLPGM04 CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*


*EXEC CICS ASSIGN X




*END


10.8.1.2 Program DefinitionsFigure 141 on page 177 and Figure 142 on page 177 show the definition for theDPLP2PST program, that is invoked by the starting transaction DP2P. We did notspecify any remote attributes, and we set the dynamic attribute to NO.DPLP2PST will LINK to subsequent programs DPLPGM01, DPLPGM02,DPLPGM03, and DPLPGM04.


� � ------------------ Update Program Definition for SCSPLEX ---------------------- COMMAND ===>

Name DPLP2PST Version 1More: +

Description ===> Peer to Peer DPL StartCreated 12/01/98 17:34 Changed 12/01/98 19:00User Data ===>

Language ===> ASSEMBLER (ASSEMBLER, C, COBOL, LE370, PLI, RPG, N/A)Reload ===> NO New copy of program loaded (NO, YES)Resident ===> NO Resident status (NO, YES)Usage ===> NORMAL Storage release (NORMAL, TRANSIENT)UseLPAcopy ===> NO Program used from LPA (NO, YES)Status ===> ENABLED Program status (ENABLED, DISABLED)Cedf ===> YES CEDF available (YES, NO)Datalocation ===> BELOW Data location (BELOW, ANY)Execkey ===> USER Program key (USER, CICS)Executionset ===> FULLAPI Program run mode (FULLAPI, DPLSUBSET)Remotesystem ===> CICS region for shipped DPL request

Press ENTER to update PROGDEF. Type END or CANCEL to cancel without updating. Enter UP or DOWN to view other screens.

� �Figure 141. Program Definition: DPLP2PST Page 1


Name DPLP2PST Version 1More: -

Reload ===> NO New copy of program loaded (NO, YES)Resident ===> NO Resident status (NO, YES)Usage ===> NORMAL Storage release (NORMAL, TRANSIENT)UseLPAcopy ===> NO Program used from LPA (NO, YES)Status ===> ENABLED Program status (ENABLED, DISABLED)Cedf ===> YES CEDF available (YES, NO)Datalocation ===> BELOW Data location (BELOW, ANY)Execkey ===> USER Program key (USER, CICS)Executionset ===> FULLAPI Program run mode (FULLAPI, DPLSUBSET)Remotesystem ===> CICS region for shipped DPL requestRemotename ===> Program name in remote CICS regionTransid ===> Tranid for remote CICS to attachRsl ===> 0 Resource security value (0-24,PUBLIC,blank)Dynamic ===> NO Dynamic routing (NO, YES)Concurrency ===> N/A Concurrency (N/A, QUASIRENT, THREADSAFE)


� �Figure 142. Program Definition: DPLP2PST Page 2

The next definition we created was for program DPLPGM01 (Figure 143 onpage 178). This program is the first in the sample application. The program isdefined without any remote attributes.



Name DPLPGM01 Version 1More: +

Description ===> Peer to Peer DPL Prog 1Created 12/01/98 17:35 Changed 12/02/98 13:46User Data ===>



� �Figure 143. Program Definition: DPLPGM01 Page 1

The second page of the program definition for DPLPGM01 (Figure 144 onpage 179) has a new attribute, Transid, which is used to identify under whichtransaction definition the program should be routed. Because CICSPlex SMdynamic routing is transaction based, the routing program has to relate theprogram to a four-character transid. If the transid is omitted, CSMI is used asthe default. The Dynamic option is set to Yes so that CICS knows that thisprogram should pass through the routing program.

We defined other programs, DPLPGM02, DPLPGM03, and DPLPGM04 similarly.



Name DPLPGM01 Version 1More: -

Reload ===> NO New copy of program loaded (NO, YES)Resident ===> NO Resident status (NO, YES)Usage ===> NORMAL Storage release (NORMAL, TRANSIENT)UseLPAcopy ===> NO Program used from LPA (NO, YES)Status ===> ENABLED Program status (ENABLED, DISABLED)Cedf ===> YES CEDF available (YES, NO)Datalocation ===> BELOW Data location (BELOW, ANY)Execkey ===> USER Program key (USER, CICS)Executionset ===> FULLAPI Program run mode (FULLAPI, DPLSUBSET)Remotesystem ===> CICS region for shipped DPL requestRemotename ===> Program name in remote CICS regionTransid ===> DP01 Tranid for remote CICS to attachRsl ===> 0 Resource security value (0-24,PUBLIC,blank)Dynamic ===> YES Dynamic routing (NO, YES)Concurrency ===> N/A Concurrency (N/A, QUASIRENT, THREADSAFE)


� �Figure 144. Program Definition: DPLPGM01 Page 2

10.8.1.3 Transaction DefinitionsBecause we specified on the program definitions that we would run theprograms under transaction IDs other than CSMI, we had to define thetransactions DP01, DP02, DP03, and DP04. We defined DP2P in the normal way,with Program pointing to DPLP2PST (Figure 145 on page 180). However,because we were dynamically routing LINKs to other programs, DPLP2P01,2,3and 4, we had to define the transactions slightly differently. The transactionsspecified here act as mirror transactions when performing the dynamicallyrouted LINK request. Hence the definitions had to be functionally the same asthose for the supplied mirror transaction, CSMI. Figure 146 on page 180 showsthe definition for DP01. Note the name of the Program and the Profile. TheProgram name is DFHMIRS, the name of the mirror program, the Profile is thesetting taken from the normal CSMI transaction definition.


� � ------------ Update Transaction Definition for SCSPLEX Page 1 ----------------- COMMAND ===>Name DP2P Version 1Description ===> DP2P Trans for DPL P2PCreated 12/01/98 17:50 Changed 12/02/98 16:10User Data ===>

Program ===> DPLP2PST Name program to process transactionTwasize ===> 0 Transaction work area size (0-32767, blank)Profile ===> DFHCICST Profile definition namePartitionset ===> Application partition set (name, KEEP, OWN)Status ===> ENABLED Transaction status (ENABLED, DISABLED)Taskdataloc ===> BELOW Task storage location (BELOW, ANY)Taskdatakey ===> USER Task storage key (USER, CICS)Storageclear ===> NO Clear task life-time storage (YES, NO)Runaway ===> SYSTEM Max tasktime (SYSTEM, 0-2700000, blank)Shutdown ===> DISABLED Status during shutdown (DISABLED, ENABLED)Isolate ===> YES Isolate user storage (YES, NO)

Press ENTER to update TRANDEF. Press UP or DOWN to view other screens. Type END or CANCEL to cancel without updating.

� �Figure 145. Transaction Definition: DP2P

� � ------------ Update Transaction Definition for SCSPLEX Page 1 ----------------- COMMAND ===>Name DP01 Version 1Description ===> DP01 Trans for DPL P2PCreated 12/02/98 13:31 Changed 12/02/98 15:49User Data ===>

Program ===> DFHMIRS Name program to process transactionTwasize ===> 0 Transaction work area size (0-32767, blank)Profile ===> DFHCICSA Profile definition namePartitionset ===> Application partition set (name, KEEP, OWN)Status ===> ENABLED Transaction status (ENABLED, DISABLED)Taskdataloc ===> BELOW Task storage location (BELOW, ANY)Taskdatakey ===> USER Task storage key (USER, CICS)Storageclear ===> NO Clear task life-time storage (YES, NO)Runaway ===> SYSTEM Max tasktime (SYSTEM, 0-2700000, blank)Shutdown ===> DISABLED Status during shutdown (DISABLED, ENABLED)Isolate ===> YES Isolate user storage (YES, NO)

Press ENTER to update TRANDEF. Press UP or DOWN to view other screens. Type END or CANCEL to cancel without updating.

� �Figure 146. Transaction Definition: DP01

After we created all the transaction definitions (Figure 147 on page 181), we hadto collate them for easy installation into a RESGROUP.


� � 07/12/1998 07:23:12 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===>W1 =TRANDEF===========SCSPLEX==SCSPLEX==07/12/1998=07:23:12====CPSM=========61

CMD Name Ver Created Changed Description --- -------- --- -------------- -------------- ------------------------------

/FOR 1 7/14/98 13:32 7/14/98 13:32CUST 1 12/03/98 14:08 12/03/98 14:08 CUST transactionDEL1 1 12/03/98 13:18 12/03/98 13:18 DEL1 transactionDE1 1 7/14/98 13:32 7/14/98 13:32DE2 1 7/14/98 13:32 7/14/98 13:32DE20 1 7/14/98 13:32 7/14/98 13:32DPDP 1 11/19/98 20:22 11/19/98 20:28 DPDP Tran for DPL/STARTDPLS 1 11/19/98 17:55 11/19/98 20:01 DPLS Tran for DPL/STARTDP01 1 12/01/98 22:04 12/02/98 15:22 DP01 Trans for DPL P2PDP02 1 12/02/98 13:31 12/02/98 15:49 DP02 Trans for DPL P2PDP03 1 12/02/98 13:31 12/02/98 15:49 DP03 Trans for DPL P2PDP04 1 12/02/98 13:31 12/02/98 15:49 DP04 Trans for DPL P2PDP2P 1 12/01/98 17:50 12/02/98 16:10 DP2P Trans for DPL P2PDST1 1 12/02/98 19:20 12/02/98 19:29 Dynamic STARTDX1 1 7/14/98 13:32 7/14/98 13:32DX2 1 7/14/98 13:32 7/14/98 13:32DX20 1 7/14/98 13:32 7/14/98 13:32HR1 1 6/17/98 11:39 6/17/98 11:39� �

Figure 147. Transaction Definitions for DPLP2P Application

We grouped the transaction definitions and program definitions together underRESGROUP DPLP2P (Figure 148).

� � 07/12/1998 07:23:30 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===>W1 =RESGROUP==========SCSPLEX==SCSPLEX==07/12/1998=07:23:30====CPSM=========13

CMD NAME Description Restype ResVer Pattern --- -------- ------------------------------ -------- ------ --------

COMMON NOT SPECIFIC TO ONE APPLICATIOCONNECT Connections to all CICSDCBTSASY Dynamic CBTS Asynchronous defsDCBTSSYN Dynamic CBTS Synchronous defsDEXCI Dynamic EXCI applicationDISTGRP Connections to all distr cicsDPLP2P Peer to Peer DPL test (TRAN)DSTART Dynamic STARTHOTELRES HOTEL RESERVATION RESOURCESINVENTOR INVENTORY TRACKING APPLICATIONSPECIFIC PRODUCTION SPECIFICATION APPLSTOCK STOCK CONTROL APPLICATIONTELLER TELLER SYSTEM APPLICATION� �

Figure 148. Resource Group for DPLP2P Application

10.8.1.4 BAS Resource Description (RESDESC)We defined a BAS resource description (RESDESC; Figure 149 on page 182) toprovide an application scope for later use when checking the operations of thedynamic routing mechanism.


� � ------------- Update Resource Description for SCSPLEX Page 1 ------------------ COMMAND ===>Name DPLP2PDescription ===> DPL Peer to Peer application

Valid Scope ===> YES Add to Topology Scope Set (YES,NO)Scope Name ===> DPLP2P Name to be used as Scope

ResGroup Scope ===> Scope applied to associated ResGroups

Auto Install ===> YES Add Description Resources to Scope (YES,NO)

Press ENTER to update Resource Description. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.� �

Figure 149. Resource Description for DPLP2P Application

The MAP command for BAS provides a good means of checking that all yourdefinitions are correctly linked and ready to be used (Figure 150). Here you canensure that your RESDESC contains a RASGNDEF, that it in turn is connected toa RESGROUP, and that the RESGROUP contains actual resources, in this casethe PROGDEFs and TRANDEFs.

� � ----------------------- MAP of RESDESC DPLP2P --------------- Row 1 of 21 COMMAND ===> Scroll ===> HALFRESDESC RASINDSC RASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- -------- -------- ----------- DPLP2P --- <------> -+- -------- --- DPLP2P -+- PROGDEF -+- DPLPGM01 1

! ! !- DPLPGM02 1! ! !- DPLPGM03 1! ! !- DPLPGM04 1! ! +- DPLP2PST 1! !- TRANDEF -+- DP01 1! ! !- DP02 1! ! !- DP03 1! ! !- DP04 1! ! +- DP2P 1! +- TSMDEF --- DPL2P 1!- DPLP2PPR --- DPLP2P --- PROGDEF -+- DPLPGM01 1! !- DPLPGM02 1! !- DPLPGM03 1! !- DPLPGM04 1! +- DPLP2PST 1+- DPLP2PTR --- DPLP2P --- TRANDEF -+- DP01 1

!- DP02 1!- DP03 1!- DP04 1� �

Figure 150. MAP View of DPLP2P Application

We created resource assignments to control the installation of the PROGDEFsand TRANDEFs. Figure 151 on page 183 shows that the PROGDEFs will beinstalled into the DISTCICS group of regions.


� � -------------- Update Resource Assignment for SCSPLEX Page 1 ------------------ COMMAND ===>

Name DPLP2PPRDescription ===> DPLP2P Programs

Target Scope ===> DISTCICS CICS System or System GroupRelated Scope ===> CICS System or System Group

Resource Group ===> DPLP2P RESGROUP Containing DefinitionsResource Type ===> PROGDEF Resource Definition Type

Usage ===> LOCAL Assignment Type (LOCAL, REMOTE)Mode ===> N/A Usage Qualifier by Resource TypeReferenced Assign ===> Resource Assignment Definition nameOverride ===> NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)

Press ENTER to update Resource Assignment. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.� �

Figure 151. Resource Assignment: DPLP2PPR

TRANDEFs will be installed locally in the DISTCICS group of regions andremotely with the dynamic option in the SCSCTOR group of regions (Figure 152).


Name DPLP2PTRDescription ===> DPLP2P Transactions

Target Scope ===> SCSCTOR CICS System or System GroupRelated Scope ===> DISTCICS CICS System or System Group

Resource Group ===> DPLP2P RESGROUP Containing DefinitionsResource Type ===> TRANDEF Resource Definition Type

Usage ===> REMOTE Assignment Type (LOCAL, REMOTE)Mode ===> DYNAM Usage Qualifier by Resource TypeReferenced Assign ===> Resource Assignment Definition nameOverride ===> NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)

Press ENTER to update Resource Assignment. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.� �

Figure 152. Resource Assignment: DPLP2PTR

10.8.1.5 Checking the Installed DefinitionsWe installed the definitions and checked the resulting installed resourcesthrough the LOCTRAN operations view, using a scope of DPLP2P to restrict thetransids to those installed for the applicaton RESDESC (Figure 153 on page 184).The key attribute is the Routing option showing STAT for static or DYNA fordynamic.


� � 07/12/1998 07:25:37 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =LOCTRAN===========SCSPLEX==DPLP2P===07/12/1998=07:25:37====CPSM=========25 CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Rout --- ID-- System-- Status-- Count Name---- --- -------- ------------ --- ----

DP01 SCSCPAA1 ENABLED 0 DPLPGM01 1 DFHTCL00 NOTPURGEABLE YES STATDP01 SCSCPAA4 ENABLED 0 DPLPGM01 1 DFHTCL00 NOTPURGEABLE YES STATDP01 SCSCPAA7 ENABLED 0 DPLPGM01 1 DFHTCL00 NOTPURGEABLE YES STATDP01 SCSCPTA1 ENABLED 0 DPLPGM01 1 DFHTCL00 NOTPURGEABLE YES DYNADP01 SCSCPTA2 ENABLED 0 DPLPGM01 1 DFHTCL00 NOTPURGEABLE YES DYNADP02 SCSCPAA1 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP02 SCSCPAA4 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP02 SCSCPAA7 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP02 SCSCPTA1 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES DYNADP02 SCSCPTA2 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES DYNADP03 SCSCPAA1 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP03 SCSCPAA4 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP03 SCSCPAA7 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP03 SCSCPTA1 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES DYNADP03 SCSCPTA2 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES DYNADP04 SCSCPAA1 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP04 SCSCPAA4 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STATDP04 SCSCPAA7 ENABLED 0 DFHMIRS 1 DFHTCL00 NOTPURGEABLE YES STAT� �

Figure 153. LOCTRAN View for DPLP2P Application

The PROGRAM view using the same scope DPLP2P (Figure 154) gives an initialindication of the use counts of the programs in the applications. We use theseuse counts to determine whether or not the applications have been balancedcorrectly.

� � 07/12/1998 07:26:07 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =PROGRAM===========SCSPLEX==DPLP2P===07/12/1998=07:26:06====CPSM=========15 CMD Program CICS Enabled Use Current Program Shared CEDF Copy --- Name---- System-- Status-- Count-- Use---- Language- Status Option Require

DPLPGM01 SCSCPAA1 ENABLED 17 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM01 SCSCPAA4 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM01 SCSCPAA7 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM02 SCSCPAA1 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM02 SCSCPAA4 ENABLED 17 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM02 SCSCPAA7 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM03 SCSCPAA1 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM03 SCSCPAA4 ENABLED 17 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM03 SCSCPAA7 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM04 SCSCPAA1 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM04 SCSCPAA4 ENABLED 17 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLPGM04 SCSCPAA7 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLP2PST SCSCPAA1 ENABLED 17 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLP2PST SCSCPAA4 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQUDPLP2PST SCSCPAA7 ENABLED 0 0 ASSEMBLER PRIVATE CEDF NOTREQU

� �Figure 154. PROGRAM View for DPLP2P Application


10.8.1.6 Workload DefinitionsThe next set of definitions that are required for the dynamic routing of programLINKs are the workload management definitions in CICSPlex SM. We created aworkload specification that could be used by the requester and router regions.In this example the requester and router regions were the old AORs as thedynamic program link request would not be made from TORs. The default targetscope in WLMSPEC SCSWS01D was the DISTCICS set of regions (Figure 155).

� � 07/12/1998 07:26:39 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =WLMSPEC===========SCSPLEX==DPLP2P===07/12/1998=07:26:39====CPSM==========2 CMD Name Affinity Affinity Target Cre Match Event Description --- -------- Relation Lifetime Scope--- Aff Key--- Name---- ------------------

SCSCWS1D DISTCICS N/A USERID Distributed RoutinSCSWS01Q HUBCICS N/A USERID Hub Routing Spec� �

Figure 155. WLMSPEC View for DPLP2P Application

For this example we decided to set up some real workload separation in termsof isolating the regions to which the various program LINKs could be directed.This would give us an idea of how WLMDEFs could affect the routing of requests.The essential flow was that the DP01 transaction (remember, WLMDEFs andTRANGRPS have to reference TRANSACTIONS, not PROGRAMS) would beseparated to the SCSCPAA1 region, DP02 would be isolated to SCSCPAA4, DP04would be isolated to SCSCPAA7, and DP03 would be left alone to fall into thedefault transaction group on the WLMSPEC (Figure 156).

� � 07/12/1998 07:27:19 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =WLMDEF============SCSPLEX==DPLP2P===07/12/1998=07:27:19====CPSM=========14 CMD Def Trangrp Luname Userid Process Target Description --- Name---- Name---- ----------------- -------- Type---- Scope--- ------------

CBTSTRAN CBTSTRAN * * * SCSCPAA4 CBTS TransacDP01TRAN DP01TRAN * * * SCSCPAA1 DP01 TransacDP02TRAN DP02TRAN * * * SCSCPAA4 DP02 TransacDP04TRAN DP04TRAN * * * SCSCPAA7 DP04 TransacDP2PTRAN DP2PTRAN * * * PROTSAOR DP2P TransacDST1TRAN DST1TRAN * * * PROTSAOR DST1 TransacSCSDPL01 SCSDPLS * * * SCSCPAA7SCSWDLSR SCSWTLSR * * SCSCGLSR Non-RLS routSCSWDRLS SCSWTRLS * * SCSCGRLS RLS routingSCSWDSC4 SCSWTSC4 * * SCSCGLSRSCSWDSX4 SCSWTSX4 * * SCSCGRLSTEST1 TEST1 * * * SCSCPAA2TEST2 TEST1 * * * SCSCPAA3VSRVTRAN VSRVTRAN * * * PROTSAOR VSRV Transac� �

Figure 156. WLMDEF View for DPLP2P Application

The active workload specification SCSCWS1D, has three available routingregions and three target regions as indicated by the WLMAWORK view inFigure 157 on page 186.


� � 07/12/1998 07:28:10 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =WLMAWORK==========SCSPLEX==SCSPLEX==07/12/1998=07:28:10====CPSM==========2 CMD Name Ownr Rout Targ Affinity Lifetime Target Event Status Cre Alg --- -------- ---- Cnt- Cnt- -------- --------- Scope--- Name---- ------ Aff ---

SCSCWS1D PCA1 3 3 NONE NONE DISTCICS ACTIVE N/A QUESCSWS01Q PCB1 2 6 NONE NONE HUBCICS ACTIVE N/A QUE� �

Figure 157. WLMAWORK View: SCSCWS1D

10.8.1.7 Checking CICS Region SettingsWhen performing dynamic routing for either program LINKs, STARTs or CICSBTS activities, you sometimes discover that the routing is not working asexpected even though all of the definitions are seemingly correct and installedcorrectly. Ensure that you check the DTRPROG and DSRTPGM settings on theCICS regions through the CICSRGND view as shown in Figure 158 for aconventional TOR (hub model) and in Figure 159 on page 187 for a distributedrouter.

� � 07/12/1998 07:28:43 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> <W1 =CICSRGN==CICSRGND=SCSPLEX==SCSPLEX==07/12/1998=07:28:27====CPSM==========1

Start Date... 03/12/199 CICS Status.. ACTIVEStart Time... 19:33:35 Monitor Stat. ONTotl CPU..... 00:20:36.5 Recordng Stat ONTotl Page In. 0 Dump Status.. SYSDUMPTotl Page Out 0 Trace Status. SYSTEMONTotl SIO Cnt. 2909 AUXTrace Stat AUXSTOPTotl Real Stg 19344 RRMS Status.. NOTAPPCurrent Tasks 5 External Sec. NOSECURITYTrn Isol Stat INACTIVE Startup Stat. EMERGENCYRPL Reopens.. 0 Autoinst InfoVTAM ACB..... OPEN Prgm AIn Exit DFHPGADXTimes Max RPL 2 Cat AIn Prgm. CTLGMODIFYMax RPL Postd 1 Dyn Route Pgm EYU9XLOPVTAM SOS Cnt. 0 Dst Route Pgm NONEVTAM Dyn Open 0 Storage Prot. INACTIVEXRF Status... NOTAPPLIC TskRec ConvSt CONVERSEIRC Status... OPEN ShutDown Tran CESDCMD Protect.. NOCMDPROTRentProg Prot NOREENTPRSOS Status... NOTSOS� �

Figure 158. Checking DTRPROG Settings in a Hub Router Region


� � 07/12/1998 07:29:06 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> <W1 =CICSRGN==CICSRGND=SCSPLEX==SCSPLEX==07/12/1998=07:28:27====CPSM==========1

Start Date... 03/12/199 CICS Status.. ACTIVEStart Time... 19:14:47 Monitor Stat. ONTotl CPU..... 00:43:04.2 Recordng Stat OFFTotl Page In. 0 Dump Status.. SYSDUMPTotl Page Out 0 Trace Status. SYSTEMONTotl SIO Cnt. 5029 AUXTrace Stat AUXSTOPTotl Real Stg 21236 RRMS Status.. OPENCurrent Tasks 5 External Sec. NOSECURITYTrn Isol Stat INACTIVE Startup Stat. COLDSTARTRPL Reopens.. 0 Autoinst InfoVTAM ACB..... OPEN Prgm AIn Exit DFHPGADXTimes Max RPL 0 Cat AIn Prgm. CTLGMODIFYMax RPL Postd 0 Dyn Route Pgm EYU9XLOPVTAM SOS Cnt. 0 Dst Route Pgm EYU9XLOPVTAM Dyn Open 0 Storage Prot. INACTIVEXRF Status... NOTAPPLIC TskRec ConvSt CONVERSEIRC Status... OPEN ShutDown Tran CESDCMD Protect.. NOCMDPROTRentProg Prot NOREENTPRSOS Status... NOTSOS� �

Figure 159. Checking DSRTPGM and DTRPROG Settings in a Distributed Router Region

10.8.1.8 CICSPlex SM Screen DefinitionWe set up a CICSPlex SM screen definition to show the PROGRAM views for theDPLP2P application. We locked one window to ensure that when we pressedEnter, one window′s data would not changed. This enabled us to easily seeincreases in use counts (Figure 160).

� � 07/12/1998 07:32:40 ----------- INFORMATION DISPLAY ------ SCREEN DEF REPLACED COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >L1 =PROGRAM===========SCSPLEX==DPLP2P >W2 -PROGRAM-----------SCSPLEX--DPLP2P-- CMD Program CICS Enabled Use ! CMD Program CICS Enabled Use --- Name---- System-- Status-- Count-- ! --- Name---- System-- Status-- Count--

DPLPGM01 SCSCPAA1 ENABLED 17 ! DPLPGM01 SCSCPAA1 ENABLED 17DPLPGM01 SCSCPAA4 ENABLED 0 ! DPLPGM01 SCSCPAA4 ENABLED 0DPLPGM01 SCSCPAA7 ENABLED 0 ! DPLPGM01 SCSCPAA7 ENABLED 0DPLPGM02 SCSCPAA1 ENABLED 0 ! DPLPGM02 SCSCPAA1 ENABLED 0DPLPGM02 SCSCPAA4 ENABLED 17 ! DPLPGM02 SCSCPAA4 ENABLED 17DPLPGM02 SCSCPAA7 ENABLED 0 ! DPLPGM02 SCSCPAA7 ENABLED 0DPLPGM03 SCSCPAA1 ENABLED 0 ! DPLPGM03 SCSCPAA1 ENABLED 0DPLPGM03 SCSCPAA4 ENABLED 17 ! DPLPGM03 SCSCPAA4 ENABLED 17DPLPGM03 SCSCPAA7 ENABLED 0 ! DPLPGM03 SCSCPAA7 ENABLED 0DPLPGM04 SCSCPAA1 ENABLED 0 ! DPLPGM04 SCSCPAA1 ENABLED 0DPLPGM04 SCSCPAA4 ENABLED 0 ! DPLPGM04 SCSCPAA4 ENABLED 0DPLPGM04 SCSCPAA7 ENABLED 17 ! DPLPGM04 SCSCPAA7 ENABLED 17DPLP2PST SCSCPAA1 ENABLED 17 ! DPLP2PST SCSCPAA1 ENABLED 17DPLP2PST SCSCPAA4 ENABLED 0 ! DPLP2PST SCSCPAA4 ENABLED 0DPLP2PST SCSCPAA7 ENABLED 0 ! DPLP2PST SCSCPAA7 ENABLED 0� �

Figure 160. Showing the Use Counts of the DPLP2P Application


10.8.1.9 Testing the ApplicationFrom a 3270 display that was attached through VTAM generic resources to theTOR, we ran the test transaction DP2P. This transaction would be dynamicallyrouted to an AOR where it would get dynamic routing advice for the LINKrequest it would issue (Figure 161).

� �dp2p� �

Figure 161. Testing the DPLP2P Application

After pressing Enter we could see that the use counts have increased inaccordance with the WLMDEFs that we installed (Figure 162).

� � 07/12/1998 07:34:25 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >L1 =PROGRAM===========SCSPLEX==DPLP2P >W2 -PROGRAM-----------SCSPLEX--DPLP2P-- CMD Program CICS Enabled Use ! CMD Program CICS Enabled Use --- Name---- System-- Status-- Count-- ! --- Name---- System-- Status-- Count--

DPLPGM01 SCSCPAA1 ENABLED 17 ! DPLPGM01 SCSCPAA1 ENABLED 18DPLPGM01 SCSCPAA4 ENABLED 0 ! DPLPGM01 SCSCPAA4 ENABLED 0DPLPGM01 SCSCPAA7 ENABLED 0 ! DPLPGM01 SCSCPAA7 ENABLED 0DPLPGM02 SCSCPAA1 ENABLED 0 ! DPLPGM02 SCSCPAA1 ENABLED 0DPLPGM02 SCSCPAA4 ENABLED 17 ! DPLPGM02 SCSCPAA4 ENABLED 18DPLPGM02 SCSCPAA7 ENABLED 0 ! DPLPGM02 SCSCPAA7 ENABLED 0DPLPGM03 SCSCPAA1 ENABLED 0 ! DPLPGM03 SCSCPAA1 ENABLED 0DPLPGM03 SCSCPAA4 ENABLED 17 ! DPLPGM03 SCSCPAA4 ENABLED 18DPLPGM03 SCSCPAA7 ENABLED 0 ! DPLPGM03 SCSCPAA7 ENABLED 0DPLPGM04 SCSCPAA1 ENABLED 0 ! DPLPGM04 SCSCPAA1 ENABLED 0DPLPGM04 SCSCPAA4 ENABLED 0 ! DPLPGM04 SCSCPAA4 ENABLED 0DPLPGM04 SCSCPAA7 ENABLED 17 ! DPLPGM04 SCSCPAA7 ENABLED 18DPLP2PST SCSCPAA1 ENABLED 17 ! DPLP2PST SCSCPAA1 ENABLED 18DPLP2PST SCSCPAA4 ENABLED 0 ! DPLP2PST SCSCPAA4 ENABLED 0DPLP2PST SCSCPAA7 ENABLED 0 ! DPLP2PST SCSCPAA7 ENABLED 0� �

Figure 162. Updated Use Counts

The application writes some debug information to a shared TS queue. Welooked at this output to verify that the program executed correctly (Figure 163).

� �cebr dplpeertopeertes� �

Figure 163. Using CEBR to Review the DPLP2P Application

The messages written to the shared TS queue show that the application initiallywas routed from the TOR to SCSCPAA1, from there the first link to programDPLPGM01 was routed to SCSCPAA1, and the rest of the applications followedthe WLMDEFs we installed against the workload for some transaction separation(Figure 164 on page 189).


� � CEBR TSQ DPLPEERTOPEERTES SYSID PAA1 REC 1 OF 13 COL 1 OF 50ENTER COMMAND ===>

************************** TOP OF QUEUE ******************************* 00001 DPL PEER-PEER PROG ST EXECUTED ON APPL => SCSCPAA1 00002 ...ISSUING START FOR TRAN DP01 00003 ...START ISSUED FOR TRAN DP01 00004 DPL PEER-PEER PROG 01 EXECUTED ON APPL =>.SCSCPAA1 00005 >>>ISSUING LINK FOR PROGRAM 02 00006 DPL PEER-PEER PROG 02 EXECUTED ON APPL =>.SCSCPAA4 00007 >>>ISSUING LINK FOR PROGRAM 03 00008 DPL PEER-PEER PROG 03 EXECUTED ON APPL =>.SCSCPAA4 00009 >>>ISSUING LINK FOR PROGRAM 04 00010 DPL PEER-PEER PROG 04 EXECUTED ON APPL =>.SCSCPAA7 00011 <<<RETURNING FROM LINK PROG 04 00012 <<<RETURNING FROM LINK PROG 03 00013 <<<RETURNING FROM LINK PROG 02

************************* BOTTOM OF QUEUE *****************************

PF1 : HELP PF2 : SWITCH HEX/CHAR PF3 : TERMINATE BROWSE PF4 : VIEW TOP PF5 : VIEW BOTTOM PF6 : REPEAT LAST FIND PF7 : SCROLL BACK HALF PF8 : SCROLL FORWARD HALF PF9 : UNDEFINED PF10: SCROLL BACK FULL PF11: SCROLL FORWARD FULL PF12: UNDEFINED� �

Figure 164. DPLP2P Application Log

10.8.2 Routing Terminal-Initiated START RequestsIn this section we cover the setting up and testing of a simple application thatwill use dynamic routing for terminal-initiated START requests. The exampleshows which resources you have to define, change, and reinstall to ensure that aSTART request can pass through the dynamic routing program. For thepurposes of this example we assume that:

• CICSPlex SM is used to provide routing information.

• CICSPlex SM BAS is being used for resource definitions.

• The configuration shown in Figure 165 on page 190 is in place.


Figure 165. Dynamic Routing of Terminal-Init iated START Requests: CICS Configuration

10.8.2.1 The ITSO Test Application: DSTART01Figure 166 on page 191 shows the program that we used to issue aterminal-initiated (TERMID option) START request. The STARTed transaction isthe same that initiates the START.


TITLE ′ DYNAMIC DPL/START DEMO PROGRAM′****************************************************************** ** MODULE NAME = DSTART01 ** ** DESCRIPTIVE NAME = SAMPLE PROGRAM FOR CICS DPL/START ** SAMPLE DYNAMIC ROUTED APPLICATION THAT ** ENABLES VERIFICATION OF WLM BALANCING ** ** %COPYRIGHT IBM CONFIDENTIAL ** ** STATUS = %SP00 ** **---------------------------------------------------------------** ** CHANGE ACTIVITY : ** $SEG(INVOICE1),COMP(SAMPLES),PROD(%PRODUCT): ** ** PN= REASON REL YYMMDD TBALL : REMARKS ** $P0= . %B0 981119 : CREATED. ** ******************************************************************* PROGRAM MAINTENANCE HISTORY *DFHEISTG DSECT EXEC INTERFACE DYNAMIC STORAGE.MSG DS 0CL50MSG01 DS CL42APPL DS CL8*DSTART01 CSECT** QUERY THE APPLICATION ID OF THE ROUTED TO SYSTEM*

MVC APPL,=8C′ X′MVC MSG01,=C′ DYNAMIC START TRAN EXECUTED ON APPLID => ′

*EXEC CICS ASSIGN X


EXEC CICS SEND TEXT FROM(MSG) LENGTH(50)EXEC CICS DELAY FOR SECONDS(5)EXEC CICS START TRANSID(′ DST1′ ) TERMID(EIBTRMID) X

INTERVAL(0)EXEC CICS RETURNEJECT

*END

Figure 166. Dynamic START Request Sample Application

10.8.2.2 Transaction DefinitionsThe DST1 transaction (Figure 167 on page 192) was defined as DYNAMIC=YESand hence ran through the DTR program as a normal terminal-initiatedtransaction (Figure 168 on page 192). It ran a program called DSTART01 which,issued an EXEC CICS START TRANSID(′DST1′) TERMID(EIBTRMID) INTERVAL(0).This technique is widely used to start the application again on the same user ′sterminal. If this is the case, it is recommended to replace these commands byEXEC CICS RETURN IMMEDIATE (see 10.8.5.2, “Using RETURN IMMEDIATE” onpage 223).


� � ------------ Update Transaction Definition for SCSPLEX Page 1 ----------------- COMMAND ===>Name DST1 Version 1Description ===> Dynamic STARTCreated 12/02/98 19:20 Changed 12/02/98 19:29User Data ===>

Program ===> DSTART01 Name program to process transactionTwasize ===> 0 Transaction work area size (0-32767, blank)Profile ===> DFHCICST Profile definition namePartitionset ===> Application partition set (name, KEEP, OWN)Status ===> ENABLED Transaction status (ENABLED, DISABLED)Taskdataloc ===> BELOW Task storage location (BELOW, ANY)Taskdatakey ===> USER Task storage key (USER, CICS)Storageclear ===> NO Clear task life-time storage (YES, NO)Runaway ===> SYSTEM Max tasktime (SYSTEM, 0-2700000, blank)Shutdown ===> DISABLED Status during shutdown (DISABLED, ENABLED)Isolate ===> YES Isolate user storage (YES, NO)

Press ENTER to update TRANDEF. Press UP or DOWN to view other screens.. . . . . . . . . . . . . . . . . . . . . . . . . . .Display Filter View Print Options Help� �

Figure 167. Transaction Definition: DST1, Page 1

As with all dynamic routing, there is no need to specify the remote attributessuch as Remotename or Remote Sysid (Figure 168). Indeed, if you do specifythem, they take priority over the routable option.

� � ------------ Update Transaction Definition for SCSPLEX Page 2 ----------------- COMMAND ===>Name DST1 Version 1

Dynamic ===> YES Dynamic route to remote region (NO, YES)Remotename ===> Transaction name in remote systemRemote Sysid ===> SYSIDENT for Remote SystemTrprof ===> DFHCICSS Transaction routing profile nameLocalq ===> N/A Queueing on local system (NO, YES, N/A)Priority ===> 1 Transaction priority (0-255, blank)Tranclass ===> DFHTCL00 Transaction class (DFHTCL00, name)Alias ===> Alias name for transactionTaskreq ===> Transactions initiationXtranid ===> Alternate name for initiating transactionRessec ===> NO Resource security checking (NO, YES)Cmdsec ===> NO Sec checking for sys prog cmds (NO, YES)Action ===> BACKOUT Recovery action (BACKOUT, COMMIT)Wait ===> YES In-doubt unit of work wait (YES, NO)Waittime ===> 0 , 0 , 0 In-doubt unit of work wait time (blank,

DD (0-93), HH (0-23), MM (0-59))

Press ENTER to update TRANDEF.. . . . . . . . . . . . . . . . . . . . . . . . . . .Display Filter View Print Options Help� �


To ensure that the transaction could be routed again when it arrived at the AOR,we defined Routable=YES was defined on the definition (Figure 169 onpage 193).


� � ------------ Update Transaction Definition for SCSPLEX Page 4 ----------------- COMMAND ===>Name DST1 Version 1


Tclass ===> NO Task class (NO, 1-10, blank)PrimedSize ===> 0 Primed storage allocation size (0-65520,blank)Extsec ===> NO External security manager used (NO, YES, N/A)Transec ===> 1 Transaction security value (1-64, blank)Rsl ===> 0 Resource security value (0-24, PUBLIC, blank)Routable ===> YES Routable (NO, YES)

Press ENTER to update TRANDEF. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.

. . . . . . . . . . . . . . . . . . . . . . . . . . .Display Filter View Print Options Help� �


TRANDEF view now shows the DST1 transaction among others (Figure 170).

� � 07/12/1998 07:56:50 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===>W1 =TRANDEF===========SCSPLEX==SCSPLEX==07/12/1998=07:56:50====CPSM=========61

CMD Name Ver Created Changed Description --- -------- --- -------------- -------------- ------------------------------

/FOR 1 7/14/98 13:32 7/14/98 13:32CUST 1 12/03/98 14:08 12/03/98 14:08 CUST transactionDEL1 1 12/03/98 13:18 12/03/98 13:18 DEL1 transactionDE1 1 7/14/98 13:32 7/14/98 13:32DE2 1 7/14/98 13:32 7/14/98 13:32DE20 1 7/14/98 13:32 7/14/98 13:32DPDP 1 11/19/98 20:22 11/19/98 20:28 DPDP Tran for DPL/STARTDPLS 1 11/19/98 17:55 11/19/98 20:01 DPLS Tran for DPL/STARTDP01 1 12/01/98 22:04 12/02/98 15:22 DP01 Trans for DPL P2PDP02 1 12/02/98 13:31 12/02/98 15:49 DP02 Trans for DPL P2PDP03 1 12/02/98 13:31 12/02/98 15:49 DP03 Trans for DPL P2PDP04 1 12/02/98 13:31 12/02/98 15:49 DP04 Trans for DPL P2PDP2P 1 12/01/98 17:50 12/02/98 16:10 DP2P Trans for DPL P2PDST1 1 12/02/98 19:20 12/02/98 19:29 Dynamic STARTDX1 1 7/14/98 13:32 7/14/98 13:32DX2 1 7/14/98 13:32 7/14/98 13:32


Figure 170. TRANDEF View with DST1 Transaction

10.8.2.3 Program DefinitionNext we defined the program (Figure 171 on page 194). An alternative to thiswould have been to use autoinstall for programs to dynamically install aprogram definition when the program was first referenced. The programdefinition showed no specific attributes for the dynamic start application.



Name DSTART01 Version 1More: +

Description ===> Dynamic START programCreated 12/02/98 19:13 Changed 12/02/98 19:13User Data ===>


Press ENTER to update PROGDEF. Type END or CANCEL to cancel without updating.. . . . . . . . . . . . . . . . . . . . . . . . . . .Display Filter View Print Options Help� �

Figure 171. Program Definition: DSTART01

10.8.2.4 BAS Resource AssignmentTo correctly install the program in the environment, we had to create a resourceassignment (RASGNDEF). With a RASGNDEF, you can easily assign CICSresources to regions and specify the required local and remote characteristics(Figure 172 on page 195). We assigned the program definition to the CICSgroup PROTSAOR (which consists of all CISC TS AORs) that will be our TargetScope.



Name DSTARTPRDescription ===> DSTART Programs

Target Scope ===> PROTSAOR CICS System or System GroupRelated Scope ===> CICS System or System Group

Resource Group ===> DSTART RESGROUP Containing DefinitionsResource Type ===> PROGDEF Resource Definition Type

Usage ===> LOCAL Assignment Type (LOCAL, REMOTE)Mode ===> N/A Usage Qualifier by Resource TypeReferenced Assign ===> Resource Assignment Definition nameOverride ===> NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)

Press ENTER to update Resource Assignment. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.


Figure 172. Resource Assignment: DSTARTPR

We have also built a resource assignment for transaction DST1 that belongs to aDSTART resource group (Figure 173). Here we assigned the REMOTE definitionsto the SCSCTOR group (Target Scope), ensuring that they were DYNAMIC, andthe LOCAL resources to the PROTSAOR group (Related Scope).


Name DSTARTTRDescription ===> DSTART Transactions

Target Scope ===> SCSCTOR CICS System or System GroupRelated Scope ===> PROTSAOR CICS System or System Group

Resource Group ===> DSTART RESGROUP Containing DefinitionsResource Type ===> TRANDEF Resource Definition Type

Usage ===> REMOTE Assignment Type (LOCAL, REMOTE)Mode ===> DYNAM Usage Qualifier by Resource TypeReferenced Assign ===> Resource Assignment Definition nameOverride ===> NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)

Press ENTER to update Resource Assignment. Enter UP or DOWN to view other screens. Enter END or CANCEL to cancel without updating.


Figure 173. Resource Assignment: DSTARTTR


10.8.2.5 BAS Resource DescriptionWe created a BAS resource description DSTART which also specified thatDSTART could be used as an application scope in the operations views(Figure 174).

� � 07/12/1998 08:32:23 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===>W1 =RESDESC===========SCSPLEX==SCSPLEX==07/12/1998=08:32:18====CPSM=========11

CMD Name Scope Scope Description --- -------- ----- Name---- ------------------------------

COMMON YES COMMON NOT SPECIFIC TO ONE APPLICATIOCONNECT NO Connections for all regionsDCBTS YES DCBTS Dynamic CBTS applicationDEXCI YES DEXCI Dynamic EXCI applicationDPLP2P YES DPLP2P DPL Peer to Peer applicationDSTART YES DSTART Dynamic START applicationHOTELRES YES HOTELRES HOTEL RESERVATION APPLICATIONINVENTOR YES INVENTOR INVENTORY TRACKING APPLICATIONSPECIFIC YES SPECIFIC PRODUCTION SPECIFICATION APPLSTOCK YES STOCK STOCK CONTROL APPLICATIONTELLER YES TELLER TELLER SYSTEM APPLICATION� �

Figure 174. Resource Description: DSTART

The final stage of the implementation was to ensure that all the definitions werepresent and ready to be installed. The MAP function of CICSPlex SM when usingBAS (or other functions like RTA, MON and WLM) is extremely useful in ensuringthat all the correct linkages are in place before doing the install. Figure 175shows a MAP view of the DSTART resource description.

� � ----------------------- MAP of RESDESC DSTART --------------- Row 1 of 4 COMMAND ===> Scroll ===> HALFRESDESC RASINDSC RASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- -------- -------- ----------- DSTART --- <------> -+- -------- --- DSTART -+- PROGDEF --- DSTART01 1

! +- TRANDEF --- DST1 1!- DSTARTPR --- DSTART --- PROGDEF --- DSTART01 1+- DSTARTTR --- DSTART --- TRANDEF --- DST1 1

--------------------------------- End Of Map ----------------------------------� �Figure 175. MAP View of DSTART Resource Description

10.8.2.6 Workload DefinitionsWe created a WLMDEF to ensure that all transactions in TRANGRP DST1TRANwould be routed to a set of AORs. Without the WLMDEF, transaction DST1 wouldhave matched the default TRANGRP specified on the WLMSPEC and would havebeen routed to an AOR in the default AORSCOPE (HUBCICS). Typically youwould use a WLMSPEC that has been inherited from an old CICSPlex SMenvironment, and the default AORSCOPE could specify regions that have not yetbeen migrated to CICS TS 1.3. In that case, this WLMDEF method would enableyou to separate your work out to CICS TS regions until all regions specified inthe default AORSCOPE have been migrated to CICS TS 1.3. Then you wouldremove this WLMDEF (Figure 176 on page 197).


� � 07/12/1998 08:33:31 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >W1 =WLMDEF============SCSPLEX==SCSPLEX==07/12/1998=08:33:31====CPSM=========14 CMD Def Trangrp Luname Userid Process Target Description --- Name---- Name---- ----------------- -------- Type---- Scope--- ------------

CBTSTRAN CBTSTRAN * * * SCSCPAA4 CBTS TransacDP01TRAN DP01TRAN * * * SCSCPAA1 DP01 TransacDP02TRAN DP02TRAN * * * SCSCPAA4 DP02 TransacDP04TRAN DP04TRAN * * * SCSCPAA7 DP04 TransacDP2PTRAN DP2PTRAN * * * PROTSAOR DP2P TransacDST1TRAN DST1TRAN * * * PROTSAOR DST1 TransacSCSDPL01 SCSDPLS * * * SCSCPAA7SCSWDLSR SCSWTLSR * * SCSCGLSR Non-RLS routSCSWDRLS SCSWTRLS * * SCSCGRLS RLS routingSCSWDSC4 SCSWTSC4 * * SCSCGLSRSCSWDSX4 SCSWTSX4 * * SCSCGRLSTEST1 TEST1 * * * SCSCPAA2TEST2 TEST1 * * * SCSCPAA3VSRVTRAN VSRVTRAN * * * PROTSAOR VSRV Transac� �

Figure 176. WLMDEF View Including DSTART Application

Figure 177 shows the WLMSPEC we defined for our hub environment. We choseto create two WLMSPECs in our configuration, one for the hub environment, andone for the distributed environment.

� � -------------------- Update WLM Specification for SCSPLEX --------------------- COMMAND ===>

WLM Spec Name SCSWS01QDescription ===> Hub Routing Spec

Affinity Relation ===> Default Affinity Relation(USERID, LUNAME, GLOBAL, BAPPL)

Affinity Lifetime ===> Default Affinity Lifetime(SIGNON, LOGON, SYSTEM, PERMANENT, PCONV, DELIMIT,ACTIVITY, PROCESS)

Match Key ===> USERID Default Primary search criteria(USERID, LUNAME)

Create Affinity ===> N/A Create auto affinity (YES, NO, N/A)Target Scope ===> HUBCICS Default CICS System, Group or Generic

Event Name ===> RTADEF, STATDEF or Generic

Abend Health ===> 0 Target ABEND Health Factor (0 - 99)Abend Load ===> 0 Target ABEND Load Factor (0 - 99)Algorithm Type ===> QUEUE Algorithm Type (GOAL, QUEUE)

Press ENTER to update the WLM Specification. Type END or CANCEL to cancel without updating.� �

Figure 177. WLM Specification: SCSWS01Q


10.8.2.7 Checking the Installed DefinitionsTo check the correct execution of our routing envinronment and the definitionswe set up, we created a CICSPlex SM Screen definition that showed theLOCTRAN definitions for the DSTART application, notice how DSTART is namedas the scope for the views. We also chose to display the Program details for theDSTART application (Figure 178). We also created a second window on thePROGRAM view so that we could see the change in program use count when theapplication worked.

� � 07/12/1998 08:38:10 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 2 ALT WIN ===> >W1 -LOCTRAN-----------SCSPLEX--DSTART---07/12/1998-08:38:09----CPSM----------5 CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Rout --- ID-- System-- Status-- Count Name---- --- -------- ------------ --- ----

DST1 SCSCPAA1 ENABLED 5 DSTART01 1 DFHTCL00 NOTPURGEABLE YES STATDST1 SCSCPAA4 ENABLED 0 DSTART01 1 DFHTCL00 NOTPURGEABLE YES STATDST1 SCSCPAA7 ENABLED 0 DSTART01 1 DFHTCL00 NOTPURGEABLE YES STATDST1 SCSCPTA1 ENABLED 5 DSTART01 1 DFHTCL00 NOTPURGEABLE YES DYNADST1 SCSCPTA2 ENABLED 0 DSTART01 1 DFHTCL00 NOTPURGEABLE YES DYNA

>L2 =PROGRAM===========SCSPLEX==DSTART >W3 -PROGRAM-----------SCSPLEX--DSTART-- CMD Program CICS Enabled Use ! CMD Program CICS Enabled Use --- Name---- System-- Status-- Count-- ! --- Name---- System-- Status-- Count--

DSTART01 SCSCPAA1 ENABLED 13 ! DSTART01 SCSCPAA1 ENABLED 13DSTART01 SCSCPAA4 ENABLED 7103 ! DSTART01 SCSCPAA4 ENABLED 7103DSTART01 SCSCPAA7 ENABLED 7039 ! DSTART01 SCSCPAA7 ENABLED 7039

!!!!!� �

Figure 178. Creating a SCREEN for the DSTART Application

10.8.2.8 Testing the ApplicationFrom a 3270 screen we logged on to the TOR and ran the sample transaction,DST1 (Figure 179). This transaction was dynamically routed from the TOR to anAOR. The application issues a message indicating in which AOR the transactionran (Figure 180).

� �DST1� �

Figure 179. Testing the DSTART Application

� � DYNAMIC START TRAN EXECUTED ON APPLID => SCSCPAA1� �

Figure 180. DSTART Application Log

On the CICSPlex SM Screen that we had earlier created we could see the usecount values increasing as the application executed (Figure 181 on page 199).


� � 07/12/1998 08:40:44 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 1 ALT WIN ===> >L2 -PROGRAM-----------SCSPLEX--DSTART---07/12/1998-08:35:26----CPSM----------3 CMD Program CICS Enabled Use Current Program Shared CEDF Copy --- Name---- System-- Status-- Count-- Use---- Language- Status Option Require

DSTART01 SCSCPAA1 ENABLED 13 0 ASSEMBLER PRIVATE CEDF NOTREQUDSTART01 SCSCPAA4 ENABLED 7103 0 ASSEMBLER PRIVATE CEDF NOTREQUDSTART01 SCSCPAA7 ENABLED 7039 0 ASSEMBLER PRIVATE CEDF NOTREQU



!!

� �Figure 181. Use Count Increase in SCSCPAA1 for DSTART Application

Initially the use count increase does not prove that dynamic routing is actuallyworking, so we decided to enhance the Screen information with the WLMAWAORview (hyperlink from WLMAWORK AOR column for the WLMSPEC we were using(see Figure 182)..

� � 07/12/1998 08:40:58 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 4 ALT WIN ===> >L2 -PROGRAM-----------SCSPLEX--DSTART---07/12/1998-08:35:26----CPSM----------3 CMD Program CICS Enabled Use Current Program Shared CEDF Copy --- Name---- System-- Status-- Count-- Use---- Language- Status Option Require

DSTART01 SCSCPAA1 ENABLED 13 0 ASSEMBLER PRIVATE CEDF NOTREQUDSTART01 SCSCPAA4 ENABLED 7103 0 ASSEMBLER PRIVATE CEDF NOTREQUDSTART01 SCSCPAA7 ENABLED 7039 0 ASSEMBLER PRIVATE CEDF NOTREQU

>L1 -PROGRAM-----------SCSPLEX--DSTART >W3 -PROGRAM-----------SCSPLEX--DSTART-- CMD Program CICS Enabled Use ! CMD Program CICS Enabled Use --- Name---- System-- Status-- Count-- ! --- Name---- System-- Status-- Count--


!!

W4 =WLMAWAOR==========SCSPLEX==SCSPLEX==07/12/1998=08:40:58====CPSM==========6 CMD Workload Ownr Target Status Connection --- -------- ---- -------- --------- Lost------

SCSWS01Q PCB1 SCSCPAA1 ACTIVESCSWS01Q PCB1 SCSCPAA2 ACTIVESCSWS01Q PCB1 SCSCPAA3 ACTIVESCSWS01Q PCB1 SCSCPAA4 ACTIVE� �

Figure 182. CICSPlex SM Screen with WLMAOR View

From the new Screen we could see that with such a lightly loaded system, thechances of the dynamic router sending the transaction to an AOR other thanSCSCPAA1 would be remote. So we decided to alter the rules slightly, byquiescing the SCSCPAA1 region (Figure 183 on page 200). (Alternatively, wecould have lowered the MAXTASK setting in SCSCPAA1).




>W2 -PROGRAM-----------SCSPLEX--DSTART >W3 -PROGRAM-----------SCSPLEX--DSTART-- CMD Program CICS Enabled Use ! CMD Program CICS Enabled Use --- Name---- System-- Status-- Count-- ! --- Name---- System-- Status-- Count--


>W4 =WLMAWAOR==========SCSPLEX==SCSPLE ! CMD Workload Ownr Target Status C ! --- -------- ---- -------- --------- L ! set SCSWS01Q PCB1 SCSCPAA1 quiesce !

SCSWS01Q PCB1 SCSCPAA2 ACTIVE !SCSWS01Q PCB1 SCSCPAA3 ACTIVE !SCSWS01Q PCB1 SCSCPAA4 ACTIVE !� �

Figure 183. Quiescing the SCSCPAA1 Region

With the region quiesced for workload management (the region is still active), wesaw that the STARTed application DST1 ran in SCSCPAA7, hence proving thatthe routing mechanism worked (Figure 184).

� � DYNAMIC START TRAN EXECUTED ON APPLID => SCSCPAA7� �

Figure 184. Transaction DST1 Executing in SCSCPAA7 Region

Returning to our saved Screen definition we could see that the use counts for theDSTART01 program had increased in SCSCPAA7 (Figure 185 on page 201).






>W4 -WLMAWAOR----------SCSPLEX--SCSPLE ! CMD Workload Ownr Target Status C ! --- -------- ---- -------- --------- L !

SCSWS01Q PCB1 SCSCPAA1 QUIESCED !SCSWS01Q PCB1 SCSCPAA2 ACTIVE !SCSWS01Q PCB1 SCSCPAA3 ACTIVE !SCSWS01Q PCB1 SCSCPAA4 ACTIVE !� �

Figure 185. Use Count Increase in SCSCPAA7 for DSTART Application

10.8.3 Routing CICS BTS Processes and ActivitiesThe dynamic routing of transactions in a CICS BTS process is identical to routingnon-terminal STARTed transactions (TERMID option not specified). Therefore,although we cover only the dynamic routing of CICS BTS transactions in thissection, the information documented here can be equally applied to nonterminalSTARTed transactions.

You can alter your CICS BTS processes and activities to be dynamically routedamong several target regions that form a BTS set. For a discussion of setting upa BTS set, refer to 10.7.2.7, “BTS Sets” on page 165.

Ensure that all participating regions of your BTS set are: interconnected, in thesame CICSplex, and running on the same MVS Parallel Sysplex. Also ensurethat your CICS BTS repository data sets are accessible by all participatingregions, in RLS mode. Failure to do this causes the process to abend with anASH2 transaction abend code.

10.8.3.1 Setting up a BTS Set in CICSPlex SMTo demonstrate how to set up a BTS set in the ITSO environment, we used thesample CICS BTS process, described in Chapter 9, “CICS Business TransactionServices” on page 123, and created the CICSPlex SM definitions necessary todynamically route transactions in the process. Figure 186 on page 202 showsthe BTS set model.

Using the newly created CICSPlex SM definitions as a base, we then set up andran a test scenario where one transaction belonging to the sample process wasrouted to another target region in the BTS set.


Figure 186. CICS BTS Sample Process: BTS Set Configuration

10.8.3.2 Recommended Approach to Creating a BTS SetIn this section we document the steps we took to create the CICSPlex SMdefinitions needed to run the sample CICS BTS process in a BTS set.

First, we created FILEDEFs for the process repository data set PTYPSALE, andthe application data set VSAMFIL1. As shown in Figure 186, we defined both therepository data set and the application data set in RLS mode.

We also defined a PROCDEF called ORDER to define the process (seeFigure 187).

� �----------- Browse CICS BTS ProcessType Definition for SCSPLEX ----------COMMAND ===>Name ORDER Version 1 Description proc type def for sales order Created 12/03/98 18:10 Changed 12/03/98 18:10 User Data

Status ENABLED Enabled|Disabled File PTYPSALE File name Auditlog CBTSLOG Name of Audit log Auditlevel FULL Off|Process|Activity|Full

� �Figure 187. CICS BTS Sample: PROCDEF ORDER


We associated the PROCDEF and the two FILEDEFs with RESGROUPsDCBTSPRC and DCBTSFL, respectively (Figure 188 on page 203 and Figure 189on page 203).

� � 04DEC1998 16:09:27 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> CSR CURR WIN ===> 1 ALT WIN ===>W1 =RESINGRP==========SCSPLEX==ALLCICS==04DEC1998==16:09:27====CPSM==========2

CMD Resource Resource Ver Restype --- Group--- Name---- --- --------

DCBTSFL PTYPSALE 1 FILEDEFDCBTSFL VSAMFIL1 1 FILEDEF� �

Figure 188. CICS BTS Sample: RESGROUP DCBTSFL



DCBTSPRC ORDER 1 PROCDEF� �Figure 189. CICS BTS Sample: RESGROUP DCBTSPRC

We then connected the two RESGROUPs, DCBTSPRC and DCBTSFL, to aRASGNDEF—DCBTSPRC and DCBTSFL, repectively (Figure 190 and Figure 191on page 204). Both RASGNDEFs were given a Target Scope of PROTSAOR,which would install the definitions into all target regions in the BTS set, as isshown in Figure 201 on page 208.

� � -------------- Browse Resource Assignment for SCSPLEX Page 1 ------------------ COMMAND ===>

Name DCBTSPRCDescription DCBTS PROCDEF

Target Scope PROTSAOR CICS System or System GroupRelated Scope CICS System or System Group

Resource Group DCBTSPRC RESGROUP Containing DefinitionsResource Type PROCDEF Resource Definition Type

Usage LOCAL Assignment Type (LOCAL, REMOTE)Mode N/A Usage Qualifier by Resource TypeReferenced Assign Resource Assignment Definition nameOverride NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)� �Figure 190. CICS BTS Sample: RASGNDEF DCBTSPRC



Name DCBTSFLDescription DCBTS Files


Resource Group DCBTSFL RESGROUP Containing DefinitionsResource Type Resource Definition Type


NONE)� �Figure 191. CICS BTS Sample: RASGNDEF DCBTSFL

Only those transactions running asynchronously in a CICS BTS process can beconsidered eligible for routing. Therefore, we separated those transactionsassociated with synchronous activities from those associated with asynchronousactivities:

• Synchronous transactions

− MENU

− RED1

− SALE

− STOC

• Asynchronous transactions

− CUST

− DEL1

− INV1

− REM1

Having identified these transactions, we created TRANDEFs for each of them andassociated the synchronous transactions with RESGROUP DCBTSSYN(Figure 192) and the asynchronous transactions with RESGROUP DCSBTASY(Figure 193 on page 205).



DCBTSSYN MENU 1 TRANDEFDCBTSSYN RED1 1 TRANDEFDCBTSSYN SALE 1 TRANDEFDCBTSSYN STOC 1 TRANDEF� �

Figure 192. CICS BTS Sample: RESGROUP DCBTSSYN




DCBTSASY CUST 1 TRANDEFDCBTSASY DEL1 1 TRANDEFDCBTSASY INV1 1 TRANDEFDCBTSASY REM1 1 TRANDEF� �

Figure 193. CICS BTS Sample: RESGROUP DCBTSASY

We next created two RASGNDEFs:

• DCBTSATR (Figure 194) which is associated with RESGROUP DCBTSASY

• DCBTSSTR (Figure 195 on page 206) which is associated with RESGROUPDCBTSSYN

We created these RASGNDEFS to allow the asynchronous transactions to beinstalled in all target regions, and the synchronous transactions to be installed inthe requester regions as remote, and the target regions as local. In this way theinitial synchronous transaction, MENU, can be activated in the requester regionbut will be routed to run in the target region (PAA4), where all other synchronoustransactions will also run. This routing process is controlled by CICSPlex SMWLM.

Figure 196 on page 206 and Figure 197 on page 206 show the map display ofthe two RASGNDEFs.


Name DCBTSATRDescription DCBTS Asynchronous Transactns


Resource Group DCBTSASY RESGROUP Containing DefinitionsResource Type TRANDEF Resource Definition Type


NONE)� �Figure 194. CICS BTS Sample: RASGNDEF DCBTSATR



Name DCBTSSTRDescription DCBTS Synchronous Transactions

Target Scope SCSCTOR CICS System or System GroupRelated Scope PROTSAOR CICS System or System Group

Resource Group DCBTSSYN RESGROUP Containing DefinitionsResource Type TRANDEF Resource Definition Type

Usage REMOTE Assignment Type (LOCAL, REMOTE)Mode DYNAM Usage Qualifier by Resource TypeReferenced Assign Resource Assignment Definition nameOverride NONE Scope of Override (TARGET, RELATED, BOTH,

NONE)� �Figure 195. CICS BTS Sample: RASGNDEF DCBTSSTR

� � ----------------------- MAP of RASGNDEF DCBTSATR ------------ Row 1 of 4 COMMAND ===> Scroll ===> HALFRASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- ----------- DCBTSATR --- DCBTSASY --- TRANDEF -+- CUST 1

|- DEL1 1|- INV1 1+- REM1 1

--------------------------------- End Of Map ----------------------------------� �Figure 196. CICS BTS Sample: Map of RASGNDEF DCBTSATR

� � ----------------------- MAP of RASGNDEF DCBTSSTR ------------ Row 1 of 4 COMMAND ===> Scroll ===> HALFRASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- ----------- DCBTSSTR --- DCBTSSYN --- TRANDEF -+- MENU 1

|- RED1 1|- SALE 1+- STOC 1

--------------------------------- End Of Map ----------------------------------� �Figure 197. CICS BTS Sample: Map of RASGNDEF DCBTSSTR

Next we used the CICSPlex SM WLM to control where the various transactionswould be allowed to run.

First we created a WLM transaction group (TRANGRP) called DCBTSSYN andadded to it all synchronous transactions belonging to RESGROUP DCBTSSYN(Figure 198 on page 207).


� � 10DEC1998 16:38:22 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> CSR CURR WIN ===> 1 ALT WIN ===>W1 =DTRINGRP==========SCSPLEX==ALLCICS==04DEC1998==16:38:20====CPSM==========8

CMD Trangrp Trans PCONV --- Name---- Name---- Mode----

DCBTSSYN MENUDCBTSSYN RED1DCBTSSYN SALEDCBTSSYN STOC� �

Figure 198. CICS BTS Sample: Contents of TRANGRP DCBTSSYN

Next we created another TRANGRP called DCBTSASY and added to ittransactions belonging to RESGROUP DCBTSASY (Figure 199).



DCBTSASY CUSTDCBTSASY DEL1DCBTSASY INV1DCBTSASY REM1� �

Figure 199. CICS BTS Sample: TRANGRP DCBTSASY

Because we wanted to ensure that all synchronous tasks ran in the same targetregion, we created a WLM definition (WLMDEF) called DCBTSSYN (Figure 200)and associated it with TRANGRP DCBTSSYN, and gave it a target scope ofSCSCPAA4. In this way all transactions in TRANGRP DCBTSSYN could run onlyin target region PAA4.

� � ------------------- Browse Workload Definition for SCSPLEX -------------------- COMMAND ===>

Definition Name DCBTSSYNDescription Sync. CICS BTS Transctn Group

Trangroup Name DCBTSSYNTerminal Luname *User ID *Process Type *Target Scope SCSCPAA4� �

Figure 200. CICS BTS Sample: WLMDEF DCBTSSYN

Because we did not want to limit where the asynchronous transactions ranwithin the BTS set, we created another WLMDEF called DCBTSASY, which weassociated with TRANGRP DCBTSASY, and gave it a target scope of PROTSAOR.As you can see from Figure 201 on page 208, all transactions specified inTRANGRP DCBTSASY were allowed to run in all three target regions in the BTSset. Figure 202 on page 208 shows the browsed view of WLMDEF DCBTSASY.


� � W1 =SYSGRPC===========SCSPLEX==ALLCICS==10/12/1998=16:44:07====CPSM=====CMD Group Member Member--- Name---- Name---- Type----

PROTSAOR SCSCPAA1 CICSSYSPROTSAOR SCSCPAA4 CICSSYSPROTSAOR SCSCPAA7 CICSSYS� �

Figure 201. CICS BTS Sample: SYSGRP PROTSAOR


Definition Name DCBTSASYDescription Async. CICS BTS Transctn Group

Trangroup Name DCBTSASYTerminal Luname *User ID *Process Type *Target Scope PROTSAOR� �

Figure 202. CICS BTS Sample: WLMDEF DCBTSASY

Finally, we connected all of the BAS definitions described above to a RESDESCcalled DCBTS (Figure 203).

� �----------------------- MAP of RESDESC DCBTS ---------------- Row 1 of 24COMMAND ===> Scroll ===> HALFRESDESC RASINDSC RASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- -------- -------- -----------DCBTS --- <------> -+- -------- -+- DCBTSASY --- TRANDEF -+- CUST 1

| | |- DEL1 1| | |- INV1 1| | +- REM1 1| +- DCBTSSYN --- TRANDEF -+- MENU 1| |- RED1 1| |- SALE 1| +- STOC 1|- DCBTSATR --- DCBTSASY --- TRANDEF -+- CUST 1| |- DEL1 1| |- INV1 1| +- REM1 1|- DCBTSFL --- DCBTSFL --- FILEDEF -+- PTYPSALE 1| +- VSAMFIL1 1|- DCBTSPRC --- DCBTSPRC --- PROCDEF --- ORDER 1+- DCBTSSTR --- DCBTSSYN --- TRANDEF -+- MENU 1

|- RED1 1|- SALE 1+- STOC 1

--------------------------------- End Of Map ----------------------------------� �Figure 203. CICS BTS Sample: Map of RESDESC DCBTS


10.8.3.3 ITSO Test ScenarioAt this point we had the basic WLM definitions we had to add to a WLM groupand install into an active workload.

However, we did not have a large enough workload volume in the ITSO CICSplexfor WLM to invoke dynamic routing automatically, so we altered the TRANGRPand WLMDEF shown above. The changes were made to enable us to simulatedynamic routing, to show that asynchronous transactions belonging to the sameBTS process do not have to run in the same target region.

We placed only one of the asynchronous transactions, CUST, in TRANGRPDCBTSASY. We then grouped the other asynchronous transactions with thesynchronous transactions, and, instead of placing all of them in TRANGRPDCBTSSYN, we placed them in a new TRANGRP called CBTSTRAN (Figure 204).

TRANGRP DCBTSASY remained associated with WLMDEF DCBTSASY, but theTarget Scope of WLMDEF DCBTASY was changed to SCSCPAA7. The newTRANGRP CBTSTRAN was associated with a new WLMDEF, also calledCBTSTRAN (Figure 205). Be aware, that we created these definitions only toshow, by artificial means, that asynchronous transactions belonging to the sameBTS process can be routed to run in different regions. You would not typicallygroup asynchronous and synchronous transactions in this way, and you wouldcertainly not limit the scope of the asynchronous transactions to just one targetregion.



CBTSTRAN DEL1CBTSTRAN INV1CBTSTRAN MENUCBTSTRAN PAY1CBTSTRAN RED1CBTSTRAN REM1CBTSTRAN SALE� �

Figure 204. CICS BTS Sample: TRANGRP CBTSTRAN


Definition Name CBTSTRANDescription CBTS Transaction Group

Trangroup Name CBTSTRANTerminal Luname *User ID *Process Type *Target Scope SCSCPAA4� �

Figure 205. CICS BTS Sample: WLMDEF CBTSTRAN


The effect of these changes was that most of the transactions in the CICS BTSprocess would run in region PAA4, but the CUST transaction would be routed torun in region PAA7. Note that the process repository data set, PTYPSALE, andthe application data set VSAMFIL1, remain accessible in RLS mode by allregions in the BTS set, as shown in Figure 186 on page 202.

10.8.3.4 ITSO Test ResultsWhen we ran the sample CICS BTS process, by entering the MENU transactionfrom region PTA1, we monitored the use of the various transactions and notedthe trace output produced by the process in the various regions, to ensure thatthe process completed successfully.

Figure 206 shows the initial input screen.

� �CICS BTS COLOURED WIDGET ORDER FORM DATE 11/12/1998

TIME 12:23:37

BLUE WIDGETS 001 CUSTOMER NUMBER 12346

RED WIDGETS xxx ORDER NUMBER 221086

GREEN WIDGETS xxx

ORDER ACCEPTED xxx

MSG:

� �Figure 206. CICS BTS Sample: Initial Input Screen

Figure 207 on page 211 shows the initial use count values for two synchronoustransactions, MENU and RED1, and two asynchronous transactions, CUST andDEL1.

Following execution of the process, we would expect to see use counts rise foreach transaction as follows:

• MENU should show 1 in region PTA1 (where the transaction was initiated)and 1 in region PAA4, where WLM should have routed it to run.

• RED1 should show 1 in region PAA4 where, as a synchronous task, WLMshould have routed it to run.

• CUST should show 1 in region PAA4 (where the transaction was initiated)and 1 in region PAA7, where WLM should have routed it to run.

• INV1 should show 1 in region PAA7 (where the transaction was initiated) and1 in region PAA4, where WLM should have routed it to run.


� �11/12/1998 12:19:39 ----------- INFORMATION DISPLAY ---------------------COMMAND ===> SCROLL ===>CURR WIN ===> 3 ALT WIN ===>>W1 -LOCTRAN-----------SCSPLEX--ALLCICS--11/12/1998-12:17:49----CPSM----------5---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

MENU SCSCPAA1 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPAA4 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPAA7 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPTA1 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES DYNAMICMENU SCSCPTA2 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W2 -LOCTRAN-----------SCSPLEX--ALLCICS--11/12/1998-12:18:01----CPSM----------5---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

RED1 SCSCPAA1 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPAA4 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPAA7 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPTA1 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICRED1 SCSCPTA2 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W3 -LOCTRAN-----------SCSPLEX--SCSPLEX--11/12/1998-12:18:16----CPSM----------3---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

CUST SCSCPAA1 ENABLED 0 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMICCUST SCSCPAA4 ENABLED 0 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMICCUST SCSCPAA7 ENABLED 0 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W4 =LOCTRAN===========SCSPLEX==SCSPLEX==11/12/1998=12:19:23====CPSM==========3===CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

DEL1 SCSCPAA1 ENABLED 0 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICDEL1 SCSCPAA4 ENABLED 0 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICDEL1 SCSCPAA7 ENABLED 0 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC� �

Figure 207. CICS BTS Sample: Initial Transaction Use Counts

Figure 208 on page 212 shows that the process ran successfully. Figure 209 onpage 212 shows the process trace output produced in region PAA4. This outputshows that, of our selected sample transactions, both RED1 and INV1 wereexecuted in this region. From the process trace output produced in region PAA7(Figure 210 on page 213), you can see that transaction CUST was executed inregion PAA7.


� �CICS BTS COLOURED WIDGET ORDER FORM DATE 11/12/1998

TIME 12:23:37

BLUE WIDGETS 001 CUSTOMER NUMBER 12346

RED WIDGETS xxx ORDER NUMBER 221086

GREEN WIDGETS xxx

ORDER ACCEPTED Y

MSG:

� �Figure 208. CICS BTS Sample: Process Completion Screen

� �SAL2:SALES221086 12:24:28entry BEGIN-PROCESS 8SAL2:SALES221086 12:24:28entry INITIAL-ACTIVITYSAL2:SALES221086 12:24:28entry CHECK-CREDIT-STOCKSAL2:SALES221086 12:24:28about to run Credit-CHECK ActivityDFH0RED1RAN OKAY - RED1 - 12:24:28 - 11121998SAL2:SALES221086 12:24:28Credit-CHECK Activity run okSAL2:SALES221086 12:24:28about to run Stock-CHECK ActivityDFH0STOCRAN OKAY - STOC - 12:24:28 - 11121998SAL2:SALES221086 12:24:28Stock-CHECK Activity run okSAL2:SALES221086 12:24:28entry ORDER-ACCEPTED-PROCSAL2:SALES221086 12:24:28entry CHECK-CUSTOMER-ACTIVITYSAL2:SALES221086 12:24:29about to run CHECK-CUSTOMER async.DFH0INV1RAN OKAY - INV1 - 12:24:31 - 11121998CBTSDEL1RAN OKAY - DEL1 - 12:24:31 - 11121998SAL2:SALES221086 12:24:31entry BEGIN-PROCESSSAL2:SALES221086 12:24:31entry DEL-INV-CHECKSAL2:SALES221086 12:24:31entry DELIVERY-CHECKSAL2:SALES221086 12:24:31DELIV-NOTE Activity run okSAL2:SALES221086 12:24:31entry DEL-COMPLETESAL2:SALES221086 12:24:31entry INVOICE-CHECKSAL2:SALES221086 12:24:31INVOICE-BUILD run okSAL2:SALES221086 12:24:31entry INV-COMPLETESAL2:SALES221086 12:24:31Inv.+Del.ok, prepare ReminderSAL2:SALES221086 12:24:31entry SET-TIMER-EVENT� �

Figure 209. CICS BTS Sample: Trace Output from Region PAA4


� �CUSTOKCK ran okay- CUST - 12:24:30 - 11121998SAL2:SALES221086 12:24:31entry BEGIN-PROCESSSAL2:SALES221086 12:24:31Check-Customer Activity run okSAL2:SALES221086 12:24:31entry DEL-NOTE-AND-INVOICE-ACTIVITYSAL2:SALES221086 12:24:31about to run INVOICE-BUILD async.SAL2:SALES221086 12:24:31about to run DELIV-NOTE async.� �

Figure 210. CICS BTS Sample: Trace Output from Region PAA7

The trace output in Figure 209 on page 212 and Figure 210 proves that three ofthe transactions shown in Figure 207 on page 211 were executed in the regionsin which we anticipated they would execute. In Figure 211, this is confirmed,and you can also see that the use count for transaction MENU also changed, asexpected.

What this example shows is that, for one complete process, some transactions,(provided they are asynchronous) can run in different regions from the othertransactions belonging to that process.

� �11/12/1998 12:25:13 ----------- INFORMATION DISPLAY ---------------------COMMAND ===> SCROLL ===>CURR WIN ===> 3 ALT WIN ===>>W1 -LOCTRAN-----------SCSPLEX--ALLCICS--11/12/1998-12:25:13----CPSM----------5---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

MENU SCSCPAA1 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPAA4 ENABLED 1 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPAA7 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES STATICMENU SCSCPTA1 ENABLED 1 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES DYNAMICMENU SCSCPTA2 ENABLED 0 DFH0SAL0 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W2 -LOCTRAN-----------SCSPLEX--ALLCICS--11/12/1998-12:25:13----CPSM----------5---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

RED1 SCSCPAA1 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPAA4 ENABLED 1 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPAA7 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES STATICRED1 SCSCPTA1 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICRED1 SCSCPTA2 ENABLED 0 DFH0RED1 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W2 -LOCTRAN-----------SCSPLEX--SCSPLEX--11/12/1998-12:25:13----CPSM----------3---CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

CUST SCSCPAA1 ENABLED 0 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMICCUST SCSCPAA4 ENABLED 1 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMICCUST SCSCPAA7 ENABLED 1 CUSTOKCK 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC

>W3 =LOCTRAN===========SCSPLEX==SCSPLEX==11/12/1998=12:25:13====CPSM==========3===CMD Tran CICS Enabled Use Program Pri TranCls Purge Dmp Route--- ID-- System-- Status-- Count Name---- --- -------- ------------ --- -------

DEL1 SCSCPAA1 ENABLED 0 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICDEL1 SCSCPAA4 ENABLED 1 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMICDEL1 SCSCPAA7 ENABLED 1 DFH0DEL1 1 DFHTCL00 NOTPURGEABLE YES DYNAMIC� �

Figure 211. CICS BTS Sample: Post-Process Transaction Use Counts


10.8.4 Routing EXCI RequestsThe logic and flow behind EXCI requests is explained in detail in Chapter 7,“External CICS Interface Enhancements” on page 79. For the purposes ofexplaining how these requests can be routed, however, we briefly describe herethe functionality of an EXCI request.

The ITSO sample EXCI process is initiated through a TSO CLIST. The CLISTprovides users with a panel where they can specify the name of a CICS serverprogram they want to run and the CICS region where they want to run it.Additionally, users can specify an action to be performed by the program on aVSAM file, the results of which will be reported back to the TSO session.

A region in which to run the program must be specified. In this test we specifythe name of one of our two router/requester regions (or TORs), PTA1 and PTA2.However, because the program is dynamically routed, it actually runs in one ofthe three target regions (or AORs) defined within WLMSPEC SCSWS01Q.

10.8.4.1 Resource Definitions.The PROGDEF view for program VSAMSER1 is shown in Figure 212 on page 215.The VSRV value specified in the TRANSID field is included so that when theprogram is routed, it runs under the transaction ID VSRV rather than CSMI, aswould otherwise be the case. As a result, we can control the scope of where theprogram can be routed, by including transaction VSRV in a workloadmanagement definition. Additionally, as we explain below, by specifying atransaction ID we can also, optionally, use the MVS WLM to influence workloadbalancing.

The transaction definition for VSRV contains a program name of DFHMIRS and aprofile name DFHCICSA. The DFHCICSA profile is required, as it specifies thecorrect value for the INBFMH parameter, which must be specified asINBFMH(ALL) for a mirror transaction. The full transaction definition details for′VSRV′ are Figure 213 on page 215 thru Figure 216 on page 216 show the fulltransaction definition details for VSRV.


� � ------------------ Browse Program Definition for SCSPLEX ---------------------- COMMAND ===>

Name VSAMSER1 Version 1

Description Dynamic EXCI programCreated 12/01/98 17:25 Changed 12/03/98 17:47User Data

Language COBOL (ASSEMBLER, C, COBOL, LE370, PLI, RPG, N/A)Reload NO New copy of program loaded (NO, YES)Resident NO Resident status (NO, YES)Usage NORMAL Storage release (NORMAL, TRANSIENT)UseLPAcopy NO Program used from LPA (NO, YES)Status ENABLED Program status (ENABLED, DISABLED)Cedf YES CEDF available (YES, NO)Datalocation BELOW Data location (BELOW, ANY)Execkey USER Program key (USER, CICS)Executionset FULLAPI Program run mode (FULLAPI, DPLSUBSET)Remotesystem CICS region for shipped DPL requestRemotename Program name in remote CICS regionTransid VSRV Tranid for remote CICS to attachRsl Resource security value (0-24,PUBLIC,blank)Dynamic YES Dynamic routing (NO, YES)Concurrency N/A Concurrency (N/A, QUASIRENT, THREADSAFE)� �

Figure 212. EXCI Sample Program VSAMSER1: PROGDEF View

� � ------------ Browse Transaction Definition for SCSPLEX Page 1 ----------------- COMMAND ===>Name VSRV Version 1Description Dynamic EXCI transactionCreated 12/03/98 17:36 Changed 12/03/98 17:36User Data

Program DFHMIRS Name program to process transactionTwasize 0 Transaction work area size (0-32767, blank)Profile DFHCICSA Profile definition namePartitionset Application partition set (name, KEEP, OWN)Status ENABLED Transaction status (ENABLED, DISABLED)Taskdataloc BELOW Task storage location (BELOW, ANY)Taskdatakey USER Task storage key (USER, CICS)Storageclear NO Clear task life-time storage (YES, NO)Runaway SYSTEM Max tasktime (SYSTEM, 0-2700000, blank)Shutdown DISABLED Status during shutdown (DISABLED, ENABLED)Isolate YES Isolate user storage (YES, NO)� �

Figure 213. EXCI Sample Transaction VSRV: TRANDEF View Page 1


� � ------------ Browse Transaction Definition for SCSPLEX Page 2 ----------------- COMMAND ===>Name VSRV Version 1

Dynamic NO Dynamic route to remote region (NO, YES)Remotename Transaction name in remote systemRemote Sysid SYSIDENT for Remote SystemTrprof DFHCICSS Transaction routing profile nameLocalq N/A Queueing on local system (NO, YES, N/A)Priority 1 Transaction priority (0-255, blank)Tranclass DFHTCL00 Transaction class (DFHTCL00, name)Alias Alias name for transactionTaskreq Transactions initiationXtranid Alternate name for initiating transactionRessec NO Resource security checking (NO, YES)Cmdsec NO Sec checking for sys prog cmds (NO, YES)Action BACKOUT Recovery action (BACKOUT, COMMIT)Wait YES In-doubt unit of work wait (YES, NO)Waittime 0 , 0 , 0 In-doubt unit of work wait time (blank,

DD (0-93), HH (0-23), MM (0-59))� �Figure 214. EXCI Sample Transaction VSRV: TRANDEF View Page 2


Dtimeout NO Apply deadlock time-out (NO, 1-6800, blank)Indoubt BACKOUT Abend action (BACKOUT, COMMIT, WAIT)Restart NO Transaction restart facility (NO, YES)Spurge NO System purgeable (NO, YES)Tpurge NO Purged for terminal error (NO, YES)Dump YES Produce transaction dump (YES, NO)Trace YES Trace transaction activity (YES, NO)Confdata NO User data trace suppression (YES, NO)TPname Transaction name for APPC partner

XTPname Alternative TPname� �Figure 215. EXCI Sample Transaction VSRV: TRANDEF View Page 3


Brexit Name of bridge exit

Tclass NO Task class (NO, 1-10, blank)PrimedSize 0 Primed storage allocation size (0-65520,blank)Extsec NO External security manager used (NO, YES, N/A)Transec 1 Transaction security value (1-64, blank)Rsl 0 Resource security value (0-24, PUBLIC, blank)Routable YES Routable (NO, YES)� �

Figure 216. EXCI Sample Transaction VSRV: TRANDEF View Page 4


10.8.4.2 Resource Assignment DefinitionsWe placed the TRANDEF VSRV and the PROGDEF VSAMSER1 in resource groupDEXCI, and defined two resource assignments ′DEXCIPR′ and ′DEXCITR′.Figure 217, and Figure 218, respectively, show the two RASGNDEFs.Additionally, we defined a resource description, DEXCI; the map view of therelationship of these modules is shown in Figure 219 on page 218.


Name DEXCIPRDescription DEXCI Programs

Target Scope ALLCICS CICS System or System GroupRelated Scope CICS System or System Group

Resource Group DEXCI RESGROUP Containing DefinitionsResource Type PROGDEF Resource Definition Type


NONE)� �Figure 217. EXCI Sample: Browsed View of RASGNDEF DEXCIPR


Name DEXCITRDescription DEXCI Transaction

Target Scope ALLCICS CICS System or System GroupRelated Scope CICS System or System Group

Resource Group DEXCI RESGROUP Containing DefinitionsResource Type TRANDEF Resource Definition Type


NONE)� �Figure 218. EXCI Sample: Browsed View of RASGNDEF DEXCITR


� � ----------------------- MAP of RESDESC DEXCI ---------------- Row 1 of 4 COMMAND ===> Scroll ===> HALFRESDESC RASINDSC RASGNDEF RESGROUP RESTYPE RESDEF-------- -------- -------- -------- -------- ----------- DEXCI --- <------> -+- -------- --- DEXCI -+- PROGDEF --- VSAMSER1 1

| +- TRANDEF --- VSRV 1|- DEXCIPR --- DEXCI --- PROGDEF --- VSAMSER1 1+- DEXCITR --- DEXCI --- TRANDEF --- VSRV 1

--------------------------------- End Of Map ----------------------------------� �Figure 219. EXCI Sample: Map View of RESDESC DEXCI

10.8.4.3 WLM DefinitionsWe associated transaction VSRV with program VSAMSER1 to control the scopeof where the program ran, by means of the CICSPlex SM WLM. To achieve thisgoal, we defined a TRANGRP VSRVTRAN as shown in the TRANGRP display inFigure 220.

� � 07DEC1998 15:02:29 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> CSR CURR WIN ===> 1 ALT WIN ===> >W1 =TRANGRP===========SCSPLEX==ALLCICS==07DEC1998==15:02:29====CPSM=========13 CMD Trangrp Affinity Affinity Cre Match State Event Description --- Name---- Relation Lifetime- Aff Key---- -------- Name---- -----------------

CBTSTRAN N/A USERID ACTIVE CICS BTS TransactionsDP01TRAN N/A USERID ACTIVE DP01 TransactionDP02TRAN N/A USERID ACTIVE DP02 TransactionDP03TRAN N/A USERID ACTIVE DP03 TransactionDP04TRAN N/A USERID ACTIVE DP04 TransactionDP2PTRAN N/A USERID ACTIVE DP2P TransactionDST1TRAN N/A USERID ACTIVE DST1 TransactionSCSDPLS N/A USERID ACTIVE DPLS transactionSCSWTLSR N/A LUNAME ACTIVE SC4 cause deadlocSCSWTRLS N/A LUNAME ACTIVE Transactions forSCSWTSC4 GLOBAL SYSTEM YES LUNAME ACTIVE SC4 cause deadlocSCSWTSX4 GLOBAL SYSTEM YES LUNAME ACTIVE SX4 cause deadlocVSRVTRAN N/A USERID ACTIVE VSRV Transaction� �

Figure 220. EXCI Sample: TRANGRP Panel

We then defined a WLMDEF called VSRVTRAN, as shown in Figure 221 onpage 219, with a target scope of PROTSAOR specified. The members of groupPROTSAOR are shown in Figure 222 on page 219.


� � 07DEC1998 14:59:14 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> CSR CURR WIN ===> 1 ALT WIN ===> >W1 =WLMDEF============SCSPLEX==ALLCICS==07DEC1998==14:59:14====CPSM=========14 CMD Def Trangrp Luname Userid Process Target Description --- Name---- Name---- ----------------- -------- Type---- Scope--- ------------

CBTSTRAN CBTSTRAN * * * SCSCPAA4 BTS TransacDP01TRAN DP01TRAN * * * SCSCPAA1 DP01 TransacDP02TRAN DP02TRAN * * * SCSCPAA4 DP02 TransacDP04TRAN DP04TRAN * * * SCSCPAA7 DP04 TransacDP2PTRAN DP2PTRAN * * * PROTSAOR DP2P TransacDST1TRAN DST1TRAN * * * PROTSAOR DST1 TransacSCSDPL01 SCSDPLS * * * SCSCPAA7SCSWDLSR SCSWTLSR * * SCSCGLSR Non-RLS routSCSWDRLS SCSWTRLS * * SCSCGRLS RLS routingSCSWDSC4 SCSWTSC4 * * SCSCGLSRSCSWDSX4 SCSWTSX4 * * SCSCGRLSTEST1 TEST1 * * * SCSCPAA2TEST2 TEST1 * * * SCSCPAA3VSRVTRAN VSRVTRAN * * * PROTSAOR VSRV Transac� �

Figure 221. EXCI Sample: WLMDEF View

� � 07DEC1998 15:04:09 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> CSR CURR WIN ===> 1 ALT WIN ===>W1 =SYSGRPC===========SCSPLEX==ALLCICS==07DEC1998==15:04:09====CPSM==========3

CMD Group Member Member --- Name---- Name---- Type----

PROTSAOR SCSCPAA1 CICSSYSPROTSAOR SCSCPAA4 CICSSYSPROTSAOR SCSCPAA7 CICSSYS� �

Figure 222. EXCI Sample: Display of SYSGRPC PROTSAOR

The WLMDEF was associated with TRANGRP VSRVTRAN, and the resulting mapof this is shown in Figure 223.

� � ----------------------- MAP of TRANGRP VSRVTRAN ------------- Row 1 of 1 COMMAND ===> Scroll ===> HALF(S)CSYSDEF WLMSPEC WLMGROUP WLMDEF TRANGRP(G)CSYSGRP----------- -------- -------- -------- --------

VSRVTRAN --- VSRVTRAN --------------------------------- End Of Map ----------------------------------� �

Figure 223. EXCI Sample: Map of TRANGRP VSRVTRAN View

10.8.4.4 Testing of EXCI SampleWith the CICSPlex SM definitions in place, we tested the EXCI sample. To provethat dynamic routing was taking place, we set up a series of CICSPlex SMpanels (Figure 224 on page 220).

The screen in this example is confined to the PROTSAOR target scope becausethese regions are the only ones in which the program is defined to run. Theseare the initial use count values:


• Window 1 shows the starting use count of program VSAMSER1 in each targetregion, before the testing started, and this window is locked.

• Window 2 also shows the use count of program VSAMSER1 in each region.This window will be refreshed after each execution.

• Window 3 shows the workload status of each region. This window will beused to quiesce regions to force dynamic routing.

� � 07/12/1998 17:23:17 ----------- INFORMATION DISPLAY --------------------------- COMMAND ===> SCROLL ===> HALF CURR WIN ===> 2 ALT WIN ===> >L1 -PROGRAM-----------SCSPLEX--PROTSAOR-07/12/1998-17:21:32----CPSM----------3 CMD Program CICS Enabled Use Current Program Shared CEDF Copy --- Name---- System-- Status-- Count-- Use---- Language- Status Option Require

VSAMSER1 SCSCPAA1 ENABLED 0 0 COBOL PRIVATE CEDF NOTREQUVSAMSER1 SCSCPAA4 ENABLED 0 0 COBOL PRIVATE CEDF NOTREQUVSAMSER1 SCSCPAA7 ENABLED 0 0 COBOL PRIVATE CEDF NOTREQU

>W2 =PROGRAM===========SCSPLEX==PROTSAOR=07/12/1998=17:23:12====CPSM==========3 CMD Program CICS Enabled Use Current Program Shared CEDF Copy --- Name---- System-- Status-- Count-- Use---- Language- Status Option Require


W3 -WLMAWAOR----------SCSPLEX--SCSPLEX--07/12/1998-17:23:12----CPSM----------3 CMD Workload Ownr Target Status Connection --- -------- ---- -------- --------- Lost------

SCSCWS1D PCA1 SCSCPAA1 ACTIVESCSCWS1D PCA1 SCSCPAA4 ACTIVESCSCWS1D PCA1 SCSCPAA7 ACTIVE� �

Figure 224. EXCI Sample - Program Use-Count View before Testing Started

The driver program was initiated from a TSO CLIST. Figure 225 and Figure 226on page 221 show the sample screens produced by the CLIST, as well as theuser input. Note, that the CICS Sys.-Id specified is PTA1 is because PTA1 andPTA2 are the only two regions in which the EXCI connection is defined andenabled. Program VSAMSER1 will not actually run in this region, however.

� � Test Driver for EXCI Pgm 10/98 - Redbook SG24-5274 Enter S=SYNC.ON Return, N=no SYNC.on Return X=exits Enter CICS Sys.-Id (e.g. PAA1)pta1 Enter CICS Server Pgm(e.g. VSAMSERV)vsamser1 Enter Account Operation Code: 1=read, 2=add, 3=update, 4=delete, 9=Abend Server1 Enter Account Number (5 Char.num)12346� �

Figure 225. EXCI Sample: TSO Front-End Input (Screen 1)


� � ok done, lets check again what you entered SYNCONRETURN: S Comit/RollBk: Acc.Op.Code : 1 CICS Target : SCSCPTA1 CICS Pgm : VSAMSER1 Account Nr. : 12346 Acc. Owner : Address : , All ok? Enter Y for yes, anything else to repeaty now calling EXCI13 Returned from EXCI13, Ret.Codes are: EXCI13 RC: 0 RESP : 0 RESP2 : 0 Account Nr. : 12346 Acc. Owner : Steve Burghard Address : 14 E Main Street Los Gatos CA USA

DISPLAY FOR EXISTING CUSTOMER NUMBER 12346

please press Enter to continue� �Figure 226. EXCI Sample: TSO Front-End Input (Screen 2)

The screen displayed in Figure 227, was captured immediately after execution ofthe test input displayed in Figure 226.

As you can see from its use count, program VSAMSER1 ran in regionSCSCPAA1.







Figure 227. EXCI Sample: Program Use-Count View after First Test

We did not have a sufficient workload to cause WLM to reroute programVSAMSER1 to another region for performance purposes, so we forced WLM tomake a decision to reroute the program, by quiescing region SCSCPAA1. Thequiesced state of region SCSCPAA1 can be seen in Figure 228 on page 222,which was captured immediately after a second run of the TSO CLIST.

Notice that the use count for program VSAMSER1 has not increased in regionSCSCPAA1 (because it is quiesced), but it has increased in region SCSCPAA4.This is as a result of WLM rerouting the program to run in region SCSCPAA4.







SCSCWS1D PCA1 SCSCPAA1 QUIESCEDSCSCWS1D PCA1 SCSCPAA4 ACTIVESCSCWS1D PCA1 SCSCPAA7 ACTIVE� �

Figure 228. EXCI Sample: Program Use-Count View after Second Test

Finally, we reactivated region SCSCPAA1 and reran the CLIST for a third time.As you can see in Figure 229, region SCSCPAA1 is now in an active state, andthe use count for program VSAMSER1 has remained the same in regionSCSCPAA4, but it has increased by 1 again in region SCSCPAA1. This indicatesthat dynamic routing has taken place yet again, with the WLM this time choosingto run the program in region SCSCPAA1.







Figure 229. EXCI Sample: Program Use-Count View after Third Test


10.8.5 Affinity ManagementIn this section we explain the impact of affinities in case of dynamic routing forLINKs and STARTs and several ways to remove them. For further informationabout affinities and their removal, we recommend consulting such CICS books asCICS Transaction Affinities Utility Guide and CICSPlex SM Managing Workloads.

10.8.5.1 New CICS BTS AffinitiesWith CICS BTS comes a new affinity type and lifetime combination. Workloadscan now be separated based on the new affinity called BAPPL (businessapplication), similarly to the already familiar affinities, like USERID, LUNAME andTRANSID (managed through TRANGRPs).

Together with this new affinity type, there come two new affinity lifetimes. Thefirst is PROCESS, and the second, ACTIVITY. Therefore business applicationscan be separated to various regions on the basis of their BAPPL for the lifetimeof the entire process (PROCESS) or the lifetime of the activity being executed(ACTIVITY).

Typically, in an environment where full data sharing is implemented, these newaffinity types and lifetimes may not have to be implemented. In areas wheredata sharing is not available, however, the affinities will have to be managedaccordingly.

In our example environment all CICS TS AORs could access VSAM data sets inRLS mode and hence data sharing was in effect for our application that usedCICS BTS.

10.8.5.2 Using RETURN IMMEDIATESince CICS 3.3, there has always been a recommendation by CICS that userswho implement an EXEC CICS START TRANSID(xxxx) TERMID(EIBTRMID)INTERVAL(0) mechanism to immediately start a new transaction on the sameterminal (therefore removing the need to press Enter before the next transactionis executed) should implement EXEC CICS RETURN TRANSID(xxxx) IMMEDIATEinstead. The advantage of using RETURN IMMEDIATE is that the transactiongoes through CICS dynamic transaction routing mechanism and TRANSID(xxxx)can be dynamically balanced. The only application issue is that changing STARTTRAN TERM INT to RETURN IMMED could potentially change the logic flow of theapplication because a RETURN implies that it is the last action of the application,unlike an embedded START, which could go on to perform many more activitiesbefore issuing its RETURN.

With CICS TS 1.3 and dynamic routing of terminal STARTs, this considerationpotentially ceases to be an issue, and your START TRAN TERM INTERVALcommands can be left alone.

10.8.5.3 Using CANCELWhen reviewing affinity reports like those of the CICS Affinity Utility, you mightnote that not all STARTs are applicable to dynamic routing. Many STARTs areexecuted with a REQID option and this information is passed to a subsequentCANCEL command. If the START is dynamically routed to another AOR, theCANCEL will probably fail because the REQID does not exist in that region.Therefore you must take account of associated CANCELs before unilaterallydeciding to convert all your STARTs to dynamic routing.


10.8.6 Using MVS/WLMIn the EXCI example we show how to use the CICSPlex SM WLM to determinewhere to route an inbound client DPL. Using the transaction name from the EXCIexample, we show here the steps necessary to involve the MVS WLM in therouting decision. In this example, we show how to set up the workload to usegoal mode to select a suitable target region.

To ensure that goal mode routing can be invoked, the program must beassociated with the same transaction ID in both the requester region and thetarget region. Therefore include a TRANSID in the EXEC CICS LINK PROGRAMstatement, with the same name as the mirror transid specified in the programdefinition. In this case, we hard coded the transaction name in the front-endprogram. Thus the statement actually issued by the front end program in ourexample was as follows:

EXEC CICS LINK PROGRAM(VSAMSER1)RETCODE(RCAREA)COMMAREA(COMMAREA)LENGTH(COMALEN)APPLID(SCSCPTA1)TRANSID(VSRV)SYNCONRETURN

Goal mode routing can be applied to all types of inbound client DPL requestsand to CWI and IIOP initiated requests. It is not limited to the EXCI example.

10.8.6.1 MVS WLM DefinitionsIn this section we explain how to set up a service class in MVS WLM to whichyou can associate a CICS transaction. In this case, the name of the serviceclass is FAST, which has an average response time goal of 0.02 seconds. Weassociate transaction VSRV, as specified in the EXCI routing example earlier,with this service class.

In so doing, we are instructing CICSPlex SM to route VSRV to the target regionthat not only meets all the QUEUE criteria but also has the greatest chance ofmeeting the response time goal specified in service class FAST.

To define a new service class, enter WLM on the TSO command line. You arethen presented with the screen in Figure 230 on page 225.


� �File Help

--------------------------------------------------------------------------

Command ===> ______________________________________________________________

W W L M MW W L MM MMW W W L M M MWW WW L M MW W LLLLL M M

Licensed Materials - Property of IBM

5647-A01 (C) Copyright IBM Corp. 1998.All rights reserved.

ENTER to continue� �Figure 230. MVS WLM Initial Screen

Press Enter, and you are presented with the screen shown in Figure 231.

� �File Help

--------------------------------------------------------------------------

Command ===> ______________________________________________________________

.---------------------------------------------.| Choose Service Definition || || Select one of the following options. || 2_ 1. Read saved definition || 2. Extract definition from WLM || couple data set || 3. Create new definition || || || |′ ---------------------------------------------′

ENTER to continue� �Figure 231. MVS WLM Choose Service Definiton Panel

Select option 2 to get to the Definition Menu, shown in Figure 232 on page 226.


� �File Utilities Notes Options Help

-------------------------------------------------------------------------- Functionality LEVEL004 Definition Menu WLM Appl LEVEL004 Command ===> ______________________________________________________________

Definition data set . . : none

Definition name . . . . . CICSpol (Required) Description . . . . . . . Policy for WLM/CICS residency

Select one of the following options. . . . . 4__ 1. Policies

2. Workloads3. Resource Groups4. Service Classes5. Classification Groups6. Classification Rules7. Report Classes8. Service Coefficients/Options9. Application Environments10. Scheduling Environments� �

Figure 232. MVS WLM Main Definit ion Menu

Enter 4 on the Definition Menu to get a list of existing service classes, as shownin Figure 233.

� �Service-Class View Notes Options Help

--------------------------------------------------------------------------Service Class Selection List Row 1 to 14 of 31

Command ===> ______________________________________________________________

Action Codes: 1=Create, 2=Copy, 3=Modify, 4=Browse, 5=Print, 6=Delete,/=Menu Bar

Action Class Description Workload1_ BATCHHI Importance 4 batch for cbw2 BATCH__ BATCHLOW Importance 5 batch for cbw2 BATCH__ BATCHSPL Batch high priority BATCH__ BATCHTR Batch Thrashers BATCH__ CICSDFLT CICS default service class CICS__ CICSRGN CICS regions vel70 CICS__ CICSWORK CICS classified work CICS__ CICS12 CICS trans from LU 1 and 2 CICS__ CICS345 CICS trans from LU 3, 4, 5 CICS__ CICS678 CICS trans from LUs 6, 7, 8 CICS__ CICS90 CICS trans from LUs 9, and 0 CICS__ CPSMLONG Long running CPSM transactions CICS__ CPSMTRAN CPSM transactions CICS__ DISC Discretionary class BATCH� �

Figure 233. MVS WLM Service Class Selection List

Enter action code 1 on any line to create a new service class. You are thenpresented with the Create a Service Class panel (Figure 234 on page 227).


� �Service-Class Notes Options Help

--------------------------------------------------------------------------Create a Service Class Row 1 to 1 of 1

Command ===> ______________________________________________________________

Service Class Name . . . . . . FAST (Required) Description . . . . . . . . . dyn. routing of DPL and EC START Workload Name . . . . . . . . CICS____ (name or ?) Base Resource Group . . . . . ________ (name or ?)

Specify BASE GOAL information. Action Codes: I=Insert new period, E=Edit period, D=Delete period.

---Period--- ---------------------Goal---------------------Action # Duration Imp. Descriptioni_

******************************* Bottom of data ********************************� �Figure 234. MVS WLM Create a Service Class

In this panel, you specify the name of the service class you want to create and inwhich existing MVS workload you want to include the new class. We chose aservice class name of FAST and the MVS workload called CICS. After enteringan i in the Action field, you are presented with the popup screen shown inFigure 235.


- .-----------------------------------------. ----------------------------| Choose a goal type for period 1 | ss Row 1 to 1 of 1

C | | _____________________________| |

S | 1_ 1. Average response time | ired) D | 2. Response time with percentile | DPL and EC START W | 3. Execution velocity | or ?) B | 4. Discretionary | or ?)

| | S | | I=Insert new period, E | |

′ -----------------------------------------′---Period--- ---------------------Goal---------------------

Action # Duration Imp. Descriptioni

******************************* Bottom of data ********************************� �Figure 235. MVS WLM Choose a Goal Type

For CICS transactions, choose a goal type of 1, Average Response Time. Youare then presented with a panel in which you specify the response time goal(Figure 236 on page 228).



- .-----------------------------------------. ----------------------------| Choose a goal type for period 1 | ss Row 1 to 1 of 1

C | | _____________________________| |

S | 1 1. Average response time | ired) D .------------------------------------------------------------------. W | Average response time goal | B | |

| Enter a response time of up to 24 hours for period 1 | S | | E | Hours . . . . . 0 (0-24) |

| Minutes . . . . 0 (0-99) || Seconds . . . . 02 (0-9999) |

A | || Importance . . 1 (1=highest, 5=lowest) |

* | Duration . . . _________ (1-999,999,999, or | ********| none for last period) || || || |′ ------------------------------------------------------------------′� �

Figure 236. MVS WLM Average Response Time Goal

You are then presented with the updated input screen, as shown in Figure 237.


--------------------------------------------------------------------------Create a Service Class Row 1 to 2 of 2

Command ===> ______________________________________________________________

Service Class Name . . . . . . FAST (Required) Description . . . . . . . . . dyn. routing of DPL and EC START Workload Name . . . . . . . . CICS (name or ?) Base Resource Group . . . . . ________ (name or ?)

Specify BASE GOAL information. Action Codes: I=Insert new period, E=Edit period, D=Delete period.

---Period--- ---------------------Goal---------------------Action # Duration Imp. Description____ 1 1 Average response time of 00:00:02.000

******************************* Bottom of data ********************************

.-----------------------------------------------------------------------.| Press EXIT to save your changes or CANCEL to discard them. (IWMAM970) |′ -----------------------------------------------------------------------′

� �Figure 237. MVS WLM Response Times Defined

On this screen, press PF3 to save the newly defined service class and confirmthat it has been created (Figure 238 on page 229).


� �Service-Class View Notes Options Help

--------------------------------------------------------------------------Service Class Selection List Row 1 to 14 of 33

Command ===> ______________________________________________________________


Action Class Description Workload__ BATCHHI Importance 4 batch for cbw2 BATCH__ BATCHLOW Importance 5 batch for cbw2 BATCH__ BATCHSPL Batch high priority BATCH__ BATCHTR Batch Thrashers BATCH__ CICSDFLT CICS default service class CICS__ CICSRGN CICS regions vel70 CICS__ CICSSAMP sample create of a service class CICS__ CICSWORK CICS classified work CICS__ CICS12 CICS trans from LU 1 and 2 CICS__ CICS345 CICS trans from LU 3, 4, 5 CICS__ CICS67 .--------------------------------------------.__ CICS90 | Service class FAST was created. (IWMAM311) |__ CPSMLO ′ --------------------------------------------′__ CPSMTRAN CPSM transactions CICS� �

Figure 238. MVS WLM Service Class FAST Created

Now, return to the main menu, where you have to enter the relevant screens toassociate transaction VSRV with service class FAST. Select option 6,″Classification Rules″, as shown in Figure 239. You are presented with theSubsystem Type Selection List for Rules panel (Figure 240 on page 230).

� �File Utilities Notes Options Help

-------------------------------------------------------------------------- Functionality LEVEL004 Definition Menu WLM Appl LEVEL004 Command ===> ______________________________________________________________

Definition data set . . : none

Definition name . . . . . CICSpol (Required) Description . . . . . . . Policy for WLM/CICS residency

Select one of the following options. . . . . 6__ 1. Policies

2. Workloads3. Resource Groups4. Service Classes5. Classification Groups6. Classification Rules7. Report Classes8. Service Coefficients/Options9. Application Environments10. Scheduling Environments� �

Figure 239. MVS WLM Add VSRV to Service Class FAST (1)


� �Subsystem-Type View Notes Options Help

--------------------------------------------------------------------------Subsystem Type Selection List for Rules Row 1 to 12 of 12

Command ===> ______________________________________________________________


------Class------- Action Type Description Service Report

__ ASCH Use Modify to enter YOUR rules3_ CICS Use Modify to enter YOUR rules__ DB2 Use Modify to enter YOUR rules SCDB2STP__ DDF Use Modify to enter YOUR rules__ IMS Use Modify to enter YOUR rules__ IWEB Use Modify to enter YOUR rules TSOODD__ JES Use Modify to enter YOUR rules__ LSFM Use Modify to enter YOUR rules__ OMVS Use Modify to enter YOUR rules OMVS__ SOM Use Modify to enter YOUR rules__ STC Use Modify to enter YOUR rules__ TSO Use Modify to enter YOUR rules TSO

******************************* Bottom of data ********************************� �Figure 240. MVS WLM Add VSRV to Service Class FAST (2)

In this panel, there is a subsystem entry called CICS, and it is in this entry thatwe want to add VSRV. Selecting option 3 allows you to modify the entry andpresents the panel shown in Figure 241.

� �Subsystem-Type Xref Notes Options Help

--------------------------------------------------------------------------Modify Rules for the Subsystem Type Row 1 to 8 of 8

Command ===> ____________________________________________ SCROLL ===> PAGE

Subsystem Type . : CICS Fold qualifier names? Y (Y or N) Description . . . Use Modify to enter YOUR rules

Action codes: A=After C=Copy M=Move I=Insert ruleB=Before D=Delete row R=Repeat IS=Insert Sub-rule

-------Qualifier------------- -------Class--------Action Type Name Start Service Report

DEFAULTS: CICSDFLT ________ I___ 1 SI CICSPCA1 ___ CPSMTRAN CPSM ____ 1 TN MCCM ___ CPSMLONG ________ ____ 1 SI CICSPCB1 ___ CPSMTRAN CPSM ____ 1 TN MCCM ___ CPSMLONG ________ ____ 1 LUG LU12 ___ CICS12 CICS12R ____ 1 LUG LU345 ___ CICS345 CICS345R ____ 1 LUG LU678 ___ CICS678 CICS678R ____ 1 LUG LU90 ___ CICS90 CICS90R****************************** BOTTOM OF DATA *****************************� �


This screen presents you with all of the current rules for the subsystem typeCICS. To add an entry for VSRV, type an i anywhere in the Action column. Youcan then enter your new data (Figure 242 on page 231).


� �Subsystem-Type Xref Notes Options Help

--------------------------------------------------------------------------Modify Rules for the Subsystem Type Row 1 to 9 of 9

Command ===> ____________________________________________ SCROLL ===> PAGE

Subsystem Type . : CICS Fold qualifier names? Y (Y or N) Description . . . Use Modify to enter YOUR rules

Action codes: A=After C=Copy M=Move I=Insert ruleB=Before D=Delete row R=Repeat IS=Insert Sub-rule

-------Qualifier------------- -------Class--------Action Type Name Start Service Report

DEFAULTS: CICSDFLT ________ ____ 1 SI CICSPCA1 ___ CPSMTRAN CPSM ____ 1 TN MCCM ___ CPSMLONG ________ ____ 1 TN VSRV ___ <<<<<<< FAST ________ ____ 1 SI CICSPCB1 ___ CPSMTRAN CPSM ____ 1 TN MCCM ___ CPSMLONG ________ ____ 1 LUG LU12 ___ CICS12 CICS12R ____ 1 LUG LU345 ___ CICS345 CICS345R

.-----------------------------------------------------------------------.| Press EXIT to save your changes or CANCEL to discard them. (IWMAM970) |′ -----------------------------------------------------------------------′� �


In this panel, we have inserted an entry for transaction VSRV and associated itwith service class FAST. Press PF3 and save the altered MVS WLM definition todefine the new workload definition to MVS.

10.8.6.2 CICSPlex SM WLM DefinitionsFor CICSPlex SM to be aware of the fact that there is now an MVS WLM serviceclass goal to be considered, the WLMSPEC that controls workloads in thecandidate regions must be altered. Change the Algorithm Type parameter toGOAL (Figure 243 on page 232) to indicate that transactions specified in an MVSWLM class, must be routed to the region that has the best chance of meeting thespecified response time goal.


� �-------------------- Update WLM Specification for SCSPLEX --------------

COMMAND ===>

WLM Spec Name SCSCWS1DDescription ===> Distributed Routing Spec

Affinity Relation ===> Default Affinity Relation(USERID, LUNAME, GLOBAL)

Affinity Lifetime ===> Default Affinity Lifetime(SIGNON, LOGON, SYSTEM, PERMANENT, PCONV, Delimit

Match Key ===> USERID Default Primary search criterion(USERID, LUNAME)

Create Affinity ===> N/A Create auto affinity (YES, NO, N/A)Target Scope ===> DISTCICS Default CICS System, Group or Generic

Event Name ===> RTADEF, STATDEF or GenericAbend Health ===> 0 AOR ABEND Health Factor (0 - 99)Abend Load ===> 0 AOR ABEND Load Factor (0 - 99)

Algorithm Type ===> GOAL Algorithm Type (GOAL, QUEUE)

� �Figure 243. WLMSPEC View

10.9 Additional Issues to Consider with Dynamic and Distributed RoutingYou have to consider additional issues when you start to implement new types ofdynamic routing.

10.9.1 Mixed CICSPlex SM Release EnvironmentsRefer to Chapter 3, “Migration in a CICSPlex SM Managed CICSplexEnvironment” on page 17 for a detailed discussion of the consequences of mixedCICSPlex SM release environments.

10.9.2 Connection TopologyFor the distributed routing model to function properly, you have to ensure thatconnections are defined among all the participating systems in the model. Thesimplest way to achieve this and to avoid creating duplicate definitions is to haveone set of connection and session definitions and use BAS SYSLINKs to installthem across all systems.

This method of defining connections is explained in CICSPlex SM BusinessApplication Services: A New Solution to CICS Resource Management and issummarized here:

1. Create a CONNECTION definition, leaving the NetName parameter blank.

2. Create a SESSION definition, associating it with the CONNECTION definitioncreated in step 1.

3. Update the Recv/Send prfx parameter in the SESSION definition with aunique value (< , >), for example.

4. Create one SYSLINK definition for each pair of systems to be connected andinstall the newly created SYSLINKs in each system.


In order for this method of defining your connections to work successfully, youshould be aware of the following limitations:

• All regions being linked together should be within the same CICSplex.

• All regions being linked together should be within the same MVS ParallelSysplex.

• If you are installing the SYSLINKs manually, you only need to do so at oneend of the link: CICSPlex SM will define the other ″end″ of the linkautomatically.

10.9.3 Service Classes and TRANSIDsAs we discuss in the section 10.8.6, “Using MVS/WLM” on page 224, it ispossible to subject your workload to the control of the MVS workload manager.To recap, you specify a service class within MVS WLM with a chosen responsetime goal and associate a transaction ID to that service class. The MVS WLMwill distribute the workload to run in the target region in the best state to meetthe specified goal.

However, to achieve this goal for a DPL request where a client program issues alink request to run a server program in another region, you must ensure thatboth the client and server programs run under the same transaction ID. Codethe same transaction ID in in the ″Mirror Tranid″ of the server programdefinition, as the transaction ID used to initiate the client program in the firstplace. Figure 244 and Figure 245 on page 234 show the effects of routing withthe same and different transaction names.

Figure 244. Same Transaction Name for Client and Server Program: CICSPlex SM Can Select Required ServiceClass


Figure 245. Different Transaction Names: CICSPlex SM Cannot Select Required Service Class


Appendix A. CICSPlex SM New and Changed Views

The new features and improvements discussed in this publication have causedseveral changes to be made to existing CICSPlex SM views and panels. Thesechanges vary from the introduction of new terminology, to an increase in thenumber of subpanels for certain views, as a result of a larger set of optionsbeing available for certain resources. Additionally, with the introduction of suchnew resources as document templates and enqueue models, there are now anumber of completely new CICSPlex SM views.

This appendix contains examples of the new views and covers the changes thathave been made to existing views. It also gives a brief description of what thenew views and altered parameters mean.

A.1 Operational Views

A.1.1 CICS Region Related Views

A.1.1.1 CICSRGNDThe CICSRGND view (Figure 246), which is a detailed version of the CICSRGNview, has been altered in two ways; it spreads across four panels rather thanthree, and the first panel now contains two new fields:

• Dst Route Pgm - indicates the name of the distributed routing program beingused, if appropriate.

• RRMS status - is added for EXCI enhancements.

� �>W1 =CICSRGN==CICSRGND=SCSPLEX==ALLCICS==25NOV1998==12:45:09====CPSM============1

CICS System.... SCSCPAA1 Start Date... 20NOV1998 CICS Status.. ACTIVECICS Release... 0530 Start Time... 14:57:24 Monitor Stat. ONJob Name....... SC53PAA1 Totl CPU..... 00:50:29.7 Recordng Stat OFFVTAM Applid.... SCSCPAA1 Totl Page In. 41 Dump Status.. SYSDUMPLocation....... SC61 Totl Page Out 0 Trace Status. SYSTEMONCICS Sysid..... PAA1 Totl SIO Cnt. 4259 AUXTrace Stat AUXSTOPAKP............ 1000 Totl Real Stg 19892 RRMS Status.. OPENMRO Batch...... 1 Current Tasks 5 External Sec. NOSECURITYPriorty Aging.. 1 Trn Isol Stat INACTIVE Startup Stat. COLDSTARTRunaway Time... 20000 RPL Reopens.. 0 Autoinst InfoScan Delay..... 100 VTAM ACB..... OPEN Prgm AIn Exit DFHPGADXXit Wait Time.. 1000 Times Max RPL 0 Cat AIn Prgm. CTLGMODIFYLibrary Loads.. 0 Max RPL Postd 0 Dyn Route Pgm DFHDYPTot Load Time.. 00:00:00 VTAM SOS Cnt. 0 Dst Route Pgm NONECur Load Wait.. 0 VTAM Dyn Open 0 Storage Prot. INACTIVETot Load Wait.. 0 XRF Status... NOTAPPLIC TskRec ConvSt CONVERSEMax Load Wait.. 0 IRC Status... OPEN ShutDown Tran CESDCnt Max Wait... 0 CMD Protect.. NOCMDPROTTot Wait Time.. 00:00:00 RentProg Prot NOREENTPRDflt Remote Sys N/A SOS Status... NOTSOSMVS System Name SC61

� �Figure 246. CICSRGND View


A.1.1.2 CICSRGN4The CICSRGND view was previously spread across three views. There is now afourth hyperlink-accessed CICSRGN view (Figure 247):

• CICSRGN4 - This view gives detailed information about the auto-install exitbeing used. It can be hyperlinked to from the Autoinst Info field of theCICSRGND view.

� �W1 =CICSRGN==CICSRGN4=SCSPLEX==ALLCICS==25NOV1998==12:56:45====CPSM=====1

CICS System. SCSCPAA1 AutoIns Max 100AIn Ena Stat ENABLED Consoles... NOAUTOPRSS Delay.. 00:00:00AIn Pgrm Nme DFHZATDXAIn Curr Req 0

� �Figure 247. CICSRGN4 View

A.1.2 Temporary Storage Related ViewsA number of new temporary storage related views are additions to the originalset of TSQ, TSQD, TSQGBL, TSQGBLD and TSQGBLS.

A.1.2.1 TSMODELThe TSMODEL view (Figure 248) shows general information about installedtemporary storage models. It can be accessed by either specifying TSMODEL, inwhich case the view will include information about all temporary storage modelswithin the current scope, or limiting the view to a specific or generic temporarystorage model name.

� � W1 =TSMODEL===========SCSPLEX==ALLCICS==19NOV1998==19:02:48====CPSM=========15=CMD Model CICS TS Queue Rec Sec TSQ Rem Remote--- ID------ System-- Prefix Location Att Att Poolname Sys Prefix

DFHWEB SCSCPAA4 DFHWEB MAIN NO NODFHWEB SCSCPAA7 DFHWEB MAIN NO NODFHWEB SCSCPFA1 DFHWEB MAIN NO NODFHWEB SCSCPTA1 DFHWEB MAIN NO NODPLSTSHR SCSCPTA1 DPL AUXILIARY NO NO TSQSPQA1TSTRDAAA SCSCPAA4 R AUXILIARY NO NO TSQSPQA1TSTRDAAB SCSCPAA4 C AUXILIARY NO NOTSTRDAAC SCSCPAA4 D AUXILIARY NO NOTSTRDAAD SCSCPAA4 E AUXILIARY NO NOTSTRDAAE SCSCPAA4 X AUXILIARY NO NOTSTRDAAF SCSCPAA4 AB AUXILIARY NO NO PFA1 LCTSTRDAAG SCSCPAA4 AUXILIARY NO NO TSQSPQA1TSTRDAAH SCSCPAA4 SAQ AUXILIARY NO YES TSQSPQA1TSTRDAAZ SCSCPAA4 Z AUXILIARY YES YESTSTRDZZ SCSCPAA4 YEAR++RESULTS AUXILIARY NO NO TSQSPQA1

� �Figure 248. TSMODEL View


A.1.2.2 TSMODELDThe TSMODELD view (Figure 249) shows detailed information about a specific orgeneric temporary storage model. It is accessed by specifying TSMODELD tsm,where tsm is the specific or generic temporary storage model name.

� �

W1 =TSMODELD==========SCSPLEX==ALLCICS==24NOV1998==12:48:19====CPSM===========1CICS System....... SCSCPTA1TS Model Name..... DFHWEB

TSQ Name Prefix... DFHWEBTSQ Location...... MAIN

Recovery Attribute NOTRECOVABLESecurity Attribute NOSECURITYShared Poolname...

Remote System.....Remote Prefix.....

� �Figure 249. TSMODELD View

A.1.2.3 TSMODELSThe TSMODELS view (Figure 250) is a summarized form of the TSMODEL view.It is identical to the TSMODEL view, except that it has an additional field,COUNT, which indicates the number of resources that were combined to formeach line of summary data.

� �>W1 =TSMODELS==========SCSPLEX==ALLCICS==24NOV1998==12:24:32====CPSM==========4CMD Model CICS Count TS Queue Rec Sec TSQ Rem--- ID------ System-- ----- Prefix Location Att Att Poolname Sys

******** SCSCPAA4 11 **************** ********* **** **** ******** ****DFHWEB SCSCPAA7 1 DFHWEB MAIN NO NODFHWEB SCSCPFA1 1 DFHWEB MAIN NO NODFHWEB SCSCPTA1 1 DFHWEB MAIN NO NO

� �Figure 250. TSMODELS View

A.1.2.4 TSQSHRThe TSQSHR view (Figure 251 on page 238) shows general information abouteither all shared temporary storage queues and pools in the current scope, orspecific queues and pools defined in the coupling facility. It is accessed byspecifying TSQSHR tsq tspool, where the optional parameters tsq and tspool are,respectively, the specific temporary storage queue name and the specifictemporary storage pool name.

Note that printable queue names are shown as 16 printable characters andunprintable names are shown as 32 hexadecimal characters.

Appendix A. CICSPlex SM New and Changed Views 237

� � W1 =TSQSHR============SCSPLEX==ALLCICS==19NOV1998==17:59:11====CPSM=========10CMD Queue CICS Pool Que Number Total--- Name---------------------------- System-- Name---- Locn Items- Length--

DPLSHAREDQUEUE SCSCPAA4 TSQSPQA1 AUX 7 364FD00C5C4C3E4E2E34040404040404040 SCSCPAA4 TSQSPQA1 AUX 12 13261FFC2C1F1F2F4F4C14040404040404040 SCSCPAA4 TSQSPQA1 AUX 2 54FFC2C1F2F2F4F4C14040404040404040 SCSCPAA4 TSQSPQA1 AUX 2 706FFC2C1F3F2F4F4C14040404040404040 SCSCPAA4 TSQSPQA1 AUX 2 668FIRSTCPSMTEST SCSCPAA4 TSQSPQA1 AUX 1 18RECOMM SCSCPAA4 TSQSPQA1 AUX 1 18RECOVTEST SCSCPAA4 TSQSPQA1 AUX 1 18SAQTEST SCSCPAA4 TSQSPQA1 AUX 1 18TESTRDO SCSCPAA4 TSQSPQA1 AUX 1 18

� �Figure 251. TSQSHR View

A.1.2.5 TSQSHRDThe TSQSHRD view (Figure 252) shows detailed information about a sharedtemporary storage queue. It is accessed by specifying TSQSHRD tsq sysnametspool, where tsq is the name of the chosen temporary storage queue, sysnameis the name of a CICS system within the current scope, and tspool is the name ofa temporary storage pool defined in the MVS coupling facility.

� �W1 =TSQSHRD===========SCSPLEX==ALLCICS==24NOV1998==13:02:24====CPSM===========1Queue Name..... TESTRDOCICS System.... SCSCPAA4Pool Name...... TSQSPQA1Location....... AUXILIARYNumber Items... 1Total Length... 18Max Item Len... 18Min Item Len... 18Time since use. 1130422Creating Tran.. CECIRecovery Status NOTRECOVABLE

� �Figure 252. TSQSHRD View

A.1.2.6 TSQSHRSThe TSQSHRS view (Figure 253) is a summarized form of the TSQSHR view. Itis identical to the TSMODEL view, except that it has an additional field, COUNT,which indicates the number of resources that were combined to form each lineof summary data.

� �>W1 =TSQSHRS===========SCSPLEX==ALLCICS==24NOV1998==12:19:41====CPSM==========1CMD Queue CICS Count Pool Que Number--- Name---------------------------- System-- ----- Name---- Locn Items- --

******************************** SCSCPAA4 10 TSQSPQA1 AUX 19 64� �Figure 253. TSQSHRS View


A.1.2.7 TSPOOLThe TSPOOL view (Figure 254) contains general information about temporarystorage pools. It is accessed by specifying TSPOOL tspool, where tspool is theoptional name of a temporary storage shared pool. If tspool is not specified, theview shows information about all temporary storage pools within the currentscope.

� � W1 =TSPOOL============SCSPLEX==ALLCICS==24NOV1998==11:59:45====CPSM==========3CMD Pool CICS Connection--- Name---- System-- Status----

TSQSPQA1 SCSCPAA1 UNCONNECTEDTSQSPQA1 SCSCPAA4 CONNECTEDTSQSPQA1 SCSCPTA2 UNCONNECTED

� �Figure 254. TSPOOL View

A.1.2.8 TSQNAMEThe TSQNAME view (Figure 255) contains general information about allnonshared temporary storage queues. It is accessed by specifying TSQNAMEtsqname, where tsqname is the optional name of a nonshared temporary storagequeue. If tsqname is not specified, the view shows information about allnonshared temporary storage queues within the current scope.

� � W1 =TSQNAME===========SCSPLEX==ALLCICS==24NOV1998==12:16:03====CPSM==========3CMD Queue CICS Que Number Total--- Name---------------------------- System-- Locn Items- Length--

CEBR SCSCPAA4 AUX 38 4992CPSMTEST SCSCPAA4 AUX 1 64DPLSHAREDQUEUE SCSCPAA7 AUX 100 12800

� �Figure 255. TSQNAME View

A.1.2.9 TSQNAMEDThe TSQNAMED view (Figure 256 on page 240) shows detailed information abouta specific nonshared temporary storage queue. It is accessed by specifyingTSQNAME tsq sysname, where tsq is the name of a specific nonsharedtemporary storage queue and sysname is the name of the CICS system in whichthe queue is defined. The CICS system referred to by sysname must be in thecurrent scope.


� �W1 =TSQNAMED==========SCSPLEX==ALLCICS==24NOV1998==12:52:59====CPSM===========1Queue Name..... CEBRCICS System.... SCSCPAA4

Location....... AUXILIARYNumber Items... 38Total Length... 4992Max Item Len... 192Min Item Len... 64Time since use. 329060Creating Tran.. CUSTRecovery Status NOTRECOVABLE

� �Figure 256. TSQNAMED View

A.1.2.10 TSQNAMESThe TSQNAMES view (Figure 257) shows summarized information about anonshared temporary storage queue. It is identical to the TSQNAME view,except that it has an additional field, COUNT, which indicates the number ofresources that were combined to form each line of summary data.

� � W1 =TSQNAMES==========SCSPLEX==ALLCICS==24NOV1998==12:04:05====CPSM==========2CMD Queue CICS Count Que Number Total--- Name---------------------------- System-- ----- Locn Items- Length--

C******************************* SCSCPAA4 2 AUX 39 5056DPLSHAREDQUEUE SCSCPAA7 1 AUX 100 12800

� �Figure 257. TSQNAMES View

A.1.3 TCP/IP Related Views

A.1.3.1 TCPIPSThe TCPIPS view (Figure 258) shows general information about currentlyinstalled TCP/IP service definitions.

� � W1 =TCPIPS============SCSPLEX==ALLCICS==20NOV1998==17:21:01====CPSM========2CMD Service CICS Port Open Conn Back IP Address TS Q--- Name System-- ----- Status---- Count- log--- --------------- Prefix

TCPIPS1 SCSCPAA4 Closed 0 0TCPIPS2 SCSCPFA1 Closed 0 0

� �Figure 258. TCPIPS View


A.1.3.2 TCPIPSDThe TCPIPSD view (Figure 259) shows detailed information about a selectedTCP/IP service definition. It can be accessed by hyperlinking from an entry inthe Service Name field on the TCPIPS view.

� � W1 =TCPIPS===TCPIPSD==SCSPLEX==ALLCICS==20NOV1998==17:21:01====CPSM========2

CICS System........ SCSCPAA4TCP/IP Service Name TCPIPS1Port............... 1Open Status........ CLOSEDConnections........ 0Backlog............ 0SSL................ SSLNOTransid............ AMNUURM................TS Queue Prefix....IP Address.........

� �Figure 259. TCPIPSD View

A.1.4 Request Model Related Views

A.1.4.1 RQMODELThe RQMODEL view (Figure 260) shows general information about currentlyinstalled request models.

� � W1 =RQMODEL===========SCSPLEX==ALLCICS==25NOV1998==19:23:58====CPSM========6CMD Model CICS Tran--- ID------ System-- ID--

DFHGFACT SCSCPAA1 CIOFDFHGFACT SCSCPAA4 CIOFDFHGFACT SCSCPAA7 CIOFDFHGFACT SCSCPFA1 CIOFDFHGFACT SCSCPTA1 CIOFDFHGFACT SCSCPTA2 CIOF

� �Figure 260. RQMODEL View

A.1.4.2 RQMODELDThe RQMODELD view (Figure 261 on page 242) shows detailed informationabout a selected request model. It can be accessed by hyperlinking from theModel ID field in the RQMODEL view.


� �W1 =RQMODEL==RQMODELD=SCSPLEX==ALLCICS==25NOV1998==19:23:58====CPSM=========1

CICS System....... SCSCPAA1Request Model Name DFHGFACTOMG Module........ com..ibm..CosLifeCycle

OMG Interface..... GenericFactoryOMG Operation..... *Transaction id.... CIOF

� �Figure 261. RQMODELD View

A.1.4.3 RQMODELSThe RQMODELS view (Figure 262) is a summary view, identical, in this example,to the RQMODEL view, with the addition of a Count field.

� � W1 =RQMODELS==========SCSPLEX==ALLCICS==25NOV1998==19:28:43====CPSM========6CMD Model CICS Count Tran--- ID------ System-- ----- ID--

DFHGFACT SCSCPAA1 1 CIOFDFHGFACT SCSCPAA4 1 CIOFDFHGFACT SCSCPAA7 1 CIOFDFHGFACT SCSCPFA1 1 CIOFDFHGFACT SCSCPTA1 1 CIOFDFHGFACT SCSCPTA2 1 CIOF� �

Figure 262. RQMODELS View

A.1.5 Task Related Views

A.1.5.1 TASKDThe TASKD view (Figure 263 on page 243) previously spread across threedifferent screens, is now spread accross nine screens.


� �>W1 =TASKD=============SCSPLEX==ALLCICS==25NOV1998==19:30:34====CPSM===========1

Task ID........ 24 CICS System.. SCSCPAA2 Expanded UOW.....Tran ID........ CONL Terminal ID.. RRMS/MVS Uowid..User ID........ CICSUSER TermConn Name N/A Client IP addr..Tran Class..... DFHTCL00 Terminal..... N/A Bridge Tranid....First Program.. EYU9XLEV Info........ N/A Identifier.......Priority....... 255 Facility ID.. DB2 Plan.........TaskProf....... DFHCICST Facility..... TASK Process Type.....

LU Name...... Process Name.....Attach Date.... Network...... USIBMSC Activity Name....Attach Time.... 00:00:00 Name...... SCSCPAA2 Clocks/timing....Elapsed Time... 05:07:53 Unit of...... 62AE5D6E Settings.........Perf Rec Cnt... N/A Work ID..... 35A20001 Request counts...Running Status. RUNNING Unit of...... B162AE5D Comms requests...Suspend Type... Recovery.... 6E35A206 Storage usage....Suspend Value.. WLM ServClass N/A TCP/IP usage.....

WLM ReptClass N/A CICS BTS requestsCurrent Suspend 00:00:00 CICS TCB..... N/A ENQ info.........

CPU/TCB info.....

� �Figure 263. TASKD View

A.1.5.2 TASK2The TASK2 view (Figure 264) is hyperlinked to from the Settings field on theTASKD view.

� �>W1 =TASKD====TASK2====SCSPLEX==ALLCICS==25NOV1998==19:34:35====CPSM============1

Task ID........ 24 CICS System... SCSCPAA2 Timeout values==Tran ID........ CONL Purge Status.. NOTPURGE Runaway Time... 50000User ID........ CICSUSER Trace Type.... STANTRAC Deadlock TmOut. 0Tran Priorty... 255 Trans Dumps... NOTRANDUMP Read TmOut..... 0

Routing info=== Security====== Recovery========Dynamic Routing STATIC CmdLvl Secur.. CMDSECNO Dyn Tran Bck...BACKOUTRouting Profile ResLvl Secur.. RESSECNO Option......... N/ARem. Tran Name. Wait Option.... N/ARem. System Id. Wait Time...... N/A

Storage========TWA Size....... 512Screen Size.... DEFAULTClear Stor..... NOCLEARTsk Data Key... CICSDATAKEYTsk Data Loc... ANYIsolate Status. ISOLATE

� �Figure 264. TASK2 View


A.1.5.3 TASK3The TASK3 view (Figure 265) is hyperlinked to from the ′Clocks/timing′ field onthe TASKD view.

� �>W1 =TASKD====TASK3====SCSPLEX==ALLCICS==25NOV1998==19:34:35====CPSM===========1

Task ID.......... 24 Running Status.. RUNNINGTran ID.......... CONL Suspend Type....User ID.......... CICSUSER Suspend Value...CICS System...... SCSCPAA2Elapsed Time..... 05:11:53 Current Suspend. 00:00:00Clocks=========== Cnt Clocks========== CntDispatch time... 00:00:02 ... 339 Lcl ENQ delay.. 00:00:00 ... 0Suspend time.... 05:11:51 ... 339 Gbl ENQ delay.. N/A ... N/ADispwait........ 00:00:00 ... 338 FC I/O......... 00:00:00 ... 0CPU............. 00:00:00 ... 338 JC I/O......... 00:00:00 ... 0RLS CPU Time.... N/A ... N/A TD I/O......... 00:00:00 ... 01st Disp Delay.. 00:00:00 ... 1 TempStor I/O... 00:00:00 ... 0

IMS DB wait.... N/A ... N/ARMI Elapsed Time 00:00:00 ... N/A DB2 total wait. N/A ... N/ARMI Suspend Time 00:00:00 ... N/A Syncpointing... N/A ... N/AException....... 00:00:00 ... 0 Comms I/O...... 00:00:00 ... 0Prog Load....... 00:00:00 ... 22 Other wait..... N/A ... N/A


A.1.5.4 TASK4The TASK4 view (Figure 266) is the first of the completely new views, containinginformation about request counts. Accordingly, it is accessed by hyperlinkingfrom the Request counts field in the TASKD view.


Task ID........ 24 CICS System.... SCSCPAA2 Jrnl Write Req N/ATran ID........ CONL FC Gets....... 0 Log Write Req. N/AUser ID........ CICSUSER FC Puts....... 0 Syncpoints.... 0

FC Browses.... 0 DH Creates.... N/ATotals......... FC Adds....... 0 DH Inserts.... N/AFile Control.. 0 FC Deletes.... 0 DH Sets....... N/ATran Data..... 3 FC AccMeths... 0 DH Retrieves.. N/ATemp Storage.. 0 TD Gets....... 3 DH Doc Length. N/APgm Control... 23 TD Puts....... 0 IMS Requests.. N/AIntervl Cntrl. N/A TD Purges..... 0 DB2 Requests.. N/ADocument reqs. N/A TS Gets....... 0 Chng Mode Reqs N/ADB requests... N/A TS Puts aux... 0 TCB Att Reqs.. N/ATermnl reqs... 0 TS Puts main.. 0BMS reqs...... 0 PC Links...... 1FEPI reqs..... 0 PC Link Dist.. N/AStorage....... 168 PC Links URM.. N/ACICS BTS reqs. N/A PC Loads...... 22WEB Reqs...... N/A PC Xctls...... 0� �

Figure 266. TASK4 View


A.1.5.5 TASK5The TASK5 view (Figure 267) contains task storage statistics. It is accessed byhyperlinking from the Storage usage field on the TASKD view.


Task ID....... 24 Above 16M===== Below 16M=====Tran ID....... CONL User Storage-- User Storage--User ID....... CICSUSER Getmains..... 0 Getmains..... 0CICS System... SCSCPAA2 HWM bytes.... 0 HWM bytes.... 0

CICS Storage-- CICS Storage--TWA Size...... 512 Getmains..... 168 Getmains..... 0Clear Stor.... NOCLEAR HWM bytes.... 20304 HWM bytes.... 0Tsk Data Key.. CICSDATAKEY Shared Storage Shared StorageTsk Data Loc.. ANY Getmains..... N/A Getmains..... N/A

Stg getmained N/A Stg getmained N/AStg freed.... N/A Stg freed.... N/A

Program Stg--- Program Stg--- Program Stg---Overall HWM.. 2400304 Total HWM.... 2400304 Total HWM.... 0

Share Stg HWM 0 Share Stg HWM 0R/O Stg HWM.. 2388480 R/O Stg HWM.. 0CICS Stg HWM. 11824 CICS Stg HWM. 0Usr Stg HWM.. N/A Usr Stg HWM.. N/A


A.1.5.6 TASK6The TASK6 view (Figure 268) contains communication requests information. It isaccessed from the TASKD view by hyperlinking from the Comms requests field.


Task ID....... 24 CICS System.... SCSCPAA2 Terminal requestsTran ID....... CONL FEPI requests== Primary----------User ID....... CICSUSER Allocates..... 0 Msgs recvd...... 0

Sends......... 0 Msgs sent....... 0Facility ID... Receives...... 0 Chrs recvd...... 0Facility...... TASK Starts........ 0 Chrs sent....... 0Terminal ID... Chars Sent.... 0 Secondary--------TermConn Name. N/A Chars Received 0 Allocates....... 0Terminal...... N/A Alloc TimeOuts 0 Msgs recvd...... 0Info......... N/A Recv TimeOuts. 0 Msgs sent....... 0LU Name....... Total Requests 0 Chrs recvd...... 0Clock times=== Clock starts=== Chrs sent....... 0TC I/O....... 00:00:00 TC I/O........ 0 LU62 Msgs Recvd. 0IRC I/O...... 00:00:00 IRC I/O....... 0 LU62 Msgs Sent.. 0LU62 I/O..... 00:00:00 LU62 I/O...... 0 LU62 Chrs Recvd. 0LU61 I/O..... 00:00:00 LU61 I/O...... 0 LU62 Chrs Sent.. 0FEPI wait.... 00:00:00 FEPI wait..... 0 TC total........ 0Socket I/O... N/A Socket I/O.... N/A BMS total....... 0



A.1.5.7 TASK7The TASK7 view (Figure 269) contains statistical information about the CICS BTSrequests issued by a task. It can be accessed by hyperlinking from the CICSBTS Requests field on the TASKD view.


Task ID............ 24 CICS System..... SCSCPAA2 Process Name.Tran ID............ CONL Process Type.... N/A Activity NameUser ID............ CICSUSER

Process/Activity... Container.......Requests=========== Requests========Run Proc/Act sync. N/A Process........ N/ARun Proc/Act async N/A Activity....... N/ALink Proc/Act..... N/A TOTAL........... N/ASuspend Proc/Act.. N/AResume Proc/Act... N/A Event...........Del/Can Proc/Act.. N/A Requests========Define Process.... N/A Retr. Reattach. N/ADefine Activity... N/A Define Input... N/AAcquire Process... N/A Define Timer... N/AReset Activity.... N/A TOTAL........... N/ATOTAL.............. N/A


A.1.5.8 TASK8The TASK8 view (Figure 270) contains statisitcal information about the usage ofTCP/IP services and activities issued by a task. It is hyperlinked to from theTCP/IP Usage field on the TASKD view.


Task ID........ 24 CICS System..... SCSCPAA2Tran ID........ CONLUser ID........ CICSUSER Client IP addr. N/A

WEB Requests=== Socket Info===== cntReceives...... N/A Socket I/O wait N/A ... N/AChars Received N/A Bytes Encrypted N/ASends......... N/A Bytes Decrypted N/AChars sent.... N/ARepos. Writes. N/ATOTAL.......... N/A



A.1.5.9 TASK9The TASK9 view (Figure 271) contains statistical information about CPU usage ofa task. It can be accessed by hyperlinking from the CPU/TCB Usage field on theTASKD view.


Task ID.......... 24Tran ID.......... CONLUser ID.......... CICSUSERCICS System...... SCSCPAA2Clocks=========== Cnt Clocks========== CntTotal Disp time. 00:00:02 ... 341 Total CPU...... 00:00:00 ... 340Misc Disp time.. N/A ... N/A Misc CPU time.. N/A ... N/AQR Disp time.... N/A ... N/A QR CPU time.... N/A ... N/A

L8 CPU time.... N/A ... N/AJ8 CPU time.... N/A ... N/AS8 CPU time.... N/A ... N/A

Max Open TCB dly N/A ... N/A TCB Att Reqs... N/AQR Mode Delay... N/A ... N/A Chng Mode Reqs. N/A

CICS TCB....... N/A


A.1.6 Data Table Related Views

A.1.6.1 CMDTDThe CMDTD view (Figure 272 on page 248) has been altered to includeinformation related to coupling facility data tables. The new parametersintroduced for this purpose are:

• CFDT Pool

• Table Name

• Load Type

• Table information

• Dataset Information

Additionally, the data presented within this view has been reorganized to suchan extent that it is spread over two more new views: CMDT2 and CMDT3.


� �W1 =CMDT=====CMDTD====SCSPLEX==ALLCICS==20NOV1998==17:21:01====CPSM============1

File ID..... FILEACICS System. SCSCPAA4Table Type.. CFTABLEDataset Name CICSSYSF.CICS530.PAA1.FILEAEnabled Stat ENABLEDOpen Status. OPENDisposition. SHAREAdd Option.. ADDABLEBrowse Opt.. BROWSABLEDelete Opt.. DELETABLERead Option. READABLEUpdate Opt.. UPDATABLEUpdate Model LOCKINGCFDT Pool... TESTCFT1Table Name.. FILEREVRecvry Stat. RECOVERABLE Table Info..Load Type... LOADFwd Recvry.. NOTFWDRCVBLE Dataset Info

� �Figure 272. CMDTD View

A.1.6.2 CMDT2The CMDT2 view (Figure 273) is an extended view accessed from the CMDTDview. It contains detailed information about the table selected for the originalCMDTD view. It is accessed by hyperlinking on the Table information parameterof the CMDTD view.

� �>W1 =CMDT=====CMDT2====SCSPLEX==ALLCICS==25NOV1998==18:40:34====CPSM============1

File ID........ FILEA CICS System..... SCSCPAA4 Table Type.....CFTABLETime Opened.... 00:00:00Time Closed.... 00:00:00 Table Reads..... Storage Usage..GMT Opened..... 00:00:00 Reads From Tbl. 0 Tot Stg Alloc. 0GMT Closed..... 00:00:00 Record Not Fnd. 0 Tot Stg Used.. 0

Read Retries... 0 Entr Stg Alloc 0Table Info..... Entr Stg Used. 0Record Size... 80 Table Adds...... Indx Stg Alloc 0Key Length.... 6 Adds From Reads 0 Indx Stg Used. 0Key Position.. 1 Tbl Add Request 0 Data Stg Alloc 0LSR Pool ID... 01 Add Rej By Exit 0 Data Stg Used. 0DataSet Type.. K Adds Table Full 0Rec Format.... VARIABLEJournal ID.... 0 Other Table Req. Table Usage....Max Num Recs.. 1000 Table Rewrites. 0 Curr Records.. 49

Table Deletes.. 0 Highest Recs.. 49Contentions.... 0

Dataset Info...

� �Figure 273. CMDT2 View


A.1.6.3 CMDT3The CMDT3 view (Figure 274) describes the data set that is underlying to thetable. The table is always loaded from the data set, but it is only kept in stepwith the data set for a CMDT, not a UMDT or a CFDT.

The CMDT3 view is accessed by hyperlinking on the Table Informationparameter in either the CMDTD view or the CMDT2 view.

� �W1 =CMDT=====CMDT3====SCSPLEX==ALLCICS==25NOV1998==18:40:34====CPSM=====1

File ID......... FILEA CICS System SCSCPAA4 Table Type CFTABLE

Dataset Stats...EXCP VSAM Dat.. 0EXCP VSAM Idx.. 0Add Requests... 0Browse Requests 0Delete Requests 0Get Requests... 0Get Upd Request 0Update Requests 0

String Usage....Strings........ 3Active Strings. 0String Waits... 0

Table Info......� �Figure 274. CMDT3 View

A.1.6.4 CMDTSThe CMDTS view (Figure 275) shows summarized information about files thathave CICS or user-maintained data tables or coupling facility data tablesassociated with them. It is a summary form of the CMDT view.

� � W1 =CMDTS=============SCSPLEX==ALLCICS==24NOV1998==12:38:02====CPSM==========2==CMD File CICS Count Enable Table Get Browse Curr Highest--- ID------ System-- ----- Status--- Type---- Requests Requests Records- Records FILEA SCSCPAA4 1 ENABLED CFTABLE 0 0 49 49 FILEA SCSCPFA1 1 ENABLED CFTABLE 0 0 6 6

� �Figure 275. CMDTS View

A.1.7 CICS BTS-Related ViewsWith CICS BTS, a new set of views have become available that relate to processtypes.


A.1.7.1 PROCTYPThe PROCTYP view (Figure 276) shows general information about BTS processtypes and their attributes.

� � W1 =PROCTYP===========SCSPLEX==ALLCICS==24NOV1998==13:09:24====CPSM==========3CMD ProcType CICS Filename Audit Audit Enable--- Name---- System-- Log Level Status ORDER SCSCPAA4 PTYPSALE CBTSLOG FULL ENABLED

� �Figure 276. PROCTYP View

A.1.7.2 PROCTYPDThe PROCTYPD view (Figure 277) shows detailed information about a processtype.

� �W1 =PROCTYPD==========SCSPLEX==ALLCICS==24NOV1998==13:12:55====CPSM===========1

CICS System..... SCSCPAA4ProcessType Name ORDER

File Name....... PTYPSALE

Audit Log name.. CBTSLOGAudit Level..... FULL

Enable Status... ENABLED� �Figure 277. PROCTYPD View

A.1.7.3 PROCTYPSThe PROCTYPS view (Figure 278) shows summarized information about BTSprocess types and is a summarized form of the PROCTYP view.

� � W1 =PROCTYPS==========SCSPLEX==ALLCICS==24NOV1998==13:14:34====CPSM==========1CMD ProcType CICS Count Filename Audit Audit Enable--- Name---- System-- ----- Log Level Status ORDER SCSCPAA4 1 PTYPSALE CBTSLOG FULL ENABLED

� �Figure 278. PROCTYPS View

A.1.8 CFDT Pool Related ViewsWith the inclusion of coupling facility data tables in this release, CICSPlex SMnow has a series of views that impart information on the data tables themselvesand the pools to which they belong.


A.1.8.1 CFDTPOOLThe CFDTPOOL view (Figure 279) provides general information about allinstalled coupling facility data table pools.

� � W1 =CFDTPOOL==========SCSPLEX==ALLCICS==26NOV1998==12:48:07====CPSM==========2CMD Pool CICS Connection--- Name---- System-- Status----

TESTCFT1 SCSCPAA4 CONNECTEDTESTCFT1 SCSCPFA1 CONNECTED

� �Figure 279. CFDTPOOL View

A.1.8.2 CFDTPOODThe CFDTPOOD view (Figure 280) provides detailed information relating to a fileassociated with a coupling facility data table pool. It can be accessed byhyperlinking from the Pool Name field on the CFDTPOOL view.

� �W1 =CFDTPOOL=CFDTPOOD=SCSPLEX==ALLCICS==26NOV1998==12:48:07====CPSM===========1

Pool Name........ TESTCFT1CICS System...... SCSCPFA1Connection Status CONNECTED

� �Figure 280. CFDTPOOD View

A.1.8.3 CFDTPOOSThe CFDTPOOS view (Figure 281) provides summary information relating tocoupling facility data table pools.

� � W1 =CFDTPOOS==========SCSPLEX==ALLCICS==26NOV1998==12:54:14====CPSM==========1CMD Pool CICS Connection Count--- Name---- System-- Status---- -----

TESTCFT1 SCSCP*** CONNECTED 2

� �Figure 281. CFDTPOOS View

A.1.9 Enqueue Related ViewsWith the introduction of global enqueue and dequeue and the enqueue model, anew set of views related to enqueue models has been created.


A.1.9.1 ENQMDLThe ENQMDL view (Figure 282) shows general information about enqueuemodels. It is accessed by specifying ENQMDL enqmodel, where enqmodel is thespecific name of a currently installed enqueue model. An asterisk (*) can alsobe specified instead of enqmodel; it will show information about all enqueuemodels in the current scope and is the default.

� � W1 =ENQMDL============SCSPLEX==ALLCICS==24NOV1998==13:15:45====CPSM==========4CMD Model CICS Scope Enable--- Name System Name Status

GMODEL1 SCSCPAA4 TES1 ENABLEDGMODEL1 SCSCPFA1 TES1 ENABLEDGMODEL2 SCSCPAA4 TES2 ENABLEDGMODEL2 SCSCPFA1 TES2 ENABLED

� �Figure 282. ENQMDL View

A.1.9.2 ENQMDLDThe ENQMDLD view (Figure 283) shows detailed information about the enqueuemodel entries defined within the Parallel Sysplex.

>W1 =ENQMDLD===========SCSPLEX==ALLCICS==24NOV1998==13:21:06====CPSM=======13:21:06====CPSM==========1Name........ GMODEL1 Enqname.. C7D3D6C2 5C404040 40404040 40404040 *GLOB* *CICS System. SCSCPAA4 40404040 40404040 40404040 40404040 * *Scope Name.. TES1 40404040 40404040 40404040 40404040 * *Enablestatus ENABLED 40404040 40404040 40404040 40404040 * *

40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *40404040 40404040 40404040 40404040 * *

Figure 283. ENQMDLD View

A.1.9.3 ENQMDLSThe ENQMDLS view (Figure 284) shows summarized information about enqueuemodels defined within the Parallel Sysplex.

� � W1 =ENQMDLS===========SCSPLEX==ALLCICS==24NOV1998==13:19:24====CPSM==========2CMD Model CICS Count Scope Enable--- Name System ----- Name Status

GMODEL** SCSCPAA4 2 TES* ENABLEDGMODEL** SCSCPFA1 2 TES* ENABLED

� �Figure 284. ENQMDLS View


A.1.10 Monitored Transaction Related ViewsBecause monitored transactions now have a greater amount of information todisplay, the views containing that data have been expanded.

A.1.10.1 MLOCTRADThe MLOCTRAD view (Figure 285) has always been split across three views. Afourth view, MLOCTRA4, has now been included (Figure 286). It can beaccessed by hyperlinking from the More Data..... field on the MLOCTRAD view.

� �W1 =MLOCTRAN=MLOCTRAD=SCSPLEX==ALLCICS==30NOV1998==14:17:42====CPSM==========1Tran ID........ AAAA CICS System.... SCSCPAA7 Remote Sysid..Use Count...... 0 First Program.. ######## FC Reqs....... 0CS Tran Rate... 0.0 Task Priority.. 1 TD Reqs....... 0MI Tran Rate... 0.0 Tran Class..... DFHTCL00 TS Reqs....... 0Total Response. 00:00:00.0 Local Dyn Cnt.. 0 BMS Reqs...... 0CS Avg Response 00:00:00.0 Restart Cnt.... 0 TC Msg Out.... 0MI Avg Response 00:00:00.0 Remote Dyn Cnt. 0 TC Msg In..... 0Total CPU Time. 00:00:00.0 Rem Start Cnt.. 0 PC Reqs....... 0CS Avg CPU Time 00:00:00.0 Stg Viol Cnt... 0 JC Reqs....... 0MI Avg CPU Time 00:00:00.0 IC Strt & Init. 0 IC Reqs....... 0Suspend Cnt.... 0 Suspend Time... 00:00:00.0 Syncpoint Req. 0Dispatch Cnt... 0 Dispatch Time.. 00:00:00.0 Terminal Stor. N/ADisp Wait Cnt.. 0 Disp Wait Time. 00:00:00.0 Pgm stg < 16M. 0Excpt Wait Cnt. 0 Excpt Wait Time 00:00:00.0 Pgm stg > 16M. 0IRC Wait Cnt... 0 IRC Wait Time.. 00:00:00.0 R/O Stg < 16M. 0TC IO Wait Cnt. 0 TC IO Wait Time 00:00:00.0 Share Stg >16M 0FC IO Wait Cnt. 0 FC IO Wait Time 00:00:00.0 Share Stg <16M 0JC IO Wait Cnt. 0 JC IO Wait Time 00:00:00.0 Totl FEPI Req. 0TD IO Wait Cnt. 0 TD IO Wait Time 00:00:00.0TS IO Wait Cnt. 0 TS IO Wait Time 00:00:00.0

More Data.....� �Figure 285. MLOCTRAD View

� �W1 =MLOCTRAN=MLOCTRA4=SCSPLEX==ALLCICS==30NOV1998==14:17:42====CPSM==========1Tran ID....... AAAA CICS System..... SCSCPAA7WEB Requests== Receives..... 0 ChngMode Reqs... 0 Chars Rcvd... 0 TCB Att. Reqs... 0 Sends........ 0 Chars sent... 0 Max Open TCB tm. 00:00:00.0 Max Open TCB cnt. 0 Repos Writes. 0 QR Mode Delay... 00:00:00.0 QR Mode Delay cnt 0 Total........ 0 QR Dispatch time 00:00:00.0 QR Dispatch cnt.. 0Document Reqs= QR CPU time..... 00:00:00.0 QR CPU count..... 0 Creates...... 0 Misc Dispatch tm 00:00:00.0 Misc Dispatch cnt 0 Inserts...... 0 Misc CPU time... 00:00:00.0 Misc CPU count... 0 Sets......... 0 L8 CPU time..... 00:00:00.0 L8 CPU count..... 0 Retrieves.... 0 J8 CPU time..... 00:00:00.0 J8 CPU count..... 0 Doc Length... 0 S8 CPU time..... 00:00:00.0 S8 CPU count..... 0 Total........ 0 DB2 Conn wait tm 00:00:00.0 DB2 Conn wait cnt 0Database Reqs= DB2 RdyQ wait tm 00:00:00.0 DB2 RdyQ wait cnt 0DB2 Requests.. 0 DB2 Req wait tm. 00:00:00.0 DB2 Req wait cnt. 0IMS Requests.. 0 IMS DB wait tm.. 00:00:00.0 IMS DB wait cnt.. 0� �

Figure 286. MLOCTRA4 View


A.1.11 CICS Web Interface Related ViewsImprovements to the way in which HTML templates can be defined and managedhave created the need for a new set of views with which to interrogate details ofdefined document templates.

A.1.11.1 DOCTEMPThe DOCTEMP view (Figure 287) provides general information about installeddocument templates.

� � W1 =DOCTEMP===========SCSPLEX==ALLCICS==26NOV1998==12:48:07====CPSM==========2CMD Document CICS Template--- Template System-- Type----

TEMPLT1 SCSCPAA4 EXIT

� �Figure 287. DOCTEMP View

A.1.11.2 DOCTEMPDThe DOCTEMPD view (Figure 288) provides detailed information about aselected document template. It can be accessed by hyperlinking from theDocument Template field on the DOCTEMP view.

� � W1 =DOCTEMP==DOCTEMPD=SCSPLEX==ALLCICS==26NOV1998==12:48:07====CPSM==========2

CICS System...... SCSCPAA4Document Template TEMPLT1Template Type.... EXITTemplate Name.... TESTTMPFile Name........TSqueue Name.....TDqueue Name.....Exit Program..... URM1Program Name.....DDname...........Member...........Dataset Name.....

� �Figure 288. DOCTEMPD View

A.1.11.3 DOCTEMPSThe DOCTEMPS view (Figure 289 on page 255) shows summary informationabout currently installed document templates.


� � W1 =DOCTEMPS==========SCSPLEX==ALLCICS==26NOV1998==13:13:27====CPSM==========1CMD Document CICS Count Template--- Template System-- ----- Type----

TEMPLT1 SCSCPAA4 1 EXIT

� �Figure 289. DOCTEMPS View

A.1.12 Program Related ViewsThe changes to program properties arising from the improvements made todynamic routing have led to new fields being added to program related views.

A.1.12.1 PROGRAMDThe PROGRAMD view (Figure 290) has been updated to include two newdynamic routing related fields. The first field, Dynam Status, reflects the valuethat was specified for Dynamic(YES|NO) when the program was defined. Thesecond field, Concurrency, reflects the value specified forConcurrency(N/A|QUASIRENT|THREADSAFE) when the program was defined.

� �>W1 =PROGRAM==PROGRAMD=SCSPLEX==ALLCICS==25NOV1998==13:58:18====CPSM=========1===

Program Name. PFC1PRG CICS System... SCSCPAA7 Curr Use Cnt. 0Load Address. FF000000 Exec Key...... USEREXECKEY Tot Use Cnt.. 0Entry Point.. FF000000 Execution Set. FULLAPI Use In Intvl. 0Length....... 0 Mirror Tranid. Newcopy Cnt.. 0Enable Status ENABLED Shared Status. PRIVATE Removed Cnt.. 0Pgm Language. ASSEMBLER LPA/SVA Stat.. NOTAPPLIC Fetch Cnt.... 0COBOL Type... NOTAPPLIC Current Loc... NOCOPY RPL Number... 0Usage........ PROGRAM Held Status... NOTAPPLIC Remote Name..CEDF Option.. CEDF Fetch Time.... 00:00:00.00 Remote Sysid.Data Location BELOW Avg Fetch Time 00:00:00.00 Copy Requird NOTREQUIREDDynam Status. NOTDYNAMIC Concurrency... QUASIRENT

� �Figure 290. PROGRAMD View

A.1.13 Transaction Related ViewsIn the same way that program properties have been affected by dynamic routingimprovements, so too have transaction properties, and new fields have beenadded to some transaction related views.

A.1.13.1 LOCTRANDThe LOCTRAND (Figure 291 on page 256) view has been updated to include onenew field relating to dynamic routing. The new field, Routing Status, reflects thevalue that was specified for Routable(NO|YES) when the transaction was defined.


� �>W1 =LOCTRAN==LOCTRAND=SCSPLEX==ALLCICS==25NOV1998==14:51:03====CPSM============1

Tran ID..... CAFB CICS System.. SCSCPAA4 Routing....... STATICProgram Name CAUCAFB1 Remote System Route Profile.Remote Name. Tran Priority 1 Use Count..... 0Enabled Stat ENABLED Task Data Loc ANY Local Dyn Cnt. 0Isolate Stat ISOLATE Task Data Key CICSDATA Remote Dyn Cnt 0Shutdwn Stat SHUTENABLED Resource Sec. RESSECNO Restarted..... 0System Purge NOTPURGEABLE Screen Size.. DEFAULT Rem Start Cnt. 0Tran Dump... TRANDUMP Read Timeout. 0 Stg Violations 0DTB Opt..... N/A DLock Timeout 0 Clear Stg..... NOCLEARCMDSEC Opt.. CMDSECNO Runaway Time. 0 TWA Size...... 0Trace Opt... STANTRACE Runaway Type. USER Profile....... DFHCICSTTran Class.. DFHTCL00 TRAN INDOUBT. FORCE Due To..

Option...... BACKOUT Trandef...... 0Wait Option. WAIT Indoubt...... 0Wait Time... 00,00,00 No Wait...... 0Wait Count.. 0 Operator..... 0Actn Mismatch 0 Other........ 0Bridge Exit.. Routing Status NOTROUTABLEFacilitylike.

� �Figure 291. LOCTRAND View

A.2 Administration Views

A.2.1 CICS System Related Views

A.2.1.1 CICSSYSThe CICSSYS view has been altered to reflect the change in dynamic routingterminology. When you issue the BROwse command against a chosen CICSsystem from the initial CICSSYS view (Figure 292), the terminology on thesecond screen of the next view is altered, as follows:

• Routing Support active replaces TOR support active

• Target routing at startup replaces AOR routing at startup

� �------------- Browse System - Workload Attributes - for SCSPLEX ---------COMMAND ===>

System name SCSCPAA2 Description AOR2 for plex SCSPLEX

Routing Support active YES Routing support to be activated Workload specification Current WLMSPEC for a Routing reg Specification source Type of link to WLMSPEC System group name System group if implicit source

Target routing at startup YES

� �Figure 292. CICSSYS Browse View


A.2.2 Workload Management Related ViewsThe introduction of new terminology to describe the various components of adynamic routing model, (that is, Router, Target, and Requester) and thesubsequent replacement of terms such as AOR and TOR are reflected in therelevant fields of the workload management related views.

A.2.2.1 WLMSPECThe WLMSPEC view (Figure 293) has been amended so that it now displays aTarget Scope as opposed to an AOR Scope.

� �

>W1 =WLMSPEC===========SCSPLEX==ALLCICS==24NOV1998==17:26:37====CPSM====1CMD Name Affinity Affinity Target Cre Match Event Description--- -------- Relation Lifetime Scope--- Aff Key--- Name---- ------------

SCSWS01Q SCSCG001 N/A USERID

� �Figure 293. WLMSPEC View

A.2.2.2 WLMDEFThe WLMDEF view (Figure 294) has also been amended so that it now displays aTarget Scope as opposed to an AOR Scope. Additionally, it now contains a newfield, Process Type, which has been added for CICS BTS support.

>W1 =WLMDEF============SCSPLEX==ALLCICS==24NOV1998==17:33:01====CPSM========================5CMD Def Trangrp Luname Userid Process Target Description--- Name---- Name---- ----------------- -------- Type---- Scope--- ---------------------------

SCSDPL01 SCSDPLS * * * SCSCPAA7SCSWDLSR SCSWTLSR * * SCSCGLSR Non-RLS routing definitionsSCSWDRLS SCSWTRLS * * SCSCGRLS RLS routing definitionsSCSWDSC4 SCSWTSC4 * * SCSCGLSRSCSWDSX4 SCSWTSX4 * * SCSCGRLS

Figure 294. WLMDEF View

A.2.2.3 WLMAWORKThe WLMAWORK view (Figure 295) has been amended so that it now displaysRout cnt and a Targ cnt as opposed to TOR cnt and AOR cnt, respectively.Additionally, it now contains a new field, Shared Status. This field indicateswhether or not the workload is shared between CMAS systems running atdifferent releases of CICSPlex SM. See Chapter 10, “Dynamic Routing of STARTand LINK Requests” on page 141 for more details.

>W1 =WLMAWORK==========SCSPLEX==ALLCICS==30NOV1998==14:42:11====CPSM=====================================1CMD Name Ownr Rout Targ Affinity Lifetime Target Event Status Cre Algorith Description Shared--- -------- ---- Cnt- Cnt- -------- --------- Scope--- Name---- ------ Aff -------- ---------------status SCSWS01Q PCA1 2 5 NONE NONE SCSCG001 ACTIVE N/A QUEUE NO

Figure 295. WLMAWORK View


A.2.2.4 WLMAWORDThe WLMAWORD view (Figure 296), which is the detailed view of a hyperlinkedactive workload name on the WLMAWORK view, has also been amended withthe new terminology.

� �

W1 =WLMAWORK=WLMAWORD=SCSPLEX==ALLCICS==30NOV1998==14:42:11====CPSM======1Workload Name.... SCSWS01Q Description..Owner Name....... PCA1 Shared StatusRouter Count..... 2Target Count..... 5Affinity......... NONEAffinity Lifetime NONETarget Scope..... SCSCG001Event Name.......Status........... ACTIVECreate Affinity.. N/AAlgorithm Type... QUEUEAbend Health..... 0Abend Load....... 0� �

Figure 296. WLMAWORD View

A.2.2.5 WLMAWDEFThe WLMAWDEF view (Figure 297) reflects the CICS BTS and terminologychanges discussed above.

>W1 =WLMAWDEF==========SCSPLEX==ALLCICS==30NOV1998==15:16:41====CPSM=================================3CMD Name Workload Ownr Trangrp Luname Userid Process Target Description--- -------- -------- ---- -------- ----------------- -------- Type---- Scope-- ----------------------

SCSWDLSR SCSWS01Q PCA1 SCSWTLSR * * SCSCGLS Non-RLS routing definiSCSWDRLS SCSWS01Q PCA1 SCSWTRLS * * SCSCGRL RLS routing definitionSCSWDSX4 SCSWS01Q PCA1 SCSWTSX4 * * SCSCGRL

Figure 297. WLMAWDEF View

A.2.2.6 TRANGRPThe TRANGRP CREate panel (Figure 298 on page 259) has been altered toreflect the fact that transaction affinities can now be associated with BTS activityor processes. There is a new option for the Affinity Relation field:

• BAPPL - base transaction affinity on the CICS BTS application

There are two new options for the Affinity Lifetime field:

• ACTIVITY - maintain transaction affinity until associated CICS BTS activityends.

• PROCESS - maintain transaction affinity until associated CICS BTS processends.


� �------------------------ Create Trangroup for SCSPLEX ------------------------COMMAND ===>

Trangroup name ===> Description ===> Transactions for RLS mode file

Status ===> ACTIVE Transaction Group Status(ACTIVE,DORMANT)

Match Key ===> LUNAME Primary WLMDEF search criterion(USERID,LUNAME)

Affinity Relation ===> Optional affinity relation may be:(USERID,LUNAME,GLOBAL,BAPPL)

Affinity Lifetime ===> Optional affinity lifetime may be:(SIGNON,LOGON,PCONV,DELIMIT,SYSTEM,PERMANENT,ACTIVITY,PROCESS)

Create Affinity ===> N/A Create Auto Affinity (YES, NO, N/A) Event Name ===> RTADEF/STATDEF or generic

Abend Health ===> 0 Target ABEND Health Factor (0 - 99) Abend Load ===> 0 Target ABEND Load Factor (0 - 99)

� �Figure 298. Transaction Group Definit ion Panel

A.3 Application Definition PanelsChanges to dynamic routing have caused additional fields to be inserted into theCREate views for both transaction and program definitions.

A.3.1 Transaction Definition PanelsThe first three TRANDEF CREATE panels are unaltered, but the fourth panel(Figure 299) now contains a new field, Routable. This field allows you to specifywhether or not the transaction, when invoked using an EXEC CICS STARTTERMID TRANSID command, is eligible for shipping to the TOR (the routingregion) for dynamic routing. The default is NO.

� �------------ Create Transaction Definition for SCSPLEX Page 4 -----------------COMMAND ===> Name PFC1 Version 0


Tclass ===> Task class (NO, 1-10, blank) PrimedSize ===> Primed storage allocation size (0-65520,blank) Extsec ===> N/A External security manager used (NO, YES, N/A) Transec ===> Transaction security value (1-64, blank)Rsl ===> Resource security value (0-24, PUBLIC, blank) Routable ===> NO Routable (NO, YES)

� �Figure 299. New Transaction Definit ion Panel (4)


A.3.2 Program Definition PanelsThe PROGDEF Create panel (Figure 300) now has two additional fields:

• Dynamic - allows you to specify whether or not an EXEC CICS LINK to thisprogram can invoke dynamic routing. The default is NO.

• Concurrency - specifies whether the program is written to threadsafestandards or is only quasi-reentrant.

� �------------------ Create Program Definition for SCSPLEX ----------------------COMMAND ===>

Name ===> PFC1PRG Version ===> 0

Description ===> RESGROUP ===> User Data ===>

Language ===> COBOL (ASSEMBLER, C, COBOL, LE370, PLI, RPG, N/A) Reload ===> NO New copy of program loaded (NO, YES) Resident ===> NO Resident status (NO, YES) Usage ===> NORMAL Storage release (NORMAL, TRANSIENT) UseLPAcopy ===> NO Program used from LPA (NO, YES) Status ===> ENABLED Program status (ENABLED, DISABLED) Cedf ===> YES CEDF available (YES, NO) Datalocation ===> BELOW Data location (BELOW, ANY) Execkey ===> USER Program key (USER, CICS) Executionset ===> FULLAPI Program run mode (FULLAPI, DPLSUBSET) Remotesystem ===> CICS region for shipped DPL request Remotename ===> Program name in remote CICS region Transid ===> Tra\id for remote CICS to attach Rsl ===> Resource security value (0-24,PUBLIC,blank) Dynamic ===> NO Dynamic routing (NO, YES) Concurrency ===> N/A Concurrency (N/A, QUASIRENT, THREADSAFE)

� �Figure 300. New Program Definit ion Panel

A.3.3 File Definition PanelThe FILEDEF Create panel (Figure 301 on page 261 and Figure 302 on page 261)now has four additional fields that support CFDTs.

• CFDTPOOL - If the table is defined with TABLE(CF), you must specify thename of the CFDT pool containing the CFDT to which the file refers.

• TABLENAME - You can specify the name of the CFDT accessed through thefile definition.

• UPDATEMODEL - You can specify the type of locking model to be used for aCFDT.

• LOAD - You can specify whether the CFDT is to be loaded from a sourcedata set when first opened.


� �---------------- Create File Definition for SCSPLEX Page 2 --------------------COMMAND ===> Name CCCCC Version 0

Remote Attributes Remotename ===> ACCUNTDB Remote file name RemoteSystem ===> PFA1 SYSIDENT for Remote System

Remote and CF Datatable Parameters Recordsize ===> 30 Record size (1 - 32767, blank) Keylength ===> 6 Key length (1 - 255, blank)

(1 - 16 for CF Tables)Initial Status Status ===> ENABLED Status (ENABLED,DISABLED,UNENABLED) Opentime ===> STARTUP Open time (FIRSTREF, STARTUP) Disposition ===> SHARE File disposition (SHARE, OLD)

NSR Buffers Databuffers ===> 9 Number of data buffers (2-32767, blank) Indexbuffers ===> 8 Number of index buffers (1-32767, blank)

� �Figure 301. New File Definit ion Panel (2)

� �---------------- Create File Definition for SCSPLEX Page 3 --------------------COMMAND ===> Name CCCCC Version 0

Datatable Parameters Table ===> NO Data table type (NO, CICS, USER, CF) Maxnumrecs ===> 10000 Max entries in data table ...

(NOLIMIT or 1-99,999,999)

CF Datatable Parameters CFDTpool ===> Name of coupling facility data table pool Tablename ===> Data table name Updatemodel ===> LOCKING Update model (LOCKING or CONTENTION) Loadtype ===> NO Whether file loads table (YES or NO)

Record Format Recordformat ===> FIXED Record format (VARIABLE, FIXED)

� �Figure 302. New File Defintion Panel (3)

A.3.4 Document Template Definition PanelThe DOCDEF Create panel (Figure 303 on page 262) is a new function enablingyou to define document HTML templates. Document templates allow you toperform variable substitution on documents in a manner similar to that done byBMS for 3270 screens.


� �------------- Create Document Template Definition for SCSPLEX -----------------COMMAND ===> Name ===> TEMPLT1 Version ===> 0 Description ===> RESGROUP ===> User Data ===>

FULL TEMPLATE NAME Templatename ===> TESTTMP ASSOCIATED CICS RESOURCEFile ===> Name of fileTSqueue Name of temporary storage queue

===>TDqueue ===> Name of transient data queueProgram ===> Name of programExitpgm ===> URM1 Name of exit program

PARTITIONED DATA SETDDname ===> DD name of partitioned datasetMembername ===> Name of member in partitioned dataset

� �Figure 303. New Document Template Definit ion Panel

A.3.5 Global Enqueue Model Definition PanelThe new ENQMDEF Create panel (Figure 304) enables you to define an enqueuemodel.

� �----------- Create Global Enqueue Definition for SCSPLEX Page 1 ---------------COMMAND ===>

Name ===> Version ===> 0Description ===>RESGROUP ===>User Data ===>

Enqscope ===>Status ===> ENABLED Enabled | DisabledEnqname ===>

===>===>===>===>

� �Figure 304. New Enqueue Model Definit ion Panel

A.3.6 Process Type Definition PanelThe new PROCDEF Create panel (Figure 305 on page 263) enables you to definea CICS BTS process type. A CICS BTS process is a collection of one or moreBTS activities.


� �----------- Create CICS BTS ProcessType Definition for SCSPLEX ----------------COMMAND ===> Name ===> Version ===> 0 Description ===> RESGROUP ===> User Data ===>

Status ===> ENABLED Enabled|Disabled File ===> File name Auditlog ===> Name of Audit log Auditlevel ===> OFF Off|Process|Activity|Full

� �Figure 305. New Process Type Definit ion Panel

A.3.7 Request Model Definition PanelThe new RQMDEF Create panel (Figure 306) enables you to define a requestmodel.

� �--------------- Create Request Model Definition for SCSPLEX -------------------COMMAND ===>

Name ===> Version ===> 0 Description ===> RESGROUP ===> User Data ===>

OMGModule ===> <IIOP Module Name

OMGInterface ===> IIOP Interface Name OMGOperation ===> IIOP Operation Name Transid ===> Transaction id� �

Figure 306. New Request Model Definit ion Panel

A.3.8 TCP/IP Service Definition PanelThe new TCPDEF Create panel (Figure 307 on page 264) enables you to define aTCP/IP service.


� �-------------- Create TCP/IP Service Definition for SCSPLEX -------------------COMMAND ===> Name ===> Version ===> 0 Description ===> RESGROUP ===> User Data ===>

Urm ===> Name of user replaceable module Portnumber ===> 00000 Port number for this service (1-32767) Certificate HFS pathname of certificate

===> Status ===> OPEN Initial status of service (OPEN, CLOSED) SSL ===> NO Use of SSL (NO, YES, CLIENTAUTH) Transaction ===> Transaction Id to process this service Backlog ===> 00001 Requests queued before rejection (0-32767) TSQprefix ===> Prefix for temporary storage queues IPaddress ===> IP address� �

Figure 307. New TCP/IP Service Definit ion Panel

A.3.9 Temporary Storage Model Definition PanelThe new TSMDEF Create panel (Figure 308) enables you to define a temporarystorage model.

� �----------------- Create TS Model Definition for SCSPLEX ----------------------COMMAND ===> Name ===> Version ===> 0 Description ===> RESGROUP ===> User Data ===>

Prefix ===> Prefix for TS queues Location ===> AUXILIARY TS queue in MAIN or AUXILIARY storage

Recovery ===> NO Recoverable TS queue (YES, NO)

Security ===> NO Security checking on queue (YES, NO)

Pool name ===> Shared TS pool name

Remote system ===> Remote system name Remote prefix ===> Prefix used on remote system� �

Figure 308. New Temporary Storage Model Definit ion Panel


Appendix B. Special Notices

This publication is intended to help customers implementing CICS TransactionServer for OS/390 Version 1 Release 3 or planning migration from earlierreleases. The information in this publication is not intended as the specificationof any programming interfaces that are provided by CICS Transaction Server forOS/390 Version 1 Release 3. See the PUBLICATIONS section of the IBMProgramming Announcement for CICS Transaction Server for OS/390 Version 1Release 3 for more information about what publications are considered to beproduct documentation.

References in this publication to IBM products, programs or services do notimply that IBM intends to make these available in all countries in which IBMoperates. Any reference to an IBM product, program, or service is not intendedto state or imply that only IBM′s product, program, or service may be used. Anyfunctionally equivalent program that does not infringe any of IBM′s intellectualproperty rights may be used instead of the IBM product, program or service.

Information in this book was developed in conjunction with use of the equipmentspecified, and is limited in application to those specific hardware and softwareproducts and levels.

IBM may have patents or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to the IBM Director ofLicensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact IBM Corporation, Dept.600A, Mail Drop 1329, Somers, NY 10589 USA.

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

The information contained in this document has not been submitted to anyformal IBM test and is distributed AS IS. The information about non-IBM(″vendor″) products in this manual has been supplied by the vendor and IBMassumes no responsibility for its accuracy or completeness. The use of thisinformation or the implementation of any of these techniques is a customerresponsibility and depends on the customer′s ability to evaluate and integratethem into the customer′s operational environment. While each item may havebeen reviewed by IBM for accuracy in a specific situation, there is no guaranteethat the same or similar results will be obtained elsewhere. Customersattempting to adapt these techniques to their own environments do so at theirown risk.

Any pointers in this publication to external Web sites are provided forconvenience only and do not in any manner serve as an endorsement of theseWeb sites.

Any performance data contained in this document was determined in acontrolled environment, and therefore, the results that may be obtained in other


operating environments may vary significantly. Users of this document shouldverify the applicable data for their specific environment.

Reference to PTF numbers that have not been released through the normaldistribution process does not imply general availability. The purpose ofincluding these reference numbers is to alert IBM customers to specificinformation relative to the implementation of the PTF when it becomes availableto each customer according to the normal IBM PTF distribution process.

The following terms are trademarks of the International Business MachinesCorporation in the United States and/or other countries:

The following terms are trademarks of other companies:

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Incorporated.

Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarksor registered trademarks of Microsoft Corporation.

PC Direct is a trademark of Ziff Communications Company and is usedby IBM Corporation under license.

Pentium, MMX, ProShare, LANDesk, and ActionMedia are trademarks orregistered trademarks of Intel Corporation in the U.S. and othercountries.

UNIX is a registered trademark in the United States and othercountries licensed exclusively through X/Open Company Limited.

Other company, product, and service names may be trademarks orservice marks of others.

ACF/VTAM AIXAPPN AS/400C S e t + + C + + / M V SC/MVS C/370CICS CICS OS/2CICS/ESA CICS/MVSCICS/VSE CICS/400CICS/6000 COBOL/370DATABASE 2 DB2DFSMS DFSMS/MVSDFSMSdfp DFSMSdssDFSMShsm DFSMSrmmES/3090 ES/4381ES/9000 ESA/390ESCON IBMIMS IMS/ESAMQSeries MVS/DFPMVS/ESA NetViewOpenEdition Operating System/2OS/2 OS/390RACF RAMACS/390 S/390 Parallel Enterprise ServerSystemView VTAM


Appendix C. Related Publications

The publications listed in this section are considered particularly suitable for amore detailed discussion of the topics covered in this redbook.

C.1 International Technical Support Organization PublicationsFor information on ordering these ITSO publications see “How to Get ITSORedbooks” on page 269.

• CICS Transaction Server for OS/390: Version 1 Release 2 ImplementationGuide, SG24-2234

• CICSPlex SM Business Application Services: A New Solution to CICSResource Management, SG24-5267

• Java Application Development for CICS: Base Services and CORBA ClientSupport, SG24-5275

• Revealed! CICS Transaction Gateway with More CICS Clients Unmasked,SG24-5277

• Business Process Model Implementation with CICS Business TransactionServices, SG24-5464

C.2 Redbooks on CD-ROMsRedbooks are also available on the following CD-ROMs:

CD-ROM Title Collection KitNumber

System/390 Redbooks Collection SK2T-2177Networking and Systems Management Redbooks Collection SK2T-6022Transaction Processing and Data Management Redbook SK2T-8038Lotus Redbooks Collection SK2T-8039Tivoli Redbooks Collection SK2T-8044AS/400 Redbooks Collection SK2T-2849RS/6000 Redbooks Collection (HTML, BkMgr) SK2T-8040RS/6000 Redbooks Collection (PostScript) SK2T-8041RS/6000 Redbooks Collection (PDF Format) SK2T-8043Application Development Redbooks Collection SK2T-8037

C.3 Other PublicationsThese publications are also relevant as further information sources:

• CICS System Definition Guide, SC33-1682

• CICS Resource Definition Guide, SC33-1684

• CICS Intercommunication Guide, SC33-1695

• CICS Messages and Codes, GC33-1694

• CICS Operations and Utilities Guide, SC33-1685

• CICS Supplied Transactions, SC33-1686

• CICS Recovery and Restart Guide, SC33-1698

• CICSPlex System Manager for MVS/ESA Concepts and Planning, GC33-0786


• CICSPlex System Manager for MVS/ESA Managing Business Applications,SC33-1809

• CICSPlex System Manager for MVS/ESA User Interface Guide, SC33-0788

• CICSPlex System Manager for MVS/ESA Operations Reference, SC33-0789

• CICSPlex System Manager for MVS/ESA Application Programming Interface,SC33-1430

• CICSPlex System Manager for MVS/ESA Resource Table Reference,SC33-1220

• CICSPlex System Manager for MVS/ESA Messages and Codes, GC33-0790

• OS/390 MVS Setting Up a Sysplex , GC28-1779

• OS/390 MVS Planning: Workload Management , GC28-1761


How to Get ITSO Redbooks

This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, andCD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.

• Redbooks Web Site http://www.redbooks.ibm.com/

Search for, view, download or order hardcopy/CD-ROMs redbooks from the redbooks Web site. Also readredpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbookssite.

Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapterswill be published this way. The intent is to get the information out much quicker than the formal publishingprocess allows.

• E-mail Orders

Send orders via e-mail including information from the redbook fax order form to:

• Telephone Orders

• Fax Orders

This information was current at the time of publication, but is continually subject to change. The latest informationfor customers may be found at http://www.redbooks.ibm.com/ and for IBM employees athttp://w3.itso.ibm.com/.

IBM Intranet for Employees

IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBMIntranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materialsrepository for workshops, presentations, papers, and Web pages developed and written by the ITSO technicalprofessionals; click the Additional Materials button. Employees may also view redbook, residency andworkshop announcements at http://inews.ibm.com/.

In United States: e-mail address: [email protected] North America: Contact information is in the ″How to Order″ section at this site:

http://www.elink.ibmlink.ibm.com/pbl/pbl/

United States (toll free) 1-800-879-2755Canada (toll free) 1-800-IBM-4YOUOutside North America Country coordinator phone number is in the ″How to Order″ section at this site:


United States (toll free) 1-800-445-9269Canada 1-403-267-4455Outside North America Fax phone number is in the ″How to Order″ section at this site:



IBM Redbook Fax Order Form

Please send me the following:

Title Order Number Quantity

First name Last name

Company

Address

City Postal code Country

Telephone number Telefax number VAT number

• Invoice to customer number

• Credit card number

Credit card expiration date Card issued to Signature

We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card notavailable in all countries. Signature mandatory for credit card payment.


List of Abbreviations

ACB access control block

ACP autoinstall control program

ACS automatic class selection

AOR application owning region

API application programming interface

APPC Advanced Program-to-ProgramCommunication

ARM automatic restart manager

AXM authorized cross-memory

BAS business application services

BDAM Basic Direct Access Method

BMP batch message processing

BMS basic mapping support

BTS business transaction services

BWO backup while open

CAS coordinating address space

CICS Customer Information Control System

CICS TS Customer Information Control SystemTransaction Server

CICSVR CICS VSAM Recovery

CF coupling facility

CFCC coupling facility control code

CFDT coupling facility data table

CFRM coupling facil ity resource management

CMAS CICSPlex SM address space

CMOS complementary metal oxidesemiconductor

CMT CICS-managed table

CORBA Common Object Request BrokerArchitecture

CPC central computer complex

CSA common system area

CSD CICS system definition

CWA common work area

CWI CICS Web Interface

DASD direct access storage device

DB2 DATABASE 2

DBCTL database control

DBRC database recovery control

DCE Distributed Computing Environment

DCT destination control table

DDL data definition language

DDM distributed data management

DFP data facility product

DML data manipulation language

DNS domain name server

DOR data owning region

DPL distributed program link

DSA dynamic storage area

ECB event control block

ECI external call interface

EIP EXEC interface program

ENF event notification facil ity

EOV end of volume

EPI external presentation interface

ESDS entry sequenced data set

ESSS environment services system services

EXCI external CICS interface

FOR fi le owning region

GEM global enterprise manager

GLUE global user exit

GRS generalized serialization services

GTF generalized trace facility

HFS hierarchical fi le system

HLL high level language

HTTP hypertext transfer protocol

IBM International Business MachinesCorporation

ICAPI Internet Connection ApplicationProgramming Interface

ICSS Internet Connection Secure Server

ICF Integrated Catalog Facility (VSAMcatalog)

ICMF Integrated Coupling Migration Facility

ICFRU Integrated Catalog Facility recoveryuti l i ty

IIOP Internet Inter-ORB Protocol

IMS Information Management System

IPL init ial program load

IRC interregion communication

IRLM IMS resource lock manager

ISC intersystem communication

ISMF Interactive Storage ManagementFacility


ISPF Interactive System Productivity Facility

IT information technology

JDK Java Development Kit

JCT journal control table

JVM Java virtual machine

KSDS key sequenced data set

LE Language Environment

LMAS local managed address space

LPA l ink pack area

LSR local shared resources

LUW logical unit of work

MAS managed address space

MPTN Multiprotocol Transport Network

MRO multiregion operation

MVS multiple virtual storage

NSR nonshared resources

OLTP online transaction processing

ONC RPC Open Network Computing RemoteProcedure Call

OO Object Oriented

ORB Object Request Broker

PDS partit ioned data set

PDSE partitioned data set extended

PLT program list table

PLTPI program list table post initialization

PLTSD program list table shutdown

POR printer-owning region

PTF program temporary f ix

QOR queue owning region

RACF Resource Access Control Facility

RBA relative byte address

RCT resource control table

RCDS recovery control data set

RDO resource definition online

RLS record level sharing

RMAS remote managed address space

RMF resource management facil i ty

RODM resource object data manager

ROR resource-owning region

RPC remote procedure call

RRDS relative record data set

RRMS recoverable resource managementservices

RTA real time analysis

SHCDS sharing control data set

SMS Storage Management Subsystem

SIT system initialization table

SMF system management facil i ty

SOS short on storage

SPI system programming interface

TCB task control block

TD transient data

TGMC Tivoli General Manager for CICS

TIOA terminal input output area

TOR terminal owning region

TPNS teleprocessing network simulator

TRUE task related user exit

TS temporary storage

TSOR temporary storage owning region

TST temporary storage table

TWA transaction work area

UMT user-managed table

UOW unit of work

UR unit of recovery

URM user replaceable module

VSAM Virtual Storage Access Method

WLM workload management

WWW World Wide Web

XCF cross-system coupling facility

XLN exchange lognames

XPI exit programming interface


Index

Aabend codes

AEZX 128AFCY 60ANQE 67

APAROW02759 15

BBAS

description 19program definit ion 161resource assignment 194resource description 181, 196SYSLINK definit ion 232transaction definit ion 162

BTSactivi ty 5, 124affinities 223audit log 126, 130BAPPL option 162CBAM transaction 134, 137compensation 134composite event 133container 125DFHATUP uti l i ty 131DFHINITIAL event 138dynamic routing of processes and activities 201event 125key features 5local request queue data set 127process 5, 124PROCTYP CICSPlex SM view 250PROCTYPD CICSPlex SM view 250PROCTYPS CICSPlex SM view 250programming model 5repository data set 125, 127routing of activities 141set 165, 201, 203

BTS commandsDEFINE PROCESS 131LINK ACTIVITY 124, 165RUN ACQPROCESS 133RUN ACTIVITY 124RUN ACTIVITY ASYNCHRONOUS 142, 165RUN ACTIVITY SYNCHRONOUS 165

BTS set 165, 201, 203Business Application Services

See BASbusiness transaction 5, 123Business Transaction Services

See BTS

CCFDT

access through file control API 40, 50CEMT support 51comparison with other techniques 56comparison with RLS 36comparison with UMT 39, 56contention model 47, 50, 51, 56cross-memory services support 42initial table load 48locking model 47, 50, 52, 55overview 36performance considerations 52pool 40, 45RACF protection 53RDO definitions 48server 40, 41server startup 43SPI support 51

cicsplexconfigurations 22maintenance point 20

CICSPlex SMAPI 19BAS 19batched repository-update facil ity 19CAS 18CMAS 18definition of CICSplex 17EUI 19MAS 17wlm algorithm specification 231

CICSPlex SM panelsCreate Trangroup 164Create WLM Specification 163Document Template Definition 262Enqueue Model Definition 262File Definition 261Process Type Definition 263Program Definition 161, 260Request Model Definition 263TCP/IP Service Definition 264Temporary Storage Model Definition 264Transaction Definition 162, 259Transaction Group Definition 259

CICSPlex SM viewsCFDTPOOD 251CFDTPOOL 251CFDTPOOS 251CICSRGN4 236CICSRGND 235, 236CICSSYS 161, 256CMDT2 248CMDT3 249


CICSPlex SM views (continued)CMDTD 248CMDTS 249DOCTEMP 254DOCTEMPD 254DOCTEMPS 255ENQMDL 252ENQMDLD 252ENQMDLS 252LOCTRAN 184LOCTRAND 256MAP 196, 218MLOCTRA4 253MLOCTRAD 253PROCTYP 250PROCTYPD 250PROCTYPS 250PROGDEF 214, 215PROGRAM 184PROGRAMD 255RASGNDEF 217RQMODEL 241RQMODELD 242RQMODELS 242TASK2 243TASK3 244TASK4 244TASK5 245TASK6 245TASK7 246TASK8 246TASK9 247TASKD 243TRANDEF 193, 215TRANGRP 219TSMODEL 236TSMODELD 237TSMODELS 237TSPIPS 240TSPIPSD 241TSPOOL 239TSQNAME 239TSQNAMED 240TSQNAMES 240TSQSHR 238TSQSHRD 238TSQSHRS 238WLMAOR 199WLMAWDEF 258WLMAWORD 258WLMAWORK 33, 164, 186, 257WLMDEF 185, 197, 219, 257WLMSPEC 185, 232, 257

CMASSYSIDNT 20CNMGMFHS 34CNMPROC 34CNMPSSI 34

combined hub and distributed model 157coupling facility structures

DFHCFLS 42DFHNCLS 75DFHXQLS 115for CICS BTS use 130for RRMS use 85

Ddata repository

backup 25, 26cross-release considerations 28migrat ion 21restore 26

DFHCFMN 42, 43, 45DFHLG520 131DFHLGCNV 131DFHNCMN 76DFHNCOPT 77distributed routing model 144dynamic routing

BTS processes and activities 201CICSPlex SM WLM limitations 160EXCI requests 214models 142new types 8, 141program link requests 171terminal-initiated START requests 189

EENQNAME 67, 68, 73ENQSCOPE 65, 66, 67, 68, 69, 70, 73, 74EUY#API3 26EXCI

callable API 79command level API 79no SYNCONRETURN option 80, 82, 84, 97, 99, 107,

108, 113SYNCONRETURN option 79, 81, 82, 84, 97, 113

EYU9XDUT 21EYU9XLOP 141, 144, 170EYUDREP 25EYUPARMS 20

Gglobal user exits

XDTAD 54XDTLC 54XDTRD 53XNQEREQ 67, 69, 70XNQEREQC 69, 70

Hhub model 142


IIEALIMIT 44IEFUSI 44informal shared data 36, 37IXCMIAPU utility 42, 75, 130

Mmessages

DFHCFnnnn 41DFHFC7130 60DFHRX0101 85DFHRX0104 85DFHRX0105 85DFHRX0106 85DFHRX0107 85DFHSH0109 127EYUXL0008 170

migrat iondata repository 21maintenance point 20

Nnamed counter 75

Ooriginal data table support 35

PPTF

OW15975 15UW05554 15UW40778 14UW40779 14UW91119 15UW91120 15

RRACF classes

FACILITY 53FCICSFCT 53SCICSTST 122

RDO resource objectsENQMODEL 66, 67JOURNALMODEL 126, 131PROCESSTYPE 126TSMODEL 118

region typesrequesting 142routing 142target 142

RODM 34root activity 125routing programs

COMMAREA passed 151, 155

routing programs (continued)distr ibuted 148dynamic 144

RRMScomponents 80ISPF panels 98setup 85SRRBACK command 81SRRCMIT command 81

Sshared data table support 35SIT parameters

DSRTPGM 144, 148, 170, 186DTRPGM 144, 145, 149DTRPROG 186GRPLIST 74RRMS 84WEB 117

spanned UOW 80, 82

Ttemporary storage

cross-memory services support 115long queue names 121, 122QNAME 121QUEUE 121queue sharing 115server 117TSMODEL 117, 118, 119, 120TST migration to RDO 119

Uunit of recovery 99, 100, 101, 102, 106, 107, 108, 109

Wworkload management

affinity management 223BTS processes and activities 201EXCI requests 214goal mode 224migration considerations 33MVS definitions 224program link requests 171service class 224terminal-initiated START requests 189

Index 275

ITSO Redbook Evaluation

CICS Transaction Server for OS/390: Version 1 Release 3 Implementation GuideSG24-5274-00

Your feedback is very important to help us maintain the quality of ITSO redbooks. Please complete thisquestionnaire and Fax it to: USA International Access Code + 1 914 432 8264 or:

• Use the online evaluation form found at http://www.redbooks.ibm.com• Send your comments in an Internet note to [email protected]

Which of the following best describes you?__Customer __Business Partner __Solution Developer __IBM employee__None of the above

Please rate your overall satisfaction with this book using the scale:(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)

Overall Satisfaction ____________

Please answer the following questions:

Was this redbook published in time for your needs? Yes____ No____

If no, please explain:_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

What other redbooks would you like to see published?_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

Comments/Suggestions: (THANK YOU FOR YOUR FEEDBACK!)_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________


SG24-5274-00Printed in the U.S.A.

CIC

S T

ransaction Server for O

S/390: V

ersion 1 Release 3 Im

plementation G

uideS

G24-5274-00IBML

ibml - lightyear consultinglightyr.com/redbooks/sg245274 - cics ts v1 r3.pdf · ibml cics...

Documents