Xpediter/cics Advanced Configuration Guide

Transcript

Xpediter/CICS Advanced Configuration Guide Release 17.02 2 Xpediter/CICS Advanced Configuration Guide Please direct questions about Xpediter/CICS or comments on this document to: Compuware Customer Support https://go.compuware.com/ This document and the product referenced in it are subject to the following legends: Copyright 1996-2017 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States. U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Compuware Corporation license agreement and as provided in DFARS 227.7202-1(a) and 227.72023(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable. Compuware Corporation. This product contains confidential information and trade secrets of Compuware Corporation. Use, disclosure, or reproduction is prohibited without the prior express written permission of Compuware Corporation. Access is limited to authorized users. Use of this product is subject to the terms and conditions of the user’s License Agreement with Compuware Corporation. Xpediter, Code Coverage, File-AID, Abend-AID, FrontLine, Compuware Shared Services, and Topaz Workbench are trademarks or registered trademarks of Compuware Corporation. IBM, CICS, DB2, IMS, MVS, and z/OS are trademarks of International Business Machines Corporation. Adobe® Reader® is a trademark of Adobe Systems Incorporated in the United States and/or other countries. All other company and product names are trademarks or registered trademarks of their respective owners. Doc. JULY2017 June 27, 2017 3 Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Notation Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Customer Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Information for Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Enabling Debugging Across Multiple-LPARs in a CICSPlex . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Configuration Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Installing and Customizing Terminate Inactive Debugging Sessions Support . . . . . . . . . . . . 13 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Compiling and Binding C Test Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Installing and Customizing the Batch Interface to Xpediter/CICS NEWCOPY . . . . . . . . . . . . 17 Additional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Implementing Support for the DB2 File Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Installing Xpediter/CICS Diagnostic Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Implementing the File Utility Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Implementing a File Utility Security Exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Error Handling and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Abends (Program Check/Abnormal Termination) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Handle Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 DBUGFILE Link-Edit Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 User Authorization Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 User Authorization Approval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Debugging the File Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Implementing the Memory Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Implementing the Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Testing the Memory Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4 Xpediter/CICS Advanced Configuration Guide Changing Data on Password-Protected Screens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Implementing the IMS File Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Configuring the Script Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Configuring the File Utility Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 XLOG Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Xpediter/CICS Not Active. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Xpediter/CICS Active, File Utility Audit Trail Not Active . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Xpediter/CICS Active, File Utility Audit Trail Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Entry Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Dataset Heading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Entry Headings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Closing the Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Dataset Service Request Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Dataset Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DL/I Segment Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 DB2 Row Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Configuring Xpediter with Language Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Setting Run-Time Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Software-Raised Error Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Amode Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Installing and Customizing the Remote Operations Command Interface . . . . . . . . . . . . . . . 61 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Specifying Xpediter Service Provider Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Xpediter Service Provider PROC and JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Configuring Restricted Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Configuring Automatic Session Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Configuring the DB2 Format Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 5 DBSQLUTL Utility Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 COPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 DELETE (DEL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 DIRECTORY (DIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 FORMAT (FOR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 INITIALIZE (INIT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 REORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 DBSQLUTL Format Utility Dataset Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring Intercommunication Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Installing in a Static Routing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Installing in a CPSM Dynamic Routing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Installing Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Installation in a Non-CPSM Dynamic Routing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Defining and Displaying User-Defined DSECTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Adding the User DSECT File to CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Configuring for System Currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Roles Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 PARMLIB Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 General Guidelines for PARMLIB Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 General Guidelines for PARMLIB Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Standard Global Table DBUGGBL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Production Global Table DBUGGBLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Default Member XDGB00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Default Member XVGB00. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Methods of Specifying and Updating Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 CMSC PARMLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Updating the Xpediter/CICS Parameters While CICS is Active. . . . . . . . . . . . . . . . . . . . . 140 Assembling DBUGGBL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Creating Additional Members for Region Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Creating Index Member XD$$00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Xpediter/CICS Index Member Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Xpediter/CICS Index Member Migration Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 DBPA Input Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 DBPA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Trap Summary Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Monitor Exceptions Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 CSECT Exclusions Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 6 Xpediter/CICS Advanced Configuration Guide Storage Protection and System Labels Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Operational Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Xpediter Service Provider Operator Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 STATUS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 DUMP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 SHUTDOWN Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 INITTCP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SHOWTCP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 TERMTCP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Canceling AID Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Suppressing System Dumps Resulting from ASRA and ASRB Abends . . . . . . . . . . . . . . . . . . . 155 Product Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Single Point Product Startup and Shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Using the Batch Interface to Xpediter/CICS NEWCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Batch Interface to Xpediter/CICS NEWCOPY Usage of the Xpediter TP Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Batch Interface to Xpediter/CICS NEWCOPY JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Miscellaneous Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Support for CICS Dynamic LIBRARY Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 DASD Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Minimizing CPU Consumption When Using Xpediter/Code Coverage . . . . . . . . . . . . . . . . . . 160 CICS SIT Parameters Affecting CPU Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Xpediter/CICS Global Table Parameter Affecting CPU Consumption . . . . . . . . . . . . . . . 160 Xpediter/Code Coverage Global Table Parameter Affecting CPU Consumption . . . . . . . 160 Topaz Workbench in a CPSM CICSPlex Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Examples of CPSM CICSPLEX Configurations Now Supported . . . . . . . . . . . . . . . . . . . . 162 7 Introduction This manual supplements the Xpediter/CICS Installation Guide, providing further customization instructions and reference information. Overview This document is intended to guide you through any additional tasks involved in installing/updating, configuring, deploying, and troubleshooting Xpediter/CICS that are not covered in the Xpediter/CICS Installation Guide. Alerts The alerts found in this Guide include: A note or tip providing additional information. Information important to remember. Caution. Failure to follow these instructions can cause serious problems. Additional Resources Refer to these other sources of information on Xpediter/CICS. Related Publications • • • • • • • Compuware Installer Mainframe Installation and Configuration Guide Xpediter/CICS Installation Guide Xpediter/CICS Release Notes Xpediter/CICS User Guides for Assembler, C, COBOL, or PL/I Xpediter/CICS Reference Manual Xpediter/CICS Quick Reference Xpediter/CICS Messages and Codes. Online Documentation The Xpediter/CICS product installation package does not include the product documentation. Access the Xpediter/CICS documentation from the Compuware FrontLine customer support website at https://go.compuware.com in the following electronic formats: • Release Notes in HTML format • Product manuals in PDF format 8 Xpediter/CICS Advanced Configuration Guide • Adobe PDF index file (PDX file) • Product manuals in HTML format. The product documentation is available for viewing or downloading: • View PDF files with the free Adobe Reader, available at http://www.adobe.com. • View HTML files with any standard web browser. Notation Rules Syntax diagrams define primary command syntax. A parameter is either a keyword or a variable. All KEYWORDs are shown in uppercase characters and must be spelled exactly as shown. You cannot substitute another value. If any part of a KEYWORD is shown in lowercase characters, that part is optional. Variables are user-specified values and are printed in lowercase italics. For example, dataset-name indicates you are to substitute a value. The syntax for commands is described in diagrams that help you visualize parameter use. The following example shows a command and a parameter: Read the diagrams from left to right and from top to bottom. These symbols help you follow the path of the syntax: indicates the beginning of a statement. indicates the statement is continued on the next line. indicates the statement is continued from the previous line. indicates the end of a statement. Required parameters appear on the horizontal line (the main path). Optional parameters appear below the main path. Default parameters appear above the main path and are optional. The command executes the same regardless of whether the default parameter is included. Vertically stacked parameters are mutually exclusive. If you must choose a parameter, one item of the stack appears on the main path. If the parameters are optional, the entire stack appears below the main path. If a parameter in a stack is the default, it appears above the main path. Introduction 9 If the same parameters are used with several commands, their syntax may be documented in a separate diagram. In the command syntax, these common parameters are indicated with separators before and after the parameter name. An arrow returning to the left indicates a repeatable item. If the arrow contains a comma, separate the repeated items with a comma. Customer Support Compuware provides a variety of support resources to make it easy for you to find the information you need. Compuware FrontLine Customer Support Website You can access online information for Compuware products via our FrontLine customer support website at https://go.compuware.com. Compuware FrontLine provides access to critical information about your Compuware products. You can review frequently asked questions, read or download documentation, access product fixes, or email your questions or comments. The first time you access Compuware FrontLine, you are required to register and obtain a password. Registration is free. Contacting Customer Support Phone • USA and Canada: 1-800-538-7822 or 1-313-227-5444. • All other countries: Contact your local Compuware office. Contact information is available at https://go.compuware.com. Web You can report issues via the Quick Link Create & View Support Cases on the Compuware FrontLine home page. Please report all high-priority issues by telephone. Mail Compuware Customer Support Compuware Corporation One Campus Martius Detroit, MI 48226-5099 Corporate Website To access Compuware’s site on the Web, go to http://www.compuware.com. The Compuware site provides a variety of product and support information. 10 Xpediter/CICS Advanced Configuration Guide Information for Customer Support If problems arise, please check your manual for assistance. If problems persist, please obtain the following information before calling Compuware for assistance. This information will help determine the exact cause of the problem as quickly as possible. 1. Identify the release number of Compuware product(s) in use. 2. Identify the operating system. 3. Identify the release of CICS Transaction Server that is being used. 4. If an abend occurs, note the displacement and the module in which it occurs. If possible, obtain a copy of the system dump. 5. Note the sequence of steps (including all commands issued) that resulted in the problem. Also note any variable data types and programming languages involved. 6. To receive product fixes electronically, be ready to provide your email address. 11 Enabling Debugging Across Multiple-LPARs in a CICSPlex The Xpediter Service Provider requires the Xpediter TP configuration dataset (TPCONFIG) to identify all of the other Service Providers, in other LPARs, that are to share CICSPlex information. Xpediter/CICS also requires TPCONFIG to identify all the CICS regions that should be contacted by the Batch Interface to CICS NEWCOPY. Roles Involved The following person is required: • Xpediter/CICS Installer. Configuration Considerations If your configuration file is on shared DASD that can be accessed by all LPARS, only one dataset with one member is required. The structure of entries within a member is such that one member may provide all of the necessary information for all Xpediter Service Providers and the Xpediter/CICS Batch Interface to CICS NEWCOPY. However—particularly for the Batch Interface to CICS NEWCOPY—you may find it easier to have multiple members in one dataset, or even multiple datasets. TPCONFIG should have its access security set so that all users can read it, but it can be updated only by those to whom you have granted edit access. TPCONFIG does not have to be in PDSE format, however a PDSE is recommended to avoid compression issues if you frequently modify the member(s). An example of a TPCONFIG member is provided in SMXDSAMP member MBRTPCNF. Task 1.1 Create and Use TPCONFIG 1. Edit and submit the sample JCL member JCLTPCNF to allocate TPCONFIG and copy the sample configuration member. 2. Customize TPCONFIG to your installation needs. Task 1.2 Specify Service Provider Communication Parameters The Xpediter Service Provider uses TCP to communicate to other Service Providers. Within the XDSSPROC JCL: 1. Specify the TPCONFIG dataset name in the TPCONFIG DD statement. 2. Specify the TPCONFIG member in the MEMBER parameter. 3. Specify the Port Number for this instance of the Service Provider in the PORT parameter. 1 12 Xpediter/CICS Advanced Configuration Guide 4. Add an entry to the TPCONFIG member for each instance of the Service Provider that should be connected. See SMXDSAMP member CFGXDSS for an example XDSS entry. Your TCP Systems Programmer can provide you with a Port Number and either a Domain Name or an IP Address for each instance of the Service Provider that you create. The Xpediter Service Provider can be executed as a started task or as a batch job. If the Service Provider is started during the IPL process and gains control before TCP/IP has started, then the TCP link between Service Providers will not be established automatically, and an error message (XSP3002E DBUGTCP cannot locate TCP/IP) will be written to the Service Provider JESLOG. If this scenario occurs, you can issue new Operator Command INITTCP to manually establish the TCP link between Service Providers after TCP/IP has been started. 13 Installing and Customizing Terminate Inactive Debugging Sessions Support If an Xpediter/CICS debugging session is inactive for a preset time interval, it can be automatically terminated to free up resources. Program DBUGXTMO determines whether a session is inactive and, if so, causes the session to be terminated. Roles Involved The following person is required for this milestone: • CICS Administrator. Program DBUGXTMO is started, via Interval Control, by executing transaction XTMO (or a user defined transaction specified in the XTMO global parameter) every n minutes. The number of minutes is controlled by global parameter XTMOCHK. The length of time, in minutes, before a session is considered inactive is controlled by global parameter XTMOINT. When DBUGXTMO executes, it checks all Xpediter/CICS debugging sessions that are running. Each session's last activity time is compared against the current time, and if this interval exceeds the setting of XTMOINT, the session is terminated. By default, this feature is disabled because the default values of XTMOCHK and XTMOINT are both zero. The feature remains disabled if the value of either parameter is zero. Transaction XTMO is started whenever Xpediter/CICS is started in a region. Refer to Parameter List for more information on XTMO and the XTMOCHK and XTMOINT parameters. If you modify and assemble program DBUGGBL, you must either restart CICS or use XPOF to stop Xpediter/CICS so the new version will be started the next time someone uses the XPED, XPRT, or XPSP transaction. If you use an XDGBxxxx member in the CMSC PARMLIB to modify these parameters, you can simply use the XSIT transaction to cause the new parameter values to take effect and, if specifying nonzero values for XTMOCHK and XTMOINT, you must then use the XTMO transaction from a terminal to start XTMO. Tasks Complete the following tasks to install and configure Xpediter/CICS Terminate Inactive Debugging Sessions support. Task 2.1 Establish XTMO Execution Interval Edit the PARMLIB member, specifying the following KEYWORD=value pair: XTMOCHK=minutes where minutes is the desired interval between executions of XTMO. Task 2.2 Establish Session Timeout Value Edit the PARMLIB member, specifying the following KEYWORD=value pair: 2 14 Xpediter/CICS Advanced Configuration Guide XTMOINT=minutes where minutes is the desired time limit for inactive session termination. 15 Compiling and Binding C Test Programs Demonstration programs for C are provided with Xpediter/CICS. Complete the task below to compile and bind those programs for use. Roles Involved The following person is required for this milestone: • Xpediter/CICS Installer. Background The C demonstration programs consists of the following load modules: • • • • CWDEMC – Main program (includes Assembler and C external subroutines) CWDYNC – A fetchable C subroutine CWDLLC – A C DLL subroutine CWDEMZCH – Optional main program. These modules are built using the following SMXDSAMP source members: • • • • • • • • • • • CWDEMC – C main source CWDEMDEF – C defines CWDEMPRO – C function prototypes CWDEMTYP – C typedefs CWDEMWS – C working storage (global variable declarations) CWDLLC – C DLL subroutine source CWDYNC – C fetchable subroutine source CWLESUBA – Assembler subroutine source CWSUBC – C subroutine source CWTBRATE – C Employee Rate Table CWDEMZCH – Optional main source. CWLESUBA, CWSUBC, CWDYNC, and CWDLLC all perform the same function. CWLESUBA and CWSUBC are both statically bound in module CWDEMC. CWDYNC is a separate module that is fetched and called. CWDLLC is a separate module that it dynamically bound at runtime. In addition, the following SMXDSAMP members are used to build the C demo programs: • CDEMOBLD – Build JCL • CDEMOLNK – Link-edit control • CZOSOPTS – Compile options member for the IBM z/OS C Compiler. Task 3.1 Build the C Demo Programs The C demo programs should be built as follows: 1. If you do not have a source listing file in which to place the program listings, allocate and initialize one now. 2. Allocate a private library and copy CDEMOBLD into it. Compuware suggests a dataset name of the form: 3 16 Xpediter/CICS Advanced Configuration Guide your-hlq.CDEMO 3. Edit member CDEMOBLD in your private library. a. Add a jobcard that conforms to your installation requirements. b. Change the TGTHLQ= statement to specify the high-level qualifier of the target datasets, for example, TGTHLQ=your-hlq This will create the following datasets: • your-hlq.OBJECT (temporary) • your-hlq.DEFSD (temporary) • your-hlq.LOAD (permanent) If you already have a PDSE library that you want to use, delete the SYSLMOD DD statement and change the SYSLMOD DD statement in the LINK step to reference that library instead. c. Change the SAMPLIB= statement to specify the full name of the SMXDSAMP library built during the SMP/E install process. d. Verify and, if necessary, change the CBC= and CEE= statements to ensure that they specify the C compiler and LE library high-level qualifiers at your installation. e. Change the CICSHLQ= statement to specify the high-level qualifier of the CICS datasets at your installation. f. Change the CXLIB= statement to specify the full name of the Compuware Shared Services SMP/E target library. g. Finally, change the DDIO= statement to specify the full name of your DDIO listing file. h. Submit the job. 4. Ensure that you have defined transaction XCCC and programs CWDEMC, CWDYNC, and CWDLLC to your CICS region. (See SMXDSAMP members CSDXDTRN and CSDXDPRG for sample transaction and program definitions.) 5. Add your-hlq.LOAD dataset to the DFHRPL concatenation in your CICS region or copy the load modules to an existing load library that is already in that concatenation. 6. If you created a new DDIO file in step 1, you will need to define it to your CICS region. You are now ready to test the C demo programs. 17 Installing and Customizing the Batch Interface to Xpediter/CICS NEWCOPY 4 The Batch Interface to Xpediter/CICS NEWCOPY allows batch compile and link jobs (or standalone linkedit jobs) to communicate with one or more CICS regions and request the NEWCOPY (PHASEIN) of the just-linked load module. Xpediter/CICS does not need to be turned on in a CICS region to use this feature. However, Xpediter/CICS transaction and program definitions must be installed in each CICS region referenced, and the Xpediter/CICS load library must be in the DFHRPL concatenation or in an installed LIBRARY. Sample JCL to merge into your existing compile and link (or standalone linkedit) procedure(s) is in SAMPLIB member JCLNEWC. Customize the dataset name in the TPCONFIG DD statement. This dataset was created in “Enabling Debugging Across Multiple-LPARs in a CICSPlex”. Then modify the two related parameters LMOD and CFGMBR to fit into your procedure(s). Specify the load module name of the newly-linked program in LMOD. Specify your TPCONFIG member name in CFGMBR. Depending on the requirements of your environment, CFGMBR could be a static value. Task 4.1 Add Necessary Definitions to CICS Regions The Batch Interface to Xpediter/CICS NEWCOPY uses either EXCI, MVS Sockets, or the CICS Web Interface (CWI) to communicate to CICS regions. Based on MVS configuration and current use (or lack of use) of TCP/IP, choose one communication method for each CICS region. EXCI is the most efficient and secure of the three communication methods. Compuware recommends that EXCI be used, if possible. To use the EXCI communication method, both the batch job and the CICS region must be in the same MVS image, unless the CICS region is running in a sysplex that supports cross-system MRO (XCF/MRO). If that is not the case, choose one of the other communications options for that CICS region. If you are not currently a user of MVS Sockets within the CICS region, Compuware recommends that you use the CICS Web Interface (CWI) communication method instead. Task 4.1.1 Choose a Communication Method Select your desired communications method, then follow the applicable instructions below to install the chosen communications method in each CICS region. Task 4.1.2 Install EXCI To define the CICS EXCI Connection and Sessions, see SMXDSAMP member CSDEXCI, which contains a sample RDO group. IBM requires that your CICS region SIT parameters include IRCSTRT=YES for EXCI to be used. The EXCI connection in CICS is defined as specific. Therefore, security is based on the batch job's userID. Ensure that RACF, or whatever external security manager you use, has appropriate entries for MRO logon and bind-time security for that userID. Refer to the chapter entitled “EXCI Security” in the CICS Transaction Server for z/OS External Interfaces Guide for additional information. Task 4.1.3 Install TCP/IP CICS Sockets (MVS Sockets) To install this communications method in your CICS region, refer to the IBM Communications Server manual IP CICS Sockets Guide. 18 Xpediter/CICS Advanced Configuration Guide If you already use this communications method within a CICS region, you may be able to use your current definitions (IP address and port number), depending on compatibility with your current security setup and listener. When using this communication method, no security checking is performed. If that is compatible with your current CICS listener, no new TCP/IP definitions are required; the region's existing IP address and port number can be provided when you add this region to the TPCONFIG member. If your current CICS listener has been customized such that the batch interface cannot use it, you must either define and start the IBM default listener on another port in this region, or use one of the other communication methods. If a new listener is used, see your MVS TCP/IP systems programmer for a port number to use. Task 4.1.4 Install CICS Web Interface (CWI) This communication method requires a CICS SIT setting, an RDO group, and at least one TCPIPSERVICE definition within the CICS region. • In the SIT, ensure option TCPIP is set to YES. • RDO groups installed must include DFHWEB. • The TCPIPSERVICE definition to be installed must be HTTP. Within that definition, the URM parameter should be DFHWBADX or a user-customized module based on DFHWBADX that supports the CWI standard URL. The SSL parameter must be NO. The AUTHENTICATE parameter must be NO. If you already have a TCPIPSERVICE definition installed in the CICS region that is compatible with the above criteria, no new TCPIPSERVICE definition is required. The existing TCPIPSERVICE port number can be provided when you add this CICS region to the TPCONFIG member. If you must define a new TCPIPSERVICE RDO entry, see your MVS TCP/IP systems programmer for a port number to use. Additional Considerations The TPCONFIG partitioned dataset member referenced in the batch JCL contains NEWC entries which specify which regions to be contacted and the communication method for each region. See SMXDSAMP member MBRTPCNF for example NEWC entries. Change the transaction code XPNC only if you also changed your definition in the corresponding CICS region. If you specify a transaction code other than CSMI on an EXCI entry, your transaction code will be ignored. The batch job executes program XPEDNEWC. That program produces a report with a result for each CICS region in the TPCONFIG member used. The return code from XPEDNEWC will also indicate the overall results: • Return code 00 indicates all CICS regions were successfully contacted and all NEWCOPY requests were successfully performed. • Return code 04 indicates some CICS regions could not be contacted (might not be "up"). • Return code 08 indicates NEWCOPY failed in one or more of the CICS regions that were successfully contacted. • Return code 12 indicates that a problem occurred while opening the TPCONFIG dataset, that no NEWC entries were in the specified member, or that the specified member name was not found. 19 Implementing Support for the DB2 File Utility 5 If your site uses DB2, Compuware recommends installation of the DB2 File Utility. The installation is performed in three stages: • Bind the plan • Establish DB2 authorization for XPED, XPRT, and XPSP transactions • Set DB2AUTH global parameter. Roles Involved The following person is required: • DB2 Administrator. Task 5.1 Bind the Plan The DBRM members for the DB2 File Utility have been updated in this release of Xpediter. The default bind package name has changed in this release to reflect the product code and release (MXD0170). Use the JCL supplied in member DBBIND10 to bind the plan used by the DB2 portion of the Xpediter/CICS File Utility, then grant EXECUTE authority of the plan to PUBLIC. 1. Modify the JCL in member DBBIND10 as described in the comments. 2. The JCL in DBBIND10 must be executed as an authorized DB2 user. Submit the JCL and ensure it completes successfully. 3. The plan bound above must be granted EXECUTION authority of PUBLIC by executing the following SQL statement using SPUFI (or whatever DB2 utility is used at your site): GRANT EXECUTE ON PLAN MXDPLAN TO PUBLIC If you changed the plan name in the JCL above, substitute that plan name in place of MXDPLAN before executing the SQL statement. Task 5.2 Establish DB2 Authorization for XPED, XPRT, and XPSP Transactions To enable the DB2 portion of the Xpediter/CICS File Utility, you must establish the necessary transaction authorizations by submitting revised DB2ENTRY RDO definitions. Ensure the PLAN parameter matches the plan name used to bind the plan in the previous section. The default in member CSDXDDB2 is MXDPLAN. You may need to modify the DB2ENTRY parameters in the RDO definitions provided in SMXDSAMP member CSDXDDB2. If so, do so before proceeding. 20 Xpediter/CICS Advanced Configuration Guide Task 5.3 Determine Setting for DB2AUTH PARMLIB Parameter Change Xpediter PARMLIB parameter DB2AUTH to the value listed in the table below that matches the applicable DB2 parameter: AUTHTYPE() DB2CONN and/or DB2ENTRY resource definition parameter. • Do not modify your DB2 setting. Set DB2AUTH to match your DB2 setting. • If you are using AUTH=(GROUP,,) or AUTHTYPE(GROUP), specify DB2AUTH=GROUP. Xpediter/CICS will behave as though DB2AUTH=NONE had been specified. Refer to the discussion at the end of these notes. • Using AUTH=(USERID,,) or AUTHTYPE(USERID) and the IBM DB2 sign-on exit DSN3@SGN is equivalent to using AUTH=(GROUP,,) or AUTHTYPE(GROUP). In this situation, Compuware also strongly recommends setting DB2AUTH to NONE—not USERID. These settings require Xpediter to examine external security blocks to create a list of resources the user is authorized to access. Compuware policy is to access individual security information only through published APIs. Attempting to support access at the group level would violate this policy and your site's security. Therefore, Xpediter cannot provide an accurate list of DB2 resources at this level, and Compuware strongly recommends setting DB2AUTH to NONE to allow DB2 authorization to manage access to DB2 resources. We regret any inconvenience this may cause. Table 1. Xpediter Global Parameter DB2AUTH Settings DB2AUTH DB2 Authorization ID Obtained by Xpediter Value NONE Xpediter makes no checks to determine whether the user is authorized to access the resource. When the resource is actually selected, DB2 will perform any necessary checking. This is the preferred setting for sites using USERID and GROUP authorization. USERID Xpediter uses eight-byte SNT USERID field. Compuware strongly recommends using NONE instead of USERID. See Notes above. GROUP Xpediter/CICS will behave as though DB2AUTH=NONE had been specified. See NONE description below and Notes above. USER Xpediter uses three-byte SNT operator ID field. TERM Xpediter uses terminal ID. TXID Xpediter uses transaction ID. SIGNID Xpediter uses CICS authorization ID value, which is from the DB2CONN SIGNID() parameter. STRING Xpediter uses value from DB2ENTRY AUTHID() parameter. Example 1 If you want to use USERID security: DB2CONN or DB2ENTRY AUTHTYPE (USERID) global table DB2AUTH=USERID Example 2 If you want to use TERM security: DB2CONN or DB2ENTRY AUTHTYPE (TERM) global table DB2AUTH=TERM Task 5.4 Allocate, Format, and Initialize the SQL Transfer File (DBCDEFSQ) Use the DBCDEFSQ SMXDSAMP member to allocate the Xpediter/CICS SQL transfer file, which enables you to save SQL calls generated by the DB2 File Utility and transfer them to other datasets. Implementing Support for the DB2 File Utility 21 This file may be shared across multiple regions on the same MVS image. Use SHAREOPTIONS (4 3) if sharing across multiple regions. 1. SMXDSAMP member DBCDEFSQ contains JCL that allocates a VSAM KSDS SQL file. Supply the volume serial, dataset name, and appropriate space parameters. 2. Add your job card and submit the JCL. 22 Xpediter/CICS Advanced Configuration Guide 23 Installing Xpediter/CICS Diagnostic Modules 6 If your site uses Abend-AID for CICS, you may want to install the Xpediter/CICS Diagnostic Modules into the Abend-AID for CICS server concatenation for DD FDBDRPL. This will enable Abend-AID to provide more comprehensive diagnostic information about Xpediter-generated abends such as STOR. Roles Involved The following person is required: • Abend-AID Installer. Task 6.1 Install Diagnostic Modules 1. Add the SMXDAAFX library name to the Abend-AID for CICS viewing server. 2. Place the SMXDAAFX library name in the concatenation for DD FDBDRPL, ahead of any other Abend-AID libraries. 24 Xpediter/CICS Advanced Configuration Guide 25 Implementing the File Utility Security Exit If your site uses an external security manager such as RACF, CA-ACF2, or CA-Top Secret, you may want to implement the Xpediter/CICS file security exit to ensure full security access to file resources. The File Utility Security Exit enhances outside security processes and protects areas not usually protected by other vendor's security packages. You can code macros and calls to your external security manager and use Compuware-supplied fields to access resources not traditionally protected by external security managers. The information provided here is important for system programmers who want to secure access to their files. The File Utility Security Exit is discussed in the following topics: • “Implementing a File Utility Security Exit” • “Error Handling and Recovery” • “Debugging the File Update Security Exit”. Roles Involved The following people are required: • Xpediter/CICS Installer • z/OS Security Administrator. Implementing a File Utility Security Exit Task 7.1 Implement a File Utility Security Exit There are sample members, described in Table 2, that are provided in CPWR.cMXD170.SMXDSAMP (where c represents the CICS release). Source members RACFEXIT and DBUGUSEC contain sample source code. Steps for implementing a security exit are described below. Table 2. Sample Source Members and Copy Books for File Security Exits Name Description RACFEXIT Sample source code for any external security managers compliant with RACROUTE and the SAF interface, such as CA-ACF2 and CA-TOP SECRET®. DBUGUSEC Sample source code for Xpediter/CICS security exit. DBSECBLK Copy code for the Xpediter/CICS security block. This block contains all necessary fields to determine what resource is being accessed, as well as the type of access being performed. DBUSERX Sample prologue and epilogue code that ensures clean entry and exit from the Xpediter/CICS security exit. Task 7.1.1 Choose Sample Exits Choose a sample program (RACFEXIT or DBUGUSEC) to code security exits for your site. Task 7.1.2 Assemble the Exit Assemble the exit provided in RACFEXIT or DBUGUSEC. Do not relink DBUGFILE at this point, because the code provided is identical to that linked into DBUGFILE during installation. 7 26 Xpediter/CICS Advanced Configuration Guide Task 7.1.3 Tailor the Exit Review the assembly. The assembled listing contains notes on coding conventions and using the security block. DBUGFILE runs as a non-terminal (asynchronous) task. As such, no TCTTE is provided by CICS for this task. To allow your external security manager to function properly, the TCAFCAAA field in the TCA of the DBUGFILE task is saved and replaced with the TCTTE address of the calling task’s terminal. Upon return from the security exit, the TCAFCAAA field is properly restored. The DBUGFILE security exit only appears to be running at a terminal. This allows your external security manager to properly handle resource checking. The File Security Exit is executed whenever the DBUGFILE program is invoked through the file utility. Secured access to a file resource can be validated prior to accessing that resource. Exit Points The File Security Exit determines whether a user has access to a file resource. Only two exit points are provided within the exit: AUTH and NOTAUTH. Authorized users will branch to the AUTH label if they can access the file resource being processed. Unauthorized users will branch to the NOTAUTH label if they cannot access the file resource or if an error that you wish to acknowledge occurs. Highlevel errors are handled by the calling code. For a list of these errors and the messages displayed when these conditions occur, see “Error Handling and Recovery”. Entry/Exit Codes The first line of code in your exit must be DBUSERX TYPE=INITIAL. This ensures that Xpediter/CICS establishes the proper entry conventions for the exit. Even though this is a command-level program, the DFHEIENT macro should not be coded, because all linkage is provided by the DBUSERX TYPE=INITIAL macro. The last line of code in your exit must be DBUSERX TYPE=FINAL to ensure that Xpediter/CICS establishes the proper exit conventions. All registers except 15 are saved before entry to the security exit and are automatically restored upon exit. It is unnecessary to save or restore registers. Control Blocks The following control blocks have been defined within the code provided by the DBUSERX TYPE=INITIAL macro. DBSECBLK This block defines all the fields you may use in this exit. Equates (EQU) are provided for many of the fields to provide easy access to the information supplied. It is considered a read-only block. All values are reestablished by the calling program, DBUGFILE, prior to invoking the security exit. Register 5 is the base register for this block. EIB The EXEC interface block layout is provided. Since the task is a non-terminal task, you should not refer to the EIB for any terminal related fields, which are provided in the DBSECBLK defined above. Register 8 is the base register for this block. Implementing the File Utility Security Exit 27 EIS The EXEC interface dynamic storage layout is also provided. Additional fields that you may require in the exit should not be defined in this block, but in the USERAREA area block described below. Register 9 is the base register for this block. USERAREA This block is a 1000-byte area, double-word aligned, where you may define additional fields as well as any areas required for your external security manager. You may modify this area, but its contents are not guaranteed to remain the same from one invocation of the exit to another. Register 6 is the base register for this area. Register Conventions Within your exit code, follow the register conventions listed in Table 3. Each register has a corresponding equate to simplify coding. The following table includes the equate associated with each register. Table 3. Exit Code Registers Register Associated Equate R0 Unused. R1 Unused. R2 Unused. R3 Unused. R4 Unused. R5 Base register for DBSECBLK. Do not modify. R6 Base register for USERAREA. Do not modify. R7 Base register for TCTTE. Do not modify. R8 First program base register. Do not modify. R9 Second program base register. Do not modify. R10 Base register for DFHEISTG. Do not modify. R11 Base register for EIB. Do not modify. R12 Base register for TCA. Do not modify. R13 Base register for CSA. Do not modify. R14 Linkage register. R15 Linkage register. Failure to follow these conventions may cause severe errors. Task 7.1.4 Run Security Exit Through IBM Command-Level Translator Translate the selected exit program using the IBM Command-Level Translator. See “Task 7.2.1 Assemble DBUGUSEC and Link-Edit DBUGFILE for Testing”. Task 7.1.5 Assemble RACFEXIT or DBUGUSEC Assemble the exit code you selected in “Task 7.1.1 Choose Sample Exits”. The sample exit code may have been RACFEXIT or DBUGUSEC. 28 Xpediter/CICS Advanced Configuration Guide Task 7.1.6 Link the Sample Program to Program DBUGFILE Link-edit load module DBUGFILE using the sample JCL provided in member USECLINK in SMXDSAMP. Specify the object library and test load library as instructed in SMXDSAMP member USECLINK. Link-edit your test version of DBUGFILE into a load library separate from your regular Xpediter/CICS libraries so if any errors are found, other users will not be affected. See “Task 7.2.1 Assemble DBUGUSEC and Link-Edit DBUGFILE for Testing”. Error Handling and Recovery Instructions for using Xpediter/CICS to debug your exit are covered in “Debug the File Update Security Exit”. If you elect not to use Xpediter/CICS to debug the security exit, the following conditions are handled automatically by DBUGFILE on behalf of the security exit. Abends (Program Check/Abnormal Termination) Program checks and abnormal termination are handled by a handle abend within DBUGFILE prior to invoking the security exit. The sequence is described below: 1. A dump is issued and sent to the CICS dump dataset. 2. A DBFX dump instructs you to refer to the previous dump for debugging information. 3. Xpediter/CICS terminates DBUGFILE gracefully. 4. The terminal displays the following error message: NOT AUTHORIZED - ERROR IN DBUGFILE SEC. EXIT. 5. The Xpediter/CICS session continues normally. Handle Conditions Conditions that can be captured and acted on by a handle condition statement are done in DBUGFILE prior to invoking the security exit. All conditions except PGMIDERR are handled as abends. The PGMIDERR occurs when you are accessing your external security manager and the program to which you are attempting to link is not defined to CICS or is disabled. The sequence is described below: 1. Xpediter/CICS terminates DBUGFILE gracefully, and no dump is created. 2. The terminal displays the following error message: NOT AUTHORIZED - SECURITY PKG NOT AVAILABLE. 3. The Xpediter/CICS session continues normally. DBUGFILE Link-Edit Failure If you elect to write your own security exit without link-editing the DBUGUSEC object module to the DBUGFILE load module, problems may occur. The sequence is described below: 1. Xpediter/CICS terminates DBUGFILE gracefully, and no dump is created. 2. The terminal displays the following error message: NOT AUTHORIZED - NO DBUGFILE SECURITY EXIT. 3. The Xpediter/CICS session continues normally. If you decide to write your own security exit, the object module must be accessible during the linkedit of DBUGFILE. Implementing the File Utility Security Exit 29 User Authorization Failure If you determine that the user is not authorized to access a file resource, branch to NOTAUTH in the security exit. The user will see the message NOT AUTHORIZED BY YOUR SYSTEM SECURITY. User Authorization Approval If the user is authorized to access a file resource, branch to AUTH in the security exit. Normal access of the resource through the file utility continues. Debugging the File Update Security Exit Task 7.2 Debug the File Update Security Exit DBUGFILE is a non-terminal task and requires a variation in the normal use of Xpediter/CICS. Treat DBUGFILE as a remote task and treat the security exit as a CSECT within DBUGFILE, using multiple CSECT support to debug it. Since you must access the file utility through DBUGFILE, you need two terminals for the debugging session. You may use physical or logical terminals. Logical sessions are denoted as TERMA or TERMB. TERMA is the session used to perform the actual debugging process, while TERMB is the session associated with accessing the file utility. Procedures for debugging the security exit are described in this section. Task 7.2.1 Assemble DBUGUSEC and Link-Edit DBUGFILE for Testing 1. Translate the program using the IBM Command-Level Translator. 2. Assemble the output produced by the Translator. The object module produced should go to an object library that you will be able to access when link-editing DBUGFILE. 3. Process the Assembler output using the Compuware Assembler language processor. This allows you to access your source listing through Xpediter/CICS. 4. Link-edit load module DBUGFILE. Use the sample JCL provided in member USECLINK in SMXDSAMP. Specify object library and test load library as instructed in samplib member USECLINK. Link-edit your test version of DBUGFILE into a load library separate from regular Xpediter/CICS libraries. If any errors are found, you will not affect other users. 5. Test your changes in a CICS test region. Verify that the library containing the new DBUGFILE linked in step 4 precedes your normal Xpediter/CICS load library. If you are going to debug using a CICS region that is already up, make DBUGFILE a NEWCOPY. Task 7.2.2 Establish a High Time-Out Factor for DBUGFILE (TERMA) 1. From a blank CICS screen, type XPSP 9.D and press Enter. This will take you directly to the DSECTs screen (9.D), where you may set the DBFLWAIT parameter in the global table to its maximum value for debugging purposes. 2. On the DSECTs screen, tab to the TABLE/AREA field and type DBUGGBL. Tab to the LABEL field and type DBFLWAIT. Press Enter to position the display at field DBFLWAIT in program DBUGGBL. 3. Tab to the hexadecimal field in the body of the screen following DBFLWAIT. This is a one-byte field (two hex digits). Write down this value so you can restore it later. Now overtype the field with x'44' to provide a 68 second wait factor and press Enter. Task 7.2.3 Select DBUGUSEC for Debugging (TERMA) 1. Type XPSP 2.6.1 on a blank CICS screen and press Enter. This will invoke Xpediter and display the List of CSECTs screen (2.6.1). 30 Xpediter/CICS Advanced Configuration Guide 2. Type DBUGFILE in the MODULE field and press Enter. 3. In the COMMAND field, type SEL DBUGUSEC and press Enter. The CSECT DBUGUSEC will now be the first listed, and YES will be displayed in its SELECTED field. Task 7.2.4 Set a Breakpoint in DBUGUSEC (TERMA) 1. Type STOP in the COMMAND field on the current screen. 2. Position the cursor at the MODULE field and type DBUGUSEC. 3. Press Enter. You should receive a message indicating the breakpoint was set. 4. To verify that you have source support and the breakpoint was set, type 2.L in the COMMAND field of the current screen. This will transfer you to the Source Listing screen (2.L). You can position to the breakpoint you have set by typing FIND STOP in the COMMAND field. Task 7.2.5 Establish a Trap for DBUGFILE (TERMA) 1. Type 1.6 in the COMMAND field on the current screen. This will take you to the Trap Summary screen (1.6) so that you can define a trap to intercept the breakpoint that was set in “Task 7.2.4 Set a Breakpoint in DBUGUSEC (TERMA)”. 2. Change the entry for your current terminal to all asterisks in the TERMINAL field. Change the TRANSACTION field to read DBFL (or the transaction code you have used in the Xpediter global table). This will ensure that you trap the breakpoint. 3. Type CWDBUG$ ON on the COMMAND line and press Enter to allow Xpediter/CICS to debug internal code. Task 7.2.6 Invoke DBUGFILE (TERMB) Switch sessions or go to a nearby terminal to be used as the terminal task using the Xpediter/CICS file utility. Sign on to CICS and access the file utility screen that you wish to use for testing your exit. The exit is invoked when the terminal appears to hang (clock will be displayed). You need to go back to TERMA to do the debugging. Task 7.2.7 Trap the Breakpoint (TERMA) Switch sessions or go to the terminal that you used to set the breakpoint in the security exit (TERMA). 1. Press PF2. This will change screens and allow the breakpoint to be intercepted. If you do not get a screen or message indicating that the breakpoint was intercepted, type =9.3 in the COMMAND field and press Enter. On the List All Tasks screen (9.3), select the entry shown for transaction DBFL-STOP. 2. Step through your code and debug the security exit as you would a normal CICS command-level Assembler program. When you have determined that things are functioning correctly, use the RESUME command to observe the results on TERMB. If necessary, repeat steps 1 through 7 until you are satisfied that your exit is functioning correctly. Task 7.2.8 Reset Time-Out Factor for DBUGFILE (TERMA) 1. When you are satisfied that your security exit is complete, either reset the time-out factor for DBUGFILE or recycle the CICS region. To reset the time-out value, type XPSP 9.D from a blank CICS screen associated with the region used for debugging (TERMA). 2. Type DBUGGBL in the TABLE/AREA field of the DSECTs screen (9.D) and type DBFLWAIT in the LABEL field. Press Enter. This will position you to the DBFLWAIT field within program DBUGGBL. 3. On the hexadecimal field in the body of the screen following DBFLWAIT, type in the value you saved previously and press Enter. This resets the DBFLWAIT time-out value. This hexadecimal field is a one-byte field (two hex digits). 4. Type CWDBUG$ OFF on the COMMAND line and press Enter to turn off internal debugging. Task 7.2.9 Remove Test Exit Either remove the test library from the DFHRPL concatenation or delete the test version of DBUGFILE from the test library. Implementing the File Utility Security Exit Task 7.2.10 Move Exit to Production (SMP/E USERMOD) Member USECUMOD in SMXDSAMP contains a sample SMP/E USERMOD to install your exit. Task 7.2.11 Implement Exit Either perform a NEWCOPY of DBUGFILE or cycle Xpediter or the CICS region to implement the production version of your file update security exit.s 31 32 Xpediter/CICS Advanced Configuration Guide 33 Implementing the Memory Update Security Exit Xpediter/CICS also offers a Memory Update Security Exit facility that complements the File Update Security Exit discussed in “Implementing the File Utility Security Exit”. Update security is implemented at the transaction level. You can set this form of security for a single transaction, for multiple transactions, or not at all (the default) by creating a Memory Update Security Exit and setting the UPDTSEC parameter in the Global Table to ON for any transaction level. Once Memory Update Security is set for a screen, you must enter a password before changes on the screen can be executed. If the password is invalid or not entered, all changes to the data areas of the screen are ignored, and a message is displayed indicating why the update was bypassed. CICS calls or external security manager calls cannot be made with this exit. This chapter discusses the following topics: • Implementing Memory Update Security Exits • Debugging the Memory Update Security Exit • Changing data on password-protected screens. This chapter is important for system programmers who want to secure access to memory areas of their applications. Roles Involved The following people are required: • Xpediter/CICS Installer • z/OS Security Administrator. Implementing the Update Security Exit Task 8.1 Implement the Memory Update Security Exit This facility allows you to provide security against memory updates on the following memory and file screens: • • • • • • • • • Memory Display (2.2) DSECTs (2.D) Edit CICS Dataset Record (5.1.3) Edit Queued Record (5.2.3) Edit Transient Data Queue Record (5.3.2) Edit DL/I Segment (5.4.4) Update MQ Queue Message (5.6.3) Memory Display (9.2) DSECTs (9.D). Compuware supplies a sample exit, DBUGPASS, in CPWR.cMXD170.SMXDSAMP (where c represents the CICS release). This dataset also includes member DBUGPASM, a macro that generates prologue and epilogue code for the exit DBUGPASS. Be sure to include this library when assembling your exit. 8 34 Xpediter/CICS Advanced Configuration Guide The system administrator provides the program code for validating the password in program DBUGPASS. The following three settings are valid: • Ignore the password and allow the update to occur. • Prohibit the update. • Allow the update to occur only when the password is valid and specified conditions are met (such as correct transaction ID or screen ID). Compuware recommends the following conditions for implementing and testing your update security exit: • Use a private object and load library for assembling and linking DBUGPASS. or • Either test in a region dedicated to your exclusive use or test at a time when other users are not accessing the region. If errors occur in this exit routine, sites may lose the use of Xpediter/CICS or, in extreme cases, suffer system outages. The following procedure implements the Memory Update Security Exit. Task 8.1.1 Specify Parameter to Enable Memory Update Security Exit Add an entry similar to the following to your XDGBxxxx member in the CMSC PARMLIB, specifying ON for the transaction level(s), XPED, XPRT, and/or XPSP, for which to invoke security: UPDTSEC=(ON,ON,ON) MEMORY UPDATE SECURITY For more details, see “DBPA Input Guidelines”. Although Compuware strongly recommends setting global parameter values in the CMSC PARMLIB, you can choose instead to directly modify values in the Xpediter global table as required, then reassemble and link edit it. Refer to “Assembling DBUGGBL” for more information. Task 8.1.2 Review Sample Source Review member DBUGPASS, provided in SMXDSAMP member, which contains sample source code for the exit. This member was used to create the current DBUGPASS during Xpediter/CICS installation. You do not need to run a CICS translator against it. Task 8.1.3 Assemble the Exit Module DBUGPASS Compuware supplies a macro, DBUGPASM, which is required to assemble the exit DBUGPASS. This macro is provided in SMXDSAMP member. Be sure to include this library in your SYSLIB DD when assembling your exit. Task 8.1.4 Determine Security Protocol at Your Site Make a copy of DBUGPASS and modify it to meet your site’s specifications. Note that this exit does not allow external security manager calls or CICS calls. A work area and data are provided for use when developing your security exit. Task 8.1.5 Relink DBUGPASS Relink program DBUGPASS. Verify that the program points to the object library containing the object module DBUGPASS output. Use the Compuware Assembler preprocessor to put the listing into a source listing file. Use Xpediter/CICS to test the exit. Member PASSLINK provided in SMXDSAMP member contains sample linkedit JCL for testing purposes. Implementing the Memory Update Security Exit 35 Task 8.1.6 Shut Off Xpediter/CICS Either shut down Xpediter by typing XPOF from a blank CICS screen and pressing Enter, or recycle the region. Task 8.1.7 Test Your Exit If the listing is not in a source file available to that region, reassemble the program so that the listing is available. Instructions for this step are in “Task 8.2 Test the Memory Update Security Exit”. Testing this exit can cause exit failure and cause the region to crash. Test this exit carefully before turning it over to the user community. Task 8.1.8 Move Exit to Production Move DBUGPASS from your test load library into the production load library. Member PASSUMOD provided in SMXDSAMP member contains a sample SMP/E USERMOD to install your exit. Task 8.1.9 Provide Passwords to Secured Users Testing the Memory Update Security Exit Task 8.2 Test the Memory Update Security Exit 1. Type XPSP DBUGPASS on a blank CICS screen and press Enter. The source listing for DBUGPASS will be displayed on the Source Listing screen (2.L). 2. Type CWDBUG$ ON on the COMMAND line and press Enter to allow Xpediter/CICS to debug internal code (for example, the security exit). 3. Display any of the screens selected for update security and begin testing your exit. If Xpediter stops at a breakpoint you set in DBUGPASS, the Assembler Break/Abend screen (2.20) will be displayed because the CWDBUG$ ON command was entered in step 2. Simply type =2.L on the COMMAND line and press Enter to transfer to the Source Listing screen (2.L). You can use any of Xpediter’s source-related features on this screen to debug your exit. 4. When you are done testing your exit, type RELEASE on the COMMAND line and press Enter to remove all breakpoints. 5. Type CWDBUG$ OFF on the COMMAND line and press Enter to shut off internal debugging. Changing Data on Password-Protected Screens Task 8.3 Change Data on Password-Protected Screens When update security is implemented, the following field is displayed on the screen: UPDATE PASSWORD: password where password is an eight-character non-displayed field for entering a password assigned by the system administrator. To update memory displayed on a screen for which update security is set, change the data on the screen and enter the password before pressing a PF or the Enter key. If the password is not entered, or is determined to be invalid by the update security exit program, all changes to the data area of the screen are ignored, and a message is displayed indicating why the update was bypassed. 36 Xpediter/CICS Advanced Configuration Guide 37 Implementing the IMS File Utility If your site uses IMS databases and you want to be able to access those IMS databases with Xpediter’s File Utility, installation of Xpediter DBCTL support is required. Roles Involved The following people are required: • IMS Administrator. Task 9.1 Implement DBCTL Support Perform the following procedure to implement DBCTL support: 1. If you are using VSAM as your access method, change the access method in SMXDSAMP member XPTSTDBD from OSAM to VSAM. 2. Generate DBD control blocks for the Xpediter/CICS database (XPTSTDBD). Either submit DBDGENs for the database using JCL already in place at your installation, or enter a job card and modify the default symbolic parameters in installation JCL member JCLDBD and submit. Table 4. Job JCLDBD Symbolic Parameters Symbolic Default Parameter Description PRINT * Print output SYSOUT class DEV SYSDA Temporary work file device SYSLIB XXXXXXX.MACLIB IMS Macro Library SAMPLIB CPWR.cMXD170.SMXDSAMP Xpediter/CICS Install Sample Library RESLIB XXXXXXX.RESLIB IMS RESLIB DBDLIB XXXXXXX.DBDLIB DBD Library MBR Blank PSB member name 3. Generate PSB control blocks for XPEDPSB1 and XPEDPSB2. Either submit PSBGENs for these PSBs using JCL already in place at your installation, or enter a job card and modify the default symbolic parameters in installation JCL member JCLPSB and submit. Table 5. Job JCLPSB Symbolic Parameters Symbolic Default Parameter Description PRINT * Print output SYSOUT class DEV SYSDA Temporary work file device SYSLIB XXXXXXX.MACLIB IMS Macro Library 9 38 Xpediter/CICS Advanced Configuration Guide Table 5. Job JCLPSB Symbolic Parameters (Continued) Symbolic Default Parameter Description SAMPLIB CPWR.cMXD170.SMXDSAMP Xpediter/CICS Install Sample Library RESLIB XXXXXXX.RESLIB IMS RESLIB PSBLIB XXXXXXX.PSBLIB IMS PSB Library MBR Blank PSB member name 4. Generate ACB control blocks for the PSBs XPEDPSB1 and XPEDPSB2. Either submit ACBGENs for these PSBs using JCL already in place at your installation, or enter a job card and modify the default symbolic parameters in installation JCL member JCLACB and submit. This must be done for each subsystem for which you want DBCTL support. Table 6. Job JCLACB Symbolic Parameters Symbolic Default Parameter Description PRINT * Print output SYSOUT class RESLIB XXXXXXX.RESLIB IMS RESLIB DBDLIB XXXXXXX.DBDLIB IMS DBD Library PSBLIB XXXXXXX.PSBLIB ACBLIB XXXXXXX.ACBLIB IMS ACB Library IMS PSB Library 5. Load the Xpediter/CICS database. Sample JCL member JCLLOAD in SMXDSAMP member is used to load the Xpediter/CICS database (XPTSTDBD). Review the JCL and submit it. • If you are using VSAM as your access method, change the access method buffer keyword from “IOBF” to “VSRBF”. • IMS stage 1 system definitions are not necessary before running this job. Table 7. Job JCLLOAD Symbolic Parameters Symbolic Default Parameter Description PRINT * Print output SYSOUT class SYSLIB XXXXXXX.MACLIB Macro Library RESLIB XXXXXXX.RESLIB IMS RESLIB PSBLIB XXXXXXX.PSBLIB IMS PSB Library MBR Blank PSB member name 6. Perform IMS system definition. Processing of the Xpediter/CICS database is like any other IMS application and must be defined to the IMS system. An APPLCTN macro must be input to the IMS stage 1 system definition job for each IMS subsystem to be used by Xpediter/CICS. The APPLCTN macro should be entered as follows: APPLCTN PSB=XPEDPSB2,PGMTYPE=BATCH,SCHDTYP=PARALLEL Implementing the IMS File Utility 39 The database must also be defined to the IMS system. A database macro must be input to the IMS stage 1 system definition job for each IMS subsystem to be used by Xpediter/CICS. The database macro should be entered as follows: DATABASE DBD=XPTSTDBD,ACCESS=RO Implementing Xpediter/CICS DBCTL support requires that an IMS OSAM buffer pool of 32K be established. This is accomplished by adding the following statement to DFSVSMxx: IOBF=(32K,4,N,N) Ensure that the PSBW pool has at least 100 KB of free space before scheduling the Xpediter/CICS PSB XPEDPSB2. If there is not enough free pool space, the PSB will be stopped and a DFS0993I message will be issued. Attempting to schedule the PSB after receiving this message will cause a user 456 abend. Normal IMS security for dependent regions restricts PSB usage to certain application group names (AGNs). Furthermore, the use of these AGNs is controlled by the external security manager. Therefore, there must be an AGN that allows the use of the PSB, and the user must be authorized to use it. Add the PSB (XPEDPSB2) to the proper AGN group for the CICS that is connected to IMS. 7. Define the database to IMS. If you want the Xpediter/CICS database to participate in IMS dynamic allocation, define it to IMS through the IMSDALOC procedure in place at your site. The output library from this procedure needs to be placed in the IMS control region and the DLISAS RESLIB concatenation: DFSMDA DFSMDA TYPE=DATABASE,DBDNAME=XPTSTDBD TYPE=DATASET,DSNNAME=XXXXXXXX.XPTSTDBD,DDNAME=XPTSTDBD If you do not want the database dynamically allocated, add a DD card in the DLISAS as follows: //XPTSTDBD DD DSN=XXXXXXX.XPTSTDBD,DISP=SHR 8. Define the database to DBRC. If you want the Xpediter/CICS database under the control of DBRC, define it with the recovery control utility to each IMS subsystem with which Xpediter/CICS will be used. Perform the definition with the following commands: INIT.DB DBD(XPTSTDBD) SHARELVL(0) TYPEIMS INIT.DBDS DBD(XPTSTDBD) DDN(XPTSTDBD) DSN(XXXXXXXX.XPTSTDBD) GENMAX(2) Because the Xpediter/CICS database is a read-only database and IMS provides you the ability to define a database as non-recoverable, you may want to do so for performance reasons. 9. If you use PSB security, you may be required to define the PSB and database to your existing external security manager. 10. Place the Xpediter/CICS APF authorized library in the DLISAS and IMS control region steplib. The default is SMXDAUTH member. IMS must be cycled for this change to take effect. 40 Xpediter/CICS Advanced Configuration Guide 41 Configuring the Script Facility The Xpediter/CICS Script Facility lets users record the primary and line commands they enter during a debugging session, save them in a PDS or PDSE, and then replay them later. This chapter explains how to set up — or disable — the Script Facility. For information on how to record and play back scripts, see the CAPTURE and INCLUDE primary commands in the Xpediter/CICS Reference Manual. Xpediter’s scripting capability is intended only for replicating breakpoints, keeps, and modifications to working storage data. Xpediter is not meant to be used as an automated testing tool. Overview The Xpediter/CICS Script Facility uses an MVS subtask to perform the physical I/O to a script PDS or PDSE. Since a subtask is used, the CICS TCB does not have to wait for completion of the I/O. This allows other CICS tasks and Xpediter debugging sessions not using scripts to continue execution. In addition, because dynamic allocation facilities are included in the subtask, setup of the Script Facility is quick and easy. The Script Facility subtask uses single-threaded access, which forces Xpediter users who have concurrent script requests outstanding to wait for prior requests to complete. Other tasks, however, including Xpediter debugging sessions that are not using a script, can continue to execute normally without waiting. Since the time required to save or execute a script is minimal, waits should not be noticeable to the user. Two types of script datasets may be accessed during a debugging session: • User script dataset • System script dataset. A user script dataset can be user-defined or site-defined. The ability to access user script datasets can be disabled as a region or site option. By default, the Script Facility will try to access a user script dataset first when executing a script. Individual users can choose not to utilize user script datasets. The system script dataset is used when: • The current script request cannot be satisfied from a user script dataset. • The user has decided not to utilize a user script dataset. • Access to user script datasets has been disabled as an installation option. Your site can set up a system script dataset as a read-only repository of scripts to be shared by multiple users. The site installer is responsible for creating the dataset with the procedures in this chapter prior to its first use. Script datasets must be defined as fixed blocked with a logical record length (LRECL) of 120. Userdefined user script datasets, if allowed by your site, do not need to be pre-allocated. Allocation will occur when a user first attempts to save a script. System script datasets and site-defined user script datasets must be pre-allocated. JCL members DBCDEFSS (for system script datasets) and DBCDEFUS (for user script datasets) contain JCL to allocate the required dataset(s). Activation of the Script Facility requires few, if any, JCL changes. If your site allows dynamic allocation of datasets, enabling and customizing the Script Facility requires no CICS startup JCL changes and only a few global table parameter changes, all of which can be done via the CMSC PARMLIB. If your site does not use dynamic allocation, you will need to modify your CICS startup JCL in addition to specifying global parameter changes. 10 42 Xpediter/CICS Advanced Configuration Guide Roles Involved The following people are required: • Xpediter/CICS Installer. Task 10.1 Setting up the Script Facility This section explains how to enable and configure the Xpediter/CICS Script Facility. In some steps, global parameter values are set using the CMSC PARMLIB. All of the global parameters set in this chapter are described in “Global Parameters Table”. For details on modifying the parameters, see “Adding Parameter Overrides to a Member in the CMSC PARMLIB”. Your site’s external security manager—RACF for example—must grant authority to create Xpediter’s system and user script datasets. Task 10.1.1 Enable the Script Facility Enable the Script Facility by adding the following line to your site’s CMSC PARMLIB: XDSCRPT=YES Enable Xpediter/CICS Script Facility Task 10.1.2 Add Program DBUGPLTS to Your CICS Shutdown PLT You may skip this step if DBUGPLTS was already added while installing Xpediter/Code Coverage. Program DBUGPLTS must be added to your CICS shutdown PLT so that the Xpediter Script Facility subtask can properly quiesce during CICS shutdown or region cancel. In your CICS shutdown PLT, before the line reading DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM, add the following entry: DFHPLT TYPE=ENTRY,PROGRAM=DBUGPLTS After adding the entry, reassemble and relink your PLTSD module. Task 10.1.3 Create a System Script Dataset The system script dataset is intended to serve as a repository of scripts to be shared by all Xpediter/CICS users in a single region or multiple regions. For example, the dataset could be enabled for READ and WRITE access in a test region where new scripts are developed. In all other CICS regions, the dataset could be enabled as a READONLY dataset. This would allow multiple users in these regions to utilize the scripts without concern about modifying them. Member DBCDEFSS contains JCL to create an Xpediter/CICS system script dataset. Modify the JCL according to the instructions below, then submit it to create your system script dataset. 1. Add a job card and any necessary OUTPUT specifications to the front of the member. 2. Change the XDSSDSN parameter in the JCL to the dataset name you want to use for your system script dataset, then write that dsn below: XDSSDSN:____________________ Your site’s external security manager must grant authority to create system script datasets with the chosen dsn. Configuring the Script Facility 43 3. Change the XDSSUNI parameter to the DASD unit name on which the dataset is to be allocated. 4. Change the XDSSVOL parameter to the volume and serial number on which the dataset is to be allocated. 5. Change the XDSSBLK parameter to the blocksize you want to use. This value must be a multiple of 120. Do not modify the LRECL specified in the JCL. 6. If you want the dataset to be allocated as a PDSE, uncomment the line reading DSNTYPE=LIBRARY,. 7. The following parameters can also be changed, if required: – – – – XDSSTYP=TRK — allocation type XDSSPA=15 — primary allocation units XDSSSA=15 — secondary allocation units XDSSDB=44 — number of directory blocks. 8. Submit the JCL to allocate your system script dataset. Task 10.1.4 Set Access to Your System Script Dataset You can configure the system script dataset with READONLY or WRITE access. To make the dataset READONLY, add the following parameter to your XDGBxxxx member in the CMSC PARMLIB: XDSSACC=READONLY System script is READONLY To enable WRITE access, add the following parameter to your XDGBxxxx member in the CMSC PARMLIB: XDSSACC=WRITE System script is READ/WRITE Task 10.1.5 Enable Allocation of Your System Script Dataset If your site allows dynamic allocation of datasets in CICS regions, go to step 1. If your site does not allow dynamic allocation of datasets in a CICS region, go to step 2. 1. Add the following parameters to your XDGBxxxx member in the CMSC PARMLIB: XDSSDD=DYNAMIC System script dynamically alloc. XDSSDSN= dsn from “Task 10.1.3 Create a System Script Dataset”, step 2 No CICS startup JCL changes are needed. Go to “Task 10.1.6 Decide Whether Your Site Will Allow User Script Datasets”. 2. Modify your XDGBxxxx member in the CMSC PARMLIB and CICS startup JCL as follows: a. Select a 1- to 8-character ddname for your system script dataset and write it below: ddname:____________________ b. Add the following parameter to your XDGBxxxx member in the CMSC PARMLIB: XDSSDD= ddname written above System script not dynamically alloc. c. Add the following DD statement to your CICS startup JCL: //ddname written above DD DISP=SHR,DSN=dsn from “Task 10.1.3 Create a System Script Dataset”, step 2 44 Xpediter/CICS Advanced Configuration Guide Task 10.1.6 Decide Whether Your Site Will Allow User Script Datasets User script datasets enhance the useability of the Script Facility. Compuware recommends allowing their use. If user script datasets are allowed, your site’s external security manager must grant authority to create them. If you want user script datasets, and your site allows dynamic allocation of datasets in CICS regions, continue with “Task 10.1.7 Decide Whether Your Site Will Force All Users to Share a Single User Script Dataset.”. If you want user script datasets, but your site does not allow dynamic allocation of datasets in CICS regions, go to “Task 10.1.9 Create a Shared User Script Dataset”. If your site does not want the enhanced useability provided by user script datasets, go to “Task 10.1.11 Set Defaults for Saving Scripts if Debugging is Terminated During Capture”. Task 10.1.7 Decide Whether Your Site Will Force All Users to Share a Single User Script Dataset. Restricting all users to a common pre-defined user script dataset can result in decreased useability and naming conflicts. Compuware recommends individual user-defined user script datasets. If you want user-defined user script datasets, continue with “Task 10.1.8 Enable Allocation of UserDefined User Script Datasets”. If your site wants to restrict users to a single shared user script dataset, go to “Task 10.1.9 Create a Shared User Script Dataset”. Task 10.1.8 Enable Allocation of User-Defined User Script Datasets The first two global parameters in this step establish dynamically allocated user-defined user script datasets. Default values are shown for the remaining global parameters which set the default allocation values for new user script datasets on the Script Dataset Allocation screen (0.6). If you want to use different values, see “Global Parameters Table” for more information. Add the parameters listed below to your XDGBxxxx member in the CMSC PARMLIB. Parameters with a value of NULL are set to a blank (null) value—not the word “null.” XDUSCR=YES XDUSDD=DYNAMIC XDUSBLK=27960 XDUSDB=44 XDUSDC=NULL XDUSLIB=NO XDUSMC=NULL XDUSPA=15 XDUSPFX=NULL XDUSSA=15 XDUSSC=NULL XDUSSMS=NO XDUSTYP=TRK XDUSUNI=SYSDA XDUSVOL=NULL Allow user-defined user script datasets Dynamically allocate user script datasets Blocksize for user script datasets (USDs) Directory blocks for USDs Data Class if SMS-controlled USDs Allocate USDs as PDSEs Management Class if SMS-controlled USDs Primary allocation for USDs Dataset name prefix for USDs Secondary allocation for USDs Storage Class if SMS-controlled USDs Allocate USDs under SMS control Allocation units for USDs Unit on which to allocate USDs Volume on which to allocate USDs Go to “Task 10.1.11 Set Defaults for Saving Scripts if Debugging is Terminated During Capture”. Task 10.1.9 Create a Shared User Script Dataset The user script dataset is intended to serve as a repository of scripts controlled by individual Xpediter/CICS users. Configuring the Script Facility 45 Member DBCDEFUS contains JCL to create an Xpediter/CICS user script dataset. Modify the JCL according to the instructions below, then submit it to create your user script dataset. 1. Add a job card and any necessary OUTPUT specifications to the front of the member. 2. Change the XDUSDSN parameter in the JCL to the dataset name you want to use for your user script dataset, then write that dsn below: XDUSDSN:____________________ 3. Change the XDUSUNI parameter to the DASD unit name on which the dataset is to be allocated. 4. Change the XDUSVOL parameter to the volume and serial number on which the dataset is to be allocated. 5. Change the XDUSBLK parameter to the blocksize you want to use. This value must be a multiple of 120. Do not modify the LRECL specified in the JCL. 6. If you want the dataset to be allocated as a PDSE, uncomment the line reading DSNTYPE=LIBRARY,. 7. The following parameters can also be changed, if required: – – – – XDUSTYP=TRK — allocation type XDUSPA=15 — primary allocation units XDUSSA=15 — secondary allocation units XDUSDB=44 — number of directory blocks. 8. Submit the JCL to allocate your user script dataset. Task 10.1.10 Enable Allocation of Your User Script Dataset If your site allows dynamic allocation of datasets in CICS regions, go to step 1. If your site does not allow dynamic allocation of datasets in a CICS region, go to step 2. 1. Add the following parameters to your XDGBxxxx member in the CMSC PARMLIB: XDUSDD=DYNAMIC User script dynamically alloc. XDUSDSN= dsn from “Task 10.1.9 Create a Shared User Script Dataset”, substep 2 No CICS startup JCL changes are needed. Go to “Task 10.1.11 Set Defaults for Saving Scripts if Debugging is Terminated During Capture”. 2. Modify your XDGBxxxx member in the CMSC PARMLIB and CICS startup JCL as follows: a. Select a 1- to 8-character ddname for your user script dataset and write it below: ddname:____________________ b. Add the following parameter to your XDGBxxxx member in the CMSC PARMLIB: XDUSDD= ddname written above User script not dynamically alloc. c. Add the following DD statement to your CICS startup JCL: // ddname written above DD DISP=SHR,DSN= dsn from step 10.1.9, substep 2 Task 10.1.11 Set Defaults for Saving Scripts if Debugging is Terminated During Capture Global parameter XDSCRXO sets the default for whether or not a script is saved when an Xpediter debugging session is terminated, either intentionally or due to terminal timeout, while that script is being captured. It can be set to SAVE or DISCARD. XDSCRXN sets the default name for scripts saved when a debugging session is terminated. Setting XDSCRXN to eight asterisks (********) will cause the userID of the person capturing a script to be used for the script name. A 1- to 8-character name can also be specified for the default script name. Users can override the default values on the Script Dataset Allocation screen (0.6). 46 Xpediter/CICS Advanced Configuration Guide Add the following parameters to your XDGBxxxx member in the CMSC PARMLIB: XDSCRXO=SAVE XDSCRXN=******** Save script if CAPTURE command active Save script with user ID as script name Task 10.2 Disabling the Script Facility If your site chooses not to use the Script Facility, you can disable it by adding the following line to your site’s global parameter overrides: XDSCRPT=NO Disable Xpediter/CICS Script Facility For more information, see Methods of Specifying and Updating Parameters.“Adding Parameter Overrides to a Member in the CMSC PARMLIB” 47 Configuring the File Utility Audit Trail The Xpediter/CICS File Utility Audit Trail lets a site keep track of any changes to its resources that are made with the Xpediter File Utility. These changes can include adds, updates, and deletes of: • • • • • dataset records temporary storage records and queues transient data records IMS segments DB2 tables The File Utility Audit Trail also records access modifications made to datasets and transient data queues, including opens, closes, and request modifications such as enabling or disabling add or update capabilities with the CICS Dataset List screen (5.1.1). The Xpediter File Utility Audit Trail writes formatted data to a Generation Data Group (GDG) dataset. You can tailor the Facility’s output to suit your site’s specific needs. Use of a GDG ensures uninterrupted recording even if a dataset fills up, and it allows for easy dataset backup. This chapter explains how to set up—or disable—the File Utility Audit Trail. Information is also provided on how to start and stop logging and switch to a new generation dataset. Extensive examples of entries are used to illustrate how Xpediter formats the information captured by the File Utility Audit Trail. Follow the step-by-step instructions in “Setting Up the File Utility Audit Trail” to enable the Xpediter/CICS File Utility Audit Trail. If your site does not want to use the File Utility Audit Trail, go to “Disabling the File Utility Audit Trail”. Roles Involved The following person is required: • Xpediter/CICS Installer. Overview The Xpediter/CICS File Utility Audit Trail uses an MVS subtask to perform the physical I/O to the dataset, as well as much of the formatting of the data. Because a subtask is used, the CICS TCB isn’t forced to make the region wait for the I/O to complete. This allows other CICS tasks and Xpediter sessions not using the File Utility to continue normal execution. File Utility users don’t need to wait for the I/O to complete either, because Xpediter simply queues I/O requests, letting the MVS subtask actually write the data. Requests from multiple users may be interspersed in the dataset, because queued data is written on a first-in, first-out basis. Each update, however, is always written in its entirety as a single event. The Xpediter File Utility Audit Trail is written to a GDG whose generation datasets have a logical record length (LRECL) of 133. The change data is formatted and includes ASA control characters so it can be directly printed. Each entry is given a header line that includes the following information about the change: • date and time the change occurred • userID, terminal ID, and netname associated with the person making the change. 11 48 Xpediter/CICS Advanced Configuration Guide This header line has a standard format and can be used as a search key if your site wants to write a program to process the dataset for other types of reporting. While the dataset is open for output, the dataset-in-use flag is enabled, prohibiting any other task, including ISPF browse, from accessing it. A CICS program furnished with Xpediter allows you to turn the File Utility Audit Trail on and off or switch the dataset to a new generation. Access to this program and its transaction code, XLOG, should be restricted to authorized individuals with your site’s external security manager. For more information, see “XLOG Transaction”. Activation of the File Utility Audit Trail requires few, if any, JCL changes. If your site allows dynamic allocation of datasets, enabling and customizing the File Utility Audit Trail requires no CICS startup JCL changes and only a few global table parameter changes, all of which can be done via the CMSC PARMLIB. If your site does not use dynamic allocation, you will need to modify your CICS startup JCL in addition to specifying global parameter changes. Using dynamic allocation provides another important benefit. When a generation dataset fills up, a new one is dynamically allocated so that logging can continue with no loss of information. Without dynamic allocation, if the dataset fills up while a entry is being written, the File Utility Audit Trail wraps to the top of the same dataset, the remainder of the entry is written, and the previous contents are overlaid. This is not an Xpediter restriction, but an inherent limitation of generation datasets, which are explicitly defined to a jobstream via JCL DD statements. Task 11.1 Setting Up the File Utility Audit Trail This section explains how to enable and configure the Xpediter/CICS File Utility Audit Trail. In some steps, global parameter values are set using the CMSC PARMLIB. All of the global parameters set in this chapter are described in “Global Parameters Table”. For details on modifying the parameters, see “Adding Parameter Overrides to a Member in the CMSC PARMLIB”. Your site’s external security manager—RACF for example—must grant authority to create Xpediter’s File Utility Audit Trail GDG dataset. Although Compuware strongly recommends setting global parameter values in the CMSC PARMLIB, you can choose instead to directly modify values in the Xpediter global table as required, then reassemble and link edit it. Refer to “Specifying Global Parameters by Assembling DBUGGBL” for more information. Task 11.1.1 Enable the File Utility Audit Trail Facility Enable the File Utility Audit Trail by adding the following line to your site’s CMSC PARMLIB: XDLOG=YES Enable Xpediter/CICS File Utility Audit Trail Task 11.1.2 Add Program DBUGPLTS to Your CICS Shutdown PLT Program DBUGPLTS must be added to your CICS shutdown PLT so that the Xpediter File Utility Audit Trail subtask can properly quiesce during CICS shutdown or region cancel. In your CICS shutdown PLT, before the line reading DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM, add the following entry: DFHPLT TYPE=ENTRY,PROGRAM=DBUGPLTS After adding the entry, reassemble and relink your PLTSD module. Task 11.1.3 Define the File Utility Audit Trail GDG To use a GDG, you must first define its properties by creating a model dataset control block (DSCB) and building a GDG index for it. These properties include the base name of the GDG, the maximum number of datasets in the group, and the action to perform when that maximum is reached. If the Configuring the File Utility Audit Trail 49 File Utility Audit Trail will be used in multiple CICS regions, you must create multiple model DSCBs so that each region has its own GDG. Member DEFLOGDG contains JCL to create a model DSCB and build a GDG index. The JCL includes an Access Method Services (AMS) DEFINE GENERATIONDATAGROUP statement. Compuware recommends using the NOEMPTY and NOSCRATCH parameters shown. With the NOEMPTY parameter, when the maximum number of datasets in the GDG has been reached and a new dataset needs to be cataloged, only the oldest dataset in the GDG is uncataloged. If the EMPTY parameter were used instead, all the datasets in the GDG would be uncataloged. With the NOSCRATCH parameter, when a generation dataset is uncataloged, its DSCB is retained in the volume’s VTOC, allowing it to still be located. Refer to the IBM manual Access Method Services for the Integrated Catalog Facility for more details. Modify the JCL according to the instructions below, then submit it to define your File Utility Audit Trail dataset. 1. Add a job card and any necessary OUTPUT specifications to the front of the member. 2. The AMS control statement NAME parameter can be up to 35 positions long. The remaining 9 positions, in the format .GxxxxVxx, will be supplied automatically by MVS when the dataset is allocated. Change the NAME parameter in the JCL to the base GDG name you want to use for your generation datasets, then write that base name below: Base GDG name:____________________ Your site’s external security manager must grant authority to create the GDG dataset with the chosen base name. 3. Change the AMS control statement LIMIT parameter to the maximum number of generation datasets you want in your GDG. Valid numbers are 1 to 255. Compuware recommends a setting of at least 10. 4. Submit the JCL to create a model DSCB and build the GDG index for your dataset. Task 11.1.4 Enable Allocation of Your File Utility Audit Trail Dataset Compuware strongly recommends using dynamic allocation of generation datasets. Use of dynamic allocation ensures continuous logging without overlaying previous information and can be enabled without changing your CICS startup JCL. If your site allows dynamic allocation of datasets in CICS regions, go to step 1. If your site does not allow dynamic allocation of datasets in a CICS region, go to step 2. 1. The first two global parameters in this step establish the use of dynamically allocated generation datasets. Default values are shown for the remaining global parameters which specify various space allocation settings. If you want to use different values, consult “Configuration Parameters” for more information. Add the following parameters to your XDGBxxxx member in the CMSC PARMLIB: XDLOGDD=DYNAMIC Dynamically allocate dataset XDLOGNM=base GDG name from “Task 11.1.3 Define the File Utility Audit Trail GDG”, substep 2 XDLOGTY=CYL Allocation units for dataset XDLOGPA=10 Primary allocation for dataset XDLOGSA=5 Secondary allocation for dataset XDLOGBK=27930 Blocksize for dataset XDLOGUN=SYSDA Unit on which to allocate dataset No CICS startup JCL changes are needed. Go to “Task 11.1.5 Specify Format of File Utility Audit Trail Dataset Output”. 2. Modify your XDGBxxxx member in the CMSC PARMLIB and CICS startup JCL as follows: 50 Xpediter/CICS Advanced Configuration Guide a. Select a 1- to 8-character ddname for your File Utility Audit Trail dataset and write it below: ddname:____________________ b. Add the following parameter to your XDGBxxxx member in the CMSC PARMLIB: XDLOGDD= ddname written above Log dataset not dynamically alloc. c. Add the following DD statement to your CICS startup JCL: // ddname written above DD DISP=(NEW,CATLG,CATLG), // DSN= base GDG name from “Task 11.1.3 Define the File Utility Audit Trail GDG”,  substep 2 (+1),SPACE=(CYL,(10,5)), // DCB=(DSORG=PS,RECFM=FBA,LRECL=133,BLKSIZE=27930) Task 11.1.5 Specify Format of File Utility Audit Trail Dataset Output Default values are shown for the following global parameters which specify the amount and format of data written to the Xpediter File Utility Audit Trail dataset. If you want to use different values, consult “Global Parameters Table” for more information. Add the following parameters to your XDGBxxxx member in the CMSC PARMLIB: XDLOGAD=FULL XDLOGDL=FULL XDLOGUP=FULL Log entire record added Log entire before image of deleted record Log entire before/after image of updated record Task 11.2 Disabling the File Utility Audit Trail If your site chooses not to use the File Utility Audit Trail, you can disable it by adding the following line to your site’s global parameter overrides: XDLOG=NO Log File Utility changes For more information, see “Adding Parameter Overrides to a Member in the CMSC PARMLIB”. XLOG Transaction The XLOG transaction, associated with program DBUGLOGM, allows selected users to enable or disable the File Utility Audit Trail while Xpediter is active and to switch to a new generation of the dataset while the File Utility Audit Trail is active. The following examples show the various screens displayed when the XLOG transaction is entered in different situations. Xpediter/CICS Not Active If Xpediter/CICS has not been initialized, the following screen will be displayed. Figure 1. XLOG Screen with Xpediter/CICS Not Active  ---------- Compuware Xpediter/CICS Time: 16:48:48.0 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 XPEDITER/CICS Audit Trail cannot execute, product is not active. Xpediter/CICS Active, File Utility Audit Trail Not Active If Xpediter is active, but the File Utility Audit Trail was not activated at product initialization or was terminated for some reason, the screen shown in Figure 2 will be displayed, allowing you to activate the File Utility Audit Trail. Configuring the File Utility Audit Trail 51 Figure 2. XLOG Screen with Xpediter/CICS Active, File Utility Audit Trail Not Active    ---------- Compuware Xpediter/CICS Time: 17:07:53.8 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing is not active. Do you wish to activate Auditing? ==> (Yes or No) If you enter N (No), the File Utility Audit Trail will remain inactive, and the following screen will be displayed. Figure 3. XLOG Screen after File Utility Audit Trail Not Activated   ---------- Compuware Xpediter/CICS Time: 17:07:53.8 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing remains inactive. If you enter Y (Yes), Xpediter will start the File Utility Audit Trail, and the screen shown in Figure 4 will be displayed. Figure 4. XLOG Screen after File Utility Audit Trail Activated     ---------- Compuware Xpediter/CICS Time: 17:24:04.2 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing has been activated. Auditing is active. Currently Writing to Dataset ’MYUSRID.ACME.GDG.G0935V00’ Xpediter/CICS Active, File Utility Audit Trail Active If Xpediter and the File Utility Audit Trail are both active, the screen shown in Figure 5 will be displayed, allowing you to terminate the File Utility Audit Trail, switch to a new generation of the dataset, or exit the XLOG transaction without making any changes. Figure 5. XLOG Screen when File Utility Audit Trail is Active     ---------- Compuware Xpediter/CICS Time: 16:52:12.8 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing is active. Currently Writing to Dataset ’MYUSRID.ACME.GDG.G0935V00’ Do you wish to terminate or switch datasets? ==> (Term, Switch, Neither) If you enter T (Term), Xpediter will terminate the File Utility Audit Trail, and the screen shown in Figure 6 will be displayed. 52 Xpediter/CICS Advanced Configuration Guide Figure 6. XLOG Screen when File Utility Audit Trail is Terminated    ---------- Compuware Xpediter/CICS Time: 16:59:41.7 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing has been terminated. Previously Writing to Dataset ’MYUSRID.ACME.GDG.G0935V00’ If you enter S (Switch), the File Utility Audit Trail will remain active, the current generation of the dataset will be closed, and logging will continue to a newly allocated generation of the dataset. Figure 7 shows the screen displayed to verify that the dataset has been switched. Figure 7. XLOG Screen when Dataset is Switched      ---------- Compuware Xpediter/CICS Time: 17:39:26.3 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing has been switched. Previously Writing to Dataset MYUSRID.ACME.GDG.G0935V00. Auditing is active. Currently Writing to Dataset ’MYUSRID.ACME.GDG.G0936V00’ If you enter N (Neither), the XLOG transaction will complete without terminating the File Utility Audit Trail or switching to a generation of dataset. The screen shown in Figure 8 will be displayed. Figure 8. XLOG Screen when Neither is Entered    ---------- Compuware Xpediter/CICS Time: 16:52:12.8 Date: 12 MAR 2003 Audit Facility Monitor Program --------C123 Term: A011 User: MYUSRID Applid: ACMEC123 Auditing remains active. Currently Writing to Dataset ’MYUSRID.ACME.GDG.G0935V00’ Entry Formatting This section has examples that show the different ways in which the File Utility Audit Trail formats data. The format of the data depends on the type of data changed with the File Utility, the kind of change done, and the settings of the global parameters XDLOGDL, XDLOGUP, and XDLOGAD. Dataset Heading The heading lines shown in Figure 9 are written to each generation of the dataset. The first line appears at the top of each new page and includes the current page number. The remaining lines only appear on the first page. The second line includes the name of the generation dataset, where it resides, and the time recording was initiated. The parameter lines indicate how the data will be formatted. Configuring the File Utility Audit Trail 53 Figure 9. Common Report Heading Lines Xpediter/CICS Log Facility Page 1 Logging to dataset ’MYUSRID.ACME.GDG.G0938V00’ on volser PRD914 was begun at 17:39:29.299525 on 12 MAR 2003. Logging parameters are: XDLOGDL=FULL Log full contents of deleted records XDLOGUP=FULL Log full contents of modified records XDLOGAD=FULL Log full contents of added records Entry Headings The entries written by the File Utility Audit Trail are in printable form, but no reporting functions built in. You must supply your own program to do more than simply print out the entire audit trail. Figure 10 shows the format of the standard header line written at the top of each Entry. Compuware plans to maintain this header format in future Xpediter releases, even if modifications are made to the format of the actual data. Figure 10. Formatting of Standard Entry Header Line File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 17:58:13.039422 on 12 MAR 2003. Table 8 lists the starting column, length, and contents of each section of the standard header line. Table 8. Standard Entry Header Line Sections Column Length Description 1 1 ASA control character 2 31 Constant: “ File Utility request from user ” 33 8 UserID associated with File Utility change 41 12 Constant: “ at netname ” 53 8 VTAM Netname from which change was made 61 11 Constant: “ (terminal ” 72 4 Terminal ID from which change was made 76 12 Constant: “) in region ” 88 8 VTAM Applid of the CICS region 96 4 Constant: “ at ” 100 15 Time at which change was made. Format is hh:mm:ss.ssssss where hh is hours, mm is minutes, and ss.ssssss is seconds. 115 4 Constant: “ on ” 119 11 Date on which change was made. Format is dd mmm yyyy where dd is day, mmm is month, and yyyy is year. Closing the Dataset Figure 11 shows the message displayed when the dataset is switched or the File Utility Audit Trail is terminated by the XLOG transaction, Xpediter shutdown, or CICS shutdown or termination. 54 Xpediter/CICS Advanced Configuration Guide Figure 11. Message Displayed when dataset is Closed Logging to dataset ’MYUSRID.ACME.GDG.G0938V00’ on volser PRD914 was completed at 18:01:20.181514 on 12 MAR 2003. Logging ended due to Xpediter/CICS XLOG transaction TERMINATE request. Dataset Service Request Changes The following examples shows the message displayed when a dataset service request is changed. In this example dataset DBUGPRF was closed and then reopened. The user then closed DBUGEMP and then added the UPD, ADD, and DEL service requests. Changes are flagged with asterisks (*) on the line following each entry. Figure 12. Formatting of Dataset Service Request Changes File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at Service requests have been changed. File Name: DBUGPRF Dataset Name: MYUSRID.DBUG.PROFILE Access Method: Before OPE ENA REA UPD ADD BRO DEL After CLO UNE REA UPD ADD BRO DEL Changes *** * * File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at Service requests have been changed. File Name: DBUGPRF Dataset Name: MYUSRID.DBUG.PROFILE Access Method: Before CLO UNE REA UPD ADD BRO DEL After OPE ENA REA UPD ADD BRO DEL Changes *** * * File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at Service requests have been changed. File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER Access Method: Before OPE ENA REA BRO After CLO UNE REA BRO Changes *** * * File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at Service requests have been changed. Some attributes for this dataset are not available (N/A) because dataset is closed. File Name: DBUGEMP Dataset Name: N/A Access Method: Before CLO UNE REA BRO After CLO UNE REA UPD ADD BRO DEL Changes *** *** *** 17:58:13.039422 on 12 MAR 2003. VSAM Type: KSDS 17:58:16.375651 on 12 MAR 2003. VSAM Type: KSDS 18:00:38.774951 on 12 MAR 2003. VSAM Type: KSDS 18:00:44.901741 on 12 MAR 2003. VSAM Type: N/A Dataset Records The following examples show the formatting performed when a dataset record is added, updated, or deleted. The two update examples show the difference in formatting when the XDLOGUP global parameter is set to FULL or SHORT. The entries created for queued temporary storage, and transient data queue records are similar. Add Figure 13 shows the formatting performed when a dataset record is added. The File Utility Audit Trail copies the contents of the added record. Figure 13. Formatting of Dataset Record Add File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 18:00:52.304322 on 12 MAR 2003. The following record has been added. File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER Access Method: VSAM Type: KSDS Contents of key. Key length: 5 ----+ 99999 FFFFF 99999 Record Length: 80 ----+---10----+---20----+---30----+---40----+---50----+---60----+---70----+---80 99999THIS RECORD WAS ADDED FROM THE 5.1.3 SCREEN. FFFFFECCE4DCCDDC4ECE4CCCCC4CDDD4ECC4F0F0F4ECDCCD04444444444444444444444444444444 99999389209536940612014454069640385050103023955500000000000000000000000000000000 Configuring the File Utility Audit Trail 55 Update — Full The formatting of the Entry for a dataset record update with the XDLOGUP global parameter set to FULL is shown in Figure 14. Before and after images are provided, and changes are flagged with asterisks (*) on the line below the after image. Figure 14. Formatting of Dataset Record Update — Full File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 18:01:01.765627 on 12 MAR 2003. The following record has been modified. File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER Access Method: VSAM Type: KSDS Contents of key. Key length: 5 ----+ 99999 FFFFF 99999 Before image record Length: 80 After image record Length: 80 Number of bytes modified: 8 Before 99999THIS RECORD WAS ADDED FROM THE 5.1.3 SCREEN. FFFFFECCE4DCCDDC4ECE4CCCCC4CDDD4ECC4F0F0F4ECDCCD04444444444444444444444444444444 99999389209536940612014454069640385050103023955500000000000000000000000000000000 ----+---10----+---20----+---30----+---40----+---50----+---60----+---70----+---80 After 99999THIS RECORD WAS UPDATED ON THE 5.1.3 SCREEN. FFFFFECCE4DCCDDC4ECE4EDCCECC4DD4ECC4F0F0F4ECDCCD04444444444444444444444444444444 99999389209536940612047413540650385050103023955500000000000000000000000000000000 Changes ** ***** * Update — Short The formatting of a short Entry for a dataset record update is shown in Figure 15. Instead of writing the entire record, the before and after images only include those parts of the record that have been changed. Figure 15. Formatting of Dataset Record Update — Short File Utility request from user MYUSRID at netname TACA011 The following record has been modified. File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER Contents of key. Key length: 5 ----+ 00040 FFFFF 00040 Before image record Length: 80 After image record Length: 80 Number of bytes modified: 21 Columns 10..15 17..19 21..24 26..33 Before 444444 444 4444 44444444 000000 000 0000 00000000 +----+ --------30--- After RECORD HAS BEEN UPDATED. DCCDDC CCE CCCD EDCCECC4 953694 812 2555 4741354B Changes ****** *** **** ******** (terminal A011) in region ACMEC123 at 14:26:04.261296 on 12 MAR 2003. Access Method: VSAM Type: KSDS Delete Figure 16 shows the formatting performed when a dataset record is deleted. The File Utility Audit Trail copies the contents of the deleted record. 56 Xpediter/CICS Advanced Configuration Guide Figure 16. Formatting of Dataset Record Delete File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 18:01:06.893980 on 12 MAR 2003. The following record has been deleted. File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER Access Method: VSAM Type: KSDS Contents of key. Key length: 5 ----+ 99999 FFFFF 99999 Record Length: 80 ----+---10----+---20----+---30----+---40----+---50----+---60----+---70----+---80 99999THIS RECORD WAS UPDATED ON THE 5.1.3 SCREEN. FFFFFECCE4DCCDDC4ECE4EDCCECC4DD4ECC4F0F0F4ECDCCD04444444444444444444444444444444 99999389209536940612047413540650385050103023955500000000000000000000000000000000 DL/I Segment Replace Figure 17 shows the formatting performed when a DL/I segment is replaced and the XDLOGUP global parameter is set to FULL. When the PSB is scheduled, an Xpediter-supplied syncpoint indicator is written. If the user exits normally from the DL/I File Utility, the syncpoint will show that the changes have been committed. If the user cancels the updates, the syncpoint will indicate that the changes have been cancelled. Entries for segment insert, segment replace with XDLOGUP=SHORT, and segment delete are similar. Figure 17. Formatting of DL/I Segment Replace File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 14:27:01.952976 on 12 MAR 2003. PSB NAME: DFHSAM04 (LOCAL) PCB#: 001 DBD: DI21PART PSB has been scheduled. ----------------------------------------------------------------------------------------------------------------------------- Xpediter/CICS syncpoint DLI00002 begins here. ----------------------------------------------------------------------------------------------------------------------------- File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 14:27:32.564709 on 11 MAR 1997. The following segment has been modified. Contents of PCB Feedback Area Database Name: DI21PART Level: 01 Status Code:’ ’ Processing Options: A Segment Name: PARTROOT Contents of Key Feedback Area. Key Feedback Length: 17 ----+---10----+-- ....2215960C10 0306FFFFFFFCFF444 04042215960310000 Contents of Search Segment Arguments Before image segment length:50 After image segment length:50 Number of bytes modified: 6 Before ....2215960C10 WASHER 0306FFFFFFFCFF4444444444444444ECECCD44444444444444 04042215960310000000000000000061285900000000000000 ----+---10----+---20----+---30----+---40----+---50 After ....2215960C10 DRYER 0306FFFFFFFCFF4444444444444444CDECD444444444444444 04042215960310000000000000000049859000000000000000 Changes ****** File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 14:28:54.938825 on 11 MAR 1997. PSB NAME: DFHSAM04 (LOCAL) PCB#: 001 DBD: DI21PART PSB has been terminated. ----------------------------------------------------------------------------------------------------------------------------- Xpediter/CICS syncpoint DLI00002 ends here. Changes are COMMITTED. ----------------------------------------------------------------------------------------------------------------------------- DB2 Row Update Figure 18 shows the formatting performed when a DB2 row is updated. Multiple requests can performed in the DB2 portion of the Xpediter File Utility and entries will be created for each, but updates are not actually passed to DB2 until the user enters the COMMIT command. The entries begin and end with syncpoint indicators. The end syncpoint indicator will show whether the DB2 changes were cancelled by a CANCEL command or some error or were committed to the database. Entries for DB2 row add and row delete are similar. Configuring the File Utility Audit Trail 57 Figure 18. Formatting of DB2 Row Update File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 14:06:54.102913 on 12 MAR 2003. DB2 Table Creator: CWX Table Name: EMPLOYEE Database Name: P51V2R3G TableSpace Name: TSEMPLOY ----------------------------------------------------------------------------------------------------------------------------- - Xpediter/CICS syncpoint DB200004 begins here. - ----------------------------------------------------------------------------------------------------------------------------- - - Update requested. User does not have exclusive lock. Only columns selected for query will be displayed. - - - The following row was updated. This row had 1 column modified. - Varlen - Column Name Attributes or NULL Status Value - ------------------ --------------- ------- ---------- ------------------------------------------------------------------ ----+- EMP_NO CHAR(5) No change 01010 - ----+---10----+---20----+---30----+- EMP_NAME CHAR(36) Before THIS DB2 ROW WAS ADDED. - After THIS DB2 COLUMN WAS MODIFIED - Changes * ****** ********** - ----+--- EMP_RATE CHAR(6) No change 001000 - ----+---- EMP_HOURS CHAR(6) No change 000040 - File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACMEC123 at 14:06:54.309849 on 07 MAR 1997. DB2 Table Creator: CWX Table Name: EMPLOYEE Database Name: P51V2R3G TableSpace Name: TSEMPLOY - - END requested. COMMIT command issued. - - ----------------------------------------------------------------------------------------------------------------------------- - Xpediter/CICS syncpoint DB200004 ends here. Changes are COMMITTED. - ----------------------------------------------------------------------------------------------------------------------------- 58 Xpediter/CICS Advanced Configuration Guide 59 Configuring Xpediter with Language Environment This chapter explains how to use Xpediter with Language Environment. Roles Involved The following person is required: • Xpediter/CICS Installer. Setting Run-Time Options Task 12.1 Set Run-Time Options To properly utilize Xpediter Language Environment, you must correctly set two of the options in CEECOPT. No other CEECOPT options need to be set for use with Xpediter. Refer to Table 9 and the option explanations below and make the necessary changes. Table 9. CEECOPT Option Settings Option Required Setting ABTERMENC ABEND TRAP ON ABTERMENC Establishes enclave termination behavior for conditions of severity 2 and above. This must be set to ABEND to force a CICS level abend for the relevant condition. Refer to IBM’s Language Environment Installation Guide for more information. TRAP Ensures that Language Environment will get control on abends. Control is needed to drive Language Environment cleanup routines as well as for proper application behavior. Xpediter/CICS requires this option to be set to ON. This option is unrelated to Xpediter’s abend trapping function or Trap Summary screen (1.6). The parameters specified in CEECOPT can be overridden with CEEUOPT. Xpediter honors valid overrides for a particular application when CEEUOPT is assembled and linked into that application. CEEUOPT, if used, must be assembled and linked with the same release of Language Environment as used in the CICS run-time environment. Software-Raised Error Conditions Previous versions of the run-time Language Environment performed selected edits of application data and instructions before the instructions were actually executed. An example would be the prechecking of signs on COBOL II add instructions. If COBOL II detected an error, it issued a 12 60 Xpediter/CICS Advanced Configuration Guide CICS-level abend (10xx). Xpediter/CICS trapped these abends while environmental components such as DSAs and TGTs were still intact. This allowed for proper display of registers, PSWs, and other pertinent information. Dumps taken with and without Xpediter were consistent in their reporting of the application’s status at the time of the abend. Instead of issuing CICS-level abends when such errors occur, the Language Environment run time notifies the condition manager, which then drives any registered user condition handlers (UCHs). If the error is left unhandled, the condition manager will abend the task with a U4038 abend, signifying an unhandled condition. Unlike the 10xx abends, which specified the cause of a particular problem, 4038 abends are generic in nature. Without Xpediter, extensive diagnosis of the resulting dump would be necessary to pinpoint the cause of a problem. The registers and PSW at the time of the dump might not reflect the actual status of the application at the time of the error. Backchaining of various control blocks could be necessary to locate the required information. To avoid these problems, Xpediter/CICS intercepts unhandled conditions before the condition manager can generate the generic abend. The 4038 abend is displayed on the Break/Abend screen (2.1), but Xpediter includes the appropriate registers and PSW. A help screen is also available, providing additional information on the original cause of the abend. A dump generated from an unhandled error condition under Xpediter will contain register and PSW values as they existed before the 4038 abend. Note that this dump may be inconsistent with a dump produced without Xpediter present to trap the abend. Amode Considerations The Language Environment condition manager drives all user condition handlers in 31-bit mode. This is true whether the UCH is statically linked into the main code base or is invoked dynamically and regardless of whether it was linked as 24 or 31 bit. Xpediter’s monitor honors the amode passed by the condition manager and will monitor all UCH modules as 31 bit. 61 Installing and Customizing the Remote Operations Command Interface The Remote Operations Command Interface (ROCI) allows both startup and shutdown of the product in multiple CICS regions with one command entered on an ISPF panel. This interface is optional. If your site has no need for a “single point of control” of Xpediter/CICS within all of your CICS regions, skip this portion of the install. After completing this optional portion of the Xpediter/CICS installation, refer to the Xpediter/CICS Reference Manual chapter entitled “Remote Operations Command Interface” for information on the usage of the ROCI. Roles Involved The following person is required: • Xpediter/CICS Installer. Tasks Task 13.1 Define and Initialize the Configuration File Within the SMXDSAMP dataset, member DBCDEFCI is a job that both defines and initializes the VSAM dataset used by ROCI. Your actual data will be added interactively via the ISPF interface. When fully loaded, the dataset will contain one 90-byte record per CICS APPLID. It is a VSAM KSDS. Modify the SPACE and VOLUME parameters according to your installation’s needs. Security on access to the configuration file can be used to limit access to this feature. Task 13.2 Copy and Customize the CLIST The Remote Operations Command Interface is an ISPF application driven from a CLIST. Within the SMXDSAMP dataset, member DBUGCI is a CLIST that must be copied to either a new or existing CLIST library of your choice, then customized. The customization instructions, which are also provided at the top of the CLIST, are as follows: • Change the NODE keyword value on line 1 of the CLIST from CPWR.cMXD170 to the site-specific value for your Xpediter/CICS SMXDPDSE and SMXDSAMP libraries. All of the ISPF panels and messages used by this interface are in SMXDSAMP. LIBDEF will be done within the CLIST to add them to ISPPLIB and ISPMLIB, respectively. • Change the ROCI keyword on line 2 of the CLIST from XPED.ROCI.CONFIG.FILE to the value you used in DBCDEFCI when the dataset was defined and initialized. • Change the EXCILIB keyword on line 3 of the CLIST from YOUR.CICS.SDFHEXCI to the name of your CICS EXCI load library. Use the highest CICS release that you are licensed for. • Change the TCPLIB keyword on line 4 of the CLIST from TCPIP.SEZALOAD to the name of your MVS TCP/IP load library. 13 62 Xpediter/CICS Advanced Configuration Guide All of the application programs invoked by this interface are in SMXDPDSE. LIBDEF will be done within the CLIST to add SMXDPDSE, EXCILIB, and TCPLIB to ISPLLIB. • If your terminal displays KATAKANA characters, change the LANG keyword on line 5 of the CLIST to LANG(JAPANESE). • As shipped, the SYSOUT report XDCIRPT will be deleted at close. This report contains all of the Xpediter/CICS messages pertaining to startup and shutdown that were generated by CICS regions during this use of the Remote Operations Command Interface. If you want to save this report, modify the ALLOCATE statement for XDCIRPT within the CLIST to include a class [SYSOUT(class)] and/or other valid TSO parameters. Refer to the IBM manual TSO Command Parameters for further information on allocating SYSOUT datasets. • The customized CLIST may either be added to your site’s vendor dialogs (or whatever you call such dialogs) invoked from your ISR@PRIM, or it may simply be invoked from the ISPF Primary Option Menu’s ISPF Command Shell option, then entered as: EX CLISTlibraryname(DBUGCI) . See your ISPF systems programmer for assistance in modifying your site’s ISR@PRIM. Task 13.3 Add Necessary Definitions to CICS Regions ROCI communicates from ISPF to the various CICS regions via any combination of External CICS Interface (EXCI), TCP/IP CICS Sockets (CICS Sockets), and/or CICS Web Interface (CWI), as specified by the CICS systems programmer. Based on MVS configuration and current use (or lack of use) of TCP/IP, choose one communication method for each CICS region. EXCI is the most efficient and secure of the three communication methods. Compuware recommends that EXCI be used, if possible. To use the EXCI communication method, both the ISPF interface and the CICS region must be in the same MVS image, unless the CICS region is running in a sysplex that supports cross-system MRO (XCF/MRO). If that is not the case, choose one of the other communications options for that CICS region. If you are not currently a user of TCP/IP CICS Sockets within the CICS region, Compuware recommends that you use the CICS Web Interface (CWI) communication method instead. Follow the applicable instructions below to install your chosen communications method in your CICS region. Task 13.3.1 Install EXCI To define the CICS EXCI Connection and Sessions, see SMXDSAMP member CSDEXCI that contains a sample RDO group. IBM requires that your CICS region SIT parameters include IRCSTRT=YES for EXCI to be used. The EXCI connection in CICS is defined as specific. Therefore, security is based on the ISPF userID. Ensure that RACF, or whatever external security manager you use, has appropriate entries for MRO logon and bind-time security, for that ISPF userID. Refer to the chapter entitled “EXCI Security” in the CICS Transaction Server for z/OS External Interfaces Guide for additional information. Task 13.3.2 Install TCP/IP CICS Sockets (CICS Sockets) To install this communications method in your CICS region, refer to the IBM Communications Server manual, IP CICS Sockets Guide. If you already use this communications method within a CICS region, you may be able to use your current definitions (IP address and port number), depending on compatibility with your current security setup and listener. Installing and Customizing the Remote Operations Command Interface 63 Using this communication method, ROCI sends the userID and password (if they were entered when the CICS region was added to the ROCI configuration file) to CICS along with the XPCI transaction code (or user-specified replacement) and a function code. An EXEC CICS VERIFY is done against the userID and password if they are present. Then the userID (if present) is tested to ensure that it is authorized to use the transaction code. If the userID and password are not entered in the ROCI configuration file record for this CICS region, no security checking is performed. If the procedure just described is compatible with your current CICS listener, no new TCP/IP definitions are required; the region’s existing IP address and port number can be provided to ROCI when you add this region to the configuration file. If your current CICS listener has been customized such that ROCI cannot use it, you must either define and start the IBM default listener on another port in this region, or use one of the other communication methods. If a new listener is used, see your MVS TCP/IP systems programmer for definition of an IP address and port number to use. Task 13.3.3 Install CICS Web Interface (CWI) This communication method requires a CICS SIT setting, an RDO group, and at least one TCPIPSERVICE definition within the CICS region. • In the SIT, ensure option TCPIP is set to YES. • RDO groups installed must include DFHWEB. • The TCPIPSERVICE definition to be installed must be HTTP. Within that definition, the URM parameter should be DFHWBADX or a user-customized module based on DFHWBADX that supports the CWI standard URL. The SSL parameter must be NO. The AUTHENTICATE parameter must be either NO or BASIC. If you specify BASIC, a valid CICS userID and password must be provided when the CICS region is added to the ROCI configuration file. If you already have a TCPIPSERVICE definition installed in the CICS region that is compatible with the above criteria, no new TCPIPSERVICE definition is required; the existing TCPIPSERVICE IP address and port number can be provided to ROCI when you add this CICS region to the configuration file. If you must define a new TCPIPSERVICE RDO entry, see your MVS TCP/IP systems programmer for an IP address and port number to use. 64 Xpediter/CICS Advanced Configuration Guide 65 Specifying Xpediter Service Provider Parameters This section describes how to configure and administer the Xpediter Service Provider. It also lists the Service Provider versions compatible with various Xpediter releases. The Xpediter Service Provider address space must be active before initialization of Xpediter/CICS. Roles Involved The following person is required: • Xpediter/CICS Installer. Overview The Xpediter Service Provider execution parameters allow a site to assign the MVS Subsystem Identifier and define the address space and its operational characteristics. The default values supplied by Compuware listed in Table 10 are appropriate for all but the largest sites. Table 10. Xpediter Service Provider Symbolic Parameters Symbolic Default Minimum Maximum Parameter Parameter Value Value Value Description ARM Blank N/A N/A Set value to ARM to enable Xpediter Service Provider participation with Automatic Restart Management. SSID XDSS N/A N/A MVS subsystem identifier DESCSP 1 MB 256 KB 250 MB Data Descriptor Subpool size COMSP 20 MB 10 MB 250 MB Common Data Subpool size THREADS 12 2 255 Task thread count TRACE 512 KB 128 KB 8 MB Internal trace table size OVERRIDE N/A N/A N/A Subsystem OVERRIDE mode modifier DEBUG N/A N/A N/A Subsystem DEBUG mode modifier XMTASKS 128 32 8160 Cross Memory task count PORT Blank 1 65535 Port number to listen on. Assigned by TCP systems programmer. MEMBER Blank N/A N/A Name of member in TPCONFIG partitioned dataset that identifies all Service Providers participating in the same CICSPlex. The Data Descriptor Subpool (DESCSP) and the Common Data Subpool (COMSP) are used in a Dynamic MRO Environment with CPSM. Refer to “Installation in a CPSM Dynamic Routing Environment” for more information. The Data Descriptor Subpool resides in the Xpediter Service Provider address space and warehouses debugging information required for dynamically routing transactions to the appropriate CICS region. The Common Data Subpool resides in the Xpediter Service Provider address space and warehouses common data and result sets for dynamically routing transactions to the appropriate CICS region. 14 66 Xpediter/CICS Advanced Configuration Guide The Task Thread count parameter limits the number of parallel tasks utilizing the Xpediter Service Provider within a CICS address space (Service Requester). The storage for each Task Thread is allocated in EPVT and is unique for each connected Service Requester address space. The Internal Trace Table tracks cross memory processing between the Xpediter Service Provider and the Service Requester address spaces. The OVERRIDE and DEBUG mode modifiers allow for initialization bypass processing and subsystem connection/disconnection state analysis. These modes should only be used under the direction of Xpediter/CICS Customer Support. If you limit the amount of extended private (EPVT) allocated to an address space via IEFUSI or IEALIMIT, special considerations apply to prevent initialization errors of the Xpediter Service Provider address space. Tasks Perform the following tasks to configure the Xpediter Service Provider. Task 14.1 Configure Service Provider Usage of the TP Configuration File The Xpediter TP configuration file (TPCONFIG) is used for two purposes: • To identify Xpediter Service Providers that are to share CICSPlex information • To identify all of the CICS regions that should be contacted by the Batch Interface to Xpediter/CICS NEWCOPY. For more information, see “Batch Interface to Xpediter/CICS NEWCOPY”. Efficiency Considerations Technically, each member of the TPCONFIG partitioned dataset may contain entries for both possible uses mentioned above. This is because each record within a member starts with a record identifier, and records with an identifier for a different purpose are ignored. However, even though it is technically feasible to have all of the information in one member, doing so would be inefficient. Even assuming shared DASD that all required LPARs can access, lumping all Service Provider (XDSS) records into one TPCONFIG member would cause the Xpediter Service Providers to communicate unnecessary data to other Service Providers outside of their CICSPlex, and force them to maintain the unnecessary data received from those outside Service Providers. For efficiency, Compuware recommends that Service Provider records be grouped in TPCONFIG members named for each CICSPlex used at your site, with one TPCONFIG member per CICSPlex. You will need multiple TPCONFIG dataset “clones” if shared DASD cannot be accessed by all required LPARs. Service Provider Record Identifiers Records in an TPCONFIG member with an asterisk in position one are considered comment records and are ignored. Records that have a blank in position one are scanned for a following record identifier. The record identifier for Xpediter Service Provider records is XDSS. Each Xpediter Service Provider that controls any portion of a CICSPlex should have a record in the member that represents that CICSPlex. Following the XDSS record identifier are: • • • • one or more blanks the PORT number for that Service Provider to listen on one or more blanks the IP Address for that Service Provider. Specifying Xpediter Service Provider Parameters 67 The PORT number should be assigned by your TCP Systems Programmer. If a Domain Name Server is available for GETHOSTBYNAME calls, then the Domain Name may be specified instead of the IP Address. Task 14.2 Implement Automatic Restart Management (ARM) Support The Xpediter Service Provider’s ARM execution parameter value must be set to ARM in the XDSSPROC to implement ARM support. For details, see “Xpediter Service Provider PROC and JCL” below. The Xpediter Service Provider should be assigned to the IBM restart level 1 (SYSLVL1), which will guarantee the Service Provider is available for the CICS regions which are assigned to the IBM restart level 2 (SYSLVL2). The Xpediter Service Provider will only restart on address space level failures, not LPAR failures, which allows for the same subsystem identifier (SSID) across the Sysplex. The element name that is utilized by the Xpediter Service Provider is XSP_ssid_mvsid where ssid is the four-character Subsystem Identifier for the Xpediter Service Provider, and mvsid is the four-character MVS identifier utilized System Management Facility (SMF). Xpediter Service Provider PROC and JCL The Xpediter Service Provider can be executed as a started task or as a batch job. If the Service Provider is started during the IPL process and gains control before TCP/IP has started, then the TCP link between Service Providers will not be established automatically, and an error message (XSP3002E DBUGTCP cannot locate TCP/IP) will be written to the Service Provider JESLOG. If this scenario occurs, you can issue new Operator Command INITTCP to manually establish the TCP link between Service Providers after TCP/IP has been started. Perform the applicable following task to configure the Xpediter Service Provider as either a started task or as a batch job. Task 14.3 Executing as a Started Task The PROC in member XDSSPROC provided in CPWR.cMXD170.SMXDSAMP (where c represents the CICS release) (Figure 19) is used to execute the Xpediter Service Provider as a started task. 68 Xpediter/CICS Advanced Configuration Guide Figure 19. Sample PROC to Execute the Xpediter Service Provider as a Started Task //XDSSPROC PROC SSID=XDSS, // DESCSP=512KB, // COMSP=20MB, // THREADS=12, // XMTASKS=128, // TRACE=128KB, // MEMBER=, <== Delete if not using TPCONFIG. // PORT=, <== Delete if not using TPCONFIG. // OVERRIDE=, // DEBUG=, // ARM= //********************************************************************* //* * //* * //* C O M P U W A R E C O R P O R A T I O N * //* * //* X P E D I T E R S e r v i c e P r o v i d e r * //* --------------- ------------- --------------* //* * //* * //* This Procedure contains the JCL required to execute the Xpediter * //* Service Provider Subsystem. The Xpediter Service Provider can * //* be executed as a Started Task (STC) or a Batch Job (Batch). The * //* following describes the parameters used to configure the Xpediter * //* Service Provider address space, for a complete explanation see * //* the Xpediter/CICS Installation Guide. * //* * //* New in release 8.3; the Service Provider can now be connected to * //* other Service Providers on other LPARs via TCP. This new optional * //* capability allows Xpediter/CICS to support CP/SM environments * //* that include multiple LPARs. If you don't need this optional * //* capability, then delete parameters MEMBER and PORT as well as the * //* DD statement for TPCONFIG and the STEPLIB concatenation of the * //* TCPIP loadlib. * //* * //* Parameter Description of parameter value * //* --------- ---------------------------------------------------- * //* SSID Subsystem Identifier * //* DESCSP Descriptor Storage Subpool Size * //* COMSP Common Storage Subpool Size * //* THREADS Local Address Space Thread Limit * //* XMTASKS Subsystem Cross Memory Task Limit * //* TRACE Internal Trace Table Size * //* MEMBER Dataset TPCONFIG member name to read *NEW 8.3* //* PORT TCP Port Number for Service Provider *NEW 8.3* //* OVERRIDE Subsystem Emergency Override Parameter * //* DEBUG Subsystem Diagnostic Mode Parameter * //* ARM Automatic Restart Manager Enable Parameter * //* * //********************************************************************* //DBUGSTC EXEC PGM=DBUGSTC,PARM=(&SSID, // 'DESCSP=&DESCSP', // 'COMSP=&COMSP', // 'THREADS=&THREADS', // 'XMTASKS=&XMTASKS', // 'TRACE=&TRACE', // 'MEMBER=&MEMBER', <== Delete if not using TPCONFIG. // 'PORT=&PORT', <== Delete if not using TPCONFIG. // '&OVERRIDE', // '&DEBUG', // '&ARM') //STEPLIB DD DISP=SHR,DSN=CPWR.cMXDnnn.SMXDAUTH <== Check DSNAME // DD DISP=SHR,DSN=TCPIP.SEZALOAD <== Optional, Check DSNAME //TPCONFIG DD DISP=SHR,DSN=XPED.TPCONFIG <== Optional, Check DSNAME Specifying Xpediter Service Provider Parameters 69 Substitute parameter values on the MVS operator START command. See Figure 19 for an explanation of valid values. The STEPLIB DD statement must be supplied, and it must point to the dataset to which the Xpediter/CICS APF authorized modules were linked. The default is CPWR.cMXD170.SMXDAUTH where c varies by CICS release. Task 14.4 Executing as a Batch Job The JCL in member XDSSJCL provided in SMXDSAMP member (Figure 20) is used to execute the Xpediter Service Provider as a batch job. 70 Xpediter/CICS Advanced Configuration Guide Figure 20. Sample JCL to Execute the Xpediter Service Provider as a Batch Job // YOUR JOB CARD HERE //********************************************************************* //* * //* * //* C O M P U W A R E C O R P O R A T I O N * //* * //* X P E D I T E R S e r v i c e P r o v i d e r * //* --------------- ------------- --------------* //* * //* * //* This Job executes the Xpediter Service Provider Subsystem. The * //* following describes the parameters used to configure the Xpediter * //* Service Provider address space, for a complete explanation see * //* the Xpediter/CICS Installation Guide. * //* * //* * //* New in release 8.3; the Service Provider can now be connected to * //* other Service Providers on other LPARs via TCP. This new optional * //* capability allows Xpediter/CICS to support CP/SM environments * //* that include multiple LPARs. If you don't need this optional * //* capability, then delete parameters MEMBER and PORT as well as the * //* DD statement for TPCONFIG in the PROC. * //* * //* * //* Parameter Description of parameter value * //* --------- ---------------------------------------------------- * //* SSID Subsystem Identifier * //* DESCSP Descriptor Storage Subpool Size * //* COMSP Common Storage Subpool Size * //* THREADS Local Address Space Thread Limit * //* XMTASKS Subsystem Cross Memory Task Limit * //* TRACE Internal Trace Table Size * //* MEMBER Dataset TPCONFIG member name to read *NEW 8.3* //* PORT TCP Port Number for Service Provider *NEW 8.3* //* OVERRIDE Subsystem Emergency Override Parameter * //* DEBUG Subsystem Diagnostic Mode Parameter * //* ARM Automatic Restart Manager Enable Parameter * //* * //********************************************************************* //XDSUBSYS EXEC XDSSPROC, // SSID=XDSS, // DESCSP=512KB, // COMSP=20MB, // THREADS=12, // XMTASKS=128, // TRACE=128KB, // MEMBER=, <== Delete if not using TPCONFIG // PORT=, <== Delete if not using TPCONFIG // OVERRIDE=, // DEBUG=, // ARM= // Replace the JOB card, substitute parameter values on the XDSSPROC procedure statement, and submit the JCL. See Table 10 for an explanation of valid XDSSPROC parameter values. The STEPLIB DD statement in procedure XDSSPROC (see Figure 19) must point to the dataset to which the Xpediter/CICS APF authorized modules were linked. The default is SMXDAUTH member. 71 Configuring Restricted Operating Modes In addition to its standard operating mode, Xpediter/CICS can be activated in three restricted modes of operation: • Diagnosis Mode • Utilities Mode • Diagnosis/Utilities Mode. These modes allow a site to tailor its Xpediter implementation to suit the processing integrity and response time requirements of its various CICS regions. In this way a customer can eliminate unnecessary processing overhead while preventing any potentially disruptive user activity. To display a complete list of commands available for the current mode, type HELP MODE and press Enter. Table 11 provides a matrix of the Xpediter functions available in each of the three modes. Roles Involved The following person is required: • Xpediter/CICS Installer. Task 15.1 Configure Restricted Operating Modes Select and configure the desired restricted operating mode based on the following sections. Diagnosis Mode In Diagnosis Mode, Xpediter/CICS is fully enabled, and primary functions such as monitor and trace are available. Users are prevented, however, from doing anything that could alter the execution path of a program. This is accomplished in the following ways: • Storage values on the Memory Display screens (2.2 and 9.2) and the DSECTs screens (2.D and 9.D) cannot be updated. • Register values and resume offsets cannot be updated. • Commands such as GOTO, VERIFY, and SKIP that reroute program flow cannot be used. Diagnosis Mode gives users access to all of Xpediter’s problem diagnosis and storage protection capabilities, without the risk of data integrity violations in fully secured environments such as quality control or production regions. The global table parameter OKUPDT contains three separate ON or OFF values that correspond to the Xpediter/CICS startup transactions XPED, XPRT, and XPSP. If a value is set to OFF, entering the corresponding transaction will start Xpediter in Diagnosis Mode. Access to Xpediter/CICS update capabilities can be limited to system programmers by setting OKUPDT to OFF,OFF,ON and using an external security manager such as RACF to restrict access to the XPSP transaction. Sites utilizing Xpediter’s global parameter override facility must also restrict access to the XSIT transaction. To prevent delays in response-time-critical regions, Compuware recommends that entries made on the Trap Summary screen (1.6 or 9.6) be as specific as possible. The USERID, NETNAME, TERM, TRAN, PROGRAM, CLIENT IP, SERVER IP, and PORT columns should contain few, if any, wildcard characters. Users should not set global traps made up of all wildcard characters in every column. 15 72 Xpediter/CICS Advanced Configuration Guide The mode indicator MODE:DIAG is displayed in the upper left-hand corner of all Xpediter screens when the product is running in Diagnosis Mode. Utilities Mode In Utilities Mode, only the file utility, task storage display, storage display facility, and source listing utility are functional. Xpediter’s CICS exits are disabled. Utilities Mode gives users access to Xpediter/CICS utilities in response-time-critical environments, such as production CICS regions, without incurring the overhead of Xpediter’s exits and sacrificing only Xpediter’s debugging capabilities. Storage can be viewed and modified on the Memory Display screens (2.2 and 9.2), the Task Storage Display screen (2.S), and the DSECTs screens (2.D and 9.D). Files and databases can also be viewed and modified with Xpediter’s file utility, and program listings can be viewed on the Source Listing screen (2.L). Trap, trace, and monitor functions, however, are unavailable in Utilities Mode. • Without its CICS exits, Xpediter cannot trap internal abends. If an internal abend occurs while in Utilities Mode, the user will receive a generic CICS abend message. Generate an SVC dump, then contact Xpediter/CICS Customer Support (see “Customer Support”). • Compuware recommends that customers using Xpediter/CICS in a production environment configure the file utility for read only access. This can be done by using the default global table, DBUGGBLP, or global override sample, XDGB00, supplied with the product. Xpediter’s file utility operates as a fully conversational CICS transaction, similar to other interactive file manipulation products. Record locks and enqueues may be held for long periods of time. If your site will be using the file utility to update records in a high-volume production environment, Compuware recommends using caution to avoid transaction abends due to record deadlocks. Care should also be taken in updating common or control records regardless of transaction volume. Utilities Mode is designated by setting the global table parameter UTILMOD to YES (the default in DBUGGBLP). Xpediter will then run in Utilities Mode for the entire region, and the Xpediter IVP will issue the following warning message when the product is initialized: XPEDITER/CICS IS SET TO INITIALIZE IN UTILITIES ONLY MODE. TRAP, TRACE, AND PROTECT WILL NOT BE AVAILABLE. The UTILMOD global table parameter can be overridden by shutting down Xpediter with the XPOF transaction and restarting it with an XPSP# transaction. Only the XPSP transaction will accept the # override parameter. Sites utilizing Xpediter’s global parameter override facility can also override the UTILMOD parameter by modifying their input dataset and running the XSIT transaction. The mode indicator MODE:UTIL is displayed in the upper left-hand corner of all Xpediter screens when the product is running in Utilities Mode. Diagnosis/Utilities Mode The most restrictive operating mode is a combination of Diagnosis and Utilities modes. Diagnosis/Utilities Mode lets a site implement Xpediter/CICS in production with all the restrictions of Utilities Mode, while also restricting update capabilities as in Diagnosis Mode. A user in Diagnosis/Utilities Mode cannot activate trap, trace, or monitor and cannot update storage. This mode does provide access to Xpediter’s file utility and source listing utility. The user can also view storage on the Memory Display screen (2.2 or 9.2), the Task Storage Display screen (2.S), and the DSECTs screen (2.D or 9.D). Diagnosis/Utilities mode is designated by setting the global table parameter OKUPDT to OFF for the desired Xpediter transaction(s) and setting the UTILMOD global table parameter to YES. The mode indicator MODE:DIAG/UTIL is displayed in the upper left-hand corner of all Xpediter screens when the product is running in Diagnosis/Utilities Mode. Configuring Restricted Operating Modes 73 Available Functions Table 11 provides a matrix of the Xpediter functions available in each of the three restricted operating modes. The bullets in each mode column indicate the corresponding functions available while operating in that mode. Utilities Mode Diagnosis/Utilities Mode Update program register values l Update program resume offsets l Reroute program flow with SKIP and GOTO commands l File utility (subject to normal global table restrictions) l l l l Source listing utility l l l l Task Storage Display screen (2.S) l l l l View storage on Memory Display screens (2.2 and 9.2) l l l l Update storage on Memory Display screens (2.2 and 9.2) l View storage on DSECTs screens (2.D and 9.D) l Update storage on DSECTs screens (2.D and 9.D) l View variables in keep window l Update variables in keep window l View variables on Program Storage screen (2.3) l Update variables on Program Storage screen (2.3) l Modify Assembler instructions with VERIFY command l Trap l l Trace l l Protect l l Xpediter Function Standard Mode Diagnosis Mode Table 11. Available Xpediter/CICS Functions by Operating Mode l l l l l l l l 74 Xpediter/CICS Advanced Configuration Guide 75 Configuring Automatic Session Termination This section explains how to configure Xpediter’s automatic session termination. This feature is also available to transaction routing users. Roles Involved The following person is required: • Xpediter/CICS Installer. Overview Normally, an Xpediter/CICS user will terminate their session before leaving CICS. But if a terminal is disconnected, signed off, or logged off while an Xpediter session is still active, the ID of that terminal will remain assigned to the abandoned (but still active) session. Because another terminal logging on could be assigned the same ID, it is possible for a user to be assigned an active Xpediter session that they are not aware of. The first user may have left the session with program breakpoints set and no sure way of reaccessing the same session to release them. Xpediter/CICS can be set up to automatically terminate an active debugging session when the terminal is signed off, logged off, and/or disconnected. XSNOFF provides session termination when an EXEC CICS SIGNOFF command is issued. Terminal autoinstall sites can modify their autoinstall exit to terminate any active Xpediter sessions when a user logs off from CICS. XSNOFF and the terminal autoinstall exit each accomplish automatic session termination by invoking the Xpediter transaction XPN0. This transaction starts program DBUGEND0, which deals with session termination in transaction routing environments. DBUGEND0 then starts program DBUGEND, which terminates any active Xpediter/CICS sessions assigned to that terminal’s ID. Xpediter’s automatic session termination writes messages to transient data destination CSMT when any of the following occur: • A session is successfully terminated. • A session is not terminated because the DISCONN parameter has been set to NO in the DBUGGBL global table. • DBUGEND encounters an error while performing command-level RETRIEVE or GETMAIN commands. Tasks To install Xpediter’s automatic session termination feature, follow the instructions below. Task 16.1 Enable Automatic Session Termination Xpediter/CICS automatic session termination can be established in either or both of the following ways: 16 76 Xpediter/CICS Advanced Configuration Guide • By enabling the signoff exit, XSNOFF. This exit is entered after a terminal user signs off from CICS. XSNOFF will terminate any active Xpediter debugging sessions assigned to that terminal. There are certain disadvantages to using the XSNOFF exit: • The XSNOFF exit prevents you from using Xpediter to debug programs that contain EXEC CICS SIGNOFF commands. • XSNOFF does not terminate debugging sessions when a terminal is disconnected. • For sites using terminal autoinstall, by modifying the exit DFHZATDX (or whatever terminal autoinstall exit is being used). When a terminal is logged off, the modified exit will terminate any active Xpediter debugging sessions assigned to that terminal. 1. To use either or both methods of automatic session termination, first do the following: a. Check the values of the following DBUGGBL global table parameters: • XPN0 - This is the transaction ID invoked at session termination. The default is XPN0. If a different value is used, that value instead of XPN0 must be defined to CICS as part of step b, below. • DISCONN - This parameter must be set to YES for Xpediter to terminate active debugging sessions when a terminal is disconnected or logged off. The default is YES. b. Ensure that the following resources have been defined to CICS (during the installation configuration in the applicable “Update the CICS Resource Definitions” task in the Xpediter/CICS Installation Guide): • Program DBUGEND0. • Program DBUGEND. • Program DBUGEND1. (Optional. See “Configure For Transaction Routing Users”.) • Transaction XPN0 (or whatever transaction is specified for the XPN0 parameter in the DBUGGBL global table). • Transaction XPND. 2. Ensure that programs DBUGEND and DBUGEND0 are link edited into the CPWR.cMXD170.SMXDOccL library. 3. To enable the XSNOFF exit for automatic session termination at terminal signoff, change the value of the UXSNOFF parameter in the DBUGGBL global table to YES. The default is NO. See “Standard Global Table DBUGGBL”. When the XSNOFF exit starts transaction XPN0, CICS assigns to it the userID that is defined in the DFLTUSER system initialization parameter. If you enable the XSNOFF exit and want to secure the XPN0 transaction through your external security manager, you must allow the DFLTUSER userID to have access to transaction XPN0 and program DBUGEND0. 4. If your site uses transaction routing, refer to “Configure For Transaction Routing Users”. 5. Sites using terminal autoinstall that want automatic session termination when terminals are logged off should perform the following: a. Ensure that dynamic transaction backout is enabled in the region. If dynamic transaction backout is not enabled, transaction CATD may experience an ASPE abend when the terminal is disconnected. If this occurs, failure of terminal control initialization will prevent CICS from being warm started. Configuring Automatic Session Termination 77 b. Modify the terminal autoinstall exit DFHZATDX (or whatever exit is used at your site) as follows: If your site uses a different autoinstall exit, its name can be found in the SIT parameter AIEXIT. 1. Add the following line of code to DFHZATDX in the “Delete Processing Section” after the IBM Put Delete Code Here comment: EXEC CICS START INTERVAL (0) TRANSID (’XPN0’) FROM (DELETE_TERM_ID) • Add the above line in the section labeled DELETE_TERMINAL. Do not add the line to the section labeled DELETE_SHIPPED_TERMINAL. • Consider adding “NOHANDLE”—or other appropriate condition handling—for exception conditions such as TRANSIDERR. 2. Reassemble and link edit DFHZATDX (or whatever VTAM terminal autoinstall exit is used at your site). Task 16.2 Configure For Transaction Routing Users Table DBUGEND1 is a CSECT with DC statements defining all the transactions to start when terminating Xpediter sessions in a static transaction routing environment. The table should contain all the transaction IDs on the local system (TOR) corresponding to the remote transaction XPND. If table DBUGEND1 is not present or does not contain any transaction IDs, transaction XPND is run in the local system when a terminal is logged off or signed off. Transaction routing users with any release of CICS should perform the following procedure: 1. Assemble and link edit a table named DBUGEND1 (see Figure 21) in the Xpediter load library. The DBUGEND1 table must not be linked with command level stubs. Figure 21. DBUGEND1 Table DBUGEND1 * CSECT DC DC DC DC -- TRANS ID DEFN TABLE -- CL4’XPN1’ CL4’XPN2’ CL4’XPN3’ CL4’XPND’ Tran Tran Tran Tran id id id id XPN1 XPN2 XPN3  XPND 1  * END 1Add the last entry shown only if you will be doing debugging in a TOR and require automatic session termination there. Changes or new definitions are not required on the remote CICS regions (AOR) if you have not changed the default Xpediter/CICS transaction names. 78 Xpediter/CICS Advanced Configuration Guide 2. Add the following transaction resource definitions for the local CICS region (TOR): CEDA DEFINE TRANSACTION(XPN1) GROUP(XPEDR170) REMOTESYSTEM(CIC1) REMOTENAME(XPND) DYNAMIC(NO) CEDA DEFINE TRANSACTION(XPN2) GROUP(XPEDR170) REMOTESYSTEM(CIC2) REMOTENAME(XPND) DYNAMIC(NO) CEDA DEFINE TRANSACTION(XPN3) GROUP(XPEDR170) REMOTESYSTEM(CIC3) REMOTENAME(XPND) DYNAMIC(NO) . . . CEDA DEFINE PROGRAM(DBUGEND1) GROUP(XPEDR170) LANGUAGE(ASM) EXECKEY(CICS) 79 Configuring the DB2 Format Utility The DB2 format utility (DBSQLUTL) lets you format SQL commands created with the Xpediter/CICS File Utility for you to include in your Assembler, C, COBOL, and PL/I programs. This section describes the DBSQLUTL utility, its use, the available commands and options, and the format utility dataset requirements. Roles Involved The following person is required: • Xpediter/CICS Installer. Task 17.1 Use DBSQLUTL to Format SQL Commands Procedure library member DBCFORSQ contains sample JCL for the DBSQLUTL utility. DBCFORSQ formats all members on DBUGSQL into a COBOL format. You can tailor the JCL to fit your needs by modifying the DD statements and entering the appropriate commands and parameters. The DBSQLUTL program terminates processing when end-of-file is reached. DBSQLUTL Utility Commands This section describes the following DBSQLUTL commands and their corresponding parameters: • • • • • • • COPY DELETE DIRECTORY FORMAT INITIALIZE PRINT REORG. The syntax diagrams show the parameters, valid abbreviations, and syntax. You can enter correct syntax for each of the commands. You may enter the commands in any column of the command card or line. One or more spaces must separate the command from its parameter, and commas or spaces separate parameters. Some parameters may include an asterisk (*) as a wildcard character. For example, entering PROGRAM=ABC* specifies all programs that begin with ABC. 17 80 Xpediter/CICS Advanced Configuration Guide COPY The COPY command copies the selected members from the input file specified by FROMDD to the output file specified by TODD. No changes are made to the members during the copy operation. To produce a printed listing of each member, specify the COPYP command with the same syntax. FROMDD Specifies the DD name of the source dataset. Valid entries are one to eight alphanumeric characters. The default value is SQLIN. TODD Specifies the DD name of the target dataset. Valid entries are one to eight alphanumeric characters. Output may be to another VSAM dataset, to a partitioned dataset, or to a sequential dataset. The default value is SQLOUT. MEMBER Specifies the name of the member to be copied. Valid entries are one to eight alphanumeric characters. Wildcard characters may be used. REPLACE Optional parameter that specifies members with duplicate names on TODD are to be replaced when found. This parameter applies only if copying to a VSAM or partitioned dataset. Valid entries are YES and NO. The default value is NO. DSORG Optional parameter that specifies the dataset organization for TODD. Valid entries are: VS (default): VSAM PO: Partitioned organization PS: Physical sequential. DELETE (DEL) The DELETE command deletes the selected members from the dataset specified by TODD. TODD Specifies the DD name of the target dataset. Valid entries are one to eight alphanumeric characters. The default value is SQLOUT. MEMBER Specifies the name of the member to be deleted. Valid entries are one to eight alphanumeric characters. Wildcard characters may be used. Configuring the DB2 Format Utility 81 DSORG Specifies the dataset organization for TODD. Valid entries are: VS (default): VSAM PO: Partitioned organization. DIRECTORY (DIR) The DIRECTORY command produces a directory listing for the specified dataset. FROMDD Specifies the DD name of the source dataset. Valid entries are one to eight alphanumeric characters. The default value is SQLIN. FORMAT (FOR) The FORMAT command reads the selected members from the input file (FROMDD), formats it according to the rules for the language specified by the LANGUAGE parameter, and writes the formatted member to the file identified by TODD. FORMAT appends an EXEC SQL statement to the beginning of the member and modifies it for inclusion in an application program. To produce a printed listing of the member in its formatted form, specify the FORMATP command with the same syntax. FROMDD Specifies the DD name of the source dataset. Valid entries are one to eight alphanumeric characters. The default value is SQLIN. TODD Specifies the DD name of the target dataset. Valid entries are one to eight alphanumeric characters. Output may be to a partitioned or sequential dataset. The default value is SQLOUT. MEMBER Specifies the name of the member to be copied. Valid entries are one to eight alphanumeric characters. Wildcard characters may be used. REPLACE Specifies whether members with duplicate names on TODD are replaced if found. This parameter applies only if copying to a partitioned or sequential dataset. Valid entries are YES and NO. The default value is NO. 82 Xpediter/CICS Advanced Configuration Guide LANGUAGE Specifies the source language used to format the member. Valid entries are ASM, C, COBOL, and PLI. The default value is COBOL. DSORG Optional parameter that specifies the dataset organization for TODD. Valid entries are: VS: VSAM PO: Partitioned organization PS: Physical sequential. FORMATP Sample Report A sample report from the FORMATP command is shown in Figure 22. A list of field explanations are provided after the figure. Other reports follow a similar format. Figure 22. Sample FORMATP Report DBSQLUTL DB2 SYSTEM QUERY LANGUAGE FORMAT UTILITY DATE FORMATP FROMDD=VSIN TODD=PDSOUT MEMBER=* """"""""""""""""""" REPLACE=YES MEMBERS FORMATTED FROM CWV.CWX0213.SQLXFER TO CWX0213.PDS.OUT COBOL FORMAT  HOMED REPLACED  EXEC SQL SELECT TIMESTAMP_FIELD,DATE_FIELD,VARCHAR_FIELD FROM CWX0030.COMPOSITE_TABLE WHERE DATE_FIELD > ’01/01/1990’ ORDER BY CWX0030.COMPOSITE_TABLE.TIMESTAMP_FIELD DESC END EXEC. 0001 MEMBERS PROCESSED 0000 MEMBERS WERE BYPASSED *** DBSQLUTL FORMATP SERVICES COMPLETED *** DBSQLUTL PROCESSING COMPLETE Command Line Displays an image of the command line read from SYSIN for the command. All data elements following a command are interpreted as parameters related to that command, with the next valid command functioning as the delimiter. If any of the parameters are invalid, the command is ignored and processing continues with the next valid command. Members Formatted Identifies the source (FROM) and target (TO) dataset names, and the language that the member is formatted in. The dataset names are derived from the DD statements associated with the FROMDD and TODD parameters. Member Name Appears with the action taken; for example, added or replaced. The action is listed only if formatting to a partitioned dataset. Member Listing Prints an image of the formatted output member. Configuring the DB2 Format Utility 83 Members Processed Count Identifies the number of members read from the source dataset and written to the target dataset. If formatting is to a partitioned dataset, this count reflects the number of members added or replaced in the directory. If formatting is to a sequential dataset, this count reflects the number of members from the input dataset that are formatted and written to the sequential file. Members Bypassed Count Identifies the number of members read from the source dataset that is not written to the target dataset. This count is shown only if formatting to a partitioned dataset. A nonzero count results when the selected members already exist on the output dataset and REPLACE=NO is specified. Services Completed Prints a standard message upon completion of each command. INITIALIZE (INIT) The INITIALIZE command prepares the DBUGSQL file for use by the Xpediter/CICS File Utility. TODD Specifies the DD name of the dataset to be initialized. Valid entries are one to eight alphanumeric characters. The default value is SQLOUT. PRINT The PRINT command produces a printed listing of the selected member. FROMDD Specifies the DD name of the source dataset. Valid entries are one to eight alphanumeric characters. The default value is SQLIN. MEMBER Specifies the name of the member to be printed. Valid entries are one to eight alphanumeric characters. Wildcard characters may be used. You cannot specify the MEMBER parameter when printing from a sequential dataset. 84 Xpediter/CICS Advanced Configuration Guide REORG The REORG command reorganizes the DBUGSQL file. Records from the file are temporarily copied to the file specified by SYSUT1 and erased from DBUGSQL. When all records have been copied, SYSUT1 is reopened as input for copying the records back to DBUGSQL. TODD Specifies the DD name of the dataset to be reorganized. Valid entries are one to eight alphanumeric characters. The default value is SQLOUT. DBSQLUTL Format Utility Dataset Requirements Table 12 provides a summary of the datasets needed for running the DBSQLUTL utility. Table 12. DBSQLUTL Format Utility Dataset Requirements COMMAND FROMDD TODD INITIALIZE VSAM COPY VSAM VSAM PDS Sequential FORMAT VSAM VSAM PDS Sequential PRINT VSAM PDS Sequential DIRECTORY VSAM PDS DELETE VSAM PDS REORG VSAM Partitioned and sequential datasets have the following requirements: • Record format is fixed block (RECFM=FB). • Logical record length and block size cannot exceed 32768: – LRECL=nnnnn, where 32768 is the maximum value – BLKSIZE=nnnnn, where 32768 is the maximum value. VSAM datasets have the following requirements: • File organization is key sequence dataset (KSDS). • Record identification is KEYS(8,0). • RECORDSIZE(30008,30008). DD statements for SYSIN and SYSPRINT are required for parameter input and report generation. Data control block (DCB) information is not required. Configuring the DB2 Format Utility 85 Supply a DD statement for SYSUT1 when using the REORG command. If DISP=NEW is specified, DCB information is not required. If the dataset is allocated in a prior step, the DCB parameter must specify: RECFM=F, LRECL=30008, BLKSIZE=30008 86 Xpediter/CICS Advanced Configuration Guide 87 Configuring Intercommunication Facilities Xpediter/CICS functions in environments that use various CICS intercommunication facilities, including: • Multiregion operation (MRO) • InterSystem Communication (ISC) • Dynamic Transaction Routing (DTR). Specific installation steps may be necessary to use Xpediter/CICS most efficiently in these environments. See the Xpediter/CICS Reference Manual for specific information on debugging in an intercommunication environment. Roles Involved The following person is required for this milestone: • CICS Administrator. This section describes installation steps under the following topics: • “ Installing in a Static Routing Environment” • “ Installing in a CPSM Dynamic Routing Environment” • “ Installation in a Non-CPSM Dynamic Routing Environment”. The use of CRTE when using Xpediter in an MRO or ISC environment is not recommended. For more information, see the section “MRO and ISC Debugging Considerations” in the chapter entitled “Intercommunication Considerations” in the Xpediter/CICS Reference Manual. Xpediter global parameter CRTEOK=NO can be specified to prevent starting an Xpediter session within a CRTE explicit routing session. Perform the tasks in the applicable section below to configure Xpediter’s intercommunication facilities. Installing in a Static Routing Environment To install Xpediter/CICS in an intercommunication environment, you must install it in each AOR region and add resource definitions in the TOR. Task 18.1 Install Xpediter/CICS in Each Region Install Xpediter/CICS in each region after you have performed the steps in “Configuring Xpediter/CICS”. The Xpediter/CICS programs, transactions, and files can have the same name in each region. If you do not change the Xpediter/CICS transaction names, you do not have to regenerate the global 18 88 Xpediter/CICS Advanced Configuration Guide parameter table. You can enter Xpediter/CICS in any region and always start it in that region, regardless of the transaction routings in effect. Do not use function shipping to define Xpediter/CICS listing files as remote resources. However, the same files can be defined in each region to allow access to each source listing at all times. Task 18.2 Add Transaction Definition Entries in the TOR Xpediter/CICS works best in intercommunication environments if it is defined to use the CICS transaction-routing feature. To do this, add the resource definitions shown to the TOR for each remote region in which Xpediter/CICS is used. Be sure to substitute the appropriate TRANSACTION and REMOTESYSTEM values for each entry. CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA CEDA DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE TRANSACTION(DBX1) TRANSACTION(DMA1) TRANSACTION(NEW1) TRANSACTION(XDB1) TRANSACTION(XIV1) TRANSACTION(XLO1) TRANSACTION(XPE1) TRANSACTION(XPN1) TRANSACTION(XPO1) TRANSACTION(XPR1) TRANSACTION(XPS1) TRANSACTION(XSI1) TRANSACTION(DBX2) TRANSACTION(DMA2) TRANSACTION(NEW2) TRANSACTION(XDB2) TRANSACTION(XIV2) TRANSACTION(XLO2) TRANSACTION(XPE2) TRANSACTION(XPN2) TRANSACTION(XPO2) TRANSACTION(XPR2) TRANSACTION(XPS2) TRANSACTION(XSI2) REMOTENAME(DBXG) REMOTENAME(DMAP) REMOTENAME(NEWC) REMOTENAME(XDBP) REMOTENAME(XIVP) REMOTENAME(XLOG) REMOTENAME(XPED) REMOTENAME(XPND) REMOTENAME(XPOF) REMOTENAME(XPRT) REMOTENAME(XPSP) REMOTENAME(XSIT) REMOTENAME(DBXG) REMOTENAME(DMAP) REMOTENAME(NEWC) REMOTENAME(XDBP) REMOTENAME(XIVP) REMOTENAME(XLOG) REMOTENAME(XPED) REMOTENAME(XPND) REMOTENAME(XPOF) REMOTENAME(XPRT) REMOTENAME(XPSP) REMOTENAME(XSIT) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID1) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) REMOTESYSTEM(SYSID2) If this environment includes Xpediter/Code Coverage, add resource definitions for XVCC, XVSC and XVSI as shown. CEDA CEDA CEDA CEDA CEDA CEDA DEFINE DEFINE DEFINE DEFINE DEFINE DEFINE TRANSACTION TRANSACTION TRANSACTION TRANSACTION TRANSACTION TRANSACTION (XVC1) (XVS1) (XVI1) (XVC2) (XVS2) (XVI2) REMOTENAME REMOTENAME REMOTENAME REMOTENAME REMOTENAME REMOTENAME (XVCC) (XVSC) (XVSI) (XVCC) (XVSC) (XVSI) REMOTESYSTEM REMOTESYSTEM REMOTESYSTEM REMOTESYSTEM REMOTESYSTEM REMOTESYSTEM (SYSID1) (SYSID1) (SYSID1) (SYSID2) (SYSID2) (SYSID2) These entries establish an alias in the TOR for each terminal-associated Xpediter/CICS transaction in each remote CICS region. 1. Type XPEn, XPRn, or XPSn to execute the terminal-associated transactions in the appropriate region. Use transaction routing and the previous table entries. 2. Define the DBXG transaction for transaction routing; it is the target of an EXEC CICS START call. This transaction initiates Xpediter/CICS when an abend is trapped on another terminal. Make sure that ATI=YES for any terminals used as the primary terminal for Xpediter/CICS. Setting ATI=YES for primary terminals allows the system to start the DBXG transaction automatically when a remote abend occurs for all terminals. Configuring Intercommunication Facilities 89 Installing in a CPSM Dynamic Routing Environment The dynamic MRO support provided by Xpediter/CICS requires IBM’s CICSPlex SM (CPSM). Refer to the Xpediter/CICS Release Notes for information on supported releases. To effect dynamic routing of transactions in a CICSPlex, Xpediter/CICS utilizes a CPSM routing exit, DBUGWRAM, which is typically run in a terminal owning region (TOR). This is distinct from the Xpediter/CICS debugger, which normally runs in an application owning region (AOR). The DBUGWRAM exit gains controls via the Global User Exit (GLUE) point XPCFTCH and XPCREQC. After a link is made to CPSM module EYU9WRAM from EYU9XLOP, the Xpediter module DBUGWRAM gains control and determines if the transaction being routed is an Xpediter transaction (XPED, XPSP, etc.) or an application transaction that matches a trap set in Xpediter/CICS. In either of these cases, module DBUGWRAM will route the transaction to an applicable CICS region containing Xpediter/CICS. DBUGWRAM now supports CICSPlex environments that cross LPAR boundaries when using Xpediter/Eclipse. When using Xpediter/Eclipse and starting a debugging session to a TOR, if the XSOC transaction is to be routed to a different LPAR, the code in DBUGWRAM will save the region where XSOC was intended to be routed. Due to the limitations of TCP/IP, the XSOC transaction will remain in a region in the CICSPlex that is running in the same LPAR as the TOR and is also running Xpediter/CICS. The actual debugging session will actually start in the original AOR in which XSOC was originally slated to run. DBUGSOCK, the program associated with XSOC, contains the socket communication code and communicates with the actual Xpediter/CICS debugging code using CICS containers. The debugging code (XDPIMIRS) will run in the AOR in which XSOC was originally slated to run. In the event that Topaz Workbench visualization is being used, or when events such as breakpoints or abends occur, these events are communicated back to the DBUGSOCK LPAR using a new program, DBUGREMS (transaction XSRE). The Xpediter Service Provider keeps track of all active traps within all AORs of each CICSPlex. UserID, Transaction Code, Terminal-ID, Netname, Client IP Address, Server IP Address, and Server Port trap fields are provided by the service provider to DBUGWRAM in the TOR to influence routing. Once routed to an appropriate AOR, all trap fields, including those that did not participate in the routing decision (Program Name, Enhanced Trapping Criteria), determine if the trap is actually matched when an abend and/or breakpoint is hit. Xpediter/CICS module DBUGWRAM also influences CPSM dynamic routing of distributed program links (DPL). Distributed program links, once routed into an AOR, no longer match the trap criteria because of the impact of routing. For example, IP input from TCPIPSERVICE connections have their DPL routing requests influenced correctly by client and/or server IP information. However, when the application program runs in the AOR, its facility is an MRO/ISC session and that program is no longer associated with the client IP address or TCPIPSERVICE. To correct this CICS DPL issue, Xpediter/CICS recognizes DPL-routed work in the AOR and corrects the information used for trapping by obtaining it from Xpediter/CICS Routing Trace records. This process is not foolproof; when multiple DPL requests with the same userID, transaction code, and program name are routed to the same AOR before Xpediter/CICS in that AOR can access its Routing Trace records, the product may obtain incorrect information for some of those DPL requests. One of the features of Topaz Workbench is that it allows debugging of transactions initiated from terminal emulators on the same workstation as the Topaz Workbench debugging session. The user specifies in the Terminal field of traps specified in the Traps tab of the Topaz Workbench launch configuration. In order to support this feature when debugging across LPAR boundaries in a CICSPlex, the cross-LPAR connections between CICS regions on different LPARs must use IP-based connections using IPCONN and TCPIPSERVICE definitions. Regions running on the same LPAR may use CONNECTION and SESSIONS definitions. Failure to use the correct type of connection for crossLPAR communication may cause unexpected results during debugging sessions. 90 Xpediter/CICS Advanced Configuration Guide Installing Resource Definitions The procedure you choose for installing Xpediter/CICS resource definitions in a dynamic MRO environment will depend on whether you want to use Xpediter to trap transactions in both TORs and AORs, or only in AORs. The remote names of the Xpediter transactions in the TOR used for dynamic transaction routing must match the names in the Xpediter global table. Therefore, if you will be using Xpediter to debug applications in both TORs and AORs, you must have two sets of transaction definitions: • One to run locally with transaction IDs matching those in the Xpediter/CICS global table. • One set to run remotely with remote names matching the Xpediter global table. In the following example of transactions defined in the TOR, transaction XPED would run locally in the TOR. Transaction XPER would run remotely in an AOR with a local name of XPED. DEFINE TRANSACTION(XPED) DYNAMIC(NO) DEFINE TRANSACTION(XPER) REMOTENAME(XPED) DYNAMIC(YES) If you do not have a need to run Xpediter/CICS in both the TOR and AOR then the definition DEFINE TRANSACTION(XPED) DYNAMIC(YES) would run the remote transaction XPED in the AOR. Refer to the members provided in SMXDSAMP as described below for complete examples. Task 18.3 Install Xpediter/CICS in TORs and AORs After completing the tasks in “Configure Xpediter/CICS — New Installation” in the Xpediter/CICS Installation Guide, install Xpediter/CICS in your site’s TORs and install and start Xpediter in the AORs. The startup global parameter CICSPLX should be set to NO in each TOR and YES in each AOR. Compuware recommends using PLTPI to start Xpediter/CICS in the AORs. Xpediter’s dynamic routing support will not allow you to start Xpediter in an AOR with the XPED, XPRT, or XPSP transactions. Transaction XPON, which can be separately secured, is provided for this purpose. Do not use function shipping to define Xpediter/CICS listing files as remote resources. However, the same files can be defined in each region to allow access to each source listing at all times. Task 18.4 Replace the Default EYU9WRAM The default EYU9WRAM delivered in the CPSM load library cannot be used with Xpediter’s Dynamic Transaction Routing support. Replace it as follows: 1. Create your own EYU9WRAM or assemble and link the sample distributed with CPSM in the sample library SEYUSAMP. The command level translate of the program requires a parameter of NOPROLOG NOEPILOG. Make sure it is linked AMODE31 and that EYU9WAPI from the CPSM library SEYULOAD is included. Sample JCL (EYU9WRAM) is provided in an SMXDSAMP member. 2. Stop and restart CPSM or recycle CICS. If you do not, TOR support will be unable to route transactions, and the only indication will be a lack of routing messages on Xpediter’s Routing Trace Summary screen (P.4). Task 18.5 Establish TOR Dynamic Transaction Routing Support The Xpediter/CICS CPSM router exit (DBUGWRAM) that provides dynamic transaction routing (DTR) and distributed program link (DPL) support can be started and stopped either by using transactions or with PLTPI and PLTSD entries. Configuring Intercommunication Facilities 91 Start DTR support in a TOR by doing one of the following: • Add program DBUGWRMI to the PLTPI of the desired CICS region(s). • Type XPWI on a blank CICS screen and press Enter. Stop DTR support in a TOR by doing one of the following: • Add program DBUGWRMD to the PLTSD of the desired CICS region(s). • Type XPWD on a blank CICS screen and press Enter. Task 18.6 Add Resource Definitions to the TOR for Dynamic Transaction Routing Support If you do not plan to use Xpediter for debugging in the TOR, use SMXDSAMP member CSDXDDYN to add required transaction and program definitions to the TOR. Refer to the applicable task “Using RDO to Update Resource Definitions” in the Xpediter/CICS Installation Guide. The definitions in member CSDXDDYN must override any previously created Xpediter definitions. If you do plan to use Xpediter for debugging in the TOR, use SMXDSAMP member CSDXDDYT to add required transaction and program definitions to the TOR. Refer to the applicable task “Using RDO to Update Resource Definitions” in the Xpediter/CICS Installation Guide. To support dynamic routing of EXEC CICS START commands and Dynamic Program Link (DPL), install the Xpediter/CICS CPSM router exit in all AOR regions. Copy the definitions from your TOR for transaction codes XPWI and XPWD and programs DBUGWRAM, DBUGWRMI, DBUGWRMD, DBUGWRMM, and DBUGWRSI. DPL requests cannot be routed in a CICSplex environment by program name. An alternative is to create a trap mask by userID and/or transaction code. Installation in a Non-CPSM Dynamic Routing Environment Xpediter/CICS cannot influence dynamic routing if the CICSPlex SM (CPSM) dynamic routing program is not used. In such situations, an Xpediter session must be initiated in each region where the program to be tested may be routed. The steps below simplify the task of initiating Xpediter sessions in multiple AORs. After the following steps have been completed, entering the XSTA transaction with appropriate parameters will start transaction XPED in each of the AORs. Task 18.7 Prepare for Static Routing Complete the steps described in “Installing in a Static Routing Environment”. The transaction definitions for XPE1, XPE2, etc. should include the parameter ROUTABLE(YES). Task 18.8 Implement Automatic Session Termination To implement automatic session termination, perform the tasks described in “Configuring Automatic Session Termination”, including those in “Task 16.2 Configure For Transaction Routing Users”. This will include the creation of a table named DBUGEND1. 92 Xpediter/CICS Advanced Configuration Guide Task 18.9 Implement the Script Facility The Xpediter/CICS Script Facility is described in “Configuring the Script Facility”. Complete the tasks described in that chapter. Consider creating an appropriate script to be specified for the global parameter XDSSAPM. Task 18.10 Create Table of Remote Xpediter Transactions Table DBUGSTA1 is a CSECT with DC statements defining all the transactions to start when initiating Xpediter sessions in multiple AORs. The table should contain all the transaction IDs on the local system (TOR) that correspond to the remote transaction XPED. The resource definitions for these transactions should include the parameter ROUTABLE(YES). If table DBUGSTA1 is not present, an error message will be issued. Create and define DBUGSTA1 as follows: 1. Assemble and link-edit a table named DBUGSTA1 (Figure 23) in a load library that will be available in the TOR. The DBUGSTA1 table must not be linked with command level stubs. Figure 23. DBUGSTA1 Table DBUGSTA1 TITLE DBUGSTA1 CSECT DC DC DC END 'Table of Transactions for STARTing Xpediter/CICS' CL4'XPE1' CL4'XPE2' CL4'XPE3' Start XPED in AOR1 Start XPED in AOR2 Start XPED in AOR3 Changes or new definitions are not required on the remote CICS regions (AOR) if you have not changed the default Xpediter/CICS transaction names. 2. Add the following resource definitions for the TOR: CEDA DEFINE PROGRAM(DBUGSTA0) GROUP(XPEDR170) LANGUAGE(ASM) EXECKEY(CICS) CEDA DEFINE PROGRAM(DBUGSTA1) GROUP(XPEDR170) LANGUAGE(ASM) EXECKEY(CICS) CEDA DEFINE TRANSACTION(XSTA) PROGRAM(DBUGSTA0) GROUP(XPEDR170) LANGUAGE(ASM) EXECKEY(CICS) The XSTA transaction could be any valid transaction name. 93 Defining and Displaying User-Defined DSECTs You can define DSECT images for Xpediter’s DSECTs screens (2.D and 9.D), including DSECTs for other third-party packages or MVS. This chapter describes the steps involved in defining and displaying user DSECTs. Roles Involved The following person is required: • Xpediter/CICS Installer. Adding the User DSECT File to CICS If a user DSECT file has been created for Abend-AID as described in the Abend-AID Installation and Customization Guide chapter entitled “User-Defined DSECTs”, you can define that file in CICS for Xpediter/CICS use. Otherwise, any new or existing source listing file may be used. Task 19.1 Create Site-Specific DSECT Images User DSECT images are created using the Compuware Shared Services (CSS) Assembler language processor. The Xpediter/CICS installation sample library (SMXDSAMP) contains two sample members, DSECTDFH and DSECTUSR, that illustrate how you can create site-specific DSECT images. DSECTDFH contains sample assembly JCL for DFHAFCB as shown in Figure 24 and Figure 25. DSECTUSR provides sample assembly JCL for a site-specific DSECT. The DSECT must include a DSECT card. For more information about the Assembler language processor, refer to the Compuware Shared Services User/Reference Guide. User-Defined DSECT Example The following example uses CICS macro DFHAFCD. This macro defines a DSECT named DFHAFCB. The assembly source to create this DSECT image is: DFHAFCD TYPE=DSECT END Figure 24 shows an example of how to define the system labels required for user-defined DSECTs on the Define System Labels screen (9.9) so they can then be displayed on the DSECTs screens (2.D or 9.D). The labels TCB and TCBXTN are used to resolve the address for DFHAFCB. You can create these labels with the following DBPA entries: DBPA 9.9 NL=TCB,EL=ADDR,OFF=21C,UC=Y DBPA 9.9 NL=TCBTXN,EL=TCB,OFF=D0,UC=Y DBPA 9.9 NL=DFHAFCB,EL=TCBTXN,OFF=14,UC=Y 19 94 Xpediter/CICS Advanced Configuration Guide Figure 24. System Labels for User DSECTs on Define System Labels Screen (9.9) ------------------ XPEDITER/CICS - DEFINE COMMAND ===> MODULE: CSECT:  DEFAULT BASE LABELS: CSA DCT EIS FCT ADDR PADDR PLEN  USER BASE ENTRY OR DEL LABEL LABEL PGM-NAME -----------------------_ TCB ADDR _ TCBXTN TCB _ DFHAFCB TCBXTN _ ________ ________ ________ _ ________ ________ ________ SYSTEM LABELS (9.9) -------------C123 SCROLL ===> CSR MOD OFL INITCOMM PGM TCA TCT MQMD MQDATA + OR USE OFFSET CONTENT LENGTH ----------- -------21C Y 00000000 D0 Y 00000000 14 Y 00000000 _________ _ ________ _________ _ ________ RESULTING VALUE -------- 008B2938 008B2A90 008B2790 Figure 25 shows an example of a user-defined DSECT on the DSECTs screen (9.D). Note that the name specified in the TABLE/AREA field matches both the label defined on the Define System Labels screen (9.9) and the member name in the SLS file. Figure 25. User DSECT Displayed on DSECTs Screen (9.D) ------------------------- XPEDITER/CICS - DSECTS (9.D) --------------------C123 COMMAND ===> SCROLL ===> CSR MODULE: CSECT: COMPILED: 12 MAY 2009 - 14.06 TABLE/AREA: DFHAFCB TABLE ENTRY ID: ________ LABEL: DFHAFCB  008B2790 DFHAFCB DSECT 008B2790 000 AFIDENT DS XL4 C1C6C3E7 * AFCX * 008B2794 004 AFVER DS XL1 02 * . * AFVER1 EQU X'01' AFVER2 EQU X'02' 008B2795 005 AFSVCNO DS XL1 D4 * M * 008B2796 006 AFLENG DS XL2 00D0 * .} * 008B2798 008 AFCSA DS XL4 8004F200 * Ø.2. * 008B279C 00C AFAICB DS XL4 00085AE4 * ..!U * 008B27A0 010 AFPFXEND DS 0XL4 00000000 * .... * AFPFXLEN EQU X'10' 008B27A0 010 AFLSTBEG DS 0XL4 00000000 * .... * 008B27A0 010 AFPFF DS XL4 00000000 * .... * 008B27A4 014 AFCHAIN DS XL4 00000000 * .... * 008B27A8 018 AFSRB DS XL4 80000000 * Ø... * 008B27AC 01C AFHPSRB DS XL4 00000000 * .... * 008B27B0 020 AFIRSVC DS XL4 87D0E114 * g}÷. * 008B27B4 024 AFIRSUDB DS XL4 318BF108 * .»1. * 95 Configuring for System Currency As you make changes to your operating system and vendor software, you may also need to make changes to Compuware product configurations. When upgrading z/OS subsystems, there are customization and reconfiguration tasks need to be performed to ensure Xpediter/CICS continues to function correctly. Roles Involved The following people are required: • Xpediter/CICS Installer • DB2 DBA • IMS DBA. Tasks Task 20.1 Upgrading CICS The following person is required: • Xpediter/CICS Installer Perform the following tasks when upgrading CICS (not Xpediter/CICS). Task 20.1.1 Install the New FMID If the SMP/E FMID for the new CICS release is not already installed, follow the instructions in the Compuware Installer Mainframe Products SMP/E Installation Guide to install Xpediter/CICS. Task 20.1.2 Update the CICS Resource Definitions Change your site’s CICS startup JCL as follows: 1. Make the CSS load library accessible to Xpediter/CICS by adding it to the DFHRPL concatenation in the CICS startup JCL. The CSS load library is named CPWR.LCXnnn.SLCXLOAD (nnn is the release of CSS) and is included in the installation of Enterprise Common Components. 2. Add the appropriate Xpediter/CICS load library listed in Table 13 to the DFHRPL concatenation. Table 13. Xpediter/CICS Load Library Datasets CICS Release Dataset Name CICS TS 4.1 CPWR.OMXD170.SMXDO66L CICS TS 4.2 CPWR.PMXD170.SMXDO67L CICS TS 5.1 CPWR.QMXD170.SMXDO68L CICS TS 5.2 CPWR.RMXD170.SMXDO69L CICS TS 5.3 CPWR.SMXD170.SMXDO70L CICS TS 5.4 CPWR.TMXD170.SMXD071L 20 96 Xpediter/CICS Advanced Configuration Guide Task 20.2 Upgrading DB2 The following person is required: • DB2 DBA Perform the following tasks when upgrading DB2 (not Xpediter/CICS). Task 20.2.1 Update Support for the DB2 File Utility The DBRM members for the DB2 File Utility have been updated in release 17.02 of Xpediter/CICS. If you are using the DB2 File Utility, the bind for plan (MXDPLAN) needs to be rerun. The default bind package name has changed in this release to reflect the product code and release (MXD0170). Perform the following steps to bind the plan: 1. Modify the JCL in member DBBIND10 as described in the comments within that member. 2. The JCL in DBBIND10 must be executed by an authorized DB2 user. Submit the JCL and ensure it completes successfully. 3. The plan bound above must be granted EXECUTION authority of PUBLIC by executing the following SQL statement using SPUFI (or whatever DB2 utility is used at your site): GRANT EXECUTE ON PLAN MXDPLAN TO PUBLIC If you changed the plan name in the JCL above, substitute that plan name in place of MXDPLAN before executing the SQL statement. Task 20.3 Upgrading IMS The following person is required: • IMS DBA Perform the following task when upgrading IMS (not Xpediter/CICS). Task 20.3.1 Update Support for the IMS File Utility If you have implemented the Xpediter/CICS IMS File Utility, you will need to update to the new Xpediter/CICS APF authorized library in the DLISAS and IMS control region STEPLIB. The default authorized library is SMXDAUTH. 97 Configuration Parameters 21 This section outlines the configuration parameters used to customize Xpediter/CICS to your installation, as well as various ways to specify them. The information presented here assumes that you have implemented the CMSC PARMLIB according to “Milestone 3: CMSC PARMLIB Implementation” in the Xpediter/CICS Installation Guide. PARMLIB Members Compuware mainframe products use parameter libraries, or PARMLIBs, to configure each product and common components. Table 15 lists the Release 17.02 PARMLIB Members for all Compuware mainframe products and common components. Your product requires a PARMLIB where its members are provided such that you can modify them to fit your site’s requirements. Compuware recommends using one common dataset, but can be concatenation of dataset names to store your site’s PARMLIB (if applicable) members in a common library. A copy of your product’s parameter file(s) must reside in the //CWPARM DD concatenation of the Compuware Mainframe Services Controller (CMSC). See the Enterprise Common Components Installation and Customization Guide for release 16.05 for further information on CMSC. The Compuware Mainframe Services Controller (CMSC) address space is a centralized facility providing the common parameter library services. It provides two basic functions in relation to parameters: storage and retrieval. The following is a guideline for some of the usage and features of the CMSC: • Users will modify a human readable PARMLIB member and issue a modify command to the CMSC to store this new set of parameters into a common memory object. • This common memory object is accessible even if the CMSC is inactive. • When the CMSC is initialized, all PARMLIB members are loaded into a common memory object. • The default suffix is 00, but this can be changed in the CMSC nnnn PARMLIB member. General Guidelines for PARMLIB Members Parameters used by your Compuware mainframe product or component are read from the common PARMLIB dataset. Edit the sample parameters to your site’s requirements. Table 14. General Guidelines PARM Name Values Samples Data columns 1 to 71 N/A Symbol separator Underscore Continuation Check first for any character in Column 72 Otherwise, check for “,” is the last non-blank "A_LONG_SYMBOL" 1. any non-blank 2. “,” 98 Xpediter/CICS Advanced Configuration Guide Table 14. General Guidelines (Continued) PARM Name Values Samples Comments “*” in column 1. * is a comment Between columns 1-71, begin with “/*” and end with “*/” /* is a comment */ • If the PARMLIB member includes multiple groups of parameters, for example for the definition of multiple DB2 Subsystem, then only one occurrence of each of the parameters within each group is allowed. • Line level comments are supported using the “/*” to start a comment and “*/” to end the comment. Embedded comments are supported. System Symbolics The CMSC resolves system symbolics as product parameters which are saved into storage, potentially allowing a single parameter member to be used across multiple LPARs. These symbols are defined by your installation in IEASYMxx. Issue the following display command to display the current symbols: /DISPLAY SYMBOLS PARMLIB Member Naming Convention PPPPnnnn PPPP is the product prefix (see Table 14). nnnn is the 1 to 4-character PARMLIB suffix, for example 00. The PARMLIB member name for each product or product component must start with the product prefix, for example FACM for File-AID Common Components. The 1- to 4-character suffixes can be used to replace the default name (FACM00). If the parameter for a given product is omitted, the default suffix will be 00. Changing the Default PARMLIB Member In the CMSC startup parameters, specify the product parameter, followed by the equal sign, and the 1- to 4-character suffix (for example: FACM=01, which points to PARMLIB member FACM01). If you changed your PARMLIB member name from the default FACM00 to FACM0005, for example, update your CMSC PARMLIB member to point to the new PARMLIB member, FACM=0005. General Guidelines for PARMLIB Dataset • The dataset can be blocked. • The dataset can have multiple extents. • The dataset must be on a single volume. • The CMCS must have READ access. Table 15. Compuware Product PARMLIB Member Parameters Product PARMLIB Product Member Parameters AABD Abend-AID BDCAS AADC Abend-AID DCAS AAFA Abend-AID Fault Analytics AATD Abend-AID TDCAS AAVW Abend-AID Viewer Configuration Parameters 99 Table 15. Compuware Product PARMLIB Member Parameters (Continued) Product PARMLIB Product Member Parameters CMSC Compuware Mainframe Service Controller FACM File-AID Common Component FADA File-AID/Data Solutions FADE File-AID DB2 Environment Information FAMV File-AID/MVS FAFR File-AID/RDX FAFD File-AID for DB2 FAIE File-AID IMS Environment Information FAIX File-AID for IMS HCI Host Communications Interface HSCM Hiperstation LMCL License Management Client (LMSINIT) LMSV License Management Server (LMZINIT) STR Strobe XVGB Xpediter/Code Coverage CICS components XD$$ Xpediter/CICS Index Member XDGB Xpediter/CICS Global components XDDB Xpediter/CICS DBPA components XTSO Xpediter/TSO XCHG Xpediter/Xchange Parameter List This section describes each parameter. The default values listed are those in DBUGGBL. Where three default values are given, they correspond to the three Xpediter/CICS transactions XPED, XPRT, and XPSP respectively. The table below lists all the parameters and the default values for each. It also indicates which methods can be used to specify the value of each parameter and whether the PARMLIB parameter can be dynamically updated by entering XSIT. The sub-columns listed under the “Changeable Via:” column have the following meanings: • CMSC PARMLIB – Parameters are processed during Xpediter/CICS initialization. – See “CMSC PARMLIB” for more details. • XSIT Transaction – Parameters from PARMLIB can be dynamically updated after Xpediter/CICS initialization by entering XSIT. – See “Updating the Xpediter/CICS Parameters While CICS is Active” for more details. • Assembling DBUGGBL – Parameters that are ineligible for CMSC PARMLIB can be specified by reassembling DBUGGBL. – See “Assembling DBUGGBL” for more details. 100 Xpediter/CICS Advanced Configuration Guide Standard Global Table DBUGGBL Table 16. Standard Global Table Parameters Changeable Via: Parameter Default in DBUGGBL CMSC PARMLIB XSIT Transaction Assembling DBUGGBL ACCESSC (ON,ON,ON) ● ● ● ACCQTS (ON,ON,ON) ● ● ● ACCTD (ON,ON,ON) ● ● ● ALLOWCM (OFF,OFF,ON) ● ● ● ALLOWMON YES ● ● ● ASMSTMP YES ● ● ● ATA (OFF) ● ● ● ATASCRN YES ● ● ● ATASEC YES ● ● ● ATAUSR1 Blank ● ● ● ATAUSR2 Blank ● ● ● ATAUSR3 Blank ● ● ● ATAXPRG No entries ● ● ● ATAXTRN No entries ● ● ● AUTOSEL YES ● ● ● AUTOXIT YES ● ● ● BRGWP YES ● ● ● BRWCNT 100 ● ● ● BTRCFLG YES ● ● ● CCUPDT YES ● ● ● CELLSIZ 10 ● CICSOTE YES ● CICSPLX NO ● CMDDLM1 ; ● ● ● COBENTR 500 ● ● ● CRTEOK YES ● ● ● CSSPPRC 4 ● ● ● DBAUDDST CSMT ● ● ● DBAUDIT NO ● ● ● DBCTPSB XPEDPSB2 ● ● ● DBFL DBFL ● ● ● DBNC NEWC ● ● ● DBPA DBPA DBXG DBXG ● ● ● DB2AUTH NONE ● ● ● DB2DEC4 PERIOD ● ● ● NO ● ● ● DB2LOKA 4 ● ● ● ● ● Configuration Parameters 101 Table 16. Standard Global Table Parameters (Continued) Changeable Via: Parameter Default in DBUGGBL DB2LOKD NO ● ● ● 1000 ● ● ● DB2NULD @ ● ● ● DB2SQLR4 250 ● ● ● DB2SQLT4 LOCAL ● ● ● DB2STR4 APOST ● ● ● DB2VARE | ● ● ● DB2VART YES ● ● ● (ON,ON,ON) ● ● ● (OFF,OFF,OFF) ● ● ● DEFCSE (NONE,NONE,NONE) ● ● ● DEFFOOT1 (OFF,OFF,OFF) ● ● ● DEFJUST1 (ON,ON,OFF) ● ● ● DEFKEEP1 (ON,ON,OFF) ● ● ● DEFMAXS1 (20,20,20) ● ● ● DEFOPT1 (ON,ON,ON) ● ● ● DEFPROT1 (OFF,OFF,OFF) ● ● ● DEFSRC1 (ON,OFF,OFF) ● ● ● DEFSTPD1 (0,0,0) ● ● ● DEFTRAC1 (OFF,OFF,OFF) ● ● ● DEFTRAP1 (ON,ON,OFF) ● ● ● DISCONN YES ● ● ● DMAP DMAP ● ● ● DUMP NO ● ● ● ENDSESS NO ● ● ● ESDBUFS 500 ● FLWAIT 14 ● ● ● FOLDLC NO ● ● ● FORCEOK YES ● ● ● GBLTRPA YES ● ● ● GOTVP NO ● IKEEP1 YES ● ● ● IVPMSGS ERROR ● ● ● LIMCREA4 * ● ● ● LIMDB4 * ● ● ● LIMTABL4 * ● ● ● LIMTS4 * ● ● ● LIMTYPE4 * ● ● ● DB2MAX 4 4 DEFALM 1 DEFALT1 1 CMSC PARMLIB XSIT Transaction Assembling DBUGGBL ● ● 102 Xpediter/CICS Advanced Configuration Guide Table 16. Standard Global Table Parameters (Continued) Changeable Via: Parameter Default in DBUGGBL MAXWAIT 6 ● ● ● MENUMSG Blank ● ● ● MONSIZE 100 ● MQDYNQ MXD.* ● ● ● MQLIST (ON,ON,ON) ● ● ● MQREAD (ON,ON,ON) ● ● ● MQUPDT (ON,ON,ON) ● ● ● MSGPFX MXD ● ● ● NBRSLS 8 ● NEWC1N YES ● ● ● NLS ASIS ● ● ● OKUPDT (ON,ON,ON) ● ● ● OPENDS (ON,ON,ON) ● ● ● PF12 (’HELP’,’HELP’) ● ● ● PF22 (’MENU’,’MENU’) ● ● ● PF32 (’END’,’END’) ● ● ● PF42 (’=X’,’EXIT’) ● ● ● PF52 (’RFIND’,’RFIND’) ● ● ● PF62 (’LOCATE *’,’LOCATE *’) ● ● ● PF72 (’UP’,’UP’) ● ● ● PF82 (’DOWN’,’DOWN’) ● ● ● PF92 (’GO 1’,’GO 1’) ● ● ● PF102 (’LEFT’,’LEFT’) ● ● ● PF112 (’RIGHT’,’RIGHT’) ● ● ● PF122 (’GO’,’GO’) ● ● ● PF132 (’SOURCE’,’SOURCE’) ● ● ● PF142 (’MEMORY’,’MEMORY’) ● ● ● PF152 (’SELECT’,’SELECT’) ● ● ● PF162 (’WS’,’WS’) ● ● ● PF172 (’=2.4’,’TRACE’) ● ● ● PF182 (’=2.8’,’LAST3720’) ● ● ● PF192 (’UP MAX’,’UP MAX’) ● ● ● PF202 (’DOWN MAX’,’DOWN MAX’) ● ● ● PF212 (’FILE’,’FILE’) ● ● ● PF222 (’=2.20’,’SRCLESS’) ● ● ● PF232 (’RETRIEVE’,’RETRIEVE’) ● ● ● PF242 (’=7.1’,’ABENDAID’) ● ● ● PL1STMP YES ● ● ● CMSC PARMLIB XSIT Transaction Assembling DBUGGBL ● ● Configuration Parameters 103 Table 16. Standard Global Table Parameters (Continued) Changeable Via: Parameter Default in DBUGGBL POPTOVR (OFF,OFF,OFF) ● PROFDDN DBUGPRF ● PROFUSR YES ● ● ● PROTCWA NO ● ● ● PROTMAX 100 ● ● ● PROTMSG CSMT ● ● ● PROTTID NO ● ● ● PSBWAIT 2 ● ● ● RDSABP YES ● ● ● READB YES ● ● ● READDL1 (ON,ON,ON) ● ● ● READDS (ON,ON,ON) ● ● ● RECREATE FTP ● ● ● RESUME YES ● ● ● RMTWAIT 6 ● ● ● RQCHSIZ 4096 ● RTIMOUT YES ● ● ● RUWAIT 0 ● ● ● SCHEDL1 (ON,ON,ON) ● ● ● SCROLL CSR ● ● ● SERVRQ (ON,ON,ON) ● ● ● SETRPLY YES ● ● ● SLSDDN SLSF001 ● ● SLSDYN NO ● ● SLSSDB SLSD0001 ● ● STEPWT 99 ● ● ● STEPWT0 5000 ● ● ● STOP YES ● ● ● SUBSYS XDSS ● SUBUBCK YES ● ● ● SUPSESM NO ● ● ● TCBNR 4 ● TRANSUC YES ● ● ● TRAPIPU NO ● ● ● TRAPNET NO ● ● ● TRAPTRM YES ● ● ● TRAPUSR NO ● ● ● TRPLOAD1 NO ● ● ● CMSC PARMLIB XSIT Transaction Assembling DBUGGBL ● ● ● ● ● ● 104 Xpediter/CICS Advanced Configuration Guide Table 16. Standard Global Table Parameters (Continued) Changeable Via: Parameter 1 Default in DBUGGBL CMSC PARMLIB XSIT Transaction Assembling DBUGGBL YES ● ● ● TRPXABD No user entries ● ● ● TSQID XPED ● ● ● UNIQUEIP NO ● ● ● UPDTDL1 (ON,ON,ON) ● ● ● UPDTDS (ON,ON,ON) ● ● ● UPDTSEC (OFF,OFF,OFF) ● ● ● UTILMOD NO ● ● UXSNOFF NO ● ● VERFILE YES ● ● ● XDBP XDBP ● ● ● XDCC YES ● XDDBPCL * ● ● ● XDDBPRP XDDBPRPT ● ● ● XDDBPTY DYNAMIC ● ● ● XDGBLCL * ● ● ● XDGBLRP XDGBLRPT ● ● ● XDGBLTY DYNAMIC ● ● ● XDLOG NO ● ● ● XDLOGAD FULL ● ● ● XDLOGBK 27930 ● ● ● XDLOGDD DYNAMIC ● ● ● XDLOGDL FULL ● ● ● XDLOGMD Blanks ● ● ● XDLOGNM XD.LOG.DATASET.GDGNAME ● ● ● XDLOGPA 10 ● ● ● XDLOGSA 5 ● ● ● XDLOGTY CYL ● ● ● XDLOGUN SYSDA ● ● ● XDLOGUP FULL ● ● ● XDLOGVO Blanks ● ● ● XDSCRPT YES ● ● ● XDSCRXN3 ******** ● ● ● XDSCRXO3 SAVE ● ● ● XDSSACC WRITE ● ● ● XDSSAPM ******** ● ● ● XDSSDD DYNAMIC ● ● ● XDSSDSN XD.SYSTEM.SCRIPT.DATASET ● ● ● TRPSAVE ● Configuration Parameters 105 Table 16. Standard Global Table Parameters (Continued) Changeable Via: Parameter Default in DBUGGBL XDTRCRP XDTRCRPT ● ● ● 27960 ● ● ● XDUSCR YES ● ● ● XDUSDB3 44 ● ● ● XDUSDC3 Blanks ● ● ● DYNAMIC ● ● ● XDUSDSN userID.SCRIPT.DATASET ● ● ● XDUSLIB3 NO ● ● ● XDUSMC Blanks ● ● ● XDUSPA3 15 ● ● ● XDUSPFX Blanks ● ● ● XDUSSA3 15 ● ● ● XDUSSC3 Blanks ● ● ● XDUSSMS3 NO ● ● ● XDUSTYP3 TRK ● ● ● XDUSUNI3 SYSDA ● ● ● XDUSVOL3 Blanks ● ● ● XFERDDN DBUGSQL ● ● ● XIVP XIVP ● ● ● XLGI XLGI ● ● ● XLOG XLOG ● ● ● XPED XPED XPFS XPFS ● XPGD XPGD ● ● ● XPND XPND ● ● ● XPN0 XPN0 ● ● ● XPOF XPOF ● ● ● XPOFTCWT 0 ● ● ● XPON XPON ● XPRT XPRT ● XPSP XPSP ● XREL XREL ● ● ● XSIT XSIT ● ● ● XSRE XSRE ● ● ● XTMO XTMO ● ● ● XTMOCHK 0 ● ● ● XTMOINT 0 ● ● ● XTMOTRV NO ● ● ● 3 XDUSBLK 3 XDUSDD 3 3 CMSC PARMLIB XSIT Transaction Assembling DBUGGBL ● ● 106 Xpediter/CICS Advanced Configuration Guide Table 16 Footnotes: 1 If you have an Xpediter profile, this parameter is taken from it. Use the Set Profile Defaults (0.1) screen to modify your profile record value. 2 If you have an Xpediter profile, this parameter is taken from it. Use the Primary PF Key Settings (0.2) screen to modify your profile record value. 3 If you have an Xpediter profile, this parameter is taken from it. Use the Script Dataset Allocation (0.6) screen to modify your profile record value. 4 If you have an Xpediter profile, this parameter is taken from it. Use the DB2 Setup (5.5.0) screen to modify your profile record value. Production Global Table DBUGGBLP Table 17 lists the default parameter values that are different in the production version of the global table, DBUGGBLP. The global override sample member, XDGB00, contains equivalent values. Table 17. Production Global Table Parameters Changeable Via: Parameter Default in DBUGGBLP CMSC PARMLIB XSIT Transaction Assembling DBUGGBLP ACCQTS (OFF,OFF,ON) ● ● ● ACCTD (OFF,OFF,ON) ● ● ● DBAUDDST XAUD ● ● ● DBAUDIT YES ● ● ● FLWAIT 7 ● ● ● FORCEOK NO ● ● ● MQUPDT (OFF,OFF,ON) ● ● ● NEWC1N NO ● ● ● OPENDS (OFF,ON,ON) ● ● ● READDL1 (OFF,ON,ON) ● ● ● READDS (OFF,ON,ON) ● ● ● RESUME NO ● ● ● SCHEDL1 (OFF,ON,ON) ● ● ● STOP NO ● ● ● UPDTDL1 (OFF,OFF,ON) ● ● ● UPDTDS (OFF,OFF,ON) ● ● ● UTILMOD YES ● ● XDCC NO ● ● Parameter Descriptions Default Member XDGB00 This section describes each global parameter. The default values listed are those in DBUGGBL. Where three default values are given, they correspond to the three Xpediter/CICS transactions XPED, XPRT, and XPSP respectively. Configuration Parameters 107 ACCESSC Default: (ON,ON,ON). Enter OFF to disable use of the ACCESS command for the specified transaction. ACCQTS Default: (ON,ON,ON). Enter OFF to disable access to QUEUED (multiple record) temporary storage queues in the file utility for the specified transaction. ACCTD Default: (ON,ON,ON). Enter OFF to disable access to transient data queues in the file utility for the specified transaction. ALLOWCM Default: (OFF,OFF,ON). Enter OFF to disable access to the ALLOW command for the specified transaction. ALLOWMON Default: YES Enter NO to disable use of the MONITOR and REVERSE commands. Refer to “MONSIZE” for information about controlling storage utilization. Refer to the Xpediter/CICS Reference Manual for information about MONITOR and REVERSE. ASMSTMP Default: YES Indicates whether the time stamp will be checked when source listings are loaded. Enter YES if the time stamp information is required to match an Assembler module to a source listing. If no time stamp is found in the module or CSECT, and ASMSTMP=YES, it is treated as a time stamp mismatch, and source support will not be available. If you postprocess using the Assembler option LOAD, enter a CWPLOAD DD statement in the language processor JCL to place a time stamp in the module. If you postprocess with the DECK option, enter CWPDECK and CWPWRK5 DD statements in the language processor JCL to place a time stamp in the module. ATA Default: OFF Enter the Xpediter initialization transaction (XPED, XPRT, or XPSP) to be run when a user transaction abend is trapped by Automatic Trap Activation (ATA). Enter OFF to disable ATA. ATA is deactivated if the Xpediter/CICS global parameter CICSPLX=YES. ATASCRN Default: YES Enter YES to display a user notification screen when Automatic Trap Activation (ATA) traps a transaction abend. Enter NO to not display the screen. The user notification screen tells the user their transaction has abended and explains how to continue. It can be customized with the ATAUSR1, 108 Xpediter/CICS Advanced Configuration Guide ATAUSR2, and ATAUSR3 global parameters. A help screen is available by entering HELP in the COMMAND field or by pressing the HELP PF key (default PF1). ATASEC Default: YES Enter YES to make Xpediter check the security access of the user before trapping a transaction abend with Automatic Trap Activation (ATA). Enter NO to make Xpediter skip the security access check, but remember that this can result in an unauthorized user being given access to Xpediter features when ATA traps an abend. ATAUSR1, ATAUSR2, and ATAUSR3 Default: blank, blank, and blank Enter any three lines of text, one per parameter, to be displayed on the Automatic Trap Activation (ATA) user notification screen described in ATASCRN above. Up to 75 characters can be entered for each parameter, or up to 72 characters if using the Global Override Facility. The text is centered and highlighted by default. To turn off highlighting, enter a period (.) as the first character. To turn off centering, enter a left brace ({) as the first character. To turn off both highlighting and centering, enter a left parenthesis ( as the first character. ATAXPRG Default: No entries Enter a list of programs to be excluded from Automatic Trap Activation (ATA) trapping. Any program whose name starts with DFH, DSH, or DB2 is automatically excluded from ATA trapping. ATAXTRN Default: No entries Enter a list of transactions to be excluded from Automatic Trap Activation (ATA) trapping. CEDA, CEMT, CESN, and CESF transactions are automatically excluded from ATA trapping. AUTOSEL Default: YES Enter NO to disable automatic selection of abends generated from another terminal. AUTOXIT Default: YES Enter NO to go to the Exit Session screen on an EXIT command. Enter YES to go directly to CICS on an EXIT command. BRGWP Default: YES Enter NO to suppress the Compuware background wallpaper used for Xpediter/CICS screens while running the 3270 Web Bridge. Configuration Parameters 109 BRWCNT Default: 100 Enter the number of dataset and/or temporary storage records to scan before the system displays the NOT FOUND message for the FIND command on the 5.1.2, 5.2.2, 5.5.2, and 5.5.4 screens. Valid values are 1 to 99999. BTRCFLG Default: YES When this option is set to YES or FULL, Xpediter/CICS updates an internal branch trace table to help diagnose any Xpediter/CICS issues. Unless Xpediter/CICS customer support has requested that you run with this option set to YES or FULL, it may be set to NO to save CPU. If BTRCFLG is set to NO and an Xpediter/CICS problem occurs, recreate the problem with BTRCFLG set to YES before gathering documentation for Xpediter/CICS customer support. CCUPDT Default: YES Enter NO to cause Xpediter/Code Coverage to start Xpediter/CICS in Diagnosis Mode. The user will be unable to update storage values or perform certain other standard operating mode functions. Specifying CCUPDT=NO will force OKUPDT to (OFF,OFF,OFF). Refer to “Configuring Restricted Operating Modes”for more information about restricted operating modes. CELLSIZ Default: 10 Designates the number of cell entries in a cell in ESD cache. Use this parameter as a performance option. Do not alter this value unless recommended by Xpediter/CICS Customer Support (see “Customer Support”). The XSIT transaction cannot be used to override this parameter. CICSOTE Default: YES Controls Xpediter/CICS support of CICS Open Transaction Environment (OTE). The default of YES provides full CICS OTE support, allowing the debugging of CICS transactions on the CICS Open TCBs (L8) as well as the CICS QR TCB. In CICS regions that do not exploit CICS OTE, Xpediter/CICS storage utilization can be reduced by specifying NO for this parameter. Setting this parameter incorrectly can cause excessive TCB switching and increased CPU utilization for transactions exploiting CICS OTE. CICSPLX Default: NO Enter YES to activate support for dynamic transaction routing under Xpediter/CICS CICSPlex support. The XSIT transaction cannot be used to override this parameter. 110 Xpediter/CICS Advanced Configuration Guide CMDDLM Default: ; Enter the delimiting character to be used to separate multiple Xpediter/CICS primary commands entered together. Any character is a valid delimiter except alphanumeric characters (a to z, A to Z, and 0 to 9), period (.), comma (,), blank ( ), underscore (_), and equal (=). The CMDDLM value is the default command delimiter and applies only to users with no delimiter stored in their user profile, such as new users or existing users invoking a new release of Xpediter for the first time. Once a command delimiter been set for a given user, it can be changed using the DELIM field on the Set Profile Defaults screen (0.1). For more information, see the Xpediter/CICS Reference Manual. COBENTR Default: 500 Enter the number of entries, from 0 to 32767, that the program statement trace table is to contain. Entering zero prohibits trace table creation. CRTEOK Default: YES The use of CRTE when using Xpediter in an MRO or ISC environment is not recommended. For more information, see the section “MRO and ISC Debugging Considerations” in the chapter entitled “Intercommunication Considerations” in the Xpediter/CICS Reference Manual. Enter NO to prevent the start of an Xpediter session within a CRTE explicit routing session. If CRTEOK=NO, an attempt to start an Xpediter session within a CRTE session will result in transaction abend XRTE. CSSPPRC Default: 4 Enter the maximum return code allowable from the compile or Compuware Shared Services language processor. If the return code in the source listing file exceeds the specified value, Xpediter/CICS will not display the source listing. Valid values are from 0 to 8. DBAUDDST Default: CSMT Enter a four-character transient data destination for the debugging audit trail messages if DBAUDIT is YES. Member CSDXDFIL in SMXDSAMP contains a sample resource definition named XAUD. DBAUDIT Default: NO Enter YES to enable an audit trail for selected Xpediter debugging commands. If the debugging audit trail is enabled, MXDAUnnnn messages will be written to the transient data queue specified by the DBAUDDST global parameter. DBCTPSB Default: XPEDPSB2 Enter the PSB to be scheduled by Xpediter/CICS for DBCTL support. Configuration Parameters 111 DBFL Default: DBFL Enter a four-character transaction ID to substitute for the DBFL transaction. Changing DBFL requires changing the resource definitions. DBFL is an Xpediter/CICS internal transaction that you should never enter. DBNC Default: NEWC Enter a four-character transaction ID to substitute for the NEWC transaction. Changing DBNC requires changing the resource definitions. DBPA Default: DBPA Enter a four-character transaction ID to substitute for the DBPA transaction. The override facility cannot be used to DBPA. Change it as described in “Assembling DBUGGBL”. Changing DBPA requires changing the resource definitions. DBXG Default: DBXG Enter a four-character transaction ID to substitute for the DBXG transaction. Changing DBXG requires changing the resource definitions. DBXG is an Xpediter/CICS internal transaction that you should never enter. DB2AUTH Default: NONE Enter the appropriate value below to match your site’s DB2 security setting for the XPED, XPRT, and XPSP transactions. Users should match the AUTHTYPE() DB2CONN/DB2ENTRY resource definition parameter. Valid entries are: • NONE: Xpediter displays a list of all tables and views in the DB2 catalog. No checks are made to determine whether the user is authorized to access the resource. When the resource is actually selected, DB2 performs any necessary checking. • USERID: Xpediter uses eight-byte SNT userID. Compuware strongly recommends using NONE instead of USERID. For more information, see “Implementing Support for the DB2 File Utility”. • GROUP: Xpediter uses the same logic as used for NONE. See description of NONE above. For more information, see “Implementing Support for the DB2 File Utility”. • USER: Xpediter uses three-byte SNT operator ID. • TERM: Xpediter uses terminal ID. • TXID: Xpediter uses transaction ID. • SIGNID: This value is from the DB2CONN SIGNID() parameter. • STRING: Xpediter uses the value from DB2ENTRY AUTHID() parameter. DB2DEC Default: PERIOD 112 Xpediter/CICS Advanced Configuration Guide Enter PERIOD to change the display character for a decimal point in the DB2 file utility to a period. Enter COMMA to change the display character for a decimal point to a comma. A user may override this value on the DB2 Setup screen (5.5.0). This value should be set to the same value specified during generation of your DB2 subsystem. DB2LOKA Default: NO Enter YES to allow exclusive locking of a DB2 table during editing within the DB2 file utility. Enter NO to prohibit a user from placing an exclusive lock on the table. This parameter is a system programmer override. It can be used to prohibit users from exclusively locking a DB2 table during editing, even if exclusive locking is requested. DB2LOKD Default: NO Enter YES to specify that the user wants exclusive locking of a DB2 table during editing within the DB2 file utility. Enter NO to specify that the user does not want exclusive locking. A user can specify YES or NO for this parameter on the DB2 Setup screen (5.5.0); however, specifying YES allows exclusive locking only if the system programmer override value (DB2LOKA) is also YES. DB2MAX Default: 1000 Enter a value between 1 and 32767 to specify the maximum number of rows a user can access in the DB2 file utility. A user can also specify a smaller value through the DB2 Setup screen (5.5.0) (see the DB2SQLR parameter). DB2NULD Default: @ Enter the character you want used as the default character when displaying null columns in the DB2 file utility. A user can override this parameter on the DB2 Setup screen (5.5.0). DB2SQLR Default: 250 Enter a value between 1 and the value specified in the DB2MAX parameter. This value is the default value used when returning rows from DB2 tables in the DB2 file utility. It allows a user to specify a value smaller than the DB2MAX value when fewer rows are desired in the DB2 file utility. A user can override this value through the DB2 Setup screen (5.5.0). DB2SQLT Default: LOCAL Enter LOCAL to use the local time, date, and time stamp values when inserting columns into new rows in the DB2 file utility. Enter GMT to use Greenwich Mean Time values if you have generated this feature in your DB2 subsystem. A user can override this parameter on the DB2 Setup screen (5.5.0). DB2STR Default: APOST Enter APOST to set the default string delimiter in the DB2 file utility to an apostrophe (’). Enter QUOTE to set the default string delimiter to a quotation mark ("). A user can override this value on the DB2 Setup screen (5.5.0). This value should be set to the same value specified during generation of your DB2 subsystem. Configuration Parameters 113 DB2VARE Default: | Enter the character you want used as the default end of string character when entering variable length column data in the DB2 file utility. A user can override this parameter on the DB2 Setup screen (5.5.0). DB2VART Default: YES Enter YES to truncate trailing blanks on input for variable length column data in the DB2 file utility. Enter NO to cause variable length fields to retain trailing blanks upon input. A user can override this parameter on the DB2 Setup screen (5.5.0). DEFALM Default: (ON,ON,ON) Enter OFF to disable the terminal alarm when an error occurs for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFALT Default: (OFF,OFF,OFF) Enter OFF to disable use of alternate screen sizes for the specified transaction. This parameter sets the default value used for the specified transaction if a user’s profile record does not exist. When ON is specified, the Xpediter/CICS screens always use the alternate screen size for display. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFCSE Default: (NONE,NONE,NONE) Enter NONE to suppress automatic selection of CSECTs when debugging multiple CSECT programs for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. Enter ALL to select all CSECTs when debugging multiple CSECT programs. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFFOOT Default: (OFF,OFF,OFF) Enter the default footing values that are displayed for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. Valid values are: MENU, KEYS, DATA, STATUS, REGISTERS, ANALYZE, FLOAT, SOURCE, or OFF. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFJUST Default: (ON,ON,OFF) Enter OFF to disable justification of the source listing for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. Justification causes the Source Listing screen (2.L) to display only the source portion from the listing instead of the entire compiler listing. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFKEEP Default: (ON,ON,OFF) 114 Xpediter/CICS Advanced Configuration Guide Enter OFF to disable the display of the keep window on the Source Listing screen (2.L) for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. Valid values are: OFF, ON, 5, 7, 9, and 11. Specifying ON sizes the keep window to 5 lines. The values 5, 7, 9, or 11 sizes the keep window to that number of lines. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFMAXS Default: (20,20,20) Enter a value between 0 and the value specified in the STEPWT parameter. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. This value specifies the maximum number of statements to execute if the DELAY factor set in the GO command is greater than zero. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFOPT Default: (ON,ON,ON) Enter OFF to turn off Xpediter/CICS screen optimization for the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. Specifying ON can decrease the amount of data sent to the screen by 60 percent with only a small additional cost in CPU time. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFPROT Default: (OFF,OFF,OFF) Enter OFF to automatically disable storage protection when using the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFSRC Default: (ON,OFF,OFF) Enter ON to allow automatic display of the Source Listing screen (2.L) upon entering Xpediter/CICS, or when a breakpoint or abend occurs while using the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFSTPD Default: (0,0,0) Enter a value between 0 and 59 to specify the default delay value in seconds for the GO command while using the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFTRAC Default: (OFF,OFF,OFF) Enter OFF to disable statement-level program tracing when using the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). DEFTRAP Default: (ON,ON,OFF) Configuration Parameters 115 Enter OFF to disable automatic abend trapping when using the specified transaction. This parameter sets the default value used for the specified transaction when a profile record does not exist for a user. A user can override this parameter on the Set Profile Defaults screen (0.1). If global parameter UNIQUEIP is YES, DEFTRAP also controls whether Xpediter will trap any abends or breakpoints that occur at your TCPIP-based workstation during a debugging session. (For more information, see “UNIQUEIP”.) This function can also be controlled from the Set Profile Defaults screen (0.1). DISCONN Default: YES Enter NO to leave Xpediter/CICS sessions active if a terminal is disconnected or logged off. See “Configuring Automatic Session Termination”. DMAP Default: DMAP Enter a four-character transaction ID to substitute for the DMAP transaction used to invoke the Xpediter/CICS BMS mapset display utility. DUMP Default: NO Enter YES to produce a dump when exiting Xpediter/CICS. ENDSESS Default: NO Enter NO to make NO the default value displayed in the END SESSION field of the EXIT SESSION screen (X). Enter YES to make YES the value displayed. ESDBUFS Default: 500 Designates the cache buffer size in kilobytes. The storage is acquired above the 16MB line. The cache buffer saves the ESD information in most recently used order. The minimum size should be at least 100K. If you set the parameter to 0, the ESD information is not cached. The XSIT transaction cannot be used to override this parameter. FLWAIT Default: 14 Enter the number of seconds to wait for the DBFL transaction to complete. Xpediter/CICS starts an asynchronous task (default is DBFL) for all file I/O in the file utility. If the attached task fails to return to Xpediter/CICS within the specified time, the system issues a message. This may happen if, for example, you request a record that has a read for update still in effect. The system would queue Xpediter/CICS until the record was available. The maximum is 44. FOLDLC Default: NO 116 Xpediter/CICS Advanced Configuration Guide Converts lowercase English characters to uppercase English characters for static portions of screens and help modules. Values are YES and NO. If you are running terminals that support katakana single-byte characters (SBC), you must specify NLS=KATAKANA FOLDLC=YES. FORCEOK Default: YES The risk inherent in forcing Xpediter termination may be unacceptable in some environments. Enter NO to disallow the use of the FORCE parameter with the product termination transaction XPOF. GBLTRPA Default: YES Enter NO to change the initial setting of the TRAP ABEND field on the Trap Summary screens (1.6 and 9.6) to NO. The NO setting can be useful for debugging handle abend routines and UCHs. GOTVP Default: NO Xpediter/CICS clients that want to Storage Protect, Trace, or Code Cover application program names beginning with VP should change this option to YES. Users of Hiperstation’s File Manager support for CICS option should leave this option set to NO. If you both have application program names beginning with VP and use Hiperstation’s File Manager support for CICS option, contact Xpediter/CICS Customer Support (see “Customer Support”) for detailed instructions. IKEEP Default: YES Controls the default setting for the usage of the Intelligent Autokeeps feature. Enter YES to allow the use of this feature. Enter NO to disable this feature. The Intelligent Autokeeps feature is configured as a subset of the AUTOKEEP profile option, and to use this feature, the AUTOKEEP profile parameter must be set to ON. A user can override this parameter on the Set Profile Defaults screen (0.1). IVPMSGS Default: ERROR Controls whether IVP messages should be written to transient data destination CSMT at product initialization. Enter ALL to specify that all messages produced by the IVP should be written to CSMT. Enter NONE to specify that no messages should be written to CSMT. Enter WARN to specify that messages should be written to CSMT only if warnings and/or errors are detected. Enter ERROR to specify that messages should be written to CSMT only if errors are detected. LIMCREA Default: * (asterisk) Enter a one to eight-character value that you want to use as the default CREATOR limit field on the DB2 Table/View List screen (5.5.1) in the DB2 file utility. A user can override this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. LIMDB Default: * (asterisk) Configuration Parameters 117 Enter a one to eight-character value that you want to use as the default DATABASE limit field on the DB2 Table/View List screen (5.5.1) in the DB2 file utility. A user can override this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. LIMTABL Default: * (asterisk) Enter a one to eight-character value that you want to use as the default TABLE/VIEW NAME limit field on the DB2 Table/View List screen (5.5.1) in the DB2 file utility. A user can override this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. LIMTS Default: * (asterisk) Enter a one to eight-character value that you want to use as the default TABLESPACE limit field on the DB2 Table/View List screen (5.5.1) in the DB2 file utility. A user can override this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. LIMTYPE Default: * (asterisk) Enter TABLE to specify a default value of tables only in the TYPE limit field on the DB2 Table/View List screen (5.5.1) in the DB2 file utility. Enter VIEW to specify a value of views only. Enter an asterisk (*) to get both tables and views. A user can override this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. MAXWAIT Default: 6 Enter the number of seconds that provides a high limit (maximum) wait time to be used on the GO command. MENUMSG Default: blank Specify a message to display on the Xpediter/CICS Primary Menu. Enter the name and/or telephone number of your site’s Xpediter/CICS Customer Support representative. Normally, this is an on-site systems programmer or information center representative. Enter a maximum of 60 free-form characters, enclosed in quotes. MONSIZE Default: 100 Specify the maximum container storage above the bar, in megabytes, for MONITOR data per task. Once the maximum storage specified has been reached, MONITOR data in containers will wrap and you may receive an AT OLDEST RETAINED EXECUTION POSITION message when doing REVERSE. Valid entries are 1 to 100, in increments of 1MB. If you experience a Short on Storage (SOS) condition using MONITOR/REVERSE, reduce MONSIZE or increase the EDSA limit. The XSIT transaction cannot be used to override this parameter. MQDYNQ Default: MXD.* The File Utility screen List MQ Queues (5.6.1) opens a dynamic queue. This parameter specifies the prefix for the name of that dynamic queue. The following variables may be used within the MQDYNQ parameter: • %A - The APPLID of the CICS region 118 Xpediter/CICS Advanced Configuration Guide • %S - The SYSID of the CICS region • %U - The UserID of the user associated with the current task. The parameter length, after variable substitution, must not exceed 33 characters and must end with an asterisk (*). • Corresponding specifications in your site's external security manager, such as RACF, may be necessary. Refer to the appropriate IBM MQ for z/OS documentation for additional information regarding dynamic queues. • This parameter may be overridden for a user’s session(s) by the DYNAMIC QUEUE PREFIX field on the 5.6.0 screen. MQLIST Default: (ON,ON,ON) Enter OFF to disable access to the list of IBM MQ for z/OS (MQ) queues in the File Utility for the specified transaction. The File Utility screen List MQ Queues (5.6.1) puts a message onto the SYSTEM.COMMAND.INPUT queue. Specifications in your site's external security manager, such as RACF, may be necessary. Refer to the appropriate MQ documentation for additional information regarding the SYSTEM.COMMAND.INPUT queue. MQREAD Default: (ON,ON,ON) Enter OFF to disable read access to IBM MQ for z/OS (MQ) queues in the File Utility for the specified transaction. MQUPDT Default: (ON,ON,ON) Enter OFF to disable update access to IBM MQ for z/OS (MQ) queues in the File Utility for the specified transaction. NBRSLS Default: 8 Enter the maximum number of SLS files to search. The allowable range is 1 to 255. Searching a large number of SLS files can result in poor response time. Consider using the Shared Directory feature of Compuware Shared Services as an alternatie. Refer to “Working with Source Shared Directory Files (File Manipulation)” in the CSS Utilities chapter of the Compuware Shared Services User/Reference Guide. NEWC1N Default: YES Controls whether Xpediter/CICS users can specify programs for PHASEIN using the NEWCOPY Programs (1.N) screen. Enter YES to make the 1.N screen accessible to all users. Enter NO to make the 1.N screen inaccessible to all users. NLS Default: ASIS Changes the character translation table that is used to display data. Options are: ASIS, ENGLISH, CANADAB, HEBREWNC, ARABIC, and KATAKANA. See also “FOLDLC”. Configuration Parameters 119 OKUPDT Default: (ON,ON,ON) Enter OFF to cause the corresponding transaction to start Xpediter in Diagnosis Mode. The user will be unable to update storage values or perform certain other standard operating mode functions. Specifying CCUPDT=NO will force OKUPDT to (OFF,OFF,OFF). Refer to “Configuring Restricted Operating Modes”for more information about restricted operating modes. OPENDS Default: (ON,ON,ON) Enter OFF to disable explicit and implicit opening and closing of datasets in the file utility for the specified transaction. PF 1-24 Default: See Table 16 for default PF key values. Enter the PF key parameter in the following format: PFnn = (’command’, ’description’) • nn: PF key number. Valid entries are 1 to 24. • command: Command to execute when you press the PF key. • description: Label to display for this PF key in the footing area of the screen. It must be no longer than eight characters. If the description is blank, it is the same as the command. PL1STMP Default: YES Indicates whether the time stamp will be checked when source listings are loaded. Enter YES if time stamp information is required to match a PL/I module to a source listing. If no time stamp is found in the module, and PL1STMP=YES, it is treated as a time stamp mismatch, and source support will not be available for the module. The PL/I compiler installation option TSTAMP determines whether the compiler places a time stamp in the module. When postprocessing with the TSTAMP installation option not active: • If you use the PL/I option OBJECT, enter a CWPLOAD DD statement in the language processor JCL to place a time stamp in the module. • If you use the PL/I option DECK, enter a CWPDECK DD statement in the language processor JCL to place a time stamp in the module. POPTOVR Default: (OFF, OFF, OFF) Enter OFF to override the processing options specified at the PCB level in a DL/I PSB. Specifying ON will cause the Edit DL/I Segment screen (5.4.4) to show all DL/I access commands as valid. However, when you use a command that is not valid for a PCB or even segment level processing options, DL/I will return a bad status code indicating this access is not valid. PROFDDN Default: DBUGPRF 120 Xpediter/CICS Advanced Configuration Guide Enter a name for the user profile file. Changing DBUGPRF requires changing the CSD entry. The XSIT transaction cannot be used to override this parameter. PROFUSR Default: YES Enter YES to use the userID field as the key for the profile record to load when starting an Xpediter/CICS session. Specifying YES eliminates the need to enter XPED/XPRT/XPSP P=profilename, which obtains profile overrides when starting a session. A profile is created for each userid signon to CICS. The profiles are updated whenever a profile option is changed. Profile options are listed on the Set Profile Defaults screen (0.1). PROTCWA Default: NO Enter YES to mark the CWA for storage protection. When protection is activated through the Storage Protection screen (9.8), Xpediter/CICS treats the CWA as part of the CSA and prevents modifications. The Monitor Exceptions (9.4.1) and Storage Protection Exceptions (9.7) screens are used to override protection for the CWA. PROTMAX Default: 100 Enter a number of concurrent programs to be protected. This value is for a shared storage GETMAIN done at system startup. It is equivalent to sequential terminal input: DBPA MAXT nnnn. PROTMSG Default: CSMT Enter the transient data destination to which the system sends Xpediter/CICS storage violation messages. This is equivalent to sequential terminal input: DBPA DESTID xxxx. PROTTID Default: NO Enter YES to unprotect the TERM field on the Storage Protection screen (1.8) and allow it to function as it does on the Storage Protection (9.8) screen. The YES value allows users to set storage protection on asynchronous tasks without having to be given access to the 9.8 screen. If the value of PROTTID is NO, the TERM field is protected and the user’s terminal ID is automatically used. Compuware recommends caution if setting PROTTID to YES because doing so enables XPED and XPRT users to activate storage protection for any terminal, transaction, or program originating in the CICS region. PSBWAIT Default: 2 Specifies the length of time in minutes that a PSB remains scheduled between DL/I calls on the Edit DL/I Segment screen (5.4.4) when the PCB command is used to schedule a PSB. Valid entries are 1 to 59. READB Default: YES Configuration Parameters 121 Enter NO to prohibit Xpediter/CICS from reading full buffers from 3270 control units. Specifying NO disables the Last 3270 Screen facility. TCAM users must specify READB=NO. The Last 3270 Screen facility is not available for remote trapping. READDL1 Default: (ON,ON,ON) Enter OFF to disable read access to DL/I segments in the file utility for the specified transaction. READDS Default: (ON,ON,ON) Enter OFF to disable read access to datasets in the file utility for the specified transaction. RECREATE Default: FTP Enter FTP to enable File Transfer Protocol (FTP) transmission of problem determination information to Compuware using the documentation packaging utility. Enter TAPE to enable creation of tapes containing the problem determination information. Enter NONE to disable the documentation packaging utility. RESUME Default: YES Enter YES to be able to resume from an abend condition. This has no effect on resuming from breakpoints. Resuming a task from an abended state may produce unpredictable results. Using the GO command on an abended task does not invoke dynamic transaction backout. If Xpediter/CICS will be used in the production region, set the option to RESUME=NO. RMTWAIT Default: 6 Enter the maximum number of seconds to wait after resuming a remotely trapped task in the event that it reaches another breakpoint or abend and is automatically reselected. Valid entries are 1 to 99. RQCHSIZ Default: 4096 Designates the number of concurrent requests against PDSEs that Xpediter/CICS will support. This parameter is utilized only when a site has PDSE datasets in its DFHRPL concatenation or in an installed LIBRARY. The value specified must be an unsigned integer in the range of 4096 to 16384. The default value of 4096 allows approximately 500 concurrent requests. Do not alter this value unless recommended by Xpediter/CICS Customer Support. The XSIT transaction cannot be used to override this parameter. RTIMOUT Default: YES Enter YES to have Xpediter/CICS use the terminal read timeout value (RTIMOUT) of the user transaction being debugged for its own conversations. If the user transaction being debugged has a 122 Xpediter/CICS Advanced Configuration Guide terminal read timeout value of two minutes, Xpediter/CICS and the user transaction converses both time out after two minutes. Enter NO to have Xpediter/CICS ignore the terminal read timeout value of the user transaction during its converses. Entering NO causes Xpediter/CICS converses to not be subjected to a read timeout value. This parameter only applies to local trapping, as Xpediter/CICS executes under the user TCA of the application transaction. RUWAIT Default: 0 Specifies the length of time in seconds that a CICS dataset record is locked when a READ UPDATE command is used on the Edit CICS Dataset Record screen (5.1.3). Valid entries are 0 to 255. The default of 0 seconds means that no lock occurs and the system does not require READ UPDATE before issuing a REWRITE command. SCHEDL1 Default: (ON,ON,ON) Enter OFF to disable PCB/TERM calls for DL/I PSBs in the file utility for the specified transaction. SCROLL Default: CSR Enter a scroll type. Valid entries are: • • • • CSR: Scrolling based on the cursor location HALF: Half-screen scrolling nnnn: Number of lines to scroll PAGE: Full-screen scrolling. SERVRQ Default: (ON, ON, ON) Enter OFF to disable updates of service request fields on the CICS Dataset List screen (5.1.1) for the specified transaction. SETRPLY Default: YES Enter YES to issue a WRITE STRUCTURED FIELD (Set Reply Mode Extended) command and make any extended attributes available for the Last 3270 Screen (2.8). Enter NO to prevent the command from being issued. Extended attributes are only returned by Xpediter/CICS if CICS has issued a query for this terminal and indicated extended attributes are supported. For more information on the QUERY parameter of the TYPETERM definition, refer to Resource Definition Online. The Last 3270 Screen facility is not available for remote trapping. SLSDDN Default: SLSF001 Enter a 4-character prefix and 3-digit suffix to be used as a template for the ddnames associated with SLS (source listing support) files. The resource definition for the file must specify this name. Any additional ddnames are built by adding 1 to the suffix portion. For example, if the default is used, the Configuration Parameters 123 second ddname will be SLSF002, the third SLSF003, and so on until the maximum number of files specified in NBRSLS is reached. If any SLS files are allocated with DD statements in the CICS startup JCL, they should be given ddnames with the first four characters matching the 4-character prefix of SLSDDN. The XSIT transaction cannot be used to override this parameter. SLSDYN Default: NO SLS (source listing support) file definitions can be created dynamically during Xpediter/CICS initialization. This option requires an SLS file with a dataset name that relates to the load library dataset name with the last qualifier either replaced by “SSD” or appended to it. For example, if a load library is named ACME.PAYROLL.LOADLIB, then the related SLS file would be named either ACME.PAYROLL.SSD or ACME.PAYROLL.LOADLIB.SSD. Enter YES to enable the dynamic file definitions or NO to disable this feature. SLSSDB Default: SLSD0001 Enter a 4-character prefix and 4-digit suffix to be used as a template for the ddnames associated with SLS (source listing support) Shared Data Base files. The value of SLSSDB will be used as the ddname template for the SLS Shared Data Base files which are dynamically allocated during SLS member open processing. The XSIT transaction cannot be used to override this parameter. STEPWT Default: 99 Enter the maximum number of statements to execute with a GO command if the delay interval is greater than 0 seconds. STEPWT0 Default: 5000 Enter the maximum number of statements to execute with a GO command if the delay interval is equal to 0 seconds. STOP Default: YES Enter NO to prohibit setting breakpoints. SUBSYS Default: XDSS Enter a four-character MVS subsystem name, such as XDSS, to make the Xpediter/CICS subsystem available. This should be a new subsystem ID defined specifically for use by the Xpediter/CICS subsystem. You may optionally specify the Xpediter/CICS subsystem ID in SYS1.PARMLIB(IEFSSNxx) for system documentation purposes. Consult your site’s MVS system programmer. For more information, see “Specifying Xpediter Service Provider Parameters”. SUBUBCK Default: YES If the value of SUBUBCK is YES, then Xpediter/CICS will check if the upper bound of subscripts has been exceeded. If it has, the informational message SUBSCRIPT OUT OF BOUNDS will be displayed. If the value of SUBUBCK is NO, the upper bounds check will not be performed. 124 Xpediter/CICS Advanced Configuration Guide SUPSESM Default: “NO” The message “XPEDITER/CICS SESSIONS NOT ACTIVE” will be suppressed from being written to the CSMT queue if all of the following occur: • The value of SUPSESM is “YES”. • The customer has AUTO SESSION TERMINATION active. • A terminal is disconnected or logged off and does not have an Xpediter/CICS session active. If the value of SUPSESM is “NO” the above message will be written as designed. TCBNR Default: 4 Designates the maximum number of subtasks that can be attached when multiple requests are made against a PDSE dataset. This parameter is utilized only when a site has PDSE datasets in its DFHRPL concatenation or in an installed LIBRARY. Entering 0 disables PDSE support and should only be done if there are no PDSE datasets in your DFHRPL concatenation or installed LIBRARY. The value specified must be an unsigned integer in the range of 0 to 10. Setting TCBNR to a higher value will make it more resource intensive. The XSIT transaction cannot be used to override this parameter. TRANSUC Default: YES Enter YES to uppercase the transaction identifier on the Trap Summary, Program Trace, and Storage Protection screens. Enter NO if you want the case to remain as you typed it on these screens. TRAPIPU Default: NO Enter YES to make the terminal’s user ID the default value in the USERID field for any TCPIP-based traps. TRAPIPU may be set to YES regardless of the value for parameter UNIQUEIP. (See “UNIQUEIP” for more information.) TRAPIPU should be set to YES when: • All TCPIP-based transactions in your environment require signon • The same user ID is used for TCPIP transactions and the 3270 debugging session • That user ID is not shared by multiple CICS users. The user ID will uniquely identify TCPIP-based traps even when the IP address does not. TRAPNET Default: NO Enter YES to make the current terminal NETNAME the default for the NETNAME field on the Trap Summary screens (1.6 and 9.6). Enter NO to make ALL (asterisks) the default. TRAPTRM Default: YES Enter YES to make the current terminal ID the default for the TERM field on the Trap Summary screens (1.6 and 9.6). Enter NO to make ALL (asterisks) the default. TRAPUSR Default: NO Configuration Parameters 125 Enter YES to make the current userID the default for the USERID field on the Trap Summary screens (1.6 and 9.6). Enter NO to make ALL (asterisks) the default. TRPLOAD Default: NO Loads saved traps at session start. This parameter is ignored if the profile dataset is in the old format. Valid entries are: YES: Loads saved traps at session start. NO: Does not load saved traps at session start. TRPSAVE Default: YES Saves traps automatically at session end. This parameter is ignored if the profile dataset is in the old format. Valid entries are: YES: Saves traps automatically at session end. NO: Does not save traps automatically at session end. TRPXABD Default: No user entries Enter one or more abend codes to be excluded from Xpediter’s automatic abend trapping function using the following format: TRPXABD=abend_code Multiple abend codes must be separated with commas and enclosed in parentheses. Continuation characters are not supported, but repeated lines can be used to build a list of excluded abend codes. An asterisk (*) can be used to specify all abend codes starting with the same character(s), but full wildcarding is not supported. For example: TRPXABD=(ABD1,ABD2,ABD3) TRPXABD=(ABD4,ABD5,ABD6) TRPXABD=ABD7 TRPXABD=AE* Previous entries added with the override facility or the XSIT transaction can be deleted by specifying the following entry on a single line: TRPXABD=REMOVE-ALL-ENTRIES In addition to the abend codes specified, there are system-defined entries that cannot be removed. TSQID Default: XPED Enter the name of the Temporary Storage Queue ID that the file utility must use. This queue communicates between the screen and file processors. This queue must not be defined in the Temporary Storage Table (TST) or in the TSMODEL entry in the CSD as recoverable. UNIQUEIP Default: NO 126 Xpediter/CICS Advanced Configuration Guide If automatic abend trapping is on (see “DEFTRAP”) and each of your TCPIP-connected workstations has a unique IP address, enter YES, and Xpediter will automatically generate unique TCPIP-based traps for individual debugging sessions. Various techniques and hardware are used to connect workstations to the mainframe. If the connection method used in your environment provides a unique IP address for each TCPIPconnected workstation, change this parameter to YES to automatically generate unique TCPIP-based traps. If multiple TCPIP-connected workstations share the same IP address, and user IDs are also not unique (see parameter “TRAPIPU”), enter NO. UPDTDL1 Default: (ON,ON,ON) Enter OFF to disable updates of DL/I segments in the file utility for the specified transaction. UPDTDS Default: (ON,ON,ON) Enter OFF to disable updates of datasets in the file utility for the specified transaction. UPDTSEC Default: (OFF,OFF,OFF) Enter OFF to prohibit the display and use of an update password on selected screens. Valid values are ON and OFF. See “Implementing the Memory Update Security Exit” for information on password security and this parameter. UTILMOD Default: NO Enter YES to designate Utilities Mode operation. Users will only have access to the file utility, storage display facility, and source listing utility, and Xpediter’s exits will be disabled. Refer to “Configuring Restricted Operating Modes” for more information about restricted operating modes. The XSIT transaction cannot be used to override this parameter. UXSNOFF Default: NO Controls whether or not the XSNOFF global exit is enabled when Xpediter/CICS initializes. Possible values are: • YES: Xpediter/CICS should enable the XSNOFF exit • NO: Xpediter/CICS should not enable the XSNOFF exit. The DISCONN parameter must also be set to YES for the exit to be enabled. Refer to “Configuring Automatic Session Termination” for considerations of setting UXSNOFF=YES. The XSIT transaction cannot be used to override this parameter. VERFILE Default: YES Enter YES to have Xpediter/CICS verify the presence of the Xpediter files DBUGPRF, DBUGSQL, and DBUGEMP. If these file do not exist in the CICS JCL, warning messages will be issued during the IVP. Because Xpediter issues an open of these files during initialization, DFHFC0951 messages will also be logged. Enter NO to have Xpediter not verify the files. Configuration Parameters 127 XDBP Default: XDBP Enter a four-character transaction ID to substitute for the XDBP transaction used to refresh the DBPA parameters from the DBPA input dataset. XDCC Default: YES Controls whether or not Xpediter/Code Coverage will be activated for use with Xpediter/CICS. Possible values are: • YES: Xpediter/Code Coverage should be activated at Xpediter/CICS initialization. Your site must be licensed for Code Coverage in order for it to be activated. • NO: Xpediter/Code Coverage should not be activated at Xpediter/CICS initialization. XDDBPCL Default: * (asterisk) Enter a one-character JES SYSOUT class to be assigned to the dynamically allocated SYSOUT dataset containing the DBPA transactions processing report. See parameter “ XDDBPRP” below. Valid values are A through Z, 0 through 9, and *. Although the override facility can be used to change XDDBPCL, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDDBPRP Default: XDDBPRPT Enter a one to eight-character ddname for the dynamically allocated SYSOUT dataset containing the DBPA transactions processing report. Although the override facility can be used to change XDDBPRP, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDDBPTY Default: DYNAMIC Enter JCL to have Xpediter use a DD statement in your CICS startup JCL to designate the destination of the report identified by global parameter XDDBPRP. Enter DYNAMIC to have Xpediter dynamically allocate the report dataset. This value of this parameter can be set using the DBPA input dataset. Although the override facility can be used to change XDDBPTY, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDGBLCL Default: * (asterisk) Enter a one-character JES SYSOUT class to be assigned to the dynamically allocated SYSOUT dataset containing the global table parameter overrides processing report. See parameter “ XDGBLRP” below. Valid values are A through Z, 0 through 9, and *. 128 Xpediter/CICS Advanced Configuration Guide Although the override facility is the preferred method to change XDGBLCL, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDGBLRP Default: XDGBLRPT Enter a one to eight-character ddname for the dynamically allocated SYSOUT dataset containing the global table parameter overrides processing report. Although the override facility is the preferred method to change XDGBLRP, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDGBLTY Default: DYNAMIC Enter JCL to have Xpediter use a DD statement in your CICS startup JCL to designate the destination of the report identified by global parameter XDGBLRP. Enter DYNAMIC to have Xpediter dynamically allocate the report dataset. Although the override facility is the preferred method to change XDGBLTY, you can also change it either as described in “Assembling DBUGGBL” or as described in “Updating the Xpediter/CICS Parameters While CICS is Active”. XDLOG Default: NO Enter YES to enable the File Utility Audit Trail. Enter NO to disable the File Utility Audit Trail. For more information, see “Configuring the File Utility Audit Trail”. XDLOGAD Default: FULL Enter FULL to write File Utility Audit Trail entries that include the entire contents of new records when those records are created using the Xpediter File Utility. Enter NONE to write those entries with only the report heading and the record key. XDLOGBK Default: 27930 Enter a decimal integer value (2 byte binary value), divisible by 133, in the range of 133 to 32718 for the blocksize of the File Utility Audit Trail GDG datasets. If the value entered is not divisible by 133, the closest value which is will be substituted. The default of 27930 sets up half track blocking on 3390 DASD. XDLOGDD Default: DYNAMIC Enter DYNAMIC to specify dynamic allocation of the File Utility Audit Trail GDG datasets. The dataset will be given the name specified in XDLOGNM. Enter a 1- to 8-character ddname only if dynamic allocation is not allowed at your site. If a ddname is used, you must add a DD statement to your CICS startup JCL indicating the name of your File Utility Audit Trail GDG dataset. For more information, see “Configuring the File Utility Audit Trail”. Configuration Parameters 129 XDLOGDL Default: FULL Enter FULL to write File Utility Audit Trail entries that include the entire contents of deleted records when those records are deleted using the Xpediter File Utility. This logging does not include mass deletes such as those of temporary storage queues or child segments deleted when a parent segment is deleted. Enter NONE to write those entries with only the report heading and the record key. XDLOGMD Default: blanks If your site wants to allocate a File Utility Audit Trail GDG dataset on non-SMS controlled DASD, enter a 1- to 44-character name for the DSCB on which to model the GDG dataset. You can specify either a model DSCB residing on the same catalog volume as your base GDG definition, or a fully qualified existing GDG dataset name. For information on the definition and use of GDG datasets in a non-SMS environment, refer to the MVS JCL User’s Guide. XDLOGNM Default: XD.LOG.DATASET.GDGNAME Enter the base dataset name to be used for the File Utility Audit Trail GDG dataset. Each time the dataset is allocated, its generation number is incremented by 1, effectively creating a new generation of the dataset. Before the dataset can be used, its model DSCB must be defined with the JCL in member DEFLOGDG. For more information, see “Configuring the File Utility Audit Trail”. XDLOGPA Default: 10 Enter a decimal integer value (3 byte binary value) in the range of 3 to 8,388,607 to specify the number of space units (cylinders, tracks, or blocks) in the primary allocation of the File Utility Audit Trail GDG dataset. XDLOGSA Default: 5 Enter a decimal integer value (3 byte binary value) in the range of 1 to 8,388,607 to specify the number of space units (cylinders, tracks, or blocks) in the secondary allocation of the File Utility Audit Trail GDG dataset. XDLOGTY Default: CYL Enter CYL to specify cylinders as the space unit for the primary and secondary allocation of the File Utility Audit Trail GDG dataset. Enter BLK to specify blocks or TRK to specify tracks. XDLOGUN Default: SYSDA Enter a 1- to 8-character unit name designating the disk unit on which to allocate the File Utility Audit Trail GDG dataset. Unless this parameter is set to blanks, it overrides the value specified for XDLOGVO. To set this parameter to blanks with the global override facility, specify a value of NULL. XDLOGUP Default: FULL 130 Xpediter/CICS Advanced Configuration Guide Enter FULL to write File Utility Audit Trail entries that include the entire contents of updated records when those records are updated using the Xpediter File Utility. This setting allows users to see the context in which even small changes have been made. Enter SHORT to write entries that include only the modified contents of the updated records. SHORT only applies to dataset, temporary storage, and DL/I segment updates. DB2 row updates are not abbreviated in any way. Enter NONE to write those entries with only the report heading and the record key. XDLOGVO Default: blanks Enter a 1- to 6-character volume serial number designating the disk unit on which to allocate the File Utility Audit Trail GDG dataset. Unless the parameter XDLOGUN is set to blanks, it overrides the value specified for this parameter. To set this parameter to blanks with the global override facility, specify a value of NULL. XDSCRPT Default: YES Enter YES to enable the Script Facility. This also enables the CAPTURE and INCLUDE commands. Enter NO to disable the Script Facility as well as the CAPTURE and INCLUDE commands. For more information, see “Configuring the Script Facility”. XDSCRXN Default: ******** Enter a 1- to 8-character script name for the default value to be displayed in the “If YES save as” field on the Script Dataset Allocation screen (0.6). The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. This parameter has no effect unless the XDSCRXO parameter is set to SAVE. The default of eight asterisks (********) is translated by Xpediter to the current userID. With the default, if a user’s debugging session is terminated while they are capturing a script, their userID will be used as the script name. For more information, see “Configuring the Script Facility”. XDSCRXO Default: SAVE Enter SAVE to make YES the default value displayed in the “Save script if CAPTURE ON at session termination?” field on the Script Dataset Allocation screen (0.6). The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. If this field is set to YES and a script is being captured when the user’s debugging session is terminated, Xpediter will attempt to save the script. The value in the If YES save as field will be used as the script name. If a script with that name already exists, it will be overwritten. Enter DISCARD to make NO the default value displayed. If this field is set to NO and a script is being captured when the user’s debugging session is terminated, the captured script commands will be discarded. For more information, see “Configuring the Script Facility”. XDSSACC Default: WRITE Enter WRITE to give Script Facility users read and update access to the system script dataset. Enter READONLY to give Script Facility users read-only access to the system script dataset. For more information, see “Configuring the Script Facility”. Configuration Parameters 131 XDSSAPM Default: ******** Enter a value for the site-wide Xpediter system script auto-play member you want to be read and processed at startup of each session. That value must exist in the system script dataset specified by global parameter XDSSDSN. The XDSSAPM parameter allows you to establish a common script that will be run at session startup for all users site-wide. This script can be used to set profile options for all users. Additional userspecified scripts are run after the system script. If the XDSSAPM value starts with a space or an asterisk (*), the parameter is considered to have no value, and no action is taken. For more information, see “XDSSDSN” and “Configuring the Script Facility”. XDSSDD Default: DYNAMIC Enter DYNAMIC to specify dynamic allocation of your system script dataset. The dataset will be given the name specified in parameter XDSSDSN. Enter a 1- to 8-character ddname only if dynamic allocation is not allowed at your site. If a ddname is used, you must submit JCL to allocate your system script dataset and add a DD statement to your CICS startup JCL indicating the name of your system script dataset. Other batch or CICS regions may be prevented from updating this system script dataset while your CICS region is active. For more information, see “Configuring the Script Facility”. XDSSDSN Default: XD.SYSTEM.SCRIPT.DATASET Enter a 1- to 44-character system script dataset name to be used if your site allows dynamic allocation of datasets. The selected dataset name is displayed in the System Dataset Name field on the Script Dataset Allocation screen (0.6). If parameter XDSSDD is not set to DYNAMIC, this parameter is ignored. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDTRCRP Default: XDTRCRPT Enter a one to eight-character ddname for the dynamically allocated SYSOUT dataset containing the program trace print output. Although the override facility can be used to change XDTRCRP, you can also change it as described in “Assembling DBUGGBL”. XDUSBLK Default: 27960 Enter a decimal integer value (2 byte binary value), divisible by 120, in the range of 0 to 32760 for the default value to be displayed in the Block Size field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Block Size field will be used when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. 132 Xpediter/CICS Advanced Configuration Guide XDUSCR Default: YES Enter YES to enable user-defined user script datasets. Your site must allow dynamic allocation of datasets in CICS regions, and parameter XDUSDD must also be set to DYNAMIC. Enter NO to prohibit user script datasets. Enter SHARED to restrict all users to a single shared user script dataset defined during Xpediter installation. This parameter also controls the default value to be displayed in the Dataset to use field on the Script Dataset Allocation screen (0.6). If XDUSCR=YES or SHARED, the default in the Dataset to use field will be U for user. If XDUSCR=NO, the default in the Dataset to use field will be S for system. The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Directory Blocks field will be used when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. XDUSDB Default: 44 Enter a decimal integer value (3 byte binary value) in the range of 1 to 8,388,607 for the default value to be displayed in the Directory Blocks field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Directory Blocks field will be used when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. XDUSDC Default: blanks If dynamically allocating SMS-controlled user script datasets, enter a 1- to 8-character data class name for the default value to be displayed in the Data Class field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Data Class field will be used when a new SMS-controlled user script dataset is dynamically allocated. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSDD Default: DYNAMIC Enter DYNAMIC to enable dynamically allocated user-defined user script datasets. Enter a 1- to 8-character ddname only if dynamic allocation of datasets in CICS regions is not allowed at your site or if your site wants to restrict all its users to a single shared user script dataset. If a ddname is used, you must submit JCL to allocate your user script dataset and add a DD statement to your CICS startup JCL indicating the name of your user script dataset. Other batch or CICS regions may be prevented from updating this user script dataset while your CICS region is active. For more information, see “Configuring the Script Facility”. XDUSDSN Default: userID.SCRIPT.DATASET Enter a 1- to 44-character user script dataset name suffix for the default value to be displayed in the User Dataset Suffix field on the Script Dataset Allocation screen (0.6). The value in this field is appended to the value in the User Dataset Prefix field (see parameter “XDUSPFX”) when a new user script dataset is dynamically allocated. The resulting user script dataset name must be no longer than 44 characters. The value established as the default for this field can be overridden by the user, and the Configuration Parameters 133 new value will be saved in their profile dataset. This parameter is ignored unless XDUSDD is set to DYNAMIC and XDUSCR is set to SHARED. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSLIB Default: NO If dynamically allocating SMS-controlled user script datasets, enter YES to make YES the default value to be displayed in the Library field on the Script Dataset Allocation screen (0.6). Enter NO to make NO the default value displayed. The value in this field is used when a new user script dataset is dynamically allocated. If the Library field is set to YES, an SMS-controlled PDSE user script dataset will be allocated. If the Library field is set to NO, a PDS user script dataset will be allocated. The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. For more information, see “Configuring the Script Facility”. XDUSMC Default: blanks If dynamically allocating SMS-controlled user script datasets, enter a 1- to 8-character management class for the default value to be displayed in the Management Class field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Management Class field will be used when a new user script dataset is dynamically allocated. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSPA Default: 15 Enter a decimal integer value (3 byte binary value) in the range of 1 to 8,388,607 for the default value to be displayed in the Primary field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Primary field will be used as the number of space units (cylinders, tracks, or blocks) in the primary allocation when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. XDUSPFX Default: blanks Enter a 1- to 44-character user script dataset name prefix for the default value to be displayed in the User Dataset Prefix field on the Script Dataset Allocation screen (0.6). The value in this field is combined with the value in the User Dataset Suffix field (see parameter XDUSDSN) when a new user script dataset is dynamically allocated. The resulting user script dataset name must be no longer than 44 characters. The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. This parameter is ignored unless XDUSDD is set to DYNAMIC and XDUSCR is set to SHARED. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSSA Default: 15 134 Xpediter/CICS Advanced Configuration Guide Enter a decimal integer value (3 byte binary value) in the range of 1 to 8,388,607 for the default value to be displayed in the Secondary field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Secondary field will be used as the number of space units (cylinders, tracks, or blocks) in the secondary allocation when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. XDUSSC Default: blanks If dynamically allocating SMS-controlled user script datasets, enter a 1- to 8-character storage class for the default value to be displayed in the Storage Class field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Storage Class field will be used when a new user script dataset is dynamically allocated. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSSMS Default: NO Enter YES to make YES the default value displayed in the Allocate SMS dataset field on the Script Dataset Allocation screen (0.6). Enter NO to make NO the default value displayed. The value in this field is used when a new user script dataset is dynamically allocated. If the Allocate SMS dataset field is set to YES, an SMS-controlled user script dataset will be allocated. If the Allocate SMS dataset field is set to NO, the user script dataset allocated will not be SMS-controlled. The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. For more information, see “Configuring the Script Facility”. XDUSTYP Default: TRK Enter TRK to make TRK the default value displayed in the Space Units field on the Script Dataset Allocation screen (0.6). Enter BLK to make BLK the default value displayed, or CYL for a default of CYL. The value established as the default for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Space Units field will be used to designate whether cylinders, tracks, or blocks will be used when a new user script dataset is dynamically allocated. For more information, see “Configuring the Script Facility”. XDUSUNI Default: SYSDA Enter a 1- to 8-character unit name for the default value to be displayed in the Unit field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Unit field designates the unit name on which a new user script dataset is to be dynamically allocated. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XDUSVOL Default: blanks Configuration Parameters 135 Enter a 1- to 6-character volume serial for the default value to be displayed in the Volume Serial field on the Script Dataset Allocation screen (0.6). The default value for this field can be overridden by the user, and the new value will be saved in their profile dataset. The value in the Volume Serial field designates the volume serial number on which a new user script dataset is to be dynamically allocated. To set this parameter to blanks with the global override facility, specify a value of NULL. For more information, see “Configuring the Script Facility”. XFERDDN Default: DBUGSQL Enter a one to seven-position ddname of the dataset used to save SQL calls generated in the DB2 file utility. This dataset allows a user of the DB2 file utility to develop DB2 queries (SELECT statements) and save the generated code. The Xpediter/CICS offline utility, DBSQLUTL, can then be used to write this information to a user-specified dataset for inclusion into program code. XIVP Default: XIVP Enter a four-character transaction ID to substitute for the XIVP transaction used to invoke the Xpediter/CICS Installation Verification Program. XLGI Default: XLGI Enter a four-character transaction ID to substitute for the XLGI transaction. This transaction is internally invoked and should not be executed from a terminal. XLOG Default: XLOG Enter a four-character transaction ID to substitute for the XLOG transaction used to start, stop, or switch the dataset of the Xpediter/CICS File Utility Audit Trail. XPED Default: XPED Enter a four-character transaction ID to substitute for the XPED transaction. The XPED parameter can only be changed as described in “Assembling DBUGGBL”. Changing XPED requires changing the resource definitions. XPFS Default: XPFS Enter a four-character transaction ID to substitute for the XPFS transaction used for SLS dataset processing. The XSIT trans cannot be used to override this parameter. XPGD Default: XPGD Enter a four-character transaction ID to substitute for the XPGD transaction used to limit access to Xpediter/CICS debugging facilities through the use of Xpediter/Eclipse. XPND Default: XPND Enter a four-character transaction ID to substitute for the XPND transaction used for debugging session termination. 136 Xpediter/CICS Advanced Configuration Guide XPN0 Default: XPN0 Enter a four-character transaction ID to substitute for the XPN0 transaction. Changing XPN0 requires changing the resource definitions. XPOF Default: XPOF Enter a four-character transaction ID to substitute for the XPOF transaction used to invoke the Xpediter/CICS shutdown facility. XPOFTCWT Default: 0 Enter the number of seconds Xpediter is to wait prior to each terminal SEND/RECEIVE issued during execution of the XPOF transaction. Valid values are 0 to 9. XPON Default: XPON Enter a four-character transaction ID to substitute for the XPON transaction. The XPON parameter can only be changed as described in “Assembling DBUGGBL”. Changing XPON requires changing the resource definitions. XPRT Default: XPRT Enter a four-character transaction ID to substitute for the XPRT transaction. The XPRT parameter can only be changed as described in “Assembling DBUGGBL”. Changing XPRT requires changing the resource definitions. XPSP Default: XPSP Enter a four-character transaction ID to substitute for the XPSP transaction. The XPSP parameter can only be changed as described in “Assembling DBUGGBL”. Changing XPSP requires changing the resource definitions. XREL Default: XREL Enter a four-character transaction ID to substitute for the XREL transaction. Changing XREL requires changing the resource definitions. XSIT Default: XSIT Enter a four-character transaction ID to substitute for the XSIT transaction used to invoke the Xpediter/CICS Global Table Override Update Utility. XSRE Default: XSRE Enter a four-character transaction ID to substitute for the XSRE transaction. Changing XSRE requires changing the resource definitions. XSRE is used to initiate remote event notifications when using Xpediter/Eclipse. Configuration Parameters 137 XTMO Default: XTMO Enter a four-character transaction ID to substitute for the XTMO transaction. Changing XTMO requires changing the resource definitions. XTMO is used to initiate inactive session termination checking, which would be started when Xpediter/CICS is started in any region. If either XTMOCHK or XTMOINT is 0, the XTMO transaction (or equivalent) will not be started, effectively disabling inactive session termination. XTMOCHK Default: 0 Enter how frequently, in minutes, XTMO should be restarted for inactive session termination checking. This means that whenever the number of minutes specified for XTMOCHK have elapsed, transaction XTMO will be started via Interval Control to check for possible inactive sessions. If the value is set to 0, inactive session termination is disabled. Valid values are 0 to 240. XTMOINT Default: 0 Enter the interval, in minutes, used to define when a session is considered inactive. If no activity has occurred in a debugging session within this interval, the session will be deemed inactive and will be terminated. If the value is set to 0, inactive session termination is disabled. Valid values are 0 to 240. XTMOTRV Default: NO Enter YES to terminate Runtime Visualizer sessions that have timed out. If you enter YES, any Runtime Visualizer sessions that are deemed to be inactive will be terminated. If you enter NO, Runtime Visualizer sessions will never timeout. Default Member XVGB00 Xpediter/Code Coverage parameters all relate to CICS and are delivered with Xpediter/CICS. COUNT Default: YES When this option is set to YES, Xpediter/Code Coverage will monitor application programs and increment verb counts as each instruction is executed. This is a very CPU-intensive process. Set this option to NO when it is not necessary to count each time a verb is executed. When COUNT=NO, Xpediter/Code Coverage will count each verb only the first time it is executed. To maximize the potential performance benefit of COUNT=NO, rules for Storage Protection and Program Trace are ignored when COUNT=NO and a Code Coverage test is active. When Xpediter/Code Coverage global table parameter COUNT=NO, the System Flow feature of Xpediter/Code Coverage cannot be used. An error message is displayed if you attempt to activate either System Flow or Both (Code Coverage plus System Flow). 138 Xpediter/CICS Advanced Configuration Guide When COUNT is set to NO: • Only one Xpediter/Code Coverage test at a time may be active in the CICS region. • Each application program you execute is marked as RESIDENT until every verb within it has been executed or the Xpediter/Code Coverage test has been halted. If you encounter a Short on Storage (SOS) situation using COUNT=NO, reduce the number of programs referenced by your Xpediter/Code Coverage test. • CPU consumption may actually increase, depending on the structure of your Xpediter/Code Coverage test. When the same code is executed multiple times, COUNT=NO will reduce CPU consumption by a factor related to how many times the code is executed. However, when different code is executed by each transaction and there is very little reuse of the same code, COUNT=NO can cause a noticeable increase in CPU consumption. CTLGMT Default: YES Optionally capture System Flow data with local time (CTLGMT=NO). Specifying CTLGMT=YES will capture System Flow data with GMT/UTC. FILTDEFU Default: NO Prime the Owner column filter value with the current userID (FILTDEFU=YES). Prime the Owner column filter with asterisks (FILTDEFU=NO). INTERVAL Default: 42 The number of minutes between automatic data extractions. Valid values are from 1 to 1440. LOGQ Default: CSMT The four-character name of the transient data queue to which Code Coverage is to direct error messages. This parameter cannot be changed when Code Coverage is active. It may be changed at Xpediter/Code Coverage initialization when the override file is initially processed. PROGCNTS Default: ******** Specifying PROOGCNTS=******** causes program counts for a program to be kept separate by userID. Specifying PROGCNTS=USER1234 causes program counts to be kept under userID USER1234 for program(s) being covered, regardless of the userID(s) that executed the program(s). SUBMIT Default: YES Whether or not to automatically submit the Code Coverage template JCL during extraction. Enter NO to disable the automatic submission during extraction. If SUBMIT is set to NO, the JCL to write the extracted data to the Code Coverage repository would need to be submitted manually. WTDQ Default: YES Used to disable the write to transient data queue function for Informational Data Extraction messages (XVTC4nnnI). The queue name is specified by the LOGQ parameter. Enter NO to disable. Configuration Parameters 139 WTO Default: YES Used to disable the write-to-operator (WTO) function for the XVTC4001 Data Extraction complete message and other Informational Data Extraction messages (XVTC4nnnI). A WTO is normally issued each time a data extraction is performed. Enter NO to disable. XVCC Default: XVCC A four-character transaction ID to substitute for the XVCC transaction. Changing the XVCC requires changing the supplied resource definition. XVGBLCL Default: * (asterisk) A one-character JES SYSOUT class to be assigned to the dynamically allocated SYSOUT dataset containing the global table parameter overrides processing report. See parameter XVGBLRP below. Valid values are A through Z and 0 through 9. XVGBLRP Default: XVGBLRPT A one- to eight-character ddname for the dynamically allocated SYSOUT dataset containing the global table parameter overrides processing report. XVGBLTY Default: DYNAMIC The type of allocation to be performed for the output report dataset. Possible values for this parameter are either JCL or DYNAMIC. If JCL is specified, Xpediter/Code Coverage will require a sysout DD statement in the CICS startup JCL to designate the output report identified by global parameter XVGBLRP. If JCL is selected, XVGBLCL will be ignored if specified. If DYNAMIC is specified, Code Coverage will dynamically allocate the report dataset. DYNAMIC is the default specification. XVKP Default: XVKP A four-character transaction ID to substitute for the XVKP transaction. Changing the XVKP requires changing the supplied resource definition. XVKP is an internal transaction that you should never enter from a terminal. Also, because the XVKP transaction is run asynchronously, security should not be set on it. XVSC Default: XVSC A four-character transaction ID to substitute for the XVSC transaction. Changing the XVSC requires changing the supplied resource definition. XVSI Default: XVSI 140 Xpediter/CICS Advanced Configuration Guide A four-character transaction ID to substitute for the XVSI transaction. Changing the XVSI requires changing the supplied resource definition. XVTQ Default: XVTQ A four-character transaction ID to substitute for the XVTQ transaction. Changing the XVTQ requires changing the supplied resource definition. Methods of Specifying and Updating Parameters This section describes the methods of specifying and updating parameters. CMSC PARMLIB Xpediter/CICS allows you to specify most configuration parameter values using CMSC PARMLIB at product initialization. Parameters are specified in CMSC PARMLIB member XDGBxxxx. All parameters can be specified using CMSC PARMLIB with the exception of the following parameters: • • • • • DBPA XPED XPON XPRT XPSP. These parameters can only be specified by editing and assembling DBUGGBL. See “Assembling DBUGGBL” for more details. Updating the CMSC with Your PARMLIB Members If you have made changes to your PARMLIB members, you can use the z/OS MODIFY (F) command to update the CMSC with those changes. Refreshing All PARMLIB Members F cmscname,PARMLIB REFRESH Refreshing a Single Parameter Member F cmscname,PARMLIB REFRESH member_name Updating the Xpediter/CICS Parameters While CICS is Active If you have made changes to your PARMLIB members while CICS is active, you can use transaction XSIT to update the active CICS region with those changes. All parameter values can be updated by entering the transaction XSIT. XSIT directs CMSC to refresh the PARMLIB members for this CICS region. It then updates Xpediter in this CICS region with the parameters from CMSC. If you execute XSIT while Xpediter is active, the following parameters will not be updated: • • • • CCUPDT CICSOTE CELLSIZ CICSPLX Configuration Parameters • • • • • • • • • • • • • • 141 ESDBUFS MONSIZE NBRSLS PROFDDN RQCHSIZ SLSDDN SLSDYN SLSSDB SUBSYS TCBNR UTILMOD UXSNOFF XDCC XPFS. Script Facility Parameters The following parameters cannot be dynamically updated using XSIT while the Script Facility is active: • XDSSDD • XDUSDD File Utility Audit Trail Parameters The following parameters cannot be dynamically updated using XSIT while the File Utility Audit Trail is active: • • • • • • • • • • • • • XDLOG XDLOGAD XDLOGBK XDLOGDD XDLOGDL XDLOGMD XDLOGNM XDLOGPA XDLOGSA XDLOGTY XDLOGUN XDLOGUP XDLOGVO. Assembling DBUGGBL SMXDSAMP member DBUGGBL contains sample source and JCL to assemble and link DBUGGBL. If you must change the values of parameters DBPA, XPED, XPON, XPRT, XPSP, enter the desired values in DBUGGBL and then assemble and link it. Ensure that the assembly has the ALIGN option. DBUGGBL should be linked with AMODE=31 and RMODE=24 (below the line) and must not be linked as reentrant. Xpediter must be reinitialized to implement the changes. Creating Additional Members for Region Customization Xpediter/CICS has a facility to effectively concatenate one or more members to each of its default CMSC PARMLIB members upon loading them. The names of these members must begin with the same four-character prefix as the prefix of the default CMSC PARMLIB member to which they will be concatenated. The members may specify any number of parameters that are appropriate to their CMSC prefix. When the same parameter is specified multiple times across the concatenated members 142 Xpediter/CICS Advanced Configuration Guide the last encountered setting is used. The Xpediter/CICS Index Member in CMSC PARMLIB, XD$$00, assigns a set of CMSC PARMLIB members for this purpose to CICS regions based on APPLID. For example, you may decide to customize the various overrides and inputs to tailor them to a specific set of applications or CICS regions. You may have several test regions that require unique parameter settings specific to those regions, or you may have certain testing options you want to make available to users in particular regions. In these cases, you can create CMSC PARMLIB members that contain a subset of overrides or input. The Index Member is optional and only needed if you want to override default members. Each region that you want to customize with additional overrides or input will contain one or more entries in the Index Member. The format of entries within the Index Member is very simple: • Blank lines are ignored • Any entry with an asterisk (*) in column 1 is considered to be a comment and is ignored • Each entry specifies the applid of a region starting in column 1, followed by an equal sign(=), followed by up to seven CMSC PARMLIB member names. For example: CICSTEST=XDGB00P,XDGBTEST,XDDBTEST,XVGB00P • If you need to specify more than seven member names, you can code additional entries with the same Applid, an equal sign (=), and again up to seven additional member names. For example: CICSTEST=XDGB00P,XDGBTEST CICSTEST=XDDBTEST,XVGB00P • If the list of member names is followed by a blank, anything to the right is considered a comment. For example: CICSTEST=XDGB00P,XDGBTEST Xpediter/CICS Global Table Overrides • There is no limit to the number of regions you can define within the Index Member and no limit to the number of individual region entries you can specify. In the following example, a site has several CICS regions. They are divided into two CICSPLEX configurations: one for production and one for testing. There are also individual production and test regions intended for additional applications separate from those running within the CICSPLEX environments. Figure 26 provides a diagram of this sample CICS configuration. Configuration Parameters 143 Figure 26. Sample CICS Region Configuration CICSPROD CICSTEST TESTPLEX TESTTOR TESTAOR1 TESTAOR2 The CMSC PARMLIB is used to establish the following overrides and inputs for the sample CICS configuration shown in Figure 26: • Region TESTTOR is a terminal owning region and typically does not have Xpediter/CICS or Xpediter/Code Coverage installed in it (other than Xpediter/CICS and/or Xpediter/Code Coverage transaction definitions). • All other regions will have Xpediter/CICS and Xpediter/Code Coverage installed. The default settings in XDGB00, XDDB00, and XVGB00 will apply to these regions. • Region CICSPROD is a production region. In addition to the default settings, the site wants to ensure that the production settings are applied to this region as well. In addition to the default settings, XDGB00P and XVGB00P will be used to override any of the default settings. • Regions CICSTEST, TESTAOR1, TESTAOR2, and TESTAOR3 are test regions. The site creates three members - XDGBTEST, XDDBTEST, and XVGBTEST - that contain overrides and input for Xpediter/CICS Global Table Parameters, Xpediter/CICS DBPA input, and Xpediter/Code Coverage Global Table Parameters respectively. • The site has decided that they want specific overrides and input to apply to the applications in their CICSPLEX AORs. They define these in members XDGBAPPL, XDDBAPPL, and XVGBAPPL. • The site also decides that they want specific settings for region CICSTEST. They define three additional members with these specific settings: XDGBTPD, XDDBTPD, and XVGBTPD. • The site then decides that the AOR regions TESTAOR1 and TESTAOR3 need additional changes. They define members XDGBAOR1, XDDBAOR1, and XVGBAOR1 with these changes. • The site decides that region TESTAOR2 needs additional adjustments, so they create members XDGBAOR2, XDDBAOR2, and XVGBAOR2. Figure 27 shows an example of statements needed in the Index Member for the environment illustrated above. Note that the overrides defined for CICSTEST, TESTAOR1, and TESTAOR2 are all defined by grouping members by type. Alternatively, the overrides defined for TESTAOR3 are defined with multiple types of members on a single line. Either method of defining overrides can be used. 144 Xpediter/CICS Advanced Configuration Guide Figure 27. Sample Reformatted Index Member *--------------------------------------------------------------------------------------- * Overrides and input for CICSPROD *--------------------------------------------------------------------------------------- CICSPROD=XDGB00P Xpediter/CICS Global Table Overrides CICSPROD=XVGB00P Xpediter/CICS Code Coverage Global Table Overrides  *--------------------------------------------------------------------------------------- * Overrides and input for CICSTEST *--------------------------------------------------------------------------------------- CICSTEST=XDGBTEST,XDGBTPD Xpediter/CICS Global Table Overrides CICSTEST=XDDBTEST,XDDBTPD Xpediter/CICS DBPA Input CICSTEST=XVGBTEST,XVGBTPD Xpediter/CICS Code Coverage Global Table Overrides  *--------------------------------------------------------------------------------------- * Overrides and input for TESTAOR1 *--------------------------------------------------------------------------------------- TESTAOR1=XDGBTEST,XDGBAPPL,XDGBAOR1 Xpediter/CICS Global Table Overrides TESTAOR1=XDDBTEST,XDDBAPPL,XDDBAOR1 Xpediter/CICS DBPA Input TESTAOR1=XVGBTEST,XVGBAPPL,XVGBAOR1 Xpediter/CICS Code Coverage Global Table Overrides  *--------------------------------------------------------------------------------------- * Overrides and input for TESTAOR2 *--------------------------------------------------------------------------------------- TESTAOR2=XDGBTEST,XDGBAPPL,XDGBAOR2 Xpediter/CICS Global Table Overrides TESTAOR2=XDDBTEST,XDDBAPPL,XDDBAOR2 Xpediter/CICS DBPA Input TESTAOR2=XVGBTEST,XVGBAPPL,XVGBAOR2 Xpediter/CICS Code Coverage Global Table Overrides  *--------------------------------------------------------------------------------------- * Overrides and input for TESTAOR3 *--------------------------------------------------------------------------------------- TESTAOR3=XDGBTEST,XDDBTEST,XVDBTEST,XDGBAPPL,XDDBAPPL,XVGBAPPL TESTAOR3=XDGBAOR1,XDDBAOR1,XVGBAOR1 Creating Index Member XD$$00 Using the above examples as guides, create the Index Member XD$$00 for your environment. Xpediter/CICS Index Member Processing During input processing, the Index Member is read. For each entry that matches the applid of a region in which Xpediter/CICS and Xpediter/Code Coverage are running, that region is scanned to determine the type of input being processed. If the current input being processed is for Xpediter/CICS Global Table Parameters, those members prefixed with XDGB will be selected for input. If the current input being processed is for Xpediter/CICS DBPA input, those members prefixed with XDDB will be selected for input. And finally, if the current input being processed is for Xpediter/Code Coverage Global Table Parameters, those members prefixed with XVGB will be selected for processing. The order of processing for each input type will always begin with the member suffixed with "00" and be followed in order using the associated members coded within the Index Member. This processing order allows you to create multiple input members that can be shared among regions, with additional input members that are specific to individual regions or types of regions. Xpediter/CICS Index Member Migration Example The example shown in Figure 28 is intended for existing Xpediter/CICS and Xpediter/Code Coverage sites running releases prior to 17.02. It presents a sample CICS startup JCL segment for region TESTAOR4. The segment shows the site’s current XDGBLINP, XVGBLINP, and XDDBPINP DD and Configuration Parameters 145 dataset concatenations. The comments denote the changes the site would make to their CMSC PARMLIB members. Figure 28. Migration Example //XDGBLINP // // //* //XVGBLINP // // // //* //XDDBPINP // //* DD DISP=SHR,XPEDITER.SMXDSAMP(DBCGBLT) DD DISP=SHR,XPEDITER.PARMLIB(GBLTEST) DD DISP=SHR,XPEDITER.PARMLIB(GBLAPPL) replace with CMSC PARMLIB member XDGB00 copy to CMSC PARMLIB member XDGBTEST copy to CMSC PARMLIB member XDGBAPPL DD DD DD DD replace copy to copy to copy to DISP=SHR,XPEDITER.SMXDSAMP(XVCGBLT) DISP=SHR,XPEDITER.PARMLIB(XVCTEST) DISP=SHR,XPEDITER.PARMLIB(XVCAPPL) DISP=SHR,SYS9.XPED.PARMLIB(XVCAOR4) DD DISP=SHR,XPEDITER.PARMLIB(DBPATEST) DD DISP=SHR,XPEDITER.PARMLIB(DBPAAPPL) with CMSC CMSC CMSC CMSC PARMLIB member XVGB00 PARMLIB member XVGBTEST PARMLIB member XVGBAPPL PARMLIB member XVGBAOR4 copy to CMSC PARMLIB member XDDBTEST copy to CMSC PARMLIB member XDDBAPPL The resulting Index Member entries for TESTAOR4 match the sample entries (grouped members by type and multiple member types on a single line, respectively) as shown here: *--------------------------------------------------------------------------------------- * Overrides and input for TESTAOR4 *--------------------------------------------------------------------------------------- TESTAOR4=XDGBTEST,XDGBAPPL Xpediter/CICS Global Table Overrides TESTAOR4=XDDBTEST,XDDBAPPL Xpediter/CICS DBPA Input TESTAOR4=XVGBTEST,XVGBAPPL,XVGBAOR4 Xpediter/CICS Code Coverage Global Table Overrides . . . TESTAOR4=XDGBTEST,XDDBTEST,XVGBTEST,XDGBAPPL,XDDBAPPL,XVGBAPPL,XVGBAOR4 DBPA Input Guidelines The skeleton XDDB00 member you created in the CMSC PARMLIB can be used as the basis for any new members. To use DBPA input, simply add the desired transactions below the comment box in your DBPA transaction member. DBPA Transactions contains a section on the correct formatting of DBPA transactions. Keep the following processing rules in mind when adding DBPA transactions: • Blank records are ignored • Records starting with an asterisk (*) in column 1 are treated as comments • Only columns 1 through 72 of a record are processed. Anything beyond column 72 is ignored DBPA Transactions The DBPA transaction sets abend traps or storage protection entries when Xpediter/CICS is first started. If you turn storage protection on, some transactions already running may not be protected. The general format for the DBPA transaction is: DBPA screen-ID keyword=value,keyword=value, . . . keyword=value 146 Xpediter/CICS Advanced Configuration Guide Positions 1 through 4 are for DBPA. Position 5 is blank. Positions 6 through 10 represent one of the following screens: • • • • • • Trap Summary (1.6, 9.6) Monitor Exceptions (9.4.1) CSECT Exclusions (9.5) Storage Exceptions (9.7) Storage Protection (9.8) Define System Labels (9.9) Keywords follow the screen ID by one space, then the screen keywords which are separated by commas. The keywords and values may continue through position 79. A typical sequence is shown in the following example: DBPA DBPA DBPA DBPA DBPA DBPA ON (required only for sequential terminal input) 9.9 keyword=value,keyword=value,...,keyword=value 9.9 keyword=value,keyword=value,...,keyword=value 9.9 keyword=value,keyword=value,...,keyword=value 9.7 keyword=value,keyword=value,...,keyword=value 9.8 keyword=value,keyword=value,...,keyword=value Keywords longer than two positions may be spelled out fully or abbreviated. After two positions, each keyword is unique. Therefore, only two positions are required. More than two positions may be used for clarity. For example, TERMINAL may be TERMNL, TERM, or just TE. In a few cases, alternate abbreviations are allowed, such as: PROGRAM, PROG, PR or PGRM, PGM, PG. The keywords, abbreviations, and examples for the Storage Exceptions (9.7), Storage Protection (9.8), and Define System Labels (9.9) screens differ from those for the Trap Summary (1.6, 9.6), Monitor Exceptions (9.4.1), and CSECT Exclusions (9.5) screens. Trap Summary Keywords The keywords for creating entries for the Trap Summary screens (1.6 and 9.6) are defined in Table 18. Table 18. Trap Summary Keywords Keyword Abbreviation Default OWNER= OW= Comments REQUIRED ID of the terminal that owns this trap. TERMINAL= TE= **** ID of the terminal to be trapped. PROGRAM= PR= or PGM= PG= ******** ID of the program to be trapped. TRAN= TR= **** ID of the transaction to be trapped. TYPE= TY= XPSP Specifies the Xpediter debugging transaction invoked when  an abend is trapped. Valid values are XPSP, XPED, and XPRT. TABEND= TA= Y Allows optional bypass of abend trapping if N is specified. USERID= US= ******** Signon ID to be trapped. NETNAME= NE= ******** NETNAME of the terminal to be trapped. IF= None Specifies enhanced trap conditions. IF= Enhanced Trap Conditions Xpediter now enables trapping based on enhanced conditions. More information can be found in the Xpediter/CICS Reference Manual under “Trap Summary (1.6)” and “Trap Summary (9.6)”. These enhanced conditions can be specified using DBPA entries that conform to the following requirements: • An initial entry for the 1.6 or 9.6 screen must be followed by a second enhanced condition entry with the same values as the initial entry for screen-ID and OWNER. Configuration Parameters 147 • The OWNER value in the second entry must be immediately followed by a comma (,) and the IF keyword: ,IF=(enhanced-condition) • The enhanced condition entry must come after the initial entry, but other DBPA entries are permitted between the two. Only the first correctly specified enhanced condition entry will be used. The following examples show how to use the DBPA 1.6 transaction: Example 1 Enter the following values to invoke XPRT for all abends occurring at terminal ID CA10. Since the OWNER terminal ID is also CA10, Xpediter is invoked when an abend occurs. DBPA 1.6 OWNER=CA10,TERMINAL=CA10,TYPE=XPRT Example 2 Enter the following values to invoke XPSP on terminal ID TF16 whenever a transaction abend occurs. Terminal ID TF16 receives a remote abend bulletin when an abend occurs. DBPA 1.6 OWNER=TF16,TERMINAL=*,TYPE=XPSP,TRANSACTION=*,PROGRAM=* Example 3 Enter the following values in an initial entry and a matching enhanced condition entry to invoke XPED on terminal ID AC12 whenever a transaction abend occurs and the value of the first five bytes of the initial commarea is aBcDe: DBPA 1.6 OWNER=AC12,TERMINAL=*,TYPE=XPED,TRANSACTION=*,PROGRAM=* DBPA 1.6 OWNER=AC12,IF=(ICA(1:5) EQ C'aBcDe') Monitor Exceptions Keywords The keywords for creating entries for the Monitor Exceptions screen (9.4.1) are defined in Table 19. Table 19. Monitor Exceptions Keywords Keyword Abbreviation Default Comments TRAN= TR= **** ID of the transaction to be excluded from monitoring. PROGRAM= PR= or PGM= PG= ******** ID of the program to be excluded from monitoring. CSECT= ******** Mask to define the name of the CSECT(s) to be excluded from monitoring. CS= The following examples show how to use the DBPA 9.4.1 transaction: Example 1 All programs starting with TSTP are excluded from monitoring and are not protected or traced by Xpediter/CICS. DBPA 9.4.1 PROGRAM=TSTP*,CSECT=* Example 2 All programs invoked by the TEST transaction are excluded from monitoring. DBPA 9.4.1 TR=TEST,PROGRAM=*,CSECT=* 148 Xpediter/CICS Advanced Configuration Guide Example 3 All programs with CSECT TESTCST are excluded from monitoring. DBPA 9.4.1 TR=*,PG=*,CS=TESTCST If you want all the CSECTs for a given program, you must use CSECT=*. CSECT Exclusions Keywords The keywords for creating entries for the CSECT Exclusions screen (9.5) are defined in Table 20. Table 20. CSECT Exclusion Keywords Keyword Abbreviation Default PROGRAM= PR= or PGM= PG= Comments REQUIRED Generic ID of the CSECT to be excluded. The following examples show how to use the DBPA 9.5 transaction: Example 1 Enter the following values to disallow selection of subroutine ABCPROGM. DBPA 9.5 PROGRAM=ABCPROGM Example 2 Enter the following values to disallow selection of all subroutines beginning with ABC*. DBPA 9.5 PG=ABC* Storage Protection and System Labels Keywords The keywords for creating entries for the Storage Exceptions (9.7), Storage Protection (9.8), and Define System Labels (9.9) screens are defined in Table 21. Wherever YES/NO is specified in the Comments column, Y/N can also be used. Table 21. Storage Protection and System Labels Keywords Keyword Minimum Abbreviation Default Value (9.7) (9.8) (9.9) Comments TYPE= TY= SYST N/A O N/A SYST or USER TERMINAL= TE= **** O O N/A Used as mask TRANS= TR= **** O O N/A Used as mask PROGRAM= or PGM= PR= PG= ******** O O N/A Used as mask STORE= ST= N O O N/A YES/NO 9.7=Allow Store 9.8=Protect Store FETCH= FE= N O O N/A YES/NO 9.7=Allow Fetch 9.8=Protect Fetch O = Optional, R = Required, N/A = Not Applicable Configuration Parameters 149 Table 21. Storage Protection and System Labels Keywords (Continued) Keyword Minimum Abbreviation Default Value (9.7) (9.8) (9.9) Comments SHRSTRG= (Shared Storage) SH= SS= N N/A O O YES/NO REENT= (Program Storage) RE= PS= N N/A O N/A YES/NO FROM= FR= (Required) R N/A N/A spaces O N/A N/A Required if LENGTH is not specified TO= LENGTH= or LNTH= LE= LN= spaces O N/A O Invalid if TO is specified UNPRO= (Unprotected Instructions) UN= UI= spaces O N/A N/A YES/NO USER= (User Label) (New Label) US= UL= NL= (Required) N/A N/A R Must start with an alpha character EXISTING= (Existing Label) EX= EL= (Required) N/A N/A R ENTRY= EN= spaces N/A N/A O OFFSET= OF= spaces N/A N/A O CONTENT= (Use Content) CO= UC= N N/A N/A O YES/NO CPSTOR= CP= N N/A O N/A Command level storage protection. O = Optional, R = Required, N/A = Not Applicable The following examples show how to use the DBPA 9.7, 9.8, and 9.9 transactions: Example 1 Enter the following values to store protect everything except program TESTPGM1 and test for program reentrancy. DBPA 9.8 PGM=TESTPGM1 DBPA 9.8 ST=Y,RE=Y Example 2 Enter the following values to store protect everything, test only program TESTPGM2 for reentrancy, and allow stores into TESTPGM2 at offset decimal 100 (hex x'64') for length of 8. DBPA DBPA DBPA DBPA 9.9 9.7 9.8 9.8 NL=MYLBL1,EL=PGM,ENTRY=TESTPGM2,OFFSET=64 FROM=MYLBL1,LEN=8,ST=Y PGM=TESTPGM2,ST=Y,REENT=Y ST=Y Example 3 Enter the following values to store and fetch protect all activity at terminal TM01, excluding programs that begin with EMUL, while still allowing transaction TST3 to update the system portion of its task control area (TCA). 150 Xpediter/CICS Advanced Configuration Guide DBPA DBPA DBPA DBPA 9.8 9.9 9.7 9.8 PGM=EMUL**** NL=TCASAA,EL=TCA,UC=Y TRAN=TST3,FROM=TCASAA,TO=TCA,ST=Y TERM=TM01,ST=Y,FE=Y Example 4 Enter the following values to store protect all activity at terminals with IDs starting with T, while allowing any command-level program to update its execute interface block (EIB). DBPA 9.9 NL=EIB,EL=EIS,OFF=8,UC=Y DBPA 9.7 FROM=EIB,LEN=55,ST=Y DBPA 9.8 TE=T***,ST=Y 151 Operational Considerations Xpediter Service Provider Operator Commands This section describes the functions, syntaxes, and parameters of the Xpediter Service Provider administrative commands. These MVS operator commands can be entered at a console, an alternate console, or using the TSO operator command interface. The basic command functions are listed in Table 22. Table 22. Service Provider Commands and Functions Command Function STATUS Displays a list of connected Service Requester address spaces. DUMP Schedules an SVCDUMP of the Xpediter Service Provider address space. SHUTDOWN Schedules termination of the Xpediter Service Provider address space. INITTCP Starts the TCP communications subtask. SHOWTCP Displays a list of Service Providers that this Service Provider is currently connected to. TERMTCP Terminates the TCP communications subtask. These commands all have a similar format: MODIFY xdssname,COMMAND,parameter The letter F is a valid abbreviation for MODIFY. This is followed by a required space and xdssname representing the started task or batch job name of the Xpediter Service Provider address space. This is followed immediately by a comma (,) and the actual command name. STATUS Command Use the STATUS command to display the status of all connected Service Requester address spaces. An example of the STATUS command is: MODIFY XD01SS01,STATUS The following is an example of output produced by using the STATUS command: 22 152 Xpediter/CICS Advanced Configuration Guide XSP2100I XSP2101I XSP2102I XSP2103I XSP2103I XSP2103I XSP2103I XSP2103I XSP2103I XSP2103I XSP2103I XSP2104I Column Service Provider Release 17.02.00 SSID(XPLX) Image(ZOS1) Job Name ASID Status Type Version Ident Connects -------- ---- -------------- -------- -------- -------- -------- ACMEASA2 0095 Initialized CICS 04.01.00 ACMEASA2 1 ACMEASA1 0062 Initialized CICS 04.01.00 ACMEASA1 1 ACMEASA4 0097 Initialized CICS 04.01.00 ACMEASA4 1 ACMEASA3 0096 Initialized CICS 04.01.00 ACMEASA3 1 ACMEASA5 0098 Initialized CICS 04.01.00 ACMEASA5 1 ACMEC168 0050 Initialized CICS 04.01.00 ACMEC168 1 ACMEC106 006C Initialized CICS 05.02.00 ACMEC106 1 ACMEC041 006D Initialized CICS 04.01.00 ACMEC041 1 8 connected Service Requester address spaces Description Job Name Started task or batch job name for connected address space. ASID Address Space Identifier for connected address space. Status Connection status. Possible values are Initializing, Initialized,  Terminating, Terminated, Abterm, and Unknown. Type Connection type. The valid value is CICS. Version Connection type version. Ident Connection type identifier. Possible values are Applid and UserId. Connects Number of concurrent connections. DUMP Command Use the DUMP command to capture an SVCDUMP of the Service Provider address space and, optionally, a list of between 1 and 14 Service Requester address spaces. The DUMP command should only be used under the direction of Xpediter/CICS Customer Support. Examples of the DUMP command are MODIFY XD01SS01,DUMP which will capture an SVCDUMP of the Service Provider address space, and MODIFY XD01SS01,DUMP,ACMEC123 which will capture an SVCDUMP of the Service Provider address space and the Service Requester address space ACMEC123. The following is an example of output produced by using the DUMP command: XSP2201I Service Provider dump has been captured SHUTDOWN Command Use the SHUTDOWN command is used to schedule normal termination of the Xpediter Service Provider address space. Operational Considerations 153 An example of the SHUTDOWN command is: MODIFY XD01SS01,SHUTDOWN The following is an example of output produced by using the SHUTDOWN command: XSP2501I XSP0501I XSP0502I XSP0501I XSP0502I XSP0901I XSP0503I Service Provider shutdown in progress Monitor subtask termination initiated Monitor subtask termination complete Command subtask termination initiated Command subtask termination complete Termination routine entered for Termination processing Service Provider Termination complete The following is an example of the output produced if there are Service Requester address spaces still connected: XSP2502E SHUTDOWN command rejected, 4 connected Service Requester address spaces Use the STATUS command to display the connected address spaces. The XPOF transaction can be used to terminate Xpediter in each connected address space. Xpediter/CICS code relies upon the presence of the Service Provider. If the Service Provider is forcibly removed, results are unpredictable and may include failure of connected CICS regions. There is an alternative to using XPOF in each connected address space. The optional Remote Operations Command Interface (ROCI) allows both startup and shutdown of the product in multiple CICS regions with one command entered on an ISPF panel. Refer to “Installing and Customizing the Remote Operations Command Interface” to implement ROCI. Refer to the chapter entitled “Remote Operations Command Interface” in the Xpediter/CICS Reference Manual for additional information on the use of ROCI. INITTCP Command Use the INITTCP command to start the TCP communications subtask. The INITTCP command can be abbreviated ITCP. Examples of the INITTCP command are: MODIFY XD01SS01,INITTCP MODIFY XD01SS01,INITTCP,PORT=54006 MODIFY XD01SS01,INITTCP,MEMBER=abcdefgh The PORT parameter is optional, allowing the user to override the PORT number originally specified. The PORT parameter can be abbreviated P. The MEMBER parameter is optional, allowing the user to override the MEMBER name originally specified. The MEMBER parameter can be abbreviated M. The following is an example of output produced by using the INITTCP command regardless of whether or not PORT or MEMBER are specified: 154 Xpediter/CICS Advanced Configuration Guide RESPONSE=CW40 XSP0460I TCP subtask initialization started SHOWTCP Command Use the SHOWTCP command to display a list of Service Providers to which this Service Provider is currently connected. The SHOWTCP command can be abbreviated STCP. An example of the SHOWTCP command is: MODIFY XD01SS01,SHOWTCP The output produced from this command provides information about the “modify” Service Provider in the XSP2100 message and about all other connected Service Providers in XSP3103 messages. The following is an example of output produced by using the SHOWTCP command: RESPONSE=CW01 XSP2100I Service Provider Release 08.03.00 SSID(XPM1) Image(CW01) XSP3101I Release SSID Image Port IP Address XSP3102I -------- ---- -------- --------------- XSP3103I 08.03.00 XPM4 CW04 55006 10.10.0.204 XSP3103I 08.03.00 XPM6 CW06 55006 10.10.0.206 TERMTCP Command Use the TERMTCP command to terminate the TCP communications subtask. The TERMTCP command can be abbreviated TTCP. An example of the TERMTCP command is: MODIFY XD01SS01,TERMTCP The following is an example of output produced by using the TERMTCP command: RESPONSE=CW40 XSP0501I TCP subtask termination initiated Canceling AID Blocks You can use CICS commands to cancel Automatic Initiator Descriptor (AID) control blocks. This is done using the SET TERMINAL or SET CONNECTION operands of the CEMT transaction, the CECI transaction, or EXEC CICS system programming commands. This facility must be used with care when Xpediter/CICS is active. Xpediter/CICS uses START requests (creating AIDs) to initiate display tasks (DBXG) for remote debugging sessions. If these tasks are deleted, the remote trap will not be automatically scheduled on the trapping terminal, and the program being debugged will be left in a wait state. These tasks will then have to be manually selected for debugging using the List Abends screen (1.3) or the List All Tasks screen (9.3). For more information on the List Abends (1.3) and List All Tasks (9.3) screens, refer to the Xpediter/CICS Reference Manual. Operational Considerations 155 Suppressing System Dumps Resulting from ASRA and ASRB Abends CICS by default produces MVS system dumps preceding ASRA and ASRB abends. This is controlled by the System Initialization Table (SIT) parameter DUMP and the entries in the CICS System Dump table. To suppress these system dumps, refer to the DUMP parameter and the topic “Suppressing system dumps that precede ASRx abends” in IBM’s CICS System Definition Guide. Product Termination To completely shut off Xpediter/CICS in an entire CICS region, enter the XPOF transaction from any terminal. XPOF is useful when maintenance has been applied to an Xpediter/CICS module and you want it to take effect without cycling your CICS system. Because all active sessions must be terminated before shutting off Xpediter/CICS, this transaction notifies you of any active sessions and tells you which terminals are running them. Once you have terminated active Xpediter/CICS sessions, XPOF removes all Xpediter/CICS product hooks and deletes all Xpediter/CICS programs. To limit who can shut down Xpediter in an entire region, Compuware recommends securing XPOF through CICS to restrict its use. If XPOF is entered and an Xpediter session exists on one or more terminals, messages will be issued as illustrated in Figure 29. Whenever feasible, the Xpediter sessions should be ended prior to continuing with XPOF. If necessary, the existence of Xpediter sessions may be ignored by entering XPOF FORCE. The use of XPOF FORCE can lead to unpredictable results, possibly including the failure of the CICS region. It should only be used in exceptional conditions. See “FORCEOK” for more information on disallowing the use of XPOF FORCE. Compuware recommends that following use of the XPOF FORCE transaction, a CICS cold restart be performed to clean up any residuals from the global/local catalogs. Figure 29. XPOF Messages *---- Xpediter/CICS shutdown proceeding For SYSID=C123 Error-other Xpediter/CICS sessions exist End Xpediter/CICS sessions on terminals: T008 userid:USER001 Single Point Product Startup and Shutdown The optional Remote Operations Command Interface (ROCI) allows both startup and shutdown of the product in multiple CICS regions with one command entered on an ISPF panel. Refer to “Installing and Customizing the Remote Operations Command Interface” to implement ROCI. Refer to the chapter entitled “Remote Operations Command Interface” in the Xpediter/CICS Reference Manual for additional information on the use of ROCI. Using the Batch Interface to Xpediter/CICS NEWCOPY This section describes the Batch Interface to Xpediter/CICS NEWCOPY. 156 Xpediter/CICS Advanced Configuration Guide The Batch Interface to Xpediter/CICS NEWCOPY allows batch compile and link jobs (or standalone linkedit jobs) to communicate with one or more CICS regions and request the NEWCOPY (PHASEIN) of the just-linked load module. Xpediter/CICS does not need to be turned on in a CICS region to use this feature. However, Xpediter/CICS transaction and program definitions must be installed in each CICS region referenced, and the Xpediter/CICS load library must be in the DFHRPL concatenation or in an installed LIBRARY. Sample JCL to merge into your existing compile and link (or standalone linkedit) procedure(s) is in SAMPLIB member JCLNEWC. Customize the dataset name in the TPCONFIG DD statement. This dataset was created in “Task 1.1 Create and Use TPCONFIG”. Then modify the two related parameters LMOD and CFGMBR to fit into your procedure(s). Specify the load module name of the newly-linked program in LMOD. Specify your TPCONFIG member name in CFGMBR. Depending on the requirements of your environment, CFGMBR could be a static value. You may use this jobstep independent of compile and/or linkedit JCL and specify multiple load module names to NEWCOPY. In addition to providing an EXEC parameter, you can supply load module names and/or the MEMBER= parameter via input DDname NEWCINP. You can also provide all data via input DDname NEWCINP and omit the EXEC parameter. Data provided via the EXEC parameter is parsed before any data provided via input DDname NEWCINP. Regardless of input source, only one TP configuration file MEMBER name may be provided. You may submit this jobstep without specifying DDname NEWCINP. All input must then be within the EXEC parameter. Your dataset allocated to NEWCINP may be blocked or unblocked, fixed length or variable. Input statements may contain a single load module name or multiple load module names. Use a comma to separate multiple load module names. The final load module name on each input statement should also be followed by a comma if more input statements follow. Comment statements, identified by an asterisk (*) in position 1, may be included in the NEWCINP input data. Batch Interface to Xpediter/CICS NEWCOPY Usage of the Xpediter TP Configuration File The Xpediter TP configuration file (TPCONFIG) is used for two purposes: • To identify Xpediter Service Providers that are to share CICSPlex information. • To identify all of the CICS regions that should be contacted by the Batch Interface to Xpediter/CICS NEWCOPY. Efficiency Considerations Technically, each member of the TPCONFIG partitioned dataset may contain entries for both possible uses mentioned above. This is because each record within a member starts with a record identifier, and records with an identifier for a different purpose are ignored. However, even though it is technically feasible to have all of the information in one member, doing so would be inefficient. It is possible to lump all Batch NEWCOPY records (NEWC) into one TPCONFIG member, but then each time the Batch Interface to Xpediter/CICS NEWCOPY is used, the program will try to contact all CICS regions. The volume of regions contacted could clutter the report produced and extend the Batch Interface’s runtime. In addition, regions that do not contain the program being newcopied would always report errors, increasing the likelihood of other errors being overlooked. Therefore, Compuware recommends logically grouping your NEWC entries into members that mirror your site’s program (load library) distribution. Operational Considerations 157 Record Identifiers for Batch Interface to Xpediter/CICS NEWCOPY Records Records in a TPCONFIG member with an asterisk in position one are considered comment records and are ignored. Records that have a blank in position one are scanned for a following record identifier. The record identifier for the Batch Interface to Xpediter/CICS NEWCOPY records is NEWC. Each CICS region that you want to be contacted to attempt NEWCOPY should have a record in the member. Following the NEWC record identifier are: • one or more blanks • the transaction ID to be initiated in CICS (XPNC is recommended) • one or more blanks • the IP Port Number for the CICS region (or keyword EXCI if the EXCI communication method is to be used) • one or more blanks • the IP Address for the CICS region (or APPLID of the CICS region if the EXCI communication method is to be used). If a Domain Name Server is available for GETHOSTBYNAME calls, then the Domain Name may be specified instead of the IP Address. Sample TPCONFIG Records for Batch Interface to Xpediter/CICS NEWCOPY To enable the Batch Interface to Xpediter/CICS NEWCOPY, add records similar to those shown in Figure 30 to your TPCONFIG dataset. Figure 30. TPCONFIG Records for Batch Interface to Xpediter/CICS NEWCOPY ************************************************************************ * DEFINE CICS REGIONS TO NEWCOPY IN * ************************************************************************ * Tranid Port Host name or IP address Comments  * ------ ----- ----------------------- -------------------------- NEWC XPNC 54106 CW01.ACME.COM MVS Sockets NEWC CSMI EXCI H01AC087 EXCI (Specific) connection NEWC XPNC 27448 CW01.ACME.COM TCPIPSERVICE (HTTP) Batch Interface to Xpediter/CICS NEWCOPY JCL To utilize the Batch Interface to Xpediter/CICS NEWCOPY, add the JCL provided in SMXDSAMP member JCLNEWC to your existing compile/link JCL procedure. This jobstep communicates to CICS via MVS Sockets, TCPIPSERVICE, or EXCI. This communication is similar to that used for Xpediter’s ROCI capability as described in “Installing and Customizing the Remote Operations Command Interface”. You should choose the communications method you are familiar with and that already exists in your CICS environments. Compuware recommends using the same connection technique and connection name that was used for ROCI. Example Batch SYSPRINT Messages The Batch Interface to Xpediter/CICS NEWCOPY writes a message to the log listing the date, SYSID, and APPLID for the program PHASEIN and indicating whether the action was successful. An example is shown in Figure 31. 158 Xpediter/CICS Advanced Configuration Guide Figure 31. Example of SYSPRINT Messages from Batch Interface to Xpediter/CICS NEWCOPY XPEDITER/CICS RELEASE 08.03.00 - BATCH INTERFACE TO NEWCOPY PAGE 1  XDP0061I EXECUTION PARAMETERS: CWDEMCB2,MEMBER=TSTNEWC ------------------------------------------------------------------------------------ XDP0062I MVS SOCKET CONNECTION WITH TRAN XPNC TO PORT 54106 CW01.ACME.COM XDP0063I MXDNC0001I 04 Mar 2008 15:12:43 - SYSID=C106 - APPLID=H01AC106 XDP0063I Program 'CBUMOVE4' phasein successful Len(00047D8) XDP0063I From(XD.TEST.BENCH.LOADLIB) ------------------------------------------------------------------------------------ XDP0062I SPECIFIC EXCI CONNECTION WITH TRAN CSMI TO APPLID H01AC087 XDP0063I MXDNC0001I 04 Mar 2008 15:12:44 - SYSID=C087 - APPLID=H01AC087 XDP0063I Program 'CBUMOVE4' phasein successful Len(00047D8) XDP0063I From(XD.TEST.BENCH.LOADLIB) ------------------------------------------------------------------------------------ XDP0062I HTTP TCPIPS CONNECTION WITH TRAN XPNC TO PORT 52054 CW01.ACME.COM XDP0063I MXDNC0001I 04 Mar 2008 15:12:45 - SYSID=C054 - APPLID=H01AC054 XDP0063I Program 'CBUMOVE4' phasein successful Len(00047D8) XDP0063I From(XD.TEST.BENCH.LOADLIB) ------------------------------------------------------------------------------------ XDP0062I HTTP TCPIPS CONNECTION WITH TRAN XPNC TO PORT 27448 CW01.ACME.COM XDP0063I MXDNC0001I 04 Mar 2008 15:12:46 - SYSID=C006 - APPLID=H01AC006 XDP0063I Program 'CBUMOVE4' phasein successful Len(00046E0) XDP0063I From(ACMJET0.XD.LOAD) 159 Miscellaneous Considerations 23 Support for CICS Dynamic LIBRARY Capability Xpediter/CICS supports RDO-installed dynamic LIBRARY resources: • Application program and Xpediter/CICS demo program load libraries may be defined in any number of LIBRARY resources, in any sequence, or may be concatenated into DFHRPL. • The Compuware Shared Services (CSS) load library may be defined in any LIBRARY resource, in any sequence, or may be concatenated into DFHRPL. Compuware recommends that the CSS load library be defined in the same place (either LIBRARY resource or DFHRPL) as the Xpediter/CICS product load library. The CSS load library may be positioned either before or after the Xpediter/CICS product load library. • The Xpediter/CICS product load library may be defined in any LIBRARY resource, or may be concatenated into DFHRPL. If it is defined in a LIBRARY resource, that LIBRARY resource may be sequenced wherever the installer decides. • Load libraries containing Xpediter/CICS product user-replaceable modules (URMs) or usercustomized exits must be defined in the same place (either LIBRARY resource or DFHRPL) as the Xpediter/CICS product load library, and should be positioned before the Xpediter/CICS product load library. • Xpediter/Code Coverage (if licensed) and Xpediter/Xchange (if licensed) load libraries must be defined in the same place (either LIBRARY resource or DFHRPL) as the Xpediter/CICS product load library. If either of those product load libraries are not defined in the same place as the Xpediter/CICS product load library, the related product will not initialize properly. The CEMT DISCARD LIBRARY command requires that the LIBRARY resource be disabled. In addition, Xpediter/CICS must be shut down with the XPOF transaction before using DISABLE or DISCARD for a LIBRARY resource. DASD Space Requirements Table 23 lists the estimated DASD space needed for Xpediter/CICS target libraries. Table 23. DASD Space Requirements Component Each CICS dependent FMID Dataset Name 3390 DASD Cylinders CPWR.cMXD170.SMXDAAFX 5 CPWR.cMXD170.SMXDAUTH 5 CPWR.cMXD170.SMXDOxxL 75 CPWR.cMXD170.SMXDPDSE 5 CPWR.cMXD170.SMXDSAMP 10 160 Xpediter/CICS Advanced Configuration Guide c designates the Xpediter code for the CICS release and xx designates the CICS release. Compuware recommends that space allocations for Xpediter’s SMP/E datasets not be reduced. The supplied allocations provide enough space to receive and apply the FMIDs without forcing SMP/E to perform numerous in-flight compresses. If too many compresses are attempted, SMP/E may abort the current operation. This could leave the installation environment in an unknown, and possibly undesirable, state. Minimizing CPU Consumption When Using Xpediter/Code Coverage There are certain CICS, Xpediter/CICS, and Xpediter/Code Coverage options you can set that may reduce CPU consumption when testing with Xpediter/Code Coverage. CICS SIT Parameters Affecting CPU Consumption You can alter the system initialization table (SIT) parameters STGPROT and SYSTR as follows either by modifying the SIT or by using SIT overrides. STGPROT When this option is set to YES and your application programs are defined as EXECKEY(USER), substantial CPU time will be spent changing execution key. Setting STGPROT to NO will save CPU. SYSTR When this option is set to ON, CICS will trace CICS API calls and internal CICS functions. Setting SYSTR to OFF will save CPU. Xpediter/CICS Global Table Parameter Affecting CPU Consumption The BTRCFLG global parameter can be set as described in “Methods of Specifying and Updating Parameters”. This region-wide option can also be changed from any Xpediter/CICS debugging session with the SET BTRACE primary command. BTRCFLG When this option is set to YES or FULL, Xpediter/CICS updates an internal branch trace table to help diagnose any Xpediter/CICS issues. Unless Xpediter/CICS customer support has requested that you run with this option set to YES or FULL, it should be set to NO to save CPU. If BTRCFLG is set to NO and an Xpediter/CICS problem occurs, recreate the problem with BTRCFLG set to YES before gathering documentation for Xpediter/CICS Customer Support. Xpediter/Code Coverage Global Table Parameter Affecting CPU Consumption The setting of the COUNT parameter in the Xpediter/Code Coverage global table (XVTCGBL) can also affect CPU consumption while testing with Xpediter/CICS. For more information on setting this option, see the Xpediter/Code Coverage Mainframe Installation Guide. COUNT When this option is set to YES, Xpediter/CICS will monitor application programs and increment verb counts as each instruction is executed. This is a very CPU-intensive process. The default is YES. Miscellaneous Considerations 161 Set this option to NO when it is not necessary to count each time a verb is executed. When COUNT=NO, Xpediter/CICS will count each verb only the first time it is executed. To maximize the potential performance benefit of COUNT=NO, rules for Storage Protection and Program Trace are ignored when COUNT=NO and a Code Coverage test is active. When Xpediter/Code Coverage global table parameter COUNT=NO, the System Flow feature of Xpediter/Code Coverage cannot be used. An error message is displayed if you attempt to activate either System Flow or Both (Code Coverage plus System Flow). When COUNT is set to NO: • Only one Xpediter/Code Coverage test at a time may be active in the CICS region. • Each application program you execute is marked as RESIDENT until every verb within it has been executed or the Xpediter/Code Coverage test has been halted. If you encounter a Short on Storage (SOS) situation using COUNT=NO, reduce the number of programs referenced by your Xpediter/Code Coverage test. • CPU consumption may actually increase, depending on the structure of your Xpediter/Code Coverage test. When the same code is executed multiple times, COUNT=NO will reduce CPU consumption by a factor related to how many times the code is executed. However, when different code is executed by each transaction and there is very little reuse of the same code, COUNT=NO can cause a noticeable increase in CPU consumption. Topaz Workbench in a CPSM CICSPlex Environment The following capabilities of Compuware’s Topaz Workbench, when used with a CPSM CICSPlex environment, effectively support Dynamic Transaction Routing across LPARs: • DBUGSOCK and XDPIMIRS use Channel/Containers to communicate. This modernizes the communication and allows cross-LPAR debugging sessions to be established. DBUGSOCK is the Xpediter/CICS Socket Handler for the Topaz Workbench debugger, and XDPIMIRS is the Xpediter/CICS Debugging Interface for the Topaz Workbench debugger. • The CPSM Dynamic Transaction Routing exit DBUGWRAM supports cross-LPAR debugging sessions. If a workstation starts a Topaz Workbench debugging session by connecting to a TOR— and transaction XSOC is defined as dynamically routed—the debugging session (XDPIMIRS) will be started in the LPAR to which XSOC is to be routed. The XSOC transaction, however, will be routed to an existing Xpediter/CICS-enabled region within the same LPAR as the TOR. This is due to a restriction of CICS Sockets for MVS that requires the socket to run in the same LPAR as the listener. This also means that for each TOR region, at least one Xpediter/CICS AOR region must be defined in the same LPAR as the TOR. • The trap routing logic within DBUGWRAM will route the application logic to the correct region where the Xpediter/CICS trap is set when is specified in the terminal field of the trap. • The Xpediter/CICS start-of-task exit uses the EXEC CICS INQUIRE ASSOCIATION call to obtain the client IP address associated with the task. This allows the terminal emulator IP address to be identified when a trap/breakpoint is taken. This most commonly occurs in cross-LPAR environments. However, the client IP address will only be filled in if the CICSPlex regions’ crossLPAR connections utilize IPIC connections. If you use SESSION/CONNECTION definitions for cross-LPAR connections, the client IP address will not be available. Compuware suggests you upgrade any cross-LPAR connections to use IPIC connections. Restrictions The following restrictions apply when using Topaz Workbench in a CPSM CICSPlex Environment: 162 Xpediter/CICS Advanced Configuration Guide • If the affinity of the transaction being routed prevents that transaction from running in the region where DBUGWRAM has determined it should be routed, that transaction will not be eligible for debugging. If you encounter this situation, you may need to end your Topaz Workbench debugging session and directly connect to an AOR where the transaction can be executed. • If you have cross-LPAR regions that communicate using non-IPIC connections, consider upgrading your connections. Being able to correctly identify the IP Address of the transaction being executed is a key factor in determining when a transaction has been initiated by a terminal emulator running on the same workstation as your debugging session. Examples of CPSM CICSPLEX Configurations Now Supported The following examples utilize the simple CICSPlex configuration shown in Figure 32. In this configuration, the Service Providers XP40, XP01, and XP06 are all TCP/IP connected utilizing Xpediter/CICS release 17.02.03 Service Providers. The AOR regions H40AC123, H40AC246, H01AC066, H01AC132, H06AC024, and H06AC093 all have Xpediter/CICS release 17.02.03 installed and active. The TOR regions H40AC063, H01AC073, and H06AC053 all have Xpediter/CICS release 17.02.03 exit DBUGWRAM installed and active. All regions, both TOR and AOR, are connected to their assigned Service Providers. It is assumed that the user has set a trap in their debug launch configuration that has in the Terminal field and all other fields set to asterisks. When the trap is set, the IP address of the workstation is used for the terminal field in the trap. This means that when the routing exit DBUGWRAM is performing a trap search to determine where to route a transaction, it will compare the IP address of the terminal entering the transaction against the IP address in the trap. Since the terminal emulator IP address matches that of the workstation, DBUGWRAM will route the transaction to the region where the trap was set. Figure 32. Simple CICSPlex Configuration LPAR CW01 LPAR CW40 TOR H40AC063 H40AC123 TOR H01AC073 H01AC066 DBUGWRAM H40AC246 DBUGWRAM H01AC132 Service Provider XP40 Service Prvider XP01 LPAR CW06 TOR H06AC053 H06AC024 DBUGWRAM H06AC093 Service Provider XP06 Example 1. Topaz Workbench Connecting Directly to an AOR In this example (Figure 33), a Topaz Workbench user connects directly to AOR H06AC024. Because the connection is to an AOR, the routing exit DBUGWRAM is not involved. This means that XSOC (DBUGSOCK) will run in the AOR and do a local LINK to the Debugging Interface XDPIMIRS. Any breakpoints the user has requested will be set in H06AC024. Miscellaneous Considerations 163 Figure 33. Topaz Workbench Connecting Directly to an AOR LPAR CW01 LPAR CW40 TOR H40AC063 H40AC123 TOR H01AC073 H01AC066 DBUGWRAM H40AC246 DBUGWRAM H01AC132 LPAR CW06 Topaz User logs into H40AC063 and types in TOR H06AC053 H06AC024 DBUGWRAM H06AC093 Connects to CW06, region H06AC024 directly. XCB2 If the user then logs into any TOR in the CICSPlex from their terminal emulator, the enhanced trap logic in routing exit DBUGWRAM will now route any transactions from that terminal emulator to AOR H06AC024 for execution. The user can now debug the programs in which they have set breakpoints using Topaz Workbench at their workstation. Example 2. Topaz Workbench Connecting to a TOR In this example, a Topaz Workbench user connects to TOR H01AC073. Because the connection is to a TOR, the routing exit DBUGWRAM is involved. When DBUGWRAM is invoked, transaction XSOC (used to initiate the debugging session) has already been slated for routing to H40AC246 on LPAR CW40 by the Work Load Manager. DBUGWRAM writes an entry to an internal table indicating that the Debugging Interface XDPIMIRS should run in region H40AC246 and then looks for a region with Xpediter/CICS active on the same LPAR (CW01) on which the TOR runs. DBUGWRAM finds that region H01AC132 is available and changes the routing of the XSOC transaction to run in H01AC132 instead of H40AC246. This is necessary since XSOC invokes DBUGSOCK, the Sockets Listener Interface, which must run on the LPAR on which it was invoked. XSOC then starts on H01AC132 and links to XDPIMIRS on H40AC246 to start the debugging session. XDPIMIRS and DBUGSOCK communicate via Channel/Containers, and the actual socket connection is made between the workstation running Topaz Workbench and DBUGSOCK on H01AC132. Any breakpoints the user has requested will be set in H40AC246. 164 Xpediter/CICS Advanced Configuration Guide Figure 34. Topaz Workbench Connecting to a TOR LPAR CW01 LPAR CW40 TOR H40AC063 H40AC123 DBUGWRAM H40AC246 H01AC066 TOR H01AC073 X M D I P R I S DBUGWRAM D S B O U C G K H01AC132 LPAR CW06 User logs into H06AC053 and types in TOR H06AC053 H06AC024 DBUGWRAM H06AC093 Topaz Connects to TOR H01AC073 on CW01. XCB2 When the user logs on to any TOR in the CICSPlex from their terminal emulator, the enhanced trap logic in routing exit DBUGWRAM will now route any transactions from that terminal emulator to AOR H40AC246 to execute. The user can now debug the programs in which they have set breakpoints using Topaz Workbench at their workstation.