Xpediter/CICS Installation Guide

Transcription

Xpediter/CICS
Installation Guide
Release 9.3
ii
Please direct questions about Xpediter/CICS
or comments on this document to:
Xpediter/CICS Customer Support
http://go.compuware.com
This document and the product referenced in it are subject to the following legends:
Copyright 1984 - 2014 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.7202-3(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, Xpediter/CICS, Xpediter/Xchange, Xpediter/Code Coverage, Abend-AID for CICS, FrontLine, and
Compuware are trademarks or registered trademarks of Compuware Corporation.
CICSPlex, CICS Transaction Server, DB2, DFSMS, IBM, MQ Series, MVS, MVS/ESA, OS/390, VTAM,
WebSphere MQ, and z/OS are trademarks or registered 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. CWXCIX9G
June 10, 2014
iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
System Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Compuware Go Customer Support Website . . . . . . . . . . . . . . . . . . . . . . . xxiv
Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
PDF and PDX Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
World Wide Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Accessibility Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Selecting Font and Font Size in the Emulator. . . . . . . . . . . . . . . . . . . . . . xxv
Changing Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Special Considerations When Using a Screen Reader. . . . . . . . . . . . . . . . xxvi
Exceptions and Work-Arounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Known Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Work-Arounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Notation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Customer Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Compuware Go Customer Support Website . . . . . . . . . . . . . . . . . . . . . . xxviii
Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Phone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxviii
Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxviii
Corporate Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Information for Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Chapter 1. Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Preinstallation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Enterprise Common Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Support for CICS Dynamic LIBRARY Capability. . . . . . . . . . . . . . . . . . . . . 1-2
Miscellaneous Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Specifying SLS Dataset(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
DASD Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Xpediter/Code Coverage Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Current Xpediter/CICS Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Installing Xpediter FMIDs for Multiple CICS Releases . . . . . . . . . . . . . . . . 1-7
Reinstallation After CICS Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Cancelling AID Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Current Abend-AID for CICS Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Current CA SYSVIEW® Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Minimizing CPU Consumption When Using Xpediter/Code Coverage . . 1-8
Performance Monitors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
Establishing PLT Startup Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Suppressing System Dumps Resulting from ASRA and ASRB Abends . . . .1-9
APF Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
SMP/E Installation and Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Allocating SMP/E Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Installing with SMP/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
iv
Installing Xpediter/CICS Using JCL Customization Facility (Optional).
Xpediter/CICS Packaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SMP/E Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Libraries Created During SMP/E Installation. . . . . . . . . . . . . . . . . . . . . .
1-11
1-12
1-12
1-13
Chapter 2. RFN Installation Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Install Enterprise Common Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
License Management System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Part 1: Initialize Installation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Step 1. Create Global Zone CSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Step 2. Receive From Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Step 3. Copy Installation Dialog File from USS to z/OS . . . . . . . . . . . . . . 2-3
Part 2: Customize Installation JCL with ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Step 1. Make Note of HLQ, Global Zone CSI, and Installation File
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Step 2. Select Installation Components. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Step 3. Specify Installation Environment Information . . . . . . . . . . . . . . . 2-5
Step 4. Specify SMS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Step 5. Specify Global CSI Dataset Name . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Step 6. Specify Jobcard Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Step 7. Specify SMP/E High-Level Qualifiers . . . . . . . . . . . . . . . . . . . . . . . 2-9
Step 8. Specify Target and Distribution Zones. . . . . . . . . . . . . . . . . . . . . 2-10
Step 9. Specify Installation-Dependent Libraries. . . . . . . . . . . . . . . . . . . 2-11
Step 10. Verify Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Step 11. Process the JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Part 3: Install Xpediter/CICS with SMP/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Step 1. Allocate Libraries and SMP/E Datasets. . . . . . . . . . . . . . . . . . . . . 2-15
Step 2. Initialize the Target and Distribution Zone CSIs . . . . . . . . . . . . . 2-15
Step 3. Review HOLDDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Step 4. Apply the Base Code and Cumulative Maintenance to the
Target Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Step 5. Accept the Base Code to the Distribution Libraries. . . . . . . . . . . 2-16
Part 4: Configure Xpediter/CICS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Step 1. Prepare the ISPF Edit Macro (Optional) . . . . . . . . . . . . . . . . . . . . 2-17
Step 2. Integrate Xpediter/CICS with MVS . . . . . . . . . . . . . . . . . . . . . . . 2-17
Update the MVS APF Authorized Library List . . . . . . . . . . . . . . . . . 2-17
Define the Xpediter Service Provider Program Properties to
MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Define the Xpediter Service Provider as an MVS Subsystem . . . . . . 2-18
Step 3. Update the CICS Resource Definitions . . . . . . . . . . . . . . . . . . . . 2-18
Using RDO to Update Resource Definitions . . . . . . . . . . . . . . . . . . 2-19
Setting Exit Program Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Step 4. External Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Xpediter Service Provider Security . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
Step 5. Creating and Managing the Xpediter TP Configuration File
(TPCONFIG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
Step 6. Initialize the Xpediter Service Provider . . . . . . . . . . . . . . . . . . . . 2-26
Step 7. Update the CICS Startup JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Step 8. Verify the Xpediter/CICS Installation . . . . . . . . . . . . . . . . . . . . . 2-29
Step 9. Review Automatic Session Termination . . . . . . . . . . . . . . . . . . . 2-30
Step 10. Review Global Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
Step 11. Create the Global Table Parameters Override Dataset
(Optional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31
Step 12. Create DBPA Transaction Input Dataset (Optional) . . . . . . . . . 2-31
Step 13. Allocate the New Profile File (DBCDEFPF). . . . . . . . . . . . . . . . . 2-31
Step 14. Allocate and Initialize the Employee File (DBCDEFEM)
(Optional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33
v
Step 15. Allocate and Initialize the Recreate Dataset (DBUGUD)
(Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34
Step 16. Implement Support for the DB2 File Utility (Optional) . . . . . . . 2-35
Bind the Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35
Establish DB2 Authorization for XPED, XPRT, and XPSP
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36
Determine Setting for DB2AUTH Global Parameter . . . . . . . . . . . . . 2-36
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37
Step 17. Allocate, Format, and Initialize the SQL Transfer File
(DBCDEFSQ) (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37
Step 18. Install the Xpediter/CICS Diagnostic Modules (Optional) . . . . . 2-39
Step 19. Implement the File Utility Security Exit (Optional) . . . . . . . . . . 2-39
Step 20. Implement Xpediter/CICS DBCTL Support (Optional) . . . . . . . 2-39
Step 21. Configure the Script Facility (Optional) . . . . . . . . . . . . . . . . . . . 2-42
Step 22. Configure the File Utility Audit Trail (Optional) . . . . . . . . . . . . 2-42
Step 23. Review the Language Environment Run-Time Options . . . . . . . 2-42
Step 24. Assemble/Compile and Link-Edit the Test Programs
(Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43
Compile and Bind C Test Programs. . . . . . . . . . . . . . . . . . . . . . . . . . 2-44
Setting Up CSS Language Processor JCL . . . . . . . . . . . . . . . . . . . . . . 2-45
Step 25. Verify Xpediter/CICS Execution . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
Step 26. Install and Customize the Remote Operations Command
Interface (Optional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-46
Step 27. Install and Customize the Batch Interface to
Xpediter/CICS NEWCOPY (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
Add Necessary Definitions to CICS Regions . . . . . . . . . . . . . . . . . . . 2-49
Additional Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
Step 28. Install and Customize for Xpediter/Eclipse (Optional). . . . . . . . 2-50
Installation of Additional Components . . . . . . . . . . . . . . . . . . . . . . 2-51
Verify IBM z/OS Communications Server Installation . . . . . . . . . . . 2-51
Define Transaction Code for Default IP CICS Sockets Listener. . . . . 2-51
Define Transaction Code for Limiting Access to Xpediter/CICS
Using Xpediter/Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-52
Define Xpediter/CICS Sockets Child Listener/Interface . . . . . . . . . . 2-52
Define Transaction Code for Xpediter/CICS Sockets Child
Listener/Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53
Define Xpediter/CICS Sockets Security Exit . . . . . . . . . . . . . . . . . . . 2-53
Define Listener to IP CICS Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54
Enable Xpediter/CICS Sockets-Based Debugging API . . . . . . . . . . . . 2-55
Test Xpediter/Eclipse Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-55
Tar File SMP/E Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56
Step 1. Download the Tar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56
Step 2. Create USS Directory and File Structure . . . . . . . . . . . . . . . . . . . . 2-56
Step 3. Copy the Tar File to USS Tarball Directory . . . . . . . . . . . . . . . . . . 2-56
Step 4. Extract Tar File Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-57
Step 5. Perform SMP/E Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58
Chapter 3. Installation Verification Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Testing your COBOL Compile Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Abend Trapping and Stepping Without Breakpoints . . . . . . . . . . . . . . . . . 3-1
Setting Keeps and Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Executing Your COBOL Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Stepping Through Your COBOL Program . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Testing your Assembler Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Abend Trapping and Stepping Without Breakpoints . . . . . . . . . . . . . . . . 3-11
vi
Setting Keeps and Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Executing Your Assembler Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stepping Through Your Assembler Program . . . . . . . . . . . . . . . . . . . . . .
Testing Your PL/I Compile Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abend Trapping and Stepping Without Breakpoints . . . . . . . . . . . . . . .
Executing Your PL/I Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stepping Through Your PL/I Program . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Your C Compile Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abend Trapping and Stepping Without Breakpoints . . . . . . . . . . . . . . .
Executing Your C Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stepping Through Your C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-14
3-16
3-19
3-21
3-21
3-24
3-26
3-29
3-31
3-31
3-34
3-38
3-39
Chapter 4. Global Parameters Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Specifying Global Parameters at Product Initialization . . . . . . . . . . . . . . . . . . 4-1
Parameters Ineligible for Global Override Facility . . . . . . . . . . . . . . . . . . 4-1
Parameters Ineligible for XSIT Transaction . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Script Facility and File Utility Audit Trail Parameters . . . . . . . . . . . . 4-2
Specifying Global Parameters with INITPARM . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Specifying Global Parameters by Assembling DBUGGBL. . . . . . . . . . . . . . . . . 4-3
Parameter Transaction Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Automatic Trap Activation Exclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Setting Values by Assembling the Global Table. . . . . . . . . . . . . . . . . . . . . 4-4
Setting Values with the Override Facility and XSIT Transaction . . . . . . . 4-4
Enabling Restricted Operating Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Global Parameter Values and Change Methods . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Standard Global Table DBUGGBL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Production Global Table DBUGGBLP . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
ACCESSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
ACCQTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
ACCTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
ALLOWCM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ALLOWMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ASMSTMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ATASCRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ATASEC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ATAUSR1, ATAUSR2, and ATAUSR3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
ATAXPRG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
ATAXTRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
AUTOSEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
AUTOXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
BRGWP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
BRWCNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
BTRCFLG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
CCUPDT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
CELLSIZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
CICSOTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
CICSPLX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
CMDDLM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
COBENTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
CRTEOK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
CSSPPRC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DBAUDDST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DBAUDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
vii
DBCTPSB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
DBFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DBNC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DBPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DBXG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
DB2AUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
DB2DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
DB2LOKA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
DB2LOKD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
DB2MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17
DB2NULD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
DB2SQLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DB2SQLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
DB2STR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DB2VARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DB2VART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DEFALM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DEFALT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DEFCSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
DEFFOOT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFJUST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFKEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
DEFMAXS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFPROT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFSRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
DEFSTPD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
DEFTRAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
DEFTRAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
DISCONN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
DMAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
ENDSESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
ESDBUFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
FLWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
FOLDLC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
GBLTRPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21
GOTVP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
IKEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
IVPMSGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21
LIMCREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
LIMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
LIMTABL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22
LIMTS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
LIMTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22
MAXWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
MENUMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
MONSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
MQDYNQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
MQLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
MQREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-23
MQUPDT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
MSGPFX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
NBRSLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
NEWC1N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
NLS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
viii
OKUPDT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OPENDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PF 1-24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PL1STMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
POPTOVR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROFDDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROFUSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROTCWA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROTMAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROTMSG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROTTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PSBWAIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RDSABP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
READB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
READDL1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
READDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RECREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RESUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RMTWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RQCHSIZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RTIMOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RUWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCHEDL1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCROLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SERVRQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETRPLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SLSDDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SLSSDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STEPWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STEPWT0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SUBSYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SUBUBCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SUPSESM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCBNR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRANSUC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRAPIPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRAPNET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRAPTRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRAPUSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRPLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRPSAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRPXABD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSQID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UNIQUEIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UPDTDL1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UPDTDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UPDTSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UTILMOD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UXSNOFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VERFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDBP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDDBPCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDDBPIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDDBPRP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-24
4-24
4-24
4-24
4-24
4-25
4-25
4-25
4-25
4-25
4-25
4-25
4-25
4-26
4-26
4-26
4-26
4-26
4-26
4-26
4-26
4-27
4-27
4-27
4-27
4-27
4-27
4-28
4-28
4-28
4-28
4-28
4-28
4-28
4-28
4-29
4-29
4-29
4-29
4-29
4-29
4-29
4-30
4-30
4-30
4-30
4-30
4-30
4-31
4-31
4-31
4-31
4-31
4-31
4-32
4-32
ix
XDDBPTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
XDGBLCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
XDGBLIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
XDGBLRP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
XDGBLTY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOGAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOGBK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOGDD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOGDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
XDLOGMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGNM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGUN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDLOGVO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34
XDSCRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
XDSCRXN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
XDSCRXO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
XDSSACC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
XDSSAPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
XDSSDD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
XDSSDSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
XDTRCRP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
XDUSBLK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
XDUSCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36
XDUSDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
XDUSDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
XDUSDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
XDUSDSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37
XDUSLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
XDUSMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
XDUSPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
XDUSPFX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
XDUSSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
XDUSSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
XDUSSMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
XDUSTYP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
XDUSUNI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
XDUSVOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
XFERDDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
XIVP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XLGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XLOG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPGD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPN0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPOFTCWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
XPON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
XPRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
XPSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
x
XREL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
XSIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
Chapter 5. Overriding Global Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDname Override Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDGBLINP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDGBLRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Table Override Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Table Override Console Log Output . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Parameter Overrides Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up the Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Parameter Overrides to the Dataset . . . . . . . . . . . . . . . . . . . . . . .
5-1
5-1
5-2
5-2
5-2
5-2
5-3
5-4
5-4
5-8
Chapter 6. Restricted Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Diagnosis Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Utilities Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Diagnosis/Utilities Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-1
6-1
6-2
6-2
6-3
Chapter 7. Xpediter Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Release Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Xpediter Service Provider Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Service Provider Usage of the Xpediter TP Configuration File . . . . . . . . . 7-2
Efficiency Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Service Provider Record Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Implementing Automatic Restart Management (ARM) Support. . . . . . . . 7-3
Xpediter Service Provider PROC and JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Executing as a Started Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Executing as a Batch Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Xpediter Service Provider Operator Commands. . . . . . . . . . . . . . . . . . . . . . . . 7-8
STATUS Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
DUMP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
SHUTDOWN Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
INITTCP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
SHOWTCP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
TERMTCP Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Chapter 8. Session and Product Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automatic Session Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Automatic Session Termination . . . . . . . . . . . . . . . . . . . . . . . . .
For Transaction Routing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quick Session Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Single Point Product Startup and Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . .
8-1
8-1
8-1
8-3
8-4
8-4
8-4
Chapter 9. DB2 Format Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the DBSQLUTL Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBSQLUTL Utility Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FROMDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TODD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MEMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPLACE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DSORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (DEL). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TODD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MEMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-1
9-1
9-2
9-2
9-2
9-2
9-2
9-2
9-3
9-3
9-3
9-3
xi
DSORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
DIRECTORY (DIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
FROMDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
FORMAT (FOR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3
FROMDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
TODD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
MEMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
REPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
DSORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
FORMATP Sample Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
INITIALIZE (INIT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
TODD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
PRINT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
FROMDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
MEMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
REORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
TODD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
DBSQLUTL Format Utility Dataset Requirements . . . . . . . . . . . . . . . . . . . . . . . 9-7
Chapter 10. Intercommunication Considerations . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Installation in a Static Routing Environment . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Step 1. Install Xpediter/CICS in Each Region . . . . . . . . . . . . . . . . . . . . . . 10-1
Step 2. Add Transaction Definition Entries in the TOR . . . . . . . . . . . . . . 10-1
Installation in a CPSM Dynamic Routing Environment . . . . . . . . . . . . . . . . . 10-2
Installing Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Step 1. Install Xpediter/CICS in TORs and AORs . . . . . . . . . . . . . . . . . . . 10-3
Step 2. Replace the Default EYU9WRAM . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Step 3. Establish TOR Dynamic Transaction Routing Support . . . . . . . . . 10-4
Step 4. Add Resource Definitions to the TOR for Dynamic
Transaction Routing Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Installation in a Non-CPSM Dynamic Routing Environment . . . . . . . . . . . . . 10-4
Step 1. Prepare for Static Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Step 2. Implement Automatic Session Termination . . . . . . . . . . . . . . . . . 10-5
Step 3. Implement the Script Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
Step 4. Create Table of Remote Xpediter Transactions . . . . . . . . . . . . . . . 10-5
Chapter 11. File Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Implementing A File Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1
Step 1. Choose Sample Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1
Step 2. Assemble the Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Step 3. Tailor the Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Exit Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2
Entry/Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Register Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Step 4. Run Security Exit Through IBM Command-Level Translator . . . . 11-3
Step 5. Assemble RACFEXIT or DBUGUSEC . . . . . . . . . . . . . . . . . . . . . . . 11-3
Step 6. Link the Sample Program to Program DBUGFILE. . . . . . . . . . . . . 11-3
Error Handling and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Abends (Program Check/Abnormal Termination) . . . . . . . . . . . . . . . . . . 11-4
Handle Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
DBUGFILE Link-Edit Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
User Authorization Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
User Authorization Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-5
Debugging the File Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-5
Step 1. Assemble DBUGUSEC and Link-Edit DBUGFILE for Testing . . . . 11-5
xii
Step 2. Establish a High Time-Out Factor for DBUGFILE (TERMA) . . . .
Step 3. Select DBUGUSEC for Debugging (TERMA) . . . . . . . . . . . . . . . .
Step 4. Set a Breakpoint in DBUGUSEC (TERMA) . . . . . . . . . . . . . . . . . .
Step 5. Establish a Trap for DBUGFILE (TERMA) . . . . . . . . . . . . . . . . . . .
Step 6. Invoke DBUGFILE (TERMB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 7. Trap the Breakpoint (TERMA) . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 8. Reset Time-Out Factor for DBUGFILE (TERMA) . . . . . . . . . . . . .
Step 9. Remove Test Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 10. Move Exit to Production (SMP/E USERMOD) . . . . . . . . . . . . . .
Step 11. Implement Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11-5
11-6
11-6
11-6
11-6
11-6
11-6
11-7
11-7
11-7
Chapter 12. Memory Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implementing the Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1. Create Global Table Override . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 2. Review Sample Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 3. Assemble the Exit Module DBUGPASS . . . . . . . . . . . . . . . . . . . .
Step 4. Determine Security Protocol at Your Site. . . . . . . . . . . . . . . . . . .
Step 5. Relink DBUGPASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 6. Shut Off Xpediter/CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 7. Test Your Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 8. Move Exit to Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 9. Provide Passwords to Secured Users. . . . . . . . . . . . . . . . . . . . . . .
Testing the Memory Update Security Exit . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Data on Password-Protected Screens . . . . . . . . . . . . . . . . . . . . . . .
12-1
12-1
12-2
12-2
12-2
12-2
12-2
12-2
12-3
12-3
12-3
12-3
12-3
Chapter 13. Storage Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Storage Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protecting Against Storage Violations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disabling Storage Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protecting Language Environment User Condition Handlers . . . . . . . . . . . .
System Labels for Creating Storage Protection Exceptions. . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Storage Protection Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Dump Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CSMT Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Dump Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Address Validation Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Detailed Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13-1
13-1
13-2
13-2
13-3
13-4
13-4
13-5
13-6
13-6
13-7
13-9
13-9
Chapter 14. Specifying DBPA Transaction Input . . . . . . . . . . . . . . . . . . . . . . . . .
Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Override Processing of ddnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDDBPINP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDDBPRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBPA Transaction Processing Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBPA Transaction Processing Console Log Output . . . . . . . . . . . . . . . . . . . .
DBPA Transaction Input Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up the Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBPA Transaction Image Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14-1
14-1
14-2
14-2
14-2
14-2
14-3
14-4
14-4
14-7
Chapter 15. Xpediter/CICS Startup During CICS Initialization . . . . . . . . . . . . . .
Specifying DBPA Entries via Input Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing Xpediter via PLT Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing Xpediter with Sequential Terminal Input . . . . . . . . . . . . . . .
DBPA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trap Summary Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15-1
15-1
15-1
15-1
15-2
15-2
15-2
xiii
Enhanced Trap Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Monitor Exceptions Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Example 1: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Example 2: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Example 3: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
CSECT Exclusions Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Example 1: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Example 2: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Storage Protection and System Labels Keywords . . . . . . . . . . . . . . . . . . . 15-5
Example 1: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
Example 2: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
Example 3: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
Example 4: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
Chapter 16. Language Environment Operation . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Setting Run-Time Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Software-Raised Error Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-1
Amode Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Chapter 17. Configuring the Script Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Setting Up the Script Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Disabling the Script Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7
Chapter 18. File Utility Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Setting Up the File Utility Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Disabling the File Utility Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
XLOG Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Xpediter/CICS Not Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Xpediter/CICS Active, File Utility Audit Trail Not Active. . . . . . . . . . . . . 18-6
Xpediter/CICS Active, File Utility Audit Trail Active . . . . . . . . . . . . . . . . 18-6
Entry Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-8
Dataset Heading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-8
Entry Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Closing the dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9
Dataset Service Request Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9
Dataset Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-9
Add. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10
Update — Full . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10
Update — Short . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11
DL/I Segment Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-11
DB2 Row Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12
Chapter 19. Batch Interface to Xpediter/CICS NEWCOPY . . . . . . . . . . . . . . . . . 19-1
Batch Interface to Xpediter/CICS NEWCOPY Usage of the Xpediter TP
Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19-1
Efficiency Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Record Identifiers for Batch Interface to Xpediter/CICS NEWCOPY
Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19-2
Sample TPCONFIG Records for Batch Interface to Xpediter/CICS
NEWCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Batch Interface to Xpediter/CICS NEWCOPY JCL . . . . . . . . . . . . . . . . . . . . . . 19-3
Example Batch SYSPRINT Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19-3
xiv
Chapter 20. User-Defined DSECTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding the User DSECT File to CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Site-Specific DSECT Images. . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-Defined DSECT Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20-1
20-1
20-1
20-1
Appendix A. SMP/E Installation Using the EP Interface . . . . . . . . . . . . . . . . . . . . A-1
Primary and Optional Installation Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Install Enterprise Common Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
License Management System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Upload Product Files and Perform SMP/E Installation . . . . . . . . . . . . . . . . . . . A-2
System Requirements and Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Firewall Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Information on the Media Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Select Items for Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Enter File Transfer Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Upload Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Enter SMP/E Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Upload and Submit Installation Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
SMP/E JCL Uploaded to the Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Upload/Installation FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
Install Windows and Third-Party Products. . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
Installing Windows Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Installing Third-Party Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Appendix B. Installing Xpediter/CICS Using ISPF . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Part 1: Verify File Transfer and Perform TSO RECEIVE . . . . . . . . . . . . . . . . . . B-2
Part 2: Install Enterprise Common Components . . . . . . . . . . . . . . . . . . . . . . . B-2
License Management System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
Part 3: Customize Installation JCL with ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Step 1. Select Installation Components. . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Step 2. Specify Installation Environment Information . . . . . . . . . . . . . . . B-5
Step 3. Specify SMS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
Step 4. Specify Global CSI Dataset Name . . . . . . . . . . . . . . . . . . . . . . . . . B-8
Step 5. Specify Jobcard Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
Step 6. Specify SMP/E High-Level Qualifiers . . . . . . . . . . . . . . . . . . . . . . . B-9
Step 7. Specify Target and Distribution Zones. . . . . . . . . . . . . . . . . . . . . B-10
Step 8. Specify Installation-Dependent Libraries. . . . . . . . . . . . . . . . . . . B-11
Step 9. Verify Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . B-13
Step 10. Process the JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13
Part 4: Install Xpediter/CICS with SMP/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-15
Step 1. Allocate Compuware Global CSI and SMP/E Datasets . . . . . . . . B-15
Step 2. Allocate Libraries and SMP/E Datasets. . . . . . . . . . . . . . . . . . . . . B-16
Step 3. Initialize the Target and Distribution Zone CSIs . . . . . . . . . . . . . B-16
Step 4. Receive the Base Code, Maintenance, and HOLDDATA . . . . . . . B-16
Step 5. Review HOLDDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-16
Step 6. Apply the Base Code and Cumulative Maintenance to the
Target Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17
Step 7. Accept the Base Code to the Distribution Libraries. . . . . . . . . . . B-17
Step 8. Continue with Xpediter/CICS Configuration . . . . . . . . . . . . . . . B-18
Appendix C. Apply Maintenance with SMP/E . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1. Locate the Xpediter SMP/E Installation Sample Library. . . . . . . . . . . .
Step 2. Receive Maintenance and HOLDDATA . . . . . . . . . . . . . . . . . . . . . . . .
Step 3. Review HOLDDATA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C-1
C-1
C-1
C-2
C-3
xv
Step 4. Apply Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
Step 5. Accept Xpediter/CICS Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
Using the HELP PTFS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I-1
xvi
xvii
Figures
2-1.
2-2.
2-3.
2-4.
2-5.
2-6.
2-7.
2-8.
2-9.
2-10.
2-11.
2-12.
2-13.
2-14.
2-15.
2-16.
2-17.
2-18.
2-19.
2-20.
2-21.
2-22.
2-23.
2-24.
2-25.
2-26.
2-27.
2-28.
2-29.
3-1.
3-2.
3-3.
3-4.
3-5.
3-6.
3-7.
3-8.
3-9.
3-10.
3-11.
3-12.
3-13.
3-14.
3-15.
3-16.
3-17.
3-18.
3-19.
3-20.
3-21.
3-22.
3-23.
3-24.
3-25.
3-26.
Sample JCL to Copy Installation Dialog File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
Selecting Components to Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Installation Environment Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Specifying SMS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7
Specifying Global CSI Dataset Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
Entering Job Card Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-9
Specifying SMP/E High-Level Qualifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10
Specifying Target and Distribution Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
Specifying Installation-Dependent Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Confirming JCL Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Report Member Detailing JCL Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Displaying Completion Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Final JCL Customization Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Sample DBUGSSX Assembly JCL Member (DBCSSX) . . . . . . . . . . . . . . . . . . . . . .2-25
Defining the Profile File (DBCDEFPF) - Part 1 of 2 . . . . . . . . . . . . . . . . . . . . . . . .2-32
Defining the Profile File (DBCDEFPF) - Part 2 of 2 . . . . . . . . . . . . . . . . . . . . . . . .2-33
Defining the Employee File - SMXDSAMP member DBCDEFEM . . . . . . . . . . . . .2-34
Sample JCL (DBCDEFRP) to Allocate and Initialize Recreate Dataset
DBUGUD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-35
Sample JCL to Allocate SQL Transfer File (DBCDEFSQ). . . . . . . . . . . . . . . . . . . . .2-38
Sample JCL to Initialize the Transfer File (DBCINISQ) . . . . . . . . . . . . . . . . . . . . .2-39
RDO Transaction Definition for XSKL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-52
RDO Transaction Definition for XPGD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-52
RDO Program Definition for Xpediter/CICS DBUGSOCK . . . . . . . . . . . . . . . . . . .2-53
RDO Transaction Definition for XSOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-53
RDO Program Definition for Xpediter/CICS Sockets Security Exit XPDCICSE . . .2-54
Definitions for Enabling Listener to IP CICS Sockets. . . . . . . . . . . . . . . . . . . . . . .2-55
Sample JCL to Create USS Directory and File Structure . . . . . . . . . . . . . . . . . . . . .2-56
Copying Tar File to Tarball Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-57
Sample JCL to Extract Contents of Tar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-57
Primary Menu (XPED/XPRT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
XCB2 Demonstration Transaction Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
COBOL Source Listing Screen Showing ASRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Source Listing Screen After Entering GO 1 Command . . . . . . . . . . . . . . . . . . . . . .3-4
Transaction Complete Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
Source Listing Screen (2.L) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5
Before Breakpoint Indicator and Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Result of SHOW KEEPS Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Result of SHOW BREAKS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
First Pass Through the CWDEMCB2 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
XCB2 Demonstration Transaction Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Source Listing Screen Showing MOVE Statement . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Working Storage Screen (2.3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9
Source Listing Screen Showing Result of Entering GT Line Command . . . . . . . . .3-9
Program Trace Screen (2.4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Transaction Completion Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
Primary Menu (XPED/XPRT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
XASM Demonstration Transaction Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Assembler Source Listing Screen With Justification On . . . . . . . . . . . . . . . . . . . .3-12
Assembler Source Listing Screen (2.L) Showing Justification Off . . . . . . . . . . . . .3-13
Assembler Source Listing Screen After Entering GO 1 Command. . . . . . . . . . . . .3-14
XASM Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14
Source Listing Screen (2.L) Showing Assembler Source . . . . . . . . . . . . . . . . . . . . .3-15
Showing Keeps on the Source Listing Screen (2.L) . . . . . . . . . . . . . . . . . . . . . . . .3-16
Source Listing Screen Showing Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16
First Pass Through the CWDEMASM Program. . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17
xviii
3-27.
3-28.
3-29.
3-30.
3-31.
3-32.
3-33.
3-34.
3-35.
3-36.
3-37.
3-38.
3-39.
3-40.
3-41.
3-42.
3-43.
3-44.
3-45.
3-46.
3-47.
3-48.
3-49.
3-50.
3-51.
3-52.
3-53.
3-54.
3-55.
3-56.
3-57.
3-58.
3-59.
3-60.
3-61.
3-62.
3-63.
3-64.
3-65.
4-1.
5-1.
5-2.
5-3.
7-1.
7-2.
8-1.
8-2.
9-1.
9-2.
10-1.
13-1.
13-2.
13-3.
13-4.
13-5.
13-6.
14-1.
14-2.
14-3.
17-1.
Source Listing Screen Showing First Breakpoint in the Program. . . . . . . . . . . . . .3-17
Source Listing Screen Showing Statement Where Value of WRKHOUR
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18
Defined Storage (2.3) Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18
Source Listing Screen Showing Result of Entering GT Line Command . . . . . . . .3-19
Source Listing Screen Showing Slow-Stepping. . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19
XASM Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
XPLE Demonstration Transaction Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
PL/I Source Listing Screen Showing ASRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
Source Listing Screen After GO 1 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23
XPLE Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23
Source Listing Screen (2.L) for the Sample Program CWDEMPE. . . . . . . . . . . . . .3-24
Source Listing Screen Showing Where Data is Defined . . . . . . . . . . . . . . . . . . . . .3-25
Result of Entering RFIND Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25
Source Listing Screen Showing Keeps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-26
Source Listing Screen Showing Before Breakpoint at First Statement . . . . . . . . . .3-27
Source Listing Screen Showing WORK_AREA Declaration . . . . . . . . . . . . . . . . . .3-27
Source Listing Screen Showing Changed Value . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28
Variable Storage (2.3) Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-29
XPLE Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31
XCCC Demonstration Transaction Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32
C Source Listing Screen Showing ASRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33
Source Listing Screen After GO 1 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34
XCCC Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34
Source Listing Screen (2.L) for the Sample Program CWDEMC . . . . . . . . . . . . . .3-35
Source Listing Screen Showing Where Data is Defined . . . . . . . . . . . . . . . . . . . . .3-36
Result of Entering RFIND Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-36
Source Listing Screen Showing Keeps Before SET TRANSLATE Commands . . . . .3-37
Source Listing Screen Showing Keeps After SET TRANSLATE Commands . . . . . .3-38
Source Listing Screen Showing Before Breakpoint at First Statement . . . . . . . . . .3-38
XCCC Transaction Complete Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-40
Sample JCL to Assemble DBUGGBL Global Parameters Table. . . . . . . . . . . . . . . . .4-3
Sample Global Table Override Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3
Sample Global Table Override Console Log Output . . . . . . . . . . . . . . . . . . . . . . . .5-4
Sample JCL to Define the Global Table Parameter Overrides Dataset . . . . . . . . . . .5-5
Sample PROC to Execute the Xpediter Service Provider as a Started Task . . . . . . .7-5
Sample JCL to Execute the Xpediter Service Provider as a Batch Job . . . . . . . . . . .7-7
DBUGEND1 Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3
XPOF Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4
Sample JCL for DBCFORSQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1
Sample FORMATP Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-5
DBUGSTA1 Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Storage Protection Entries for Protecting Storage . . . . . . . . . . . . . . . . . . . . . . . . .13-2
Storage Protection Entries for Disabling Storage Monitoring . . . . . . . . . . . . . . . .13-3
Language Environment Storage Protection Entries . . . . . . . . . . . . . . . . . . . . . . . .13-4
Handler Module Exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-4
System Labels for Accessing the EIB Transaction ID . . . . . . . . . . . . . . . . . . . . . . .13-5
Transaction Dump Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-8
Sample DBPA Transaction Processing Report . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-3
Sample DBPA Transaction Input Console Log Output . . . . . . . . . . . . . . . . . . . . .14-4
Sample JCL to Define the DBPA Transactions Input Dataset . . . . . . . . . . . . . . . .14-5
Sample JCL to Allocate a System Script Dataset (DBCDEFSS) . . . . . . . . . . . . . . . .17-3
Figures
17-2.
18-1.
18-2.
18-3.
18-4.
18-5.
18-6.
18-7.
18-8.
18-9.
18-10.
18-11.
18-12.
18-13.
18-14.
18-15.
18-16.
18-17.
18-18.
18-19.
19-1.
19-2.
19-3.
20-1.
20-2.
A-1.
A-2.
A-3.
A-4.
A-5.
A-6.
A-7.
A-8.
A-9.
B-1.
B-2.
B-3.
B-4.
B-5.
B-6.
B-7.
B-8.
B-9.
B-10.
B-11.
B-12.
B-13.
B-14.
B-15.
C-1.
xix
Sample JCL to Allocate a User Script Dataset (DBCDEFUS) . . . . . . . . . . . . . . . . . .17-6
Sample JCL to Define File Utility Audit Trail GDG (DEFLOGDG). . . . . . . . . . . . .18-4
XLOG Screen with Xpediter/CICS Not Active . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-6
XLOG Screen with Xpediter/CICS Active, File Utility Audit Trail Not
Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-6
XLOG Screen after File Utility Audit Trail Not Activated . . . . . . . . . . . . . . . . . . .18-6
XLOG Screen after File Utility Audit Trail Activated . . . . . . . . . . . . . . . . . . . . . . .18-6
XLOG Screen when File Utility Audit Trail is Active . . . . . . . . . . . . . . . . . . . . . . .18-7
XLOG Screen when File Utility Audit Trail is Terminated. . . . . . . . . . . . . . . . . . .18-7
XLOG Screen when Dataset is Switched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7
XLOG Screen when Neither is Entered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7
Common Report Heading Lines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Formatting of Standard Entry Header Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Message Displayed when dataset is Closed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-9
Formatting of Dataset Service Request Changes . . . . . . . . . . . . . . . . . . . . . . . . . .18-9
Formatting of Dataset Record Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-10
Formatting of Dataset Record Update — Full . . . . . . . . . . . . . . . . . . . . . . . . . . .18-10
Formatting of Dataset Record Update — Short . . . . . . . . . . . . . . . . . . . . . . . . . .18-11
Formatting of Dataset Record Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-11
Formatting of DL/I Segment Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-12
Formatting of DB2 Row Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-12
TPCONFIG Records for Batch Interface to Xpediter/CICS NEWCOPY . . . . . . . . .19-3
Batch Interface to Xpediter/CICS NEWCOPY Sample Member JCLNEWC. . . . . .19-3
Example of SYSPRINT Messages from Batch Interface to Xpediter/CICS
NEWCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19-4
System Labels for User DSECTs on Define System Labels Screen (9.9) . . . . . . . . .20-2
User DSECT Displayed on DSECTs Screen (9.D) . . . . . . . . . . . . . . . . . . . . . . . . . .20-2
Installation Using the Product Setup Window or Using Optional ISPF
Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Mainframe Upload Dialog, Upper Portion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Mainframe Upload Dialog, Lower Portion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
SMP/E Install Dialog, Upper Portion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7
SMP/E Install Dialog, SMP/E Options Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
SMP/E Install Dialog, Zone Info and System Utilities Portion. . . . . . . . . . . . . . . . A-9
SMP/E Install Dialog, SMS Parameters and Dataset Definitions Portion . . . . . . . A-10
Windows® Products Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
3rd Party Products Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Installing Enterprise Common Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-4
Selecting Components to Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-4
Confirming Installation Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-5
Installation Environment Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-6
Specifying SMS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-7
Specifying Global CSI Dataset Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-8
Entering Job Card Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-9
Specifying SMP/E High-Level Qualifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-10
Specifying Target and Distribution Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-11
Specifying Xpediter/CICS Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-12
Specify DevEnterprise Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-12
Confirming JCL Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-13
Report Member Detailing JCL Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-14
Displaying Completion Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-14
Final JCL Customization Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-15
HELP PTFS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
xx
xxi
Tables
1-1.
1-2.
1-3.
1-4.
2-1.
2-2.
2-3.
2-5.
2-4.
2-6.
2-7.
2-8.
2-9.
2-10.
2-11.
2-12.
2-13.
2-14.
2-15.
2-16.
4-1.
4-2.
6-1.
7-1.
7-2.
9-1.
11-1.
11-2.
15-1.
15-2.
15-3.
15-4.
16-1.
18-1.
B-1.
C-1.
C-2.
DASD Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
SMP/E Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
Xpediter/CICS SMP/E Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12
Libraries Created During Installation with SMP/E . . . . . . . . . . . . . . . . . . . . . . . . .1-13
Installation JCL Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Resource Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Xpediter/CICS Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22
User Security for Xpediter/CICS Started Transactions . . . . . . . . . . . . . . . . . . . . . .2-23
Xpediter/Code Coverage Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23
User Security for Xpediter/Code Coverage Started Transactions. . . . . . . . . . . . . .2-24
Xpediter Service Provider Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
Load Libraries for CICS Release Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28
Xpediter Global Parameter DB2AUTH Settings . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37
Job JCLDBD Symbolic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40
Job JCLPSB Symbolic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40
Job JCLACB Symbolic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40
Job JCLLOAD Symbolic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41
Test Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-43
Additional Test Programs Using Channels and Containers . . . . . . . . . . . . . . . . .2-43
Sample CSS Language Processor JCL Members . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45
Global Table Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
Production Global Table Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12
Available Xpediter/CICS Functions by Operating Mode . . . . . . . . . . . . . . . . . . . . .6-3
Xpediter Service Provider Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1
Xpediter Service Provider Symbolic Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2
DBSQLUTL Format Utility Dataset Requirements . . . . . . . . . . . . . . . . . . . . . . . . . .9-7
Sample Source Members and Copy Books for File Security Exits . . . . . . . . . . . . .11-1
Exit Code Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3
Trap Summary Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-2
Monitor Exceptions Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
CSECT Exclusion Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
Storage Protection and System Labels Keywords . . . . . . . . . . . . . . . . . . . . . . . . . .15-5
CEECOPT Option Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-1
Standard Entry Header Line Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Installation JCL Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-15
Maintenance JCL Members for All Installed Components . . . . . . . . . . . . . . . . . . C-2
Maintenance JCL Members for Xpediter/CICS Only . . . . . . . . . . . . . . . . . . . . . . . C-2
xxii
xxiii
Introduction
Intro
This manual provides information about how to install, customize, and maintain
Xpediter/CICS. It contains the following chapters:
Chapter 1, “Installation Overview”: Provides an overview of the installation
requirements and considerations for Xpediter/CICS.
Chapter 2, “RFN Installation Procedures”: Lists the step-by-step procedures for
installing the product using Receive From Network (RFN) and SMP/E.
Chapter 3, “Installation Verification Procedures”: Describes the steps necessary to
verify that compile procedures have been successfully modified.
Chapter 4, “Global Parameters Table”: Provides a table of Xpediter/CICS customization
options.
Chapter 5, “Overriding Global Parameters”: Explains how to use Xpediter’s strongly
recommended method of overriding global table parameters during product startup.
Chapter 6, “Restricted Operating Modes”: Describes the three modes that allow a site to
tailor its Xpediter/CICS implementation to suit the processing integrity and throughput
requirements of its various CICS regions.
Chapter 7, “Xpediter Service Provider”: Explains how to configure and administer the
Xpediter Service Provider address space.
Chapter 8, “Session and Product Termination”: Describes the procedures to use for
automatic session termination and Xpediter/CICS termination.
Chapter 9, “DB2 Format Utility”: Describes how to use the DB2 format utility and the
available commands and options.
Chapter 10, “Intercommunication Considerations”: Lists the installation
requirements, example procedures, and restrictions for using Xpediter/CICS in an MRO
environment.
Chapter 11, “File Update Security Exit”: Discusses the procedures for installing,
modifying, implementing, and debugging the file update security exit.
Chapter 12, “Memory Update Security Exit”: Discusses the procedures for installing,
modifying, implementing, and debugging the memory update security exit.
Chapter 13, “Storage Protection”: Describes the procedure for initiating Xpediter’s
storage protection facility and ways to tailor this facility to meet your site’s specific
needs.
Chapter 14, “Specifying DBPA Transaction Input”: Explains how to use Xpediter’s
strongly recommended method of specifying DBPA transactions to create storage
protection entries during initialization of CICS and Xpediter.
Chapter 15, “Xpediter/CICS Startup During CICS Initialization”: Describes the DBPA
transaction, which sets abend traps or storage protection entries when Xpediter/CICS is
initiated at PLT startup.
Chapter 16, “Language Environment Operation”: Provides instructions on utilizing
Xpediter in a Language Environment installation and discusses software-raised error
conditions and amode considerations.
xxiv
Chapter 17, “Configuring the Script Facility”: Describes the Xpediter/CICS Script
Facility and how to configure it for use at your site.
Chapter 18, “File Utility Audit Trail”: Explains the Xpediter/CICS File Utility Audit
Trail and provides step-by-step instructions for enabling it.
Chapter 19, “Batch Interface to Xpediter/CICS NEWCOPY”: Describes how to perform
batch NEWCOPY (PHASEIN) of programs.
Chapter 20, “User-Defined DSECTs”: Describes the steps involved in defining and
displaying user DSECTs.
Appendix A, “SMP/E Installation Using the EP Interface”: Lists the step-by-step
procedures for installing Xpediter from an EP product distribution.
Appendix B, “Installing Xpediter/CICS Using ISPF”: Provides instructions for those
sites that choose to manually install Xpediter using ISPF.
Appendix C, “Apply Maintenance with SMP/E”: List the step-by-step procedures for
applying Xpediter/CICS maintenance manually using ISPF.
Once Xpediter/CICS is installed, its extensive Help facility—featuring hypertext
navigation—provides detailed information on all product features.
Intended Audience
This manual is intended for Xpediter/CICS installers and system programmers.
System Environment
See the Xpediter/CICS Release Notes for the most current system environment information.
Related Publications
The documents in the following list are provided in the installation package. For details,
see “Online Documentation” below.
• Xpediter/CICS Release Notes: Overview of release features, supported operating
environments, customer support, and any new Xpediter information.
• Xpediter/CICS User Guides for Assembler, C, COBOL, or PL/I: Introduction to Xpediter’s
levels, screens, and functions.
• Xpediter/CICS Reference Manual: Documents the screens and commands of the product.
• Xpediter/CICS Quick Reference: Overview of functions and command syntax and a quick
command reference.
• Xpediter/CICS Messages and Codes: Lists error and warning messages that might be
encountered during installation or use of Xpediter.
For information regarding Compuware Shared Services, refer to the Enterprise Common
Components Installation and Customization Guide.
Compuware Go Customer Support Website
Access online customer support for Compuware products via our Compuware Go
customer support website. View or download documentation, frequently asked questions,
and product fixes, or directly e-mail Compuware with questions or comments. To access
Introduction
xxv
Compuware Go, you must first register and obtain a password at
http://go.compuware.com.
Online Documentation
The installation package includes the following Xpediter documentation in these
electronic formats:
• Release Notes in HTML format
• The product manuals in PDF format
• The Adobe PDF index file (PDX file).
PDF and PDX Files
View and print the PDF files with Adobe Reader. Download a free copy of the reader from
Adobe’s website, http://www.adobe.com.
World Wide Web
Compuware’s site on the World Wide Web provides information about Compuware and
its products. The address is http://www.compuware.com.
Accessibility Information
Compuware is committed to making its products and services easier for everyone to use.
This section provides information about the features that make Xpediter/CICS more
accessible for people with disabilities. This section also applies to Xpediter’s features and
components.
Xpediter/CICS is a mainframe application designed to run on IBM's OS/390 or z/OS
operating systems, utilizing IBM’s ISPF on IBM 327x-type terminals. This platform offers
few if any accessibility features in the mainframe environment referenced above. Due to
this fact, Compuware Corporation has focused its attention in regard to the accessibility
of its mainframe products in the area of emulated 3270 sessions on personal computers
(PCs) with Windows 98 or higher operating systems. Xpediter supports and/or does not
disrupt, with few exceptions, Windows accessibility features and Windows-based
Assistive Technology (AT) devices and software such as Braille devices, screen readers,
and magnifiers.
Look for more information on accessibility features on our Compuware Go customer
support website at http://go.compuware.com/.
Note: Xpediter is a mainframe system development tool intended for use by mainframe
systems software developers/programmers. Much of the input and output used
and produced by Xpediter, such as program execution statistics, are not easily
understood by the general public, nor are they intended to be. Unfortunately, as
in the case of Xpediter reports, data/information in these formats by its very
nature can be confusing to screen readers, and therefore to those who use them
as well. Effective use of this application requires the specialized knowledge of a
mainframe systems software developer/programmer.
Selecting Font and Font Size in the Emulator
This option is particularly useful for people with low vision. By default, dialog boxes and
tool windows in the emulator window should use the same font as the Icon font used by
the operating system. The color settings for dialog boxes and tool windows should also
match the defaults used by the operating system. Text can also be manipulated within
xxvi
the emulator window to meet individual needs via the selection of font and/or font size
settings.
Changing Color
Xpediter/CICS inherits color and contrast settings from the emulator. Selecting the
color/contrast settings in the emulator or ISPF to provide appropriate highlighting can
assist users with low vision. For more information see the emulator or ISPF
documentation or help.
Special Considerations When Using a Screen Reader
Xpediter’s accessibility was evaluated using Freedom Scientific JAWS for Windows version
10.0 screen reader and Attachmate EXTRA! Personal Client Version 6.5 in addition to
Windows accessibility features.
When using a screen reader such as JAWS, select the following emulator settings for
enhanced compatibility:
• A plain font (such as Lucida, Courier New, or Times Roman)
• A font size of 10 or smaller (especially if JAWS is used)
• A blinking cursor with the fastest blink rate possible (especially if JAWS is used).
Enhanced accessibility can be gained by customizing of your screen reader for your
emulator. Different emulator/screen reader combinations can present differing
compatibility issues. Consult your screen reader’s documentation, help, or technical
support for more information.
Exceptions and Work-Arounds
Known Exceptions
During Xpediter/CICS’s accessibility evaluation, some exceptions were encountered in
which some accessibility features or assistive technology were not fully supported. These
exceptions are currently under investigation by Compuware Corporation and include:
• Some system error and warning messages are not read by screen reader when issued.
This is believed to be caused by an external interface. See “Work-Arounds” below.
• Some system error and warning messages are not accompanied by audio alerts when
issued, however they are read by screen reader. This is believed to be caused by an
external interface. Currently, no solution is available.
• System error and warning messages do not capture visual focus of a screen magnifier.
This is believed to be caused by an external interface. Currently, no solution is
available.
• Some entry and display fields lack individual labels, and when entry fields are
accessed via the Tab key, the entire individual line is read.
Work-Arounds
• When the screen reader fails to read an error or warning message (an audio alert will
occur if enabled on your system), move the cursor up the screen to the line
containing the error message (usually on the top/title line). Allow the screen reader
to read the line and its error message individually.
Notation Rules
Syntax diagrams define primary command syntax.
Introduction
xxvii
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.
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.
xxviii
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 Go Customer Support Website
You can access online information for Compuware products via our Compuware Go
customer support website at http://go.compuware.com.
Compuware Go provides access to critical information about your Compuware products.
You can review frequently asked questions, read or download documentation, access
product fixes, or e-mail your questions or comments. The first time you access
Compuware Go, you are required to register and obtain a password. Registration is free.
Compuware now offers User Communities, online forums to collaborate, network, and
exchange best practices with other Compuware solution users worldwide. To join, go to
http://groups.compuware.com.
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 http://go.compuware.com.
Web
You can report issues via the Quick Link Create & View Support Cases on the
Compuware Go home page.
Note: 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.
Introduction
xxix
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.
xxx
1-1
Chapter 1.
Installation Overview
Chap 1
This chapter contains important information that can help you install the Xpediter/CICS
product in the most efficient manner. It also discusses installation considerations for new
users. Review it before beginning the installation process.
Topics presented in this chapter include:
• Preinstallation Considerations:
– “Enterprise Common Components”
– “Support for CICS Dynamic LIBRARY Capability”
– “Miscellaneous Considerations”
– “Specifying SLS Dataset(s)”
– “DASD Space Requirements”
– “Xpediter/Code Coverage Users”
– “Current Xpediter/CICS Users”
– “Installing Xpediter FMIDs for Multiple CICS Releases”
– “Reinstallation After CICS Upgrade”
– “Cancelling AID Blocks”
– “Current Abend-AID for CICS Users”
– “Minimizing CPU Consumption When Using Xpediter/Code Coverage”
– “Current CA SYSVIEW® Users”
– “Minimizing CPU Consumption When Using Xpediter/Code Coverage”
– “Performance Monitors”
– “Establishing PLT Startup Entries”
– “Suppressing System Dumps Resulting from ASRA and ASRB Abends”
– “APF Authorization”.
• SMP/E Installation and Maintenance:
– “Allocating SMP/E Zones”
– “Installing with SMP/E”
– “Installing Xpediter/CICS Using JCL Customization Facility (Optional)”
– “Xpediter/CICS Packaging”
– “SMP/E Layout”
– “Libraries Created During SMP/E Installation”.
Preinstallation Considerations
Enterprise Common Components
Before you begin installing this product, please be aware that the process includes
installation of two Enterprise Common Components: Compuware Shared Services (CSS)
and License Management System (LMS). CSS and LMS are required for use of
Xpediter/CICS and are on the Enterprise Common Components (ECC) media provided in
its own shipping package. (Refer to “System Environment” in “Introduction” for
information on supported releases.) Installation guidelines are presented in Chapter 2,
“RFN Installation Procedures”.
Note: Xpediter/CICS requires Compuware Shared Services Release 8.8 or above.
CSS and LMS use an SMP/E installation and are shipped on separate media. For more
details, consult the Enterprise Common Components Installation and Customization Guide.
1-2
Support for CICS Dynamic LIBRARY Capability
CAUTION:
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.
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
user-customized 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.
Miscellaneous Considerations
The z/OS-supplied (or OS/390-supplied) datasets listed below are required during SMP/E
APPLY of Xpediter/CICS. The high-level qualifiers of the dataset names may vary at your
site.
•
•
•
•
•
CEE.SCEELKED
TCPIP.SEZARNT1
TCPIP.SEZACMTX
TCPIP.SEZATCP
SYS1.CSSLIB
IMPORTANT:
An MVS APF authorized library is now required.
Note: This authorized library must not be included in the MVS linklist. Doing so would
allow unrestricted access.
IMPORTANT:
• The Xpediter Service Provider address space must be active before initialization of
Xpediter/CICS.
• The Xpediter transactions XPFS and XROI should not be secured. (All users of
Xpediter, including the userID associated with PLTPI programs, should be permitted
to execute these transactions.) XPFS is required for source support, and securing it
can cause a NO SOURCE AVAILABLE condition. For more information, see “Step 4.
External Security Considerations” on page 2-21.
1-3
Before installing the product, carefully review the following chapters:
• Chapter 5, “Overriding Global Parameters”
• Chapter 14, “Specifying DBPA Transaction Input”
Note: Procedures in Chapter 2, “RFN Installation Procedures” describe installation of
Xpediter/CICS in a single region. MRO (multiregion operation) users should also
refer to Chapter 10, “Intercommunication Considerations”.
Specifying SLS Dataset(s)
SLS datasets are accessed using CICS I/O facilities and require CICS file control entry
definitions.
DASD Space Requirements
Table 1-1 lists the estimated DASD space needed for Xpediter/CICS target libraries.
Table 1-1.
DASD Space Requirements
Component
Each CICS dependent FMID
Dataset Name
3390 DASD Cylinders
CPWR.cMXD930.SMXDAAFX
5
CPWR.cMXD930.SMXDAUTH
5
CPWR.cMXD930.SMXDOxxL
75
CPWR.cMXD930.SMXDPDSE
5
CPWR.cMXD930.SMXDSAMP
10
Note: 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.
Xpediter/Code Coverage Users
Xpediter/Code Coverage is an advanced analysis tool that identifies how much of an
application has been tested. It utilizes Xpediter/CICS to collect data during testing.
The Xpediter/Code Coverage Mainframe Installation Guide includes various references to
Xpediter/CICS datasets. If you are installing a new release of Xpediter/CICS, but not a
new release of Xpediter/Code Coverage, you should still revisit the Xpediter/Code Coverage
Mainframe Installation Guide. Migration to the new Xpediter/CICS release should include
Xpediter/Code Coverage components that use Xpediter/CICS libraries.
Current Xpediter/CICS Users
If you are an experienced installer of Xpediter/CICS, you may prefer to use the following
guidelines instead of the detailed procedures in the next chapter to install the product.
However, to ensure an error-free installation, Compuware strongly recommends
reviewing the procedures in Chapter 2, “RFN Installation Procedures” before
beginning.
1. Install Compuware Shared Services. See Chapter 2, “RFN Installation Procedures”,
“Install Enterprise Common Components” on page 2-2.
1-4
Note: The Compuware Shared Services load library must be included in the DFHRPL
concatenation of the CICS startup JCL. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 7. Update the CICS
Startup JCL” on page 2-28.
2. Install Xpediter/CICS. See Chapter 2, “RFN Installation Procedures”, “Part 1:
Initialize Installation Environment” on page 2-2.
3. Optional: Prepare the ISPF Edit Macro. If you have used this ISPF Edit Macro in the
past, you should review and update the information as required. See Chapter 2,
“RFN Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 1. Prepare
the ISPF Edit Macro (Optional)” on page 2-17.
4. Authorize the Xpediter/CICS authorized library (SMXDAUTH) and establish the MVS
program properties for program DBUGSTC. Add the authorized library name to
IEAAPFxx or PROGxx in SYS1.PARMLIB. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 2. Integrate Xpediter/CICS
with MVS” on page 2-17.
5. Update the CICS resource definitions. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 3. Update the CICS Resource
Definitions” on page 2-18.
Note: Xpediter might not initialize using the resource definitions from a previous
release. Compuware highly recommends the use of RENTPGM parameter set
to PROTECT.
6. Review external security considerations. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 4. External Security
Considerations” on page 2-21.
Note: The delivery of the default Subsystem Security Exit (DBUGSSX) has changed,
beginning with Release 8.2. The default exit is now delivered with the load
module name DBUGSSXX in SMXDAUTH. Therefore, a Subsystem Security
Exit will be used only if you take action. If you need to use a Subsystem
Security Exit, you can rename DBUGSSXX to DBUGSSX or create your own
customized version. An example SMP/E USERMOD to rename the module is in
member SSXXUMOD in SMXDSAMP. For more information, see “Step 4.
External Security Considerations” on page 2-21.
7. Run the Xpediter Service Provider initialization job. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 6. Initialize the
Xpediter Service Provider” on page 2-26.
Note: The Xpediter Service Provider address space must be active before
initialization of Xpediter/CICS.
8. Update the CICS startup JCL. See Chapter 2, “RFN Installation Procedures”,“Part 4:
Configure Xpediter/CICS”, “Step 7. Update the CICS Startup JCL” on page 2-28.
9. Optional: Allocate the new profile file (DBCDEFPF). See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 13. Allocate the New Profile
File (DBCDEFPF)” on page 2-31.
Notes:
– If you have been using the profile file, you may continue to use your existing
dataset. However, the ability to save and restore traps only exists with the new
format data set.
– An ENQMODEL for the profile dataset, included in sample member CSDXDFIL,
was introduced in release 8.1. (It was included in PTFs for previous releases.)
Ensure that this ENQMODEL definition is added to all CICS regions that share
1-5
the same Xpediter/CICS Profile Dataset. This ensures that ENQs done for the
Profile File are recognized across all CICS regions in the sysplex.
10. Verify the Xpediter/CICS installation. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 8. Verify the Xpediter/CICS
Installation” on page 2-29.
11. Review your site’s automatic session termination options. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 9. Review
Automatic Session Termination” on page 2-30. For more information, refer to
Chapter 8, “Session and Product Termination”.
12. If you reassembled the global table during a previous Xpediter/CICS installation,
review the global table parameters and make any required changes. See Chapter 2,
“RFN Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 10. Review
Global Parameters” on page 2-30.
Note: If you have been using the default global table parameters, you may want to
review them for possible changes that may be required for your site.
Before submitting your JCL to assemble the global table, ensure the following
datasets are in the SYSLIB concatenation:
– SMXDSAMP member containing macro DBUGGBLM
– SYS1.MACLIB.
13. Optional: Create the global table parameters override dataset. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 11. Create the
Global Table Parameters Override Dataset (Optional)” on page 2-31.
Notes:
– Compuware strongly recommends using this feature due to the greatly enhanced
ease of use it provides. For detailed information, see Chapter 5, “Overriding
Global Parameters”.
– If you have been using a global parameters override dataset, review the
parameters for possible changes that may be required for your site. You may
continue to use your existing dataset.
14. Optional: Create the DBPA transaction input dataset. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 12. Create DBPA
Transaction Input Dataset (Optional)” on page 2-31.
Notes:
– Compuware strongly recommends this method of utilizing DBPA transaction
input to configure storage protection and abend trapping. This feature is easier to
set up and use and includes reporting capabilities. For detailed information, see
Chapter 14, “Specifying DBPA Transaction Input”.
– If you have been using the DBPA file, you may continue to use your existing
dataset.
15. Optional: Allocate and initialize the employee file (DBCDEFEM). See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 14. Allocate and
Initialize the Employee File (DBCDEFEM) (Optional)” on page 2-33.
Note: If you have been using the employee file, you may continue to use your
existing dataset.
16. Optional: Allocate and initialize the Recreate dataset (DBUGUD). See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 15. Allocate and
Initialize the Recreate Dataset (DBUGUD) (Optional)” on page 2-34.
Note: If you have been using the Recreate dataset, you may continue to use your
existing dataset.
1-6
17. Optional: Implement support for the DB2 file utility. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 16. Implement
Support for the DB2 File Utility (Optional)” on page 2-35.
Note: The DBRM members for the DB2 File Utility have been updated in this release
of Xpediter. The bind for plan (MXD0930) must be rerun if using the DB2 file
utility.
18. Optional: Allocate, format, and initialize the SQL transfer file (DBCDEFSQ). See
Chapter 2, “RFN Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step
17. Allocate, Format, and Initialize the SQL Transfer File (DBCDEFSQ) (Optional)” on
page 2-37.
Note: If you have been using the SQL transfer file, you may continue to use your
existing dataset.
19. Install the Compuware Xpediter/CICS Diagnostic Modules. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 18. Install the
Xpediter/CICS Diagnostic Modules (Optional)” on page 2-39.
Note: The target library, SMXDAAFX, now contains the Diagnostic Modules.
20. Optional: Implement the file utility security exit. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 19. Implement the File Utility
Security Exit (Optional)” on page 2-39.
21. Optional: Implement Xpediter/CICS DBCTL support. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 20. Implement
Xpediter/CICS DBCTL Support (Optional)” on page 2-39.
22. Optional: Configure the Script Facility. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 21. Configure the Script
Facility (Optional)” on page 2-42.
Note: If you have been using a system script dataset, you may continue to use your
existing dataset.
23. Optional: Configure the File Utility Audit Trail. See Chapter 2, “RFN Installation
Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 22. Configure the File Utility
Audit Trail (Optional)” on page 2-42.
Note: If you have been using a GDG dataset, you may continue to use your existing
dataset.
24. Review the Language Environment run-time options. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 23. Review the
Language Environment Run-Time Options” on page 2-42.
25. Optional: Assemble/compile and link edit the test programs. See Chapter 2, “RFN
Installation Procedures”, “Part 4: Configure Xpediter/CICS”, “Step 24.
Assemble/Compile and Link-Edit the Test Programs (Optional)” on page 2-43.
Note: If you have previously installed the test programs, you do not need to
recompile them.
26. Verify Xpediter/CICS execution. See Chapter 2, “RFN Installation Procedures”,
“Part 4: Configure Xpediter/CICS”, “Step 25. Verify Xpediter/CICS Execution” on
page 2-46.
1-7
Installing Xpediter FMIDs for Multiple CICS Releases
If you install two or more CICS-dependant FMIDs for the same release of Xpediter/CICS,
there will be an instance of SMXDAUTH, SMXDAAFX, SMXDPDSE, and SMXDSAMP for
each FMID. Assuming the same level of maintenance on each FMID, all instances of these
datasets are identical. The following example uses SMXDAUTH, but the concept applies
equally to SMXDAAFX, SMXDPDSE, and SMXDSAMP.
Consider this example. You presently use the MMXD930 FMID and are installing the
OMXD930 FMID for a newer CICS release. Your Xpediter Service Provider has
CPWR.MMXD930.SMXDAUTH as the STEPLIB. There is no technical requirement to
immediately change the STEPLIB to specify CPWR.OMXD930.SMXDAUTH as the
STEPLIB.
There may be an operational reason to migrate to use of the OMXD930 instance of
SMXDAUTH, at some convenient time. Once all CICS regions have been migrated to the
newer CICS release, you may want to archive or delete the MMXD930 datasets.
Obviously, that archive or delete cannot be completed if the MMXD930 instance of
SMXDAUTH is still in use.
Reinstallation After CICS Upgrade
If you install a new CICS release, you are not required to perform a complete
reinstallation of Xpediter/CICS. At the very least, however, you must perform “Part 1:
Initialize Installation Environment” on page 2-2, executing the jobs required for your
new version of CICS. You must also perform “Step 3. Update the CICS Resource
Definitions” on page 2-18 and “Step 7. Update the CICS Startup JCL” on page 2-28 of
“Part 4: Configure Xpediter/CICS”. Review the rest of that section to determine whether
additional steps are required at your site. Optional datasets such as the global parameter
overrides dataset, profile file, or SQL transfer file can be reused with the new version of
CICS. Refer to “Current Xpediter/CICS Users” on page 1-3 for other installation
considerations.
Cancelling 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.
Current Abend-AID for CICS Users
If you are a current Abend-AID for CICS user, you should be aware that Abend-AID for
CICS and Xpediter/CICS use Compuware Shared Services to format, access, and update
the source listing file. Compuware Shared Services is a part of Enterprise Common
Components (ECC). The newest version of ECC is shipped with each release of
Xpediter/CICS and Abend-AID for CICS.
Current CA SYSVIEW® Users
If you are a current CA SYSVIEW ® user, be aware that CA SYSVIEW and Xpediter/CICS
both supply a CICS transaction named XPFS. Both products provide a way to change the
1-8
transaction ID. If you decide to change the Xpediter/CICS transaction ID, refer to the
XPFS parameter in Chapter 4, “Global Parameters Table” and “Step 3. Update the CICS
Resource Definitions” on page 2-18. If you prefer to change the CA SYSVIEW transaction
ID, consult the appropriate CA documentation.
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 Chapter 4, “Global
Parameters Table”. This region-wide option can also be changed from any
Xpediter/CICS debugging session with the SET BTRACE primary command. For more
information, see the Xpediter/CICS Reference Manual.
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.
Note: 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.
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.
1-9
Note: 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).
CAUTION:
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.
Performance Monitors
If you use CICS performance monitors that limit the duration of CICS transactions,
exclude Xpediter/CICS’s background transactions from monitoring. The transactions to
be excluded are XPFS, XSKL, and XVKP. Long-running functions may exceed the
monitor's duration parameters.
Establishing PLT Startup Entries
Xpediter/CICS provides a facility for using DBPA transactions to establish PLT startup
entries. DBPA transactions are used to configure Xpediter’s storage protection and abend
trapping.
During CICS or Xpediter initialization, the DBPA facility reads a dataset that contains the
necessary transactions. Only minor changes to the CICS startup JCL and creation of the
DBPA transaction dataset are required to utilize the facility. Refer to Chapter 14,
“Specifying DBPA Transaction Input” for detailed information.
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.
APF Authorization
Following IBM system integrity guidelines, Compuware recommends that your Xpediter
load library not be APF-authorized. Depending on your MVS system installation options,
libraries placed in the link list may be APF-authorized automatically.
1-10
SMP/E Installation and Maintenance
Xpediter/CICS is packaged for installation using System Modification Program Extended
(SMP/E). SMP/E is a method developed by IBM to install software products in the MVS
environment. This section describes allocating SMP/E zones, SMP/E jobs to be executed,
and libraries created during the SMP/E installation.
SMP/E provides enhanced installation management and maintenance tracking
capabilities. To facilitate SMP/E, the Xpediter/CICS installation contains both the base
code and all cumulative, approved maintenance to-date.
Compuware recommends that you periodically obtain and apply maintenance to keep
your product version current. You can obtain cumulative maintenance from Compuware
Go (Frontline) or by ordering an updated copy of Xpediter/CICS. To install the
Xpediter/CICS maintenance to an existing installation, you only need to perform the
steps described in “Part 1: Initialize Installation Environment” on page 2-2, or
(optionally) the steps in Appendix C, “Apply Maintenance with SMP/E”.
Note: Compuware recommends using the Receive From Network (RFN) installation
procedure described in Chapter 2, “RFN Installation Procedures”. The alternate
procedures in Appendix A, “SMP/E Installation Using the EP Interface” are
intended for those sites that use the EP interface to perform a full SMP/E
installation, and the alternate procedures in Appendix B, “Installing
Xpediter/CICS Using ISPF” are intended for those sites that first use the EP
interface, but only to upload product files to the mainframe.
The alternate procedure in Appendix C, “Apply Maintenance with SMP/E” utilizes the
Installation JCL Customization Facility consisting of a set of REXX EXECs, JCL skeletons,
and panels. This facility prompts you for the installation information and then builds
the necessary jobs required to perform the SMP/E installation. You can also view
reporting information from the installation facility, such as parameters and execution
information.
Allocating SMP/E Zones
SMP/E uses a VSAM cluster called a CSI (Consolidated Software Inventory) to control all
product installation and maintenance information. Within a CSI, there are a minimum
of three zones:
• Global zone
• Target zone
• Distribution zone
If a CSI is shared among several different products, there will be a single Global zone and
a separate set of Target and Distribution zones for each product installed as illustrated in
Table 1-2. A site may have many CSIs, each with its own Global, Target, and Distribution
zones.
Note: To prevent possible conflicts, Compuware strongly recommends that all
Compuware products and components distributed via SMP/E share a single
Global zone reserved solely for Compuware products. Target and distribution
zones cannot be shared.
Table 1-2.
SMP/E Zones
Global Zone
Target Zone CICS TS 3.1
Distribution Zone CICS TS 3.1
Table 1-2.
1-11
SMP/E Zones
Global Zone
There are many different ways to allocate the zones. These methods include the
following:
• The Global, Target, and Distribution zones may all reside together in a single VSAM
cluster.
• The zones may each reside in separate VSAM clusters.
• The zones may each reside in a combination of VSAM clusters.
For example, you could have a single VSAM cluster for your Global zone and combine all
the Target and Distribution zones in a second VSAM cluster. Or each set of Target and
Distribution zones may be combined in a single VSAM cluster. Compuware recommends
that all zones be placed in separate VSAM clusters so that each zone can be backed up
and restored individually, if necessary, without impacting any other zone.
Installing with SMP/E
The SMP/E portion of the installation process consists of seven basic steps:
1.
2.
3.
4.
5.
6.
7.
Allocate and initialize the SMP/E datasets.
Receive base.
Apply base.
Accept base.
Receive maintenance.
Apply maintenance.
Accept maintenance.
After a function or maintenance (such as a PTF) has gone through the ACCEPT step, that
becomes your current release-base level. At any time prior to the ACCEPT step, you may
issue a RESTORE command to reset your Target libraries to the way they were as of the
last ACCEPT command. The RESTORE command is used to remove maintenance, or even
entire functions, while the ACCEPT command effectively sets a new base level of the
release to which further maintenance will be applied. For more information about using
the RESTORE command, refer to your site’s IBM SMP/E documentation.
Installing Xpediter/CICS Using JCL Customization Facility (Optional)
Note: Compuware recommends using the Receive From Network (RFN) installation
installation, and the alternate procedures in Appendix B, “Installing
Xpediter/CICS Using ISPF” are intended for those sites that first use the EP
interface, but only to upload product files to the mainframe.
The alternate procedure in Appendix B, “Installing Xpediter/CICS Using ISPF” utilizes the
Installation JCL Customization Facility consisting of a set of REXX EXECs, JCL skeletons,
messages, and panels contained in the SMP/E installation sample library. The facility will
display several panels to obtain installation information, and then will build the
necessary jobs required to perform the SMP/E installation. The facility allows you to
input SMP/E information, such as the Global SMP/E and SMP/E dataset high-level
qualifiers, one time. They can then be used in all SMP/E installation jobs.
1-12
Note: The Installation JCL Customization Facility asks for your site’s dataset names for
certain IBM-supplied datasets. The default names are shown in Figure B-10 on
page B-12. It would be beneficial to verify the appropriate dataset names for your
site before you begin the installation procedures.
Using the Installation JCL Customization Facility, you can install any or all of the
following:
•
•
•
•
•
•
CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
3.1
3.2
4.1
4.2
5.1
5.2
modules
modules
modules
modules
modules
modules.
Xpediter/CICS Packaging
Compuware has registered the following element prefixes with IBM for the
Xpediter/CICS components:
• MXD for Xpediter/CICS
• KCW as a generic Compuware prefix.
The FMIDs for each component are listed below.
•
•
•
•
•
•
MMXD930 - CICS TS 3.1 modules
NMXD930 - CICS TS 3.2 modules
OMXD930 - CICS TS 4.1 modules
PMXD930 - CICS TS 4.2 modules
QMXD930 - CICS TS 5.1 modules
RMXD930 - CICS TS 5.2 modules.
SMP/E Layout
Refer to Table 1-3 for a list of the SMP/E files created by unloading the Xpediter/CICS
distribution media, where dasdhlq is the DASD high-level qualifier chosen for your site.
Table 1-3.
Xpediter/CICS SMP/E Layout
File Name
File Contents
dasdhlq.CPWR.XD090300.MCS
MCS statements
dasdhlq.CPWR.XD090300.MNT
PTFs/APARs for this release (cumulative maintenance)
dasdhlq.CPWR.XD090300.HLD
HOLDDATA for maintenance
dasdhlq.CPWR.XD090300.ABS
Abstracts only for PTFs/APARs
dasdhlq.CPWR.MMXD930.F1
JCLIN statements for FMID MMXD930
Object modules for FMID MMXD930
Samples and JCL for optional steps for FMID MMXD930
dasdhlq.CPWR.NMXD930.F1
JCLIN statements for FMID NMXD930
Object modules for FMID NMXD930
Samples and JCL for optional steps for FMID NMXD930
dasdhlq.CPWR.OMXD930.F1
JCLIN statements for FMID OMXD930
Object modules for FMID OMXD930
Samples and JCL for optional steps for FMID OMXD930
dasdhlq.CPWR.PMXD930.F1
JCLIN statements for FMID PMXD930
Table 1-3.
1-13
Xpediter/CICS SMP/E Layout
File Name
File Contents
Object modules for FMID PMXD930
Samples and JCL for optional steps for FMID PMXD930
dasdhlq.CPWR.QMXD930.F1
JCLIN statements for FMID QMXD930
Object modules for FMID QMXD930
Samples and JCL for optional steps for FMID QMXD930
dasdhlq.CPWR.RMXD930.F1
JCLIN statements for FMID RMXD930
Object modules for FMID RMXD930
Samples and JCL for optional steps for FMID RMXD930
Libraries Created During SMP/E Installation
Table 1-4 lists the libraries created during the Xpediter/CICS installation using SMP/E.
Table 1-4.
Libraries Created During Installation with SMP/E
DDname
Library Type and Content
Dataset Name as Distributed
SMPCSI
Compuware Global CSI
CPWR.GLOBAL.CSI
SMPLOG
Compuware SMP/E System File
CPWR.GLOBAL.SMPLOG
SMPPTS
Compuware SMP/E System File
CPWR.GLOBAL.SMPPTS
MXD930D
CICS TS 3.1 Distribution Zone
CPWR.MMXD930.DZONE.CSI
MXD930T
CICS TS 3.1 Target Zone
CPWR.MMXD930.TZONE.CSI
SMPTLIB
CICS TS 3.1 SMP/E System File
CPWR.MMXD930.F1
SMP#####
CPWR.MMXD930.F2
SMPMTS
CPWR.MMXD930.SMPMTS
SMPSCDS
CPWR.MMXD930.SMPSCDS
SMPSTS
CPWR.MMXD930.SMPSTS
SMXDSAMP CICS TS 3.1 Target Sample Library
CPWR.MMXD930.SMXDSAMP
AMXDSAMP CICS TS 3.1 Distribution Sample Library
CPWR.MMXD930.AMXDSAMP
SMXDAUTH CICS TS 3.1 Target Authorized Loadlib
CPWR.MMXD930.SMXDAUTH
SMXDAAFX
CPWR.MMXD930.SMXDAAFX
CICS TS 3.1 Target Abend-AID for CICS Help Library
AMXDO64L CICS TS 3.1 Distribution Load Library
CPWR.MMXD930.AMXDO64L
SMXDO64L
CICS TS 3.1 Target Loadlib
CPWR.MMXD930.SMXDO64L
SMXDPDSE
CICS TS 3.1 Target PDS/E Loadlib for ROCI & Batch
NEWCOPY
CPWR.MMXD930.SMXDPDSE
NXD930D
CPWR.NMXD930.DZONE.CSI
NXD930T
CPWR.NMXD930.TZONE.CSI
SMPTLIB
CPWR.NMXD930.F1
SMP#####
CPWR.NMXD930.F2
SMPMTS
CPWR.NMXD930.SMPMTS
SMPSCDS
CPWR.NMXD930.SMPSCDS
SMPSTS
CPWR.NMXD930.SMPSTS
CPWR.NMXD930.SMXDSAMP
1-14
Table 1-4.
DDname
CPWR.NMXD930.AMXDSAMP
CPWR.NMXD930.SMXDAUTH
SMXDAAFX
CPWR.NMXD930.SMXDAAFX
CPWR.NMXD930.AMXDO65L
SMXDO65L
CPWR.NMXD930.SMXDO65L
SMXDPDSE
NEWCOPY
CPWR.NMXD930.SMXDPDSE
OXD930D
CPWR.OMXD930.DZONE.CSI
OXD930T
CPWR.OMXD930.TZONE.CSI
SMPTLIB
CPWR.OMXD930.F1
SMP#####
CPWR.OMXD930.F2
SMPMTS
CPWR.OMXD930.SMPMTS
SMPSCDS
CPWR.OMXD930.SMPSCDS
SMPSTS
CPWR.OMXD930.SMPSTS
CPWR.OMXD930.SMXDSAMP
CPWR.OMXD930.AMXDSAMP
CPWR.OMXD930.SMXDAUTH
SMXDAAFX
CPWR.OMXD930.SMXDAAFX
CPWR.OMXD930.AMXDO66L
SMXDO66L
CPWR.OMXD930.SMXDO66L
SMXDPDSE
NEWCOPY
CPWR.OMXD930.SMXDPDSE
PXD930D
CPWR.PMXD930.DZONE.CSI
PXD930T
CPWR.PMXD930.TZONE.CSI
SMPTLIB
CPWR.PMXD930.F1
SMP#####
CPWR.PMXD930.F2
SMPMTS
CPWR.PMXD930.SMPMTS
SMPSCDS
CPWR.PMXD930.SMPSCDS
SMPSTS
CPWR.PMXD930.SMPSTS
CPWR.PMXD930.SMXDSAMP
CPWR.PMXD930.AMXDSAMP
CPWR.PMXD930.SMXDAUTH
SMXDAAFX
CPWR.PMXD930.SMXDAAFX
CPWR.PMXD930.AMXDO67L
SMXDO67L
CPWR.PMXD930.SMXDO67L
SMXDPDSE
NEWCOPY
CPWR.PMXD930.SMXDPDSE
QXD930D
CPWR.QMXD930.DZONE.CSI
QXD930T
CPWR.QMXD930.TZONE.CSI
SMPTLIB
CPWR.QMXD930.F1
1-15
Table 1-4.
DDname
SMP#####
CPWR.QMXD930.F2
SMPMTS
CPWR.QMXD930.SMPMTS
SMPSCDS
CPWR.QMXD930.SMPSCDS
SMPSTS
CPWR.QMXD930.SMPSTS
CPWR.QMXD930.SMXDSAMP
CPWR.QMXD930.AMXDSAMP
CPWR.QMXD930.SMXDAUTH
SMXDAAFX
CPWR.QMXD930.SMXDAAFX
CPWR.QMXD930.AMXDO68L
SMXDO68L
CPWR.QMXD930.SMXDO68L
SMXDPDSE
NEWCOPY
CPWR.QMXD930.SMXDPDSE
RXD930D
CPWR.RMXD930.DZONE.CSI
RXD930T
CPWR.RMXD930.TZONE.CSI
SMPTLIB
CPWR.RMXD930.F1
SMP#####
CPWR.RMXD930.F2
SMPMTS
CPWR.RMXD930.SMPMTS
SMPSCDS
CPWR.RMXD930.SMPSCDS
SMPSTS
CPWR.RMXD930.SMPSTS
CPWR.RMXD930.SMXDSAMP
CPWR.RMXD930.AMXDSAMP
CPWR.RMXD930.SMXDAUTH
SMXDAAFX
CPWR.RMXD930.SMXDAAFX
CPWR.RMXD930.AMXDO69L
SMXDO69L
CPWR.RMXD930.SMXDO69L
SMXDPDSE
NEWCOPY
CPWR.RMXD930.SMXDPDSE
1-16
2-1
Chapter 2.
RFN Installation Procedures
Chap 2
Note: If you are unable to use the Receive from Network (RFN) process to SMP/E install
Xpediter/CICS, use the alternative installation method described in Appendix A,
“SMP/E Installation Using the EP Interface”.
In response to customer requests, Compuware has added Receive From Network (RFN) to
its product delivery and installation methods. The RFN process enables you to receive the
product directly to your z/OS environment and install it using System Modification
Program Extended (SMP/E).
After you select a licensed product from Compuware’s online ordering system, you
receive an e-mail message containing sample JCL for creating the SMP/E Global Zone and
performing the RFN job. It may also contain a link for downloading any PC-based
products that may have been ordered at the same time.
The following steps provide a checklist for installing Xpediter using RFN procedures.
Please note that this procedure also references the installation of Enterprise Common
Components (ECC), which is provided separately in SMP/E installation format.
Install Enterprise Common Components
Part 1: Initialize Installation Environment
1. Create Global Zone CSI
2. Receive From Network
3. Copy Installation Dialog File from USS to z/OS.
Part 2: Customize Installation JCL with ISPF
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
Make Note of HLQ, Global Zone CSI, and Installation File Name
Select Installation Components
Specify Installation Environment Information
Specify SMS Parameters
Specify Global CSI Dataset Name
Specify Jobcard Information
Specify SMP/E High-Level Qualifiers
Specify Target and Distribution Zones
Specify Installation-Dependent Libraries
Verify Installation Information
Process the JCL.
Part 3: Install Xpediter/CICS with SMP/E
1.
2.
3.
4.
5.
Allocate Libraries and SMP/E Datasets
Initialize the Target and Distribution Zone CSIs
Review HOLDDATA
Apply the Base Code and Cumulative Maintenance to the Target Libraries
Accept the Base Code to the Distribution Libraries.
2-2
Part 4: Configure Xpediter/CICS
Installation of Enterprise Common Components (ECC) libraries is a required part of the
Xpediter/CICS installation process. Compuware Shared Services is a major part of ECC.
The most current release of ECC is provided in SMP/E installation format on separate
media. It includes a number of enhancements over previous Shared Services releases.
• A copy of the most current version of the Enterprise Common Components Installation and
Customization Guide is included on the ECC media. If you do not have your copy and
are a registered user of the Compuware Go (FrontLine) support web site at
(http://go.compuware.com), you can download a copy from there.
Follow the instructions in the Enterprise Common Components Installation and Customization
Guide and perform all the procedures applicable to Xpediter/CICS to install Enterprise
Common Components.
Note: Xpediter/CICS requires Compuware Shared Services Release 8.8 or above.
License Management System
Compuware provides the License Management System (LMS) to help manage access to
Compuware’s products at your site. The LMS includes several components that together
allow you to establish, maintain, diagnose, and upgrade access to the Compuware
products licensed by your enterprise.
Install LMS from the Enterprise Common Components (ECC) installation media.
Separately, via e-mail you receive a License Certificate for Xpediter.
IMPORTANT:
Xpediter/CICS operation requires these steps:
1. Ensure that the Compuware License Management System has been installed from the
ECC installation media.
Refer to the Compuware Enterprise Common Components Installation and Customization
Guide for installation procedures. This step is only necessary for a first-time install of
LMS or when upgrading the License Management System itself.
2. Import the License Certificate into your License File.
3. Establish and update the Runtime License Management System by running the
program LMSINIT.
Refer to the “License Certificate Import Checklist” section in the Compuware License
Management User/Reference Guide for detailed instructions.
Part 1: Initialize Installation Environment
Step 1. Create Global Zone CSI
A valid SMP/E Global Zone CSI configured for Compuware software is required. If you
need to create an SMP/E Global Zone CSI, you can use the sample JCL provided in the file
create_smpe_global.txt. Follow the instructions in the comments of the sample JCL to
customize the batch job, then submit it to create an SMP/E Global Zone CSI.
2-3
Step 2. Receive From Network
Note: If your order contained multiple products, this step may have already been
performed. This step is only required once per order because the smpe_receive job
receives everything that was ordered into the specified Global Zone.
The most common Receive From Network installation is directly to the mainframe, but
not all sites can.
• If you are able to do a Receive From Network directly to your mainframe, you can use
the sample JCL attached to the product order e-mail in the file named
smpe_receive.txt to facilitate an SMP/E Receive From Network. Follow the
instructions in the comments of the sample JCL to customize the batch job, then
submit it to perform the RECEIVE. Note that input within this job is CaSe SEnSiTiVE.
• If you are unable to do a Receive From Network directly to your mainframe, follow
the instructions in “Tar File SMP/E Receive” on page 2-56 before proceeding. That
section is applicable only if you are not performing an SMP/E Receive From Network
directly to your mainframe.
Step 3. Copy Installation Dialog File from USS to z/OS
Compuware provides an ISPF SMP/E installation dialog in one of the Unix System
Services (USS) files created by the Receive From Network batch job. Customize and
submit the JCL below to copy that install file to your z/OS system.
Figure 2-1. Sample JCL to Copy Installation Dialog File
//jobname JOB (account),'programmer-name',NOTIFY=&SYSUID,
//
MSGLEVEL=(1,1),MSGCLASS=?,CLASS=?,REGION=0M
//*********************************************************************
//* This job will copy the install file to a dataset that will
*
//*
be customized to complete the SMP/E install.
*
//*
*
//*
@@@@@> INPUT WITHIN THIS JOB IS CaSe sENsiTivE. <@@@@@@
*
//*
*
//* NOTES:
*
//* 1 - Update the jobcard as required. (REGION=0M is recommended.)
*
//* 2 - The PATH='/temp/nts/#######/SMPRELF' on the SMPDIR DD must
*
//*
point to the directory that contains the install file.
*
//*
Change the '/temp/nts' portion to what was used when you
*
//*
customized the PATH= variable on the SMPNTS DD in the
*
//*
Receive From Network JCL. Change the ####### to the
*
//*
id= number located on the PACKAGE statement in the Receive
*
//*
From Network JCL.
*
//* 3 - Change ???????? to the SMP/E dataset prefix you used when
*
//*
you customized the Receive From Network JCL. This should be
*
//*
the same as the dataset name prefix used for your SMP/E
*
//*
Global CSI.
*
//* 4 - Examine the name= value. The F0 qualifier references the
*
//*
English version of the installation dialog. For the Japanese *
//*
version of the dialog, change the F0 qualifier to F99.
*
//*********************************************************************
//SMPER1 EXEC PGM=GIMUNZIP,REGION=0M
//SMPDIR
DD PATHDISP=KEEP,PATH='/temp/nts/#######/SMPRELF'
//SMPOUT
DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUT3
DD UNIT=SYSALLDA,SPACE=(6160,(0230,0760))
//SYSUT4
DD UNIT=SYSALLDA,SPACE=(6160,(0230,0760))
//SYSIN
DD *
<GIMUNZIP>
2-4
<ARCHDEF
name="IS.PROD.XD.V090300.CPWR.MMXD930.F0.pax.Z"
replace="YES"
newname="????????.MMXD930.INS">
</ARCHDEF>
</GIMUNZIP>
//
The ISPF Installation JCL Customization Facility uses screens to gather your installation
information. It then uses that information to build the jobs needed to complete the
SMP/E installation.
Step 1. Make Note of HLQ, Global Zone CSI, and Installation File Name
The installation process utilizes System Modification Program Extended (SMP/E). For
more information about this type of installation, consult the IBM SMP/E Reference or the
IBM SMP/E User’s Guide.
In using Receive From Network (RFN) to receive and install this product, the following
steps should have already been performed:
1. Using JCL provided with the order of this product, you should have allocated and
initialized an SMP/E Global Zone Consolidated Software Inventory (CSI) that will be
used during this install. Optionally, you may have had an SMP/E Global Zone CSI
already prepared for Compuware products.
Make a note of the high-level qualifier (HLQ) you specified when creating the CSI:
__________________________________________________________________________
Make a note of the full Global Zone CSI name:
__________________________________________________________________________
2. Using JCL provided with the order of this product, you should have performed an
SMP/E Receive From Network for the product(s) ordered. The sample JCL provided in
“Step 3. Copy Installation Dialog File from USS to z/OS” on page 2-3 included
instructions on locating the installation file and a sample job that must be run to
copy the installation file to your z/OS system.
After running the job, make a note of the installation file name:
__________________________________________________________________________
Step 2. Select Installation Components
The ISPF Installation JCL Customization Facility uses screens to gather your installation
information. It then uses that information to build the jobs needed to perform the SMP/E
installation.
Note: Slight variations in the following procedure may exist depending on the format in
which you received the product.
Begin the process of installing products using the ISPF Installation JCL Customization
Facility as follows:
1. Invoke the installation facility for the Compuware Xpediter/CICS product by
entering the TSO EXECUTE command with the dataset name of the installation
library followed by $$XBEINS. For example:
TSO EX 'hlq.MMXD930.INS($$XBEINS)'
2-5
where hlq is the high-level qualifier you entered when transferring files to the
mainframe. The exact dataset name can be found in the notes you made in “Step 1.
Make Note of HLQ, Global Zone CSI, and Installation File Name” on page 2-4.
The SMP/E Installation JCL Customization Facility screen (Figure 2-2) is displayed.
Figure 2-2. Selecting Components to Install
Compuware Xpediter RFN - ProdID XD090300
SMP/E Installation JCL Customization Facility






Command ==>
Place an "S" by one or more of the following components to select for install
JCL customization and press ENTER.
FMID
Status
Xpediter/CICS 09.03.00
_
_
_
_
_
_
CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
5.2
5.1
4.2
4.1
3.2
3.1
Modules
Modules
Modules
Modules
Modules
Modules
Press PF1 for help,
RMXD930
QMXD930
PMXD930
OMXD930
NMXD930
MMXD930
END to exit.
2. Type an S to the left of each component you want to install.
3. Press Enter. To indicate your choices, the word SELECTED will be displayed in the
Status column next to each component chosen.
4. To modify a selection, add or delete the S to the left of the component.
5. When you are satisfied with your selections, press Enter again to start the JCL
customization process. The screen shown in Figure 2-3 is displayed.
Step 3. Specify Installation Environment Information
Note: Depending on your installation choices, you may not see all of the screens
documented herein.
2-6
Figure 2-3. Installation Environment Screen







Command ==>
Customizing:
Xpediter/CICS - CICS TS 5.1 Modules
Please complete the following:
- Do you want to enter SMS parameters?
- DASD unit:
- DASD volser (optional):
- SMP/E work unit:
- Global SMP/E dataset high-level qualifier:

NO
SYSDA
SYSDA
CPWR
Note: The Global SMP/E dataset high-level qualifier
must match the value in the Receive From
Network job.
Press ENTER to continue, PF1 for help, or END to return to previous panel.
This screen prompts you to enter information about the installation environment. Notice
that the names of the components selected for installation are listed below the
Command prompt. Those names will remain there during the rest of this procedure.
1. Specify installation information as follows:
Do you want to enter SMS parameters?
If you specify YES in the SMS Parameters field, you will be prompted to enter SMS
(Storage Management Subsystem) parameters on the next screen. Depending on
your site’s SMS installation options, default SMS parameters may be supplied
when datasets are being allocated during execution of the job. If so, or if you do
not want to specify SMS parameters, enter NO. Otherwise, enter YES to supply or
override the SMS parameters. The default value is NO.
DASD unit
Enter a valid DASD unit name. The value of this field will be used in the UNIT=
parameter of the DD statements that allocate non-VSAM libraries and datasets.
The default value is SYSDA.
DASD volser
This field is optional. If a volume is specified, SMP/E will use it as the target for
library and dataset allocation.
SMP/E work unit
Enter the name of a DASD unit to use for allocating SMP/E work files. The default
value is SYSDA.
Global SMP/E dataset high-level qualifier
Enter a value to be used for generating the names of the SMP/E system datasets.
These datasets include SMPLOG, SMPPTS, SMPTLIB, and the Global Consolidated
Software Inventory (CSI). The HLQ name can be found in the notes you made in
“Step 1. Make Note of HLQ, Global Zone CSI, and Installation File Name” on page
2-4.
Notes:
• Due to limits on the length of the DSPREFIX parameter (used to build the
SMPTLIB names for SMP/E RELFILES), this field cannot be longer than 26
characters.
2-7
• To prevent possible conflicts, Compuware strongly recommends that all
Global zone reserved solely for Compuware products. Target and
distribution zones cannot be shared.
2. Press Enter to continue.
Step 4. Specify SMS Parameters
If, in the previous step, you specified NO in the SMS Parameters field, you can skip
this step.
The screen shown in Figure 2-4 was displayed when you pressed Enter in the previous
step.
Figure 2-4. Specifying SMS Parameters









Command ==>
Customizing:
Enter any or all of the following SMS parameters:
Data class:
Storage class:
Management class:
1. Specify the data class, storage class, and/or management class parameters for the SMS
operating environment as follows:
Data Class
Specify the eight-character data class name for SMS.
Storage Class
Specify the eight-character storage class name for SMS.
Management Class
Specify the eight-character management class name for SMS.
Note: Installation defaults are not displayed on this screen. They will be applied
during execution of the SMP/E jobstream generated by this procedure. If your
site does not supply defaults or you wish to override the supplied defaults,
enter the desired SMS parameters on this screen.
2-8
Step 5. Specify Global CSI Dataset Name
step.
Figure 2-5. Specifying Global CSI Dataset Name










Command ==>
Customizing:
The following dataset name will be used for the global CSI:
CPWR.CSI
If you do not want to use this CSI name, type in a new CSI name
...or...
Erase the field and press ENTER to set it to the default.
The dataset currently exists.
Enter the DSN for the existing global CSI as follows:
1. Verify that the global CSI dataset name is correct. If necessary, change the name to
that found in the notes you made in “Step 1. Make Note of HLQ, Global Zone CSI,
and Installation File Name” on page 2-4.
2. Press Enter.
Step 6. Specify Jobcard Information
step. It prompts you for job card information.
2-9
Figure 2-6. Entering Job Card Information








Command ==>
Customizing:
Enter job card information:
//$$$$$$$$ JOB ('ACCTINFO'),'XPEDITER XD090300',
//
CLASS=L,MSGCLASS=X,NOTIFY=&SYSUID
//*
//*
OPTIONAL JES PARAMETER CARD GOES HERE
//*
NOTE: The class selected MUST allow enough CPU time for long-running jobs.
APPLY and ACCEPT jobs can easily exceed 5 CPU minutes each.
1. Specify the job card information for the ISPF Installation JCL Customization Facility
by updating the supplied model job card to follow your site standards. You may enter
up to five lines of job information.
The installation facility will set the $$$$$$$$ value equal to the member name of
each job created. You also have the option of specifying the job name using the
format xxxxxxx$ or xxxxxxxx, where the x’s are whatever name you choose. If you set
it to xxxxxxx$, the installation facility will set the job name for each job to xxxxxxx
and append a number to it. A letter will be appended for jobs 10 and above. If you set
it to xxxxxxxx, the installation facility will use the specified name for all jobs created.
Note: The job class specified must allow enough CPU time for long-running jobs.
Step 7. Specify SMP/E High-Level Qualifiers
The screen shown in Figure 2-7 on page 2-10 was displayed when you pressed Enter in
the previous step. It prompts you for the SMP/E high-level qualifiers of the components
previously selected for installation. The area listing the high-level qualifiers may be
scrollable, as indicated by More: +.
2-10
Figure 2-7. Specifying SMP/E High-Level Qualifiers




Command ==>
Customizing:
Enter the following information:
More:









+
SMP/E dataset high-level qualifier: CPWR.QMXD930
Note: If a high-level qualifier is longer than 28 characters, the installation facility is not
able to generate a default dataset name for the target and distribution zones. You
can either change the high-level qualifier entered, or manually modify the zone
dataset names to valid lengths.
1. Specify the high-level qualifiers as applicable for your installation as follows:
Component-Specific Modules SMP/E Dataset High-level Qualifier
Enter a value to be used in generating names of component-specific datasets,
including target and distribution zone CSIs, and their respective non-SMP/E
target and distribution libraries. The value entered cannot exceed 28 characters.
2. Press Enter.
Step 8. Specify Target and Distribution Zones
The screen shown in Figure 2-8 on page 2-11 is an example of what was displayed when
you pressed Enter in the previous step.
Note: To prevent possible conflicts, Compuware strongly recommends that all
Compuware products and components distributed via SMP/E share a single Global
zone reserved solely for Compuware products. Target and distribution zones
cannot be shared.
2-11
Figure 2-8. Specifying Target and Distribution Zones










Command ==>
Customizing:
Enter the following information for: Xpediter/CICS - CICS TS 5.1 Modules
Distribution zone name:
QXD930D
DZone CSI dataset name:
CPWR.QMXD930.DZONE.CSI
DZone CSI currently does not exist
Target zone name:
QXD930T
TZone CSI dataset name:
CPWR.QMXD930.TZONE.CSI
TZone CSI currently does not exist
1. Specify the target and distribution zone information as follows:
Distribution Zone Name
Specifies the name of the SMP/E distribution zone used by the product to be
installed. The name you specify must be unique within the global zone.
DZone CSI Dataset Name
Specifies the dataset name of the SMP/E distribution zone used by the product to
be installed.
DZone CSI currently exists/does not exist
Indicates whether the distribution zone CSI dataset exists.
Target Zone Name
Specifies the name of the SMP/E target zone used by the product to be installed.
The name you specify must be unique within the global zone.
TZone CSI Dataset Name
Specifies the dataset name of the SMP/E target zone used by the product to be
installed.
TZone CSI currently exists/does not exist
Indicates whether the target zone CSI dataset exists.
2. Press Enter.
Step 9. Specify Installation-Dependent Libraries
step.
2-12
Figure 2-9. Specifying Installation-Dependent Libraries






Command ==>
Customizing: Xpediter/CICS 09.03.00
Enter the following SMP/E library names from your environment:
LE link-edit library: CEE.SCEELKED
TCP/IP RENT library: TCPIP.SEZARNT1
TCP/IP misc. library: TCPIP.SEZACMTX
TCPIP.SEZATCP
USS library:
SYS1.CSSLIB
The standard defaults are: CEE.SCEELKED
TCPIP.SEZARNT1
TCPIP.SEZACMTX
TCPIP.SEZATCP
SYS1.CSSLIB
1. Enter the names of the following libraries as they are defined at your installation:
LE Link Edit Library
Specifies the Language Environment link-edit library.
TCP/IP RENT Library
Specifies the TCP/IP re-entrant library.
TCP/IP Misc. Library
Specifies the TCP/IP standard library.
USS Library
Specifies the Unix System Services library.
2. Press Enter.
Step 10. Verify Installation Information
When you pressed Enter in the previous step, the first of a series of confirmation screens
was displayed. On each confirmation screen you have the following choices.
• To accept the information on the screen, press Enter.
• To correct a particular parameter, press End to return to the associated entry screen.
After you accept the information on each of the confirmation screens, the installation
process will continue.
Step 11. Process the JCL
The screen shown in Figure 2-10 was displayed when you pressed Enter the final time in
the previous step.
2-13
Figure 2-10. Confirming JCL Processing













SMP/E Installation JCL Customization Facility - Verification Screen
Command ==>
Customizing:
THIS IS THE LAST PANEL BEFORE CUSTOMIZATION BEGINS.
ENSURE THAT ALL VARIABLES ARE CORRECT BEFORE PRESSING ENTER.
Press ENTER to begin customizing the JCL.
1. Press Enter to start the processing that builds customized JCL members or press End
to cancel the installation.
When you press Enter, the progress of the JCL customization process is displayed in a
scrollable area on the screen. You can scroll up or down to view the list of jobs and
the members generated.
2. After the installation JCL has been created, press End. A screen is displayed informing
you that a parameter report has been generated (Figure 2-11). This report details the
JCL created and lists the parameters and execution information used during
installation.
Figure 2-11. Report Member Detailing JCL Processing




The following PDS member contains a report of all parameters used during
customization and a log of all JCL members created:
hlq.MMXD930.INS($$XBERPT)
Press ENTER to browse the report, END to exit.
3. If you want to browse the report at this time, press Enter. You can also examine the
report later by accessing the installation library report member shown on this screen.
4. Press End. The screen first displayed in Figure 2-2 on page 2-5 will be redisplayed,
showing a status of COMPLETE for each component (Figure 2-12 on page 2-14).
2-14
Figure 2-12. Displaying Completion Status

Command ==>
JCL customization is complete for selected components.
See status column.
FMID
Status

_
S
_
_
_
_





CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
5.2
5.1
4.2
4.1
3.2
3.1
Modules
Modules
Modules
Modules
Modules
Modules
RMXD930
QMXD930
PMXD930
OMXD930
NMXD930
MMXD930
Press PF1 for help,
COMPLETE
END to exit.
5. Press End. The screen shown in Figure 2-13 will be displayed instructing you to refer
to the product installation guides to complete the installation process.
Figure 2-13. Final JCL Customization Screen



Note: To complete the installation of the selected component(s), return to the
appropriate Xpediter installation guide(s).
Press END to exit.
6. The processing of the ISPF Installation JCL Customization Facility is now finished.
Press End to exit.
Note: Compuware recommends you maintain availability to your customized install
library. Otherwise, it may be necessary to unload and recustomize the install
library from product or maintenance media to perform future maintenance.
There are six sample jobs for using SMP/E to install Xpediter/CICS. Use the dataset name
found in the notes you made in “Step 1. Make Note of HLQ, Global Zone CSI, and
Installation File Name” on page 2-4.
Installation JCL members are described in the following table.
Table 2-1.
Installation JCL Members
Member
Function
$01GLCSI
Unnecessary for a Receive From Network-initiated Install.
$02TZCSI
Performs the allocation of the zones and related SMP/E datasets.
$03ALDSN
Initializes the CSIs with the required entries.
Table 2-1.
2-15
Installation JCL Members (Continued)
Member
Function
$04RECV
Unnecessary for a Receive From Network-initiated Install.
$05APPLY
Applies the base code and maintenance.
$06ACCPT
Accepts the base code.
Note: Except where otherwise noted, the return code from all jobs should be zero.
Step 1. Allocate Libraries and SMP/E Datasets
This step allocates target and distribution zone CSIs as well as product-specific SMP/E
datasets. These datasets include the product-specific load libraries.
The installation facility has created a job called $02TZCSI that allocates the required
libraries and datasets.
Note: The space allocations used are based on 3390 DASD. If you use 3380 DASD, you
may decide to change the BLKSIZE for the load library and APF-authorized load
library to 6356 for a better blocking factor.
1. Review the job $02TZCSI for any necessary changes.
2. Submit the job to start the allocation process.
Step 2. Initialize the Target and Distribution Zone CSIs
This step initializes the Xpediter/CICS target and distribution zone CSIs. The installation
facility has created a job called $03ALDSN that performs the initialization.
1. Review the job $03ALDSN for any necessary changes.
Note: Before you submit this job, make sure the job submitted in the previous step
has completed.
2. Submit the job to start the initialization process. This job uses REP statements rather
than ADD statements to simplify rerunning the job. It is normal to receive a return
code of 4 with the following messages:
GIM56501W The aaaaaa subentry was added rather than replaced
because it did not exist.
GIM27701W aaaaaaaa ENTRY bbbbbbbbbbbbbbbbb does not exist. the replace
operation has been changed to an add.
Otherwise, the return code should be 0.
Step 3. Review HOLDDATA
At times, installing base code and maintenance requires additional actions that must be
performed after a PTF(s) is applied. In these cases, the PTF is identified as an exception
with:
++HOLD
and the HOLDDATA contains information on the additional actions you must perform to
completely implement the change. The HOLDDATA can be found in the SMPRPT output
from the RFN job.
2-16
CAUTION:
It is very important that you perform any HOLDDATA action. Failure to do so can
cause unpredictable results, including incorrect data and abends. It is possible that
the installation does not have any hold actions.
Step 4. Apply the Base Code and Cumulative Maintenance to the Target
Libraries
This step applies the Xpediter/CICS base code and cumulative maintenance to the target
zone. The installation facility has created a job called $05APPLY that performs the apply
process.
CAUTION:
Be sure to run $05APPLY in a job class suitable for long-running batch jobs.
Note: The default control statements apply the base FMID and all cumulative
maintenance, however you may wish to run an APPLY CHECK before applying the
software.
1. Review the job $05APPLY for any necessary changes.
2. Submit the job to start the apply process.
Note: While an APPLY CHECK may end with RC=0, a successful APPLY will end with
RC=4 or less. The APPLY CHECK, unlike the actual APPLY, only checks the SMP/E
environment and does not invoke any external utilities, such as IEBCOPY or the
linkage editor.
Step 5. Accept the Base Code to the Distribution Libraries
This step accepts the Xpediter/CICS base code to the distribution libraries.
The installation facility has created a job called $06ACCPT that accepts the base code
into the distribution libraries.
CAUTION:
Be sure to run $06ACCPT in a job class suitable for long-running batch jobs.
Note: The default control statements accept the base FMID, however you may wish to
run an ACCEPT CHECK before accepting the software.
1. Review the job $06ACCPT for any necessary changes.
2. Submit the job to start the accept process.
Note: An ACCEPT may end with a non-zero return code, even though the ACCEPT
CHECK ended with RC=0. This is because the ACCEPT may invoke external
utilities, such as IEBCOPY or the linkage editor, while the ACCEPT CHECK only
checks the SMP/E environment.
After the steps above have been completed, you must continue with the procedures in
“Part 4: Configure Xpediter/CICS” on page 2-17.
Note: If your site will be using Xpediter/Code Coverage, ensure all Xpediter/Code
Coverage SMP/E installation jobs have completed before configuring
Xpediter/CICS.
2-17
This part explains how to configure Xpediter/CICS for use at your site. Many of the steps
are optional, depending on whether your site wants to use a specific Xpediter feature or
is licensed for a particular Xpediter option.
Note: All dataset members referred to in this section can be found in the
CPWR.cMXD930.SMXDSAMP library, where c designates the CICS release:
•
•
•
•
•
•
M: CTS 3.1
N: CTS 3.2
O: CTS 4.1
P: CTS 4.2
Q: CTS 5.1
R: CTS 5.2.
Step 1. Prepare the ISPF Edit Macro (Optional)
XDUPDATE is an ISPF edit macro that can be used to automate the entry of site-specific
JCL parameters. Using this macro saves you from having to repeatedly type in the same
information and ensures your JCL parameters are always entered correctly.
To use the edit macro, first copy member XDUPDATE from the SMXDSAMP member (as
described in the Note above) into your CLIST library. Then enter your site-specific
information in the XDUPDATE macro. The macro includes instructions for entering the
information. Your CLIST library must be allocated to your ISPF session. You can verify
that your CLIST library is accessible to ISPF by entering the command TSO LISTA.
The edit macro can be used during Xpediter installation each time you are instructed to
edit JCL. To run it, first open the JCL member for editing. You can then look at the JCL
before any changes are made. Type XDUPDATE in the COMMAND field of the ISPF EDIT
screen and press Enter.
Step 2. Integrate Xpediter/CICS with MVS
In this step, which must be performed, you will define an Xpediter/CICS APF authorized
library to MVS by updating the MVS APF authorized library list. You will also define the
Xpediter Service Provider program properties to MVS and define it as an MVS subsystem.
Notes:
• The Xpediter/CICS APF authorized library should not be included in the operating
system’s link list. This will allow you to protect the library and ensure only approved
users can execute the Xpediter Service Provider.
• If you will be using DBCTL support, do not define the Xpediter/CICS APF authorized
library as a PDSE, because IMS does not support PDSEs in steplibs.
Update the MVS APF Authorized Library List
1. For sites using dynamic lists, issue the following MVS operator command to update
the MVS APF authorized library list:
SET PROG=xx
where xx is the suffix of the PROGxx member containing the Xpediter/CICS
APF authorized library.
2. For sites using static lists, perform one of the following to update the MVS APF
authorized library list:
2-18
– Copy the contents of the Xpediter/CICS APF authorized library dataset to an
existing MVS APF authorized library. The default dataset name is
CPWR.cMXD930.SMXDAUTH where c designates the CICS release.
Note: The Xpediter/CICS APF authorized library is backward compatible. For
more information, see “Step 6. Initialize the Xpediter Service Provider” on
page 2-26.
– Use an MVS monitor with APF authorized library update capabilities to
dynamically update the MVS APF authorized library list.
– Schedule an IPL. Perform the next step before you IPL.
Define the Xpediter Service Provider Program Properties to MVS
1. Add program DBUGSTC to the MVS program properties table (PPT) member in
SYS1.PARMLIB using either of the following methods:
– Copy SMXDSAMP member SCHEDXD to SYS1.PARMLIB, then add XD to the
SCH=(xx) directive of IEASYSxx in SYS1.PARMLIB. For example, change SCH=00
to SCH=(00,XD).
– Append SMXDSAMP member SCHEDXD to your SCHEDxx member in
SYS1.PARMLIB.
2. Update the MVS PPT by issuing one of the following MVS operator commands:
where xx is the suffix of the SCHEDxx member used during the last IPL
SET SCH=(xx,XD) and XD is the suffix of the SCHEDxx member which contains the MVS PPT
entry for DBUGSTC.
SET SCH=xx
where xx is the suffix of the SCHEDxx member which contains the MVS
PPT entry for DBUGSTC.
Define the Xpediter Service Provider as an MVS Subsystem
Add an MVS subsystem definition to SYS1.PARMLIB using either of the following
methods:
• Copy SMXDSAMP member IEFSSNXD to SYS1.PARMLIB, then add XD to the
SSN=(xx) directive of IEASYSxx in SYS1.PARMLIB. For example, change SSN=00 to
SSN=(00,XD).
• Append SMXDSAMP member IEFSSNXD to your IEFSSNxx member in SYS1.PARMLIB.
You are not required to perform an IPL to use the Xpediter Service Provider. If an MVS
subsystem entry has not already been defined, Xpediter/CICS will build one dynamically
during initialization.
Notes:
• Make sure the MVS Performance Group used by the Xpediter Service Provider is
above CICS and below VTAM to prevent runtime abends.
• For additional information, refer to Chapter 7, “Xpediter Service Provider”.
Step 3. Update the CICS Resource Definitions
This step explains how to update your site’s CICS resource definitions.
Observe the following general considerations:
• Some Xpediter/CICS control blocks are now GETMAINed in accordance with the
TASKDATALOC specified for the transaction being tested. Xpediter’s use of below the
2-19
line storage can be reduced by specifying TASKDATALOC=ANY for your eligible
transactions.
• Xpediter/CICS does not support programs with RELOAD=YES in the PPT entry.
Remove this option for programs that you plan to debug with Xpediter.
• Do not define temporary storage queues with an XP prefix as remote.
• In DFHSITxx, do not specify SRT=NO.
• Unless the documentation packaging utility has been disabled by changing the value
of global parameter RECREATE to NONE, either in DBUGGBL or as a global table
override, specify SPOOL=YES as a SIT parameter.
• If your site will be initializing Xpediter/CICS using PLT startup, observe the following
conditions:
– Add the Xpediter/CICS program DBUGPPM2 to the PLT program initialization
(PLTPI) table.
– Shutdown of Xpediter/CICS via the PLT is supported. To enable this support, add
program DBUGPLTS to the PLTSD table. 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. Do not put
DBUGPPM2 in the PLTSD table.
Notes:
• Modification of the PLTSD will be required if the Xpediter Script Facility or File
Utility Audit Trail is enabled later in this installation procedure.
• When Xpediter/CICS starts the DBPA transaction during PLT post-initialization, the
userID assigned is the same as the userID assigned to the CPLT transaction.
• Compuware highly recommends the use of RENTPGM=PROTECT.
Using RDO to Update Resource Definitions
1. Submit the supplied JCL to batch the required CEDA transactions. Refer to Table 2-2
and use the SYSIN in resource members CSDXDFIL and CSDXDTRN. Also include
CSDXDPRG if autoinstall will not be used to install Xpediter programs at your site.
Notes:
– If your site is not using Xpediter/Code Coverage, edit the CSDXDFIL member
and comment out the definitions for XVTCEXTR (the Code Coverage extract
dataset), XVTCEXTJ (the Code Coverage JCL template dataset), and XVTCSPEC
(the Code Coverage Specifications Archive dataset).
– If your site is using BAS, you may use the furnished JCL member CSD2BAS to
create an input file for the BATCHREP view in the CICSPlex SM End User
Interface.
– LSRPOOLNUM or LSRPOOLID may be specified as appropriate. Be aware that for
file control update requests, CICS does not support the use of
LSRPOOLNUM(NONE) or LSRPOOLID(NONE) while Transaction Isolation is
active. Beginning with CICS TS 4.1 this restriction is enforced with an AFDK
abend.
2. If your site is using RDO to define DB2 resources, use the SYSIN in resource member
CSDXDDB2 to batch the CEDA transactions that define the entries required for the
DB2 File Utility. Refer to “Step 16. Implement Support for the DB2 File Utility
(Optional)” on page 2-35.
3. If your site is using Xpediter’s CICSPlex TOR support, use the SYSIN in resource
member CSDXDDYN to batch the CEDA transactions that define the entries required.
2-20
Refer to “Installation in a CPSM Dynamic Routing Environment” on page 10-2.
4. The Xpediter/CICS resource group created in this step must be added to a CICS group
list, which in turn is specified in the system initialization parameter GRPLIST.
5. CSDXDFIL contains an ENQMODEL new in Release 8.1. Ensure that this ENQMODEL
definition is added to all CICS regions that share the same Xpediter/CICS Profile
Dataset.
Note: If you change any of the Xpediter transaction IDs before submitting the JCL, they
must also be changed in the Xpediter/CICS global table.
Table 2-2.
Resource Members
SYSIN Member for JCL Member DBCRDO or CSD2BAS
CSDXDFIL
CSDXDPRG (omit if using autoinstall for Xpediter programs)
CSDXDTRN
CSDXDDB2 (DB2ENTRY and DB2TRAN entries for DB2 sites only)
CSDXDDYN (if using Xpediter’s CICSPlex TOR support)
Program Autoinstall
Xpediter/CICS fully supports autoinstall for user programs, mapsets, and partitionsets.
If your site has elected to autoinstall Xpediter programs, you must make the
following changes to the installation process:
• Be sure to omit SYSIN member CSDXDPRG. Member CSDXDTRN contains a single
program definition for program DBUPGADX, to install the Xpediter/CICS Program
Autoinstall Exit program. All other Xpediter/CICS programs are autoinstalled by this
exit.
• DBUPGADX is the Xpediter/CICS autoinstall exit for programs. DBUPGADX is
designed to work in conjunction with any current Program Autoinstall Exits, so your
Autoinstall Exit programs do not need to be changed.
• To implement the Xpediter/CICS Program Autoinstall Exit, alter the system
initialization table (SIT) parameters PGAIEXIT and INITPARM as follows by either
modifying the SIT or by using SIT overrides:
– PGAIEXIT
To ensure that the Xpediter/CICS exit gains control before your normal Program
Autoinstall Exit, change or override this parameter to PGAIEXIT=DBUPGADX. If
you are currently using program autoinstall, take your current exit name and
substitute it for DFHPGADX in the INITPARM parameter added below.
– INITPARM
Add DBUPGADX='DFHPGADX' to your existing INITPARM parameters. For
example, you would change or override INITPARM=(current string) to
INITPARM=(DBUPGADX='DFHPGADX',current string). If you do not currently use
INITPARM, code INITPARM=(DBUPGADX='DFHPGADX').
DFHPGADX is the Program Autoinstall Exit that will be linked to if no program
name matches are found in DBUPGADX. Change the string DFHPGADX to the
name of the exit that you want to have control.
As mentioned above, if you are already using program autoinstall, you should
replace DFHPGADX with the string previously used on your PGAIEXIT
parameter. If your old SIT parameters were PGAIEXIT=OLDPAEXT and
INITPARM=(current string), you would change or override them to
PGAIEXIT=DBUPGADX and INITPARM=(DBUPGADX='OLDPAEXT',current string).
2-21
You may also change this added parameter to DBUPGADX='LAST'. This would
indicate to DBUPGADX that no other exits are called if the program being
autoinstalled is not an Xpediter/CICS program.
Notes:
– If you omit or miscode the INITPARM, the default action is to link to
DFHPGADX.
– If PGAIEXIT=DBUPGADX and INITPARM=(DBUPGADX='OLDPAEXT'), where
OLDPAEXT is written in a high-level language, IGZINSH (an IBM-supplied
program) needs to be pre-installed in the CICS region.
– If Xpediter/CICS is not initialized in the CICS region when a user tries to start an
Xpediter session, Xpediter will invoke the initialization process. If the user is
using the Xpediter/Eclipse interface, the program definitions for DBUGSOCK and
XDPIMIRS must be already installed in the CICS region. If Xpediter/Eclipse is
used at your site, uncomment the DBUGSOCK and XDPIMIRS definitions
supplied in the SMXDSAMP member CSDXDTRN.
Setting Exit Program Priorities
If you have more than one XPCTA exit program that sets PCUE_BRANCH_ADDRESS (the
resume address parameter), you must decide on the order of priority. The last exit
program enabled is the last to get control and is also the last to move the address into the
resume address field. The program only branches to the last resume address. You must
ensure that all exit programs correctly check and update the return code fields. The
XPCTA sample (DFH$PCTA) must be modified to be used with multiple XPCTA exit
programs, because it does not check for return codes from any previous exits.
Note: In order to trap CICS abends, Xpediter/CICS must be the last XPCTA exit program
to change the resume address.
If you have more than one XPCFTCH exit program that sets PCUE_BRANCH_ADDRESS
(the resume address parameter), you must decide on the order of priority. The last exit
program enabled is the last to get control and is also the last to move the address into the
resume address field. The program only branches to the last resume address. You must
ensure that all exit programs correctly check and update the return code fields.
Note: In order to trace, monitor, or code cover CICS transactions, Xpediter/CICS must be
the last XPCFTCH exit program to change the resume address unless the last exit is
for Xchange/CICS.
Step 4. External Security Considerations
To help you to set up security groups for external security, the following tables list the
Xpediter/CICS and Xpediter/Code Coverage transactions and their uses. The tables also
identify started transactions and provide recommended external security settings.
The terms used in the “Security Recommended” column are defined as follows:
• NO - All users of Xpediter, including the userID associated with PLTPI programs,
should be permitted to execute these transactions.
• YES - These transactions provide capabilities beyond the needs of a typical end user
of Xpediter. Access may be limited to those responsible for installation,
configuration, etc.
2-22
• EITHER - No recommendation.
Table 2-3.
Xpediter/CICS Transactions
Started
Security
Recommended
Trans
Program
Use
DBFL
DBUGFILE
File utility
•
NO
DBPA
DBUGPPM2
PLT startup
•
NO
DBXG
DBUGSP00
Remote traps
•
NO
DMAP DBUGMAPS
Display BMS maps
EITHER
NEWC DBUGNEWC
Newcopy (PHASEIN) programs
EITHER
XACH
CWDEMACH Demo program
EITHER
XASL
CWCEEASM
Demo program
EITHER
XASM
CWDEMASM Demo program
EITHER
XCB2
CWDEMCB2
Demo program
EITHER
XCBN
CWDEMCBN Demo program
EITHER
XCCC
CWDEMC
Demo program
EITHER
XCCH CWDEMCCH Demo program
EITHER
XDBP
DBUGDBPA
Process DBPA input
YES
XIVP
DBUGINST
Installation Verification Program
EITHER
XLGI
DBUGLOGC
File Utility logging
XLOG
DBUGLOGM
Activate, terminate, or switch datasets
YES
XPCH
CWCEMPCH
Demo program
EITHER
XPCI
DBUGCRTL
Remote Operations Command Interface (ROCI)
XPED
DBUGSP00
Access Xpediter
XPFS
DBUGCSFS
SLS Dataset Services
XPGD
XDPIMIRS
Secure Xpediter/CICS access from Xpediter/Eclipse
EITHER
XPLE
CWDEMPE
Demo program
EITHER
XPLI
CWDEMPL
Demo program
EITHER
XPN0
DBUGEND0
Automatic session termination
XPNC
DBUGCRTL
Newcopy (PHASEIN) program from batch
XPND
DBUGEND
Automatic session termination
XPOF
DBUGDBXX
Shutdown Xpediter
EITHER
XPRT
DBUGSP00
Access Xpediter
EITHER
XPSP
DBUGSP00
Access Xpediter with system facilities
YES
•
•
NO
EITHER
EITHER
•
•
NO
NO
EITHER
•
NO
XPWD DBUGWRAM Disable Xpediter’s dynamic transaction routing exit
YES
XPWI
DBUGWRAM Enable Xpediter’s dynamic transaction routing exit
YES
XREL
DBUGNEWC
Internal Xpediter transaction
NO
XROI
DBUGROIC
Interface to License Management System
XSIT
DBUGSIT
Process global overrides
YES
XSOC
DBUGSOCK
Xpediter/Eclipse connections
NO
XSTA
DBUGSTA0
Access Xpediter in multiple AORs
EITHER
XZCH
CWDEMZCH Demo program
•
NO
EITHER
Table 2-4.
2-23
Xpediter/Code Coverage Transactions
Trans Program
Use
XVCC XVTCMGR
Code Coverage definition update
XVKP
Internal Code Coverage transaction
XVTCEXTR
Started
Security
Recommended
YES
•
NO
XVSC XVTCMGR
Code Coverage definition update
YES
XVSI
Process global overrides
YES
XVTCSIT
XVTQ XVTCCCIN
Internal Xpediter/Code Coverage quiesce tran ID
•
NO
CAUTION:
If external security checking is enabled (SEC=YES and XPCT=YES in the CICS System
Initialization Table) for the started transactions identified in Table 2-3 and Table 2-4,
CICS calls the external security manager using the default CICS resource class name
CICSPCT prefixed with A or B. This is done to verify that the userID associated with
the transaction is authorized to use started transactions. Please refer to the CICS
System Definition Guide and your external security manual for more information.
Incorrect security settings for the XPFS transaction can cause a NO SOURCE
AVAILABLE condition for all program listings accessed via Shared Directory or DDIO
datasets and can also cause the SLS Datasets (9.L) screen to function improperly.
Incorrect security settings for the XREL transaction can cause erroneous failure of
the new copy function for programs where breakpoints have been removed.
Incorrect security settings for the XVKP transaction can cause failure of periodic
extract of data for Xpediter/Code Coverage.
The following table lists the results of assigning user security to Xpediter/CICS started
transactions.
Table 2-5.
User Security for Xpediter/CICS Started Transactions
Trans
Program
Use
UserID
DBFL
DBUGFILE
File utility
Assigned the userID of the terminal accessing the file utility.
DBPA
DBUGPPM2
PLT startup
Assigned the same userID as the CPLT transaction.
DBXG DBUGSP00
Remote traps
Assigned the userID of the trapping terminal.
XLGI
DBUGLOGC
Activate, terminate,
or switch logging
Assigned the userID of the terminal accessing transaction
XLOG.
XPCI
DBUGCRTL
Remote Operations
Command Interface
(ROCI)
Refer to “Step 26. Install and Customize the Remote
Operations Command Interface (Optional)” on page 2-46
for security considerations.
XPFS
DBUGCSFS
SLS Dataset Services
Assigned the userID of the Xpediter/CICS initiator or
DFLTUSER. If initiated via PLTPI, assigned PLTPIUSR or the
CICS region userID.
XPGD XDPIMIRS
Xpediter/Eclipse
Refer to “Step 28. Install and Customize for
Xpediter/Eclipse (Optional)” on page 2-50.
XPN0
Automatic session
termination
Assigned the userID of the terminal at which it runs (when
started via autoinstall terminal delete).
XPND DBUGEND
Automatic session
termination
Same as XPN0.
XREL
Release held
programs
Runs when all breakpoints are removed from a program.
Assigned the userID of the terminal for which the
breakpoints were removed.
DBUGEND0
DBUGNEWC
2-24
Table 2-5.
User Security for Xpediter/CICS Started Transactions
Trans
Program
Use
UserID
XROI
DBUGROIC
Assigned the userID of the Xpediter/CICS initiator. If
Interface to License
initiated via PLTPI, assigned PLTPIUSR or DFLTUSER userID.
Management System
If initiated via terminal, assigned userID of the terminal.
Notes:
• If automatic session termination is performed via the XSNOFF global exit, XPN0 and
XPND must not be secured.
• When Xpediter/CICS starts the DBFL and XREL transactions internally, the current
userID will be propagated to either the DBFL or XREL transaction.
The following table lists the results of assigning user security to Xpediter/Code Coverage
transactions.
Table 2-6.
User Security for Xpediter/Code Coverage Started Transactions
Trans
Program
Use
UserID
XVKP
XVTCEXTR
Code Coverage autoDFLTUSER. If initiated via PLTPI, assigned PLTPIUSR or the
extract transaction
CICS region userID.
XVTQ
XVTCCCIN
Code Coverage
quiesce transaction
DFLTUSER. If initiated via PLTPI, assigned PLTPIUSR or the
CICS region userID.
Xpediter Service Provider Security
The delivery of the default Subsystem Security Exit (DBUGSSX) has changed, beginning
with Release 8.2. The default exit is now delivered with the load module name
DBUGSSXX in SMXDAUTH. Therefore, a Subsystem Security Exit will be used only if you
take action. If you need to use a Subsystem Security Exit, you can rename DBUGSSXX to
DBUGSSX or create your own customized version. An example SMP/E USERMOD to
rename the module is in member SSXXUMOD in SMXDSAMP.
If you are using an external security manager, such as RACF, at your site, you may need to
customize the Subsystem Security Exit (DBUGSSX) and/or define access rules to allow a
CICS address space to access the Xpediter Service Provider Subsystem. Use the sample JCL
provided in SMXDSAMP member DBCSSX (Figure 2-14 on page 2-25) to assemble and
link-edit DBUGSSX.
2-25
Figure 2-14. Sample DBUGSSX Assembly JCL Member (DBCSSX)
********************************* Top of Data *************************
//*====>INSERT JOBCARD HERE <===JOBCARD
//*********************************************************************
//ASM
EXEC PGM=ASMA90,
//
PARM=('LIST,OBJECT,TERM,LINECOUNT(58)')
//SYSTERM DD SYSOUT=*
//SYSLIB
DD DISP=SHR,DSN=SYS1.MACLIB
//
DD DISP=SHR,DSN=SYS1.MODGEN
//SYSLIN
DD DISP=(NEW,PASS),DSN=&&OBJLIB,
//
UNIT=SYSDA,SPACE=(CYL,(3,1))
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(3,1)),DISP=(,DELETE)
//SYSUT2
//SYSUT3
//SYSPUNCH DD DUMMY,DCB=BLKSIZE=80
//SYSIN
DD DISP=SHR,HERES SOME MORE
//
DSN=CPWR.cMXD930.SMXDSAMP(DBUGSSX)
<-- CHECK DSN
//*********************************************************************
//LINKEDIT EXEC PGM=IEWL,
//
PARM='LIST,XREF,MAP,RENT',
//
COND=((5,LT,ASM))
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSLIN
DD DISP=(OLD,DELETE),DSN=&&OBJLIB,
//
UNIT=SYSDA,VOL=REF=*.ASM.SYSLIN
//
DD *
ENTRY DBUGSSX
NAME DBUGSSX(R)
//SYSLMOD DD DISP=SHR,
//
DSN=CPWR.cMXD930.SMXDAUTH
<-- CHECK DSN
//
During Xpediter Service Provider Subsystem initialization, the optional DBUGSSX exit is
fetched from the Xpediter/CICS APF authorized library. DBUGSSX is called during
address space connect processing to determine whether the requester is authorized to
connect to the Xpediter Service Provider Address Space. If DBUGSSX is not available, all
CICS address space connections will be granted.
Without any customization, DBUGSSX performs a RACROUTE authorization check for
READ access against a model profile dataset resource class. The model profile dataset is
named XPEDITER.SUBSYS.ssid.cccccccc where ssid is the Xpediter Service Provider
Subsystem Identifier and cccccccc is the requester address space job or started task name.
Resource Rules
Generic resource rules apply to the DBUGSSX-generated resource names. For the most
complete protection, a site can define specific resource rules for each resource name that
may be generated, then only grant the desired access to those resources to selected
userIDs and groups (address spaces).
Another alternative is for a site to define a resource rule that denies all access by default
and is always applied unless some other, more restrictive, rule is applied. The rule would
be specified as XPEDITER.SUBSYS.** and defined as having no universal access
(UACC=NONE). No userIDs or groups would have READ access to it.
More specific resource rules could then be defined, allowing access on an individual
basis. In one possible scenario, a site that has CICS production processing regions with
job names of PRODxxxx and test processing regions with job names of TESTxxxx might
want to protect its production regions from use of the Xpediter Service Provider
Subsystem, while retaining the capability of using it in their test regions. To accomplish
this, first the site would define XPEDITER.SUBSYS.** with UACC=NONE and not grant
2-26
READ access to any userIDs or groups. Then XPEDITER.SUBSYS.*.TEST* would be defined
with UACC=NONE, and only selected userIDs and groups (address spaces) would be given
the necessary READ access.
With these rules, site security retains complete control over which address spaces are able
to use the Xpediter Service Provider Subsystem.
Step 5. Creating and Managing the Xpediter TP Configuration File
(TPCONFIG)
The Xpediter TP configuration file is required to provide various types of information to
the mainframe side of the Xpediter/CICS and Xpediter/Eclipse products. The Xpediter
Service Provider requires this dataset to identify all of the other Service Providers, in
other LPARs, that are to share CICSPlex information. Xpediter/CICS also requires this
dataset to identify all the CICS regions that should be contacted by the Batch Interface to
CICS NEWCOPY. For usage with Xpediter/Eclipse, see the documentation in the
Compuware Workbench Installation Guide.
If your configuration file is on shared DASD that can be accessed by all LPARS, then 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 Xpediter/Eclipse,
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.
The configuration file should have its access security set so that all users can read it, but
can be updated only by those to whom you have granted edit access.
The configuration file dataset 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 configuration file member is provided in the Xpediter/CICS sample
dataset (member name MBRTPCNF). The following is a summary of the steps needed to
create and use the configuration file:
1. Edit and submit the sample JCL member JCLTPCNF to allocate the configuration file
and copy the sample configuration member.
2. Customize the configuration member to your installation needs.
This dataset will be referred to as the TPCONFIG dataset in “Step 6. Initialize the Xpediter
Service Provider” below and in “Step 27. Install and Customize the Batch Interface to
Xpediter/CICS NEWCOPY (Optional)” on page 2-48.
Step 6. Initialize the Xpediter Service Provider
Before proceeding, make sure you have completed the procedures in “Step 2. Integrate
Xpediter/CICS with MVS” on page 2-17.
Releases of Xpediter prior to 7.3 do not support the Xpediter Service Provider. As shown
in Table 2-7, this release of Xpediter can only be used with this version of the Xpediter
Service Provider. For those sites using multiple releases of Xpediter/CICS, this release of
the Service Provider is backward compatible with Releases 9.2, 9.1, and 9.0 of
Xpediter/CICS.
Table 2-7.
Xpediter Service Provider Compatibility
Service Provider Version
Xpediter
Release
9.0
9.1
9.2
9.3
9.0
•
•
•
•
•
•
•
9.1
Table 2-7.
Xpediter
Release
2-27
9.0
9.1
9.2
9.2
9.3
•
•
9.3
•
1. Edit and enable SMXDSAMP member XDSSPROC as follows:
a. Make sure the Xpediter/CICS APF authorized dataset name in the STEPLIB DD
statement matches the name used at your site. The default is SMXDAUTH
member.
b. Make sure the SSID parameter value, which specifies the four-character
subsystem identifier for the Xpediter Service Provider subsystem, matches the
value of global parameter SUBSYS used at your site. The default is XDSS.
c. If you do not plan to share CICSPlex information across LPARs, then delete the
TPCONFIG DD statement and related parameters MEMBER and PORT from
XDSSPROC, delete parameters MEMBER and PORT from XDSSJCL, and skip the
rest of this substep.
The Xpediter Service Provider uses TCP to communicate to other Service
Providers. If you want this instance of the Service Provider to share CICSPlex
information with other Service Providers across LPARs, then customize the
dataset name in the TPCONFIG DD statement and the two related parameters,
MEMBER and PORT. Specify your TPCONFIG member name (from “Step 5.
Creating and Managing the Xpediter TP Configuration File (TPCONFIG)” on
page 2-26) in the XDSSPROC MEMBER parameter. 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. Specify the Port Number
for this instance of the Service Provider in the PORT parameter. Using the
information provided by your TCP Systems Programmer, add an entry to the
TPCONFIG member. See SMXDSAMP member MBRTPCNF for an example XDSS
entry.
d. Copy member XDSSPROC from SMXDSAMP member to a JCL procedure dataset
defined to JES.
2. The Xpediter Service Provider subsystem can be executed as a batch job or as a
started task.
– To run the subsystem as a batch job:
1. Edit member XDSSJCL provided in SMXDSAMP member as required. Make
sure the SSID parameter value, which specifies the four-character subsystem
identifier for the Xpediter Service Provider, matches the name used at your
site. The default is XDSS.
2. Submit XDSSJCL.
– To run the subsystem as a started task, issue the following operator command:
where {,SSID=xxxx} is an optional parameter used to override
S XDSSPROC{,SSID=xxxx} the default subsystem identifier, XDSS, with the identifier used at
your site.
If you would like the Xpediter Service Provider to be initialized automatically
during MVS startup, add the following start command to SYS1.PARMLIB member
COMMNDxx:
S XDSSPROC,SSID=xxxx where xxxx is the subsystem identifier. XDSS is the default.
2-28
Note: To use the new TCP link between Service Providers, the start command for
the Xpediter Service Provider must come after your start of TCPIP.
For more information on the subsystem, see Chapter 7, “Xpediter Service Provider”.
For information on subsystem security, refer to “Step 4. External Security
Considerations” on page 2-21.
Note: The MVS Performance Group for the Xpediter Service Provider must be higher
than CICS and less than VTAM to prevent runtime abends.
Step 7. Update the CICS Startup JCL
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.
To enable Xpediter’s CICS Release Support, add the appropriate load library listed in
Table 2-8 to the DFHRPL concatenation.
Note: Dynamic LIBRARY resource definitions may be used instead of the static
DFHRPL concatenation. For more information, see “Support for CICS
Dynamic LIBRARY Capability” on page 1-2.
Table 2-8.
Load Libraries for CICS Release Support
CICS Release Dataset Name
CICS TS 3.1
CPWR.MMXD930.SMXDO64L
CICS TS 3.2
CPWR.NMXD930.SMXDO65L
CICS TS 4.1
CPWR.OMXD930.SMXDO66L
CICS TS 4.2
CPWR.PMXD930.SMXDO67L
CICS TS 5.1
CPWR.QMXD930.SMXDO68L
CICS TS 5.2
CPWR.RMXD930.SMXDO69L
2. SLS (source listing support) datasets are associated with ddnames derived from the
values of global parameter SLSDDN. These parameter values are composed of a 4character prefix and a 3-digit suffix. The default is SLSF001. The maximum number
of ddnames is specified by the global parameter NBRSLS. For more information, see
Chapter 4, “Global Parameters Table”. Allocate one or more SLS datasets to CICS
using one or any combination of the following methods:
– Add a DD statement and/or RDO definition for each SLS standard DDIO dataset
or shared directory to the CICS startup JCL. The ddnames should be composed of
a 4-character prefix matching the prefix portion of parameter SLSDDN and a 3digit suffix between 001 and 099. Shared databases are dynamically allocated as
required.
– Use the DSNAME parameter of the CSD resource definition.
Notes:
– If you make a change to your SLS file that requires closing then opening it while
CICS is active, you must make that change from the SLS Datasets screen (9.L).
– If you use a non-IBM dynamic allocation product, ensure that the source listing
datasets are excluded from automatic opens performed by these products when
the dataset is allocated. If you fail to do so, you may be unable to access source
listings through Xpediter/CICS.
2-29
– If you are installing Xpediter/CICS for the first time, the optional datasets
described in the remainder of this step have not yet been created.
3. If you are not dynamically allocating CICS datasets and plan on using the profile file
to be created in “Part 4: Configure Xpediter/CICS”, “Step 13. Allocate the New Profile
File (DBCDEFPF)” on page 2-31, add a DD statement for it. The default name is
DBUGPRF. Although the profile file is optional, Compuware highly recommends its
use.
4. If you are not dynamically allocating CICS datasets, add a DD statement for the
employee file, which is used with the test programs, to be created in “Part 4:
Configure Xpediter/CICS”, “Step 14. Allocate and Initialize the Employee File
(DBCDEFEM) (Optional)” on page 2-33. Remove this statement when the programs
are no longer used for demonstration purposes. The default is DBUGEMP.
5. Add a DD statement for the global table parameter override dataset to be created in
“Part 4: Configure Xpediter/CICS”, “Step 11. Create the Global Table Parameters
Override Dataset (Optional)” on page 2-31. The default ddname is XDGBLINP. Refer
to Chapter 5, “Overriding Global Parameters” for complete details.
6. Add a DD statement for the DBPA transaction input dataset to be created in “Part 4:
Configure Xpediter/CICS”, “Step 12. Create DBPA Transaction Input Dataset
(Optional)” on page 2-31. The default ddname is XDDBPINP. Refer to Chapter 14,
“Specifying DBPA Transaction Input” for complete details.
7. Optional (DB2 only): Add a DD statement for DBUGSQL.
8. Unless the documentation packaging utility has been disabled by changing the value
of global parameter RECREATE to NONE, either in DBUGGBL or as a global table
override, you must do one of the following:
– Add a DD statement for the Recreate JCL member DBUGUD to be allocated in
“Part 4: Configure Xpediter/CICS”, “Step 15. Allocate and Initialize the Recreate
Dataset (DBUGUD) (Optional)” on page 2-34.
– Use the DSNAME parameter of the CSD resource definition for the Recreate JCL
member DBUGUD.\
Step 8. Verify the Xpediter/CICS Installation
To verify that the Xpediter/CICS installation has been successful, Xpediter/CICS runs the
Installation Verification Process (IVP). This procedure, performed automatically when the
product is initialized in the CICS region, detects any changes introduced in the region
that would cause the product not to function. You may request verification by using the
XIVP transaction. This transaction routes the resulting output messages to the
destination of your choice. The syntax for XIVP is as follows:
DEST=TERMINAL
Causes the output to go to the terminal at which XIVP is entered. This is the
default.
DEST=NONE
Causes all output to go only to transient destination CSMT.
DEST=tempstg-queue
Causes the output to go to the temporary storage queue name supplied.
The global table parameter IVPMSGS controls the destination of messages. To change this
parameter, refer to Chapter 4, “Global Parameters Table”.
2-30
All discrepancies detected by XIVP are assigned a severity level of SEVERE, ERROR,
WARNING or INFORMATIONAL.
If severe errors are detected during initialization, they are placed in the temporary
storage queue XPEDXIVP, and Xpediter/CICS abends with a code of DBI0. Refer to
Appendix A in the Xpediter/CICS Reference Manual for information on the abend code. If the
product is being initialized at a terminal where errors are detected, the following
messages are directed to the terminal user before the abend is issued:
ERRORS WERE DETECTED DURING INITIALIZATION
USE CEBR TO BROWSE TEMPSTG QUEUE XPEDXIVP, OR
EXAMINE TRANSDATA DESTINATION CSMT FOR MESSAGES, OR
EXECUTE TRANSACTION XIVP DEST=TERMINAL TO SEE ERRORS
If ERROR level discrepancies are detected during initialization, they are placed in the
temporary storage queue XPEDXIVP, and Xpediter/CICS initialization will continue. If
the product is being initialized at a terminal, the messages shown below will be directed
to the terminal user. If the user responds NO to the “continue initialization” prompt,
Xpediter/CICS abends with DBI0.
ERRORS DETECTED
THE PRODUCT MAY BE USED, BUT UNPREDICTABLE RESULTS
MAY OCCUR, UP TO AND INCLUDING POSSIBLE REGION
OUTAGES. CORRECT THESE ERRORS AS SOON AS POSSIBLE.
CONTINUE INITIALIZATION? ==>
(YES/NO)
If product is initialized with ERROR level discrepancies, a message “Xpediter
initialization error, execute XIVP” will be issued to the terminal when a new
Xpediter/CICS session is started. This will alert each user to the fact that there may be
problems with the product’s configuration. These errors should be corrected as soon as
possible.
Step 9. Review Automatic Session Termination
Xpediter/CICS can be tailored to terminate an active debugging session automatically if a
terminal is disconnected, logged off, and/or signed off from CICS. Refer to Chapter 8,
“Session and Product Termination” for additional information on this option.
Notes:
• Compuware highly recommends that you install automatic session termination to
release the resources of sessions that have not been manually terminated.
• If you have been using Automatic Session Termination, you may continue to use
your existing implementation.
Step 10. Review Global Parameters
Compuware recommends that your site install and test Xpediter/CICS with the shipped
options. You may, however, want to review the global parameters in Chapter 4, “Global
Parameters Table”.
IMPORTANT:
Xpediter’s restricted modes are enabled by changing the default settings for the
global table parameters OKUPDT and UTILMOD. See the Xpediter/CICS Reference
Manual for more information on using restricted modes.
2-31
Step 11. Create the Global Table Parameters Override Dataset
(Optional)
Xpediter/CICS provides a facility for overriding global parameters with values read from
a sequential dataset at product initialization. A standalone transaction, XSIT, can also be
used to override global parameters from the same dataset while Xpediter is running.
Compuware strongly recommends using the override dataset method of overriding
parameters because it provides greatly enhanced ease of use. To create the required
dataset and enable the override facility, follow the instructions in Chapter 5,
“Overriding Global Parameters”.
Note: If you have been using a global parameters override dataset, review the parameters
for possible changes that may be required for your site. You may continue to use
your existing dataset.
Step 12. Create DBPA Transaction Input Dataset (Optional)
Xpediter/CICS includes a facility for specifying DBPA transactions from a sequential
input dataset. DBPA transactions can be used to conveniently set storage protection and
abend trapping options at Xpediter startup. A standalone transaction, XDBP, can also be
used to refresh the parameters from the input dataset without recycling Xpediter or the
CICS region.
Compuware strongly recommends using this method, which is easier to set up and use
than previous methods and includes reporting capabilities. To create the required
dataset, enable the facility, and convert DBPA transactions used with previous releases,
follow the instructions in Chapter 14, “Specifying DBPA Transaction Input”.
Note: If you have been using the DBPA file, you may continue to use your existing
dataset.
Step 13. Allocate the New Profile File (DBCDEFPF)
Release 8.1 introduced a new format profile file that enables users to save and restore trap
settings. This member contains a utility that creates a new format Profile file and
optionally converts an existing old format Profile file.
Installing the profile file enables you to individually define PF key settings, footing
options, scroll values, and trap and trace options.
Notes:
• If you reformatted the profile dataset with release 8.1, you may continue to use your
existing dataset.
• Although this keyed sequential dataset is optional, Compuware recommends its use.
• If you have been using the profile file, you may continue to use your existing dataset.
However, the ability to save and restore traps and also associate a profile with a
userID only exists with the new format dataset.
• The new format of the profile file can be shared with older releases of Xpediter/CICS
when appropriate maintenance is applied. The PTF-IDs for the older releases are:
XD*F078 for release 8.0, XD*E279 for release 7.7, and XD*C240 for release 7.6.
• An ENQMODEL for the profile dataset, included in sample member CSDXDFIL, was
new to release 8.1. (It was included in PTFs for previous releases.) Ensure that this
ENQMODEL definition is added to all CICS regions that share the same
Xpediter/CICS Profile Dataset. This ensures that ENQs done for the Profile File are
recognized across all CICS regions in the sysplex.
2-32
• Also see “PROFUSR” on page 4-25. If you are currently using PROFUSR=NO, you may
want to reconsider this setting.
Define a VSAM KSDS file with the attributes shown for SMXDSAMP member DBCDEFPF
in Figure 2-15 and Figure 2-16. This member contains the JCL for the profile options.
The resource definition for DBUGPRF is installed as part of “Part 4: Configure
Xpediter/CICS”, “Step 3. Update the CICS Resource Definitions” on page 2-18.
Figure 2-15. Defining the Profile File (DBCDEFPF) - Part 1 of 2
//* DBCDEFPF - JCL TO ALLOCATE/CONVERT AN XPEDITER/CICS PROFILE FILE.
//*
//* ---
//* If you already have a new-format profile file, then this entire
//* job can be skipped. An old-format file has a keylength of 8 in
//* the beginning of the record. A new-format file has a keylength
//* of 21 later in the record.
//* ---
//* All Xpediter/CICS releases since 7.6 can use both the old-format
//* and the new-format of profile file.
//* ---
//* The following JCL will allocate the Xpediter/CICS profile file,
//* then convert an old-format profile file to the new format,
//* then optionally "swap" names of your old and new profile files.
//* ---
//* Supply the VOLSER, DSN, and SPACE parameters.
//* ---
//* Read the comments before each JOBSTEP for further
//* customization requirements.
//* ---
//*
//*
//* ------------------------------------------------------------------
//* The AMS step is required.
//* ---
//* Change parameters to conform to your installation standards.
//* ------------------------------------------------------------------
//*
//AMS
EXEC PGM=IDCAMS
//SYSIN
DD *

/* Define new profile dataset. Do not reuse production DSN */

DEFINE CLUSTER
-
(NAME(XPED.NEW.PROFILE.FILE)
/* SUPPLY DSN
*/ -
VOLUMES(??????)
/* SUPPLY VOLSER */ -
CYLINDERS(2 2)
/* SUPPLY SPACE
*/ -
FREESPACE(50 25)
/* DO NOT MODIFY */ -
RECORDSIZE(4081 4081)
SHAREOPTIONS(4 3)
UNIQUE
KEYS(21 1314))
DATA( NAME(XPED.NEW.PROFILE.FILE.DATA))
-
INDEX(NAME(XPED.NEW.PROFILE.FILE.INDEX))
//*
//*
2-33
Figure 2-16. Defining the Profile File (DBCDEFPF) - Part 2 of 2
//* ------------------------------------------------------------------
//* The CONVERT step is required only if you have an old-format
//* profile file to convert. If you do not have an old-format profile
//* file to convert, then delete this step and the RENAME step (only
//* the AMS step should be used).
//* ---
//* If you do have an old-format profile file to convert, then ...
//* (1) Change the STEPLIB to the name of your Xpediter/CICS loadlib
//*
(any CICS release).
//* (2) Provide the DSName of your old-format profile file in
//*
the "DSN=..." field of the PROFIN statement.
//* (3) Change the PROFOUT DSName to the name used in the AMS step.
//* ------------------------------------------------------------------
//*
//CONVERT EXEC PGM=DBUGCNV1
//STEPLIB DD DISP=SHR,DSN=CPWR.cMXDnnn.SMXDOccL /* CHECK DSN */
//PROFIN
DD DISP=SHR,DSN=XPED.PROD.PROFILE.FILE
//PROFOUT DD DISP=SHR,DSN=XPED.NEW.PROFILE.FILE
//*
//*
//* ------------------------------------------------------------------
//* The RENAME step is optional.
//* ---
//* If you had an old-format profile file, and all CICS regions
//* that reference it are shutdown now, then you may RENAME the
//* old-format file and RENAME the new-format file to that old
//* name.
//* ------------------------------------------------------------------
//*
//RENAME
EXEC PGM=IDCAMS,COND=(0,NE,CONVERT)
//SYSIN
DD *

/* Rename current production dataset
*/

ALTER
-
XPED.PROD.PROFILE
-
NEWNAME(XPED.OLD.PROFILE)
ALTER
-
XPED.PROD.PROFILE.*
-
NEWNAME(XPED.OLD.PROFILE.*)

/* Change new dataset to production DSN
*/

ALTER
-
XPED.NEW.PROFILE
-
NEWNAME(XPED.PROD.PROFILE)
ALTER
-
XPED.NEW.PROFILE.*
-
NEWNAME(XPED.PROD.PROFILE.*)
//*
//*
Step 14. Allocate and Initialize the Employee File (DBCDEFEM)
(Optional)
The employee dataset (keyed sequential) is required to run the test (demonstration)
programs. However, you can delete this dataset once these programs are no longer used
for demonstration purposes.
Note: If you have been using the employee file, you may continue to use your existing
dataset.
2-34
Define a VSAM KSDS file with the attributes shown in Figure 2-17. SMXDSAMP member
DBCDEFEM also contains the JCL. The JCL loads the file with five records. The test
programs require that these records be present.
The resource definition for DBUGEMP is installed as part of “Part 4: Configure
Xpediter/CICS”, “Step 3. Update the CICS Resource Definitions” on page 2-18.
Figure 2-17. Defining the Employee File - SMXDSAMP member DBCDEFEM
//AMS
EXEC PGM=IDCAMS
//STEPCAT DD DSN=OPTIONAL.STEPCAT.DSN,
/* SUPPLY STEPCAT
//
DISP=SHR
//DBUGEMP DD VOL=SER=??????,
/* SUPPLY VOLSER
//
UNIT=3380,
/* AND/OR UNIT
//
DISP=OLD
//SYSIN
DD *
DEFINE CLUSTER
(NAME(XPED.EMPLOYEE.FILE)
/* SUPPLY DSN
VOLUMES(??????)
/* SUPPLY VOLSER
FILE(DBUGEMP)
TRACKS(5 0)
/* SUPPLY SPACE
RECORDSIZE(80 80)
/* DO NOT MODIFY
CONTROLINTERVALSIZE(1024)
/* DO NOT MODIFY
SHAREOPTIONS(3 3)
/* DO NOT MODIFY
UNIQUE
KEYS(5 0))
/* DO NOT MODIFY
DATA( NAME(XPED.EMPLOYEE.FILE.DATA))
/* SUPPLY NAME
INDEX(NAME(XPED.EMPLOYEE.FILE.INDEX))
/* SUPPLY NAME
CATALOG(OPTIONAL.STEPCAT.DSN)
/* SUPPLY STEPCAT

/*
LOAD FIVE EMPLOYEE RECORDS

IF LASTCC EQ 0
THEN REPRO
INFILE(SYSIN)
OUTDATASET(XPED.EMPLOYEE.FILE)
/* SUPPLY DSN
00010EMPLOYEE #10
010
00020EMPLOYEE #20
020
00030EMPLOYEE #30
030
00040EMPLOYEE #40
040
00050EMPLOYEE #50
050
*/
*/
*/
*/
*/
*/
*/
-
-
-
-
-
-
-
-
-
-
-
-

*/

*/
*/
*/
*/
*/
*/
-
-
-
*/
Step 15. Allocate and Initialize the Recreate Dataset (DBUGUD)
(Optional)
Xpediter/CICS includes a documentation packaging utility that can assist you, if
necessary, in collecting and transmitting data to Xpediter/CICS Customer Support. That
data allows Compuware to recreate your environment and resolve support issues more
quickly.
Note: If you have been using the Recreate dataset, you may continue to use your existing
dataset.
Unless the documentation packaging utility has been disabled by changing the value of
global parameter RECREATE to NONE, either in DBUGGBL or as a global table override,
you must use one of the following methods to allocate and initialize the Recreate dataset
DBUGUD:
• Invoke the DOCINIT member of dataset SMXDSAMP member using the TSO
EXECUTE command. For example:
2-35
TSO EX 'CPWR.cMXD930.SMXDSAMP(DOCINIT)'
DOCINIT is a REXX EXEC similar to the Installation JCL Customization Facility
(XDINST). Be sure the values entered for DOCINIT are the same as those entered
during “Step 1. Select Installation Components” on page 2-4.
• Use the JCL provided in member SMXDSAMP. Edit the JCL (shown in Figure 2-18) to
your site’s standards, then submit it to allocate and initialize the Recreate dataset.
Note: This member contains control characters in columns 79 and 80. Do not edit
with NUM option or modify these columns.
After completing the full installation, you have the option of contacting Xpediter/CICS
Customer Support to arrange a test of the documentation packaging utility that will
verify its proper configuration. Refer to “Customer Support” on page xxviii.
Figure 2-18. Sample JCL (DBCDEFRP) to Allocate and Initialize Recreate Dataset DBUGUD
//TEMPLATE EXEC PGM=IDCAMS
//SYSIN
DD *
DELETE XPED.RECREATE.JCL CL PURGE
DEFINE CLUSTER
(NAME(XPED.RECREATE.JCL)
VOLUMES(vvvvvv)
TRACKS(2 2)
RECORDSIZE(80 80)
NUMBERED
SHAREOPTIONS(1 3))
/*
LOAD JCL DATA
IF LASTCC EQ 0
THEN REPRO
INFILE(SYSJIN)
OUTDATASET(XPED.RECREATE.JCL)
/*
//SYSJIN DD DATA,DLM=@@
/* SEE MEMBER DBCDEFRP */
@@
//
/* DO NOT MODIFY
/* DO NOT MODIFY
/* DO NOT MODIFY
*/
*/
*/
*/
-
-
-
-
-
-
-
-
-
Step 16. Implement Support for the DB2 File Utility (Optional)
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.
Bind the Plan
Notes:
• The DBRM members for the DB2 File Utility have been updated in this release of
Xpediter. The following bind steps must be performed.
• The default bind plan name has changed in this release to reflect the product code
and release (MXD0930). If during the migration to the new release of the DB2 File
Utility you intend to also use a previous release of the DB2 File Utility, you must use
the plan name (default MXD0910) for Xpediter/CICS 9.1, the plan name (default
MXD0900) for Xpediter/CICS 9.0, the plan name (default MXD0830) for
Xpediter/CICS 8.3, the plan name (default MXD0820) for Xpediter/CICS 8.2, the
2-36
plan name (default MXD0810) for Xpediter/CICS 8.1, the plan name (default
MXD0800) for Xpediter/CICS 8.0, or the plan name (default CWSQLPRO) for releases
prior to 8.0.
Use the JCL supplied in member DBBIND 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 DBBIND as follows:
a. Change the dataset names to point to the appropriate DB2 libraries.
b. Change the dataset names to point to the appropriate input DBRM library. This is
the name of the library in which you placed the source members and macros
supplied by Xpediter/CICS.
c. Change the subsystem name in the DSN SYSTEM statement to match the
subsystem for which you are binding the plan.
d. Optional: Compuware recommends using MXD0930 as your plan name,
however:
• If your site requires a different name, change the plan name in the BIND
PLAN(MXD0930) statement to the required plan name.
• If your site uses Dynamic Plan Selection, copy member CWSQLPRO provided
in SMXDSAMP member into a new SAMPLIB member named DBUGSP00.
Then change the plan name in the BIND PLAN(CWSQLPRO) statement to
DBUGSP00.
2. The JCL in DBBIND 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 MXD0930 TO PUBLIC
If you changed the plan name in the JCL above, substitute that plan name in place of
MXD0930 before executing the SQL statement.
Establish DB2 Authorization for XPED, XPRT, and XPSP Transactions
Note: If you have previously established DB2 authorization settings, you may skip this
section.
To enable the DB2 portion of the Xpediter/CICS File Utility, you must establish the
necessary transaction authorizations by submitting revised DB2ENTRY CEDA definitions.
Ensure the PLAN parameter matches the plan name used to bind the plan in the previous
section. The default in member CSDXDDB2 is MXD0930.
• You may need to modify the DB2ENTRY parameters in the CEDA definitions
provided in SMXDSAMP member, member CSDXDDB2. After modifying the entries,
continue with “Determine Setting for DB2AUTH Global Parameter” below. The
modified entries will be applied in “Step 24. Assemble/Compile and Link-Edit the
Test Programs (Optional)” on page 2-43.
Determine Setting for DB2AUTH Global Parameter
In “Step 10. Review Global Parameters” on page 2-30, change Xpediter global parameter
DB2AUTH to the value listed in Table 2-9 on page 2-37 that matches the applicable DB2
parameter: AUTHTYPE() DB2CONN and/or DB2ENTRY resource definition parameter.
2-37
Notes:
• 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 2-9.
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
Step 17. Allocate, Format, and Initialize the SQL Transfer File
(DBCDEFSQ) (Optional)
Notes:
• If you installed support for the DB2 file utility in “Step 16. Implement Support for
the DB2 File Utility (Optional)” on page 2-35, Compuware recommends that you
create this SQL transfer file.
2-38
• If you have been using the SQL transfer file, you may continue to use your existing
dataset.
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. This file may be shared across multiple regions on the same MVS image.
Use SHAREOPTIONS (4 3) if sharing across multiple regions.
1. The JCL in Figure 2-19 on page 2-38 allocates a VSAM KSDS SQL file. Supply the
volume serial, dataset name, and appropriate space parameters. SMXDSAMP member
DBCDEFSQ contains this JCL.
2. Add your job card and run the JCL.
Figure 2-19. Sample JCL to Allocate SQL Transfer File (DBCDEFSQ)
//*
DBCDEFSQ - IDCAMS JCL TO ALLOCATE AN SQL TRANSFER FILE.
//*
//* THE FOLLOWING JCL WILL ALLOCATE THE SQL TRANSFER FILE.
//* SUPPLY THE STEPCAT, VOLSER, UNIT, DSN, AND SPACE PARAMETERS.
//* THIS JCL IS INTENDED AS AN EXAMPLE.
//* PLEASE CONSULT THE INSTALLATION GUIDE BEFORE RUNNING.
//*
//AMS
EXEC PGM=IDCAMS
//STEPCAT DD DSN=OPTIONAL.STEPCAT.DSN,
/* SUPPLY STEPCAT */
//
DISP=SHR
//DBUGSQL DD VOL=SER=??????,
/* SUPPLY VOLSER */
//
UNIT=3380,
/* AND/OR UNIT
*/
//
DISP=OLD
//SYSIN
DD *
DEFINE CLUSTER
-
(NAME(XPED.SQL.XFER.FILE)
/* SUPPLY DSN
*/ -
VOLUMES(??????)
/* SUPPLY VOLSER */ -
FILE(DBUGSQL)
-
CYLINDERS(1 1)
/* SUPPLY SPACE
*/ -
RECORDSIZE(30008 30008)
SHAREOPTIONS(3 3)
-
UNIQUE
-
KEYS(8 0))
DATA( NAME(XPED.SQL.XFER.FILE.DATA))
/* SUPPLY NAME
*/ -
INDEX(NAME(XPED.SQL.XFER.FILE.INDEX))
/* SUPPLY NAME
*/ -
CATALOG(OPTIONAL.STEPCAT.DSN)
/* SUPPLY STEPCAT */ 

/**************************************************************/
/*
USE JCL IN MEMBER ’DBCINISQ’ TO INITIALIZE THIS DATASET */
/**************************************************************/
3. Once the SQL file is allocated, format it using the JCL supplied in the DBCINISQ
SMXDSAMP member (see Figure 2-20 on page 2-39).
4. Add the appropriate dataset names and execute this JCL to initialize the SQL transfer
file.
2-39
Figure 2-20. Sample JCL to Initialize the Transfer File (DBCINISQ)
//*
DBCINISQ - INITIALIZE SQL TRANSFER FILE
//*
//* THIS JOB WILL INITIALIZE THE SQL TRANSFER FILE FOR USE
//* WITH THE FILE UTILITY.
//* THE STEPLIB DSN MUST BE CHANGED TO REFLECT THE XPEDITER/CICS
//* LOAD LIBRARY.
//* THE COMMAND CARDS SUPPLIED ARE SUGGESTED AND SHOULD ONLY BE
//* MODIFIED AFTER CONSULTING THE INSTALLATION GUIDE. PLEASE
//* CONSULT THE INSTALLATION GUIDE BEFORE RUNNING THIS JCL.
//*
//INIT
EXEC PGM=DBSQLUTL
//STEPLIB DD DISP=SHR,
//
DSN=CPWR.cMXD930.SMXDOccL /* SUPPLY LOADLIB DSN
*/
//SYSUDUMP DD SYSOUT=*
//SQLOUT
DD DISP=SHR,
//
DSN=XPED.SQL.XFER.FILE
/* SUPPLY DBUGSQL FILE DSN */
//SYSIN
DD *
INIT
/*
//
Step 18. Install the Xpediter/CICS Diagnostic Modules (Optional)
If Compuware’s Abend-AID for CICS is not installed at your site, skip this step.
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.
Place the SMXDAAFX library name in the Abend-AID for CICS server concatenation for
DD FDBDRPL, ahead of any other Abend-AID modules.
Notes:
• If your site is using this facility, this step must be performed.
• If you have been using the Xpediter/CICS Diagnostic Modules, you should install the
latest version at a convenient time.
Step 19. Implement the File Utility Security Exit (Optional)
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. For detailed information, refer to Chapter 11, “File
Update Security Exit”.
Note: If you have been using the File Utility Security Exit, you need to reinstall it with
this release of Xpediter/CICS.
Step 20. Implement Xpediter/CICS DBCTL Support (Optional)
If your site uses IMS databases and you want to be able to access IMS databases with
Xpediter’s File Utility, installation of Xpediter DBCTL support is required. Perform the
following procedure to implement DBCTL support:
1. Before proceeding, make sure you have performed the procedures in “Step 2.
Integrate Xpediter/CICS with MVS” on page 2-17.
2-40
2. If you are using VSAM as your access method, change the access method in
SMXDSAMP member XPTSTDBD from OSAM to VSAM.
3. 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 2-10. 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
Xpediter/CICS Install Sample Library
RESLIB
XXXXXXX.RESLIB
IMS RESLIB
DBDLIB
XXXXXXX.DBDLIB
DBD Library
MBR
Blank
PSB member name
4. 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 2-11. Job JCLPSB Symbolic Parameters
Symbolic
Default
Parameter
Description
PRINT
*
DEV
SYSDA
Temporary work file device
SYSLIB
XXXXXXX.MACLIB
IMS Macro Library
SAMPLIB
Xpediter/CICS Install Sample Library
RESLIB
XXXXXXX.RESLIB
IMS RESLIB
PSBLIB
XXXXXXX.PSBLIB
IMS PSB Library
MBR
Blank
PSB member name
5. 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 2-12. Job JCLACB Symbolic Parameters
Symbolic
Default
Parameter
Description
PRINT
*
RESLIB
XXXXXXX.RESLIB
IMS RESLIB
DBDLIB
XXXXXXX.DBDLIB IMS DBD Library
PSBLIB
XXXXXXX.PSBLIB
ACBLIB
XXXXXXX.ACBLIB IMS ACB Library
IMS PSB Library
2-41
6. 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.
Notes:
– 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 2-13. Job JCLLOAD Symbolic Parameters
Symbolic
Default
Parameter
Description
PRINT
*
SYSLIB
XXXXXXX.MACLIB
Macro Library
RESLIB
XXXXXXX.RESLIB
IMS RESLIB
PSBLIB
XXXXXXX.PSBLIB
IMS PSB Library
MBR
Blank
PSB member name
7. 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
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)
Note: 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.
8. 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
2-42
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
9. 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)
Note: Because the Xpediter/CICS database is a read-only database and IMS 4.1 and
above provide you the ability to define a database as non-recoverable, you
may want to do so for performance reasons.
10. If you use PSB security, you may be required to define the PSB and database to your
existing external security manager.
11. Place the Xpediter/CICS APF authorized library in the DLISAS and IMS control region
steplib. The default is SMXDAUTH member.
Note: IMS must be cycled for this change to take effect.
Step 21. Configure the Script Facility (Optional)
The Xpediter/CICS Script Facility lets users record selected primary and line commands
they enter during a debugging session, save them in a PDS or PDSE, and then replay them
later.
Note: If you have been using a system script dataset, you may continue to use your
existing dataset.
To set up the Script Facility, perform the procedure in Chapter 17, “Configuring the
Script Facility”.
Step 22. Configure the File Utility Audit Trail (Optional)
The Xpediter/CICS File Utility Audit Trail lets your site keep track of any changes to
supported resources that are made with the Xpediter File Utility.
Note: If you have been using a GDG dataset, you may continue to use your existing
dataset.
To set up the File Utility Audit Trail, perform the procedure in Chapter 18, “File Utility
Audit Trail”.
Step 23. Review the Language Environment Run-Time Options
Xpediter/CICS support for Language Environment abend trapping and user condition
handling is dependent on the installation parameters specified in CEExOPT (where x is
D, R, or U). See the LE Customization Guide and the CICS Customization Guide for further
details.
See Chapter 16, “Language Environment Operation” for detailed information on
running Xpediter with Language Environment.
2-43
Step 24. Assemble/Compile and Link-Edit the Test Programs (Optional)
The test programs are used to verify proper installation and to demonstrate the product.
Table 2-14 shows the program name for each test program and the language that it is
used for. The table also includes the name of the Assembler subroutine that is called by
each of these programs.
For specific information on compiling your programs using the Compuware language
processor, refer to the Enterprise Common Components Installation and Customization Guide.
Table 2-14. Test Programs
Program Name Language
CWDEMCB2
COBOL
CWDEMCBN
COBOL (w/nested programming)
CWDEMASM
Assembler
CWCDSUBA
Assembler Subroutine
CWDEMPL
PL/I
CWDEMPE
Enterprise PL/I
CWDEMC
C
Table 2-15. Additional Test Programs Using Channels and Containers
Program Name Language
CWDEMACH
Assembler
CWDEMCCH
COBOL
CWDEMPCH
Enterprise PL/I
CWDEMZCH
C
Note: If you have previously installed the test programs, you do not need to recompile
them.
Complete the following steps to ensure that the test programs function properly:
1. Assemble program CWCDSUBA. If you have the Assembler option, process it using
the Compuware Assembler language processor. The CWCDSUBA routine does not
contain any CICS commands and, therefore, does not need to be translated.
CWCDSUBA must be included when CWDEMCB2, CWDEMCBN, CWDEMCCH,
CWDEMPL, CWDEMPE, or CWDEMPCH are link-edited.
2. Compile either the CWDEMCB2 or CWDEMCBN program with the modified
compile/link-edit JCL that includes the Compuware COBOL language processor. Use
the NODYNAM parameter in the COBOL compile step and make sure that the library
for CWCDSUBA is in the SYSLIB dataset. (You may also compile CWDEMCCH.)
3. (Optional) If you have the PL/I option, compile either the CWDEMPL or CWDEMPE
program with the modified compile/link-edit JCL that includes the Compuware PL/I
language processor. Make sure that the library for CWCDSUBA is in the SYSLIB
dataset. (You may also compile CWDEMPCH.)
4. (Optional) If you have the Assembler option, assemble CWDEMASM using the
modified assembly/link-edit JCL that includes the Compuware Assembler language
processor. (You may also compile CWDEMACH.)
5. (Optional) If you have the C option, compile the CWDEMC program with the
modified compile/link-edit JCL that includes the Compuware C language processor.
(You may also compile CWDEMZCH.) See “Compile and Bind C Test Programs”
below to compile and link edit the full set of C test programs.
2-44
Compile and Bind C Test Programs
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.
Note: 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.
Build the C demo programs 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:
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)
Note: 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.
2-45
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 on page 2-44, you will need to define it to
your CICS region.
You are now ready to test the C demo programs.
Setting Up CSS Language Processor JCL
Compuware Shared Services (CSS) Language Processor JCL is used to create source listing
file members. If you have not previously set up this JCL, you can select an SMXDSAMP
member from Table 2-16 to use as an example.
The Language Processors provide two ways to process your programs: preprocessing and
postprocessing. To determine which method is appropriate for your site, refer to the
Compuware Shared Services User/Reference Guide, MVS Version. Each method may require
changes to your compile JCL.
Before using one of the Language Processors, you must first install the CSS load library
and prepare a source listing file.
When running the Language Processor as a preprocessor, you can specify compiler
options either in the CWPPRMO input dataset or in the PARM statement passed to the
preprocessor. Depending on the method used, it may be necessary to include the
LANGPARM command with the compiler options.
Table 2-16. Sample CSS Language Processor JCL Members
Name
Language Type
XDCOBPRE COBOL
Preprocessor
XDCOBPOS COBOL
Postprocessor
XDASMPRE Assembler Preprocessor
XDASMPOS Assembler Postprocessor
XDPLIPRE
PL/I
Preprocessor
XDPLIPOS
PL/I
Postprocessor
XDCPRE
C
Preprocessor
XDCPOS
C
Postprocessor
Modify the chosen JCL as follows:
2-46
• Change any occurrences of CPWR.LCXnnn (where nnn is the CSS release number) to
the dataset name of the libraries created during Compuware Enterprise Common
Components installation.
• Edit the CWPDDIO DD statement to specify the desired source listing file.
• Either determine the Language Processor options you will use as input and add them
to the appropriate EXEC parameter, or update the CWPPRMO DD statement that
points to the appropriate options. The sample options specified will minimize the
space required by providing the smallest output to the source listing file and will
generate a printout of the enhanced listing. When these sample options are used, a
printout of the listing from the source listing file will contain only the source
statements. The XREF and other portions of the listing are not written to the source
listing file.
• Edit the PARM statements to conform to your site’s requirements.
Step 25. Verify Xpediter/CICS Execution
Many Xpediter/CICS system functions rely on compile options and successful
modification of your compile procedure. To verify that the compile procedure is
successfully modified, follow the procedures in Chapter 3, “Installation Verification
Procedures”.
Step 26. Install and Customize the Remote Operations Command
Interface (Optional)
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.
Notes:
• ROCI works only with CICS regions running Xpediter/CICS release 8.0 or above.
Regions running earlier releases of Xpediter/CICS will not recognize commands from
this interface.
• If you copied and customized the ROCI CLIST during a previous installation of
Xpediter/CICS, you may continue to use your CLIST. You only need to update your
NODE keyword value with the value for this release.
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.
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.
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:
2-47
– Change the NODE keyword value on line 1 of the CLIST from CPWR.cMXD930 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.
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.
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 instructions below to install the chosen communications method in your
CICS region:
– Installing 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.
2-48
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.
– Installing 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.
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.
– Installing 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.
Step 27. Install and Customize the Batch Interface to Xpediter/CICS
NEWCOPY (Optional)
Note: This interface is optional. If your site has no need for the interface, skip this step.
2-49
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 release 8.3 (or above) transaction and program definitions must
be installed in each CICS region referenced, and the Xpediter/CICS release 8.3 (or above)
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 “Step 5. Creating and Managing
the Xpediter TP Configuration File (TPCONFIG)” on page 2-26. 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.
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.
Follow the applicable instructions below to install the chosen communications method
in each CICS region.
Installing 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
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.
Installing 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.
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
2-50
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.
Installing 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.
Step 28. Install and Customize for Xpediter/Eclipse (Optional)
Xpediter/Eclipse consists of an Eclipse plug-in that provides the ability to test and debug
applications that execute in CICS and MVS environments. This step describes the actions
necessary to enable a user running Eclipse on their workstation to interface with the
Xpediter/CICS Sockets-Based Debugging API.
2-51
Installation of Additional Components
Before proceeding, make sure the necessary components and plug-ins have been installed
in accordance with the Compuware Workbench Installation Guide.
Verify IBM z/OS Communications Server Installation
Use of Xpediter/Eclipse components requires your site to install IBM’s z/OS
Communications Server product. This facility provides the TCP/IP v4 support necessary
to provide sockets communications between the various components of Xpediter/Eclipse,
Xpediter/CICS, and the Compuware ECC for Eclipse component.
Note: Xpediter/Eclipse and its components do not contain support for TCP/IP v6
communications. Both TCP/IP v4 and v6 can coexist within the z/OS
Communications Service.
Only the steps necessary to customize your current IP CICS Sockets are covered in this
step. If you do not currently have IP CICS Sockets defined in your CICS regions, you must
follow the installation steps outlined in the IP CICS Sockets Guide shipped with IBM’s z/OS
Communications Server.
Compuware strongly recommends the installation of the EZAC transaction and
components shipped with IBM’s z/OS Communications Server. Compuware also
recommends that you automatically start and shut down the IP CICS Sockets interface
according to the instructions provided in the IP CICS Sockets Guide, in the section entitled
“Managing IP CICS Sockets: Starting and stopping CICS automatically”.
Define Transaction Code for Default IP CICS Sockets Listener
Xpediter/CICS requires use of the default CICS sockets listener, EZACIC02, shipped with
the z/OS Communications Server.
Modify the sample RDO definition shown in Figure 2-21 as follows, then add it to any
CICS region that an Xpediter/Eclipse user may connect to:
• Although you can choose a different transaction code, Compuware suggests you use
XSKL. If you choose another transaction code, make note of it for later use in “Define
Listener to IP CICS Sockets” on page 2-54.
• The program name in the definition below, EZACIC02, may need to be modified.
– If your site has not created a customized version of EZACIC02, leave the
PROGRAM parameter unchanged.
– If your site is running a customized version of EZACIC02, determine the load
module name of the customized version as follows:
• If the customized version is not named EZACIC02, leave the PROGRAM
parameter unchanged.
• If the customized version is named EZACIC02, change the PROGRAM
parameter to whatever name the original EZACIC02 was renamed to.
• If the original EZACIC02 was not renamed, you must recover and rename it
something other than EZACIC02, then use that new name for the PROGRAM
parameter.
• Transaction XSKL, or the transaction code you decide to use as the equivalent,
should not be secured. If you wish to limit access to Xpediter/CICS by use of
Xpediter/Eclipse, you should instead secure transaction code XPGD as described in
the next section.
2-52
Figure 2-21. RDO Transaction Definition for XSKL
DEFINE -
TRANSACTION(XSKL) -
DESCRIPTION('Xpediter/CICS Eclipse Listener Task') -
GROUP(XPEDR920) -
PROGRAM(EZACIC02) -
PRIORITY(255) -
TASKDATALOC(ANY) -
TASKDATAKEY(CICS)
Define Transaction Code for Limiting Access to Xpediter/CICS Using
Xpediter/Eclipse
Xpediter/CICS requires that you define transaction XPGD, or one of your choosing, as
shown in Figure 2-22. This transaction can be used to limit access to Xpediter/CICS
debugging facilities through the use of Xpediter/Eclipse. Even if you choose to not limit
access, the transaction must be defined.
• If you want to use a different transaction code:
– It must have the attributes shown in Figure 2-22.
– You must specify the new transaction code using the Xpediter/CICS global
parameter XPGD=xxxx, where xxxx is the transaction code you elect to use. For
more information, see “XPGD” on page 4-40.
• If you do not wish to limit access, make sure you do not secure this transaction.
• If your site wants to limit access to Xpediter/CICS debugging facilities through the
use of Xpediter/Eclipse, you may do so by limiting access to transaction XPGD. This
transaction can be secured by defining user profiles in the ACICSPCT class. Any users
added should have READ access. Only users who pass this security check will be
allowed access to Xpediter/CICS debugging facilities using Xpediter/Eclipse.
Figure 2-22. RDO Transaction Definition for XPGD
DEFINE -
TRANSACTION(XPGD) -
DESCRIPTION(Xpediter/CICS Sockets Security) -
GROUP(XPEDR920) -
PROGRAM(XDPIMIRS) -
TASKDATALOC(ANY) -
TASKDATAKEY(CICS)
Define Xpediter/CICS Sockets Child Listener/Interface
The Xpediter/CICS Sockets Child Listener/Interface program, DBUGSOCK, is a required
component of the Xpediter/CICS Sockets-Based Debugging API. This program handles
the TCP/IP sockets communication between the various components of the
Xpediter/Eclipse package.
Add the RDO definition shown in Figure 2-23 to any CICS region that an
Xpediter/Eclipse user may connect to:
2-53
Figure 2-23. RDO Program Definition for Xpediter/CICS DBUGSOCK
DEFINE
PROGRAM(DBUGSOCK)
DESCRIPTION('Xpediter/CICS Eclipse Sockets Interface')
GROUP(XPEDR920)
LANGUAGE(ASSEMBLER)
EXECKEY(CICS)
DATALOCATION(ANY)
Define Transaction Code for Xpediter/CICS Sockets Child Listener/Interface
The transaction code defined below ensures that the appropriate connections can occur
between the various components of the Xpediter/Eclipse package and will be used when
specifying CICS entries in the Xpediter TP Configuration file.
Although you can choose a different transaction code, Compuware suggests you use
XSOC. If you choose another transaction code:
• Make note of it for later use in “Define Listener to IP CICS Sockets” on page 2-54.
• It must have the attributes shown in Figure 2-24.
Xpediter/Eclipse user may connect to.
Figure 2-24. RDO Transaction Definition for XSOC
DEFINE
TRANSACTION(XSOC)
DESCRIPTION('Xpediter/CICS Sockets Child Listener/Interface')
GROUP(XPEDR920)
PROGRAM(DBUGSOCK)
PRIORITY(255)
TASKDATALOC(ANY)
TASKDATAKEY(CICS)
Define Xpediter/CICS Sockets Security Exit
Xpediter/CICS provides a sockets security exit, XDPCICSE, which allows users of
Xpediter/Eclipse to be authenticated. When establishing a debugging session from
Xpediter/Eclipse, a user must provide their mainframe userID and password. This data is
encrypted and passed during the connection process. Before the sockets listener attempts
to pass control to the Xpediter/CICS Sockets Child Listener/Interface, additional checks
are made and the userID and password are verified. The exit that does this is specified in
the IP CICS Sockets Listener definition in the next section. If the userID/password is
authenticated, IP CICS Sockets logs the user onto CICS and the task under which the
Xpediter/Eclipse session is running is assigned that userID. If the userID/password cannot
be authenticated, the task ends and access is not allowed.
The following program definition is required. If you wish to ensure userID/password
authentication and logon, you must specify the parameter SECEXIT=XDPCICSE in the IP
CICS Sockets Listener definition in the next section. If you do not require a user to log on
to CICS, leave this parameter blank. This will cause the default CICS userID to be
assigned to the task under which the Xpediter/Eclipse session runs.
Xpediter/Eclipse user may connect to and have their userID authenticated:
2-54
Figure 2-25. RDO Program Definition for Xpediter/CICS Sockets Security Exit XPDCICSE
DEFINE
PROGRAM(XDPCICSE)
DESCRIPTION('Xpediter/CICS Sockets Security Module')
GROUP(XPEDR920)
LANGUAGE(ASSEMBLER)
EXECKEY(CICS)
DATALOCATION(ANY)
Define Listener to IP CICS Sockets
This step provides the definitions required to enable the Xpediter/Eclipse components to
connect and communicate properly with the Xpediter/CICS Sockets-Based Debugging
API. Many of the parameters listed below must be specified exactly as shown. Modifying
them in any way can result in the unavailability of the Xpediter/CICS Sockets-Based
Debugging API and complicate problem determination. If you are unsure of any
parameter, code it as shown in the example in Figure 2-26.
The definitions shown in Figure 2-26 have been formatted as though the parameters were
being entered in your original EZACICFG. Although it is possible to add them to the
EZACICFG JCL stream, doing so might cause other definitions to be lost. If you have
experience with regenerating your configuration dataset, use the following definitions.
However, Compuware strongly recommends that you utilize the existing EZAC
transaction—which can be secured and limited to selected users—and enter them
interactively using the EZAC DEFine and ALTer parameters.
IMPORTANT:
– If you are sharing a configuration dataset among several regions, make sure you
create identical definitions for all regions you want Xpediter/Eclipse users to be
able to connect with. Each definition would require you to modify the APPLID
and PORT parameters at a minimum. If you decided above to modify the CICS
RDO definition for the XSKL or XSOC transactions, or if you need to create
unique definitions by region, you must modify the TRANID and CSTRAN
parameters as well. Do not modify any underlined parameter settings.
– The USERID parameter can be assigned a default userID to be assigned to the task
under which the Xpediter/CICS interface to Xpediter/Eclipse will run. You can
choose to specify a value or not.
– The SECEXIT parameter can be used if you want to ensure that the user
attempting to use Xpediter/Eclipse can be authenticated. If you want to require
authentication, the program XDPCICSE must be specified. If a user cannot be
authenticated, access to Xpediter/CICS debugging facilities through
Xpediter/Eclipse will be prohibited.
– WLM (Work Load Manager) parameters have been explicitly omitted. Support for
this facility will be implemented in a future release.
2-55
Figure 2-26. Definitions for Enabling Listener to IP CICS Sockets
EZACICD TYPE=LISTENER,
FORMAT=ENHANCED,
APPLID=H01AC024,
TRANID=XSKL,
PORT=nnnnn,
AF=INET,
IMMED=YES,
BACKLOG=20,
NUMSOCK=50,
ACCTIME=30,
GIVTIME=30,
REATIME=300,
CSTRAN=XSOC,
CSSTTYP=KC,
CSDELAY=000000,
MSGLEN=61,
PEEKDAT=NO,
MSGFORM=EBCDIC
USERID=aaaaaaaa,
SECEXIT=XDPCICSE
Create Listener Record (XP Eclipse)
Enhanced Listener
APPLID of CICS
Use Clone of Standard Transaction ID
CICS Port Number of listener
IPv4
Start Listener Immediately
Set Backlog Value to 20
Support 50 Concurrent Connections
Set Timeout Value to 30 Seconds
Set Givesocket Timeout to 30 Seconds
Set Read Timeout to 5 minutes
TranID Associated with DBUGSOCK
Child Server Startup Type
Child Server Delay Interval
Length of Input Message
Peek Option
Output Message Format
Default userid to be assigned
Security Exit
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Enable Xpediter/CICS Sockets-Based Debugging API
Install the RDO definitions created above by either submitting CEDA transaction to
specify your definitions or by creating sequential input versions of the definitions and
adding them with the DFHCSDUP batch utility.
After the RDO definitions have been installed, activate the new listeners using the EZAO
transaction. This is not necessary, however, if you have stopped and started IP CICS
Sockets.
Test Xpediter/Eclipse Connection
After successfully completing the above steps and checking your CICS and JES logs for
errors, test your Xpediter/Eclipse connection. Make sure your Xpediter TP Configuration
File member contains valid CICS entries that point to any CICS regions you want
Xpediter/Eclipse users to connect to. For more information, see the section entitled “Part
4: Create and Manage the CSS TP Configuration File” in Chapter 3 of the Compuware
Workbench Installation Guide. You should also make sure that your Eclipse Debug Launch
Configuration settings have been properly specified and you can connect to the
Xpediter/Eclipse TP. If you are unable to connect, double-check the installation of the
Xpediter/Eclipse components and review any messages written to the JES and CICS logs
to assist in verifying their correct installation.
Additional Information
A new Xpediter/CICS Global Override, XPGD=xxxx, has been added for supporting the
Xpediter/Eclipse interface. This override allows the default transaction id XPGD to be
renamed to one of your choosing (xxxx). If you decide to modify this parameter, you
must also ensure that its definition matches that shown in Figure 2-22 in the section
“Define Transaction Code for Limiting Access to Xpediter/CICS Using Xpediter/Eclipse”
above.
Several new messages with the prefix MXDSK have been added to support the
Xpediter/Eclipse interface. The Xpediter/CICS Sockets modules XDPCICSE and
DBUGSOCK output these messages. They provide informational data, and many of them
are related to the setup of the Xpediter/Eclipse interface. You are advised to review the
CSMT output during and after installation or if connection or usage problems occur
while attempting to use the Xpediter/Eclipse interface.
2-56
Tar File SMP/E Receive
This section contains instructions for those sites unable to do a Receive From Network
directly to the mainframe.
Step 1. Download the Tar File
The product order e-mail contains a link to a .tar file. Click the link and save the file to
your default download directory.
Step 2. Create USS Directory and File Structure
Certain directories, sub-directories, and files must exist before transferring the
installation package to the Unix System Services (USS) workspace. To create them,
customize and run the sample JCL shown in Figure 2-27.
Figure 2-27. Sample JCL to Create USS Directory and File Structure
//
//*********************************************************************
//* This job will create the directories / files necessary for
//*
housing the RFN tarball on your USS workspace.
//*
//* CAUTION: This is not a complete job. Before using this JCL,
//*
you will have to make modifications.
//*
//*
@@@@@> INPUT WITHIN THIS JOB IS CaSe sENsiTivE. <@@@@@@
//*
//* Notes:
//*
1 - Update jobcard as required. REGION=0M is important!
//*
2 - If necessary, change the dataset name on the SYSEXEC DD
//*
card to match the name of your BPX REXX library.
//*
3 - Change all ???????? to the desired USS work directory.
//*
(Be careful with the placement of the '/' character(s).)
//*
4 - Change nnnnnnn to the high level portion of the name of the
//*
.tar file that was downloaded earlier.
//*
//* EXAMPLES:
//*
If your USS work directory is sub directory 'work' under
//*
your 'userid' directory, then:
//*
C '????????' '/userid/work'
//*
If the downloaded tarball file is 0000005.tar, then:
//*
C 'nnnnnnn' '0000005'
//*********************************************************************
//STEP1
EXEC PGM=IKJEFT01,DYNAMNBR=50
//SYSEXEC DD DISP=SHR,DSN=SYS1.SBPXEXEC
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*,TERM=TS
//SYSOUT
DD SYSOUT=*,TERM=TS
//SYSTSIN DD *
oshell
rm -r ????????/rfn
oshell
mkdir ????????/rfn
oshell
mkdir ????????/rfn/nnnnnnn
oshell
mkdir ????????/rfn/nts
oshell
mkdir ????????/rfn/tarball
//
Step 3. Copy the Tar File to USS Tarball Directory
Use an FTP client such as WS_FTP or FileZilla to copy the downloaded .tar file to your
mainframe USS tarball sub-directory created by the JCL in Step 2 above. The example in
2-57
Figure 2-28 shows FileZilla, a free FTP client, being used to drag-and-drop the .tar file into
the tarball folder.
Figure 2-28. Copying Tar File to Tarball Folder
Step 4. Extract Tar File Contents
Before completing the Receive From Network process, the contents of the .tar file must be
extracted into the directory and file structure created in Step 2 above. To extract the
contents of the .tar file, customize and run the sample JCL shown in Figure 2-29.
Figure 2-29. Sample JCL to Extract Contents of Tar File
//
//*********************************************************************
//* This job will extract a tarball file, creating the required
//*
directory / file structure for the Receive from Network job.
//*
//* CAUTION: This is not a complete job. Before using this JCL,
//*
you will have to make modifications.
//*
//*
@@@@@> INPUT WITHIN THIS JOB IS CaSe sENsiTivE. <@@@@@@
//*
//* Notes:
//*
1 - Update jobcard as required. REGION=0M is important!
//*
2 - If necessary, change the dataset name on the SYSEXEC DD
//*
card to match the name of your BPX REXX library.
//*
3 - Change all ???????? to the desired USS work directory.
//*
(Be careful with the placement of the '/' character(s).)
//*
4 - Change nnnnnnn to the high level portion of the name of the
//*
.tar file that was downloaded earlier.
//*
//* EXAMPLES:
//*
If your USS work directory is sub directory 'work' under
//*
your 'userid' directory, then:
//*
C '????????' '/userid/work'
//*
If the downloaded tarball file is 0000005.tar, then:
2-58
//*
C 'nnnnnnn' '0000005'
//*********************************************************************
//*
//*--------------------------------------------------------------------
//* CREATE COMMAND FILE
//*--------------------------------------------------------------------
//BUILD1
EXEC PGM=IKJEFT01
//SYSEXEC DD DISP=SHR,DSN=SYS1.SBPXEXEC
//SYSOUT
//SYSTSIN DD *
oshell cat > ????????/rfn/commands.sh
//*--------------------------------------------------------------------
//* POPULATE COMMAND FILE
//*--------------------------------------------------------------------
//BUILD2
EXEC PGM=IKJEFT01
//SYSOUT
//OUT
DD PATH='????????/rfn/commands.sh'
//IN
DD *
cd ????????/rfn/nnnnnnn
pax -rvf ????????/rfn/tarball/nnnnnnn.tar
//SYSTSIN DD *
OCOPY INDD(IN) OUTDD(OUT) TEXT PATHOPTS(USE)
//*--------------------------------------------------------------------
//* Extract TAR file (execute shell)
//*--------------------------------------------------------------------
//EXTRACT EXEC PGM=BPXBATCH
//STDIN
DD PATH='????????/rfn/commands.sh'
//STDOUT
DD SYSOUT=*
//STDERR
DD SYSOUT=*
//
Step 5. Perform SMP/E Receive
The Receive From Network package is now staged in the USS workspace. Use the sample
JCL provided in the file named smpe_receive.txt to facilitate an SMP/E Receive. Follow
the instructions in the comments of the sample JCL to customize the batch job, with the
following additions:
• The host= variable should point to your site, with the appropriate settings for user=
and pw=.
• The file= variable should point to ????????/rfn/nnnnnnn/GIMPAF.XML where
???????? is the USS work directory used when running the job to extract the tar file
and nnnnnnn is your 7-digit order number.
Submit the customized JCL to perform the RECEIVE. When the job has completed, return
to “Step 3. Copy Installation Dialog File from USS to z/OS” on page 2-3.
3-1
Chapter 3.
Installation Verification Procedures
Chap 3
This chapter contains the steps to verify that your compile/assembly procedures were
successfully modified. The steps ensure that you can access a program source listing and
that the functions that use a source listing work properly.
The XPED level is used to activate Xpediter/CICS. Once activated, you can use one of the
following test programs to access source and verify that Xpediter/CICS debugging
functions are available:
•
•
•
•
•
CWDEMASM for Assembler (transaction XASM)
CWDEMC for C (transaction XCCC)
CWDEMCB2 for COBOL (transaction XCB2)
CWDEMPL for PL/I (transaction XPLI)
CWDEMPE for Enterprise PL/I (transaction XPLE).
Note: Assembler, C, and PL/I support are optional. If you are unsure of your site’s status,
contact your Xpediter/CICS sales representative.
Detailed steps for each of these verification procedures are presented in the following
sections.
Note: The line numbers shown in this chapter may vary from those actually seen during
verification procedures.
Testing your COBOL Compile Procedures
The procedures listed in this section use the sample XCB2 transaction, which executes
the CWDEMCB2 COBOL test program.
Abend Trapping and Stepping Without Breakpoints
This procedure contains the steps for trapping an abend and stepping through a program
in which no breakpoints are set.
1. On a blank CICS screen, type XPED and press Enter.
This activates Xpediter/CICS, sets the abend trap option, and displays the Primary
Menu as shown in Figure 3-1.
Xpediter/CICS is now ready to intercept any abends that occur in any program
executed from your terminal.
3-2
Figure 3-1. Primary Menu (XPED/XPRT)

-------------------- XPEDITER/CICS 09.03.00 - PRIMARY MENU ----------------C123
COMMAND ===>
MODULE:
CSECT:





0
1
2
5
7
SESSION PROFILE
SESSION CONTROL
DEBUGGING FACILITIES
FILE UTILITY
ABEND-AID FOR CICS
-
Set default session attributes
Analyze summary of session events
Interactively debug application programs
Access datasets, temp stg, trans data, DLI, DB2
Interface to Abend-AID for CICS
C
G
P
X
CODE COVERAGE
XCHANGE/CICS
CICSPLEX FACILITIES
EXIT
-
Interface to Xpediter/Code Coverage
Interface to Xpediter/Xchange CICS Facilities
Access CICSPlex Control Facilities
Exit Xpediter
To set breakpoints in your program or keep specific data fields,
enter your program name and use either the SOURCE command or PF key.
For Online Technical Support refer to: http://frontline.compuware.com
NOTICE:
Press PF2/PF14 to display the Copyright/Trade Secret Notice
2. Press Clear to return to CICS so that you can begin your test.
3. On a blank CICS screen, type XCB2 and press Enter.
The XCB2 Demonstration Transaction screen is displayed as shown in Figure 3-2.
Figure 3-2. XCB2 Demonstration Transaction Screen
XCB2 _____ - ENTER EMPLOYEE NUMBER

*** COMPUWARE CORPORATION ***
DEMONSTRATION TRANSACTION

ENTER DESIRED EMPLOYEE ABOVE:
00001 - CAUSES ASRA ABEND
00002 - CAUSES AEIM (AND OTHER ABENDS)
00003 - CAUSES A WRITE TO TEMPORARY STORAGE
00004 - STARTS UP XCB2 AS AN ASYNCHRONOUS TASK
00005 - USED TO SHOW MULTIPLE CSECT SUPPORT
00333 - CAUSES A STORAGE VIOLATION OF A SAA
00999 - ENDS NORMALLY
C123
4. To cause an ASRA abend, type 00001 and press Enter.
The CWDEMCB2 test program is intercepted before CICS gets control of the abend,
and the Source Listing screen (2.L) is displayed as shown in Figure 3-3.
Notes:
• If DUMP=YES is specified, an MVS snap dump is taken before Xpediter/CICS gets
control.
• If the NO SOURCE AVAILABLE message or the NO TIMESTAMP message is
displayed, use the HELP command (the default PF key is PF1) for detailed
information. The Help screen lists the causes for the message and highlights the most
probable causes. Also review the output from the Compuware language processor to
verify that the source listing was successfully written to the source listing file.
3-3
Figure 3-3. COBOL Source Listing Screen Showing ASRA

--------------------- XPEDITER/CICS - SOURCE LISTING (2.L) ----------------C123
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMCB2 CSECT: CWDEMCB2
COMPILED: 25 JUN 2002 - 16.58.54
LV ----- COBOL DATANAME KEEPS ---- -- ATTRIBUTES -- ----+---10----+---20--->
77 CURR-PAY
9(5)V99 NUM-DIS 0000000
02 WA-HOURS
999 NUM-DIS
$$$
02 WA-RATE
9(3)V99 NUM-DIS 00950
**END**
-----000490
000491
000492
000493
000494
=====>
000496
000497
000498
000499
000500
000501
000502
000503
----------------------------- ASRA (DATA EXCEPTION) at CWDEMCB2.495 ->
MOVE '*** EMPLOYEE NOT ON FILE ****' TO PAYPROMP
GO TO 600-SEND-PAY-MAP.
1
1
1
1
1
300-EMPLOYEE-PAY-RTN.
IF WA-TYPE EQUAL 'N' OR 'I' OR 'S'
COMPUTE CURR-PAY
EQUAL WA-HOURS * WA-RATE
COMPUTE CURR-TAXES EQUAL CURR-PAY * WA-TAX-
ADD CURR-PAY
TO WA-YTD-GRS
ADD CURR-TAXES TO WA-YTD-TAX.
IF PAYEMP1 EQUAL '00001'
MOVE WORK-AREA TO PAYROLL-DATA-EMP001.
The module name, CSECT name, compile date, and compile time of program
execution are displayed at the top of the screen to indicate which program is
executing.
The keep window is displayed directly below the program information. All data
names from the current statement are automatically displayed in this window. These
are called automatic keeps and are valid for Assembler, COBOL, and PL/I programs.
Data names that were selected with the KEEP command are also displayed in this
window. These are called explicit keeps and are indicated by a K next to the data name.
To scroll the information in the keep window, position the cursor in the window and
use the PF keys assigned to scroll up, down, left, and right. The default PF keys are
PF7, PF8, PF10, and PF11 respectively.
The STATUS line contains messages and is displayed immediately following the keep
window. The message displayed in Figure 3-3 indicates that a data exception ASRA
abend was intercepted at statement 495 in CWDEMCB2.
The source code follows the STATUS line. This section can be scrolled by positioning
the cursor anywhere on the screen outside of the keep window. An arrow (=====>)
indicates the current statement.
Notice the value of WA-HOURS in the keep window. The bad data in this field ($$$)
is causing the ASRA.
5. To correct this data, position the cursor on $$$ in the keep window, type 040, and
press Enter.
6. Type GO 1 on the COMMAND line (the default PF key is PF9) and press Enter to
execute one line of source.
Notice the changes to the values of the data fields in the keep window, as shown in
Figure 3-4.
3-4
Figure 3-4. Source Listing Screen After Entering GO 1 Command

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMCB2
****** STATEMENT 000495 EXECUTED
STEP=00001 *******
77 CURR-TAXES
9(5)V99 NUM-DIS 0000000
* 77 CURR-PAY
9(5)V99 NUM-DIS 0038000
02 WA-TAX-RAT
9(3)V9 NUM-DIS
0200
**END**
-----000490
000491
000492
000493
000494
000495
=====>
000497
000498
000499
000500
000501
000502
000503
----------------------------------------------- Before CWDEMCB2.496 ->
MOVE '*** EMPLOYEE NOT ON FILE ****' TO PAYPROMP
GO TO 600-SEND-PAY-MAP.
1
1
1
1
1
300-EMPLOYEE-PAY-RTN.
IF WA-TYPE EQUAL 'N' OR 'I' OR 'S'
COMPUTE CURR-PAY
EQUAL WA-HOURS * WA-RATE
COMPUTE CURR-TAXES EQUAL CURR-PAY * WA-TAX-
ADD CURR-PAY
TO WA-YTD-GRS
ADD CURR-TAXES TO WA-YTD-TAX.
MOVE WORK-AREA TO PAYROLL-DATA-EMP001.
7. Type GO on the COMMAND line (the default PF key is PF12) and press Enter to
continue the test.
When execution successfully completes, the Transaction Complete screen is
displayed as shown in Figure 3-5.
Figure 3-5. Transaction Complete Screen
*** COMPUWARE CORPORATION ***

EMPLOYEE NUMBER: 00001
EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
040
HOURLY RATE:
9.50
GROSS PAY:
380.00

*** TRANSACTION COMPLETE ***
C123
To release all resources, you must tell Xpediter/CICS that you have completed your
debugging session.
8. On a blank CICS screen, type XPND and press Enter.
Setting Keeps and Breakpoints
This procedure shows you how to set keeps and breakpoints in the program source.
1. On a blank CICS screen, type XPED CWDEMCB2 and press Enter.
The Source Listing screen (2.L) is displayed as shown in Figure 3-6.
3-5
Figure 3-6. Source Listing Screen (2.L)
COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
-------------------------------------------------------------------------->
000415
PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA.
000416
000-BEGIN-PROGRAM.
000417
*EXEC CICS HANDLE AID
000418
*
CLEAR (800-RETURN-TO-CICS)
000419
*END-EXEC.
000420
MOVE '
00301
' TO DFHEIV0
000421
CALL 'DFHEI1' USING DFHEIV0
000422
SERVICE LABEL
000423
GO TO 800-RETURN-TO-CICS DEPENDING ON DFHEIGDI
000424
*EXEC CICS ASSIGN
000425
*
SYSID(WS-SYSID)
000426
*
NOHANDLE
000427
*END-EXEC.
000428
MOVE '
00304
' TO DFHEIV0
000429
CALL 'DFHEI1' USING DFHEIV0 WS-SYSID.
000430
000431
000432
000433
IF EIBCALEN EQUAL ZERO
000434
1
NEXT SENTENCE
Explicit keeps are also displayed in the keep window area of the Source Listing screen
(2.L) when an abend or breakpoint occurs.
By setting a keep for WA-HOURS, you can monitor its value and effect on program
execution. Explicit keeps are helpful when you want to view the contents of a
variable regardless of whether or not it participates in a statement.
Note: Intelligent Autokeeps can be used to automatically redisplay the value of a
variable modified by a statement after you have stepped to the next
statement. The redisplayed autokeep is known as an intellikeep. This feature can
often eliminate the need to set, then later remove, an explicit keep. It also
deletes any autokeeps that duplicate explicit keeps you have set. An
intellikeep is indicated by an asterisk (*) next to the variable name. For more
information, refer to the Xpediter/CICS Reference Manual.
2. On the COMMAND line, type KEEP WA-HOURS and press Enter.
To indicate that the keep was set, Xpediter/CICS places a K in column 9 on the line
where the data is defined and displays the following message:
*************** KEEP SET ***************
The value of WA-HOURS displays in the keep window when you execute the
program.
Breakpoints are set to halt execution of a program. They are set at any executable
verb and can be taken either before or after the statement is executed.
Set an unconditional breakpoint at the beginning of the program.
Xpediter/CICS automatically displays the data names in the current statement when
an abend or breakpoint is encountered during execution. Also, you can select any
number of data names to be displayed during execution (explicit keeps).
3. Type BEFORE 0 and press Enter.
To indicate that a before breakpoint was set, Xpediter/CICS places a B indicator in
column 9 for the entry statement in the program and displays the following message
as shown in Figure 3-7:
************ BEFORE SET ***************
3-6
Figure 3-7. Before Breakpoint Indicator and Message
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMCB2
*********************** BEFORE SET ************************
-------------------------------------------------------------------------->
000415
000416
000417
000418
*
000419
*END-EXEC.
000420 B
MOVE '
00301
' TO DFHEIV0
000421
000422
SERVICE LABEL
000423
000424
000425
*
SYSID(WS-SYSID)
000426
*
NOHANDLE
000427
*END-EXEC.
000428
MOVE '
00304
' TO DFHEIV0
000429
CALL 'DFHEI1' USING DFHEIV0 WS-SYSID.
000430
000431
000432
000433
IF EIBCALEN EQUAL ZERO
000434
1
NEXT SENTENCE
4. To see where keeps are set, type SHOW KEEPS and press Enter. See Figure 3-8. The K
indicates that a keep was set for WA-HOURS, and this data name appears in the keep
window when the program is executed.
Figure 3-8. Result of SHOW KEEPS Command
COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
-------------------------------------------------------------------------->
- - - - - - - - - - - - - - - - 91 LINE(S) NOT DISPLAYED
000086 K
05 WA-HOURS
PIC 999.
- - - - - - - - - - - - - - - - - 1715 LINE(S) NOT DISPLAYED
**************************** BOTTOM OF DATA **************************
5. To see where the breakpoint was set, type SHOW BREAKS and press Enter.
The Source Listing screen (Figure 3-9) displays all the breakpoints currently set in the
program. The B in column 9 indicates that you set a before breakpoint on the line
shown to halt the program before executing that line.
Figure 3-9. Result of SHOW BREAKS Command
COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
-------------------------------------------------------------------------->
000420 B
MOVE '
00301
' TO DFHEIV0
**************************** BOTTOM OF DATA **************************
6. To display all lines of the source code, type RESET and press Enter.
Now that you have set breakpoints and selected keeps, the program is ready to be
tested.
3-7
Executing Your COBOL Program
This example shows you how to execute the program to verify that your keeps and
breakpoints are properly set.
1. Type SET TRACE ON on the COMMAND line and press Enter to turn on the trace
facility.
2. Press Clear to return to CICS.
3. Type XCB2 and press Enter.
The Source Listing screen (2.L) displays the first breakpoint in the program as shown
in Figure 3-10. At this point, the program waits for your input to continue the
procedure.
Figure 3-10. First Pass Through the CWDEMCB2 Program


COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
K 02 WA-HOURS
999 NUM-DIS
095
01 DFHEIV0
X(77)
..................\.....
**END**
---------------------------------------------------- Before CWDEMCB2.420 ->
000415
000416
000417
000418
*
000419
*END-EXEC.
=====> B
MOVE '
00301
' TO DFHEIV0
000421
000422
SERVICE LABEL
000423
000424
000425
*
SYSID(WS-SYSID)
000426
*
NOHANDLE
000427
*END-EXEC.
000428
MOVE '
00304
' TO DFHEIV0
4. Type GO on the COMMAND line and press Enter (or use PF12) to continue
processing.
The XCB2 Demonstration Transaction screen is displayed as shown in Figure 3-11.
Figure 3-11. XCB2 Demonstration Transaction Screen
XCB2 _____ - ENTER EMPLOYEE NUMBER


ENTER DESIRED EMPLOYEE ABOVE:
00001 - CAUSES ASRA ABEND
00002 - CAUSES AEIM (AND OTHER ABENDS)
00003 - CAUSES A WRITE TO TEMPORARY STORAGE
00004 - STARTS UP XCB2 AS AN ASYNCHRONOUS TASK
00005 - USED TO SHOW MULTIPLE CSECT SUPPORT
00333 - CAUSES A STORAGE VIOLATION OF A SAA
00999 - ENDS NORMALLY
5. Type 00001 and press Enter.
C123
3-8
Again, the program pauses at the first statement. Notice the value of WA-HOURS. At
this point, the field is set to low values. The next command pinpoints where WAHOURS was set to $$$.
6. Type GO UNTIL WA-HOURS CHANGES and press Enter.
This causes the program to execute until the value of WA-HOURS changes. Once the
value of WA-HOURS changes, the Source Listing screen (2.L) displays the MOVE
statement that changed WA-HOURS. See Figure 3-12.
Figure 3-12. Source Listing Screen Showing MOVE Statement

COMMAND ===> GO UNTIL WA-HOURS CHANGES
SCROLL ===> CSR
MODULE: CWDEMCB2
****** "UNTIL" CONDITION MET, STEP EXECUTION HALTED *******
K 02 WA-HOURS
999 NUM-DIS
$$$
01 PAYROLL-DATA-EMP001
GROUP
NMR. DAVID ABEND456 MAIN
01 WORK-AREA
GROUP
**END**
-----000470
000471
000472
000473
000474
====>>
000476
000477
000478
000479
000480
000481
------------------------------------------------ After CWDEMCB2.475 ->
CALL 'DFHEI1' USING DFHEIV0 DUMMY-EMP DUMMY-LEN
1
1
1
1
MOVE DUMMY-PAYEMP1 TO PAYEMP1.
MOVE PAYROLL-DATA-EMP001 TO WORK-AREA
GO TO 300-EMPLOYEE-PAY-RTN.
GO TO 900-PROCESS-00002-SELECTION.
As shown in the MOVE statement, WORK-AREA is a group item that contains WAHOURS. PAYROLL-DATA-EMP001 is also a group item. Let’s take a closer look at this
group level to see where the $$$ came from.
7. Clear the COMMAND line by pressing EOF.
8. Place the cursor under the PAYROLL-DATA-EMP001 area of the keep window and
press PF8 to scroll PAYROLL-DATA-EMP001 to the top of the keep window.
9. To transfer to the Working Storage screen (2.3), type WS on the COMMAND line and
press Enter (the default PF key is PF16).
You should be positioned with PAYROLL-DATA EMP001 at the top of the screen as
shown in Figure 3-13.
3-9
Figure 3-13. Working Storage Screen (2.3)


-------------------- XPEDITER/CICS - WORKING STORAGE (2.3) ----------------C123
COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
LV
01
02
02
02
03
03
03
03
02
02
03
03
03
02
02
02
02
02
----- COBOL DATANAME ---------- -- ATTRIBUTES -PAYROLL-DATA-EMP001
GROUP
PAY001-TYPE
X
PAY001-NAME
X(15)
PAY001-ADDRESS
GROUP
PAY001-STREET
X(12)
PAY001-CITY
X(8)
PAY001-STATE
XX
PAY001-ZIP
X(5)
PAY001-RATE
9(3)V99 NUM-DIS
PAY001-DATE-EFF
GROUP
PAY001-DTEFF-MM
XX
PAY001-DTEFF-DD
XX
PAY001-DTEFF-YY
XX
PAY001-LST-PCT
9(3)V9 NUM-DIS
PAY001-TAX-RAT
9(3)V9 NUM-DIS
PAY001-YTD-GRS
S9(5)V99 NUM-DIS
PAY001-YTD-TAX
S9(5)V99 NUM-DIS
PAY001-HOURS
XXX
----+---10----+---20--->
N
MR. DAVID ABEND
456 MAIN ST.
HOMETOWN
MI
48010
00950
01
01
84
0110
0200
+1500000
+0300000
$$$
10. To change the value and set a keep, type K next to PAY001-HOURS, type 040 over
$$$, and press Enter.
11. Press PF6 (LOCATE *) to return to the Source Listing screen (2.L).
12. Type GT on the IF PAYEMP1 EQUAL '00001' line and press Enter. This command
moves the execution pointer (=====>) to that line and indicates that execution is to
be resumed there. See Figure 3-14.
Figure 3-14. Source Listing Screen Showing Result of Entering GT Line Command


COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMCB2
****************** GOTO STATEMENT 000474 ******************
K 02 PAY001-HOURS
XXX
040
03 PAYEMP1
X(5)
00001
**END**
-----000470
000471
000472
000473
=====>
000475
000476
000477
000478
000479
000480
000481
000482
000483
----------------------------------------------- Before CWDEMCB2.474 ->
CALL 'DFHEI1' USING DFHEIV0 DUMMY-EMP DUMMY-LEN
1
1
1
1
1
MOVE PAYROLL-DATA-EMP001 TO WORK-AREA
GO TO 300-EMPLOYEE-PAY-RTN.
Stepping Through Your COBOL Program
This procedure tests the program trace function, and demonstrates how to slow-step
through a program.
3-10
When you use the GO command without any parameters, the program resumes
execution at the current statement. When you add parameters specifying number of
statements and a delay interval, the GO command slow-steps through the program.
1. Type GO 5 1 on the COMMAND line and press Enter.
The GO command performs the following:
– The program executes five lines of code with a one second pause between each
statement.
– The execution pointer points to the current statement, which is highlighted.
– The data field area displays the data fields contained in the current statement
and those you have selected for viewing.
– The screen shows the statements that were executed, how many steps are
complete, and the program-level trace.
The Program Trace screen (2.4) displays the instructions that were executed during
your test and gives an instruction-by-instruction trace of the program execution. You
can use this trace to check the logic flow if you have set your TRACE option to ON.
For information on how to change the TRACE parameter (DEFTRAC), refer to
Chapter 4, “Global Parameters Table”.
2. To transfer to the Program Trace screen, type =2.4 and press Enter. (The default PF
key is PF17.)
As shown in Figure 3-15, this screen displays the execution of your program logic.
Figure 3-15. Program Trace Screen (2.4)
--------------------- XPEDITER/CICS - PROGRAM TRACE (2.4) -----------------C123
COMMAND ===>
SCROLL ===> CSR
COMPILED: 25 JUN 2002 - 16.58.54
TERM: 0265 ----------------------------------------------- Before CWDEMCB2.496
=======> TASK(00075) MODULE:CWDEMCB2 CSECT:CWDEMCB2
LANGUAGE:COBOL
<BRANCH>
000436
1
GO TO 200-RECEIVE-INPUT.
<BRANCH>
000457
200-RECEIVE-INPUT.
000458
*EXEC CICS HANDLE CONDITION
000459
*
LENGERR (500-MAPERR)
000460
*END-EXEC.
000461
MOVE '......................00329
' TO DFHEIV0
000462
000463
SERVICE LABEL
000464
GO TO 500-MAPERR DEPENDING ON DFHEIGDI.
<BRANCH>
000469
MOVE '..{........ ...00332
' TO DFHEIV0
000470
CALL 'DFHEI1' USING DFHEIV0 DUMMY-EMP DUMMY-LEN.
000471
000472
000473
000474
<RESUMED TO NEW LOCATION, STATEMENT
474
This screen shows the instructions that executed. The <BRANCH> indicates areas
where branches were taken. The message line displays the terminal ID and shows
where program execution stopped. The trace information is collected until the trace
option is turned off or the debugging session is ended. The task number, module
name, CSECT name, and language are provided to identify each task.
4. To resume execution, type GO (PF12) on the COMMAND line and press Enter.
3-11
Figure 3-16. Transaction Completion Screen

EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
040
HOURLY RATE:
9.50
GROSS PAY:
380.00

C123
Note: Always terminate Xpediter/CICS after completing a debugging session.
5. Type XPND on a blank CICS screen and press Enter.
Testing your Assembler Procedures
These procedures use the sample XASM transaction, which executes the CWDEMASM
Assembler program.
Note: Assembler support is optional. If you are unsure of your site’s status, contact your
Xpediter/CICS sales representative.






COMMAND ===>
MODULE:
CSECT:
0
1
2
5
7
SESSION PROFILE
SESSION CONTROL
FILE UTILITY
ABEND-AID FOR CICS
-
C
G
P
X
CODE COVERAGE
XCHANGE/CICS
CICSPLEX FACILITIES
EXIT
-
Exit Xpediter
NOTICE:
2. Press Clear to return to CICS so that you can start your transaction.
3-12
3. On a blank CICS screen, type XASM and press Enter.
The XASM Demonstration Transaction screen is displayed as shown in Figure 3-18.
Figure 3-18. XASM Demonstration Transaction Screen

XASM _____ - ENTER EMPLOYEE NUMBER
C123

ENTER
00001
00002
00003
00999
DESIRED EMPLOYEE ABOVE:
- CAUSES ASRA ABEND
- AEIM ABEND
- AEIP ABEND
- ENDS NORMALLY
The CWDEMASM test program is intercepted before CICS gets control of the abend,
then the Source Listing screen (2.L) is displayed as shown in Figure 3-19.
Notes:
a. If DUMP=YES is specified, an MVS snap dump is taken before Xpediter/CICS gets
control.
b. If the NO SOURCE AVAILABLE message or the NO TIMESTAMP message is
displayed, use the HELP command (the default PF key is PF1) for detailed
information. The Help screen lists the causes for the message and highlights the
most probable causes. Also review the output from the Compuware language
processor to verify that the source listing was successfully written to the source
listing file.
Figure 3-19. Assembler Source Listing Screen With Justification On


COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMASM CSECT: CWDEMASM
COMPILED: 09 JUN 2005 - 11.22
-------- DATA LABEL KEEPS -------- -- ATTRIBUTES -- ----+---10----+---20--->
CURRPAY
PL5
+9
WRKHOUR
PL3
?????
**END**
-----000599
000600
000601
000602
=====>
000604
000605
000606
000607
000608
000609
000610
000611
000612
----------------------------- ASRA (DATA EXCEPTION) at CWDEMASM.603 ->
MVC
CURRTAXS,ZEROS2
ZERO OUT CURRTAXS.
MVC
CURRPAY+4(1),WRKRATE MOVE WRKRATE INTO CURRPAY.
* IF 00001 WAS ENTERED, AN ASRA WILL
* OCCUR ON THE FOLLOWING INSTRUCTION....
MP
CURRPAY,WRKHOUR
MULTIPLY CURRPAY BY WRKHOUR.
MVC
CURRTAXS+2(5),CURRPAY MOVE CURRPAY INTO CURRTAXS.
MP
CURRTAXS,WRKTAX
MULTIPLY CURRTAXS BY WRKTAX.
AP
WRKYTDG,CURRPAY
ADD WRKYTDG TO CURRPAY.
AP
WRKYTDT,CURRTAXS
ADD WRKYTDT TO CURRTAXS.
SENDMAP2 LA
R0,PAYMAP2
MOVE
LH
R1,PAYMP2L
SPACES
LA
R14,SPACES2
TO
L
R15,=X'40000000'
MAP
MVCL R0,R14
TWO.
The module name, CSECT name, and assembly date and time of the displayed
program are shown at the top of the screen. The keep window appears next with all
the data items from the current statement displayed automatically. These are called
autokeeps.
3-13
The STATUS line contains messages and is displayed directly below the keep window.
The message displayed in the STATUS line in Figure 3-20 indicates the statement
number in CWDEMASM at which an ASRA has occurred.
The source statements follow the STATUS line. This section of the screen can be
scrolled by positioning the cursor anywhere on the screen outside the keep window.
An arrow (=====>) identifies the current statement.
Xpediter/CICS has the capability to display the OPCODE as well as just the source
statements.
5. To display the OPCODE, turn off justification by typing SET JUST OFF and pressing
Enter.
The display shows the offset and assembly from the source listing as shown in Figure
3-20.
Figure 3-20. Assembler Source Listing Screen (2.L) Showing Justification Off


COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
------- DATA LABEL KEEPS -------- -- ATTRIBUTES -- ----+---10----+---20--->
CURRPAY
PL5
+9
WRKHOUR
PL3
?????
**END**
-----000598
000599
000600
000601
000602
=====>
000604
000605
000606
000607
000608
000609
000610
000611
000240 D204 D267 D266
PROCESS MVC
CURRPAY,ZEROS1
ZERO OUT
000246 D206 D26D D26C
MVC
CURRTAXS,ZEROS2
ZERO OUT
00024C D200 D26B D24B
MVC
CURRPAY+4(1),WRKRATE MOVE WRK
000252 FC42 D267 D25A
MP
CURRPAY,WRKHOUR
MULTIPLY
000258 D204 D26F D267
MVC
CURRTAXS+2(5),CURRPAY MOVE CUR
00025E FC61 D26D D24C
MP
CURRTAXS,WRKTAX
MULTIPLY
000264 FA44 D24E D267
AP
WRKYTDG,CURRPAY
ADD WRKY
00026A FA66 D253 D26D
AP
WRKYTDT,CURRTAXS
ADD WRKY
000270 4100 D7A5
SENDMAP2 LA
R0,PAYMAP2
MOVE
000274 4810 D264
LH
R1,PAYMP2L
SPACES
000278 41E0 D7A4
LA
R14,SPACES2
TO
00027C 58F0 33F4
L
R15,=X'40000000'
MAP
Notice the value of WRKHOUR in the keep window. The bad data in this field (?????)
6. To correct this data, position the cursor on ????? in the keep window, type 00040,
and press Enter.
7. Type GO 1 on the COMMAND line and press Enter (the default PF key is PF9) to
execute one line of source.
Notice the changes to the values of the data fields in the keep window, as shown in
Figure 3-21. The values of the autokeeps change to reflect the values of the variables
in the current statement.
3-14
Figure 3-21. Assembler Source Listing Screen After Entering GO 1 Command


COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMASM
****** ASM-INST AT OFFSET 0252 EXECUTED STEP=00001 *******
------- DATA LABEL KEEPS -------- -- ATTRIBUTES -- ----+---10----+---20--->
CURRTAXS
PL7
?????????????
CURRPAY
PL5
+360
**END**
-----000598
000599
000600
000601
000602
000603
=====>
000605
000606
000607
000608
000609
000610
000611
----------------------------------------------- Before CWDEMASM.604 ->
000240 D204 D267 D266
PROCESS MVC
CURRPAY,ZEROS1
ZERO OUT
000246 D206 D26D D26C
MVC
CURRTAXS,ZEROS2
ZERO OUT
00024C D200 D26B D24B
MVC
000252 FC42 D267 D25A
MP
CURRPAY,WRKHOUR
MULTIPLY
000258 D204 D26F D267
MVC
00025E FC61 D26D D24C
MP
CURRTAXS,WRKTAX
MULTIPLY
000264 FA44 D24E D267
AP
WRKYTDG,CURRPAY
ADD WRKY
00026A FA66 D253 D26D
AP
WRKYTDT,CURRTAXS
ADD WRKY
000270 4100 D7A5
SENDMAP2 LA
R0,PAYMAP2
MOVE
000274 4810 D264
LH
R1,PAYMP2L
SPACES
000278 41E0 D7A4
LA
R14,SPACES2
TO
00027C 58F0 33F4
L
R15,=X'40000000'
MAP
8. Type GO on the COMMAND line and press Enter (the default PF key is PF12) to
continue the test.
When execution successfully completes, the Transaction Complete Screen is
Figure 3-22. XASM Transaction Complete Screen

EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
00040
HOURLY RATE:
9.00
GROSS PAY:
0000360.00

C123
To release all resources, exit from Xpediter/CICS after you complete a debugging
session.
In this procedure, you set keeps and breakpoints in the program.
1. On a blank CICS screen, type XPED CWDEMASM and press Enter. The Source Listing
screen (2.L) is displayed.
2. To clip the source code and display it without the OPCODE, turn on justification by
typing SET JUST ON and pressing Enter. The Source Listing screen (2.L) will appear as
3-15
Figure 3-23. Source Listing Screen (2.L) Showing Assembler Source
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
-------------------------------------------------------------------------->
000390
+
STM
14,12,12(13)
SAVE CALLER'S REGISTERS
@BBAC8
000391
+*********************************************************************
000392
+*
ESTABLISH CODE ADDRESSIBILITY
000393
+*********************************************************************
000394
+
USING *-4,3
@BBAC8
000395
+
LR
3,15
@BBAC8
000396
+*********************************************************************
000397
+*
OBTAIN DYNAMIC STORAGE
000398
+*********************************************************************
000399
+
BAL
1,*+8
@L
000400
+
DC
AL2(DFHEIEND-DFHEISTG) LENGTH OF STORAGE
@L
000401
+
DC
H'0'
IDENTIFIES CICS 1.7 LEVEL
@L
000402
+
L
15,=V(DFHEAI0)
@F8E1S @L
000403
+
BALR 14,15
OBTAIN STORAGE
@F8E1S @L
000404
+
ST
13,DFHEISA-DFHEISTG+4(,1) CHAIN TO CALLER'S @F8E1S @L
000405
+
LR
15,1
ADDRESS OF STORAGE
@F8E1S @L
000406
+
ICM
1,B'1111',24(13)
RESTORE INPUT REGISTER 1 @F8E1S @L
000407
+
BZ
*+10
IF ARGUMENT LIST EXISTS
@L
000408
+
MVC
DFHEIBP-DFHEISTG(L'DFHEIBP+L'DFHEICAP,15),0(1)
-----+
THEN COPY EIB AND CA PTRS
@L
Next, you will set an explicit keep for WRKHOUR so you can monitor its value and
view its effect on program execution. Explicit keeps are helpful when you want to
view the contents of a variable regardless of whether or not it participates in a
statement.
3. On the COMMAND line, type KEEP WRKHOUR and press Enter.
To indicate that the explicit keep was set, Xpediter/CICS places a K in column 9 on
the line where the data is defined and displays the following message:
*************** KEEP SET ***************
The value of WRKHOUR is displayed in the keep window when you execute the
program.
instruction and can be taken either before or after the statement is executed.
Next, you will set an unconditional breakpoint at the beginning of the program to
see the value of WRKHOUR.
4. Type BEFORE 0 and press Enter.
column 9 for the entry statement in the program (line 387) and displays the
following message:
************ BEFORE SET ***************
5. To see where keeps are set, type SHOW KEEPS and press Enter. See Figure 3-24. The K
indicates that a keep was set for WRKHOUR.
3-16
Figure 3-24. Showing Keeps on the Source Listing Screen (2.L)
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
-------------------------------------------------------------------------->
000179 K WRKHOUR DS
PL3
**************************** BOTTOM OF DATA **************************
6. To see where the breakpoints are set, type SHOW BREAKS and press Enter.
As shown in Figure 3-25, the Source Listing screen (2.L) shows all breakpoints that
were set. The B in column 9 indicates that a breakpoint was set before line 390 and
that the program is set to stop before this instruction is executed.
Figure 3-25. Source Listing Screen Showing Breakpoints
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
-------------------------------------------------------------------------->
000390 B +
STM
14,12,12(13)
@BBAC8
**************************** BOTTOM OF DATA **************************
7. To display all the lines of source code, type RESET and press Enter.
tested.
Executing Your Assembler Program
In this procedure, you will execute the program to verify that your keeps and breakpoints
are properly set.
1. To turn on the trace facility, type SET TRACE ON on the COMMAND line and press
Enter.
3. Type XASM and press Enter.
The first breakpoint in the program is displayed on the Source Listing screen (2.L) as
3-17
Figure 3-26. First Pass Through the CWDEMASM Program



COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
K WRKHOUR
PL3
?????
**END**
---------------------------------------------------- Before CWDEMASM.390 ->
000387
+*
PROLOG CODE FOR EXEC INTERFACE
000388
+*********************************************************************
000389
+CWDEMASM CSECT
@BBAC8
=====> B +
STM
14,12,12(13)
@BBAC8
000391
+*********************************************************************
000392
+*
000393
+*********************************************************************
000394
+
USING *-4,3
@BBAC8
000395
+
LR
3,15
@BBAC8
000396
+*********************************************************************
000397
+*
000398
+*********************************************************************
000399
+
BAL
1,*+8
@L
000400
+
DC
@L
4. Type GO on the COMMAND line and press Enter (or use PF12) to continue
processing.
The XASM Demonstration Transaction screen is displayed.
Again, the program pauses at the first statement, as seen in the following figure:
Figure 3-27. Source Listing Screen Showing First Breakpoint in the Program



COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
K WRKHOUR
PL3
?????
**END**
---------------------------------------------------- Before CWDEMASM.390 ->
000387
+*
PROLOG CODE FOR EXEC INTERFACE
000388
+*********************************************************************
000389
+CWDEMASM CSECT
@BBAC8
=====> B +
STM
14,12,12(13)
@BBAC8
000391
+*********************************************************************
000392
+*
000393
+*********************************************************************
000394
+
USING *-4,3
@BBAC8
000395
+
LR
3,15
@BBAC8
000396
+*********************************************************************
000397
+*
000398
+*********************************************************************
000399
+
BAL
1,*+8
@L
000400
+
DC
@L
6. Type GO and press Enter. Notice the value of WRKHOUR (?????). The next steps show
how to check the value of WRKHOUR, and how to correct the bad data.
3-18
Figure 3-28. Source Listing Screen Showing Statement Where Value of WRKHOUR Changes

COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
K WRKHOUR
PL3
?????
CURRPAY
PL5
+9
WRKHOUR
PL3
?????
**END**
-----000600
000601
000602
=====>
000604
000605
000606
000607
000608
000609
000610
000611
000612
000613
MVC
MP
CURRPAY,WRKHOUR
MVC
MP
CURRTAXS,WRKTAX
AP
WRKYTDG,CURRPAY
AP
WRKYTDT,CURRTAXS
SENDMAP2 LA
R0,PAYMAP2
MOVE
LH
R1,PAYMP2L
SPACES
LA
R14,SPACES2
TO
L
R15,=X'40000000'
MAP
MVCL R0,R14
TWO.
MVC
PAYTITL1,MAPTITL1
MOVE
Let’s take a closer look at where WRKHOUR is defined.
7. To transfer to the Defined Storage screen (2.3), type DS on the COMMAND line and
press Enter.
You should be positioned with WRKHOUR at the top of the screen as shown in Figure
3-29.
Figure 3-29. Defined Storage (2.3) Screen


-------------------- XPEDITER/CICS - DEFINED STORAGE (2.3) ----------------C123
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
-------- DATA LABEL -------------- -- ATTRIBUTES
K WRKHOUR
PL3
PAYMP1L
H
PAYMP1AL
H
PAYMP1BL
H
PAYMP2L
H
ZEROS1
X
CURRPAY
PL5
ZEROS2
X
CURRTAXS
PL7
RATEINCR
CL3
DUMMYLEN
H
DUMMYEMP
0CL8
CL3
DUMMYPAY
CL5
EMP001
0CL61
PAYTYPE1
C
PAYNAME1
CL15
PAYSTRT1
CL12
-- ----+---10----+---20--->
?????
'X 0050
'X 032E
'X 0332
'X 0370
'X 00
+9
'X 00
?????????????
000
'X 0008
. F00001
. F
00001
N
MR. DAVID ABEND
456 MAIN ST
8. To change the value of WRKHOUR, type 00040 over ????? and press Enter.
3-19
Figure 3-30. Source Listing Screen Showing Result of Entering GT Line Command

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMASM
***************** GOTO OFFSET X'00000252' *****************
K WRKHOUR
PL3
+40
CURRPAY
PL5
+9
WRKHOUR
PL3
+40
**END**
-----000600
000601
000602
=====>
000604
000605
000606
000607
000608
000609
000610
000611
000612
000613
MVC
MP
CURRPAY,WRKHOUR
MVC
MP
CURRTAXS,WRKTAX
AP
WRKYTDG,CURRPAY
AP
WRKYTDT,CURRTAXS
SENDMAP2 LA
R0,PAYMAP2
MOVE
LH
R1,PAYMP2L
SPACES
LA
R14,SPACES2
TO
L
R15,=X'40000000'
MAP
MVCL R0,R14
TWO.
MVC
PAYTITL1,MAPTITL1
MOVE
Stepping Through Your Assembler Program
This procedure tests slow-stepping through an Assembler program, and demonstrates the
program trace function.
1. Type GO 5 1 and press Enter.
This GO command performs the following as shown in Figure 3-31:
– The program executes five lines of code with a one-second pause between each
statement.
– A message shows the offset and the number of steps that have executed.
Figure 3-31. Source Listing Screen Showing Slow-Stepping

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMASM
****** ASM-INST AT OFFSET 026A EXECUTED STEP=00005 *******
K WRKHOUR
PL3
+40
* WRKYTDT
PL7
+10200
PAYMAP2
0CL880
*** COMPUWARE CORPORATIO
**END**
-----000600
000601
000602
000603
000604
000605
000606
000607
=====>
000609
000610
000611
000612
000613
----------------------------------------------- Before CWDEMASM.608 ->
MVC
MP
CURRPAY,WRKHOUR
MVC
MP
CURRTAXS,WRKTAX
AP
WRKYTDG,CURRPAY
AP
WRKYTDT,CURRTAXS
SENDMAP2 LA
R0,PAYMAP2
MOVE
LH
R1,PAYMP2L
SPACES
LA
R14,SPACES2
TO
L
R15,=X'40000000'
MAP
MVCL R0,R14
TWO.
MVC
PAYTITL1,MAPTITL1
MOVE
3-20
The Program Trace screen (2.4) displays the instructions that executed during your
test and gives an instruction-by-instruction trace of the program’s execution. You can
use this trace to check the logic flow if you have set your TRACE option to ON. For
information on how to change the TRACE parameter (DEFTRAC), refer to Chapter 4,
“Global Parameters Table”.
2. To transfer to the Program Trace screen (2.4), type =2.4 (the default PF key is PF17)
and press Enter.
The Program Trace screen (2.4) is displayed as shown in Figure 3-32.
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11.22
TERM: 0006 ----------------------------------------------- Before CWDEMASM.608
=======> TASK(00163) MODULE:CWDEMASM CSECT:CWDEMASM
LANGUAGE:ASSEMBLE
000510
000130 D204 D486 D27D
MVC
PAYEMP1,DUMMYPAY
STORE IN
000511
000136 D504 D486 34A6
CLC
PAYEMP1,=C'00001'
IS IT =
000512
00013C 4780 3230
BE
ASRAABND
YES, ASR
<BRANCH>
000595
000230 D23C D220 D282
ASRAABND MVC
WORKAREA,EMP001
MOVE BAD
000596
000236 47F0 3240
B
PROCESS
BRANCH T
<BRANCH>
000598
000240 D204 D267 D266
PROCESS MVC
CURRPAY,ZEROS1
ZERO OUT
000599
000246 D206 D26D D26C
MVC
CURRTAXS,ZEROS2
ZERO OUT
000600
00024C D200 D26B D24B
MVC
000601
000602
<ABEND "ASRA" HAS BEEN TRAPPED>
000603
000252 FC42 D267 D25A
MP
CURRPAY,WRKHOUR
MULTIPLY
000604
000258 D204 D26F D267
MVC
000605
00025E FC61 D26D D24C
MP
CURRTAXS,WRKTAX
MULTIPLY
000606
000264 FA44 D24E D267
AP
WRKYTDG,CURRPAY
ADD WRKY
000607
00026A FA66 D253 D26D
AP
WRKYTDT,CURRTAXS
ADD WRKY
******************************** BOTTOM OF DATA *******************************
option is turned off or the debugging session is ended. The task number, module
4. To resume execution, type GO (the default PF key is PF12) on the COMMAND line
and press Enter.
Figure 3-33. XASM Transaction Complete Screen

EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
00040
HOURLY RATE:
9.00
GROSS PAY:
0000360.00

C123
3-21
Testing Your PL/I Compile Procedures
These procedures use the sample XPLE transaction, which executes the CWDEMPE PL/I
test program.
Note: PL/I support is optional. If you are unsure of your site’s status, contact your






COMMAND ===>
MODULE:
CSECT:
0
1
2
5
7
SESSION PROFILE
SESSION CONTROL
FILE UTILITY
ABEND-AID FOR CICS
-
C
G
P
X
CODE COVERAGE
XCHANGE/CICS
CICSPLEX FACILITIES
EXIT
-
Exit Xpediter
NOTICE:
Xpediter/CICS is now ready to intercept any abends that may be in your program.
2. Press Clear to return to CICS to start your test.
3. On a blank CICS screen, type XPLE and press Enter.
The XPLE Demonstration Transaction screen is displayed as shown in Figure 3-35.
3-22
Figure 3-35. XPLE Demonstration Transaction Screen


XPLE _____ - ENTER EMPLOYEE NUMBER
C123
DEMONSTRATION TRANSACTION (PL/1)
ENTER
00001
00002
00003
00004
00005
00333
00999
DESIRED EMPLOYEE ABOVE:
- CAUSES ASRA ABEND (DATA EXCEPTION)
- CAUSES AEIM (DSIDERROR)
- CAUSES A WRITE TO TEMPORARY STORAGE
- STARTS UP XPLI AS AN ASYNCHRONOUS TASK
- USED TO SHOW MULTIPLE CSECT SUPPORT
- CAUSES A STORAGE VIOLATION OF A SAA
- ENDS NORMALLY
The CWDEMPE test program is intercepted before CICS gets control of the abend,
and the Source Listing screen (2.L) is displayed as shown in Figure 3-36.
Note: If the NO SOURCE AVAILABLE message is displayed, use the HELP command
(the default PF key is PF1) for detailed information. The Help screen lists the
causes for the No Source Available (NSA) message and highlights the most
probable causes. Also review the output from the Compuware language
processor to verify that the source listing was successfully written to the
source listing file.
Figure 3-36. PL/I Source Listing Screen Showing ASRA

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMPE CSECT: CWDEMPE
COMPILED: 11 AUG 2006 - 10:51:01
LV ---- PL/I VARIABLE KEEPS ----- -- ATTRIBUTES -- ----+---10----+---20--->
CURR_PAY
FIXED DEC(7,2)
0.00
02 WA_HOURS
PIC'999'
$$$
02 WA_RATE
FIXED DEC(5,2)
9.50
**END**
-----000839
000840
000841
=====>
000843
000844
000845
000846
000847
000848
000849
000850
000851
000852
------------------------------ ASRA (DATA EXCEPTION) at CWDEMPE.842 ->
SELECT(WA_TYPE);
WHEN('N','I','S')
DO;
CURR_PAY
= WA_HOURS * WA_RATE ;
CURR_TAXES = CURR_PAY * WA_TAX_RAT ;
WA_YTD_GRS = CURR_PAY + WA_YTD_GRS ;
WA_YTD_TAX = CURR_TAXES + WA_YTD_TAX ;
END ;
OTHERWISE;
END;
L400_TRANSACTION_COMPLETE:
EMPNUMB = PAYEMP1 ;
The module name, CSECT name, and compile date and time of the displayed
program are shown at the top of the screen.
The keep window is displayed below the program information.
use the assigned PF keys to scroll up, down, left, and right. The default PF keys are
The STATUS line is displayed after the keep window. The message displayed in Figure
3-36 indicates that an ASRA abend was intercepted at statement 837 in CWDEMPE.
3-23
the cursor anywhere on the screen outside of the keep window. An arrow indicates
the current statement.
Notice the value of WA_HOURS in the keep window. The bad data in this field ($$$)
5. To correct the data, position the cursor on the $$$ in the keep window, type 040, and
press Enter.
6. Type GO 1 (the default PF key is PF9) on the COMMAND line and press Enter to
execute one statement.
Notice the changes to the values in the keep window as shown in Figure 3-37.
Figure 3-37. Source Listing Screen After GO 1 Command

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMPE
STEP=00001 *******
*
CURR_PAY
FIXED DEC(7,2)
380.00
CURR_TAXES
FIXED DEC(7,2)
0.00
02 WA_TAX_RAT
FIXED DEC(4,1)
0.2
**END**
-----000839
000840
000841
000842
=====>
000844
000845
000846
000847
000848
000849
000850
000851
000852
------------------------------------------------ Before CWDEMPE.843 ->
SELECT(WA_TYPE);
WHEN('N','I','S')
DO;
CURR_PAY
END ;
OTHERWISE;
END;
7. Type GO (the default PF key is PF12) on the COMMAND line and press Enter to
continue the test.
Figure 3-38. XPLE Transaction Complete Screen

EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
040
HOURLY RATE:
9.50
GROSS PAY:
380.00

To release all resources, always shut down Xpediter/CICS after completing a
debugging session.
C123
3-24
In this procedure, you will set keeps and breakpoints in the program source.
1. On a blank CICS screen, type XPED CWDEMPE and press Enter.
Figure 3-39. Source Listing Screen (2.L) for the Sample Program CWDEMPE
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11:23:48
-------------------------------------------------------------------------->
000361
CALL DFHENTRY_BF3CF5BF_B4ED7F82('
. ................00000315' /
000362
'02 06 80 00 03 05 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F0
000363
0 F0 F0 F0 F3 F1 F5 'X */,L800_RETURN_TO_CICS);
000364
END;
000365
000366
/* EXEC CICS ASSIGN
000367
SYSID(WS_SYSID)
000368
NOHANDLE */
000369
DO;
000370
DCL DFHENTRY_BF3CF5BF_B50D4442 BASED(ADDR(DFHEI0)) OPTIONS(INTER A
000371
EMBLER) ENTRY(*,*);
000372
CALL DFHENTRY_BF3CF5BF_B50D4442('
. ................00000318' /
000373
'02 08 80 00 23 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F0
000374
0 F0 F0 F0 F3 F1 F8 'X */,WS_SYSID);
000375
END;
000376
000377
/* ---------------------------------------------------------------- *
000378
L000_FIXED_POINT:;
000379
DCL FIXED_BIN15A
FIXED BIN(15,7) SIGNED ;
000380
DCL FIXED_BIN31A
FIXED BIN(31,7) SIGNED ;
Xpediter/CICS automatically displays the variables in the current statement when an
abend or breakpoint is encountered during execution. You may also select any
number of variables to be displayed during execution (explicit keeps). Explicit keeps
are helpful when you want to view the contents of a variable regardless of whether or
not it participates in a statement.
By setting a keep on WA_HOURS, you can monitor its value and check its effect on
the program execution.
2. Type FIND FIRST WA_HOURS on the COMMAND line and press Enter.
The display is positioned to the DCL for WA_HOURS.
3. Type a K in the statement number field next to WA_HOURS and press Enter.
where the data is defined, as shown in Figure 3-40, and displays the following
message:
*************** KEEP SET ***************
The value of WA_HOURS will be displayed in the keep window when you execute the
program.
3-25
Figure 3-40. Source Listing Screen Showing Where Data is Defined
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMPE
************************ KEEP set *************************
-------------------------------------------------------------------------->
000142
05 WA_YTD_TAX FIXED DEC(7,2),
000143 K
05 WA_HOURS
PIC'999',
000144
05 WA_MSG
CHAR(26);
000145
DCL WA_PTR
POINTER ;
000146
000147
DCL 01 VSAM_EMP_RECORD,
000148
05 EMP_NUM_KEY
CHAR(5) INIT(''),
000149
05 EMP_NAME
CHAR(15) INIT(''),
000150
05 EMP_HOURS
PIC 'ZZZ' INIT(''),
000151
05 EMP_TOTPAY
PIC 'ZZZZZVZZ' INIT(''),
000152
05 FILLER
CHAR(50) INIT('') ;
000153
000154
DCL 01 EMP_RECORD_TABLE,
000155
03 EMP_RECORD_TBL(5),
000156
05 EMP_NUM_KEY_TBL CHAR(5) INIT('','','','',''),
000157
05 EMP_NAME_TBL
CHAR(15) INIT('','','','',''),
000158
05 EMP_HOURS_TBL
FIXED DEC(3) INIT('','','','',''),
000159
05 EMP_TOTPAY_TBL
FIXED DEC(7,2) INIT('','','','','');
000160
000161
DCL 01 EMP_RECORD_LIST,
verb and can be taken either before or after the statement is executed. The following
example shows you how to set a breakpoint to halt execution before the selected
statement is executed.
4. Type RFIND (the default PF key is PF5) on the COMMAND line, move the cursor
down past the DCL for WA_HOURS, and press Enter to position the display to the
next occurrence of WA_HOURS (statement 837) as shown in Figure 3-41.
Figure 3-41. Result of Entering RFIND Command
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11:23:48
-------------------------------------------------------------------------->
000836
DO;
000837
CURR_PAY
000838
000839
000840
000841
END ;
000842
OTHERWISE;
000843
END;
000844
000845
000846
000847
000848
EMPNAME = WA_NAME ;
000849
HRSWRKD = WA_HOURS ;
000850
HRLYRAT = WA_RATE ;
000851
GROSPAY = CURR_PAY ;
000852
GOTO SEND_PAYMAP2 ;
000853
000854
L500_MAPERR:
000855
5. Type B on the statement number (837) and press Enter to set an unconditional before
breakpoint — the program pauses before this statement is executed.
column 9 for the statement and displays the following message:
************ BEFORE SET ***************
3-26
6. Type K3 on the statement number (837) and press Enter to set a keep on the third
variable in the line (WA_RATE).
7. Type BEFORE 0 on the COMMAND line and press Enter to set a breakpoint on the
first program line.
8. To see where the breakpoints were set, type SHOW BREAKS and press Enter.
were set and the procedures for which they were set.
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11:23:48
-------------------------------------------------------------------------->
000359 B ; CALL DFHTNNA1('
. ................00000315' /* '02 06 80 00 03
000837 B
CURR_PAY
**************************** BOTTOM OF DATA **************************
9. To see the keeps that were set, type SHOW KEEPS and press Enter. See Figure 3-43.
Figure 3-43. Source Listing Screen Showing Keeps
COMMAND ===>
SCROLL ===> CSR
COMPILED: 11 AUG 2006 - 10:51:01
-------------------------------------------------------------------------->
000134 K
05 WA_RATE
FIXED DEC(5,2),
- - - - - - - - - - - - - - - - - - 8 LINE(S) NOT DISPLAYED
000143 K
05 WA_HOURS
PIC'999',
**************************** BOTTOM OF DATA **************************
10. Type RESET and press Enter to display all source lines.
tested.
Executing Your PL/I Program
are properly set.
Enter.
3. Type XPLE and press Enter.
3-27
Figure 3-44. Source Listing Screen Showing Before Breakpoint at First Statement


COMMAND ===>
SCROLL ===> CSR
COMPILED: 11 AUG 2006 - 10:51:01
K 02 WA_HOURS
PIC'999'
<<
INVALID PTR(0)
>>
K 02 WA_RATE
FIXED DEC(5,2)
<<
INVALID PTR(0)
>>
**END**
----------------------------------------------------- Before CWDEMPE.361 ->
000358
DO;
000359
DCL DFHENTRY_BF3CF5BF_B4ED7F82 BASED(ADDR(DFHEI0)) OPTIONS(INTER A
000360
=====> B
CALL DFHENTRY_BF3CF5BF_B4ED7F82('
. ................00000315' /
000362
'02 06 80 00 03 05 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F0
000363
0 F0 F0 F0 F3 F1 F5 'X */,L800_RETURN_TO_CICS);
000364
END;
000365
000366
/* EXEC CICS ASSIGN
000367
SYSID(WS_SYSID)
000368
NOHANDLE */
000369
DO;
000370
DCL DFHENTRY_BF3CF5BF_B50D4442 BASED(ADDR(DFHEI0)) OPTIONS(INTER A
000371
4. Type GO (PF12) on the COMMAND line and press Enter to continue processing.
The XPLE Demonstration Transaction screen is displayed.
Again, the program pauses at the first statement as shown in Figure 3-44.
Look at the value for WA_HOURS in the keep window. << INVALID PTR(0) >>
indicates that WA_HOURS is part of a based variable that depends on a pointer that is
not initialized.
6. Type FIND WA_HOURS PREV and press Enter to see where WA_HOURS is declared.
7. Scroll back (the default PF key is PF7) to the declaration of the structure
(WORK_AREA) and notice that the structure is based on WA_PTR. (See Figure 3-45).
Figure 3-45. Source Listing Screen Showing WORK_AREA Declaration


COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11:23:48
K 02 WA_HOURS
PIC'999'
$$$
K 02 WA_RATE
FIXED DEC(5,2)
9.50
**END**
-----000115
000116
000117
000118
000119
000120
000121
000122
000123
000124
000125
000126
000127
000128
----------------------------------------------- Before CWDEMPE.359 ->
10 PAY999_DTEFF_MM CHAR(2) INIT('01'),
10 PAY999_DTEFF_DD CHAR(2) INIT('01'),
10 PAY999_DTEFF_YY CHAR(2) INIT('84'),
05 PAY999_LST_PCT FIXED DEC(4,1) INIT(00.11),
05 PAY999_TAX_RAT FIXED DEC(4,1) INIT(00.20),
05 PAY999_YTD_GRS FIXED DEC(7,2) INIT(+15000.00),
05 PAY999_YTD_TAX FIXED DEC(7,2) INIT(+03000.00),
05 PAY999_HOURS
PIC'999'
INIT(040),
05 PAY999_MSG
CHAR(26)
INIT(' ');
DCL
01 WORK_AREA BASED(WA_PTR),
05 WA_TYPE
CHAR (1),
05 WA_NAME
CHAR (15),
05 WA_ADDRESS,
8. On the COMMAND line, type GO UNTIL WA_PTR CHANGES and press Enter.
3-28
This causes the program to execute until the value of WA_PTR changes as shown in
Figure 3-46.
Figure 3-46. Source Listing Screen Showing Changed Value
COMMAND ===> GO UNTIL WA_PTR CHANGES
SCROLL ===> CSR
MODULE: CWDEMPE
****** "UNTIL" condition met, step execution halted *******
LV ----- PL/I VARIABLE KEEPS ----- -- ATTRIBUTES -- ----+---10----+---20--->
K 02 WA_HOURS
PIC'999'
$$$
K 02 WA_RATE
FIXED DEC(5,2)
9.50
K
WA_PTR
PTR ALIGN
'X 0020683C
01 PAYROLL_DATA_EMP001
GROUP
**END**
------------------------------------------------------ After CWDEMPE.804 ->
000801
000802
IF PAYEMP1 = '00001'
000803
THEN DO;
====>>
WA_PTR
= ADDR(PAYROLL_DATA_EMP001) ;
000805
GOTO L300_EMPLOYEE_PAY_RTN;
000806
END ;
000807
000808
IF PAYEMP1 = '00002'
000809
THEN GOTO L900_PROCESS_00002_SELECTION;
000810
000811
IF PAYEMP1 = '00003'
000812
THEN GOTO L950_PROCESS_00003_SELECTION;
000813
000814
IF PAYEMP1 = '00004'
As shown in the current statement, PAYROLL_DATA_EMP001 is a group item that
contains the $$$ data. Transferring to the Variable Storage screen (2.3) lets you get a
more detailed look at this field. Notice that both fields involved in the current
statement are also displayed in the keep window.
9. Clear the COMMAND line by pressing Erase EOF.
10. Position the cursor in the keep window on PAYROLL_DATA_EMP001 and scroll (PF8)
to move this field to the top of the display.
11. To transfer to the Variable Storage screen (2.3), type =2.3 on the COMMAND line and
press Enter.
PAYROLL_DATA_EMP001 should be positioned at the top of the screen as shown in
Figure 3-47. The first item in the keep window is always displayed first on the
Variable Storage screen (2.3).
Look at the value of PAY001_HOURS at the bottom of the screen. This is where $$$
originated.
3-29
Figure 3-47. Variable Storage (2.3) Screen

-------------------- XPEDITER/CICS - VARIABLE STORAGE (2.3) ---------------C123
COMMAND ===>
SCROLL ===> CSR
COMPILED: 11 AUG 2006 - 10:51:01
PROCEDURE: CWDEMPE
LV ---- PL/I VARIABLE ----------01 PAYROLL_DATA_EMP001
02 PAY001_TYPE
02 PAY001_NAME
02 PAY001_ADDRESS
03 PAY001_STREET
03 PAY001_CITY
03 PAY001_STATE
03 PAY001_ZIP
02 PAY001_RATE
02 PAY001_DATE_EFF
03 PAY001_DTEFF_MM
03 PAY001_DTEFF_DD
03 PAY001_DTEFF_YY
02 PAY001_LST_PCT
02 PAY001_TAX_RAT
02 PAY001_YTD_GRS
02 PAY001_YTD_TAX
02 PAY001_HOURS
-- ATTRIBUTES -GROUP
CHAR(1)
CHAR(15)
GROUP
CHAR(12)
CHAR(8)
CHAR(2)
CHAR(5)
FIXED DEC(5,2)
GROUP
CHAR(2)
CHAR(2)
CHAR(2)
FIXED DEC(4,1)
FIXED DEC(4,1)
FIXED DEC(7,2)
FIXED DEC(7,2)
CHAR(3)
----+---10----+---20--->
N
MR. DAVID ABEND
456 MAIN ST.HOMETOWNMI48
456 MAIN ST.
HOMETOWN
MI
48010
9.50
010184
01
01
84
0.1
0.2
15000.00
3000.00
$$$
12. Type K to the left of PAY001_HOURS.
13. Correct the value by typing 040 over the $$$ and pressing Enter.
Stepping Through Your PL/I Program
This procedure tests slow-stepping through a program and the program trace function.
This GO command performs the following:
– Individual lines of code are executed with a one-second pause between each
statement, except when a breakpoint is encountered.
– The data fields contained in the current statement, as well as those you have
selected for viewing, are displayed in the keep window.
– The screen shows the executed statements and the number of completed steps.
– Before all five statements can be executed, the breakpoint set previously is
encountered as shown in Figure 3-48.
3-30
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMPE
*********BREAKPOINT ENCOUNTERED, STEPPING HALTED **********
K 02 PAY001_HOURS
CHAR(3)
$$$
CURR_PAY
FIXED DEC(7,2)
0.00
02 WA_HOURS
PIC'999'
$$$
02 WA_RATE
FIXED DEC(5,2)
9.50
**END**
----------------------------------------------------- Before CWDEMPE.837 ->
000836
DO;
=====> B
CURR_PAY
000838
000839
000840
000841
END ;
000842
OTHERWISE;
000843
END;
000844
000845
000846
000847
000848
EMPNAME = WA_NAME ;
000849
HRSWRKD = WA_HOURS ;
on the COMMAND line and press Enter.
COMMAND ===>
SCROLL ===> CSR
COMPILED: 09 JUN 2005 - 11:23:48
TERM: 0008 ------------------------------------------------ Before CWDEMPE.842
=======> TASK(00139) MODULE:CWDEMPE CSECT:CWDEMPE
LANGUAGE:PL/I
000784
/* EXEC CICS HANDLE CONDITION
000785
LENGERR (L500_MAPERR) */
000786
DO;
000788
000789
CALL DFHENTRY_BF3CF5BF_BA8BB104('......................00000722'
<BRANCH>
000800
CALL DFHENTRY_BF3CF5BF_BAA34444('..{........ ...00000725' /* '04
<BRANCH>
000805
PAYEMP1 = DUMMY_PAYEMP1;
000807
IF PAYEMP1 = '00001'
000808
THEN DO;
000809
WA_PTR
= ADDR(PAYROLL_DATA_EMP001) ;
000810
GOTO L300_EMPLOYEE_PAY_RTN;
<BRANCH>
000837
L300_EMPLOYEE_PAY_RTN:
000839
SELECT(WA_TYPE);
<BRANCH>
000842
CURR_PAY
******************************** BOTTOM OF DATA *******************************
option is turned off of the debugging session is ended. The task number, module
3-31
and press Enter.
Figure 3-50. XPLE Transaction Complete Screen

EMPLOYEE NAME:
MR. DAVID ABEND
HOURS WORKED:
040
HOURLY RATE:
9.50
GROSS PAY:
380.00

C123
Testing Your C Compile Procedures
These procedures use the sample XCCC transaction, which executes the CWDEMC C test
program.
Note: C support is optional. If you are unsure of your site’s status, contact your
3-32






COMMAND ===>
MODULE:
CSECT:
0
1
2
5
7
SESSION PROFILE
SESSION CONTROL
FILE UTILITY
ABEND-AID FOR CICS
-
C
G
P
X
CODE COVERAGE
XCHANGE/CICS
CICSPLEX FACILITIES
EXIT
-
Exit Xpediter
NOTICE:
Xpediter/CICS is now ready to intercept any abends that may be in your program.
2. Press Clear to return to CICS to start your test.
3. On a blank CICS screen, type XCCC and press Enter.
The XCCC Demonstration Transaction screen is displayed as shown in Figure 3-52.
Figure 3-52. XCCC Demonstration Transaction Screen
XCCC _____ - ENTER EMPLOYEE NUMBER

*** Compuware Corporation ***
Demonstration Transaction (C)

Enter desired employee above:

00001 - Causes ASRA Abend

00003 - Causes a write to temporary storage
00004 - Starts up XCCC as an asynchronous task
00005 - Used to show multiple CSECT support: ASM subroutine
00006 - Used to show multiple CSECT support: C subroutine
00007 - Used to show multiple MODULE support: C fetchable subroutine
C123
The CWDEMC test program is intercepted before CICS gets control of the abend, and
the Source Listing screen (2.L) is displayed as shown in Figure 3-53.
Note: If the NO SOURCE AVAILABLE message is displayed, use the HELP command
(the default PF key is PF1) for detailed information. The Help screen lists the
causes for the No Source Available (NSA) message and highlights the most
probable causes. Also review the output from the Compuware language
processor to verify that the source listing was successfully written to the
source listing file.
3-33
Figure 3-53. C Source Listing Screen Showing ASRA

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
LV ----- C VARIABLE KEEPS -------- -- ATTRIBUTES -- ----+---10----+---20--->
dGrossPay
decimal
+0
dHoursWorked
decimal
???
dHourlyRate
decimal
+525
**END**
-----010345
010346
010347
=====>
010349
010350
010351
010352
010352
010353
010354
010354
010355
010356
----------------------------- ASRA (DATA EXCEPTION) at CWDEMC.10348 ->
|
| dTaxRate
= pPayrollParms -> dCurrentTaxRate;
|
| dGrossPay
= dHoursWorked * dHourlyRate;
|
| dGrossTax
= dGrossPay * dTaxRate / 100.0d;
|
| memset ( chConvertBuffer, Null, sizeof (chConvertBuffer) );
+ __memset(chConvertBuffer,'\0',sizeof (chConvertBuffer));
|
| memcpy ( chConvertBuffer,
+
|
WsPayrollWorkArea.YearToDatePay,
|
sizeof (WsPayrollWorkArea.YearToDatePay) );
The module name, CSECT name, and compile date and time of the displayed
program are shown at the top of the screen.
The keep window is displayed below the program information.
use the assigned PF keys to scroll up, down, left, and right. The default PF keys are
The STATUS line is displayed after the keep window. The message displayed in Figure
3-53 indicates that an ASRA abend was intercepted at statement 10348 in CWDEMC.
the cursor anywhere on the screen outside of the keep window. An arrow indicates
the current statement.
Notice the value of dHoursWorked in the keep window. The bad data in this field
(shown as ??? to indicate invalid decimal data) is causing the ASRA.
5. To correct the data, position the cursor on the ??? in the keep window, type 40, and
press Enter.
6. Type GO 1 (the default PF key is PF9) on the COMMAND line and press Enter to
execute one statement.
Notice the changes to the values in the keep window as shown in Figure 3-54.
3-34
Figure 3-54. Source Listing Screen After GO 1 Command

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
STEP=00001 *******
dGrossTax
decimal
+0
dGrossPay
decimal
+21000
dTaxRate
decimal
+150
**END**
-----010345
010346
010347
010348
010349
=====>
010351
010352
010352
010353
010354
010354
010355
010356
----------------------------------------------- Before CWDEMC.10350 ->
|
| dTaxRate
= pPayrollParms -> dCurrentTaxRate;
|
| dGrossPay
= dHoursWorked * dHourlyRate;
|
| dGrossTax
= dGrossPay * dTaxRate / 100.0d;
|
| memset ( chConvertBuffer, Null, sizeof (chConvertBuffer) );
+ __memset(chConvertBuffer,'\0',sizeof (chConvertBuffer));
|
| memcpy ( chConvertBuffer,
+
|
WsPayrollWorkArea.YearToDatePay,
|
sizeof (WsPayrollWorkArea.YearToDatePay) );
7. Type GO (the default PF key is PF12) on the COMMAND line and press Enter to
continue the test.
Figure 3-55. XCCC Transaction Complete Screen

Employee Number: 00001
Employee Name:
Mr. David Abend
Hours Worked:
40
Hourly Rate:
5.25
Gross Pay:
210.00

*** Transaction XCCC complete ***
To release all resources, always shut down Xpediter/CICS after completing a
debugging session.
In this procedure, you will set keeps and breakpoints in the program source.
1. On a blank CICS screen, type XPED CWDEMC and press Enter.
3-35
Figure 3-56. Source Listing Screen (2.L) for the Sample Program CWDEMC
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
-------------------------------------------------------------------------->
008745
| CALLTYPE
CallType
= CallInternal;
008746
|
008747
| CHAR
szPrintBufferÝ256¨ = { Null, };
008747
+ CHAR
szPrintBufferÝ256¨ = { '\0', };
008748
|
008749
| PAYMAP1
*pPayMap1
= NULL;
008749
+ PAYMAP1
*pPayMap1
= ((void *)0);
008750
| PAYMAP2
*pPayMap2
= NULL;
008750
+ PAYMAP2
*pPayMap2
= ((void *)0);
008751
|
008752
| PCHAR
pCommPtr
= NULL;
008752
+ PCHAR
pCommPtr
= ((void *)0);
008753
|
008754
| SHORT
i
= 0;
008755
| SHORT
j
= 0;
008756
|
008757
| /******************************************************************
008758
| /* End of automatic variable definitions for main function
008759
| /******************************************************************
008760
|
Xpediter/CICS automatically displays the variables in the current statement when an
abend or breakpoint is encountered during execution. You may also select any
number of variables to be displayed during execution (explicit keeps). Explicit keeps
are helpful when you want to view the contents of a variable regardless of whether or
not it participates in a statement.
By setting a keep on dHoursWorked, you can monitor its value and check its effect
on the program execution.
2. Type FIND FIRST dHoursWorked on the COMMAND line and press Enter.
The display is positioned to the declaration for dHoursWorked.
3. Type a K in the statement number field next to dHoursWorked and press Enter.
where the data is defined, as shown in Figure 3-57, and displays the following
message:
*************** KEEP SET ***************
The value of dHoursWorked will be displayed in the keep window when you execute
the program.
3-36
Figure 3-57. Source Listing Screen Showing Where Data is Defined
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
************************ KEEP SET *************************
-------------------------------------------------------------------------->
010246
|
010247 K | decimal(3,0)
dHoursWorked
= 0d;
010247
+ _Decimal(3,0)
dHoursWorked
= 0d;
010248
| decimal(7,2)
dHourlyRate
= 0.00d;
010248
+ _Decimal(7,2)
dHourlyRate
= 0.00d;
010249
| decimal(5,1)
dTaxRate
= 0.0d;
010249
+ _Decimal(5,1)
dTaxRate
= 0.0d;
010250
| decimal(11,2)
dGrossPay
= 0.00d;
010250
+ _Decimal(11,2)
dGrossPay
= 0.00d;
010251
| decimal(11,2)
dYTDPay
= 0.00d;
010251
+ _Decimal(11,2)
dYTDPay
= 0.00d;
010252
| decimal(9,2)
dGrossTax
= 0.00d;
010252
+ _Decimal(9,2)
dGrossTax
= 0.00d;
010253
| decimal(9,2)
dYTDTax
= 0.00d;
010253
+ _Decimal(9,2)
dYTDTax
= 0.00d;
010254
|
010255
| CHAR
chConvertBuffer Ý16¨ = { Null, };
010255
+ CHAR
chConvertBuffer Ý16¨ = { '\0', };
010256
|
010257
| /******************************************************************
verb and can be taken either before or after the statement is executed. The following
example shows you how to set a breakpoint to halt execution before the selected
statement is executed.
4. Type RFIND (the default PF key is PF5) on the COMMAND line, move the cursor
down past the declaration for dHoursWorked, and press Enter to position the
display to the next occurrence of dHoursWorked (statement 10280) as shown in
Figure 3-58.
Figure 3-58. Result of Entering RFIND Command
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
-------------------------------------------------------------------------->
010279
|
010280
| if ( sscanf ( chConvertBuffer, "%D(3,0)", &dHoursWorked ) == 0 )
010281
| {
010282
|
if ( sWsEmployeeNumber == 1 )
010283
|
{
010284
|
memcpy ( (char *) &dHoursWorked,
010284
+
010285
|
WsPayrollWorkArea.HoursWorked,
010286
|
sizeof (WsPayrollWorkArea.HoursWorked) );
010286
+__memcpy((char *) &dHoursWorked,WsPayrollWorkArea.HoursWorked,sizeof
010286
+ed));
010287
|
}
010288
|
else
010289
|
{
010290
|
ErrorMsg ( "Bad data in Hours Worked field" );
010291
|
}
010292
| }
010293
| else
010294
| {
010295
|
pPayrollParms -> dCurrentHours = dHoursWorked;
5. Type B on the statement number (10280) and press Enter to set an unconditional
before breakpoint — the program pauses before this statement is executed.
column 9 for the statement and displays the following message:
3-37
************ BEFORE SET ***************
6. Type K1 on the statement number (10280) and press Enter to set a keep on the first
variable in the line (chConvertBuffer).
7. Type BEFORE 0 on the COMMAND line and press Enter to set a breakpoint on the
first program line.
8. To see where the breakpoints were set, type SHOW BREAKS and press Enter.
were set.
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
-------------------------------------------------------------------------->
008745 B | CALLTYPE
CallType
= CallInternal;
010280 B | if ( sscanf ( chConvertBuffer, "%D(3,0)", &dHoursWorked ) == 0 )
**************************** BOTTOM OF DATA **************************
9. To see the keeps that were set, type SHOW KEEPS and press Enter. See Figure 3-60.
Figure 3-60. Source Listing Screen Showing Keeps Before SET TRANSLATE Commands
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
-------------------------------------------------------------------------->
- - - - - - - - - - - - - - - 11078 LINE(S) NOT DISPLAYED
010247 K | decimal(3,0)
dHoursWorked
= 0d;
010255 K | CHAR
chConvertBuffer Ý16¨ = { Null, };
**************************** BOTTOM OF DATA **************************
Depending on the code page used by your terminal, line 10255 in figure 3-60 may show
brackets around the number 16 or it may show other characters, such as the symbol for
Yen currency before the 16 and an umlaut following the 16. This occurs when the C
complier was told to use code page 1047 and your terminal is using a different code page.
The Yen currency and umlaut characters are from code page 037. If you experience this
problem, use the SET TRANSLATE primary command to correct it. For code page 037,
enter the following two primary commands:
SET TRANSLATE AD BA
SET TRANSLATE BD BB
If your terminal uses a code page other than 037, replace the BA and BB above with that
code page’s hexadecimal representation for open bracket and close bracket.
If the listing uses a code page other than 1047, replace the AD and BD above with that
code page’s hexadecimal representation for open bracket and close bracket.
When you have properly set up your profile’s output translate table, the Source Listing
screen showing keeps should look like this:
3-38
Figure 3-61. Source Listing Screen Showing Keeps After SET TRANSLATE Commands
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
-------------------------------------------------------------------------->
- - - - - - - - - - - - - - - 11078 LINE(S) NOT DISPLAYED
010247 K | decimal(3,0)
dHoursWorked
= 0d;
010255 K | CHAR
chConvertBuffer [16] = { Null, };
**************************** BOTTOM OF DATA **************************
10. Type RESET and press Enter to display all source lines.
tested.
Executing Your C Program
are properly set.
Enter.
3. Type XCCC and press Enter.
Figure 3-62. Source Listing Screen Showing Before Breakpoint at First Statement

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
K
dHoursWorked
decimal
<< Out of scope >>
K
chConvertBuffer
char[16]
CallType
enum
<< Not initialized >>
**END**
----------------------------------------------------- Before CWDEMC.8745 ->
008742
| /* Start of automatic variable definitions for main function
008743
| /******************************************************************
008744
|
=====> B | CALLTYPE
CallType
= CallInternal;
008746
|
008747
| CHAR
szPrintBuffer[256] = { Null, };
008747
+ CHAR
szPrintBuffer[256] = { '\0', };
008748
|
008749
| PAYMAP1
*pPayMap1
= NULL;
008749
+ PAYMAP1
*pPayMap1
= ((void *)0);
008750
| PAYMAP2
*pPayMap2
= NULL;
008750
+ PAYMAP2
*pPayMap2
= ((void *)0);
008751
|
008752
| PCHAR
pCommPtr
= NULL;
4. Type GO (PF12) on the COMMAND line and press Enter to continue processing.
The XCCC Demonstration Transaction screen is displayed.
Again, the program pauses at the first statement as shown in Figure 3-62.
3-39
Look at the value for dHoursWorked in the keep window. The indicator <<Out of
scope>> shows that dHoursWorked is defined in a function that is not currently
being executed.
Stepping Through Your C Program
This procedure tests slow-stepping through a program and the program trace function.
This GO command performs the following:
– Individual lines of code are executed with a one-second pause between each
statement, except when a breakpoint is encountered.
– The data fields contained in the current statement, as well as those you have
selected for viewing, are displayed in the keep window.
– The screen shows the executed statements and the number of completed steps.

COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
STEP=00005 *******
K
dHoursWorked
decimal
K
chConvertBuffer
char[16]
01 pWsEIB
struct *
<NULL>
**END**
-----008764
008765
008766
=====>
008768
008769
008770
008771
008772
008772
008773
008774
008775
008776
------------------------------------------------ Before CWDEMC.8767 ->
|
| /* EXEC CICS ADDRESS EIB(pWsEIB) */
| {
| DFHEXEC("\x02\x02\x80\x00\x2F\x05\x00\x00\x00\x00\x00\x00\x00\x00\x
|\x00\x00\x00\x00\x00\x00\x00\xF0\xF0\xF0\xF2\xF1\xF4\xF0\xF0",&pWsEIB
|
dfheiptr = pWsEIB;
|
}
|
| if ( pWsEIB != NULL )
+ if ( pWsEIB != ((void *)0) )
| {
|
/****************************************************************
|
/* Figure out what to to:
|
/* If COMMAREA present
on the COMMAND line and press Enter.
3-40
COMMAND ===>
SCROLL ===> CSR
MODULE: CWDEMC
CSECT: CWDEMC
COMPILED: 14 NOV 2006 - 14:54:47
TERM: 0007 ------------------------------------------------ Before CWDEMC.8767
=======> TASK(00293) MODULE:CWDEMC
CSECT:CWDEMC
LANGUAGE:C
<BRANCH>
0010477 1981
414 + if ( pWsParmArea != ((void *)0) )
0010479 1983
415 |
free ( pWsParmArea );
0010480 1984
416 +
pWsParmArea = ((void *)0);
0010483 1987
417 | return;
<BRANCH>
0009030 534
85 |
if ( WsTransactionStatus == TransactionWaiting )
0009037 541
86 +
dfhb0020 = __strlen(szCommArea);
0009038 542
|
DFHEXEC("\x0E\x08\xE0\x00\x2F\x00\x00\x10\x00\xF0\xF0
=======> TASK(00294)
PROGRAM(CWDEMC )
LANGUAGE(C)
0008745 249
1 | CALLTYPE
CallType
= CallInternal;
0008747 251
2 + CHAR
szPrintBuffer[256] = { '\0', };
0008749 253
3 + PAYMAP1
*pPayMap1
= ((void *)0);
0008750 254
4 + PAYMAP2
*pPayMap2
= ((void *)0);
0008752 256
5 + PCHAR
pCommPtr
= ((void *)0);
0008754 258
6 | SHORT
i
= 0;
0008755 259
7 | SHORT
j
= 0;
0008767 271
| DFHEXEC("\x02\x02\x80\x00\x2F\x05\x00\x00\x00\x00\x00\x00
******************************** BOTTOM OF DATA *******************************
option is turned off of the debugging session is ended. The task number, module
and press Enter.
5. The program now pauses at the breakpoint set on statement 10280. Type GO on the
command line and press enter to complete execution.
Figure 3-65. XCCC Transaction Complete Screen


Employee Number: 00999
Employee Name:
Mr. John Doe
Hours Worked:
45
Hourly Rate:
9.99
Gross Pay:
449.55
*** Transaction XCCC complete ***
4-1
Chapter 4.
Global Parameters Table
Chap 4
This chapter outlines the global parameters table and describes how to change the table.
The global parameters are used to customize Xpediter/CICS to your installation. If this is
your first installation of Xpediter/CICS, Compuware suggests that you install and test the
product with the shipped global parameters before modifying the table.
A default DBUGGBL module is included with the system. Its source can be found in
member DBUGGBL of the library CPWR.cMXD930.SMXDSAMP (where c varies by CICS
release). DBUGGBL is suitable for a test region. The values supplied for each parameter in
DBUGGBL are shown in Table 4-1 on page 4-5. DBUGGBLP is suitable for a production
region and must be assembled and linked if you want to use it. The default parameter
values supplied with DBUGGBLP that are different from those in DBUGGBL are shown in
Table 4-2 on page 4-12.
Before modifying the global parameters table, make a backup copy of the existing
DBUGGBL load and source members.
Specifying Global Parameters at Product Initialization
Xpediter/CICS includes a facility that allows you to override almost all existing global
parameter values at product initialization. This global override facility can also be
invoked while Xpediter is active by entering the transaction XSIT. Refer to Chapter 5,
“Overriding Global Parameters” for complete information.
Note: If using the override facility with parameter XDGBLRP, XDGBLCL, or XDGBLTY,
the change must be coded on the first record of the override dataset.
Parameters Ineligible for Global Override Facility
Only a few parameters cannot be overridden with the Xpediter global override facility.
Changing them requires editing and assembling DBUGGBL as described in “Specifying
Global Parameters by Assembling DBUGGBL” on page 4-3. These parameters are:
•
•
•
•
•
DBPA
XPED
XPON
XPRT
XPSP
Parameters Ineligible for XSIT Transaction
A few other parameters can be modified in one or more of the ways described in this
chapter — but not while Xpediter is active in the CICS region. For this reason, the XSIT
transaction cannot be used to override those parameters. They are:
•
•
•
•
•
•
CCUPDT
CICSOTE
CELLSIZ
CICSPLX
ESDBUFS
MONSIZE
4-2
•
•
•
•
•
•
•
•
•
•
NBRSLS
PROFDDN
RQCHSIZ
SLSDDN
SLSSDB
SUBSYS
TCBNR
UTILMOD
UXSNOFF
XPFS
Some of these parameters can be changed by modifying or overriding the system
initialization table (SIT) parameter INITPARM. For details, see “Specifying Global
Parameters with INITPARM” on page 4-2.
To change any other global table parameters, Compuware recommends that you use the
override facility instead of the table edit and assembly procedure.
Script Facility and File Utility Audit Trail Parameters
While the Xpediter/CICS Script Facility or File Utility Audit Trail are active, certain global
parameters related to their use cannot be overridden with the XSIT transaction:
• The parameters XDSSDD and XDUSDD cannot be overridden while the Script Facility
is active.
• The following parameters cannot be overridden while the File Utility Audit Trail is
active:
–
–
–
–
–
–
–
–
–
–
–
–
–
XDLOG
XDLOGAD
XDLOGBK
XDLOGDD
XDLOGDL
XDLOGMD
XDLOGNM
XDLOGPA
XDLOGSA
XDLOGTY
XDLOGUN
XDLOGUP
XDLOGVO
Specifying Global Parameters with INITPARM
You can modify the following global table parameters by changing or overriding the SIT
parameter INITPARM:
•
•
•
•
•
•
•
•
XDGBLCL
XDGBLIN
XDGBLRP
XDGBLTY
XDDBPCL
XDDBPIN
XDDBPRP
XDDBPTY
Add the desired modification in the form DBUGSIT=’globalparm=parmstring’.
For example, to change the value of the XDGBLIN parameter to MYGBLINP, change or
override
4-3
INITPARM=(current string)
so it includes DBUGSIT with the global parameter and desired value:
INITPARM=(DBUGSIT=’XDGBLIN=MYGBLINP’,current string)
Specifying Global Parameters by Assembling DBUGGBL
Review the applicable global parameter default values in either Table 4-1 on page 4-5 for
DBUGGBL, or Table 4-2 on page 4-12 for DBUGGBLP. If your site does not use the
Xpediter override facility, or the desired parameter cannot be changed with the override
facility or INITPARM, you must enter the desired value in the DBUGGBL or DBUGGBLP
global table, then assemble and link edit it. Ensure that the assembly has the ALIGN
option. The table (DBUGGBL) should be linked with AMODE=31 and RMODE=24 (below
the line) and must not be linked as reentrant. Use the JCL shown in Figure 4-1 to
assemble the global parameters table.
Note: The step names in the JCL shown may differ from those required at your site.
Figure 4-1. Sample JCL to Assemble DBUGGBL Global Parameters Table
//DOIT
EXEC ASMHCL
//ASM.SYSLIB DD DSN=CPWR.cMXD930.SMXDSAMP,DISP=SHR
/*-- CHECK DSN --*/
//
DD DSN=SYS1.MACLIB,DISP=SHR
//ASM.SYSIN DD *
TITLE ’XPED GLOBAL TABLE’
PRINT NOGEN
COPY DBUGGBLM
PRINT ON
DBUGGBLM PF9=(’SELECT’,’SELECT’),TRAPNET=YES <--- MODIFY FOR DESIRED OPTIONS
END
/*
//LKED.SYSLMOD DD DSN=CPWR.cMXD930.SMXDOccL(DBUGGBL),DISP=SHR /*-- DSN --*/
Parameter Transaction Codes
Many parameters are set up to specify options based upon which transaction is used to
access Xpediter/CICS — XPED, XPRT, or XPSP. The format for setting values for these
parameters is:
PARAMETER=(xped-value,xprt-value,xpsp-value)
For example, the following parameter sets default storage protection:
DEFPROT=(ON,OFF,OFF)
The values specified for this parameter establish how storage protection is set for users of
each of the different Xpediter access transactions:
• XPED users ON
• XPRT users OFF
• XPSP users OFF
Automatic Trap Activation Exclusions
The global parameters ATAXPRG and ATAXTRN are used to exclude selected programs
and transactions from Xpediter’s Automatic Trap Activation (ATA). A series of entries are
4-4
used to set the value for each parameter. Follow the instructions below that are
appropriate for your site.
For more information on ATA, see the Xpediter/CICS Reference Manual and the parameter
descriptions for ATA, ATASCRN, ATASEC, ATAUSR*, ATAXPRG, and ATAXTRN in this
chapter.
Setting Values by Assembling the Global Table
If you set parameter values as described in “Specifying Global Parameters by Assembling
DBUGGBL” on page 4-3, specify programs or transactions to be excluded from ATA in the
format PARAMETER=(entry1,entry2,entry3,etc.). One or more entries can be specified on
each line. Enclose multiple entries in parentheses. For example:
ATAXPRG=(ACCTPGM1,ACCTPGM2,PAYROLL1)
ATAXTRN=(ATP1,ATP2,PRL1)
ATAXPRG=PAYROLL2
A list of entries can be continued on additional lines, if necessary, in accordance with
standard Assembler coding rules.
An asterisk (*) can be used to create prefix entries (for example, PROG*), but full
wildcarding (for example, PROG*M) is not supported.
Setting Values with the Override Facility and XSIT Transaction
If you set parameter values as described in Chapter 5, “Overriding Global Parameters”,
specify programs or transactions to be excluded from ATA in the format
PARAMETER=(entry1,entry2,entry3,etc.). One or more entries can be specified on each
line. Enclose multiple entries in parentheses. Continuation lines are not supported.
Instead, repeat the parameter on additional lines, as required, to build a list of values. For
example:
ATAXPRG=(ACCTPGM1,ACCTPGM2)
ATAXPRG=(ACCTPGM3,ACCTPGM4)
ATAXPRG=ACCTPGM5
An asterisk (*) can be used to create prefix entries (for example, PROG*), but full
wildcarding (for example, PROG*M) is not supported.
When entries are specified with the XSIT transaction, they are added to existing entries.
Attempts to add duplicate entries are not honored, but produce no error messages.
The only way to delete entries added with the override facility or XSIT transaction is to
specify REMOVE-ALL-ENTRIES on a separate line. For example:
ATAXTRN=REMOVE-ALL-ENTRIES
Enabling 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.
4-5
Xpediter’s restricted operating modes are enabled by specifying values for the global table
parameters OKUPDT and UTILMOD as follows:
• 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.
• 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.
• 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.
Global Parameter Values and Change Methods
Detailed descriptions of all the parameters are provided in “Parameter Descriptions” on
page 4-12.
Note: The values of certain global parameters are used to initialize input fields on the
screens listed below. See the corresponding chapters in the Xpediter/CICS Reference
Manual or the individual parameter descriptions for details.
•
•
•
•
•
Set Profile Defaults (0.1)
Primary PF Key Settings (0.2)
Script Dataset Allocation (0.6)
DB2 Setup (5.5.0)
DB2 Table/View List (5.5.1).
Standard Global Table DBUGGBL
Table 4-1 lists all the global parameters and the default values for each. It also indicates
which methods can be used to change the value of each parameter. The global override
sample member, DBCGBLT, contains equivalent values. Table 4-2 on page 4-12 lists the
default parameter values that are different in the production version of the global table,
DBUGGBLP.
Table 4-1.
Global Table Parameters
Parameter
Default in DBUGGBL
ACCESSC
Changeable Via:
Override Facility
XSIT Transaction
(ON,ON,ON)
•
•
•
ACCQTS
(ON,ON,ON)
•
•
•
ACCTD
(ON,ON,ON)
•
•
•
ALLOWCM
(OFF,OFF,ON)
•
•
•
ALLOWMON YES
•
•
•
ASMSTMP
•
•
•
YES
INITPARM
Assembling Table
4-6
Table 4-1.
Parameter
Default in DBUGGBL
ATA
Changeable Via:
Override Facility
XSIT Transaction
(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
•
•
•
DB2LOKA4
NO
•
•
•
DB2LOKD
NO
•
•
•
1000
•
•
•
DB2MAX
4
DB2NULD
INITPARM
Assembling Table
•
•
•
•
•
@
•
•
•
4
250
•
•
•
4
LOCAL
•
•
•
DB2STR4
APOST
•
•
•
DB2VARE4
|
•
•
•
DB2SQLR
DB2SQLT
Table 4-1.
Parameter
Default in DBUGGBL
DB2VART
4-7
Changeable Via:
DEFALM
DEFALT
1
1
Override Facility
XSIT Transaction
INITPARM
Assembling Table
YES
•
•
•
(ON,ON,ON)
•
•
•
(OFF,OFF,OFF)
•
•
•
DEFCSE1
(NONE,NONE,NONE)
•
•
•
DEFFOOT1
(OFF,OFF,OFF)
•
•
•
DEFJUST1
(ON,ON,OFF)
•
•
•
1
DEFKEEP
(ON,ON,OFF)
•
•
•
DEFMAXS1
(20,20,20)
•
•
•
(ON,ON,ON)
•
•
•
DEFPROT
(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
•
•
•
GBLTRPA
YES
•
•
•
GOTVP
NO
•
IKEEP1
YES
•
•
•
IVPMSGS
ERROR
•
•
•
LIMCREA4
*
•
•
•
LIMDB4
*
•
•
•
LIMTABL4
*
•
•
•
LIMTS4
*
•
•
•
LIMTYPE4
*
•
•
•
MAXWAIT
6
•
•
•
MENUMSG
Blank
•
•
•
MONSIZE
100
•
MQDYNQ
MXD.*
•
•
•
MQLIST
(ON,ON,ON)
•
•
•
MQREAD
(ON,ON,ON)
•
•
•
MQUPDT
(ON,ON,ON)
•
•
•
MSGPFX
MXD
•
•
•
DEFOPT
1
1
•
•
•
4-8
Table 4-1.
Parameter
Default in DBUGGBL
NBRSLS
8
•
NEWC1N
YES
•
•
•
NLS
ASIS
•
•
•
OKUPDT
(ON,ON,ON)
•
•
•
OPENDS
(ON,ON,ON)
•
•
•
PF12
(’HELP’,’HELP’)
•
•
•
PF2
(’MENU’,’MENU’)
•
•
•
PF32
Changeable Via:
2
Override Facility
XSIT Transaction
INITPARM
Assembling Table
•
(’END’,’END’)
•
•
•
2
(’=X’,’EXIT’)
•
•
•
2
PF5
(’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’)
•
•
•
PF20
(’DOWN MAX’,’DOWN MAX’)
•
•
•
PF212
(’FILE’,’FILE’)
•
•
•
PF222
(’=2.20’,’SRCLESS’)
•
•
•
PF232
(’RETRIEVE’,’RETRIEVE’)
•
•
•
PF242
(’=7.1’,’ABENDAID’)
•
•
•
PL1STMP
YES
•
•
•
POPTOVR
(OFF,OFF,OFF)
•
•
•
PROFDDN
DBUGPRF
•
PROFUSR
YES
•
•
•
PROTCWA
NO
•
•
•
PROTMAX
100
•
•
•
PROTMSG
CSMT
•
•
•
PROTTID
NO
•
•
•
PSBWAIT
2
•
•
•
PF4
2
•
Table 4-1.
Parameter
Default in DBUGGBL
RDSABP
4-9
Changeable Via:
Override Facility
XSIT Transaction
INITPARM
Assembling Table
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
•
•
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
•
•
•
TRPSAVE1
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
•
•
•
•
•
4-10
Table 4-1.
Parameter
Default in DBUGGBL
VERFILE
Changeable Via:
Override Facility
XSIT Transaction
INITPARM
Assembling Table
YES
•
•
•
XDBP
XDBP
•
•
•
XDCC
YES
•
•
•
XDDBPCL
*
•
•
•
•
XDDBPIN
XDDBPINP
•
•
•
•
XDDBPRP
XDDBPRPT
•
•
•
•
XDDBPTY
DYNAMIC
•
•
•
•
XDGBLCL
*
•
•
•
•
XDGBLIN
XDGBLINP
•
•
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
•
•
•
XDTRCRP
XDTRCRPT
•
•
•
XDUSBLK3
27960
•
•
•
3
YES
•
•
•
3
44
•
•
•
3
Blanks
•
•
•
XDUSDD
DYNAMIC
•
•
•
XDUSDSN3
userID.SCRIPT.DATASET
•
•
•
XDUSCR
XDUSDB
XDUSDC
Table 4-1.
Parameter
Default in DBUGGBL
4-11
Changeable Via:
Override Facility
XSIT Transaction
NO
•
•
•
Blanks
•
•
•
15
•
•
•
XDUSPFX
Blanks
•
•
•
XDUSSA3
15
•
•
•
Blanks
•
•
•
XDUSSMS
NO
•
•
•
XDUSTYP3
3
XDUSLIB
3
XDUSMC
XDUSPA
3
XDUSSC3
3
INITPARM
Assembling Table
TRK
•
•
•
3
SYSDA
•
•
•
3
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
•
•
•
XDUSUNI
XDUSVOL
•
•
1If
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.
3If
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.
4If
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.
4-12
Production Global Table DBUGGBLP
Table 4-2 lists the default parameter values that are different in the production version of
the global table, DBUGGBLP. The global override sample member, DBCGBLT, contains
equivalent values.
Table 4-2.
Production Global Table Parameters
Parameter
Default in DBUGGBLP
Changeable Via:
Override Facility
XSIT Transaction
INITPARM
Assembling Table
ACCQTS
(OFF,OFF,ON)
•
•
•
ACCTD
(OFF,OFF,ON)
•
•
•
DBAUDDST XAUD
•
•
•
DBAUDIT
YES
•
•
•
FLWAIT
7
•
•
•
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
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.
ACCESSC
Enter OFF to disable use of the ACCESS command for the specified transaction. The
default is (ON,ON,ON).
ACCQTS
Enter OFF to disable access to QUEUED (multiple record) temporary storage queues in the
file utility for the specified transaction. The default is (ON,ON,ON).
ACCTD
Enter OFF to disable access to transient data queues in the file utility for the specified
transaction. The default is (ON,ON,ON).
4-13
ALLOWCM
Enter OFF to disable access to the ALLOW command for the specified transaction. The
default is (OFF,OFF,ON).
ALLOWMON
Enter NO to disable use of the MONITOR and REVERSE commands. The default is YES.
Refer to “MONSIZE” on page 4-22 for information about controlling storage utilization.
Refer to the Xpediter/CICS Reference Manual for information about MONITOR and REVERSE.
ASMSTMP
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. The default is
YES.
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
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. The default is OFF.
Note: ATA is deactivated if the Xpediter/CICS global parameter CICSPLX=YES.
ATASCRN
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, 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). The default is YES.
ATASEC
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. The default is YES.
ATAUSR1, ATAUSR2, and ATAUSR3
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 default for all three parameters is blanks.
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.
4-14
ATAXPRG
Enter a list of programs to be excluded from Automatic Trap Activation (ATA) trapping.
For more information on entering values for this parameter, refer to “Automatic Trap
Activation Exclusions” on page 4-3.
Note: Any program whose name starts with DFH, DSH, or DB2 is automatically excluded
from ATA trapping.
ATAXTRN
Enter a list of transactions to be excluded from Automatic Trap Activation (ATA)
trapping. For more information on entering values for this parameter, refer to
“Automatic Trap Activation Exclusions” on page 4-3.
Note: CEDA, CEMT, CESN, and CESF transactions are automatically excluded from ATA
trapping.
AUTOSEL
Enter NO to disable automatic selection of abends generated from another terminal. The
default is YES.
AUTOXIT
Enter NO to go to the Exit Session screen on an EXIT command. Enter YES (default) to go
directly to CICS on an EXIT command.
BRGWP
Enter NO to suppress the Compuware background wallpaper used for Xpediter/CICS
screens while running the 3270 Web Bridge. The default is YES.
BRWCNT
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. The default is 100. Valid values are 1 to 99999.
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 may be set to NO to
save CPU. The default is YES.
Note: 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
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. The default is YES.
Note: Specifying CCUPDT=NO will force OKUPDT to (OFF,OFF,OFF).
4-15
Refer to Chapter 6, “Restricted Operating Modes” for more information about restricted
operating modes.
CELLSIZ
Designates the number of cell entries in a cell in ESD cache. Use this parameter as a
performance option. The default value is 10. Do not alter this value unless recommended
by Xpediter/CICS Customer Support (see “Customer Support” on page xxviii). The XSIT
transaction cannot be used to override this parameter.
CICSOTE
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.
CAUTION:
Setting this parameter incorrectly can cause excessive TCB switching and increased
CPU utilization for transactions exploiting CICS OTE.
CICSPLX
Enter YES to activate support for dynamic transaction routing under Xpediter/CICS
CICSPlex support. The default is NO. The XSIT transaction cannot be used to override
this parameter.
CMDDLM
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 default is a semi-colon (;).
Note: 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
Enter the number of entries, from 0 to 32767, that the program statement trace table is to
contain. Entering zero prohibits trace table creation. The default is 500.
CRTEOK
Note: 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. The default is YES.
4-16
CSSPPRC
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. The default value is 4.
Valid values are from 0 to 8.
DBAUDDST
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. The default is CSMT.
DBAUDIT
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. The default value for DBAUDIT
is NO.
DBCTPSB
Enter the PSB to be scheduled by Xpediter/CICS for DBCTL support. The default is
XPEDPSB2.
DBFL
Enter a four-character transaction ID to substitute for the DBFL transaction. Changing
DBFL requires changing the resource definitions. The default is DBFL.
CAUTION:
DBFL is an Xpediter/CICS internal transaction that you should never enter.
DBNC
Enter a four-character transaction ID to substitute for the NEWC transaction. Changing
DBNC requires changing the resource definitions. The default is NEWC.
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 “Specifying Global Parameters by
Assembling DBUGGBL” on page 4-3. Changing DBPA requires changing the resource
definitions. The default is DBPA.
DBXG
Enter a four-character transaction ID to substitute for the DBXG transaction. Changing
DBXG requires changing the resource definitions. The default is DBXG.
CAUTION:
DBXG is an Xpediter/CICS internal transaction that you should never enter.
4-17
DB2AUTH
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 (default): 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 “Step 16. Implement
Support for the DB2 File Utility (Optional)” on page 2-35.
• GROUP: Xpediter uses the same logic as used for NONE. See description of NONE
above. For more information, see “Step 16. Implement Support for the DB2 File
Utility (Optional)” on page 2-35.
• 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
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. The
default is PERIOD.
DB2LOKA
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. The
default value for the DB2LOKA parameter is NO.
DB2LOKD
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. The default value for the DB2LOKD parameter is NO.
DB2MAX
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). The default value is 1000.
DB2NULD
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).
The default value is @.
4-18
DB2SQLR
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). The default value is 250.
DB2SQLT
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). The default value is LOCAL.
DB2STR
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. The default value is APOST.
DB2VARE
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). The default value is |.
DB2VART
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). The default value is
YES.
DEFALM
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). The default is (ON,ON,ON).
DEFALT
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). The default is (OFF,OFF,OFF).
DEFCSE
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) The default is (NONE,NONE,NONE).
4-19
DEFFOOT
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). The default is (OFF,OFF,OFF).
DEFJUST
Enter OFF to disable justification of the source listing for the specified transaction. This
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). The default is
(ON,ON,OFF).
DEFKEEP
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). The default is (ON,ON,OFF).
DEFMAXS
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). The default is (20,20,20).
DEFOPT
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). The default is
(ON,ON,ON).
DEFPROT
Enter OFF to automatically disable storage protection when using the specified
Profile Defaults screen (0.1). The default is (OFF,OFF,OFF).
DEFSRC
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
Profile Defaults screen (0.1). The default is (ON,OFF,OFF).
4-20
DEFSTPD
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). The default is (0,0,0).
DEFTRAC
Enter OFF to disable statement-level program tracing when using the specified
Profile Defaults screen (0.1). The default is (OFF,OFF,OFF).
DEFTRAP
Enter OFF to disable automatic abend trapping when using the specified transaction. This
does not exist for a user. A user can override this parameter on the Set Profile Defaults
screen (0.1). The default is (ON,ON,OFF).
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” on page 4-30.) This function
can also be controlled from the Set Profile Defaults screen (0.1).
DISCONN
Enter NO to leave Xpediter/CICS sessions active if a terminal is disconnected or logged
off. The default is YES. See Chapter 8, “Session and Product Termination”.
DMAP
Enter a four-character transaction ID to substitute for the DMAP transaction used to
invoke the Xpediter/CICS BMS mapset display utility. The default is DMAP.
DUMP
Enter YES to produce a dump when exiting Xpediter/CICS. The default is NO.
ENDSESS
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. The default is NO.
ESDBUFS
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 default value is 500K. The XSIT transaction cannot be used to override
this parameter.
FLWAIT
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
4-21
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, and the default is 14.
FOLDLC
Converts lowercase English characters to uppercase English characters for static portions
of screens and help modules. Values are YES and NO. NO is the default.
Note: If you are running terminals that support katakana single-byte characters (SBC),
you must specify NLS=KATAKANA FOLDLC=YES.
GBLTRPA
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. The default is YES.
GOTVP
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” on page xxviii) for detailed instructions. The default for this option
is NO.
IKEEP
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). The default is YES.
IVPMSGS
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. The default is ERROR.
LIMCREA
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. The default is
an asterisk (*).
LIMDB
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
4-22
this value on the DB2 Setup (5.5.0) and DB2 Table/View List (5.5.1) screens. The default is
an asterisk (*).
LIMTABL
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.
The default is an asterisk.
LIMTS
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. The
default is an asterisk (*).
LIMTYPE
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. The default is an
asterisk (*).
MAXWAIT
Enter the number of seconds that provides a high limit (maximum) wait time to be used
on the GO command. The default is 6 seconds.
MENUMSG
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. The default is blank.
MONSIZE
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. The default is 100. 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
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
• %S - The SYSID of the CICS region
• %U - The UserID of the user associated with the current task.
4-23
The parameter length, after variable substitution, must not exceed 33 characters and
must end with an asterisk (*). The default is MXD.*.
Note: Corresponding specifications in your site's external security manager, such as
RACF, may be necessary. Refer to the appropriate WebSphere MQ documentation
for additional information regarding dynamic queues.
Note: This parameter may be overridden for a user’s session(s) by the DYNAMIC QUEUE
PREFIX field on the 5.6.0 screen.
MQLIST
Enter OFF to disable access to the list of WebSphere MQ (MQSeries) queues in the File
Utility for the specified transaction. The default is (ON,ON,ON).
Note: 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 WebSphere MQ
documentation for additional information regarding the
SYSTEM.COMMAND.INPUT queue.
MQREAD
Enter OFF to disable read access to WebSphere MQ (MQSeries) queues in the File Utility
for the specified transaction. The default is (ON,ON,ON).
MQUPDT
Enter OFF to disable update access to WebSphere MQ (MQSeries) queues in the File
Utility for the specified transaction. The default is (ON,ON,ON).
MSGPFX
Designates the message prefix to be used when messages are written to the console. The
default is MXD.
Note: MSGPFX may be changed using the Override Facility. Some messages, however, are
issued before the overrides are processed. The prefix shown in those messages will
be the value in the assembled table.
NBRSLS
Enter the maximum number of SLS files to search. The default is 8. The allowable range is
1 to 255.
CAUTION:
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 alternative.
Refer to “Working with Source Shared Directory Files (File Manipulation)” in the CSS
Utilities chapter of the Compuware Shared Services User/Reference Guide.
NEWC1N
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. The default is YES.
4-24
NLS
Changes the character translation table that is used to display data. Options are: ASIS,
ENGLISH, CANADAB, HEBREWNC, ARABIC, and KATAKANA. The default is ASIS. See also
FOLDLC.
OKUPDT
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. The default is (ON,ON,ON).
Note: Specifying CCUPDT=NO will force OKUPDT to (OFF,OFF,OFF).
operating modes.
OPENDS
Enter OFF to disable explicit and implicit opening and closing of datasets in the file
utility for the specified transaction. The default is (ON,ON,ON).
PF 1-24
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.
The Xpediter/CICS default PF key values are listed in Table 4-1 on page 4-5.
PL1STMP
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. The default for PL1STMP is YES.
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
• If you use the PL/I option DECK, enter a CWPDECK DD statement in the language
POPTOVR
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. The default is (OFF, OFF, OFF).
4-25
PROFDDN
Enter a name for the user profile file. The default is DBUGPRF. Changing DBUGPRF
requires changing the CSD entry. The XSIT transaction cannot be used to override this
parameter.
PROFUSR
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. The default is
YES.
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
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. The default is NO.
PROTMAX
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. The default is 100.
PROTMSG
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.
The default is CSMT.
PROTTID
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. The default NO.
Note: 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
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. The default is 2 minutes.
RDSABP
Enter YES to allow breakpoints to be set in read-only dynamic storage areas (RDSA and
ERDSA). Enter NO if breakpoints will not be set in read-only DSAs. The default is YES.
4-26
READB
Enter NO to prohibit Xpediter/CICS from reading full buffers from 3270 control units.
Specifying NO disables the Last 3270 Screen facility. The default is YES. TCAM users must
specify READB=NO.
Note: The Last 3270 Screen facility is not available for remote trapping.
READDL1
Enter OFF to disable read access to DL/I segments in the file utility for the specified
READDS
Enter OFF to disable read access to datasets in the file utility for the specified transaction.
The default is (ON,ON,ON).
RECREATE
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. The default is FTP.
RESUME
Enter YES to be able to resume from an abend condition. This has no effect on resuming
from breakpoints. The default is YES.
CAUTION:
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
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. The default value is 6.
RQCHSIZ
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 CICS RPL
concatenation. The value specified must be an unsigned integer in the range of 4096 to
16384. The default value is 4096, which 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
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 terminal read timeout value of two minutes, Xpediter/CICS and the user
transaction converses both time out after two minutes. The default is YES. Enter NO to
4-27
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.
Note: This parameter only applies to local trapping, as Xpediter/CICS executes under the
user TCA of the application transaction.
RUWAIT
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 is 0 seconds, which means that no lock occurs and the system
does not require READ UPDATE before issuing a REWRITE command.
SCHEDL1
Enter OFF to disable PCB/TERM calls for DL/I PSBs in the file utility for the specified
SCROLL
Enter a scroll type. Valid entries are:
•
•
•
•
CSR (default): Scrolling based on the cursor location
HALF: Half-screen scrolling
nnnn: Number of lines to scroll
PAGE: Full-screen scrolling.
SERVRQ
Enter OFF to disable updates of service request fields on the CICS Dataset List screen
(5.1.1) for the specified transaction. The default is (ON, ON, ON).
SETRPLY
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 default is YES.
Note: The Last 3270 Screen facility is not available for remote trapping.
SLSDDN
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 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. The default is SLSF001.
4-28
SLSSDB
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 default is
SLSD0001. 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
Enter the maximum number of statements to execute with a GO command if the delay
interval is greater than 0 seconds. The default is 99.
STEPWT0
Enter the maximum number of statements to execute with a GO command if the delay
interval is equal to 0 seconds. The default is 5000.
STOP
Enter NO to prohibit setting breakpoints. The default is YES.
SUBSYS
Enter a four-character MVS subsystem name, such as XDSS (the default), 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
Chapter 7, “Xpediter Service Provider”.
SUBUBCK
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. The default value is YES.
SUPSESM
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. The
default is “NO”.
TCBNR
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 CICS RPL concatenation. Entering 0 disables PDSE support and
should only be done if there are no PDSE datasets in your CICS RPL concatenation. The
value specified must be an unsigned integer in the range of 0 to 10. The default value is
4-29
4. Setting TCBNR to a higher value will make it more resource intensive. The XSIT
transaction cannot be used to override this parameter.
TRANSUC
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. The default is YES.
TRAPIPU
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” on page 4-30 for more information.) The default is NO.
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
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.
The default for this parameter is NO.
TRAPTRM
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. The default
for this parameter is YES.
TRAPUSR
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. The default
for this parameter is NO.
TRPLOAD
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 (default): Does not load saved traps at session start.
TRPSAVE
Saves traps automatically at session end. This parameter is ignored if the profile dataset is
in the old format. Valid entries are:
YES (default): Saves traps automatically at session end.
NO: Does not save traps automatically at session end.
4-30
TRPXABD
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
Enter the name of the Temporary Storage Queue ID that the file utility must use. This
queue communicates between the screen and file processors. The default is XPED.
Note: This queue must not be defined in the Temporary Storage Table (TST) or in the
TSMODEL entry in the CSD as recoverable.
UNIQUEIP
If automatic abend trapping is on (see “DEFTRAP” on page 4-20) and each of your TCPIPconnected 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
TCPIP-connected 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” on page 4-29), enter
NO. The default is NO.
UPDTDL1
Enter OFF to disable updates of DL/I segments in the file utility for the specified
UPDTDS
Enter OFF to disable updates of datasets in the file utility for the specified transaction.
The default is (ON,ON,ON).
UPDTSEC
Enter OFF to prohibit the display and use of an update password on selected screens.
Valid values are ON and OFF. The default is (OFF,OFF,OFF). See Chapter 12, “Memory
Update Security Exit” for information on password security and this parameter.
4-31
UTILMOD
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. The default is NO.
operating modes. The XSIT transaction cannot be used to override this parameter.
UXSNOFF
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.
NO is the default.
Note: The DISCONN parameter must also be set to YES for the exit to be enabled. Refer
to Chapter 8, “Session and Product Termination” for considerations of setting
UXSNOFF=YES. The XSIT transaction cannot be used to override this parameter.
VERFILE
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. The default YES.
XDBP
Enter a four-character transaction ID to substitute for the XDBP transaction used to
refresh the DBPA parameters from the DBPA input dataset. The default is XDBP.
XDCC
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.
YES is the default.
XDDBPCL
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 above. Valid values are A through Z, 0 through 9, and *. The default is *.
Although the override facility can be used to change XDDBPCL, you can also change it
either as described in “Specifying Global Parameters by Assembling DBUGGBL” on page
4-3 or as described in “Specifying Global Parameters with INITPARM” on page 4-2.
4-32
XDDBPIN
Enter a one to eight-character ddname that will point to the input dataset used to specify
DBPA transactions for configuring storage protection and abend trapping. For detailed
information, see Chapter 14, “Specifying DBPA Transaction Input”. The default is
XDDBPINP.
Although the override facility can be used to change XDDBPIN, you can also change it
XDDBPRP
Enter a one to eight-character ddname for the dynamically allocated SYSOUT dataset
containing the DBPA transactions processing report. The default is XDDBPRPT.
Although the override facility can be used to change XDDBPRP, you can also change it
XDDBPTY
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. The default is DYNAMIC.
Although the override facility can be used to change XDDBPTY, you can also change it
XDGBLCL
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 above. Valid values are A through Z, 0 through 9, and *. The default
is *.
If using the override facility with parameter XDGBLCL, the change must be coded on the
first record of the override dataset.
Although the override facility can be used to change XDGBLCL, you can also change it
XDGBLIN
Enter a one to eight-character ddname that will point to the input dataset used for global
table parameter overrides. For detailed information, see Chapter 5, “Overriding Global
Parameters”. The default is XDGBLINP.
The override facility cannot be used to change XDGBLIN. Change it either as described in
“Specifying Global Parameters by Assembling DBUGGBL” on page 4-3 or as described in
“Specifying Global Parameters with INITPARM” on page 4-2.
XDGBLRP
containing the global table parameter overrides processing report. The default is
XDGBLRPT.
4-33
If using the override facility with parameter XDBGLRP, the change must be coded on the
Although the override facility can be used to change XDGBLRP, you can also change it
XDGBLTY
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. The default is DYNAMIC.
If using the override facility with parameter XDBGLTY, the change must be coded on the
Although the override facility can be used to change XDGBLTY, you can also change it
XDLOG
Enter YES to enable the File Utility Audit Trail. Enter NO to disable the File Utility Audit
Trail. The default is NO.
For more information, see Chapter 18, “File Utility Audit Trail”.
XDLOGAD
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. The default is FULL.
XDLOGBK
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 is
27930, which sets up half track blocking on 3390 DASD.
XDLOGDD
Enter DYNAMIC to specify dynamic allocation of the File Utility Audit Trail GDG
datasets. The dataset will be given the name specified in XDLOGNM. DYNAMIC is the
default.
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.
XDLOGDL
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. The default is FULL.
4-34
XDLOGMD
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/ESA JCL
User’s Guide.
XDLOGNM
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. The default is
XD.LOG.DATASET.GDGNAME.
XDLOGPA
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 primary allocation
of the File Utility Audit Trail GDG dataset. The default is 10.
XDLOGSA
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. The default is 5.
XDLOGTY
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. The default is CYL.
XDLOGUN
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. The default is SYSDA. To set this parameter to blanks with
the global override facility, specify a value of NULL.
XDLOGUP
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. The default is FULL.
XDLOGVO
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
4-35
to blanks, it overrides the value specified for this parameter. The default for XDLOGVO is
blanks. To set this parameter to blanks with the global override facility, specify a value of
NULL.
XDSCRPT
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. The default is YES.
For more information, see Chapter 17, “Configuring the Script Facility”.
XDSCRXN
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 is eight asterisks (********) which 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.
XDSCRXO
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. The default value for this parameter is SAVE.
XDSSACC
Enter WRITE to give Script Facility users read and update access to the system script
dataset. WRITE is the default. Enter READONLY to give Script Facility users read-only
access to the system script dataset.
XDSSAPM
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 user-specified 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. The default is eight asterisks (********). For more
information, see “XDSSDSN” on page 4-36 and Chapter 17, “Configuring the Script
4-36
Facility”.
XDSSDD
Enter DYNAMIC to specify dynamic allocation of your system script dataset. The dataset
will be given the name specified in parameter XDSSDSN. DYNAMIC is the default.
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.
XDSSDSN
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. The default is
XD.SYSTEM.SCRIPT.DATASET. To set this parameter to blanks with the global override
facility, specify a value of NULL.
XDTRCRP
containing the program trace print output. The default is XDTRCRPT.
Although the override facility can be used to change XDTRCRP, you can also change it as
described in “Specifying Global Parameters by Assembling DBUGGBL” on page 4-3.
XDUSBLK
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. The default value for this
parameter is 27960.
XDUSCR
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. The default is YES.
4-37
XDUSDB
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. The default
value for this parameter is 44.
XDUSDC
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.
This parameter defaults to blanks. To set this parameter to blanks with the global
override facility, specify a value of NULL.
XDUSDD
Enter DYNAMIC to enable dynamically allocated user-defined user script datasets.
DYNAMIC is the default.
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.
XDUSDSN
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
will be saved in their profile dataset. This parameter is ignored unless XDUSDD is set to
DYNAMIC and XDUSCR is set to SHARED. The default is userID.SCRIPT.DATASET. To set
this parameter to blanks with the global override facility, specify a value of NULL.
XDUSLIB
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
4-38
this field can be overridden by the user, and the new value will be saved in their profile
dataset. The default value for this parameter is NO.
XDUSMC
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. This parameter defaults to blanks. To set this parameter to blanks with the
global override facility, specify a value of NULL.
XDUSPA
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. The default value for this parameter is 15.
XDUSPFX
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
will be saved in their profile dataset. This parameter is ignored unless XDUSDD is set to
DYNAMIC and XDUSCR is set to SHARED. The default is blanks. To set this parameter to
blanks with the global override facility, specify a value of NULL.
XDUSSA
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. The default value for this
parameter is 15.
XDUSSC
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
4-39
Class field will be used when a new user script dataset is dynamically allocated. This
parameter defaults to blanks. To set this parameter to blanks with the global override
facility, specify a value of NULL.
XDUSSMS
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. The default value for this parameter is NO.
XDUSTYP
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
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. The default value for this
parameter is TRK.
XDUSUNI
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
in the Unit field designates the unit name on which a new user script dataset is to be
dynamically allocated. The default is SYSDA. To set this parameter to blanks with the
global override facility, specify a value of NULL.
XDUSVOL
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. This parameter defaults to blanks. To
set this parameter to blanks with the global override facility, specify a value of NULL.
XFERDDN
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. The default name for this dataset is DBUGSQL.
4-40
XIVP
Enter a four-character transaction ID to substitute for the XIVP transaction used to
invoke the Xpediter/CICS Installation Verification Program. The default is XIVP.
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. The
default is XLGI.
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. The default is
XLOG.
XPED
Enter a four-character transaction ID to substitute for the XPED transaction. The XPED
parameter can only be changed as described in “Specifying Global Parameters by
Assembling DBUGGBL” on page 4-3. Changing XPED requires changing the resource
definitions. The default is XPED.
XPFS
Enter a four-character transaction ID to substitute for the XPFS transaction used for SLS
dataset processing. The default is XPFS. The XSIT trans cannot be used to override this
parameter.
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
Enter a four-character transaction ID to substitute for the XPND transaction used for
debugging session termination. The default is XPND.
XPN0
Enter a four-character transaction ID to substitute for the XPN0 transaction. Changing
XPN0 requires changing the resource definitions. The default is XPN0.
XPOF
Enter a four-character transaction ID to substitute for the XPOF transaction used to
invoke the Xpediter/CICS shutdown facility. The default is XPOF.
XPOFTCWT
Enter the number of seconds Xpediter is to wait prior to each terminal SEND/RECEIVE
issued during execution of the XPOF transaction. The default is 0 seconds. Valid values
are 0 to 9.
4-41
XPON
Enter a four-character transaction ID to substitute for the XPON transaction. The XPON
Assembling DBUGGBL” on page 4-3. Changing XPON requires changing the resource
definitions. The default is XPON.
XPRT
Enter a four-character transaction ID to substitute for the XPRT transaction. The XPRT
Assembling DBUGGBL” on page 4-3. Changing XPRT requires changing the resource
definitions. The default is XPRT.
XPSP
Enter a four-character transaction ID to substitute for the XPSP transaction. The XPSP
Assembling DBUGGBL” on page 4-3. Changing XPSP requires changing the resource
definitions. The default is XPSP.
XREL
Enter a four-character transaction ID to substitute for the XREL transaction. Changing
XREL requires changing the resource definitions. The default is XREL.
XSIT
Enter a four-character transaction ID to substitute for the XSIT transaction used to invoke
the Xpediter/CICS Global Table Override Update Utility. The default is XSIT.
4-42
5-1
Chapter 5.
Overriding Global Parameters
Chap 5
The Xpediter/CICS global table described in Chapter 4, “Global Parameters Table”
contains various parameters you can use to tailor the functioning of Xpediter to a
specific site or CICS region. Prior to Release 6.8, changing global table parameters meant
assembling and link-editing the load module DBUGGBL, then recycling Xpediter or the
CICS region. Although this method can still be used — and must be for a few parameters
— a new and preferred method has been introduced.
The new method reads the desired global parameter values from a sequential dataset
during product initialization. This method is easy to set up and maintain, and it makes
Xpediter itself easier to install and maintain.
In addition, a standalone transaction, XSIT, can be used to read the override parameters
from the input dataset. This eliminates the need to recycle Xpediter or the CICS region
when you want to make global table parameter changes.
This chapter includes sections on the following topics:
• Processing of the global parameter overrides dataset
• Overriding input and report dataset ddnames
• Format of the override report and console log output.
“Global Parameter Overrides Dataset” on page 5-4 contains step by step instructions for
setting up your own global parameter overrides using a sequential dataset.
Processing Overview
Override parameters are read from the dataset pointed to by the XDGBLINP DD. This DD
must be added to the CICS startup JCL. If no DD is found in the JCL, no global override
processing will occur. If a DD already exists in the CICS startup JCL with this name, you
can override the ddname to be used. Refer to “DDname Override Processing” on page 5-2.
As the input is processed, a printed report is written to a SYSOUT dataset dynamically
allocated to the XDGBLRPT DD. If a DD for XDGBLRPT already exists in the CICS startup
JCL, no report is produced. The default ddname, XDGBLRPT, can be overridden. Refer to
“DDname Override Processing” on page 5-2.
Parameter overrides are processed in the order in which they are read. Blank records and
comment records are ignored and written to the output report. Parameter overrides are
also written to the output report. See “Adding Parameter Overrides to the Dataset” on
page 5-8 for override parameter format and processing rules.
If an error is detected in a parameter override, processing continues and an error message
is written to the output report. Refer to the Xpediter/CICS Messages and Codes manual for a
list of possible messages.
5-2
DDname Override Processing
XDGBLINP
XDGBLINP is the default ddname for the input dataset containing the global parameter
overrides. This ddname can be overridden with the XDGBLIN parameter override as
described in “Setting Up the Dataset” on page 5-4.
XDGBLINP ddname overrides are processed in the following order:
1. The ddname is set to the default name XDGBLINP.
2. If the global table contains a valid override ddname, the ddname is set to that value.
3. INITPARM is checked for a DBUGSIT value for XDGBLIN. If present, the value is
validated. If the value is valid, the ddname is set to that value.
XDGBLRPT
The default ddname for the report dataset is XDGBLRPT. The default SYSOUT class is
asterisk (*). The report ddname can be overridden with the XDGBLRP parameter override.
The SYSOUT class can be overridden with the XDGBLCL parameter override. This is
The XDGBLRPT ddname and SYSOUT class overrides are processed in the following order:
1. The ddname is set to the default name XDGBLRPT and the SYSOUT class to the
default class *.
3. If the global table contains a valid override SYSOUT class, the SYSOUT class is set to
that value.
4. INITPARM is checked for DBUGSIT values for XDGBLRP and XDGBLCL. If present,
the values are validated. If the ddname value for XDGBLRP is present and valid, the
ddname is set to that value. If the SYSOUT class value for XDGBLCL is present and
valid, the SYSOUT class is set to that value.
5. The first record of the input dataset is checked for the XDGBLRP and XDGBLCL
parameters. If present, the values are validated. If the ddname value is present and
valid, the ddname is set to that value. If the SYSOUT class value is present and valid,
the SYSOUT class is set to that value.
Global Table Override Report
The global table override report is produced as a dynamically allocated SYSOUT dataset.
The report is optional, and if any errors occur while allocating the report dataset,
processing can still continue.
Figure 5-1 is a sample Xpediter/CICS global table override report. The numbered
references are discussed following the figure.
5-3
Figure 5-1. Sample Global Table Override Report
XPEDITER/CICS GLOBAL TABLE OVERRIDE REPORT
APPLID: ACMEC123 DATE: 30 SEP 2003 TIME: 16:38:55 USERID: MYUSRID
PAGE
1
TERM: A011[1]

[2]
INPUT DDNAME XDGBLINP (DEFAULT NAME).
REPORT DDNAME GLOBREPT (OVERRIDE FROM FIRST INPUT RECORD).

INPUT RECORD/ERROR MESSAGE
------------------------------------------------------------------------

[3]XDGBLRP=GLOBREPT
SEND REPORT TO GLOBREPT DD
*-----------------------------------------------------------------------
*
[4] *
*
*
BLANK RECORDS ARE IGNORED.
*
*
RECORDS STARTING WITH ’*’ IN COLUMN 1 ARE TREATED AS COMMENTS.
*
*
COLUMNS 1 THROUGH 72 OF A RECORD ARE PROCESSED. ANYTHING BEYOND
*
COLUMN 72 IS DISCARDED.
*
*-----------------------------------------------------------------------
ACCESSC=(ON,ON,ON)
ACCESS COMMAND USAGE
ERROR> BRWCNT=????
FIND COMMAND RECORD LIMIT
FILE UTILITY
<ERROR[5]
<ERROR[5]
ERROR> Invalid numeric data in Xpediter/CICS Global Table Override.
BRWCNT=1000
FIND COMMAND RECORD LIMIT
FILE UTILITY
ERROR> DEFMAXS=(20,??,20)
MAX STMTS TO EXECUTE IF DELAY > 0
<ERROR
<ERROR
ERROR> Parm 2 numeric data invalid for Xpediter /CICS Global Table Override.
DEFMAXS=(20,20,20)
MAX STMTS TO EXECUTE IF DELAY > 0
[1] The second heading line indicates the CICS region applid, date, time, terminal, and
userID of the user logged on to the terminal when program DBUGSIT was run.
[2] These heading lines indicate the ddnames used for the input and report datasets. In
addition, they indicate whether the ddnames used are the default names or have been
overriden by the user.
[3] Input parameters, including blank lines and comments, are displayed from here
down. This provides a complete audit of the parameters processed.
[4] Comments appear in this portion of the report, each preceded by an asterisk. This
sample report includes a few comments about processing rules for override parameters.
[5] When an error is detected on an input record, the error is flagged. The line that
follows contains a message indicating the error detected and is also flagged. Only the first
error detected for a parameter is flagged.
Global Table Override Console Log Output
Messages are written to the console log whenever the global override process is run. In
addition to messages indicating the start and end of processing, any errors related to
dataset attributes are also written to the console. Figure 5-2 is a sample of output written
to the console.
Messages that do not apply to a particular input parameter are displayed with two lines
per message. All messages contain similar information on the first line including a
message number, severity level, date, time, and region applid.
5-4
Figure 5-2. Sample Global Table Override Console Log Output
11.09.10 JOB00568
11.09.10 JOB00568
11.09.10 JOB00568
+XDDGB0000 I 30 SEP 2003 11:09:10 ACMEC123
XPEDITER/CICS GLOBAL TABLE OVERRIDE PROCESSING HAS BEGUN.
+XDDGB0011 I 30 SEP 2003 11:09:10 ACMEC123
SEE SYSOUT DD XDGBLRPT FOR REPORT.
+XDDGB0001 I 31 30 SEP 2003 11:09:10 ACMEC123
XPEDITER/CICS GLOBAL TABLE OVERRIDE PROCESSING HAS ENDED.
Global Parameter Overrides Dataset
This section describes the steps necessary to create a PDS or PDSE that will contain global
table parameter override records. These records will be read during product initialization
to allow modification of global table parameters. This method eliminates the need —
except with a limited number of parameters — to assemble and link-edit the global table
DBUGGBL.
A standalone transaction, XSIT, can be used to refresh the parameters from the input
dataset. This eliminates the need to recycle Xpediter or the CICS region when you want
to make global parameter changes.
Even if you don’t need to override global table parameters at this time, Compuware
suggests that you modify your CICS startup JCL and use the skeleton member created in
this procedure. Nothing will be harmed, and if you later need to override any global
parameters, the dataset will be ready for use.
Although global table parameter overrides can come from a SYSIN dataset or flat
sequential dataset, the preferred method is for the input to come from a PDS or PDSE.
The advantages include ease of installation, flexibility in maintenance of input, and the
ability to modify the override dataset while the region is active.
Initially, you should use a test CICS region to test your global table parameter override
processing. After reviewing the output and the actual processing, you will easily be able
to modify all your CICS regions.
Setting Up the Dataset
Perform the following steps to establish global table parameter override processing.
1. Create the global table parameter overrides dataset and default member.
The JCL in Figure 5-3 defines the global table parameter overrides input dataset. The
actual JCL is provided in CPWR.cMXD930.SMXDSAMP (where c represents the CICS
release) member DBCDEFGT. This JCL also creates a default member needed in later
steps. When modifying the JCL, write the name you use for the DSNNAME parameter
of procedure DEFSIT ([1]) in the space below:
Overrides dataset name:____________________
5-5
Figure 5-3. Sample JCL to Define the Global Table Parameter Overrides Dataset
//* =====>
INSERT JOBCARD HERE
<=====
//*********************************************************************
//*
*
//* DBCDEFGT THIS MEMBER ALLOCATES AND CREATES A DEFAULT MEMBER
*
//*
IN THE XPEDITER/CICS GLOBAL TABLE OVERRIDE INPUT
*
//*
DATASET.
*
//*
*
//*********************************************************************
//DEFSIT PROC DSNNAME=’XPEDITER.GLOBAL.OVERRIDE’,[1] <== CHECK DSN
//
DUNIT=’SYSDA’,
<== CHECK UNIT
//
DVOL=’VOLSER’,
<== CHECK VOLSER
//
DBLOCK=3200
<== CHECK BLKSIZE
//*********************************************************************
//*
*
//* ALLOCATE THE XPEDITER/CICS GLOBAL TABLE OVERRIDE INPUT DATASET
*
//*
*
//* NOTE: SPACE PARAMETER VALUES ARE ONLY ESTIMATES. DEPENDING ON
*
//*
THE NUMBER OF GLOBAL TABLE OVERRIDES AND INDIVIDUAL
*
//*
MEMBERS YOU DECIDE TO USE, MAY IMPACT THE SPACE REQUIRE*
//*
MENTS. THE SPACE ALLOCATION DEFAULTS SHOULD BE ACCEPTABLE *
//*
TO THE MAJORITY OF INSTALLATIONS.
*
//*
*
//*********************************************************************
//ALLOC
EXEC PGM=IEFBR14
//XDGBLINP DD DSN=&DSNNAME,
//
DISP=(,CATLG),
//
VOL=SER=&DVOL,
//
UNIT=&DUNIT,
//*
DSNTYPE=LIBRARY,
<=== UNCOMMENT IF PDS/E DESIRED
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=&DBLOCK),
//
SPACE=(TRK,(10,5,25))
//*********************************************************************
//*
*
//* CREATE A SKELETON MEMBER, NAMED DEFAULT. THIS MEMBER CAN BE
*
//* USED AS A MODEL FOR FUTURE MEMBER DEFINITIONS.
*
//*
*
//*********************************************************************
//LOADIT
EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD DUMMY
//SYSIN
DD DDNAME=DEFAULT
//SYSUT2
DD DSN=&DSNNAME,DISP=SHR
//
PEND
//DBCDEFGT EXEC DEFSIT
//LOADIT.DEFAULT DD *
******************************* NOTE ***********************************
* PLEASE CHANGE THE FOLLOWING "/*./" TO "./"
*************************************************************************
/*./ ADD NAME=DEFGBL
XDGBLCL=?,XDGBLRP=RPTDD
GLOBAL TABLE OVERRIDE REPORT CLASS/DDNAME

*----------------------------------------------------------------------*
*
XPEDITER/CICS GLOBAL TABLE OVERRIDE INPUT
*
*
*
* BLANK RECORDS ARE IGNORED.
*
*
*
* RECORDS STARTING WITH ’*’ IN COLUMN 1 ARE TREATED AS COMMENTS.
*
*
*
* COLUMNS 1 THROUGH 72 OF A RECORD ARE PROCESSED. ANYTHING BEYOND
*
* COLUMN 72 IS DISCARDED.
*
*
*
*
PLACE GLOBAL TABLE OVERRIDES FOLLOWING THIS COMMENT BOX
*
*----------------------------------------------------------------------*

/*


5-6
2. Create your own overrides member in the global table parameter overrides
dataset.
a. Create a new member in your override dataset.
b. Copy member DEFGBL into it.
c. Write the member name below:
Member Name:____________________
This method of specifying global table parameter overrides is very flexible. If you
wanted to specify overrides for a specific CICS region, you could use the CICS startup
JCL member name. You could also create a single member for all regions. By using
dataset concatenation as shown below, you could create a set of members to control
the override process. You could have a member common to all regions, a member
specifically for test regions, and a member for a single region.
For example, you could define a member named COMMON that contained a set of
overrides common to all regions. Member TESTREGS could contain parameter
overrides intended for test regions. Finally, member CICS0001 would have parameter
overrides specifically for region CICS0001. By using the following concatenated DD
statement, the overrides would be processed as a single input stream, with the
records from COMMON read first, followed by those from TESTREGS, and finally the
records in member CICS0001.
//XDGBLINP DD DISP=SHR,DSN=XPEDITER.GLOBAL.OVERRIDE(COMMON)
//
DD DISP=SHR,DSN=XPEDITER.GLOBAL.OVERRIDE(TESTREGS)
//
DD DISP=SHR,DSN=XPEDITER.GLOBAL.OVERRIDE(CICS0001)
Two members have been provided in SMXDSAMP member that contain all the global
table parameter settings. Member DBCGBLT contains the default settings that
correspond to the default global table DBUGGBL shipped with Xpediter. Member
DBCGBLP contains the default settings that correspond to the optional production
global table DBUGGBLP that also ships with Xpediter. You can append either of these
members to the member you create in this step. Then simply change any parameters
necessary to meet your requirements.
Note: The XDGBLCL and XDGBLRP parameters, if used, must always be the first
record in an override dataset member.
3. Establish a ddname for the global table parameter overrides dataset.
a. Review the CICS startup JCL you want to modify. If you already have a DD
statement with the ddname XDGBLINP in your JCL, go to step b. Otherwise, just
write XDGBLINP in the space below, then continue with step 4 on page 5-7.
Input ddname:____________________
b. Select a new ddname not already in your JCL and write it in the “Input ddname”
space above.
c. Use the system initialization table (SIT) INITPARM parameter as follows. No
assembly or link-edit of the global table is required.
1. Review the startup JCL for the CICS region you are modifying. Locate the SIT
override dataset. If the SIT overrides are in an instream SYSIN dataset, write
the name of the CICS startup JCL member below. Otherwise write the name
of the separate SIT override dataset.
CICS SIT override dataset:____________________
2. Edit the dataset you wrote in above. Refer to the ddname you wrote in earlier
and add an INITPARM parameter — or modify your existing INITPARM
parameter — as shown below. Use your “Input ddname” in place of
myddname.
INITPARM=(DBUGSIT=’XDGBLIN=myddname’,...any existing parameters)
5-7
3. Save the dataset.
4. Establish a ddname for the global table override report dataset.
Review the CICS startup JCL you want to modify. If you already have a DD statement
with the ddname XDGBLRPT in your JCL, select a new ddname not in your JCL and
write it in the space below. Otherwise, just write in XDGBLRPT.
Report ddname:____________________
5. Choose a SYSOUT class for the global table override report.
The SYSOUT class is a one byte value in the range A through Z, 0 through 9, or
asterisk (*).
If you specify a JES output class that requests immediate printing, the output will be
printed after the global table parameter overrides have been processed. Otherwise it
will remain with the normal JES output for the region until CICS ends. Enter your
SYSOUT class in the space below.
SYSOUT Class:____
6. Modify the override dataset member.
Edit the input member whose name you wrote down in step step 2 on page 5-6. The
first line of this member contains parameters that allow you to easily override the
report ddname and SYSOUT class.
Note: Make sure this is always the first record in your override member.
The first line should currently read:
XDGBLCL=?,XDGBLRP=RPTDD
GLOBAL TABLE OVERRIDE REPORT CLASS/DDNAME
Modify the line as follows:
a. Change ? to the value you wrote down in step 5.
b. Change RPTDD to the value you wrote down in step 4.
Save the member, then continue with step 7.
7. Add a DD statement for the global table parameter overrides input dataset to
your CICS startup JCL.
a. Edit your CICS startup JCL. Refer to the global parameter overrides dataset name,
input ddname, and member name you wrote in earlier. Add the following DD
statement to the CICS step, using your “Input ddname” in place of myddname,
your “Overrides dataset name” in place of dataset, and your “Member name” in
place of member.
//myddname DD DISP=SHR,DSN=dataset(member)
b. Save your modified CICS startup JCL.
That completes the setup of the global table parameter override facility. You have
successfully modified your CICS startup JCL to allow input of global parameter overrides
from a dataset. You may continue with the installation of Xpediter/CICS.
When testing Xpediter after installation, look for the global table override report dataset
in your JES output. Check the report and the console log for any errors that may have
occurred while overriding global table parameters. Message formats and explanations are
provided in the Xpediter/CICS Messages and Codes manual.
If you need to add global parameter overrides to your other CICS regions, simply repeat
step 2 through step 7.
5-8
Adding Parameter Overrides to the Dataset
The global table parameter override facility makes adding or modifying parameters much
less restrictive than it was when global table assembly and link-edit were required. In
addition, blank lines and comments can be mixed in with the actual parameters to
improve readability and provide a way of documenting changes.
Keep the following processing rules in mind when adding parameter overrides:
• 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.
• Only one parameter per record is validated. The only exceptions are the report
dataset ddname and SYSOUT class override parameters, which must be coded on the
same line and must be in the first record in the parameter override dataset. In the
following example, parameter ACCESSC will be processed because it is the first
parameter on the line. Parameter ACCQTS will be ignored.
ACCESSC=(ON,ON,ON),ACCQTS=(ON,ON,ON)
• After validation of the first parameter in a record, excess data is ignored. This lets you
code comments following a parameter. In the following example, the parameter
ACCESSC will be processed, and the comment ACCESSC COMMAND OVERRIDE
EXAMPLE will be ignored.
ACCESSC=(ON,ON,ON)
ACCESS COMMAND OVERRIDE EXAMPLE
• If using the override facility with parameter XDGBLRP or XDGBLCL, the change
must be coded on the first record of the override dataset.
6-1
Chapter 6.
Restricted Operating Modes
Chap 6
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 6-1 on page 6-3 provides a matrix of the Xpediter functions
available in each of the three modes.
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.
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.
6-2
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.
Note: 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” on page xxviii).
Note: 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, DBCGBLP,
supplied with the product.
CAUTION:
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).
Restricted Operating Modes
6-3
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.
Available Functions
Table 6-1 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.
Diagnosis/Utilities Mode
Update program register values
•
Update program resume offsets
•
Reroute program flow with SKIP and GOTO commands
•
File utility (subject to normal global table restrictions)
•
•
•
•
Source listing utility
•
•
•
•
Task Storage Display screen (2.S)
•
•
•
•
View storage on Memory Display screens (2.2 and 9.2)
•
•
•
•
Update storage on Memory Display screens (2.2 and 9.2)
•
View storage on DSECTs screens (2.D and 9.D)
•
Update storage on DSECTs screens (2.D and 9.D)
•
View variables in keep window
•
Update variables in keep window
•
View variables on Program Storage screen (2.3)
•
Update variables on Program Storage screen (2.3)
•
Modify Assembler instructions with VERIFY command
•
Trap
•
•
Trace
•
•
Protect
•
•
Xpediter Function
Standard Mode
Utilities Mode
Available Xpediter/CICS Functions by Operating Mode
Diagnosis Mode
Table 6-1.
•
•
•
•
•
•
•
•
6-4
7-1
Chapter 7.
Xpediter Service Provider
Chap 7
This chapter 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.
A single Xpediter Service Provider can handle multiple CICS regions and different CICS
releases. Subsequent releases of the Xpediter Service Provider are downward compatible.
For example, the Xpediter Service Provider included with Xpediter/CICS release 9.1
supports Xpediter/CICS releases 9.1 and 8.3, but does not support Xpediter/CICS release
9.2.
The Xpediter Service Provider supports the following features:
•
•
•
•
•
Xpediter/CICS routing in a CICSPlex dynamic-routing environment
Setting breakpoints in programs residing in protected E(RDSA)
Exploitation of the trap facility to improve performance of breakpoint handling
Debugging in Open Transaction Environment (OTE)
Cross-LPAR communication between Xpediter Service Providers to facilitate CICSPlex
dynamic routing.
Note: When using the Cross-LPAR communication between Xpediter Service Providers
feature, the userID associated with the Service Provider must have a RACF OMVS
segment (or its equivalent, if you use a different external security manager).
Detailed descriptions of the various messages generated by the Xpediter Service Provider
are provided in the Xpediter/CICS Messages and Codes manual.
Release Compatibility
As shown in Table 7-1, this release of Xpediter can only be used with this version of the
Xpediter Service Provider. For those sites using multiple releases of Xpediter/CICS, this
release of the Service Provider is backward compatible with Releases 9.2, 9.1, and 9.0 of
Xpediter/CICS.
Table 7-1.
Xpediter
Release
9.0
9.1
9.2
9.3
9.0
•
•
•
•
•
•
•
•
•
9.1
9.2
9.3
•
7-2
Xpediter Service Provider Parameters
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 are appropriate for all but the largest sites.
Table 7-2.
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.
N/A
Name of member in TPCONFIG
partitioned dataset that identifies all
Service Providers participating in the
same CICSPlex.
MEMBER
Blank
N/A
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 Dynamic MRO
environment on page 8-2 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.
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.
Note: 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.
Service Provider Usage of the Xpediter TP Configuration File
The Xpediter TP configuration file (TPCONFIG) is used by both Xpediter/Eclipse and
Xpediter/CICS. Xpediter/Eclipse usage is documented in the Compuware Workbench
Installation Guide. Xpediter/CICS uses this dataset for two purposes:
7-3
• 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 Chapter 19, “Batch Interface
to Xpediter/CICS NEWCOPY”.
Efficiency Considerations
Technically, each member of the TPCONFIG partitioned dataset may contain entries for
all three 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.
Note: Record identifiers for Xpediter/Eclipse are documented in Compuware’s Compuware
Workbench Installation Guide.
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.
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.
Implementing 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
7-4
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.
Executing as a Started Task
The PROC in member XDSSPROC provided in CPWR.cMXD930.SMXDSAMP (where c
represents the CICS release) (Figure 7-1) is used to execute the Xpediter Service Provider
as a started task.
Figure 7-1. 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=,
//
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',
//
'PORT=&PORT',
//
'&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
7-5
7-6
Substitute parameter values on the MVS operator START command. See Table 7-2 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.cMXD930.SMXDAUTH where c varies by CICS release.
Executing as a Batch Job
The JCL in member XDSSJCL provided in SMXDSAMP member (Figure 7-2) is used to
execute the Xpediter Service Provider as a batch job.
7-7
Figure 7-2. 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 7-2 on page 7-7 for an explanation of valid
XDSSPROC parameter values.
Note: The STEPLIB DD statement in procedure XDSSPROC (see Figure 7-1 on page 7-5)
must point to the dataset to which the Xpediter/CICS APF authorized modules
were linked. The default is SMXDAUTH member.
7-8
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 as follows:
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:
XSP2100I
XSP2101I
XSP2102I
XSP2103I
XSP2103I
XSP2103I
XSP2103I
XSP2103I
XSP2103I
XSP2103I
XSP2103I
XSP2104I
Column
Service Provider Release 09.03.00 SSID(XPLX) Image(ZOS1)
Job Name ASID
Status
Type
Version Ident
Connects
-------- ---- -------------- -------- -------- -------- --------
ACMEASA2 0095 Initialized
CICS
04.01.00 ACMEASA2
1
CICS
04.01.00 ACMEASA1
1
CICS
04.01.00 ACMEASA4
1
CICS
04.01.00 ACMEASA3
1
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.
Column
Description
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.
7-9
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.
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
7-10
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.
CAUTION:
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
“Step 26. Install and Customize the Remote Operations Command Interface (Optional)”
on page 2-46 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:
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:
7-11
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
7-12
8-1
Chapter 8.
Session and Product Termination
Chap 8
This chapter explains how to add Xpediter’s automatic session termination. This feature
is also available to transaction routing users. The XPND transaction for quick session
termination and the XPOF transaction for shutting off Xpediter/CICS in an entire region
are also discussed.
Automatic Session Termination
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.
To install Xpediter’s automatic session termination feature, follow the instructions below.
Enabling Automatic Session Termination
Xpediter/CICS automatic session termination can be established in either or both of the
following ways:
• 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.
Note: There are certain disadvantages to using the XSNOFF exit:
8-2
– 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 are defined to CICS in “Step 3. Update the
CICS Resource Definitions” on page 2-18:
• Program DBUGEND0.
• Program DBUGEND.
• Program DBUGEND1. (Optional. See “For Transaction Routing Users” on
page 8-3.)
• 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.cMXD930.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 Chapter 4, “Global Parameters Table”.
Note: 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 “For Transaction Routing Users” on page
8-3.
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.
CAUTION:
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.
b. Modify the terminal autoinstall exit DFHZATDX (or whatever exit is used at your
site) as follows:
Note: If your site uses a different autoinstall exit, its name can be found in the
SIT parameter AIEXIT.
Session and Product Termination
8-3
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)
Note: Add the above line in the section labeled DELETE_TERMINAL. Do not
add the line to the section labeled DELETE_SHIPPED_TERMINAL.
2. Reassemble and link edit DFHZATDX (or whatever VTAM terminal
autoinstall exit is used at your site).
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 8-1) in the Xpediter
load library.
Note: The DBUGEND1 table must not be linked with command level stubs.
Figure 8-1. 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
this entry only if you will be doing debugging in a TOR and require automatic
session termination there.
Note: 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 transaction resource definitions for the local CICS region (TOR):
CEDA DEFINE TRANSACTION(XPN1) GROUP(XPEDR930)
REMOTESYSTEM(CIC1) REMOTENAME(XPND) DYNAMIC(NO)
.
.
.
CEDA DEFINE PROGRAM(DBUGEND1) GROUP(XPEDR930)
LANGUAGE(ASM) EXECKEY(CICS)
8-4
Quick Session Termination
To quickly terminate an Xpediter/CICS session (in order to release breakpoints in several
programs, for example), execute XPND from a terminal. This will terminate the active
Xpediter session assigned to that terminal.
Using this method writes all messages to the terminal instead of CSMT. This method is
valid for all CICS releases.
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.
Note: 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 8-2. 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.
CAUTION:
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.
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 8-2. 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 “Step 26. Install and Customize the Remote Operations Command
Interface (Optional)” on page 2-46 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.
9-1
Chapter 9.
DB2 Format Utility
Chap 9
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 chapter describes the DBSQLUTL utility, its use, the available commands
and options, and the format utility dataset requirements.
Using the DBSQLUTL Utility
Procedure library member DBCFORSQ contains sample JCL for the DBSQLUTL utility.
DBCFORSQ formats all members on DBUGSQL into a COBOL format.
Figure 9-1 shows the sample JCL contained in the DBCFORSQ member.
Figure 9-1. Sample JCL for DBCFORSQ
//*
DBCFORSQ - FORMAT ALL MEMBERS ON DBUGSQL TRANSFER FILE
//*
//* THIS JOB WILL FORMAT ALL MEMBERS FROM THE XPEDITER/CICS SQL
//* TRANSFER FILE INTO A COBOL FORMAT WITH THE FORMATTED MEMBERS BEING
//* WRITTEN TO A PDS.
//* THE STEPLIB DSN MUST BE CHANGED TO REFLECT THE LOAD LIBRARY
//* XPEDITER/CICS WAS LINK EDITED TO.
//* THE COMMAND CARDS SUPPLIED ARE SUGGESTED AND SHOULD ONLY BE
//* MODIFIED AFTER CONSULTING THE INSTALLATION MANUAL. PLEASE
//* CONSULT THE INSTALLATION MANUAL BEFORE RUNNING THIS JCL.
//*
//FORMAT
EXEC PGM=DBSQLUTL
//STEPLIB DD DISP=SHR,
//
DSN=CPWR.cMXD930.SMXDOccL /* SUPPLY LOADLIB DSN */
//SYSUDUMP DD SYSOUT=*
//SQLIN
DD DSN=XPED.SQL.XFER.FILE,
/* SUPPLY DBUGSQL FILE DSN */
//
DISP=SHR
//YOURPDS DD DSN=XPED.FORMAT.PDS,
/* SUPPLY DSN
*/
//
DISP=(NEW,CATLG,DELETE),
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=8000),
//
SPACE=(TRK,(2,1,5)),
//
UNIT=3380,VOL=SER=?????? /* SUPPLY VOLSER
*/
//SYSIN
DD *

FORMATP TODD=YOURPDS
MEMBER=*
DSORG=PO

/*
//
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.
9-2
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.
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.
DB2 Format Utility
9-3
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
characters. The default value is SQLOUT.
MEMBER
Specifies the name of the member to be deleted. Valid entries are one to eight
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
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.
9-4
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
TODD
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
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.
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 9-2. A list of field
explanations are provided after the figure. Other reports follow a similar format.
DB2 Format Utility
9-5
Figure 9-2. 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.
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.
9-6
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
MEMBER
Specifies the name of the member to be printed. Valid entries are one to eight
Note: You cannot specify the MEMBER parameter when printing from a sequential
dataset.
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.
DB2 Format Utility
9-7
DBSQLUTL Format Utility Dataset Requirements
Table 9-1 provides a summary of the datasets needed for running the DBSQLUTL utility.
Table 9-1.
COMMAND
DBSQLUTL Format Utility Dataset Requirements
FROMDD
INITIALIZE
TODD
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.
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
9-8
10-1
Chapter 10.
Intercommunication Considerations
Chap 10
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.
This chapter describes installation steps under the following topics:
• “Installation in a Static Routing Environment”
• “Installation in a CPSM Dynamic Routing Environment”
• “Installation in a Non-CPSM Dynamic Routing Environment”.
Installation 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.
Step 1. Install Xpediter/CICS in Each Region
Install Xpediter/CICS in each region after you have performed the steps in Chapter 2,
“RFN Installation Procedures”.
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 parameter table. You can enter Xpediter/CICS in any region and
always start it in that region, regardless of the transaction routings in effect.
Note: 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.
Step 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
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)
REMOTENAME(DBXG)
REMOTENAME(DMAP)
REMOTENAME(NEWC)
REMOTENAME(XDBP)
REMOTENAME(XIVP)
REMOTENAME(XLOG)
REMOTENAME(XPED)
REMOTENAME(XPND)
REMOTENAME(XPOF)
REMOTESYSTEM(SYSID1)
10-2
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
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(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(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.
Installation in a CPSM Dynamic Routing Environment
The dynamic MRO support provided by Xpediter/CICS requires IBM’s CICSPlex SM
(CPSM). Refer to “System Environment” in “Introduction” 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,
within an MVS image, containing Xpediter/CICS.
The Xpediter Service Provider keeps track of all active traps within all AORs of each
CICSPlex. User-ID, 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
10-3
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.
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.
Step 1. Install Xpediter/CICS in TORs and AORs
After completing Chapter 2, “RFN Installation Procedures”, 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.
Note: Do not use function shipping to define Xpediter/CICS listing files as remote
resources. The same files can be defined in each region, however, to allow access
to each source listing at all times.
Step 2. 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.
10-4
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).
Step 3. 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.
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.
Step 4. 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
“Using RDO to Update Resource Definitions” on page 2-19. 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
“Using RDO to Update Resource Definitions” on page 2-19.
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 and DBUGWRMM.
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.
Step 1. Prepare for Static Routing
Complete the steps described in “Installation in a Static Routing Environment” on page
10-1. The transaction definitions for XPE1, XPE2, etc. should include the parameter
ROUTABLE(YES).
10-5
Step 2. Implement Automatic Session Termination
To implement automatic session termination, perform the tasks described in “Automatic
Session Termination” on page 8-1, including those in the section entitled “For
Transaction Routing Users” on page 8-3. This will include the creation of a table named
DBUGEND1.
Step 3. Implement the Script Facility
The Xpediter/CICS Script Facility is described in Chapter 17, “Configuring the Script
Facility”. Complete the tasks described in that chapter.
Note: Consider creating an appropriate script to be specified for the global parameter
XDSSAPM.
Step 4. 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 10-1) in a load library that
will be available in the TOR.
Note: The DBUGSTA1 table must not be linked with command level stubs.
Figure 10-1. 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
Note: 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(XPEDR930)
LANGUAGE(ASM) EXECKEY(CICS)
CEDA DEFINE PROGRAM(DBUGSTA1) GROUP(XPEDR930)
LANGUAGE(ASM) EXECKEY(CICS)
CEDA DEFINE TRANSACTION(XSTA) PROGRAM(DBUGSTA0)
GROUP(XPEDR910) LANGUAGE(ASM) EXECKEY(CICS)
Note: The XSTA transaction could be any valid transaction name.
10-6
11-1
Chapter 11.
File Update Security Exit
Chap 11
Xpediter offers a File Update Security Exit facility that 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 Compuwaresupplied fields to access resources not traditionally protected by external security
managers.
This chapter discusses the following topics:
• Implementing a File Update Security Exit
• Error handling and recovery
• Debugging the File Update Security Exit.
This chapter is important for system programmers who want to secure access to their
files.
Implementing A File Security Exit
There are sample members, described in Table 11-1, that are provided in
CPWR.cMXD930.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 11-1. 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.
Step 1. Choose Sample Exits
Choose a sample program (RACFEXIT or DBUGUSEC) to code security exits for your site.
Step 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.
Step 3. Tailor the Exit
Review the assembly. The assembled listing contains notes on coding conventions and
using the security block.
11-2
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. High-level 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” on page 11-4.
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.
Note: 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.
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.
11-3
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 11-2. Each register
has a corresponding equate to simplify coding. The following table includes the equate
associated with each register.
Table 11-2. 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.
CAUTION:
Failure to follow these conventions may cause severe errors.
Step 4. Run Security Exit Through IBM Command-Level Translator
Translate the selected exit program using the IBM Command-Level Translator. See “Step
1. Assemble DBUGUSEC and Link-Edit DBUGFILE for Testing” on page 11-5.
Step 5. Assemble RACFEXIT or DBUGUSEC
Assemble the exit code you selected in “Step 1. Choose Sample Exits” on page 11-1. The
sample exit code may have been RACFEXIT or DBUGUSEC.
Step 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
11-4
library separate from your regular Xpediter/CICS libraries so if any errors are found, other
users will not be affected. See “Step 1. Assemble DBUGUSEC and Link-Edit DBUGFILE for
Testing” on page 11-5.
Error Handling and Recovery
Instructions for using Xpediter/CICS to debug your exit are covered in “Debugging the
File Update Security Exit” on page 11-5. 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.
NOT AUTHORIZED - SECURITY PKG NOT AVAILABLE.
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.
NOT AUTHORIZED - NO DBUGFILE SECURITY EXIT.
If you decide to write your own security exit, the object module must be accessible
during the link-edit of DBUGFILE.
11-5
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
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.
Step 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.
Step 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.
11-6
Step 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).
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.
Step 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.
Step 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 “Step 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.
Step 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.
Step 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.
Step 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
11-7
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.
Step 9. Remove Test Exit
Either remove the test library from the DFHRPL concatenation or delete the test version
of DBUGFILE from the test library.
Step 10. Move Exit to Production (SMP/E USERMOD)
Member USECUMOD in SMXDSAMP contains a sample SMP/E USERMOD to install your
exit.
Step 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.
11-8
12-1
Chapter 12.
Memory Update Security Exit
Chap 12
Xpediter/CICS also offers a Memory Update Security Exit facility that complements the
File Update Security Exit discussed in Chapter 11, “File Update 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.
Implementing the 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.cMXD930.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.
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:
12-2
• 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.
CAUTION:
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.
Step 1. Create Global Table Override
Add an entry similar to the following to your global overrides dataset, 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 “Adding Parameter Overrides to the Dataset” on page 5-8.
Note: Although Compuware strongly recommends setting global parameter values with
an override dataset, 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” on page 4-3 for more
information.
Step 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.
Step 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.
Step 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.
Step 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.
Step 6. Shut Off Xpediter/CICS
Either shut down Xpediter by typing XPOF from a blank CICS screen and pressing Enter,
or recycle the region.
Memory Update Security Exit
12-3
Step 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 “Testing the Memory Update
Security Exit”.
CAUTION:
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.
Step 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.
Step 9. Provide Passwords to Secured Users
Testing 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
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.
12-4
13-1
Chapter 13.
Storage Protection
Chap 13
The Xpediter/CICS storage protection facility protects CICS regions from programs that
violate CICS storage areas. Storage violations cause programs to abend, produce
unexpected program results, or cause CICS region crashes.
This chapter describes how to initiate Xpediter’s storage protection facility and tailor it to
meet your needs.
The Xpediter/CICS storage protection feature, which has no dependencies on the IBM
CICS storage protection feature, supplements this protection by preventing user
applications from overwriting each other, or from overwriting any other areas that do
not belong to the application’s task. The Xpediter/CICS storage protection facility is
designed to enhance and extend the facilities provided by CICS.
Xpediter’s storage protection facility can also check data areas modified by CICS
command level commands. If the CICS command would cause a storage violation,
Xpediter can protect this storage and prevent the storage violation from occurring.
The topics covered in this chapter include:
•
•
•
•
•
•
Using storage protection
Monitoring storage violations
Disabling storage monitoring
System labels for creating storage protection exceptions
Storage protection considerations
A transaction dump example.
The Xpediter/CICS screens affected by storage protection that are described in this
chapter include the following:
•
•
•
•
Storage Protection (1.8)
Storage Exceptions (9.7)
Define System Labels (9.9)
Using Storage Protection
Xpediter/CICS allows you to select the degree of storage protection for your debugging
session.
• In the XPED/XPRT level, the Storage Protection screen (1.8) permits you to set
storage protection for any transaction or program originating from your terminal.
Global parameter PROTTID can be used to remove the restriction on setting storage
protection only for your own terminal. 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.
• In the XPSP level, the Storage Protection screen (9.8) permits you to set storage
protection for any terminal, task, or program in the CICS region.
Storage protection can be automatically set with the PROTECT option on the Set Profile
Defaults screen (0.1). The default for a new user profile can be set by tailoring the
DEFPROT parameter of the Xpediter/CICS global parameter table.
13-2
Additional storage protection can be set by using the Storage Protection screen (9.8) or
Xpediter’s DBPA transactions. See Chapter 15, “Xpediter/CICS Startup During CICS
Initialization” for more information.
When storage protection is enabled, Xpediter/CICS analyzes each application instruction
to verify that the instruction will not cause a storage violation. It also provides options
for checking program reentrancy, protecting shared storage, and executing CICS
commands.
Xpediter/CICS not only detects and prevents storage violations, it identifies the program,
transaction code, and instruction and gives the definition of the violation it is
preventing. After the potential storage violation is detected and prevented, you can
interactively debug the violating task through Xpediter’s interactive debugging
functions. Additional diagnostic reports can be created through Abend-AID for CICS by
requesting a dump of the trapped storage violation.
With Xpediter/CICS, processing may be continued around the instruction that attempted
to violate storage. This allows you to continue a test session that might otherwise have
ended in an abend or region crash. If you prefer, you can use the ALLOW command to let
the trapped storage violation take place, provided that the global table parameter
ALLOWCM is set to ON for the transaction that was used to start Xpediter.
Xpediter/CICS detects and prevents storage violations even when you are not in an active
debugging session. Xpediter/CICS intercepts the violation before it can occur and
produces a transaction abend dump. The region remains active, and programs and
storage areas are protected.
Protecting Against Storage Violations
To ensure that all transactions are tested for storage violations, use the entry shown in
Figure 13-1 on the Storage Protection screen (9.8). Since the entries are searched in the
order in which they appear, this should be the last entry on the screen. This allows other
Xpediter/CICS users to tailor their own storage protection.
Figure 13-1. Storage Protection Entries for Protecting Storage

------------------- XPEDITER/CICS - STORAGE PROTECTION (9.8) --------------C123
COMMAND ===>
SCROLL ===> CSR
MODULE:
CSECT:
ENTRY 000001
LINE COMMANDS: A (After) B (Before) C (Copy) D (Delete) I (Insert) M (Move) 
-----------PROTECTION OPTIONS-------
CMD
TYPE
TERM
TRAN
PROGRAM
STORE FETCH
SHR
PGM
CMD Store
-----------------------------------------------------------------------------
_
USER
****
****
********
YES
NO
NO
NO
YES
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
Disabling Storage Protection
To turn off storage protection without destroying the current table entries, use the
settings in Figure 13-2 for the first entry on the Storage Protection screen (9.8).
Storage Protection
13-3
Figure 13-2. Storage Protection Entries for Disabling Storage Monitoring

COMMAND ===>
SCROLL ===> CSR
MODULE:
CSECT:
ENTRY 000001
LINE COMMANDS: A (After) B (Before) C (Copy) D (Delete) I (Insert) M (Move)
CMD
TYPE
TERM
TRAN
PROGRAM
STORE FETCH
SHR
PGM
CMD Store
-----------------------------------------------------------------------------
_
SYST
****
****
********
NO
NO
NO
NO
NO
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
Protecting Language Environment User Condition
Handlers
A Language Environment user condition handler (UCH) resembles a subroutine in several
ways. A UCH can be registered like a static call and link-edited into the main code base,
or registered like a dynamically called subroutine and link-edited as a separate load
module. Since UCHs involve error handling, they are also similar to CICS handle
facilities.
There is a major difference, though, in how UCHs and CICS handle facilities process error
conditions. CICS handle facilities drive error routines in a single-stage, inline sequence.
Control is passed to an error routine that is directly responsible for branching back to the
main code base, if appropriate for a particular application. UCHs, on the other hand, use
a two-stage processing sequence that is totally independent of the main code base. The
Language Environment condition manager drives both UCH invocation and retry.
Because of the way UCHs break from the main code base, their monitoring requirements
can be very different from those of mainline applications. To deal with these potential
differences, Xpediter/CICS treats the invoking of a UCH in the same way as it does a CICS
link request. For this reason, you must make separate entries on the Storage Protection
screen (1.8 or 9.8) in order to establish storage protection for UCH modules. Specifying
exclusions for UCHs also requires individual entries on the Monitor Exceptions screen
(9.4.1).
In the following example, a mainline program registers two handlers: one for screening
conditions unique to its own processing tasks and one for screening all program checks
in the entire application. The mainline program calls an Assembler subroutine that
requires reentrancy monitoring, but the handler for screening program checks is an
Assembler module that, for valid reasons, violates reentrancy rules. In this situation, the
mainline program, its subroutines, and its general condition handler require different
protection rules than the handler that screens program checks.
As shown in Figure 13-3, a single entry on the Storage Protection screen (1.8) can be used
to establish protection for the mainline and associated routines. A separate entry is
created to protect the program check module.
13-4
Figure 13-3. Language Environment Storage Protection Entries

COMMAND ===>
SCROLL ===> CSR
MODULE: LEPROGRM CSECT: LEPROGRM
ENTRY 000001
LINE COMMANDS: A (After) B (Before) C (Copy) D (Delete) I (Insert) M (Move)
CMD
TYPE
TERM
TRAN
PROGRAM
STORE FETCH
SHR
PGM
CMD Store
-----------------------------------------------------------------------------
_
USER
T123
****
LEPROGRM
YES
NO
NO
YES
NO
_
USER
T123
****
PROGCHEK
YES
NO
NO
NO
NO
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
_
____
____
____
________
___
___
___
___
___
If the handler for program checks has been tested and is allowed to run without any form
of protection, the 1.8 entry for the mainline program can still be used. An entry on the
Monitor Exceptions screen (9.4.1) could be used to specify that the program check
module be excluded (Figure 13-4).
Figure 13-4. Handler Module Exclusion

------------------ XPEDITER/CICS - MONITOR EXCEPTIONS (9.4.1) ------------C123
COMMAND ===>
SCROLL ==> CSR
MODULE:
CSECT:
ENTRY 0000 of 000
LINE COMMANDS: L (List of Entry Points)
D (Delete)
CMD
TRAN
PROGRAM
CSECT
EXCL. LEVEL/MESAGE
------------------------------------------------------------
_
****
LEPROGRM
PROGCHEK
_
____
________
________
_
____
________
________
_
____
________
________
If an error condition occurred, control would pass from the main code base to the
program check module. The 9.4.1 entry for the program check module would cause
Xpediter/CICS to suspend its monitoring cycle during the time the module was in
control. If this handler were to percolate the condition to another handler,
Xpediter/CICS would reestablish its monitoring cycle, because the storage protection
entry encompasses the other handler.
System Labels for Creating Storage Protection
Exceptions
On the Define System Labels screen (9.9), an XPSP user can create a system label that
designates a specific storage area. That system label can then be entered on the Storage
Exceptions screen (9.7) and used to set up whatever type of storage protection exception
is needed.
Example
To remove protection from the EIB transaction ID (EIBTRNID), use the following entries.
Storage Protection
13-5
Figure 13-5. System Labels for Accessing the EIB Transaction ID

------------------ XPEDITER/CICS - DEFINE SYSTEM LABELS (9.9) -------------C123
COMMAND ===>
SCROLL ===> CSR
MODULE:
CSECT:
DEFAULT BASE LABELS:

CSA DCT EIS FCT
ADDR PADDR PLEN
MOD OFL
INITCOMM
PGM TCA TCT
MQMD MQDATA
USER
BASE
ENTRY OR
+ OR USE
RESULTING
DEL
LABEL
LABEL
PGM-NAME
OFFSET
CONTENT LENGTH
VALUE
------------------------------------------------------------------------------
_
EIB
EIS
8
Y
00000004
002030D0
_
EIBTRAN
EIB
8
N
00000004
002030D8
_
________
________
________
_________
_
________
_
________
________
________
_________
_
________
_
________
________
________
_________
_
________
_
________
________
________
_________
_
________
Once these entries are made, you can use the Storage Exceptions screen (9.7) to establish
an entry to unprotect this field.
Storage Protection Considerations
This section describes the rules Xpediter/CICS follows when monitoring for storage
violations.
• Programs with names that begin with DFH are not protected.
• Programs written in JAVA are not protected.
• “C” programs that use XPLink linkage are not protected.
• Any transaction and related programs already running when Xpediter/CICS is
initialized are not eligible for storage protection, trace, or Code Coverage
monitoring.
• If a protected program branches to a program not defined with resource definitions,
protection continues under the options of the initial, resource-defined program.
• If a protected program branches to a resource-defined program with an entry point
found by a command level EXEC CICS LOAD PROGRAM(...) HOLD, then
Xpediter/CICS scans the storage protection table to determine if the new program
qualifies for different protection or no protection.
• If a program is at a breakpoint or abend when storage protection is set for it, it will
take effect when the task is stepped/resumed.
• Xpediter/CICS storage protection does not compromise pseudo-reentrancy within a
load module. For non-reentrant code between CICS calls, Xpediter/CICS does not
interrupt you to do CICS calls.
• Xpediter/CICS protects stores and fetches defined to CICS storage boundaries. If
Xpediter/CICS cannot identify the referenced area, the reference is considered a
storage violation.
Xpediter/CICS storage protection enforces the following standards:
• Store and fetch are both allowed on the CWA unless global option PROTCWA is used.
• Store is allowed into the register save area of the EIUS. Only fetch is allowed for the
rest of the EIS or EIUS.
• Only fetch is allowed on the following:
– CSA, OFL, FCT
– User, terminal, shared storage SAAs, or storage check zones
13-6
–
–
–
–
–
–
–
FIOA-headers (56 bytes)
FWA-headers (16 bytes)
Static storage area
TCA-system area (beginning with TCASAA and ending with TCASYAA)
TCA user area
TCA-LIFO and load list storage.
TCTTE.
• Xpediter/CICS storage protection traps wild branches and branches to addresses not
aligned on a half-word boundary. However, if the program is using either HANDLEABEND or SETXIT, Xpediter/CICS assumes that the program error exit handles it, and
lets the branch be taken.
• When using storage protection, it is not necessary to increase the ICVR values.
Xpediter/CICS calculates an approximate number of user instructions for the ICVR
from CICS. It counts the instructions between CICS calls. When the user and
Xpediter/CICS (combined) exceed the ICVR, Xpediter/CICS suppresses the AICA. If
the program runs excessive instructions between CICS calls, then Xpediter/CICS
allows the AICA abend.
• When a storage violation is found, storage protection sends a message to transient
data destination CSMT. The message contains DATE, TIME, TERM, TRAN, PROGRAM,
and INSTRUCTION offset. You can change the destination or suppress the message
completely. Changing the destination or suppressing the message requires a change
to the Xpediter/CICS global parameter PROTMSG.
Transaction Dump Output
When a storage violation is detected and prevented by Xpediter/CICS, the output you
receive may include a transaction dump. Upon request, Xpediter/CICS creates an ASRA
transaction abend dump. By using the dump and the following instructions, you can
determine exactly what would have caused the storage violation. The PSW and registers
in the dump are from your program and can be used to find the instruction that is in
error. The PSW points to the instruction in error, not past it.
Xpediter/CICS uses two storage areas chained off the TCA as user-class storage (USER24
or USER31, depending on TaskDataLoc). These two storage areas are storage protection
temporary save area (TSA) and input register work area (INRWORK). They are located on
the standard storage chains. TSA may be identified by an eye catcher PROTAID followed
by x'EE'. INRWORK may be identified by an eye catcher PROTINR followed by x'EE'. For
clarification and emphasis refer to Figure 13-6 on page 13-8 and the explanation that
follows the figure.
CSMT Message
Xpediter/CICS also writes a message to transient data destination CSMT or whatever
destination was specified for global parameter PROTMSG. That message contains:
•
•
•
•
•
•
Date of the storage violation
Time of the storage violation
Storage violation message
Terminal or client IP address associated with the storage violation
Program associated with the storage violation
Offset into the associated program of the offending instruction. This offset is for use
with the compile listing’s PMAP or CLIST. It does not reflect additional
modules/stubs linked with the load module.
Note: This offset is from the beginning of the user program. That is, if the program is
command level, the stub size is backed out of the offset. This lets you match
the offset to your program listing.
Storage Protection
Transaction Dump Example
Figure 13-6 on page 13-8 is an example from a transaction abend dump created by
Xpediter/CICS. The numbered references are discussed following the figure.
13-7
13-8
Figure 13-6. Transaction Dump Example
PAGE

36

[1]
*B0000060. .;
....XPED**** 04 *
*AUG 2002 12:45:52 STORAGE VIOLAT*
*ION 0004 XCB2 CWDEMCB2 001C44
*
*
B0000060
*
0022BF90
0022BFB0
0022BFD0
0022BFF0




00000000
C2F0F0F0 F0F0F6F0
00000020
C1E4C740 F2F0F0F2
00000040
C9D6D540 F0F0F0F4
00000060
40404040 40404040


TRANSACTION STORAGE-USER24
8C40005E
40F1F27A
40E7C3C2
C2F0F0F0
40404040
F4F57AF5
F240C3E6
F0F0F6F0
00000000
C2F0F0F0 F0F0F6F0
00000020
0022A788 000C7860
00000040
002000D0 0022AFF0
00000060[3]0022BF88 17203EA8
00000080[3]172031E4 17204B1A
000000A0
000061A8 00002000
000000C0
00000000 00000000
000000E0
20000000 0022A788
00000100
58FE0060 07FF9624
00000120
00000000 00000000
00000140
00000000 00020104
00000160
00000000 00000000
00000180
00000000 000002A0
000001A0
800DB954 9604C020
000001C0
0022BF88 00207308
000001E0
0022A488 163044C0
00000200
00000000 00000000
00000220
00000000 00000000


8C000720
0022B478
000FC008
000FC338
172031A4
7FFFFFFE
00000000
00000000
F03E41FF
00000000
0E000000
00000000
00009000
41CC0008
00200050
000CBAB0
00000000
00000000
ADDRESS 0022B1D0 TO 0022B8FF
LENGTH 00000730
[2]
[2]
00000000 D7D9D6E3 C9D5D9EE 00000003 0022B1E8
*B0000060........PROTINR........Y*
0005E780 17204CBC 000061A8 0022B1E8 000F31C8
*..xh...-......X...<.../y...Y...H*
8004DE20 800F3552 000C86CA 16304600 002073A8[3]*.......0..............f........y*
16263FCC 002000D0 16309510 16308510 163044C0
*...h...y..C...........n...e.....*
00207308 97204CBC 00000000 079D2000 97204CEC[4]*...U.......u....p.<.........p.<.*
00000000 00002000 00000000 97204CEC 80000000
*../y....................p.<.....*
00000000 00000068 000CBAB0 00[5]1E8 800C8640
*...........................Y..f *
9614E058 41EE0008 9612E050 90CFE068 58DE0058
*......xh....o.......o...........*
00089622 F03690CF F04E58DF 003E58FF 004607FF
*...-..o.0.....o.0...0+..........*
00000000 00000000 00000000 0022B938 0022BAF8
*...............................8*
0022B1E8 00000000 000E0806 00000000 97204066
*...............Y............p. .*
97204CBC 164B53F0 001CD984 00002000 00000000
*............p.<....0..Rd........*
00000000 00000000 00000000 00000000 00000000
*................................*
9602C018 90CFC030 58DC0020 58FC0028 07FF0000
*....o.......o...................*
172030A8 000FC338 16263FCC 000C9640 161CFFFF
*...h...........y..C.......o ....*
0022B1E8 800C8640 00207110 97203DE2 202030A8
*..uh...........Y..f ....p..S...y*
00000000 000FC008 00000000 000C8902 00000000
*..........................i.....*
0022B404 0022B40C 162FB7DC 00007600 162FBD64
*................................*
0022B1D0
0022B1F0
0022B210
0022B230
0022B250
0022B270
0022B290
0022B2B0
0022B2D0
0022B2F0
0022B310
0022B330
0022B350
0022B370
0022B390
0022B3B0
0022B3D0
0022B3F0


















ADDRESS 0022A780 TO 0022B1CF
LENGTH 00000A50
[6]
[6]
8C000A3C 00000000 D7D9D6E3 C1C9C4EE 00000003 0022A788
*B0000060........PROTAID.......xh*
0022B478 0005E780 0022B1E8 16309510 0022B1E8 000DB7E0
*..xh...-......X....Y..n....Y....*
000FC008 8004DE20 000DB989 000D5AF8 00000000 00000000
*......Zh...........i...8........*
00000000 000000BB 00000000 00000000 00000000 00000000
*.......Y........................*
0000000[7]7203088 A6000000 F0F0F0F4 164B53F0 000C7860
*...............hw...0004...0...-*
00000000 0022BF88 00000000[7]404040 40404040 40404040
*...............h....
*
000FC008 8004DE20 164B53F0 91000000 16304600 002073A8
*......X............0j..........y*
97204CEC 000061A8 000C9640 7FFFFFFE 000000E5 00000068
*...h..xhp.<.../y..o .......V....*
800C8640 00207308 800C913E 0000001C 0022BF88 800CE328
*.......Y..f ......j........h..T.*
000C7860 800CD530 0022BF8F 0022BF87 0022B1E8 000CE530
*..X...xh...-..N........g...Y..V.*
000FC008 8004DE20 800CEBBE 00000004 00000000 00000000
*n..8...0........................*
00000000 00000000 00000000 00000000 00000000 00000000
*................................*
00200448 00228E27 16303798 16310A17 0022BF78 0022BF87
*...................q...........g*
00000000 00000000 00000000 0022BF88 0022BF88 00000000
*.......g...............h...h....*
00000000 00000000 00000000 00000000 00000000 00000000
*;...STOR........................*
00000000 00000000 00000000 800CDAE2 164B14B0 00000000
*.......................S........*
00000000 00000000 00000000 00000000 00000000 00000000
*................................*
00000000 00000000 00000000 00000000 00000000 00000000
*................................*
00000000 00000000 00000000 00000000 D6F5F3F0 F661F2F8
*........................O5306/28*
000F8EE0 0002A000 02000100 00000000 00000000 00000000
*/0217.20........................*
00000000 00000000 0BF80000 16310E80 000FD0B0 16310ED0
*.................8..............*
0022A780
0022A7A0
0022A7C0
0022A7E0
0022A800
0022A820
0022A840
0022A860
0022A880
0022A8A0
0022A8C0
0022A8E0
0022A900
0022A920
0022A940
0022A960
0022A980
0022A9A0
0022A9C0
0022A9E0
0022AA00




















00000000
C2F0F0F0
00000020
0022A788
00000040
002000D0
00000060
00000000
00000080
00000000
000000A0
00000000
000000C0
00000000
000000E0
0022BF88
00000100
000CBAB0
00000120
0005E780
00000140
9572B9F8
00000160
00000000
00000180
00000000
000001A0
0022BF78
000001C0[8]5E000002
000001E0
00000000
00000200
00000000
00000220
00000000
00000240
00000000
00000260
61F0F2F1
00000280
00000000
F0F0F6F0
000C7860
0005E988
0022B1E8
00000000
00000000
0005E780
0022A788
0022B1E8
0022A788
0022AFF0
00000000
00000000
0022BF87
E2E3D6D9
00000000
00000000
00000000
00000000
F74BF2F0
00000000
00560000 E7D7C5C4 5C5C5C5C 40F0F440
F240E2E3 D6D9C1C7 C540E5C9 D6D3C1E3
C4C5D4C3 C2F240F0 F0F1C3F4 F4404040
TIME=12:46:06
ACMEC123
--- CICS TRANSACTION DUMP --- CODE=STOR
TRAN=XCB2
ID=1/0002
DATE=02/08/04


ADDRESS 0022BF90 TO 0022BFFF
LENGTH 00000070
Storage Protection
13-9
The following explanation discusses the numbered references in Figure 13-6 on page
13-8.
[1] Message written to transient data destination CSMT.
[2] INRWORK identified by PROTINR eye catcher followed by x'EE'.
[3] INRWORK + x'58' contains the contents of registers 0 through 15 as they were at the
time of the attempted storage violation.
[4] INRWORK + x'9C' contains the address of the instruction that would have caused the
storage violation.
[5] INRWORK + x'B8' contains the address of the instruction executed prior to the
instruction that would have caused the storage violation. For example, if the storage
violation was caused by a bad branch, this would be the address of the branch
instruction.
Note: The address at INRWORK + x'B8' will be the same as the address at INRWORK +
x'9C' for non-branch instructions.
[6] TSA identified by PROTAID eye catcher followed by x'EE'.
[7] TSA + x'A8' and TSA + x'D4' contain the address validation information. Beginning at
x'A8', there is a four-byte length and four-byte address for field 1. This is followed by a
four-byte length and four-byte address for field 2 and again for field 3. Beginning at
x'D4', there is a one-byte code for each of the three fields (as described in “Address
Validation Codes” below).
[8]TSA + x'1C0' contains the Xpediter/CICS detailed error code.
Address Validation Codes
Each of the three address validation entries beginning at TSA + x'A8' contains a four-byte
length and a four-byte virtual storage beginning address. For each of the three entries,
there is a corresponding one-byte code beginning at TSA + x'D4'. The following values are
accumulated in that one-byte code field:
• x'01' - The address list entry identified as a storage violation. This is the entry in
error.
• x'10' - Store protection validation was requested for this address.
• x'20' - Branch address protection validation was requested for this address.
• x'40' - Fetch protection validation was requested for this address.
• x'80' - Last entry in the address list.
For example, if the 1 byte CODE field contains x'91', this indicates that this is the final
entry in the list (x'80'), it was monitored for store protection (x'10'), and a storage
violation was detected (x'01'). The beginning address and length fields describe the
storage involved. The detailed error code describes the operation that would have caused
a storage violation.
Detailed Error Codes
The Xpediter/CICS detailed error code located in the TSA at x'1C0' explains the detected
storage violation. With the code from the TSA, see Xpediter/CICS system messages to
locate the corresponding explanation.
13-10
14-1
Chapter 14.
Specifying DBPA Transaction Input
Chap 14
Xpediter uses DBPA transactions to set storage protection and abend trapping options
during product initialization. A sequential dataset with the desired transactions is read at
Xpediter startup.
All you need to do is create the dataset and put a DD statement pointing to it in your
CICS startup JCL. Comments and blank lines are allowed within your DBPA transaction
images. A printed report echoes the input transactions and provides any error messages.
In addition, a standalone transaction, XDBP, can be used to refresh the parameters from
the input dataset. This eliminates the need to recycle Xpediter or the CICS region when
you want to make storage protection or abend trapping option changes.
This chapter includes sections on the following topics:
• Processing of the DBPA transaction input dataset
• Overriding input and report dataset ddnames
• Format of the DBPA transaction processing report and console log output.
“DBPA Transaction Input Dataset” on page 14-4 contains step by step instructions for
setting up your own DBPA transactions sequential dataset.
If your site uses Xpediter/Code Coverage, this method can be used to define Code
Coverage tests. See the Xpediter/Code Coverage Mainframe User/Reference Guide for details.
Processing Overview
DBPA transaction images are read from the dataset pointed to by the XDDBPINP DD. This
DD must be added to the CICS startup JCL. If no DD is found in the JCL, no DBPA
transaction processing will occur. If a DD already exists in the CICS startup JCL with this
name, you can override the ddname to be used. Refer to “Override Processing of
ddnames”.
As the input is processed, a printed report is written to a SYSOUT dataset dynamically
allocated to the XDDBPRPT DD. If a DD for XDDBPRPT already exists in the CICS startup
JCL, no report is produced. The default ddname, XDDBPRPT, can be overridden. Refer to
“Override Processing of ddnames”.
DBPA transaction images are processed in the order in which they are read. Blank records
and comment records are ignored and written to the output report. DBPA transactions
images are also written to the output report. See “DBPA Transaction Image Guidelines”
on page 14-7 for DBPA transaction format and processing rules.
If an error is detected in a transaction image, the record — along with an error message —
is written to the output report. Refer to the Xpediter/CICS Messages and Codes manual for a
list of possible messages.
14-2
Override Processing of ddnames
XDDBPINP
XDDBPINP is the default ddname for the input dataset containing the DBPA transaction
images. This ddname can be overridden with the XDDBPIN parameter override as
XDDBPINP ddname overrides are processed in the following order:
1. The ddname is set to the default name XDDBPINP.
3. INITPARM is checked for a DBUGSIT value for XDDBPIN. If present, the value is
validated. If the value is valid, the ddname is set to that value.
XDDBPRPT
The default ddname for the report dataset is XDDBPRPT. The default SYSOUT class is
asterisk (*). The report ddname can be overridden with the XDDBPRP parameter override.
The SYSOUT class can be overridden with the XDDBPCL parameter override. This is
The XDDBPRPT ddname and SYSOUT class overrides are processed in the following order.
1. The ddname is set to the default name XDDBPRPT and the SYSOUT class to the
default class *.
3. If the global table contains a valid override SYSOUT class, the SYSOUT class is set to
that value.
4. INITPARM is checked for DBUGSIT values for XDDBPRP and XDDBPCL. If present,
the values are validated. If the ddname value for XDDBPRP is present and valid, the
ddname is set to that value. If the SYSOUT class value for XDDBPCL is present and
valid, the SYSOUT class is set to that value.
5. The first record of the input dataset is checked for the XDDBPRP and XDDBPCL
parameters. If present, the values are validated. If the ddname value for XDDBPRP is
present and valid, the ddname is set to that value. If the SYSOUT class value for
XDDBPCL is present and valid, the SYSOUT class is set to that value.
DBPA Transaction Processing Report
The DBPA transaction processing report is produced as a dynamically allocated SYSOUT
dataset. The report is optional, and if any errors occur while allocating the report dataset,
processing can still continue.
Figure 14-1 is a sample Xpediter/CICS DBPA transaction processing report. The numbered
references are discussed following the figure.
14-3
Figure 14-1. Sample DBPA Transaction Processing Report
XPEDITER/CICS DBPA TRANSACTION PROCESSING REPORT
APPLID: ACMEC123 DATE: 30 SEP 2003 TIME: 14:29:58 USERID: MYUSRID
PAGE
1
TERM: A011[1]

[2]
INPUT DDNAME XDDBPINP (DEFAULT NAME).
REPORT DDNAME DBPAMSGS (OVERRIDE FROM FIRST INPUT RECORD).

INPUT RECORD/ERROR MESSAGE
------------------------------------------------------------------------

[3]XDDBPRP=DBPAMSGS
DBPA TRANSACTION REPORT GOES TO THIS DD
*-----------------------------------------------------------------------
* TEST FOR XPEDITER/CICS DBPA INPUT (STORAGE MONITORING) PARAMETERS.
[4]
*
* BLANK RECORDS ARE IGNORED.
*
* RECORDS STARTING WITH ’*’ IN COLUMN 1 ARE TREATED AS COMMENTS.
*
* COLUMNS 1 THROUGH 72 OF A RECORD ARE PROCESSED. ANYTHING BEYOND
* COLUMN 72 IS DISCARDED.
*
*-----------------------------------------------------------------------
* THIS ENTRY DEFINES LABEL ’PGMLEN01’ FOR LENGTH OF PROGRAM DBUGSIT
*-----------------------------------------------------------------------
DBPA 9.9 NL=PGMLEN01,EL=PLEN,EN=DBUGSIT
*-----------------------------------------------------------------------
* THIS ENTRY DEFINES LABEL ’PGMLEN02’ FOR LENGTH OF PROGRAM DBUGDBPA
*-----------------------------------------------------------------------
DBPA 9.9 NL=PGMLEN02,EL=PLEN,EN=DBUGDBPA
*-----------------------------------------------------------------------
* THIS ENTRY IS BAD
*-----------------------------------------------------------------------
ERROR> DBPA 7.8 NL=PGMLEN02,EL=PLEN,EN=DBUGDBPA
<--- ERROR[5]
ERROR> **** INVALID KEYWORD.
<--- ERROR[5]
*-----------------------------------------------------------------------
* IGNORE MONITORING FOR XSIT
*-----------------------------------------------------------------------
DBPA 9.4.1 TRAN=XSIT
[1] The second heading line indicates the CICS region applid, date, time, terminal, and
userID of the user logged on to the terminal when program DBUGPPM2 was run.
[2] These heading lines indicate the ddnames used for the input and report datasets. In
addition, they indicate whether the ddnames used are the default names or have been
overriden by the user.
[3] DBPA transaction images, including blank lines and comments, are displayed from
here down. This provides a complete audit of the transactions processed.
[4] This sample report includes comments explaining the processing rules for DBPA
transaction input.
[5] When an error is detected on an input record, the error is flagged. The line that
follows contains a message indicating the error detected and is also flagged. Only the first
error detected for a transaction image is flagged.
DBPA Transaction Processing Console Log Output
Messages are written to the console log whenever the DBPA transaction process is run.
Figure 14-2 is a sample of output written to the console.
14-4
Messages that do not apply to a particular DBPA transaction image are displayed with two
lines per message. All messages contain similar information on the first line including a
message number, severity level, date, time, and region applid. This provides two places
that can be checked for error conditions. Messages that apply to a particular DBPA
transaction image are displayed with three lines per message. The second line contains
the first 71 bytes of the input image. The third line contains the message text.
Figure 14-2. Sample DBPA Transaction Input Console Log Output
11.09.24 JOB00568
11.09.24 JOB00568
11.09.24 JOB00568
+XDDPA0000 I 30 SEP 2003 11:09:24 ACMEC123
XPEDITER/CICS DBPA TRANSACTION PROCESSING HAS BEGUN.
+XDDPA0011 I 30 SEP 2003 11:09:24 ACMEC123
SEE SYSOUT DD XDDBPRPT FOR REPORT.
+XDDPA0001 I 30 SEP 2003 11:09:24 ACMEC123
XPEDITER/CICS DBPA TRANSACTION PROCESSING HAS ENDED.
DBPA Transaction Input Dataset
This section describes the steps necessary to create a PDS or PDSE that will contain
storage protection and abend trapping override records in the form of DBPA transactions.
These records will be read during product initialization to allow modification of storage
protection and abend trapping rules.
Even if you don’t need to use DBPA transaction input at this time, Compuware suggests
that you modify your CICS startup JCL and use the skeleton member created in this
procedure. Nothing will be harmed, and if you later need to use DBPA transaction input,
the dataset will be ready for use.
Although DBPA transaction input can come from a SYSIN dataset or flat sequential
dataset, the preferred method is for the input to come from a PDS or PDSE. The
advantages include ease of installation, flexibility in maintenance of input, and the
ability to modify the DBPA transaction dataset while the region is active.
Initially, you should use a test CICS region to test your DBPA transaction input
processing. After reviewing the output and the actual processing, you will easily be able
to modify all your CICS regions.
Setting Up the Dataset
Perform the following steps to establish DBPA transaction input processing.
1. Create the DBPA transaction input dataset and default member.
The JCL in Figure 14-3 defines the DBPA transaction input dataset. The actual JCL
may be found in CPWR.cMXD930.SMXDSAMP (where c represents the CICS release)
member DBCDEFDB. This JCL also creates a default member needed in later steps.
When modifying the JCL, write the name you use for the DSNNAME parameter of
procedure DEFDBPA [1] in the space below:
Input dataset name:____________________
14-5
Figure 14-3. Sample JCL to Define the DBPA Transactions Input Dataset
//* =====>
INSERT JOBCARD HERE
<=====
//*********************************************************************
//*
*
//* DBCDEFDB THIS MEMBER ALLOCATES AND CREATES A DEFAULT MEMBER
*
//*
IN THE XPEDITER/CICS TRANSACTION INPUT DATASET.
*
//*
*
//*********************************************************************
//DEFDBPA PROC DSNNAME=’XPEDITER.CICS.DBPA.TRANS’,[1] <== CHECK DSN
//
DUNIT=’SYSDA’,
<== CHECK UNIT
//
DVOL=’VOLSER’,
<== CHECK VOLSER
//
DBLOCK=3200
//*********************************************************************
//*
*
//* ALLOCATE THE XPEDITER/CICS DBPA TRANSACTION INPUT DATASET
*
//*
*
//* NOTE: SPACE PARAMETER VALUES ARE ONLY ESTIMATES. DEPENDING ON
*
//*
THE NUMBER OF DBPA TRANSACTIONS AND INDIVIDUAL MEMBERS
*
//*
YOU DECIDE TO USE, MAY IMPACT THE SPACE REQUIREMENTS.
*
//*
THE SPACE ALLOCATION DEFAULTS SHOULD BE ACCEPTABLE TO THE *
//*
MAJORITY OF INSTALLATIONS.
*
//*
*
//*********************************************************************
//ALLOC
EXEC PGM=IEFBR14
//XDDBPINP DD DSN=&DSNNAME,
//
DISP=(,CATLG),
//
VOL=SER=&DVOL,
//
UNIT=&DUNIT,
//*
DSNTYPE=LIBRARY,
<=== UNCOMMENT IF PDS/E DESIRED
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=&DBLOCK),
//
SPACE=(TRK,(10,5,25))
//*********************************************************************
//*
*
//* CREATE A SKELETON MEMBER, NAMED DEFAULT. THIS MEMBER CAN BE
*
//* USED AS A MODEL FOR FUTURE MEMBER DEFINITIONS.
*
//*
*
//*********************************************************************
//LOADIT
EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD DUMMY
//SYSIN
DD DDNAME=DEFAULT
//SYSUT2
DD DSN=&DSNNAME,DISP=SHR
//
PEND
//DBCDEFDB EXEC DEFDBPA
//LOADIT.DEFAULT DD *
******************************* NOTE ***********************************
* PLEASE CHANGE THE FOLLOWING "/*./" TO "./"
*************************************************************************
/*./ ADD NAME=DEFDBPA
XDDBPCL=?,XDDBPRP=RPTDD
DBPA TRANSACTION REPORT CLASS/DDNAME

*----------------------------------------------------------------------*
*
XPEDITER/CICS DBPA TRANSACTION INPUT
*
*
STORAGE MONITORING PARAMETERS
*
*
*
* BLANK RECORDS ARE IGNORED.
*
*
*
* RECORDS STARTING WITH ’*’ IN COLUMN 1 ARE TREATED AS COMMENTS.
*
*
*
* COLUMNS 1 THROUGH 72 OF A RECORD ARE PROCESSED. ANYTHING BEYOND
*
* COLUMN 72 IS DISCARDED.
*
*
*
*
PLACE DBPA TRANSACTIONS FOLLOWING THIS COMMENT BOX
*
*----------------------------------------------------------------------*
/*
14-6
2. Create your own transaction member in the DBPA transaction input dataset.
a. Create a new member in your DBPA transaction input dataset.
b. Copy member DEFDBPA into it.
c. Write the member name below:
Member name:____________________
This method of specifying DBPA transactions is very flexible. If you wanted to create
storage protection entries for a specific CICS region, you could use the CICS startup
JCL member name. You could also create a single member for all regions. By using
dataset concatenation as shown below, you could create a set of members to control
the DBPA transaction process. You could have a member common to all regions, a
member specifically for test regions, and a member for a single region.
For example, you could define a member name DBPACOMM that contained a set of
storage protection rules common to all regions. Member DBPATEST could contain
rules intended for test regions. Finally, member DBPA0001 would have rules
specifically for region CICS0001. By using the following concatenated DD statement,
the input would be processed as a single input stream, with the records from
DBPACOMM read first, followed by those from DBPATEST, and finally the records in
member DBPA0001.
//XDDBPINP DD DISP=SHR,DSN=XPEDITER.CICS.DBPA.TRANS(DBPACOMM)
//
DD DISP=SHR,DSN=XPEDITER.CICS.DBPA.TRANS(DBPATEST)
//
DD DISP=SHR,DSN=XPEDITER.CICS.DBPA.TRANS(DBPA0001)
A member, DEFLBEIB, has been provided in SMXDSAMP member that contains a
DBPA image to create a system label (EIB) that can be used in creating storage
protection entries and abend trapping options. Member DEFLBEIB defines a system
label. System labels must be defined prior to being referenced. Concatenate the member(s)
you created in this step after member DEFLBEIB.
3. Establish a ddname for the DBPA transaction input dataset.
with the ddname XDDBPINP in your JCL, select a new ddname not in your JCL and
write it in the space below. Otherwise, just write in XDDBPINP.
Input ddname:____________________
4. Establish a ddname for the DBPA transaction report dataset.
with the ddname XDDBPRPT in your JCL, select a new ddname not in your JCL and
write it in the space below. Otherwise, just write in XDDBPRPT.
Report ddname:____________________
5. Choose a SYSOUT class for the DBPA transaction report.
The SYSOUT class is a one byte value in the range A through Z, 0 through 9, or an
asterisk (*). If you specify a JES output class that requests immediate printing, the
output will be printed after the DBPA transaction input has been processed.
Otherwise it will remain with the normal JES output for the region until CICS ends.
Enter your SYSOUT class in the space below.
SYSOUT Class:____
6. Set your DBPA transaction input global table parameters.
a. If your region is set up to read global table parameter overrides from a sequential
dataset as described in Chapter 5, “Overriding Global Parameters”, go to step
step 7 on page 14-7 to set the required parameters. Otherwise continue with step
b.
b. Review Chapter 5, “Overriding Global Parameters” for instructions on setting
up your CICS region for global table parameter overrides. This facility allows you
to easily change global table parameters without having to assemble or link-edit
14-7
the Xpediter global table. Compuware strongly suggests you do this now, and
then continue with step step 7. If you do not want to do this now, continue with
step c.
c. Use the system initialization table (SIT) INITPARM parameter as follows. No
assembly or link-edit of the global table is required.
1. Review the startup JCL for the CICS region you are modifying. Locate the SIT
override dataset. If the SIT overrides are in an instream SYSIN dataset, write
the name of the CICS startup JCL member below. Otherwise write the name
of the separate SIT override dataset.
CICS SIT override dataset:____________________
2. Edit the dataset you wrote in above. Refer to the ddnames and SYSOUT class
you wrote in earlier. Add an INITPARM parameter — or modify your existing
INITPARM parameter — as shown below, using your “Input ddname” in place
of myddname, your “Report ddname” in place of rptddnam, and your
“SYSOUT class” in place of the ?.
INITPARM=(DBUGSIT=’XDDBPIN=myddname,XDDBPRP=rptddnam,
XDDBPCL=?’,...any existing parameters)
3. Save the dataset.
7. Modify global table parameter overrides dataset.
Edit your global overrides dataset member. The dataset and member names should be
written down in Chapter 5, “Overriding Global Parameters” and can also be found
in your CICS startup JCL.
a. Refer to the ddnames and SYSOUT class you wrote in earlier. Add the following
three overrides anywhere after the first record, using your “Input ddname” in
place of myddname, your “Report ddname” in place of rptddnam, and your
“SYSOUT class” in place of the ?.
XDDBPIN=myddname
XDDBPRP=rptddnam
XDDBPCL=?
DBPA transaction input ddname
DBPA transaction report ddname
DBPA transaction report SYSOUT class
b. Save the member.
8. Add a DD statement for the DBPA transaction input dataset to your CICS startup
JCL.
a. Edit your CICS startup JCL. Refer to the DBPA transaction input dataset name,
member name, and ddname you wrote in earlier. Add the following DD
statement to the CICS step, using your “Input ddname” in place of myddname,
your “Input dataset name” in place of dataset, and your “Member name” in
place of member.
//myddname DD DISP=SHR,DSN=dataset(member)
b. Save your modified CICS startup JCL.
That completes the setup of the DBPA transaction input facility. You have successfully
created a basic DBPA transaction member and modified your CICS startup JCL to allow
input of DBPA transactions from a dataset. Before adding transactions to your basic DBPA
member, refer to “DBPA Transaction Image Guidelines” on page 14-7. To use your DBPA
transaction input at CICS initialization, follow the instructions in Chapter 15,
“Xpediter/CICS Startup During CICS Initialization”.
DBPA Transaction Image Guidelines
The skeleton member you created 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. Chapter 15, “Xpediter/CICS Startup During CICS Initialization”
14-8
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.
15-1
Chapter 15.
Xpediter/CICS Startup During CICS Initialization
Chap 15
Xpediter/CICS allows storage protection and abend trapping options to be set at product
startup during CICS initialization. This is done with DBPA entries, either by accessing
them at program list table (PLT) startup or by submitting them as sequential terminal
input. Detailed information about DBPA entries can be found in Chapter 14,
“Specifying DBPA Transaction Input”.
Specifying DBPA Entries via Input Dataset
To utilize the input dataset method of specifying DBPA entries:
1. Carefully review Chapter 14, “Specifying DBPA Transaction Input” and perform
the necessary procedures.
2. Develop any DBPA entries you wish to use and add them to the input dataset
member created in step 1. Refer to “DBPA Transactions” on page 15-2.
3. Determine whether initializing Xpediter/CICS via PLT or sequential terminal input is
more appropriate for your site, then continue with the corresponding section below.
Initializing Xpediter via PLT Startup
To use the PLT startup method of specifying DBPA entries, you must modify the program
list table post initialization (PLTPI) table as follows:
1. Add program DBUGPPM2 to your PLTPI table program.
Note: DBUGPPM2 must be after the DFHDELIM entry.
2. Assemble and link edit your PLTPI table program.
Initializing Xpediter with Sequential Terminal Input
Only two simple transaction images are required to establish storage protection and
abend trapping options when using the input dataset method:
1. Enter the transaction image DBPA ON\. DBPA must begin in column 1, and ON must
begin in column 6.
Note: System initialization parameter EODI can be used to change the default
backslash (X'E0') end-of-data indicator.
2. After the Xpediter DBPA ON transaction, you must enter the CICS sign-off
transaction CESF GOODNIGHT\.
Note: If you are unfamiliar with sequential terminal input, refer to the CICS Application
Programmer’s Reference Manual.
15-2
DBPA Transactions
The DBPA transaction sets abend traps or storage protection entries when CICS is first
started. You may use it as sequential terminal input or as input during PLTPI processing.
Do not use this transaction from a terminal once CICS is running.
CAUTION:
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
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)
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:
Example:
DBPA
DBPA
DBPA
DBPA
DBPA
DBPA
ON (required only for sequential terminal input)
9.9 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 15-1.
Table 15-1. 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.
15-3
Table 15-1. Trap Summary Keywords
Keyword
Comments
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.
• 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.
Examples
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')
15-4
Monitor Exceptions Keywords
The keywords for creating entries for the Monitor Exceptions screen (9.4.1) are defined in
Table 15-2.
Table 15-2. 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=
********
CS=
Mask to define the name of the CSECT(s) to be excluded from
monitoring.
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=*
Example 3:
All programs with CSECT TESTCST are excluded from monitoring.
DBPA 9.4.1 TR=*,PG=*,CS=TESTCST
Note: 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 15-3.
Table 15-3. CSECT Exclusion Keywords
Keyword
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*.
15-5
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 15-4. Wherever YES/NO
is specified in the Comments column, Y/N can also be used.
Table 15-4. 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
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:
15-6
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).
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
16-1
Chapter 16.
Language Environment Operation
Chap 16
This chapter explains how to use Xpediter with Language Environment.
Setting 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 16-1 and make the necessary changes. Each setting is explained following
the table.
Table 16-1. CEECOPT Option Settings
Option
Required Setting
ABTERMENC ABEND
TRAP
ON
Establishes enclave termination behavior for conditions of severity 2 and above. This must
ABTERMENC 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 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
16-2
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 31bit 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.
17-1
Chapter 17.
Configuring the Script Facility
Chap 17
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.
Note: 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.
Follow the step-by-step instructions in “Setting Up the Script Facility” on page 17-2 to
enable the Xpediter/CICS Script Facility. If your site does not want to use the Script
Facility, go to “Disabling the Script Facility” on page 17-7.
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. User-defined user script datasets, if allowed by your site, do not need to be preallocated. 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
17-2
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 global parameter overrides dataset. If your site does not use dynamic
allocation, you will need to modify your CICS startup JCL in addition to specifying
global parameter changes.
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 your global parameter override dataset.
All of the global parameters set in this chapter are described in Chapter 4, “Global
Parameters Table”. For details on modifying the override dataset, see “Adding Parameter
Overrides to the Dataset” on page 5-8.
Your site’s external security manager — RACF for example — must grant authority to
create Xpediter’s system and user script datasets.
information.
1. Enable the Script Facility.
Enable the Script Facility by adding the following line to your site’s global parameter
overrides dataset:
XDSCRPT=YES
Enable Xpediter/CICS Script Facility
2. Add program DBUGPLTS to your CICS shutdown PLT.
Note: 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:
After adding the entry, reassemble and relink your PLTSD module.
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 shown in Figure 17-1 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.
17-3
a. Add a job card and any necessary OUTPUT specifications to the front of the
member.
b. 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:____________________
Note: Your site’s external security manager must grant authority to create system
script datasets with the chosen dsn.
c. Change the XDSSUNI parameter to the DASD unit name on which the dataset is
to be allocated.
d. Change the XDSSVOL parameter to the volume and serial number on which the
dataset is to be allocated.
Figure 17-1. Sample JCL to Allocate a System Script Dataset (DBCDEFSS)
//* =====>
INSERT JOBCARD HERE
<=====
//*********************************************************************
//*
*
//* DBCDEFSS THIS MEMBER CREATES A DATASET FOR USE AS AN
*
//*
XPEDITER/CICS SYSTEM SCRIPT DATASET.
*
//*
*
//* NOTE: SPACE PARAMETER VALUES ARE ONLY ESTIMATES. THE NUMBER
*
//*
OF INDIVIDUAL MEMBERS AND SIZE OF MEMBERS MAY IMPACT THE
*
//*
SPACE REQUIREMENTS.
*
//*
*
//*********************************************************************
//DEFSCR PROC XDSSDSN=’XD.SYSTEM.SCRIPT.DATASET’, <== CHECK DSN
//
XDSSUNI=’SYSDA’,
<== CHECK UNIT
//
XDSSVOL=’VOLSER’,
<== CHECK VOLSER
//
XDSSBLK=27960,
//
XDSSTYP=TRK,
<== CHECK ALLOC TYPE
//
XDSSPA=15,
<== CHECK PRIMARY
//
XDSSSA=15,
<== CHECK SECONDARY
//
XDSSDB=44
<== CHECK DIRBLOCKS
//*********************************************************************
//*
*
//* CREATE AN XPEDITER/CICS SYSTEM SCRIPT DATASET
*
//*
*
//*********************************************************************
//ALLOC
EXEC PGM=IEFBR14
//XDSCRIPT DD DSN=&XDSSDSN,
//
DISP=(,CATLG),
//
VOL=SER=&XDSSVOL,
//
UNIT=&XDSSUNI,
//*
DSNTYPE=LIBRARY,
<=== UNCOMMENT IF PDSE DESIRED
//
DCB=(RECFM=FB,LRECL=120,BLKSIZE=&XDSSBLK),
//
SPACE=(&XDSSTYP,(&XDSSPA,&XDSSSA,&XDSSDB))
//
PEND
//DBCDEFSS EXEC DEFSCR
e. 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.
f. If you want the dataset to be allocated as a PDSE, uncomment the line reading
DSNTYPE=LIBRARY,.
g. The following parameters can also be changed, if required:
• XDSSTYP=TRK — allocation type
• XDSSPA=15 — primary allocation units
17-4
• XDSSSA=15 — secondary allocation units
• XDSSDB=44 — number of directory blocks.
h. Submit the JCL to allocate your system script dataset.
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 global
overrides dataset:
XDSSACC=READONLY
System script is READONLY
To enable WRITE access, add the following parameter to your global overrides
dataset:
XDSSACC=WRITE
System script is READ/WRITE
5. Enable allocation of your system script dataset.
If your site allows dynamic allocation of datasets in CICS regions, go to step a. If your
site does not allow dynamic allocation of datasets in a CICS region, go to step b.
a. Add the following parameters to your global overrides dataset:
XDSSDD=DYNAMIC
System script dynamically alloc.
XDSSDSN= dsn from step 3, substep b on page 17-3
No CICS startup JCL changes are needed.
Go to step 6.
b. Modify your global overrides dataset and CICS startup JCL as follows:
1. Select a 1- to 8-character ddname for your system script dataset and write it
below:
ddname:____________________
2. Add the following parameter to your global overrides dataset:
XDSSDD= ddname written above System script not dynamically alloc.
3. Add the following DD statement to your CICS startup JCL:
//ddname written above DD DISP=SHR,DSN=dsn from step 3, substep b on page
17-3
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.
Note: 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 step 7.
If you want user script datasets, but your site does not allow dynamic allocation of
datasets in CICS regions, go to step 9 on page 17-5.
If your site does not want the enhanced useability provided by user script datasets, go
to step 11 on page 17-7.
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 userdefined user script datasets.
17-5
If you want user-defined user script datasets, continue with step 8.
If your site wants to restrict users to a single shared user script dataset, go to step 9.
8. Enable allocation of user-defined user script datasets.
The first two global parameters in this step establish dynamically allocated userdefined 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, consult
Chapter 4, “Global Parameters Table” for more information.
Add the parameters listed below to your global overrides dataset. 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 step 11 on page 17-7.
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.
Member DBCDEFUS shown in Figure 17-2 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.
member.
b. 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:____________________
c. Change the XDUSUNI parameter to the DASD unit name on which the dataset is
to be allocated.
d. Change the XDUSVOL parameter to the volume and serial number on which the
dataset is to be allocated.
17-6
Figure 17-2. Sample JCL to Allocate a User Script Dataset (DBCDEFUS)
//* =====>
INSERT JOBCARD HERE
<=====
//*********************************************************************
//*
*
//* DBCDEFUS THIS MEMBER CREATES A DATASET FOR USE AS AN
*
//*
XPEDITER/CICS USER SCRIPT DATASET.
*
//*
*
//* NOTE: SPACE PARAMETER VALUES ARE ONLY ESTIMATES. THE NUMBER
*
//*
OF INDIVIDUAL MEMBERS AND SIZE OF MEMBERS MAY IMPACT THE
*
//*
SPACE REQUIREMENTS.
*
//*
*
//*********************************************************************
//DEFSCR PROC XDUSDSN=’XD.USER.SCRIPT.DATASET’,
<== CHECK DSN
//
XDUSUNI=’SYSDA’,
<== CHECK UNIT
//
XDUSVOL=’VOLSER’,
<== CHECK VOLSER
//
XDUSBLK=27960,
//
XDUSTYP=TRK,
<== CHECK ALLOC TYPE
//
XDUSPA=15,
<== CHECK PRIMARY
//
XDUSSA=15,
<== CHECK SECONDARY
//
XDUSDB=44
<== CHECK DIRBLOCKS
//*********************************************************************
//*
*
//* CREATE AN XPEDITER/CICS USER SCRIPT DATASET
*
//*
*
//*********************************************************************
//ALLOC
EXEC PGM=IEFBR14
//XDSCRIPT DD DSN=&XDUSDSN,
//
DISP=(,CATLG),
//
VOL=SER=&XDUSVOL,
//
UNIT=&XDUSUNI,
//*
DSNTYPE=LIBRARY,
<=== UNCOMMENT IF PDSE DESIRED
//
DCB=(RECFM=FB,LRECL=120,BLKSIZE=&XDUSBLK),
//
SPACE=(&XDUSTYP,(&XDUSPA,&XDUSSA,&XDUSDB))
//
PEND
//DBCDEFUS EXEC DEFSCR
e. 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.
f. If you want the dataset to be allocated as a PDSE, uncomment the line reading
DSNTYPE=LIBRARY,.
g. 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.
h. Submit the JCL to allocate your user script dataset.
10. Enable allocation of your user script dataset.
a. Add the following parameters to your global overrides dataset:
XDUSDD=DYNAMIC
User script dynamically alloc.
XDUSDSN= dsn from step 9, substep b on page 17-5
Go to step 11.
17-7
1. Select a 1- to 8-character ddname for your user script dataset and write it
below:
ddname:____________________
XDUSDD= ddname written above User script not dynamically alloc.
// ddname written above DD DISP=SHR,DSN= dsn from step 9, substep b on
page 17-5
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).
Add the following parameters to your global overrides dataset:
XDSCRXO=SAVE
XDSCRXN=********
Save script if CAPTURE command active
Save script with user ID as script name
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 override dataset:
XDSCRPT=NO
Disable Xpediter/CICS Script Facility
For more information, see “Adding Parameter Overrides to the Dataset” on page 5-8.
17-8
18-1
Chapter 18.
File Utility Audit Trail
Chap 18
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” on page
18-2 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” on page 18-5.
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.
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.
18-2
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” on page 18-5.
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 global parameter overrides dataset. 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.
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 your global parameter override
dataset. All of the global parameters set in this chapter are described in Chapter 4,
“Global Parameters Table”. For details on modifying the override dataset, see “Adding
Parameter Overrides to the Dataset” on page 5-8.
Your site’s external security manager — RACF for example — must grant authority to
create Xpediter’s File Utility Audit Trail GDG dataset.
information.
1. Enable the File Utility Audit Trail Facility.
Enable the File Utility Audit Trail by adding the following line to your site’s global
parameter overrides dataset:
XDLOG=YES
Enable Xpediter/CICS File Utility Audit Trail
2. Add program DBUGPLTS to your CICS shutdown PLT.
Note: You may skip this step if DBUGPLTS was already added while configuring the
Xpediter/CICS Script Facility or installing Xpediter/Code Coverage.
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:
After adding the entry, reassemble and relink your PLTSD module.
3. Define the File Utility Audit Trail GDG.
18-3
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 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 shown in Figure 18-1 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.
member.
b. 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:____________________
Note: Your site’s external security manager must grant authority to create the
GDG dataset with the chosen base name.
18-4
Figure 18-1. Sample JCL to Define File Utility Audit Trail GDG (DEFLOGDG)
//* =====>
INSERT JOBCARD HERE
<=====
//*********************************************************************
//*
*
//* DEFLOGDG THIS MEMBER CREATES A MODEL DSCB AND BUILDS A
*
//*
GENERATION DATA GROUP INDEX FOR THE DATASETS USED
*
//*
BY THE XPEDITER/CICS FILE UTILITY AUDIT TRAIL.
*
//*
*
//* REFER TO THE MANUAL "ACCESS METHOD SERVICES (AMS) FOR THE ICF"
*
//* FOR A DETAILED DESCRIPTION OF PARAMETERS ASSOCIATED WITH THE
*
//* "DEFINE GENERATIONDATAGROUP" STATEMENT.
*
//*
*
//* DEFAULTS USED:
*
//*
*
//*
NAME(..)
SUPPLY THE BASE GDG DATASET NAME YOU REQUIRE.
*
//*
ALSO SPECIFY THIS NAME FOR THE XPEDITER/CICS
*
//*
GLOBAL PARAMETER "XDLOGNM".
*
//*
*
//*
LIMIT(20) ALLOW MAXIMUM OF 20 DATASETS IN THE GROUP.
*
//*
MODIFY PER YOUR SITE STANDARDS. COMPUWARE
*
//*
RECOMMENDS YOU SET THIS VALUE NO LOWER THAN 10.
*
//*
*
//*
NOEMPTY
ONLY UNCATALOG THE OLDEST DATASET IN THE GROUP WHEN *
//*
THE MAXIMUM IS REACHED.
*
//*
*
//*
NOSCRATCH DO NOT REMOVE THE DSCB FOR A DATASET WHEN IT IS
*
//*
UNCATALOGED WHEN THE MAXIMUM IS REACHED.
*
//*
*
//*
*
//*
*
//*********************************************************************
//DEFLOGDG EXEC PGM=IDCAMS
//SYSIN
DD *
DEFINE GENERATIONDATAGROUP -
(NAME(XD.LOG.DATASET.GDGNAME) /* MUST MODIFY */
NOEMPTY -
NOSCRATCH -
LIMIT(20))
/*
c. 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.
d. Submit the JCL to create a model DSCB and build the GDG index for your
dataset.
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.
a. 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 Chapter 4, “Global Parameters Table” for more
information.
18-5
XDLOGDD=DYNAMIC
Dynamically allocate dataset
XDLOGNM=base GDG name from step 3, substep b on page 18-3
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
Go to step 5.
1. Select a 1- to 8-character ddname for your File Utility Audit Trail dataset and
write it below:
ddname:____________________
XDLOGDD= ddname written above
Log dataset not dynamically alloc.
// ddname written above DD DISP=(NEW,CATLG,CATLG),
// DSN= base GDG name from step 3, substep b on page
18-3 (+1),SPACE=(CYL,(10,5)),
// DCB=(DSORG=PS,RECFM=FBA,LRECL=133,BLKSIZE=27930)
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 Chapter 4, “Global Parameters Table” for
more information.
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
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 override dataset:
XDLOG=NO
Log File Utility changes
For more information, see “Adding Parameter Overrides to the Dataset” on page 5-8.
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.
18-6
Figure 18-2. 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 18-3 will be
displayed, allowing you to activate the File Utility Audit Trail.
Figure 18-3. XLOG Screen with Xpediter/CICS Active, File Utility Audit Trail Not Active



Time: 17:07:53.8 Date: 12 MAR 2003
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 18-4. XLOG Screen after File Utility Audit Trail Not Activated


Time: 17:07:53.8 Date: 12 MAR 2003
Applid: ACMEC123
Auditing remains inactive.
If you enter Y (Yes), Xpediter will start the File Utility Audit Trail, and the screen shown
in Figure 18-5 will be displayed.
Figure 18-5. XLOG Screen after File Utility Audit Trail Activated




Time: 17:24:04.2 Date: 12 MAR 2003
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 186 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.
18-7
Figure 18-6. XLOG Screen when File Utility Audit Trail is Active




Time: 16:52:12.8 Date: 12 MAR 2003
Applid: ACMEC123
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 18-7 will be displayed.
Figure 18-7. XLOG Screen when File Utility Audit Trail is Terminated



Time: 16:59:41.7 Date: 12 MAR 2003
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 18-8 shows the screen displayed to verify that the
dataset has been switched.
Figure 18-8. XLOG Screen when Dataset is Switched





Time: 17:39:26.3 Date: 12 MAR 2003
Applid: ACMEC123
Auditing has been switched.
Previously Writing to Dataset MYUSRID.ACME.GDG.G0935V00.
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
18-9 will be displayed.
Figure 18-9. XLOG Screen when Neither is Entered



Time: 16:52:12.8 Date: 12 MAR 2003
Applid: ACMEC123
Auditing remains active.
18-8
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 18-10 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.
Figure 18-10. 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.2995
25 on 12 MAR 2003.
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 18-11 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 18-11. Formatting of Standard Entry Header Line
File Utility request from user MYUSRID
at netname TACA011
(terminal A011) in region ACME
Table 18-1 lists the starting column, length, and contents of each section of the standard
header line.
Table 18-1. 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 ”
18-9
Table 18-1. Standard Entry Header Line Sections
Column Length Description
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 18-12 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.
Figure 18-12. 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.
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 18-13. Formatting of Dataset Service Request Changes
File Utility request from user MYUSRID at netname TACA011
C123 at 17:58:13.039422 on 12 MAR 2003.
Service requests have been changed.
File Name: DBUGPRF Dataset Name: MYUSRID.DBUG.PROFILE
Method: VSAM
Type: KSDS
Before OPE ENA REA UPD ADD BRO DEL
After
CLO UNE REA UPD ADD BRO DEL
Changes *** * *
C123 at 17:58:16.375651 on 12 MAR 2003.
Service requests have been changed.
File Name: DBUGPRF Dataset Name: MYUSRID.DBUG.PROFILE
Method: VSAM
Type: KSDS
Before CLO UNE REA UPD ADD BRO DEL
After
OPE ENA REA UPD ADD BRO DEL
Changes *** * *
Access
Access
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.
18-10
Add
Figure 18-14 shows the formatting performed when a dataset record is added. The File
Utility Audit Trail copies the contents of the added record.
Figure 18-14. Formatting of Dataset Record Add
C123 at 18:00:52.304322 on 12 MAR 2003.
The following record has been added.
File Name: DBUGEMP Dataset Name: MYUSRID.EMPL.MASTER
Type: KSDS
Contents of key. Key length: 5
----+
99999
FFFFF
Access Method: VSAM
Update — Full
The formatting of the Entry for a dataset record update with the XDLOGUP global
parameter set to FULL is shown in Figure 18-15. Before and after images are provided,
and changes are flagged with asterisks (*) on the line below the after image.
Figure 18-15. Formatting of Dataset Record Update — Full
C123 at 18:01:01.765627 on 12 MAR 2003.
The following record has been modified.
Method: VSAM
Type: KSDS
----+
99999
FFFFF
99999
Before image record Length: 80
After image record Length: 80
Number of bytes modified: 8
Access
Update — Short
The formatting of a short Entry for a dataset record update is shown in Figure 18-16.
Instead of writing the entire record, the before and after images only include those parts
of the record that have been changed.
18-11
Figure 18-16. Formatting of Dataset Record Update — Short
C123 at 14:26:04.261296 on 12 MAR 2003.
The following record has been modified.
Method: VSAM
Type: KSDS
----+
00040
FFFFF
00040
Before image record Length: 80
After image record Length: 80
Number of bytes modified: 21
Access
Delete
Figure 18-17 shows the formatting performed when a dataset record is deleted. The File
Utility Audit Trail copies the contents of the deleted record.
Figure 18-17. Formatting of Dataset Record Delete
C123 at 18:01:06.893980 on 12 MAR 2003.
The following record has been deleted.
Method: VSAM
Type: KSDS
----+
99999
FFFFF
Access
DL/I Segment Replace
Figure 18-18 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 Xpeditersupplied 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.
18-12
Figure 18-18. Formatting of DL/I Segment Replace
File Utility request from user MYUSRID at netname TACA011 (terminal A011) in region ACME
C123 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.
----------------------------------------------------------------------------------------------------------------------------
C123 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
DB2 Row Update
Figure 18-19 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.
Figure 18-19. Formatting of DB2 Row Update
C123 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.
ill be displayed.
-
User does not have exclusive lock.
-
-
-
Only columns selected for query w
19-1
Chapter 19.
Batch Interface to Xpediter/CICS NEWCOPY
Chap 19
This chapter describes the Batch Interface to Xpediter/CICS NEWCOPY.
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 Release 8.3 (or above) transaction and program definitions must
be installed in each CICS region referenced, and the Xpediter/CICS Release 8.3 (or above)
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 (Figure 19-2 on page 19-3). Customize the
dataset name in the TPCONFIG DD statement. This dataset was created in “Step 5.
Creating and Managing the Xpediter TP Configuration File (TPCONFIG)” on page 2-26.
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.
Note: 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 by both Xpediter/Eclipse and
Xpediter/CICS. Xpediter/Eclipse usage is documented in the Compuware Workbench
Installation Guide. Xpediter/CICS uses this dataset for two purposes:
• To identify Xpediter Service Providers that are to share CICSPlex information. For
more information, see Chapter 7, “Xpediter Service Provider”.
• To identify all of the CICS regions that should be contacted by the Batch Interface to
Xpediter/CICS NEWCOPY.
19-2
Efficiency Considerations
Technically, each member of the TPCONFIG partitioned dataset may contain entries for
all three 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.
Record Identifiers for Batch Interface to Xpediter/CICS NEWCOPY
Records
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.
Notes:
• Service Provider records are discussed in Chapter 7, “Xpediter Service Provider”.
• Record identifiers for Xpediter/Eclipse are documented in the Compuware Workbench
Installation Guide.
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)
• the IP Port Number for the CICS region (or keyword EXCI if the EXCI
communication method is to be used)
• 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 19-1 to your TPCONFIG dataset.
Batch Interface to Xpediter/CICS NEWCOPY
19-3
Figure 19-1. 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 (Figure 19-2) 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
“Step 26. Install and Customize the Remote Operations Command Interface (Optional)”
on page 2-46. 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.
Figure 19-2. Batch Interface to Xpediter/CICS NEWCOPY Sample Member JCLNEWC
//NEWCOPY
//
//
//STEPLIB
//
//
//*NEWCINP
//TPCONFIG
//SYSPRINT
//*
EXEC PGM=XPEDNEWC,
PARM='&LMOD,MEMBER=&CFGMBR',
COND=(0,LT)
DD
DISP=SHR,DSN=CPWR.CMXDnnn.SMXDPDSE
DD
DISP=SHR,DSN=TCPIP.SEZALOAD
DD
DISP=SHR,DSN=YOUR.CICS.SDFHEXCI
DD
DISP=SHR,DSN=Your.multiple.lmod.statements
DD
DISP=SHR,DSN=CPWR.COMMON.TPCONFIG
DD
SYSOUT=*
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 19-3.
19-4
Figure 19-3. 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
------------------------------------------------------------------------------------
XDP0062I HTTP TCPIPS CONNECTION WITH TRAN XPNC TO PORT 52054 CW01.ACME.COM
------------------------------------------------------------------------------------
XDP0062I HTTP TCPIPS CONNECTION WITH TRAN XPNC TO PORT 27448 CW01.ACME.COM
XDP0063I Program 'CBUMOVE4' phasein successful Len(00046E0)
XDP0063I From(ACMJET0.XD.LOAD)
20-1
Chapter 20.
User-Defined DSECTs
Chap 20
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.
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.
Creating 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 sitespecific DSECT images. DSECTDFH contains sample assembly JCL for DFHAFCB as shown
in Figure 20-1 and Figure 20-2. DSECTUSR provides sample assembly JCL for a sitespecific DSECT.
Note: 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 20-1 shows an example of how to define the system labels required for userdefined 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
20-2
Figure 20-1. 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
RESULTING
OFFSET
CONTENT LENGTH
VALUE
----------- ---------------
21C
Y
00000000
008B2938
D0
Y
00000000
008B2A90
14
Y
00000000
008B2790
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
_________
_
________
Figure 20-2 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 20-2. 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.
*
A-1
Appendix A.
SMP/E Installation Using the EP Interface
Note:
Appendix A.
App A
Compuware recommends using the Receive From Network (RFN) installation
procedures in this appendix are intended for those sites that use the EP interface
to perform a full SMP/E installation, and the alternate procedures in Appendix
B, “Installing Xpediter/CICS Using ISPF” are intended for those sites that first
use the EP interface, but only to upload product files to the mainframe.
This appendix explains how to SMP/E install Xpediter/CICS using the EP interface. The
following topics are covered:
• Primary and Optional Installation Paths
• Installation of Compuware’s Enterprise Common Components
• Uploading the Xpediter/CICS installation files and performing SMP/E installation.
Primary and Optional Installation Paths
Figure A-1 shows the primary and optional paths that you can use to install and/or apply
maintenance to the product(s), and where to find the necessary instructions.
Figure A-1. Installation Using the Product Setup Window or Using Optional ISPF Dialog
A-2
• A copy of the most current version of the Enterprise Common Components Installation and
Customization Guide is included on the ECC media. If you do not have your copy and
are a registered user of the Compuware Go (FrontLine) support web site at
Common Components.
Note:
Xpediter/CICS requires Compuware Shared Services Release 8.8 or above.
IMPORTANT:
program LMSINIT.
Upload Product Files and Perform SMP/E Installation
Compuware provides a convenient way to upload product files and perform an SMP/E
installation, all from a straightforward PC workstation interface. When you insert the
product media for mainframe Extended Play (EP) products (or double-click the Setup.exe
file from an electronic distribution), the product Setup dialog box appears. You can use
this interface to upload product installation and/or maintenance files to the mainframe
and perform a full SMP/E installation.
Notes:
1. Some product media do not support SMP/E installation. Such media can be easily
identified by the absence of the SMP/E Install tab on the Setup dialog box’s
Mainframe Products tab. If your product media does not contain the SMP/E Install
A-3
tab, skip these instructions and go to the appropriate appendix in the product’s
Installation Guide that contains upload and installation instructions for non-SMP/E
media.
2. If you prefer using a mainframe TSO session to complete the SMP/E installation or
application of maintenance, go to the appropriate appendix in the Installation Guide
for the product you are installing and continue with the instructions there.
3. You may optionally upload the files only, including all SMP/E installation JCL, and
then use a mainframe session to perform the SMP/E installation.
The interface also includes a tab for contacting Compuware Customer Support and may
include tabs for Windows ® products and third-party products. For more information, see
“Install Windows and Third-Party Products” on page A-12.
System Requirements and Preparation
Before using the upload/installation interface, make sure your system meets the
following requirements:
• Internet Explorer 6.0 or above
• Adobe Reader 6.0 or above to view PDF documents
• If your PC’s display DPI setting makes the interface difficult to view, temporarily set
it to Normal size (96 DPI).
Firewall Settings
Either configure software firewalls running on your PC to grant the upload application
(cwftpw.exe located in folder \cpwr of the media) network access to your mainframe, or
disable firewalls during the upload.
Information on the Media Label
If you are installing from physical media, the media label provides information about
installation or operating capability, as noted below:
Name/Release
Name and release of the product.
Creation
The product’s installation media label shows when it was made. Compare this
creation date with any maintenance posted on the Compuware Go customer support
Website at http://go.compuware.com.
If additional maintenance has become available since the date on the installation
media, either download the maintenance, or call Customer Support to request new
installation media with the current maintenance.
Select Items for Upload
IMPORTANT: Sample Xpediter Setup dialog boxes are shown in this section, but the
steps are applicable to other Compuware mainframe products.
In addition to installation, maintenance, and documentation files, the product media (or
electronic distribution) contains an HTML-based upload/installation application used to
FTP-transfer the necessary files to your mainframe.
1. Insert the media into the drive or double-click Setup.exe. A product Setup dialog box
similar to that shown in Figure A-2 appears. The Mainframe Upload tab of the
Mainframe Products tab is shown first. Fields marked with an asterisk (*) are
required.
A-4
Figure A-2. Mainframe Upload Dialog, Upper Portion
Note:
Do not click the Upload Product Files button until all required fields have been
filled in.
2. Following your site’s standards, enter a value in the High Level Qualifier for
Common Files field. Common files are datasets that can be used across multiple
products on the EP and may include maintenance files, MCS files, and sample
libraries. The default high level qualifier is SYS1.CPWR.COMMON. If you do not
have ALTER access to this hlq, you must change it to a qualifier you can create files
under.
3. Select the files to be uploaded as follows:
– If you want to upload files for all of the products listed, use the All row as
follows:
1. Click either the Product and Maintenance check box or the Maintenance
only check box.
2. Enter an appropriate qualifier in the Unload High Level Qualifier field. Be
sure you are allowed to create files under this qualifier.
Note:
The ISPF SMP/E JCL generation dialogs are currently designed to
handle only a Common Unload High Level Qualifier. If you plan to
use the mainframe ISPF dialog to generate SMP/E JCL for more than
one product, you must use the same upload hlq for all of them. This
restriction does not apply if you are planning to use the Setup dialog
box’s SMP/E Install tab to generate installation JCL.
– If you want to upload a selected combination of product and/or maintenance
files, use the individual product rows as follows:
Note:
Some products may require a component that is common to multiple
products. For example, if you select Abend-AID and/or Abend-AID for
CICS, you should also select Abend-AID Base Services.
A-5
1. Click either the Product and Maintenance check box or the Maintenance
only check box for each product you want to install or apply maintenance
to.
2. Optionally, click the Japanese Support check box if you plan on installing
localized or Japanese language support.
3. Optionally, enter an appropriate qualifier in the product Unload High Level
Qualifier field. If the product is not selected for upload, this field will be
ignored. If this field is cleared, it will be reset to the default value.
4. Scroll down to view the lower portion of the dialog box as shown in Figure A-3.
5. Edit the sample information in the Job Card field as required.
Note:
The job class specified must allow enough CPU time for long-running jobs.
Running the SMP/E APPLY and ACCEPT steps will result in the generation of a
large amount of output. Be sure to set your job card Class and Lines parameters
accordingly.
Figure A-3. Mainframe Upload Dialog, Lower Portion
Enter File Transfer Settings
1. In the Mainframe FTP Information area, specify the values to be used during FTP
transfer of the product installation and maintenance files as follows:
–
–
–
–
In the Host field, enter your host mainframe’s IP or DNS name.
In the User Id field, enter the TSO user ID to use for the FTP session.
In the Password field, enter the password associated with the TSO user ID above.
In the Port field, enter the number of the host port used for FTP uploads and
downloads. The default is 21.
– In the Dasd Unit field, enter the esoteric unit to delete temporary upload files.
The default is SYSDA.
2. (Optional) Specify the storage options to be used on the mainframe as follows:
A-6
– In the Volume field, enter the name of the volume on which to place the
uploaded files. Be sure the target volume has enough space to hold all the files
uploaded.
Note: Click the File Size button to display an estimate of the minimum number
of tracks required to upload the selected products. The estimate assumes
3390 DASD and will be less accurate for different DASD. Compuware
recommends adding 5% to the estimated minimum tracks value.
– If using SMS, enter the appropriate class to apply to the uploaded files in the SMS
Storage Class field.
Upload Files
When the desired installation and/or maintenance files have been selected and all
required fields have been filled in, click Upload Product Files to upload the selected files
in TSO XMIT format, along with the JCL to perform a TSO RECEIVE of the files.
The upload/installation application uploads the required files to your mainframe. The
name of the file containing the JCL to TSO RECEIVE the files is shown at the bottom of
the screen.
Note:
The Compuware EP Setup upload confirmation dialog may include one or more
messages indicating the upload status of Common file set n. The upload of
Common file set 0 normally includes UNLOAD, UPLDEL, and SMPE.DATA files.
Other files may also be uploaded, depending on the design of the EP.
Enter SMP/E Settings
Notes:
• If you prefer using a mainframe TSO session to complete the SMP/E installation or
application of maintenance, go to the appropriate appendix in the Installation Guide
and continue with the instructions there.
• At the end of the SMP/E install process below, if you click Upload SMP/E JCL to the
Mainframe and SUBMIT, the TSO RECEIVE discussed above is executed
automatically as part of the SMP/E install.
The products’ Setup dialog box enables SMP/E installation of the selected product and/or
maintenance files directly from your PC.
1. Click the SMP/E Install tab. The dialog shown in Figure A-4 appears, listing the
product installation and/or maintenance files you uploaded previously.
A-7
Figure A-4. SMP/E Install Dialog, Upper Portion
Note: Do not click either of the Upload SMP/E JCL to the Mainframe buttons until all
required fields, including those under SMP/E Options, have been filled in. Be
sure to use names or hlq that you have UPDATE or ALTER access for as necessary.
2. Specify the basic values to be used during the SMP/E process as follows:
– In the Compuware GLOBAL CSI Dataset field, enter the name of the CSI dataset
used for Compuware products. The default is SYS1.CPWR.GLOBAL.CSI.
– Click the appropriate button under Does the Global CSI already exist?
depending on whether the CSI exists and, if so, whether it has been set up for
Compuware use.
– In the HLQ for Compuware SMP/E Datasets field, enter the high-level qualifier
to be used for the SMP/E datasets on the mainframe. The default is
SYS1.CPWR.GLOBAL.
– In the Compuware Products High-level qualifier field, enter the high-level
qualifier associated with the products to be installed. The default is SYS1.CPWR.
Note:
The value entered in this field becomes the default for the High Level
Qualifier fields on the Zone Info part of the screen in the next step. Any
HLQ you enter there will override the default value for installing that
specific product.
– In the DASD Unit field, enter the appropriate symbolic unit. The default is
SYSDA.
– (Optional) In the DASD Volser field, enter the appropriate storage volume serial
information. Be sure the target volume has enough space to hold all your files.
– In the SMP/E Work Unit field, enter the name of the appropriate SMP/E work
symbolic unit. The default is SYSDA.
A-8
3. Click the plus (+) sign next to SMP/E Options to expand that area of the screen as
shown in Figure A-5.
Figure A-5. SMP/E Install Dialog, SMP/E Options Area
4. Click the plus sign next to Zone Info. The SMP/E target and distribution zone fields
shown in the upper part of Figure A-6 appear. For each item listed, edit the values in
the Target Zone Name, Distribution Zone Name, and each of the High Level
Qualifier fields, as necessary. The High Level Qualifier fields default to the value in
the Compuware Products High-level qualifier field, but you can enter override
values on a product-by-product basis.
A-9
Figure A-6. SMP/E Install Dialog, Zone Info and System Utilities Portion
5. Click the plus sign next to System Utilities. The utilities fields shown in the lower
part of Figure A-6 appear. Standard defaults are pre-filled. For each item listed, enter
the applicable value as required.
6. Click the plus sign next to SMS parameters. The parameters fields shown in the
upper part of Figure A-7 appear. Enter the data class, storage class, or management
class SMS parameters for SMP/E datasets if they are required at your site.
A-10
Figure A-7. SMP/E Install Dialog, SMS Parameters and Dataset Definitions Portion
7. Click the plus sign next to Cross-Product and/or Non-Compuware Dataset
Definitions. Dataset Name fields similar to those shown in the middle part of Figure
A-7 appear. Enter the appropriate DSN for each dataset listed. If you are installing
individual products or maintenance only, you may not need to enter values for all
DSNs.
Note: DevEnterprise requires a DSN for the Host Communications loadlib (SLHCLOAD),
and if that field is left blank, a message may appear. If you are installing
DevEnterprise, click Cancel, enter a DSN for SLHCLOAD, and retry the upload.
Otherwise click OK to dismiss the message and continue with the installation.
8. If necessary, edit the sample information in the Job Card field as required.
9. Make any necessary revisions to the Mainframe FTP Information fields.
Upload and Submit Installation Jobs
When the desired items on the SMP/E Install tab have been selected and all required
fields have been filled in, do one of the following:
• Recommended: To upload the JCL and submit it immediately to initiate the SMP/E
process, click Upload SMP/E JCL to the Mainframe and SUBMIT.
• Optional: To upload the JCL to be submitted manually later, click Upload SMP/E
JCL to the Mainframe. You will need to use a mainframe TSO session to complete
the SMP/E installation or application of maintenance. Go to the Installation Guide
appendix entitled “Installing Xpediter/CICS Using ISPF” and continue with the
instructions there.
The upload/installation application uploads the required files to your mainframe and, if
SUBMIT was clicked, initiates the SMP/E installation procedure.
A-11
Continue the installation and product configuration process below. For the most current
installation instructions and Release Notes, visit the Compuware Go customer support
Website at go.compuware.com.
SMP/E JCL Uploaded to the Mainframe
When SMP/E installation generation is done from the PC using the upload/installation
application rather than using the ISPF Installation JCL Customization Facility, dataset
<hlq>.<prodid>.SMPE.JCL is uploaded to the mainframe. This dataset contains the JCL
used to perform an SMP/E installation, along with jobs that process maintenance files
(uploaded from media or downloaded from Compuware Go).
*$01GLCSI
1. Allocate the SMPLOG and SMPPTS datasets.
2. Define a VSAM cluster for use as a separate global CSI for installing
Compuware products, then load the SMP/E initialization record
(GIMZPOOL) into it.
3. Initialize the global CSI with appropriate Zonedef, option, and DDDEF
entries.
* Depending on the selection made in the upload/installation application, this
member may not exist, or items 1 and 2 may be bypassed.
$02TZCSI
1. Delete Relfiles.
2. Delete and define the target and distribution zone clusters and support
files.
3. Update the global CSI with component specific Zonedef, option, and
DDDEF entries.
4. Initialize the product target and distribution zone CSIs with DLIBZONE,
TARGETZONE, option, and DDDEF entries.
$03ALDSN
1. Delete any existing SMP/E libraries and datasets.
2. Allocate the SMP/E libraries and datasets.
$04RECV
Receive the base code and maintenance PTFs
$05APPLY
Apply base code and maintenance PTFs into target SMP/E libraries.
$06ACCPT
Accept base code into the SMP/E distribution libraries.
Note: Use job $16MACPT to accept maintenance PTFs.
$07SUBMT
This jobstream is the JCL that is submitted when Upload SMP/E JCL to the
Mainframe and Submit is clicked. It is a concatenation of the above
members (minus extra jobcards) into a single member.
$10MNTJB
This jobstream is the JCL that is submitted when Upload SMP/E JCL to the
Mainframe and Submit is clicked and Maintenance Only is selected. It is
a concatenation of members $14MRECV and $15MAPLY (minus extra
jobcards) into a single member.
$14MRECV
This jobstream receives the maintenance file(s) for installed components.
Update JCL statements SMPPTFIN and SMPHOLD to point to the files
uploaded from the media, electronic distribution, or Compuware Go (or
downloaded from FTP).
$15MAPLY
This jobstream will apply the maintenance PTFs to the SMP/E files
$16MACPT
This jobstream will accept the maintenance PTFs to the SMP/E files
A-12
Upload/Installation FAQs
What should I do if I receive a message stating that I am not an Administrator and
cannot perform product installation?
For Windows releases prior to Windows 7, this message can be ignored. You do not need
Administrator rights because nothing is being installed on your PC from the media. The
upload/installation application simply facilitates the upload of files to the mainframe
and, optionally, their installation there.
Windows 7 users with User Account Control (UAC) settings higher than Never notify
must have administrator privileges on their PC—or have access to an ID and password
with administrator privileges—to run the upload/installation application.
What should I do if I receive a message stating “Install Program As Other User”?
Select Run the program as your-domain\your-domain-id and click OK to continue.
Nothing is installed on your PC. The upload/installation application simply facilitates
the upload of files to the mainframe and, optionally, their installation there.
What should I do if I receive a message stating “Error: You must have a supporting
browser”?
Install Internet Explorer 6.0 or above and set it as your default browser. Contact your
System Administrator for more information.
What should I do if I receive a message stating “Cannot connect to host xxxxx:nn”?
The host name or remote port you specified on the Mainframe Upload dialog is incorrect.
Contact your System Administrator for the host ID of the mainframe. The host name is
the domain name or IP address of the mainframe. It may be the LPAR system ID or it may
be some other name.
What should I do if the upload is slow, doesn’t complete, or I receive a number of
transfer-retry messages?
Windows firewall and third-party firewalls can cause numerous retries and time-outs. All
firewalls should either be configured to allow the upload application access to the
mainframe or they should be disabled during the upload process.
What should I do if I am using Windows 7, and a Program Compatibility Assistant
dialog box appears after I close the product Setup dialog box?
You can simply click Cancel to dismiss the dialog box. To prevent it from reappearing the
next time you close the product Setup interface, click This program installed correctly
instead. Note that the dialog box may reappear when using subsequent product
distributions.
What should I do if I can’t view some or all of the documentation?
Adobe Reader 6.0 or above is required to view and use the PDF/PDX files. You may be able
to view the PDF files with an older version. However, you will not be able to use a PDF
index file (.pdx), which significantly speeds searches and allows you to search the entire
set of documents at once. Download a free copy of the reader from www.adobe.com.
Install Windows and Third-Party Products
The same Extended Play (EP) Setup dialog box that allows you to upload and install
mainframe products (see “Upload Product Files and Perform SMP/E Installation” on page
A-2) also includes a Contact Us tab for contacting Compuware Customer Support and
may include tabs for Windows ® products and third-party products.
A-13
Installing Windows Products
When you insert the product media for mainframe EP products (or double-click the
Setup.exe file from an electronic distribution), the products’ Setup dialog box appears.
Click the Windows® Products tab. A dialog box similar to the one shown in Figure A-8
appears. Use the links and follow the on-screen prompts to install the desired software.
Figure A-8. Windows® Products Tab
Installing Third-Party Products
Click the 3rd Party Products tab. A dialog box similar to the one shown in Figure A-9
appears. Use the links and follow the on-screen prompts to install the desired software.
Figure A-9. 3rd Party Products Tab
A-14
B-1
Appendix B.
Installing Xpediter/CICS Using ISPF
Note:
Appendix A.
App B
Compuware recommends using the Receive From Network (RFN) installation
installation, and the alternate procedures in this appendix are intended for those
sites that first use the EP interface, but only to upload product files to the
mainframe.
The following steps provide a checklist for installing Xpediter/CICS. Please note that this
procedure also references the installation of Enterprise Common Components (ECC),
which is provided on separate product media in SMP/E installation format.
Pre-installation Considerations
Review “Preinstallation Considerations” on page 1-1 before proceeding with the
remainder of this appendix.
Part 1: Verify File Transfer and Perform TSO RECEIVE
Part 2: Install Enterprise Common Components
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Select Installation Components.
Specify Installation Environment Information
Specify SMS Parameters
Specify Global CSI Dataset Name
Specify Jobcard Information
Specify SMP/E High-Level Qualifiers
Specify Target and Distribution Zones
Specify Installation-Dependent Libraries
Verify Installation Information
Process the JCL.
1.
2.
3.
4.
5.
6.
7.
8.
Allocate Compuware Global CSI and SMP/E Datasets.
Allocate Libraries and SMP/E Datasets.
Initialize the Target and Distribution Zone CSIs
Receive the Base Code, Maintenance, and HOLDDATA.
Review HOLDDATA
Apply the Base Code and Cumulative Maintenance to the Target Libraries
Accept the Base Code to the Distribution Libraries
Continue with Xpediter/CICS Configuration.
Note:
If your site will be using Xpediter/Code Coverage, ensure all Xpediter/Code
Coverage SMP/E installation jobs have completed before configuring
Xpediter/CICS.
B-2
For configuration instructions, see “Part 4: Configure Xpediter/CICS” on page 2-17.
Before continuing with the installation steps, be sure to read “Preinstallation
Considerations” on page 1-1, and the Enterprise Common Components Installation and
Customization Guide to determine the considerations that are specific to your needs.
Note:
Any references to CICS TS pertain to IBM’s CICS Transaction Server.
Part 1: Verify File Transfer and Perform TSO RECEIVE
1. Verify that the files were successfully transferred to the mainframe.
2. Submit the job provided in the hlq.prodid.UNLOAD dataset to TSO RECEIVE the
installation files. The specific dataset name was listed in the lower portion of the
Mainframe Upload dialog as shown in Figure A-3 on page A-5.
Part 2: Install Enterprise Common Components
A copy of the most current version of the Enterprise Common Components Installation and
Customization Guide is included on the ECC media. If you do not have your copy and are a
registered user of the Compuware Go (FrontLine) support web site at
Common Components.
Note:
Xpediter/CICS requires Compuware Shared Services Release 8.8 or above.
IMPORTANT:
program LMSINIT.
B-3
IMPORTANT:
If you took the first optional path to this Appendix after uploading product files in
“Upload Files” on page -4, continue with the instructions in this Part and Part 4.
However, if you continued to the second optional path by uploading your
installation JCL (without submitting it) in “Upload and Submit Installation Jobs” on
page -8, skip this Part and go directly to “Part 4: Install Xpediter/CICS with SMP/E”
on page B-15.
Overview
This part explains the steps required to customize the JCL for installation of
Xpediter/CICS, including:
•
•
•
•
•
•
CICS
CICS
CICS
CICS
CICS
CICS
Note:
TS
TS
TS
TS
TS
TS
3.1
3.2
4.1
4.2
5.1
5.2
modules
modules
modules
modules
modules
modules.
To prevent possible conflicts, Compuware strongly recommends that all
The Xpediter installation process utilizes System Modification Program Extended
(SMP/E). For more information about this type of installation, and other installation
considerations, refer to Chapter 1, “Installation Overview”. For more information
about SMP/E, consult the IBM SMP/E Reference or the IBM SMP/E User’s Guide.
Step 1. Select Installation Components
The SMP/E Installation JCL Customization Facility uses screens to gather your
installation information. It then uses that information to build the jobs needed to
perform the SMP/E installation.
Note: Slight variations in the following procedure may exist depending on the format in
which you received the product.
Begin the process of installing products using the SMP/E Installation JCL Customization
Facility as follows:
1. Invoke the installation facility for the Compuware Xpediter EP by entering the TSO
EXECUTE command with the dataset name of the installation library followed by
$$XBEINS. For example:
TSO EX 'hlq.CPWR.BE131111.INS($$XBEINS)'
where hlq is the high-level qualifier you entered when transferring files to the
mainframe and BE is the product identifier (prodid). The exact dataset name can be
found in the UNLOAD job used to TSO RECEIVE installation files.
The SMP/E Installation JCL Customization Facility screen (Figure B-1) is displayed.
B-4
Figure B-1. Installing Enterprise Common Components
Compuware Xpediter EP - EPID BE131111













Command ==>
If Compuware Enterprise Common Components (ECC) has been installed, press END
(PF3) to continue with the Xpediter EP installation dialog.
If Compuware Enterprise Common Components (ECC) has not been installed, specify
the dataset name of your ECC Installation Library below and press ENTER.
ECC Installation Library:
Press PF1 for help,
END to exit.
2. Do one of the following:
– If Enterprise Common Components (ECC) is already installed, press PF3 to
continue with the Xpediter EP installation dialog. The SMP/E Installation JCL
Customization Facility screen (Figure B-2) is displayed.
– If ECC is not already installed, specify the dataset name of your ECC installation
library and press Enter. The ECC installation begins. Follow the instructions in the
Enterprise Common Components Installation and Customization Guide. After the ECC
installation is complete, the SMP/E Installation JCL Customization Facility screen
(Figure B-2) is displayed.
Figure B-2. Selecting Components to Install



Command ==>
Place an "S" by one or more of the following components to select for install
JCL customization and press ENTER.
FMID
Status
_
_
_
_
_
_
_
_
_
_
CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
5.2
5.1
4.2
4.1
3.2
3.1
Modules
Modules
Modules
Modules
Modules
Modules
RMXD930
QMXD930
PMXD930
OMXD930
NMXD930
MMXD930
Xpediter/TSO and Xpediter/IMS 09.03.00
Xpediter/Xchange 05.00.00
Xpediter/Code Coverage 03.01.00
DevEnterprise 05.03.00
Press PF1 for help,
MLXT930
MLXG500
MLXV310
MLXW530
END to exit.
3. Type an S to the left of each component you want to install.
B-5
Note: If you are installing Xpediter/CICS with support for more than one release of
CICS, which may include releases your site is planning to install in the future,
Compuware recommends installing them simultaneously.
4. Press Enter.
To indicate your choices, the word SELECTED will be displayed in the Status column
next to each component chosen as shown in Figure B-3.
Figure B-3. Confirming Installation Selections



Command ==>
Press ENTER to begin JCL customization for the selected component.
Select all desired components before continuing.
FMID
Status
_
S
_
_
_
_
S
S
S
S
CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
5.2
5.1
4.2
4.1
3.2
3.1
Modules
Modules
Modules
Modules
Modules
Modules
RMXD930
QMXD930
PMXD930
OMXD930
NMXD930
MMXD930
Press PF1 for help,
MLXT930
MLXG500
MLXV310
MLXW530
SELECTED
SELECTED
SELECTED
SELECTED
SELECTED
END to exit.
5. To modify a selection, add or delete the S to the left of the component.
6. When you are satisfied with your selections, press Enter again to start the JCL
customization process. The screen shown in Figure B-4 is displayed.
Step 2. Specify Installation Environment Information
Depending on your installation choices, you may not see all of the screens documented
herein.
B-6
Figure B-4. Installation Environment Screen



Command ==>
Customizing:
Xpediter/TSO and Xpediter/IMS
Xpediter/Xchange
Xpediter/Code Coverage
DevEnterprise
Please complete the following:
- Do you want to enter SMS parameters?
- DASD unit:
- DASD volser (optional):
- SMP/E work unit:
- Global SMP/E dataset high-level qualifier:
- Install dataset high-level qualifier (HLQ)
NO
SYSDA
SYSDA
CPWR
<hlq>
Note: The Global SMP/E dataset high-level qualifier
is used when building the .CSI, .SMPLOG, and
.SMPPTS dataset names.
This screen prompts you to enter information about the installation environment. Notice
that the names of the components selected for installation are listed below the
Command prompt. Those names will remain there during the rest of this procedure.
1. Specify installation information as follows:
Do you want to enter SMS parameters?
If you specify YES in the SMS Parameters field, you will be prompted to enter SMS
(Storage Management Subsystem) parameters on the next screen. Depending on
your site’s SMS installation options, default SMS parameters may be supplied
when datasets are being allocated during execution of the job. If so, or if you do
not want to specify SMS parameters, enter NO. Otherwise, enter YES to supply or
override the SMS parameters. The default value is NO.
DASD unit
Enter a valid DASD unit name. The value of this field will be used in the UNIT=
parameter of the DD statements that allocate non-VSAM libraries and datasets.
The default value is SYSDA.
DASD volser
This field is optional. If a volume is specified, SMP/E will use it as the target for
library and dataset allocation.
SMP/E work unit
Enter the name of a DASD unit to use for allocating SMP/E work files. The default
value is VIO.
Global SMP/E dataset high-level qualifier
Enter a value to be used for generating the names of the SMP/E system datasets.
These datasets include SMPLOG, SMPPTS, SMPTLIB, and the Global Consolidated
Software Inventory (CSI).
The supplied default is CPWR.GLOBAL. Using this default will result in a Global
Zone dataset name of CPWR.GLOBAL.CSI.
Notes:
• Due to limits on the length of the DSPREFIX parameter (used to build the
SMPTLIB names for SMP/E RELFILES), this field cannot be longer than 26
characters.
B-7
• To prevent possible conflicts, Compuware strongly recommends that all
• If you prefer to have different Global SMP/E dataset high-level qualifier for
each Compuware product, you must install each product separately.
Install dataset high-level qualifier (HLQ)
Enter the value for HLQ that you used when unloading the installation datasets.
Step 3. Specify SMS Parameters
If, in the previous step, you specified NO in the SMS Parameters field, you can skip
this step.
The screen shown in Figure B-5 was displayed when you pressed Enter in the previous
step.
Figure B-5. Specifying SMS Parameters





Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
Enter any or all of the following SMS parameters:
Data class:
Storage class:
Management class:
1. Specify the data class, storage class, and/or management class parameters for the SMS
operating environment as follows:
Data Class
Specify the eight-character data class name for SMS.
Storage Class
Specify the eight-character storage class name for SMS.
Management Class
Specify the eight-character management class name for SMS.
Note: Installation defaults are not displayed on this screen. They will be applied
during execution of the SMP/E jobstream generated by this procedure. If your
site does not supply defaults or you wish to override the supplied defaults,
enter the desired SMS parameters on this screen.
B-8
Step 4. Specify Global CSI Dataset Name
step.
Figure B-6. Specifying Global CSI Dataset Name






Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
The following dataset name will be used for the global CSI:
CPWR.GLOBAL.CSI
If you do not want to use this CSI name, type in a new CSI name
...or...
Erase the field and press ENTER to set it to the default.
The dataset currently does not exist.
Note: The DSN for a new global CSI cannot exceed 38 characters. If the global CSI is predefined outside of the Customization Facility, it can consist of up to 44 characters.
1. Verify that the global CSI dataset name is correct. Change the name or specify a new
name if necessary.
2. Press Enter.
Step 5. Specify Jobcard Information
step. It prompts you for job card information.
B-9
Figure B-7. Entering Job Card Information




Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
Enter job card information:
//$$$$$$$$ JOB ('DEFAULT'),'XPEDITER XSRELEASE',
//
CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//*
//*
OPTIONAL JES PARAMETER CARD GOES HERE
//*
NOTE: The class selected MUST allow enough CPU time for long-running jobs.
APPLY and ACCEPT jobs can easily exceed 5 CPU minutes each.
1. Specify the job card information for the SMP/E Installation JCL Customization
Facility by updating the supplied model job card to follow your site standards. You
may enter up to five lines of job information.
The installation facility will set the $$$$$$$$ value equal to the member name of
each job created. You also have the option of specifying the job name using the
format xxxxxxx$ or xxxxxxxx, where the x’s are whatever name you choose. If you set
it to xxxxxxx$, the installation facility will set the job name for each job to xxxxxxx
and append a number to it. A letter will be appended for jobs 10 and above. If you set
it to xxxxxxxx, the installation facility will use the specified name for all jobs created.
Note: The job class specified must allow enough CPU time for long-running jobs.
Step 6. Specify SMP/E High-Level Qualifiers
The screen shown in Figure B-8 on page B-10 was displayed when you pressed Enter in
the previous step. It prompts you for the SMP/E high-level qualifiers of the components
previously selected for installation. The area listing the high-level qualifiers is scrollable,
as indicated by More: +.
B-10
Figure B-8. Specifying SMP/E High-Level Qualifiers
Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
Enter the following information:
More:




+
SMP/E dataset high-level qualifier: CPWR.QMXD930
SMP/E dataset high-level qualifier: CPWR.MLXT930
Xpediter/Xchange
SMP/E dataset high-level qualifier: CPWR.MLXG500
Note: If a high-level qualifier is longer than 28 characters, the installation facility is not
able to generate a default dataset name for the target and distribution zones. You
can either change the high-level qualifier entered, or manually modify the zone
dataset names to valid lengths.
1. Specify the high-level qualifiers as applicable for your installation as follows:
Component-Specific Modules SMP/E Dataset High-level Qualifier
Enter a value to be used in generating names of component-specific datasets,
including target and distribution zone CSIs, and their respective non-SMP/E
target and distribution libraries. The value entered cannot exceed 28 characters.
2. Press Enter.
Step 7. Specify Target and Distribution Zones
The screen shown in Figure B-9 on page B-11 is an example of what was displayed when
you pressed Enter in the previous step. This screen will appear once for each product you
have chosen to install.
B-11
Figure B-9. Specifying Target and Distribution Zones






Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
Enter the following information for: Xpediter/CICS - CICS TS 5.1 Modules
Distribution zone name:
QXD930D
DZone CSI dataset name:
CPWR.QMXD930.DZONE.CSI
DZone CSI currently does not exist
Target zone name:
QXD930T
TZone CSI dataset name:
CPWR.QMXD930.TZONE.CSI
TZone CSI currently does not exist
1. Specify the target and distribution zone information as follows:
Distribution Zone Name
Specifies the name of the SMP/E distribution zone used by the product to be
installed. The name you specify must be unique within the global zone.
DZone CSI Dataset Name
Specifies the dataset name of the SMP/E distribution zone used by the product to
be installed.
Distribution CSI currently exists/does not exist
Indicates whether the distribution zone CSI dataset exists.
Target Zone Name
Specifies the name of the SMP/E target zone used by the product to be installed.
The name you specify must be unique within the global zone.
Target Zone CSI Dataset Name
Specifies the dataset name of the SMP/E target zone used by the product to be
installed.
Target CSI Currently exists/does not exist
Indicates whether the target zone CSI dataset exists.
2. Press Enter. If you are installing more than one product, the screen shown in Figure
B-9 on page B-11 is displayed once for each product you are installing.
Step 8. Specify Installation-Dependent Libraries
If you are installing Xpediter/CICS or DevEnterprise, one or two additional screens
appear to allow you to specify installation-dependent libraries.
If you are installing Xpediter/CICS, the screen shown in Figure B-10 was displayed when
you pressed Enter in the previous step.
B-12
Figure B-10. Specifying Xpediter/CICS Libraries






Command ==>
Customizing: Xpediter/CICS 09.03.00
Enter the following SMP/E library names from your environment:
LE link-edit library: CEE.SCEELKED
TCP/IP RENT library: TCPIP.SEZARNT1
TCP/IP misc. library: TCPIP.SEZACMTX
TCPIP.SEZATCP
USS library:
SYS1.CSSLIB
The standard defaults are: CEE.SCEELKED
TCPIP.SEZARNT1
TCPIP.SEZACMTX
TCPIP.SEZATCP
SYS1.CSSLIB
TCP/IP RENT Library
Specifies the TCP/IP re-entrant library.
TCP/IP Misc. Library
Specifies the TCP/IP standard library.
USS Library
Specifies the Unix System Services library.
2. Press Enter. If you are installing DevEnterprise, the screen shown in Figure B-11 is
displayed. Otherwise, skip the rest of this step.
Figure B-11. Specify DevEnterprise Libraries
Compuware Xpediter EP - EPID BE131111
Default HCI library




Command ==>
Customizing: DevEnterprise 05.03.00
Enter the following library names from your environment:
LE link-edit library:
CEE.SCEELKED
Compuware ECC HCI load library: HC.PROD.R020500.SLHCLOAD
The standard defaults are:








CEE.SCEELKED
CPWR.SLHCLOAD
B-13
Compuware ECC HCI Load Library
Specifies the ECC HCI loadlib installed at your site.
New install dataset
Specify the name of the DevEnterprise installation library you created when
transferring files to the mainframe.
Old install (optional)
If you are upgrading from release 4.2.1 or higher of Xpediter/DevEnterprise and
have not changed the version/release/maintenance level naming convention,
much of the site-specific information can be merged from your previous settings.
To use the values you used in the previous release, specify the DevEnterprise
install library created in the previous installation of the product.
4. Press Enter.
Step 9. Verify Installation Information
When you pressed Enter in the previous step, the first of a series of confirmation screens
was displayed. On each confirmation screen you have the following choices.
• To accept the information on the screen, press Enter.
• To correct a particular parameter, press END to return to the associated entry screen.
After you accept the information on each of the confirmation screens, the installation
process will continue.
Step 10. Process the JCL
The screen shown in Figure B-12 was displayed when you pressed Enter the final time in
the previous step.
Figure B-12. Confirming JCL Processing









SMP/E Installation JCL Customization Facility - Verification Screen
Command ==>
Customizing:
Xpediter/Xchange
DevEnterprise
THIS IS THE LAST PANEL BEFORE CUSTOMIZATION BEGINS.
ENSURE THAT ALL VARIABLES ARE CORRECT BEFORE PRESSING ENTER.
Press ENTER to begin customizing the JCL.
B-14
1. Press Enter to start the processing that builds customized JCL members or press End
to cancel the installation.
When you press Enter, the progress of the JCL customization process is displayed in a
scrollable area on the screen. You can scroll up or down to view the list of jobs and
the members generated.
2. After the installation JCL has been created, press End. A screen is displayed informing
you that a parameter report has been generated (Figure B-13). This report details the
JCL created and lists the parameters and execution information used during
installation.
Figure B-13. Report Member Detailing JCL Processing




The following PDS member contains a report of all parameters used during
customization and a log of all JCL members created:
<hlq>.CPWR.BE131111.INS($$XBERPT)
Press ENTER to browse the report, END to exit.
3. If you want to browse the report at this time, press Enter. You can also examine the
report later by accessing the installation library report member shown on this screen.
4. Press End. The screen first displayed in Figure B-3 on page B-5 will be redisplayed,
showing a status of COMPLETE for each component (Figure B-14 on page B-14).
Figure B-14. Displaying Completion Status

Command ==>
JCL customization is complete for selected components.
See status column.
FMID



Status
_
S
_
_
_
_
S
S
S
S
CICS
CICS
CICS
CICS
CICS
CICS
TS
TS
TS
TS
TS
TS
5.2
5.1
4.2
4.1
3.2
3.1
Modules
Modules
Modules
Modules
Modules
Modules
RMXD930
QMXD930
PMXD930
OMXD930
NMXD930
MMXD930
Press PF1 for help,
MLXT930
MLXG500
MLXV310
MLXW530
COMPLETE
COMPLETE
COMPLETE
COMPLETE
COMPLETE
END to exit.
5. Press End. The screen shown in Figure B-15 will be displayed instructing you to refer
to the product installation guides to complete the installation process.
B-15
Figure B-15. Final JCL Customization Screen



Note: To complete the installation of the selected component(s), return to the
appropriate Xpediter installation guide(s).
Press END to exit.
6. The processing of the SMP/E Installation JCL Customization Facility is now finished.
Press End to exit.
Note: Compuware recommends you maintain availability to your customized install
library. Otherwise, it may be necessary to unload and recustomize the install
library from product or maintenance media to perform future maintenance.
Note: The six sample jobs for using SMP/E to install Xpediter/CICS are located in one of
the following libraries, depending upon how you transferred the files to your
site’s mainframe:
• hlq.CPWR.BExxxxxx.SMPE.JCL: If you used the product media to SMP/Einstall the product files, as described in “Part 1: Initialize Installation
Environment” on page 2-2.
• hlq.CPWR.BExxxxxx.INS: If you SMP/E-installed the product files using the
SMP/E Installation JCL Customization Facility, as described above.
Installation JCL members are described in the following table.
Table B-1.
Installation JCL Members
Member
Function
$01GLCSI
Depending on the values specified on the workstation, allocates, initializes, and/or
updates the Compuware Global CSI and Global SMP/E datasets.
$02TZCSI
Performs the allocation of the zones and related SMP/E datasets.
$03ALDSN
Initializes the CSIs with the required entries.
$04RECV
Receives the base code, maintenance, and HOLDDATA.
$05APPLY
Applies the base code and maintenance.
$06ACCPT
Accepts the base code.
Note:
Except where otherwise noted, the return code from all jobs should be zero.
Step 1. Allocate Compuware Global CSI and SMP/E Datasets
This step allocates and/or initializes the Compuware Global CSI for use with SMP/E. It
may also allocate the SMPLOG and SMPPTS datasets. For more information on these
datasets, refer to Table 1-4 on page 1-13.
The installation facility has created the job $01GLCSI. This job allocates and/or
initializes the SMP/E Global Zone datasets described in “Step 4. Specify Global CSI
Dataset Name” on page 2-8.
1. Review the job $01GLCSI for any necessary changes.
B-16
2. Submit the job to start the allocation/initialization process.
Step 2. Allocate Libraries and SMP/E Datasets
This step allocates target and distribution zone CSIs as well as product-specific SMP/E
datasets. These datasets include the CICS release specific load libraries as well as the APF
authorized load library.
The installation facility has created a job called $02TZCSI that allocates the required
libraries and datasets based on which components were chosen for installation at your
site.
Note:
The space allocations used are based on 3390 DASD. If you use 3380 DASD, you
may decide to change the BLKSIZE for the load library and APF authorized load
library to 6356 for a better blocking factor.
1. Review the job $02TZCSI for any necessary changes.
2. Submit the job to start the allocation process.
Step 3. Initialize the Target and Distribution Zone CSIs
This step initializes the Xpediter/CICS target and distribution zone CSIs. The installation
facility has created a job called $03ALDSN that performs the initialization.
1. Review the job $03ALDSN for any necessary changes.
Note:
Before you submit this job, make sure the job submitted in the previous step
has completed.
2. Submit the job to start the initialization process. This job uses REP statements rather
than ADD statements to simplify rerunning the job. It may safely return an RC=4
warning code if the following message is issued:
GIM27701W aaaaaaaa ENTRY bbbbbbbbbbbbbbbbb DOES NOT EXIST. THE REPLACE
OPERATION HAS BEEN CHANGED TO AN ADD.
Otherwise, the return code should be 0.
Step 4. Receive the Base Code, Maintenance, and HOLDDATA
This step receives the Xpediter/CICS base code and maintenance from the SMP/E files
into the SMPPTS and SMPTLIBs. The installation facility has created a job called
$04RECV that performs these processes. In addition, the job requests an SMP/E LIST
HOLDDATA.
CAUTION:
Be sure to run $04RECV in a job class suitable for long-running batch jobs.
1. Review the job $04RECV for any necessary changes.
2. Submit the job to start the receive process. The JCL generated by the installation
facility includes a step that will RECEIVE maintenance PTFs and LIST HOLDDATA. If
the PTF and/or HOLDDATA files are empty, a return code of 4 can be expected.
At times, installing maintenance media requires additional actions that must be
performed after a PTF(s) is applied. In these cases, the PTF is identified as an exception
with:
B-17
++HOLD
completely implement the change.
CAUTION:
the maintenance media does not have any hold actions.
Note: All of the jobs in “Step 4. Receive the Base Code, Maintenance, and HOLDDATA”
on page B-16 issue a command to display any HOLDDATA on the maintenance
media.
Step 6. Apply the Base Code and Cumulative Maintenance to the Target
Libraries
This step applies the Xpediter/CICS base code and maintenance to the target zone. This
includes the CICS release specific load libraries as well as the APF authorized load library
and the sample library.
The installation facility has created a job called $05APPLY that applies the base code and
maintenance to the target zone.
CAUTION:
Be sure to run $05APPLY in a job class suitable for long-running batch jobs.
Note:
The default control statements apply the base FMID and all cumulative
maintenance, however you may wish to run an APPLY CHECK before applying
the software.
1. Review the job $05APPLY for any necessary changes.
2. Submit the job to start the apply process.
Note:
While an APPLY CHECK may end with RC=0, a successful APPLY will end with
RC=4 or less. The APPLY CHECK, unlike the actual APPLY, only checks the SMP/E
environment and does not invoke any external utilities, such as IEBCOPY or the
linkage editor.
Step 7. Accept the Base Code to the Distribution Libraries
This step accepts the Xpediter/CICS base code into the distribution libraries. This
includes the CICS release-specific load libraries as well as the APF authorized load library
and the sample library.
The installation facility has created a job called $06ACCPT that accepts the base code
into the distribution libraries.
CAUTION:
Be sure to run $06ACCPT in a job class suitable for long-running batch jobs.
Note:
The default control statements accept the base FMID, however you may wish to
run an ACCEPT CHECK before accepting the software.
1. Review the job $06ACCPT for any necessary changes.
2. Submit the job to start the accept process.
B-18
Note: While an ACCEPT CHECK may end with RC=0, a successful ACCEPT will end with
RC=4 or less. The ACCEPT CHECK, unlike the actual ACCEPT, only checks the
SMP/E environment and does not invoke any external utilities, such as IEBCOPY
or the linkage editor.
Step 8. Continue with Xpediter/CICS Configuration
After the installation has been completed, you must continue with the procedures in
“Part 4: Configure Xpediter/CICS” on page 2-17.
C-1
Appendix C.
Apply Maintenance with SMP/E
Appendix A.
App C
IMPORTANT:
Compuware recommends that you check for any critical HIPER PTFs before
proceeding. PTFs are available at http://go.compuware.com or by contacting
Xpediter/CICS Customer Support at 1-800-538-7822. For telephone numbers in other
geographies, see the list of worldwide offices at http://www.compuware.com. Refer
to “Customer Support” on page xxviii.
Overview
This chapter describes the procedure for applying Xpediter/CICS maintenance. If you
have just installed Xpediter according to the instructions in Chapter 2, “RFN
Installation Procedures”, Appendix A, “SMP/E Installation Using the EP Interface”,
or Appendix B, “Installing Xpediter/CICS Using ISPF”, the maintenance has already
been applied. You may skip to Chapter 3, “Installation Verification Procedures”.
Your Xpediter installation media includes all maintenance for the included components
available as of the day it was created. You may request separate, cumulative maintenance
media from Compuware Customer Support that contains the latest preventive service.
Maintenance is installed using SMP/E.
A return code of 4 or less is acceptable for any maintenance step in this chapter.
Step 1. Locate the Xpediter SMP/E Installation Sample
Library
Note:
The three sample jobs for using SMP/E to install preventive maintenance are
located in one of the following libraries, depending upon how you transferred
the files to your site’s mainframe:
• hlq.CPWR.BExxxxxx.SMPE.JCL: If you used the product media to SMP/Einstall the product files, as described in “Part 1: Initialize Installation
Environment” on page 2-2.
• hlq.CPWR.BExxxxxx.INS: If you SMP/E-installed the product files using the
SMP/E Installation JCL Customization Facility, as described in Appendix B,
“Installing Xpediter/CICS Using ISPF”.
After you locate the SMP/E installation sample library, execute the maintenance jobs
listed in Table C-1 or Table C-2. The first column in Table C-1 lists members generated
from the workstation. The second column lists members generated by the ISPF
Installation JCL Customization Facility.
If you performed the installation from the workstation, the members in Table C-2 and
the second column of Table C-1 will not exist. If you want to use those members, follow
the instructions in Appendix B, “Installing Xpediter/CICS Using ISPF”, Part 3, “Step 1.
Select Installation Components” through “Step 10. Process the JCL” to re-customize the
C-2
JCL needed for the maintenance process.
Table C-1.
Maintenance JCL Members for All Installed Components
Member
Member
$14MRECV
$GBM1RCV Receives the maintenance and HOLDDATA.
$15MAPLY
$GBM2APL
$16MACPT
$GBM3ACC Accepts the maintenance to the distribution libraries.
N/A
$GBM4PTF
Table C-2.
Maintenance JCL Members for Xpediter/CICS Only
Member
Function
$xxM1RCV
Receives PTFs for the CICS release.
$xxM2APL
Applies PTFs for the CICS release.
$xxM3ACC
Accepts PTFs for the CICS release.
$xxM4PTF
Lists all PTFs applied to applicable target and distribution zones.
This optional job is for reporting purposes only.
Function
Applies the maintenance to the target libraries.
Prints the PTFs applied and accepted.
The xx that appears in the job names is replaced with a two-letter code during
installation. The two-letter code used depends on which component(s) you are installing:
•
•
•
•
•
•
MX (CICS TS 3.1 support)
NX (CICS TS 3.2 support)
OX (CICS TS 4.1 support)
PX (CICS TS 4.2 support)
QX (CICS TS 5.1 support)
RX (CICS TS 5.2 support).
The following steps are recommended for the maintenance cycle:
1. Accept any PTFs from a previous maintenance run that have not been accepted yet.
2. Receive and apply the new maintenance PTFs.
3. Test the new PTFs for any problems that may arise due to site dependencies, then
move them into production and accept the new PTFs. You could also wait until the
next maintenance run before doing the accept.
Step 2. Receive Maintenance and HOLDDATA
Use the following applicable JCL member to receive any maintenance from the
maintenance install media:
•
•
•
•
•
•
•
$14MRECV (all components) or $GBM1RCV (all components)
$MXM1RCV (CICS TS 3.1 support)
$NXM1RCV (CICS TS 3.2 support)
$OXM1RCV (CICS TS 4.1 support)
$PXM1RCV (CICS TS 4.2 support)
$QXM1RCV (CICS TS 5.1 support)
$RXM1RCV (CICS TS 5.2 support).
Review this JCL and change the SMPPTFIN and SMPHOLD dataset names to the names of
the datasets to be received.
After you review and modify the JCL, submit the applicable job(s) to start the receive
process.
Apply Maintenance with SMP/E
C-3
At times, installing maintenance requires additional actions that must be performed after
a PTF(s) is applied. In these cases, the PTF is identified as an exception with:
++HOLD
completely implement the change.
CAUTION:
the maintenance installation media does not have any hold actions.
Note:
All of the jobs in “Step 2. Receive Maintenance and HOLDDATA” on page C-2
issue a command to display any HOLDDATA on the maintenance media.
Step 4. Apply Maintenance
Use the following applicable JCL member(s) to apply any maintenance to the target
libraries:
•
•
•
•
•
•
•
$15MAPLY (all components) or $GBM2APL (all components)
$MXM2APL (CICS TS 3.1 support)
$NXM2APL (CICS TS 3.2 support)
$OXM2APL (CICS TS 4.1 support)
$PXM2APL (CICS TS 4.2 support)
$QXM2APL (CICS TS 5.1 support)
$RXM2APL (CICS TS 5.2 support).
After you review and modify the JCL, submit the applicable job(s) to start the apply
process.
Notes:
1. Run the jobs in a job class suitable for long-running batch jobs.
2. You may be required to have SMP/E restore a USERMOD prior to applying a PTF to a
module. SMP/E messages inform you when this action is necessary. After the PTF is
applied, you must then reapply the USERMOD.
3. It is advisable to run an APPLY CHECK before applying any maintenance.
Step 5. Accept Xpediter/CICS Maintenance
CAUTION:
Compuware strongly recommends that you do not accept any PTFs until they have
been thoroughly tested at your site.
After a function or maintenance (PTFs or APARs) has gone through the ACCEPT step, that
becomes your current release’s base level. At any time prior to the ACCEPT step, you may
issue a RESTORE command to reset your target libraries to the way they were as of the last
ACCEPT command. The RESTORE command removes maintenance, or even entire
functions, while the ACCEPT command effectively sets a new base level of the release to
which further maintenance will be applied. For more information about using the
RESTORE command, refer to your site’s IBM SMP/E documentation.
C-4
Use the following applicable JCL member to have SMP/E accept any maintenance to the
distribution libraries:
•
•
•
•
•
•
•
$16MACPT (all components) or $GBM3ACC (all components)
$MXM3ACC (CICS TS 3.1 support)
$NXM3ACC (CICS TS 3.2 support)
$OXM3ACC (CICS TS 4.1 support)
$PXM3ACC (CICS TS 4.2 support)
$QXM3ACC (CICS TS 5.1 support)
$RXM3ACC (CICS TS 5.2 support).
The following parameter must be added to the ACCEPT command to bypass any
HOLDDATA:
BYPASS(HOLDSYSTEM,HOLDUSER)
After you review and modify the JCL, submit the applicable job(s) to start the accept
process.
Notes:
1. Run the job in a class suitable for long-running batch jobs.
2. It is advisable to run an ACCEPT CHECK before accepting the PTFs.
3. Do not perform an ACCEPT on any USERMODs.
Using the HELP PTFS Command
Use the HELP PTFS command to list the SMP/E PTFs installed on your Xpediter/CICS and
Compuware Shared Services products. Xpediter/CICS Customer Support could request
this information if you report a problem using Xpediter. You can invoke the HELP PTFS
command from any Xpediter/CICS screen. The display lists PTFs that were present when
Xpediter was initialized in the CICS region; you may need to restart Xpediter to load
recently applied PTFs.
Figure C-1. HELP PTFS Command
------------------------ XPEDITER/CICS - HELP FACILITY --------------------C123
COMMAND ===>
SCROLL ===> CSR
COMPILED: 23 DEC 2012 - 14.26.47
Help Module: DBUHPTFS
Commands: END (Prev screen) CANCEL (Exit help) UP DOWN
Line
1 of
22

---------------------General Information
-----------------------

Customer Name .......... ACME CORPORATION
Customer Number ........ 000001
CICS TS Release......... 4.1.0 ( CICS 6.6 )
Xpediter Load library .. XD.R090300.OMXD930.SMXDO66L
CSS Load Library ....... CPWR.LCX870.SLCXLOAD

--------------- PTFs Applied to Xpediter/CICS 09.03.00 ---------------

1
2
3
4
5
6
7
8
9
10
11

--------- PTFs Applied to Compuware Shared Services 08.07.00 ---------

1
2
3
4
5
6
7
8
9
10
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
I-1
Index
Special Characters
(DBUGUD), 2-34
(E)RDSA debugging, 7-1
A
accept base code
to distribution libraries, B-17
accept base code to distribution libraries, 2-16
Acrobat PDF online documentation, xxv
AICA abend, 13-6
AIEXIT SIT parameter, 8-2
allocating
global CSI and SMP/E datasets, B-15
libraries and SMP/E datasets, B-16
allocating libraries and SMP/E datasets, 2-15
AOR, 10-2, 10-5
APF authorization, 1-9
apply
base code to target libraries, B-17
apply base code to target libraries, 2-16
ASPE abend, 8-2
ASRA, 1-9
ASRB, 1-9
Assembler Language Processor
specifying jobcard information, B-8
authorized load library. See SMXDAUTH
autoinstall, 2-20
automatic session termination, 2-30, 8-1–8-3
enabling, 8-1
for static transaction routing users, 8-3
B
base code
accept to distribution libraries, 2-16, B-17
apply to target libraries, 2-16, B-17
receiving, B-16
Batch Interface to NEWCOPY, 19-1
C
CANCEL START requests, 1-7
preinstallation considerations, 1-7
CATD transaction, 8-2
CEDA transaction, 8-3
CICS resource definitions, 2-18
updating for all CICS releases, 2-18
CICS upgrade, reinstallation after, 1-7
CICSPlex, 10-2
Code Coverage, 1-3
cold restart, 8-4
Compuware GLOBAL CSI Dataset field, A-7
Compuware Go customer support website, xxiv, xxviii
Compuware Shared Services, 2-2, A-2, B-2
installation, 2-2, A-2, B-2
minimum release requirement, 2-2, A-2, B-2
Compuware Shared Services (CSS), 1-1
Assembler language processor, 20-1
control blocks, 1-7
Automatic Initiator Descriptor (AID), 1-7
control blocks, DBUGUSEC, 11-2
COPY command, 9-2
COPYP command, 9-2
CPU consumption, with Xpediter/Code Coverage, 1-8
CSI for Compuware products, A-7
CSMT message, 13-6
Customer Support, xxviii
customer support website, xxiv
D
DB2 file utility, 2-35
implementing support for, 2-35
DB2 format utility, 9-1–9-7
DBCFORSQ, 9-1
DBCTL support
installing, 2-39
DBPA entries, 15-1
DBPA parameters examples
1.6 examples, 15-3
9.5 examples, 15-4
9.7, 9.8, and 9.9 examples, 15-5
typical DBPA sequence, 15-2
DBPA transaction, 15-2
DBPA transaction input dataset, 2-31
DBPA transaction input, specifying, 14-1
DBSQLUTL format utility, 9-7
dataset requirements, 9-7
DBSQLUTL utility, 9-1
commands, 9-2
COPY, 9-2
COPYP, 9-2
DELETE, 9-3
DIRECTORY, 9-3
FORMAT, 9-3
FORMATP, 9-3
INITIALIZE, 9-6
PRINT, 9-6
REORG, 9-6
DBUGEND, 8-1–8-2
DBUGEND0, 8-1–8-2
DBUGEND1, 8-2–8-3
DBUGGBL, 4-5
DBUGGBL global parameters, 4-1
customizing global parameters table, 4-1
DBUGGBLP, 4-12
DBUGGBLP global parameters, 4-1
DBUGPPM2 program
installation procedure, 2-19
DBUGSIT, 4-2
DBUGSSX, 1-4, 2-24
DBUGSSXX, 1-4, 2-24
I-2
debugging, security exit, 11-5
defining user DSECTs, 20-1
See user DSECT files
DELETE command, 9-3
DFHRPL, 1-2, 1-4, 2-28, 2-45, 11-7
DFHZATDX, 8-2
DFLTUSER SIT parameter, 8-2
Diagnosis Mode, 6-1
Diagnosis/Utilities Mode, 6-2
DIRECTORY command, 9-3
disabling storage monitoring, 13-2
DISCARD LIBRARY command, 1-2
DISCONN global table parameter, 8-1–8-2
distribution zones, 2-10
SMP/E, 1-10
documentation packaging utility, 2-19, 2-29, 2-34–
2-35, 4-26
dynamic LIBRARY, 1-2, 2-28
dynamic transaction routing, 10-2, 10-4
E
edit macro, 2-17
employee file (DBCDEFEM), 2-33
Enterprise Common Components (ECC), 1-1
entry/exit codes, file security exit, 11-2
ERDSA debugging. See (E)RDSA under Special Characters
error handling and recovery, DBUGUSEC, 11-4
exit points, DBUGUSEC, 11-2
Extended Play (EP) products, A-2, A-12
external security manager, 2-23–2-24, 2-39, 2-41–2-42,
2-48, 4-5, 4-23, 6-1, 8-2, 11-1, 12-1, 17-2–17-4, 18-2–
18-3
F
disabling, 18-5
overview, 18-1
setting up, 18-2
XLOG transaction, 18-5
FMIDs, 1-12
FORMAT command, 9-3
FORMATP command, 9-3
FORMATP sample report, 9-4
FTP transfer of installation files, A-5
functions available in restricted modes, 6-3
G
global CSI, A-7
global CSI dataset name, specifying, 2-8, B-8
global parameter changes, 4-1
by changing and assembling DBUGGBL, 4-3
by override facility, 4-1
global parameter overrides, 5-1
global parameters table, 4-1–4-41
global table parameters override dataset, 2-31
global zone
SMP/E, 1-10
H
high-level qualifiers
SMP/E, B-9
high-level qualifiers, SMP/E, 2-9
HLQ
for Compuware products, A-7
for distribution zone datasets, A-8
for target zone datasets, A-8
for the SMP/E datasets, A-7
HOLDDATA
reviewing, C-3
HOLDDATA, reviewing, 2-15
I
INITIALIZE command, 9-6
initializing
target and distribution zone CSIs, B-16
initializing target and distribution zone CSIs, 2-15
INITPARM, 4-2
input register work area (INRWORK), 13-9
installation
checklist, 2-1
DASD unit name, 2-6, B-6
DASD volser, 2-6, B-6
global SMP/E dataset high-level qualifier, 2-6, B-6
JCL Customization Facility, 2-4, B-3
job card information, 2-9, B-9
procedure, 2-1
selecting components, 2-4, B-3
SMP/E work unit, 2-6, B-6
SMS data class, 2-7, B-7
SMS management class, 2-7, B-7
specify global CSI dataset name, 2-8, B-8
specify SMS parameters, 2-7, B-7
specifying environment information, 2-5, B-5
storage class, 2-7, B-7
installation JCL, 2-17
installation overview, 1-1–1-15
installation paths, recommended and optional, A-1
installation procedure, 2-1–2-46
installation checklist, 2-1
installation verification procedures, 3-1–3-40
testing your Assembler procedures, 3-11
testing your C procedures, 3-31
testing your COBOL procedures, 3-1
testing your PL/I procedures, 3-21
Installation Verification Process (IVP), 2-29
installing third-party products, A-13
installing Windows products, A-12
Intelligent Autokeeps, 3-5, 3-15, 3-24, 4-21
intellikeep, 3-5, 3-15, 3-24, 4-21
intended audience, xxiv
intercommunication considerations, 10-1–10-2
Internet, Compuware WWW address, xxv
introduction, xxiii
Customer Support, xxviii
notation rules, xxvi
ISPF edit macro, 2-17
IVP. See Installation Verification Process (IVP)
I-3
J
O
JCL
processing, B-13
updating startup, 2-28
JCL Customization Facility
overview of, 1-11
using, B-3
JCL Customization Facility, using, 2-4
JCL processing, 2-12
job card
specifying information, B-8
job card, specifying information, 2-8
override dataset, 2-31
overriding global parameters, 5-1–5-8
L
label, installation media, A-3
Language Environment, 2-42, 16-1
setting run-time options, 16-1
LANGUAGE parameter, 9-3
LE/370. See Language Environment
libraries
created during SMP/E installation, 1-13
LIBRARY resources, 1-2, 2-28
M
macro
DBUGGBLM, 4-12
parameter transaction codes, 4-3
mainframe FTP information, A-5
maintenance
accepting, C-3
applying, C-3
receiving, C-2
minimizing CPU consumption, with Xpediter/Code
Coverage, 1-8
modes of operation, 6-1
available functions, 6-3
Diagnosis Mode, 6-1
Utilities Mode, 6-2
monitor exceptions keywords, DBPA, 15-4
MRO. See intercommunication considerations
MVS APF authorized library, 2-17
for breakpoints in protected (E)RDSA, 2-17–2-18
for CICSPlex dynamic transaction routing, 2-17–
2-18
for DBCTL support, 2-17
MVS program properties table, 2-18
N
NEWCOPY, Batch Interface, 19-1
notation rules, xxvi
P
PDF documentation, xxv
PLT shutdown, 2-19, 17-2, 18-2
PLT startup
activating storage protection, 15-1
PLT startup entries, 1-9
preinstallation considerations, 1-1
after CICS upgrade, 1-7
cancelling AID blocks, 1-7
current Abend-AID for CICS users, 1-7
current Xpediter/CICS users, 1-3
Primary Menu (XPED/XPRT), 3-1, 3-21, 3-31
PRINT command, 9-6
product media, 1-10
contents of, 1-10
SMP/E layout, 1-12
product termination, 8-4
profile file (DBCDEFPF), 2-31
allocate, 2-31
conversion, 2-31
program autoinstall, 2-20
PROTAID, 13-6, 13-9
PROTINR, 13-6, 13-9
PSW, for transaction dump, 13-6
Q
quick session termination, 8-4
R
RDO, 8-3
receiving, C-2
base code, maintenance, and HOLDDATA, B-16
maintenance, C-2
recreate dataset, 2-34
related publications, xxiv
remote operations setup, 2-46
REORG command, 9-6
restricted operating modes, 4-4, 6-1–6-3
available functions, 6-3
Diagnosis Mode, 6-1
Utilities Mode, 6-2
S
sample library. See SMXDSAMP
Script Facility, 17-1–17-7
disabling, 17-7
overview, 17-1
setting up, 17-2
I-4
security exit
installing, 2-39
security exits, 11-1, 12-1
file update, 11-1–11-7
control blocks, 11-2
debugging, 11-5
entry/exit codes, 11-2
error handling and recovery, 11-4
exit points, 11-2
implementation, 11-1
register conventions, 11-3
memory update, 12-1–12-3
changing data on password-protected screens,
12-3
implementation, 12-1
testing, 12-3
sequential terminal input, storage protection, 15-1
Service Provider. See Xpediter Service Provider
session and product termination, 8-1–8-4
automatic session termination, 8-1
Setup window, A-2, A-12
Shared Services. See Compuware Shared Services
SIT parameters, 4-2
SMP/E
allocating global datasets, B-15
allocating libraries and datasets, 2-15, B-16
allocating zones, 1-10
high-level qualifiers, B-9
installation and maintenance, 1-10
installation steps, 1-11
JCL Customization Facility, description of, 1-11
layout, 1-12
libraries created during installation, 1-13
overview of, 1-10
SMP/E high-level qualifiers, 2-9
SMP/E installation
firewall settings, A-3
from a PC, A-2
system requirements and preparation, A-3
SMS
data class, 2-7, B-7
management class, 2-7, B-7
parameters, 2-6, B-6
SMXDAUTH, 1-3–1-4, 1-7, 1-13–1-14, 2-18, 2-27, 2-42,
7-6–7-7
SMXDSAMP, 1-3, 2-17, 4-1, 5-4, 7-4, 10-3, 11-1, 12-1,
14-4
softcopy documentation, xxv
specifying jobcard information, 2-8
SQL transfer file, 2-38
allocation JCL (DBCDEFSQ), 2-38
use, 9-1
startup
of Xpediter/CICS, 15-1
PLT input, 15-1
static transaction routing, 8-3
storage class, 2-7, B-7
storage protection, 13-1–13-9
detailed error codes, 13-9
examples, 13-2
system-wide monitoring, 13-2
transaction dump, 13-7
using system labels, 13-4
monitoring considerations, 13-5
monitoring for storage violations, 13-2
PLT input, 15-1
sequential terminal input, 15-1
system labels for creating storage protection exceptions, 13-4
transaction dump output, 13-6
using, 13-1
storage protection and system labels keywords, DBPA,
15-5
storage protection table, 13-5
storage violation, 13-1
subsystem initialization, 2-26
subsystem security, 2-24
Subsystem Security Exit, 1-4, 2-24
suppressing system dumps, 1-9
syntax
conventions, xxvi
diagrams, xxvi
syntax notation rules, xxvi
system dumps, suppressing, 1-9
system labels, storage protection exception, 13-4
System messages. See Xpediter/CICS Reference Manual
T
target zones, 2-10
SMP/E, 1-10
terminal autoinstall, 8-2
test programs
assemble/compile and link-edit, 2-43
testing your Assembler procedures, 3-11
testing your C procedures, 3-31
testing your COBOL procedures, 3-1
testing your PL/I procedures, 3-21
third-party installation files, A-13
TOR, 10-2, 10-5
transaction dump output, Xpediter/CICS, 13-6
detailed error codes, 13-9
transaction dump example, 13-7
transaction routing, 8-1–8-2
U
uploading installation files, A-2
uploading maintenance files, A-2
user DSECT files
creating, 20-1
Utilities Mode, 6-2
UXSNOFF global table parameter, 8-2
V
verification process, 2-29
Xpediter/CICS installation, 2-29
verify installation information, 2-12, B-13
verifying Xpediter/CICS execution, 2-46
W
WebSphere MQ, 4-23
Windows installation files, A-12
World Wide Web, Compuware address, xxv
I-5
X
XDDBPCL, 14-2, 14-7
XDDBPINP, 2-29, 14-1–14-2, 14-6
XDDBPRPT, 14-1–14-2, 14-6
XDGBLCL, 4-32, 5-2, 5-6–5-7
XDGBLINP, 2-29, 4-32, 5-1–5-2, 5-6
XDGBLRPT, 4-32, 5-1–5-2, 5-7
XDSSPROC, 7-3
XLOG transaction, 18-5
Xpediter Primary Menu (XPED/XPRT), 3-1, 3-21, 3-31
Xpediter Service Provider, 7-1
Automatic Restart Management support, 7-3
executing as a batch job, 7-6
executing as a started task, 7-4
execution parameters, 7-2
initialization sequence, 7-1
MVS operator commands, 7-8
DUMP command, 7-9
INITTCP command, 7-10
SHOWTCP command, 7-10
SHUTDOWN command, 7-9
STATUS command, 7-8
TERMTCP command, 7-11
release compatibility, 7-1
subsystem initialization, 2-26
Subsystem Security Exit (DBUGSSX), 2-24
Xpediter/CICS Customer Support, xxviii
Xpediter/CICS execution verification, 2-46
Xpediter/CICS startup during CICS initialization,
15-1–15-6
CSECT exclusions keywords, DBPA, 15-4
monitor exceptions keywords, DBPA, 15-4
storage protection and system labels keywords, DBPA, 15-5
trap summary keywords, DBPA, 15-2
Xpediter/CICS termination, 8-4
Xpediter/Code Coverage, 1-3
Xpediter/Eclipse
install and customize for, 2-50
XPN0 global table parameter, 8-2
XPN0 transaction, 8-2
XPND transaction, 8-1–8-4
XPOF transaction, 2-22, 8-1, 8-4
XPON transaction, 10-3
XSNOFF, 8-1
Z
z/OS datasets, 1-2
I-6

Xpediter/CICS Installation Guide

Transcription

Similar documents

Atlantis Energy Systems Inc.

2012 - Chicago International Charter School

Coffing EC3 Manual

Instituto Superior Bissaya Barreto • Coimbra

Pass With Flying Colors - Camp Manito

2010 - Chicago International Charter School

Xpediter/CICS Quick Reference

Parent-Student Handbook 2016-2017

This administrator guide is intended to assist system