Application Testing Collection for MVS/ESA & OS/390 IBM

Application Testing Collectionfor MVS/ESA & OS/390 IBM

User's GuideVersion 2 Release 1

SC26-9871-03

Application Testing Collectionfor MVS/ESA & OS/390 IBM

User's GuideVersion 2 Release 1

SC26-9871-03

Note!

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

| Fourth Edition (December 2000)

| This edition applies to version 2 release 1 modification 3 of IBM Application Testing Collection for MVS/ESA & OS/390 (product| number 5655-B97) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition reflects| documentation changes required to support Service APAR's PQ44107, PQ44108, and PQ44109.

Copyright International Business Machines Corporation 1997, 2000. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Table of Contents

About this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConventions and terminology used in this book . . . . . . . . . . . . . . . . . . xvii

Reading syntax diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiRelated information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixSending your comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi| Summary of changes (V2R1M3) . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Summary of changes (V2R1M2) . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiSummary of changes (V2R1M1) . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Part 1. Introducing the IBM Application Testing Collection . . . . . . . . . . . . . . . 1

Chapter 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Part 2. Installing and customizing ATC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. System installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 7What you receive with Application Testing Collection . . . . . . . . . . . . . . . . 7

Base feature: Coverage Assistant and Source Audit Assistant . . . . . . . . . 7Optional features: Distillation Assistant or Unit Test Assistant . . . . . . . . . 8

What you need to install Application Testing Collection . . . . . . . . . . . . . . . 8Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Storage requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11SVC requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Installing and customizing the base feature . . . . . . . . . . . . . . . . . . . . . 11Loading the data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Modifying the SATGEXEC data set . . . . . . . . . . . . . . . . . . . . . . . . 11Customizing common parameters . . . . . . . . . . . . . . . . . . . . . . . . . 12Setting up the linklist data set . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Setting up the authorized data sets . . . . . . . . . . . . . . . . . . . . . . . . 12Installing and enabling the monitor SVCs . . . . . . . . . . . . . . . . . . . . 14Ensuring users have access to AMASPZAP . . . . . . . . . . . . . . . . . . . 16Editing the site default exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Installing optional features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Copying ATC to system data sets . . . . . . . . . . . . . . . . . . . . . . . . . . 18Verifying the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 3. Basic user setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Modifying your ATC defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Editing your user defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Resetting your user defaults to the system defaults . . . . . . . . . . . . . . 25

Accessing the Language Environment runtime library . . . . . . . . . . . . . . . 25Starting the ATC ISPF interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 4. ATC samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Table of Contents iii

Part 3. Using Coverage Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 5. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35What is Coverage Assistant? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35What does CA require? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36How does CA work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Where can you get further details? . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 6. Coverage Assistant samples . . . . . . . . . . . . . . . . . . . . 41COBOL summary of test case coverage . . . . . . . . . . . . . . . . . . . . . . 43

Compile the source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Edit the CA control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Create Setup JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Create JCL to start a monitor session . . . . . . . . . . . . . . . . . . . . . . 47Create JCL for a Summary report . . . . . . . . . . . . . . . . . . . . . . . . . 47Edit JCL to link the modified object modules . . . . . . . . . . . . . . . . . . 48Edit JCL to run the GO step . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Execute the JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

COBOL Annotated Listing reports . . . . . . . . . . . . . . . . . . . . . . . . . . 49Compile the test case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Edit the CA control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Create Setup JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Create JCL to start a monitor session . . . . . . . . . . . . . . . . . . . . . . 51Create JCL for an Annotated Listing report . . . . . . . . . . . . . . . . . . . 52Edit JCL to link the modified object modules . . . . . . . . . . . . . . . . . . 52Edit JCL to run GO step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Execute the JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

PL/I summary of test case coverage . . . . . . . . . . . . . . . . . . . . . . . . . 53PL/I Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Assembler summary of test case coverage . . . . . . . . . . . . . . . . . . . . . 55Assembler Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 7. Editing the Coverage Assistant control file . . . . . . . . . . . . 61Contents of the control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Chapter 8. Coverage Assistant reports . . . . . . . . . . . . . . . . . . . . . 63Creating coverage reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Creating Summary and Annotated Listing report JCL using the panels . . . 64Summary report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Areas of the Summary report . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Suppression of conditional branch coverage with Performance Mode . . . . 71

Summary report when no listings are available during Setup . . . . . . . . . . 73Areas of the Summary report . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Summary report for assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74| Fields in the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Areas of the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Selecting specific listings to annotate . . . . . . . . . . . . . . . . . . . . . . . 84Reducing the size of an Annotated Listing report . . . . . . . . . . . . . . . . 84Displaying execution counts in an Annotated Listing report . . . . . . . . . . 85

iv ATC for MVS/ESA & OS/390 User's Guide

Differences in CA reports when DA and UTA are used . . . . . . . . . . . . . . 86Changes in annotation symbols with Performance Mode . . . . . . . . . . . . . 86Changes in annotation symbols with the EXTPROGRAM-ID option . . . . . . . 87Parameters for the Summary and Report programs . . . . . . . . . . . . . . . . 87

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Printing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Targeted Summary reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Targeted Summary control file . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Creating Targeted Summary reports . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 9. Using Coverage Assistant in a large project environment . . 99Creating CA files during code development . . . . . . . . . . . . . . . . . . . . . 99

Breakpoint data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Test case coverage results . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Combining test case coverage results . . . . . . . . . . . . . . . . . . . . . . . 101Creating the combine JCL using the panels . . . . . . . . . . . . . . . . . . 102Rules for combining results . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Measuring coverage for individual test cases . . . . . . . . . . . . . . . . . . . 104

Part 4. Using Distillation Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Chapter 10. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107What is Distillation Assistant? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107What does DA require? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Input master data set restrictions . . . . . . . . . . . . . . . . . . . . . . . . 108Logical distillation requirements . . . . . . . . . . . . . . . . . . . . . . . . . 109

How does DA work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Physical distillation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Where can you get further details? . . . . . . . . . . . . . . . . . . . . . . . . 113

Chapter 11. Distillation Assistant samples . . . . . . . . . . . . . . . . . . 115COB03 and PLI02 test cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 12. Logical distillation . . . . . . . . . . . . . . . . . . . . . . . . . 125Description of reading input data sets . . . . . . . . . . . . . . . . . . . . . . . 125Coverage of the distilled data set . . . . . . . . . . . . . . . . . . . . . . . . . 125PL/I ON-units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125How much data can be read . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Recording which keys execute a statement . . . . . . . . . . . . . . . . . . . . 126

Chapter 13. Editing the Distillation Assistant control file . . . . . . . . . 129Contents of the control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Chapter 14. Physical distillation . . . . . . . . . . . . . . . . . . . . . . . . 133Physical distillation summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Parameters used by physical distillation . . . . . . . . . . . . . . . . . . . . . . 134Running physical distillation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Generating JCL for physical distillation . . . . . . . . . . . . . . . . . . . . . 136Physical distillation return codes . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Table of Contents v

Part 5. Using Unit Test Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 15. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145What is Unit Test Assistant? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145What does UTA require? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146How does UTA work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Where can you get further details? . . . . . . . . . . . . . . . . . . . . . . . . 150

Chapter 16. Unit Test Assistant samples . . . . . . . . . . . . . . . . . . . 151COB02 test case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Chapter 17. Unit Test Assistant read and warp descriptions . . . . . . . 161Description of the variable read operation . . . . . . . . . . . . . . . . . . . . 161

Where a variable is read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Which COBOL storage areas can be read . . . . . . . . . . . . . . . . . . . 161How much data can be read . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Description of the variable warp operation . . . . . . . . . . . . . . . . . . . . 163What COBOL variables can be warped . . . . . . . . . . . . . . . . . . . . 163When a COBOL variable is warped . . . . . . . . . . . . . . . . . . . . . . . 163What PL/I variables can be warped . . . . . . . . . . . . . . . . . . . . . . . 163When a PL/I variable is warped . . . . . . . . . . . . . . . . . . . . . . . . . 163

Reading and warping on the same statement . . . . . . . . . . . . . . . . . . 163

Chapter 18. Editing the Unit Test Assistant control file . . . . . . . . . . 165Contents of the control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Chapter 19. Unit Test Assistant reports . . . . . . . . . . . . . . . . . . . . 167Monitored Variables report (MVR) . . . . . . . . . . . . . . . . . . . . . . . . . 167Variable Data report (VDR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Errors during data warping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Combined Variable Data report (CVDR) . . . . . . . . . . . . . . . . . . . . . . 171Creating Unit Test report JCL using the panels . . . . . . . . . . . . . . . . . 172Parameters for the UTA report program . . . . . . . . . . . . . . . . . . . . . . 174

Chapter 20. Unit Test Assistant file warping . . . . . . . . . . . . . . . . . 175File Warp operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175File Warp samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177File Warp control file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Field definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Group-level definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Record type definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Positional parameter definitions . . . . . . . . . . . . . . . . . . . . . . . . . 180Control file example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182File Warp return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Part 6. Common CA, DA, and UTA Information . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 21. CA, DA, and UTA control file . . . . . . . . . . . . . . . . . . . 187

vi ATC for MVS/ESA & OS/390 User's Guide

Contents of the control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Control file statement syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Control file examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Chapter 22. CA, DA, and UTA setup . . . . . . . . . . . . . . . . . . . . . . 211Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Compiler options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Instrumenting load modules using listings . . . . . . . . . . . . . . . . . . . . . 219Instrumenting load modules without listings . . . . . . . . . . . . . . . . . . . . 220Creating the Setup JCL using the panels . . . . . . . . . . . . . . . . . . . . . 222When to create or submit Setup JCL . . . . . . . . . . . . . . . . . . . . . . . 224Setup JCL for the compile job stream . . . . . . . . . . . . . . . . . . . . . . . 224Parameters for the Setup and Zaptxt programs . . . . . . . . . . . . . . . . . 224

Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Zaptxt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Chapter 23. Monitor execution . . . . . . . . . . . . . . . . . . . . . . . . . 227Creating the monitor JCL using the panels . . . . . . . . . . . . . . . . . . . . 229Parameters for Start monitor (ATGOMCMD) . . . . . . . . . . . . . . . . . . . 231Parameters for Variable monitor (ATGOMVAR) . . . . . . . . . . . . . . . . . 231Multiple user sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Coverage of common modules with multiple user sessions . . . . . . . . . 232Using the Performance Mode to reduce monitor overhead . . . . . . . . . . . 235Restrictions on types of programs that can be monitored . . . . . . . . . . . . 236System abend 0F8 on user program . . . . . . . . . . . . . . . . . . . . . . . . 236Restrictions on where programs can be monitored . . . . . . . . . . . . . . . 236Buffer monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Chapter 24. Monitor commands . . . . . . . . . . . . . . . . . . . . . . . . . 239Issuing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

ATGPROFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241ATGPRON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242ATGQUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243ATGRBPDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244ATGRESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248ATGRIDAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249ATGRVADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250ATGSESSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252ATGSLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253ATGSNAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255ATGSTATS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257ATGSTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Chapter 25. Diagnosing monitor problems . . . . . . . . . . . . . . . . . . 261System abend 047 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261System abend 7C3 on user program . . . . . . . . . . . . . . . . . . . . . . . 261Protection exception 0C4 (reason code 4) on user program . . . . . . . . . . 262System abend 0F8 on user program . . . . . . . . . . . . . . . . . . . . . . . . 262System abend Fnn on user program . . . . . . . . . . . . . . . . . . . . . . . . 262Lack of SQA or ECSA space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Poor performance when measuring conditional branch coverage . . . . . . . 263

Part 7. Using Source Audit Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Table of Contents vii

Chapter 26. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267What is Source Audit Assistant? . . . . . . . . . . . . . . . . . . . . . . . . . . 267What does SAA require? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267How does SAA work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Chapter 27. Source Audit Assistant samples . . . . . . . . . . . . . . . . 271

Chapter 28. Starting Source Audit Assistant . . . . . . . . . . . . . . . . . 275Executing the SAA source extractor . . . . . . . . . . . . . . . . . . . . . . . . 275Executing the SAA Comparison Analysis tool . . . . . . . . . . . . . . . . . . 277

Chapter 29. Source Audit Assistant Comparison Analysis tool . . . . . 281SAA Comparison Analysis tool inputs . . . . . . . . . . . . . . . . . . . . . . . 281SAA Comparison Analysis tool outputs . . . . . . . . . . . . . . . . . . . . . . 282

Part 8. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Appendix A. Problem determination . . . . . . . . . . . . . . . . . . . . . . 287ATGO: Combine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288ATGR: Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290ATGS: Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301ATGT: SAA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307ATGV: ATGOVARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312ATGW: Distill and File Warp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322ATGX: Monitor and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ATGY: Control files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339ATGZ: Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Appendix B. ATC requirements and resources . . . . . . . . . . . . . . . 359CA resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Monitor ECSA and SQA usage . . . . . . . . . . . . . . . . . . . . . . . . . 360Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Data set attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361DDNAMEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

DA and UTA resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Monitor ECSA and SQA usage . . . . . . . . . . . . . . . . . . . . . . . . . 363Data set attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363DDNAMEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Appendix C. DBCS support . . . . . . . . . . . . . . . . . . . . . . . . . . . 365DBCS requirements for ATC compilers and assemblers . . . . . . . . . . . . 365DBCS support with CA, DA, and UTA . . . . . . . . . . . . . . . . . . . . . . . 365DBCS support with the SAA Comparison Analysis tool . . . . . . . . . . . . . 366

Appendix D. Converting existing ATC systems and users to V2R1M3 . 367| V2R1M0, V2R1M1,or V2R1M2 systems and users to V2R1M3 . . . . . . . . 367

V1RxMx systems and users to V2R1M3 . . . . . . . . . . . . . . . . . . . . . 367

Appendix E. Coverage Assistant FastPath . . . . . . . . . . . . . . . . . . 369Creating Quick Start JCL from the panels . . . . . . . . . . . . . . . . . . . . 370

Quick Start parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

viii ATC for MVS/ESA & OS/390 User's Guide

Creating Snapshot Summary JCL from the panels . . . . . . . . . . . . . . . 375Creating Quick Stop JCL from the panels . . . . . . . . . . . . . . . . . . . . . 377

Quick Stop Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Appendix F. Parameters Common To Multiple Routines . . . . . . . . . . 381NATLANG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382LOCALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383LINECOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Table of Contents ix

x ATC for MVS/ESA & OS/390 User's Guide

Figures

1. ATC Primary Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 192. Manipulate ATC Defaults panel . . . . . . . . . . . . . . . . . . . . . . . . 203. ATC Defaults panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224. Reset Defaults to System Defaults panel . . . . . . . . . . . . . . . . . . . 255. CA—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386. Sample run—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . 427. Summary report for COB01 . . . . . . . . . . . . . . . . . . . . . . . . . . 448. Control file for COB01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469. COBOL Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . 50

10. Summary report for PLI01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 5411. Control file for PLI01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5412. PL/I Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . . 5513. Summary report for ASM01 . . . . . . . . . . . . . . . . . . . . . . . . . . 5614. Control file for ASM01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5615. Assembler Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . 5716. Coverage Reports panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6317. Create JCL for Summary Report panel . . . . . . . . . . . . . . . . . . . . 6418. Create JCL for Summary and Annotated Listing Report panel . . . . . . 6519. Summary report for COB01 in COBOL . . . . . . . . . . . . . . . . . . . . 6820. Summary report for PLI01 in PL/I . . . . . . . . . . . . . . . . . . . . . . . 6921. Summary report with Performance Mode enabled during Setup . . . . . 7222. Summary report when no listings are available during Setup . . . . . . . 74

| 23. Summary report for ASM01 showing executable statements . . . . . . . 76| 24. Summary report for ASM01 showing executable bytes . . . . . . . . . . . 77

25. COBOL Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . 7926. PL/I Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . . 8127. ASM Annotated Listing report . . . . . . . . . . . . . . . . . . . . . . . . . 8228. Annotated Listing report with execution counts . . . . . . . . . . . . . . . 8529. Sample conditional branch coverage with UTA . . . . . . . . . . . . . . . 8630. Sample conditional branch coverage without UTA . . . . . . . . . . . . . 8631. Sample Annotated Listing report with UTA . . . . . . . . . . . . . . . . . . 8632. Sample Annotated Listing report without UTA . . . . . . . . . . . . . . . . 8633. Targeted Summary control file . . . . . . . . . . . . . . . . . . . . . . . . . 9534. Generate a Targeted Summary Report panel . . . . . . . . . . . . . . . . 9635. Using CA in a large project environment—flow diagram . . . . . . . . . 10036. Combining results of multiple testers—flow diagram . . . . . . . . . . . 10137. Create JCL for Combining Multiple Runs panel . . . . . . . . . . . . . . 10238. ISPF edit screen for combining results . . . . . . . . . . . . . . . . . . . 10339. DA—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11140. Sample run—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . 11641. Input master data set for COB03 and PLI02 . . . . . . . . . . . . . . . . 11842. New (distilled) master data set for COB03 and PLI02 . . . . . . . . . . 11843. Control file for COB03 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12044. Control file for PLI02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12045. Partial Annotated Listing report for COB03 showing key numbers . . . 12646. CACTL statements for distillation (COBOL) . . . . . . . . . . . . . . . . 13147. COBOL file definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13148. CACTL statements for distillation (PL/I) . . . . . . . . . . . . . . . . . . . 13149. Create JCL to Generate a Key List and Distill Data panel . . . . . . . . 13550. Create JCL to Generate a Key List and Distill DASD Data panel . . . . 136

Figures xi

51. Create JCL to Generate a Key List and Distill Tape Data panel . . . . 13952. UTA—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14853. Sample UTA run—flow diagram . . . . . . . . . . . . . . . . . . . . . . . 15254. MVR for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15455. VDR for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15556. Control file for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15757. Sample UTA control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16658. COBOL file definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16659. Control file for warping a PL/I input buffer . . . . . . . . . . . . . . . . . 16660. MVR for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16961. VDR for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17062. CVDR for COB02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17163. Create JCL for Unit Test Assistant Reports panel . . . . . . . . . . . . . 17264. UTA—file warp flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . 17565. Copy book defining a file record . . . . . . . . . . . . . . . . . . . . . . . 17666. Example of a warp control file . . . . . . . . . . . . . . . . . . . . . . . . 17667. Generate JCL for File Warping panel . . . . . . . . . . . . . . . . . . . . 17768. Example control file with file warping definitions . . . . . . . . . . . . . . 18269. Coverage, Distillation and Unit Test Assistant panel . . . . . . . . . . . 18770. Work with the CA/DA/UTA Control File panel . . . . . . . . . . . . . . . 18771. CA Setup—flow diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . 21872. DA and UTA Setup—flow diagram . . . . . . . . . . . . . . . . . . . . . 21873. Create JCL for Setup panel . . . . . . . . . . . . . . . . . . . . . . . . . 22274. CA test case execution—flow diagram . . . . . . . . . . . . . . . . . . . 22775. DA test case execution—flow diagram . . . . . . . . . . . . . . . . . . . 22876. UTA test case execution—flow diagram . . . . . . . . . . . . . . . . . . 22877. Create JCL to Start the Monitor panel . . . . . . . . . . . . . . . . . . . 22978. Control the CA/DA/UTA Monitor panel . . . . . . . . . . . . . . . . . . . 24079. Monitor: Quit Monitor panel 1 . . . . . . . . . . . . . . . . . . . . . . . . 24380. Monitor: Quit Monitor panel 2 . . . . . . . . . . . . . . . . . . . . . . . . 24381. Quit monitor status panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 24482. Monitor: Display Breakpoint Status panel . . . . . . . . . . . . . . . . . . 24483. Breakpoint status panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24684. Monitor: Reset All Data in Monitor panel . . . . . . . . . . . . . . . . . . 24885. Monitor: Add ID panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24986. Add ID status panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24987. Monitor: Display Variable Status panel . . . . . . . . . . . . . . . . . . . 25088. Variable information panel . . . . . . . . . . . . . . . . . . . . . . . . . . 25189. Active session display panel . . . . . . . . . . . . . . . . . . . . . . . . . 25290. Release level and table address data . . . . . . . . . . . . . . . . . . . . 25291. Monitor: Display Listings panel . . . . . . . . . . . . . . . . . . . . . . . . 25392. Listings statistics panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25493. Monitor: Take Snapshot of Data panel 1 . . . . . . . . . . . . . . . . . . 25594. Monitor: Take Snapshot of Data panel 2 . . . . . . . . . . . . . . . . . . 25595. Snapshot status panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25696. Monitor: Display Statistics panel . . . . . . . . . . . . . . . . . . . . . . . 25797. PA statistics panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25898. Monitor: Stop Monitor panel 1 . . . . . . . . . . . . . . . . . . . . . . . . 25999. Monitor: Stop Monitor panel 2 . . . . . . . . . . . . . . . . . . . . . . . . 259100. Stop completed panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260101. SuperC panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271102. Create Prototype Target Control Dataset & Validate Changes panel . . 272103. Sample SAA Change Validation report . . . . . . . . . . . . . . . . . . . 273104. Sample SAA Targeted Summary control file . . . . . . . . . . . . . . . . 273

xii ATC for MVS/ESA & OS/390 User's Guide

105. Source Audit Assistant panel . . . . . . . . . . . . . . . . . . . . . . . . . 275106. Extract Source Code from Listings panel . . . . . . . . . . . . . . . . . . 275107. Create Prototype Targeted Summary Dataset & Validate Changes panel 278108. Sample SAA Change Validation report . . . . . . . . . . . . . . . . . . . 283109. Coverage Assistant FastPath panel . . . . . . . . . . . . . . . . . . . . . 369110. Create JCL for Quick Start panel . . . . . . . . . . . . . . . . . . . . . . 371111. Quick Start Parameters panel . . . . . . . . . . . . . . . . . . . . . . . . 372112. Create JCL for Snapshot Summary panel . . . . . . . . . . . . . . . . . 375113. Create JCL for Stop & Summary panel . . . . . . . . . . . . . . . . . . . 377114. Quick Stop Parameters panel . . . . . . . . . . . . . . . . . . . . . . . . 378

Figures xiii

xiv ATC for MVS/ESA & OS/390 User's Guide

Tables

1. CA, DA, and UTA data sets . . . . . . . . . . . . . . . . . . . . . . . . . . 272. SAA data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283. CA COBOL sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284. CA PL/I sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295. CA assembler sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296. DA COBOL sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307. DA PL/I sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308. UTA sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319. UTA File Warp sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

10. SAA sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3111. Supported input/output combinations . . . . . . . . . . . . . . . . . . . . 13412. COBOL syntax conversion table . . . . . . . . . . . . . . . . . . . . . . . 20613. PL/I syntax conversion table . . . . . . . . . . . . . . . . . . . . . . . . . 20614. Multiple testers executing code in a module monitored by one session 23315. Multiple testers executing code in a module monitored by multiple

sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23416. Multiple testers executing code in a module, but each tester with a

unique copy of the module . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Tables xv

xvi ATC for MVS/ESA & OS/390 User's Guide

About this book

This book provides information about the IBM Application Testing Collection forMVS/ESA & OS/390. The Application Testing Collection (ATC) is a generalpurpose application development (AD) test tool suite.

Who should read this bookYou should read this book if you will be testing applications on MVS/ESA orOS/390.

Conventions and terminology used in this bookThe following list describes special ways in which some characters and words aredisplayed in this book and describes the meaning associated with each one:

Display Method Meaning

Monospaced type Shows something that you type (such as a command),an example, or something that is displayed on yourmonitor (for example, an error message).

Italic type Indicates information that you supply (such as a param-eter or a variable). Italic type can also indicate a newterm. See the glossary for definitions of new terms.

Bold type Indicates information that you should pay particularattention to.

Reading syntax diagramsThroughout this book, syntax is presented in diagrams. The following list describeshow to read the diagrams to enter commands correctly:

� Read the syntax diagrams from left to right, from top to bottom, following thepath of the line.

The ─── symbol indicates the beginning of a statement.

The ─── symbol indicates that the statement syntax is continued on thenext line.

The ─── symbol indicates that a statement is continued from the previousline.

The ─── � symbol indicates the end of a statement.

Diagrams of syntactical units other than complete statements start with the ─── symbol and end with the ─── symbol.

Fragments of a syntax diagram are enclosed by the symbol ├───┤.

About this book xvii

� Required items appear on the horizontal line (the main path).

──statement──required-item───────────────────────────────────────── �

� Optional items appear below the main path.

──statement─ ──┬ ┬─────────────── ──────────────────────────────────── � └ ┘─optional-item─

� Defaults appear above the main path.

┌ ┐─default-item─ ──statement─ ──┴ ┴────────────── ───────────────────────────────────── �

� If you can choose from two or more items, they appear vertically, in a stack.

If you must choose one of the items, one item of the stack appears on the mainpath.

──statement─ ──┬ ┬─required-choice1─ ───────────────────────────────── � └ ┘─required-choice2─

If choosing one of the items is optional, the entire stack appears below themain path.

──statement─ ──┬ ┬────────────────── ───────────────────────────────── � ├ ┤─optional-choice1─ └ ┘─optional-choice2─

� An arrow returning to the left above the main path indicates an item that can berepeated.

┌ ┐─────────────────── ──statement─ ───

�┴─repeatable-item─ ────────────────────────────────── �

A repeat arrow above a stack indicates that you can make more than onechoice from the stacked items, or repeat a single choice.

� An out-of-line fragment of a syntax diagram, which is shown later in the syntaxdiagram (or in another syntax diagram), is enclosed in vertical bars.

──statement──required-item──┤ required-group ├─ ──┬ ┬─────────────── ─ � └ ┘─optional-item─

required-group:├─ ──┬ ┬─OPTION1─ ─more-required-items───────────────────────────────────┤ └ ┘─OPTION2─

� Keywords appear as bold uppercase letters and should be spelled exactly asshown (for example, DEFAULTS ). However, keywords may be coded in anycombination of uppercase and lowercase characters.

Variables appear in all italic letters (for example, label). They represent user-supplied names or values.

� Only one keyword from a particular group can be specified, and the samekeyword cannot be specified more than once unless explicitly indicated.

� If punctuation marks, parentheses, arithmetic operators, or any such symbolsare shown, you must enter them as part of the syntax.

xviii ATC for MVS/ESA & OS/390 User's Guide

Related informationThe following publications are available in hardcopy form. They are also availablein downloadable form from the ATC Web site:

Application Testing Collection for MVS/ESA & OS/390 Version 2 Release 1,Product Number 5655-B97:

Automated Regression Testing Tool User's Guide, SC26-9872

Fact Sheet, GC26-9883

General Information, GC26-9870

Licensed Program Specifications, GC26-9884

Program Directory, GI10-8207

To locate these publications go to:

http://www.ibm.com/s390/atc

Each publication is available in PostScript and the following online formats:

� Book, which can be viewed with the IBM BookManager READ and IBMLibrary Reader licensed programs. The IBM Library Reader can be down-loaded from the following Web site:http://booksrv2.raleigh.ibm.com/homepage/ilrserv.html

� PDF, which can be viewed with the Adobe Acrobat Reader 3.0 and later. TheAdobe Acrobat Reader can be downloaded from the Adobe Web site.

Sending your commentsYour feedback helps IBM to provide quality information. Please send any com-ments that you have about this book or other Application Testing Collection doc-umentation. You can use any of the following methods to provide comments:

� Send your comments by e-mail to [email protected]. Be sure to include thename of the product, the version number of the product, and the name and partnumber of the book (if applicable). If you are commenting on specific text,please include the location of the text (for example, a chapter and section title,a table number, a page number, or a help topic title).

� Complete the readers' comment form at the back of the book and return it bymail, by fax (859-243-4345 for the United States and Canada), or by giving it toan IBM representative.

About this book xix

xx ATC for MVS/ESA & OS/390 User's Guide

Summary of changes

| Summary of changes (V2R1M3)| � CA now supports breakpointing of assembler code containing more than one| CSECT in a single assembly.

| � For assembler programs, the summary statement statistics are now available| based on number of statements or bytes of code. Number of statements is| now the default.

| � When compiling for CA using the VisualAge PL/I compiler, the NOINSOURCE| option is now required only when using the 2.2.0 compiler without APAR| PQ40062.

| � Source Audit Assistant now accepts SuperC listings generated with the WIDE| option.

| � Minor corrections have been made throughout the book.

Summary of changes (V2R1M2)� Basic National Language support is provided. ATC is now enabled for future

addition of alternate languages. Currently only mixed case English is supported.

� LOCALE support is provided to allow user or installation specification of desireddate, time, and numeric formats.

� LINECOUNT support is provided to allow user selection of page size.

� VisualAge PL/I Version 2 Release 2 is now supported by Coverage Assistantand Source Audit Assistant.

� Minor corrections have been made throughout the book.

Summary of changes (V2R1M1)� The COBOL NOTEST compiler option is no longer required in order to use

normal setup when listing analysis is done.

� Unit Test Assistant data warping now supports the multiply and divide operatorsin addition to addition and subtraction.

� Source Audit Assistant now allows source margins to be specified for PL/Isource programs.

� All of the data formerly put in ESQA by the ATC monitor is now put in ECSA(e.g., breakpoint tables).

� The Internet site from which downloadable user publications can be obtainedhas changed.

� The fax number for use in returning the reader's comment form has changed.

� Requirements for the use of Language Environment have been clarified.

� Minor corrections have been made throughout the book.

Summary of changes xxi

xxii ATC for MVS/ESA & OS/390 User's Guide

Part 1. Introducing the IBM Application Testing Collection

Part 1. Introducing the Application Testing Collection 1

2 ATC for MVS/ESA & OS/390 User's Guide

Chapter 1. Overview

The Application Testing Collection (ATC) is a set of tools that enable you toaddress the challenge of planning, performing, and evaluating the results of MVSand OS/390 batch and online testing. The tools that make up ATC are asfollows:

Coverage AssistantCoverage Assistant (CA) measures code coverage in application pro-grams written in the COBOL, PL/I, and S/390 assembler languages andcompiled by specific IBM COBOL and PL/I compilers or assembled bythe High Level Assembler or Assembler H.

Distillation AssistantDistillation Assistant (DA) monitors file reads for a specified file that con-tains logical keys and determines all of the keys that caused increasedcode coverage. It then creates a “distilled” copy of the input file, con-taining only the records containing these keys. This smaller, distilled filecan then be used during program testing to obtain equivalent code cov-erage, but at the same time, decrease the time and resources requiredfor the testing. DA does this for applications written in the COBOL orPL/I language and compiled by specific IBM COBOL or PL/I compilers.

Unit Test AssistantUnit Test Assistant (UTA) reads and records the values assigned to vari-ables at selected statement numbers in an application program as it isexecuting. It creates a report, which allows subsequent analysis of thevariable data. UTA does this for applications written in the COBOL lan-guage and compiled by specific IBM COBOL compilers.

In addition, UTA provides two types of data warping:

1. Dynamic data warping 2. File warping

UTA dynamic data warping automatically modifies variables as they areencountered during program execution. When data enters or exits aprogram at I/O time (or at other times where the application logic dic-tates), UTA changes the value of that data in a manner that you specify.UTA does this for COBOL variables and PL/I input buffers.

A standard file warping process is that of aging, or warping, occurrencesof dates in input data files. Using UTA file warping, copies of input filesare made with data fields of records warped under user control.

Source Audit AssistantSource Audit Assistant (SAA) analyzes a comparison (generated by theSuperC Compare Utility) of two levels of source code. SAA helps verifywhether changes are valid and identifies items that need closer exam-ination. The identified changed source can also be directed as input toother tools in the collection, such as Coverage Assistant's targetedsummary.

Chapter 1. ATC overview 3

Automated Regression Testing ToolAutomated Regression Testing Tool (ARTT) is a capture and verificationtool that records a base run of your program and automatically com-pares it with a proof run using real or previously captured input. ARTTpermits all levels of testing (unit, function, integration, and system) withor without a production system, and its data transformation capabilityallows testing to continue when I/O and programs are in incompatibleformats (for example, when one has been modified to accept futuredates and the other has not). Data transformation can be particularlyuseful if you are unsure of the status of I/O received from outsidesources. For more information, see the user documentation that wasshipped with ARTT.


Part 2. Installing and customizing ATC

Part 2. Installing and customizing ATC 5


Chapter 2. System installation

This chapter summarizes the system and hardware requirements and the installa-tion process for the following Application Testing Collection tools: CoverageAssistant (CA), Source Audit Assistant (SAA), Distillation Assistant (DA), and UnitTest Assistant (UTA). Information about installing the ATC Automated RegressionTesting Tool (ARTT) is in the user documentation that was shipped with ARTT.

Installation requirements and related service information are updated periodically.For any changes that may have been made to the following information since thisbook was printed, see the Program Directory.

What you receive with Application Testing CollectionWhen you order the base feature of the IBM Application Testing Collection forMVS/ESA & OS/390 (5655-B97), you receive the Coverage Assistant and SourceAudit Assistant tools. ATC optional features that you can order are DistillationAssistant and Unit Test Assistant.

Base feature: Coverage Assistant and Source Audit AssistantYou receive the following items with the Coverage Assistant and Source AuditAssistant tools:

� Documentation


– General Information, GC26-9870

– Licensed Program Specifications, GC26-9884

– Program Directory, GI10-8207

– User's Guide, SC26-9871

� Distribution media

Application Testing Collection is SMP/E installable.

� Data sets (created during SMP/E installation and post install jobs)

The data set names shown below use the default low level qualifiers. Yourinstallation may have chosen to change them.

hi_lev_qual.SATGATGI ATC General Information (in BookManagerBOOK format)

hi_lev_qual.SATGATUG ATC User's Guide (in BookManager BOOKformat)

hi_lev_qual.SATGEXEC Command procedures (REXX)

hi_lev_qual.SATGMLIB ISPF messages

hi_lev_qual.SATGMOD Executable modules

hi_lev_qual.SATGBMOD Executable modules to be added to the systemlinklist concatenation

Chapter 2. System installation 7

hi_lev_qual.SATGPLIB ISPF panels

hi_lev_qual.SATGSAMP Samples

hi_lev_qual.SATGSLIB ISPF skeletons

hi_lev_qual.SATGTLIB ISPF tables

Optional features: Distillation Assistant or Unit Test AssistantYou receive the following items with the Distillation Assistant and Unit TestAssistant tools:

� Documentation


– Licensed Program Specifications, GC26-9884

– Program Directory, GI10-8207

� Distribution media

Application Testing Collection is SMP/E installable.

� Data sets (updated during SMP/E installation and post install jobs)

The data set names shown below use the default low level qualifiers. Yourinstallation may have chosen to change them.

hi_lev_qual.SATGEXEC Command procedures (REXX)

hi_lev_qual.SATGMOD Executable modules

hi_lev_qual.SATGPLIB ISPF panels

hi_lev_qual.SATGSLIB ISPF skeletons

What you need to install Application Testing CollectionBefore installing Application Testing Collection, make sure that your system meetsthe following hardware, software, and storage requirements.

Hardware requirementsApplication Testing Collection runs on all Year 2000-ready S/390-compatibleprocessors.

Software requirementsApplication Testing Collection requires one of the following operating systems:

� MVS/ESA SP Version 5 (5655-068 or 5655-069) or later

– DFSMS/MVS 1.2 (5695-DF1)

– TSO/E 2.5 (5685-025)

– ISPF 4.2.1 (5645-001)

– Language Environment for MVS & VM 1.5 (5688-198)

Note: The ATC programs use Language Environment for MVS & VM 1.5,however it is not a requirement for the user's programs.


� OS/390 Version 1 (5645-001), OS/390 Version 2 (5647-A01), or later

This includes OS/390 versions of DFSMS/MVS, TSO/E, ISPF for OS/390,and Language Environment.

Note: The ATC programs use Language Environment for OS/390 & VM,however it is not a requirement for the user's programs.

To install Application Testing Collection, you must use System ModificationProgram/Extended (SMP/E) Release 8.1 or later.

Application Testing Collection can be used in conjunction with the following pro-ducts, if installed: Coverage Assistant, Source Audit Assistant, Distillation Assistant,and Unit Test Assistant.

Coverage Assistant supports the following compilers and assemblers:

� IBM COBOL for OS/390 & VM 2.1 (5648-A25)

� VisualAge COBOL Millennium Language Extensions for OS/390 & VM 1.0(5648-MLE)

� IBM COBOL for MVS & VM 1.2 (5688-197)

� VisualAge COBOL Millennium Language Extensions for MVS & VM 1.0(5654-MLE)

� VS COBOL II Version 1 Release 4.0 (5688-022, 5688-023)

� OS/VS COBOL Version 1 Release 2.4 (5740-CB1, 5740-LM1)

� VisualAge PL/I Compiler Version 2 Release 2 (5655-B22)

� IBM PL/I for MVS & VM 1.1.1 (5688-235)

� VisualAge PL/I Millennium Language Extensions for MVS & VM 1.0(5648-MLX)

� OS PL/I Optimizing Compiler 2.3.0 (5668-909, 5668-910, 5668-911)

� OS PL/I Optimizing Compiler 1.5.1 (5734-PL1, 5734-PL3, 5734-LM4,5734-LM5)

� High Level Assembler (HLASM) Version 1 Release 2 or 3 (5696-234)

� Assembler H (HASM) Version 2 (5668-962)

Distillation Assistant supports the following compilers:







� IBM PL/I for MVS & VM 1.1.1 (5688-235)





Note that although the VisualAge PL/I Compiler Version 2 Release 2 (5655-B22) issupported by Coverage Assistant and Source Audit Assistant, it is not currentlysupported by Distillation Assistant.

Unit Test Assistant supports the following compilers:







The following PL/I compilers are supported for data warping of file buffers only:

� IBM PL/I for MVS & VM 1.1.1 (5688-235)




Note that although the VisualAge PL/I Compiler Version 2 Release 2 (5655-B22) issupported by Coverage Assistant and Source Audit Assistant, it is not currentlysupported by Unit Test Assistant.

Source Audit Assistant supports the following languages for seed analysis and tem-plate control file generation:

� COBOL � PL/I

Source Audit Assistant supports the following compiler and assembler listings forthe listing extractor:









� IBM PL/I for MVS & VM 1.1.1 (5688-235)




� High Level Assembler (HLASM) Version 1 Releases 1, 2 and 3 (5696-234)

� Assembler H (HASM) Version 2 (5668-962)

Storage requirementsApplication Testing Collection requires minimal storage for installation. Storagerequirements during execution vary depending on the size of the program you areworking with.

SVC requirementsApplication Testing Collection requires two user SVCs. These SVCs are installedand enabled dynamically, by running a user-supplied job either directly or duringIPL. These SVCs must be installed before any user jobs that are to be monitoredare run. If not, an Fnn abend will occur when a user runs a breakpointed program.

Installing and customizing the base featureInstalling the ATC base feature consists of the following sets of steps, each ofwhich is described in this chapter:

� Loading the data sets� Modifying the SATGEXEC data set� Customizing common parameters� Setting up the linklist data set� Setting up the authorized data sets� Installing and enabling the monitor SVCs� Ensuring users have access to AMASPZAP� Editing the site default exec

Loading the data setsLoad the ATC data sets onto your system using the instructions in the ProgramDirectory.

Modifying the SATGEXEC data setOnce the data sets are installed on your system, you must modify the SATGEXECdata set to specify your data set names. Edit the ATGSTART member of theSATGEXEC data set, following the directions in the member's prologue for sitecustomization of data set names.


Customizing common parametersThe common_parameters described in Appendix F, “Parameters Common To Mul-tiple Routines” on page 381 can be customized in the following ways at installationtime:

1. The default national language can be selected from any of the validlanguage_id values.

2. New date, time, and numeric formats can be defined for use in the LOCALEoption.

3. The default LOCALE values can be selected from any of the valid date_fmt,time_fmt, and numeric_fmt values listed or from any locally defined formats.

4. The default LINECOUNT can be altered.

In order to make any of these customizations, the ATGONIOP load module inSATGBMOD must be re-generated using the source found inSATGSAMP(ATGONIOP). The following steps describe the process for thiscustomization:

� Copy the ATGONIOP member of SATGSAMP into another dataset.

� Modify the copy following the comments in the code.

� Assemble the modified copy using the High Level Assembler and usingSATGSAMP as a SYSLIB.

� Linkedit the object from this assembly into the SATGBMOD dataset.

Sample JCL is provided to perform these steps in member ATGXNIOP inSATGSAMP.

Setting up the linklist data setCertain ATC load modules must be available in the system linklist concatenation.This may be accomplished in either of two ways:

� You may add the SATGBMOD dataset to your linklist concatenationor,� You may copy the following members of SATGBMOD into an existing linklist

dataset: – ATGONIOP – ATGONIRL – ATGO4ENU

Note that after copying these members into an existing linklist data set youmust do an LLA refresh to make these members available to the ATC pro-grams.

Setting up the authorized data setsCertain ATC load modules must be placed in APF authorized libraries. Some ofthese load modules must be capable of being executed by general users (see“Authorized programs for which general user access is required” on page 13) whileothers must be executable only by system programmers (see “Authorized programsfor which general user access is prohibited” on page 13).


There are several ways to accomplish this:

1. Make SATGMOD APF authorized and RACF accessible to general users

In this case, there is no further action required for the programs that are exe-cutable by general users. However, you must take one of the following actionsfor the programs that should only be executable by a system programmer:

a. Move these programs to another APF authorized library to which onlysystem programmers have RACF access.

orb. Use RACF Program profiles to restrict execution of these programs.

2. Do not make SATGMOD APF authorized

In this case you must:

a. Copy the programs to be executed by general users to an APF authorizedlibrary to which general users have access.

and b. Either:

� Copy the programs to which only system programmers should haveaccess to another APF authorized library to which only system pro-grammers have RACF access.

or� Copy the programs to which only system programmers should have

access to an APF authorized library to which general users haveaccess and use RACF Program profiles to restrict execution of theseprograms.

Authorized programs for which general user access is requiredThe following monitor interface and variable monitor load modules that are distrib-uted in SATGMOD must be in an authorized data set and available to generalusers via STEPLIB/PGM= for a batch job or via TSO CALL for a REXX EXEC:

� ATGOMCMD (monitor interface)� ATGOMVAR (variable monitor)� ATGO3ENU (monitor messages)

In addition, ATGOMCMD must be made available to be called as an authorizedTSO program; otherwise, an 047 abend will occur. This can be accomplished byadding the ATGOMCMD program to the AUTHPGM entry in the SYS1.PARMLIBmember IKJTSOxx. You must also tell TSO to use this new authority (dynamically,by issuing the PARMLIB UPDATE(xx) command from TSO, or by doing an IPL).User's must be able to invoke this program using the TSO CALL command.

Authorized programs for which general user access is prohibitedThe monitor installer/enabler and monitor SVC (ATGOMNST and ATGOMONS)load modules distributed in SATGMOD must be placed in an authorized library fromwhich only a system programmer (or whoever is allowed to install SVCs) canexecute.


Setting up RACF Program profilesIf you choose to put the programs described in “Authorized programs for whichgeneral user access is prohibited” on page 13 in an APF authorized data set that isaccessible to general users, you must use RACF PROGRAM profiles to restrictaccess to these programs.

Allow the ATGOMNST-started task (described in “Installing and enabling themonitor SVCs”) to execute these modules.

Ensure that your users do not have read/execute access to these modules in anauthorized library.

To set up RACF PROGRAM profiles to restrict access to these programs, RACFcommands shown in the following example might be used.

RDEFINE PROGRAM(ATGOMNST) NOTIFY(notify) UACC(NONE) +

DATA('RACF profile for ATC monitor') +

ADDMEM('authlib'/'volser'/PADCHK) OWNER(owner))

RDEFINE PROGRAM(ATGOMONS) NOTIFY(notify) UACC(NONE) +

DATA('RACF profile for ATC monitor') +

ADDMEM('authlib'/'volser'/PADCHK) OWNER(owner)

SETROPTS WHEN(PROGRAM) REFRESH

PERMIT ATGOMNST CLASS(PROGRAM) ID(id) ACCESS(READ)

PERMIT ATGOMONS CLASS(PROGRAM) ID(id) ACCESS(READ)

SETROPTS WHEN(PROGRAM) REFRESH

where:

notify TSO user ID of the person who should be notified of a RACF accessfailure

authlib Data set name of the authorized library containing ATGOMNST andATGOMONS

volser Volume serial of authlib data set (or ****** to specify the currentSYSRES volume)

owner TSO user ID or RACF group name of the person or persons that willown this profile

id TSO user ID or RACF group name of the person or persons who shouldhave the ability to install the SVCs

Installing and enabling the monitor SVCsBefore a user starts a monitor session, the monitor SVCs must be installed andenabled. The ATGOMNST module does this for you. It must be run toinstall/enable the SVCs, reinstall/enable the SVCs after service is applied, or at anyIPL time after the initial installation.

To do the initial installation:

1. Acquire two free user SVC numbers.

Note: SYS1.PARMLIB(IEASVCxx) does not need to be updated since theseuser SVCs will be installed dynamically. However, you do need to ensure thatthese SVC numbers are not being used on your system.


2. Edit hi_lev_qual.SATGSAMP(ATGXISVC) and change the following:

a. Change the STEPLIB data set name to the authorized data set that con-tains the ATGOMNST and ATGOMONS modules.

b. Change the JOB card to run on your system.

c. Change the PARM operands to contain the two SVC numbers you acquiredfor ATC. Make sure you enter these numbers (in hexadecimal nota-tion) correctly!

d. If users do not want COBOL programs that use the TEST option in theabsence of a listing to abend if no matching monitor session exists, addTESTOPT as the third parameter. For more information, see “Instru-menting load modules without listings” on page 220.

3. Submit this JCL on the system on which you intend to run the monitor. The jobshould get a return code of 0 (RC=0).

4. To verify that the monitor has been installed/enabled properly, run the followingcommand from ISPF 6:

ex 'hi_lev_qual.SATGEXEC(ATGSESSN)' 'LEVEL'

You should then see an ISPF Browse panel that looks similar to this:

BROWSE YOUNG.MSGS.FILE Line 00000000 Col 00

Command ===> Scroll ===>

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLL Top of Data LLLLLLLLLLLLLLLLLLLLLLLLLL

| Monitor Release: V2R1M3 Date: 2000.334

MAST: 00F9B8E8 PSA: 00F87000 CPU: 00F87000 SEST: 00F9BCE8 UNID: 00000000

| Verify that the monitor release is V2R1M3 and the date is 2000.334 or later.

5. To automatically reinstall and re-enable the monitor SVCs after a system IPL,make the following changes:

a. Add line 000600 in the following example to theSYS1.PARMLIB(COMMNDxx) data set. The SYS1.PARMLIB(COMMNDxx)data set contains the names of programs to start at IPL time, and line000600 installs and enables the ATC monitor SVCs.

000100 COM='MN JOBNAMES,T'

000110 COM='SET DIAG=01'

000200 COM='K M,AMRF=N'

000300 COM='K S,DEL=RD,SEG=20,CON=N,RNUM=20,RTME=1/2,MFORM=M,L=01'

000400 COM='S JES2,PARM='WARM,NOREQ''

000500 COM='S IRRDPTAB'

>000600 COM='S ATGOMNST'

000700 COM='S VTAM43P1,,,(LIST=15)'

000800 COM='S EZAZSSI,P=SPIMVSP1'

000900 COM='S STARTUP,M=STARTP1'


b. Add the following PROC to your SYS1.PROCLIB data set. A copy of thisPROC is located in 'hi_lev_qual.SATGSAMP(ATGXPSVC)' for your conven-ience.

//ATGOMNST PROC

//L

//L This is a cataloged proc that can be placed in SYS1.PROCLIB and

//L invoked at IPL time to install/enable the ATC monitor SVCs.

//L

//L The following line must go in the COMMNDxx member of SYS1.PARMLIB

//L that is used during IPL:

//L

//L COM='S ATGOMNST'

//L

//L Change the 1st 2 PARM operands to contain the 2 ATC SVC numbers

//L (in HEX). These should match the entries for ATGSVC2B and

//L ATGSVC4B you have in the ATGRDFLT member of the ATC REXX

//L (SATGEXEC) library.

//L

//L //INSTATC EXEC PGM=ATGOMNST,PARM=(FE,FF)

//L

//L If your users want COBOL testcases compiled with the

//L TEST (COUNT for OS/VS COBOL) compiler option and breakpointed

//L using the COBOL control card EXTPROGRAM-ID keyword to

//L be able to run without a monitor session, add the TESTOPT

//L keyword. See the User's Guide section titled

//L 'Instrumenting load modules without listings' for more

//L information.

//L

//L //INSTATC EXEC PGM=ATGOMNST,PARM=(FE,FF,TESTOPT)

//L

//L

//ATGOMNST EXEC PGM=ATGOMNST,PARM=(FE,FF)

//L

//L The following STEPLIB must contain ATGOMNST and ATGOMONS

//L and must be an authorized library.

//L

//STEPLIB DD DSN=LSTTOOL.TA.APF.LOAD,DISP=SHR

//SYSOUT DD SYSOUT=L

//SYSPRINT DD SYSOUT=L

//SYSUDUMP DD SYSOUT=L

c. Make the same changes to this PROCLIB member as you made to'hi_lev_qual.SATGSAMP(ATGXISVC)'.

6. Give the ATGOMNST-started task RACF access to the ATGOMNST andATGOMONS load modules.

Ensuring users have access to AMASPZAPUser access to the SPZAP service aid program (AMASPZAP) is required if the userchooses to place breakpoints in load modules directly (rather than in objectmodules) via the TOLOADDSN CA/DA/UTA control card keyword. If your usersneed to do this, ensure that they can execute the AMASPZAP program.


Editing the site default execComplete the following steps to edit 'hi_lev_qual.SATGEXEC(ATGRDFLT)' foryour installation:

1. Change all occurrences of ATC210.SHP to hi_lev_qual. For example, if youwant to use the high-level qualifier ATC.V2R1M0, change all occurrences ofATC210.SHP to ATC.V2R1M0.

2. In the execute step data entry for EXEJOBLB, change the nameLSTTOOL.TA.APF.LOAD to the name of the authorized library you used for theATGOMCMD and ATGOMVAR programs identified in “Setting up the author-ized data sets” on page 12.

3. Enter the ATC Monitor SVC numbers (in hexadecimal notation) in theATGSVC2B and ATGSVC4B entries.

4. For JCL generation, if your system requires it, change the *JOBLn lines. WhenJCL is created, these will be the first three lines of the JCL (for each respectivejob). You may also need to change all of the *JOBJL lines to specify any JEScontrol information required by your site. If your installation will primarily runPL/I test cases (instead of COBOL), change the EXMCTLTY line to P.

5. If your site requires a specification of the UNIT parameter (or other allocationparameters such as STORCLAS) on new or temporary data set allocations,then scan this EXEC for the word SPACE and update the allocation specifica-tions accordingly. In addition, scan the 'hi_lev_qual.SATGSLIB' data set forsimilar allocation parameters and make appropriate changes there too.

6. The Language Environment for MVS & VM 1.5 (or later) runtime library isrequired for some ATC batch jobs. If this library is not available through yoursystem's normal search path for load modules, you should enter its name in theATCJBLB2 line. (An example would be CEE.V1R5M0.SCEERUN.)

7. By setting the USEPRGNM variable setting to N, you can tell ATC not to gen-erate or build any data set names automatically.

8. If the USEPRGNM variable setting is Y, then you can tell ATC to generate orbuild each data set as either a sequential or a partitioned data set.

To generate a data set as a:

� Sequential data set, set the DSORG variable after the data set variable toSEQ

� Partitioned data set, set the DSORG variable after the data set variable toPDS

ATC will use the following forms to generate data set names:

� For sequential data sets:

'proj_qual.program_name.file_type'

For example: 'YOUNG.TEST.COB01.BRKTAB'

� For partitioned data sets:

'proj_qual.file_type(program_name)'

For example: 'YOUNG.TEST.BRKTAB(COB01)'


Installing optional featuresTo install the ATC optional features, you load the ATC data sets onto your systemusing the instructions in the Program Directory.

Copying ATC to system data setsYou can run the ATC user interface either stand-alone under ISPF option 6 or youcan include it into your system's standard ISPF concatenation. If you want to run itfrom your standard ISPF concatenation, either include the following data sets in theproper concatenations or copy the members to a data set allocated to that concat-enation.

Data set DD concatenation

hi_lev_qual.SATGEXEC SYSEXEC or SYSPROC

hi_lev_qual.SATGMLIB ISPMLIB

hi_lev_qual.SATGMOD ISPLLIB

hi_lev_qual.SATGPLIB ISPPLIB

hi_lev_qual.SATGSLIB ISPSLIB

hi_lev_qual.SATGTLIB ISPTLIB

To start ATC in this configuration, execute the ATGSTART exec.

Verifying the installationTo ensure that the ATC package has been installed correctly and to give you somefamiliarity with ATC if you are a new user, we recommend that you run the sampletest cases shipped with the package. For details, see Chapter 4, “ATC samples”on page 27, Chapter 6, “Coverage Assistant samples” on page 41, Chapter 11,“Distillation Assistant samples” on page 115, Chapter 16, “Unit Test Assistantsamples” on page 151, and Chapter 27, “Source Audit Assistant samples” onpage 271.


Chapter 3. Basic user setup

This chapter contains topics describing ATC customization procedures and Setupoptions. These topics will be of most interest to individuals who are new to ATC.

Modifying your ATC defaultsTypically, you do not have to perform any installation or customization procedures;however, if you want to change ATC user defaults, the ATC panels let you changeall of the user defaults provided in the site defaults. Using the panels, you canmodify your defaults in the following ways:

� Edit your defaults.� Reset your defaults to the system defaults.� Import defaults from a sequential data set.� Export defaults to a sequential data set.

Note: If you are changing from one release of ATC to another, it is recommendedthat you do a Defaults RESET (ATC option 0.2) and reenter any personal changes.

To start changing your ATC user defaults, complete the following steps:

1. Start ATC by selecting ISPF option 6 and entering:EX 'hi_lev_qual.SATGEXEC(ATGSTART)'

where:

hi_lev_qual is the MVS data set high-level qualifier under which ATC wasinstalled.

The first panel that you will see is the ATC Primary Option Menu shown inFigure 1.

Z [ ------------------------ ATC Primary Option Menu V2R1M3 -----------------------

Option ===>_

0 Defaults Manipulate ATC defaults

1 CA/DA/UTA Coverage, Distillation and Unit Test Assistant

2 SAA Source Audit Assistant

Enter X to Terminate

\ ]

Figure 1. ATC Primary Option Menu

Chapter 3. Basic user setup 19

2. To specify your ATC user default values, select option 0 from the ATC PrimaryOption Menu. This displays the Manipulate ATC Defaults panel shown inFigure 2.

Z [-------------------------- Manipulate ATC Defaults --------------------------

Option ===>_

1 EDIT Edit defaults

2 RESET Reset defaults to system defaults

3 IMPORT Import defaults from a sequential dataset

4 EXPORT Export defaults to a sequential dataset

Enter END to Terminate

Import | Export Dataset (Options 3 and 4 only):

data set name . . . .

\ ]

Figure 2. Manipulate ATC Defaults panel

You can change your ATC user defaults using the options and data set namefield on this panel. The options and field are as follows:

EDIT Edit your user defaults.

RESET Reset the user defaults to the system default values.

IMPORT Import previously exported default values from the dataset specified in data set name .

EXPORT Export the current default values to the data set specifiedin data set name .

Data set name Name of the data set that is the source or target of theimport or export operation, respectively.

The following topics describe editing and resetting your defaults to the systemdefaults in more detail.

Editing your user defaultsTo edit your user defaults:

1. Select option 1 from the Manipulate ATC Defaults panel. The scrollable panelshown in Figure 3 on page 22 is displayed.

2. If you choose, you can change the Project Qualifier value to the high-levelqualifier you want ATC to use to construct names for user and project datasets.

3. If you want ATC to generate or build any data set names automatically, makesure Use Pgm Name For File Name is set to Yes. ATC uses the Project Qual-ifier, the Program Name, and each data set's specified values for Type andDSORG to build names of the following forms:

� For sequential data sets:




� For partitioned data sets:



If No is specified for Use Pgm Name For File Name, ATC will not build orchange any data set names automatically.


Z [ -------------------------------- Edit Defaults --------------------------------

Command ===>

Enter END (to Exit and Save changes) or CANCEL (to Exit without saving)

------------------------------- General Defaults ------------------------------

Project Qualifier. . . . . YOUNG.SAMPLE

Use Pgm Name for File Name YES (Yes|No)

Program Name . . . . . . . COB01

JCL Output Dsn . . . . . . 'YOUNG.SAMPLE.JCL'

Type . . . . . . . . . . JCL

DSORG. . . . . . . . . . PDS (SEQ|PDS)

Alloc Parms. . . . . . . LRECL(80) RECFM(F B) BLKSIZE(0)

TRACKS SPACE(10 10)

1st JOBLIB Dsn . . . . . . 'ATC.V2R1M0.SATGMOD'

2nd Alternate JOBLIB Dsn .

3rd Alternate JOBLIB Dsn .

4th Alternate JOBLIB Dsn .



REXX Dsn . . . . . . . . . 'ATC.V2R1M0.SATGEXEC'

Sample Dsn . . . . . . . . 'ATC.V2R1M0.SATGSAMP'

Display Messages . . . . . I (S|E|W|R|I)

Log Messages . . . . . . . I (S|E|W|R|I)

Enable CA. . . . . . . . . YES (Yes|No)

Enable DA. . . . . . . . . NO (Yes|No)

Enable UTA . . . . . . . . NO (Yes|No)

Control File Dsn . . . . . 'YOUNG.SAMPLE.CACTL(COB01)'

Type . . . . . . . . . . CACTL

DSORG. . . . . . . . . . PDS (SEQ|PDS)

Alloc Parms. . . . . . . LRECL(255) RECFM(V B) BLKSIZE(0)

TRACKS SPACE(10 10)

DD Parms . . . . . . . . SPACE=(TRK,(2,2)),

DCB=(RECFM=VB,LRECL=255,BLKSIZE=0)

Type of Control File . . . COBOL (COBOL|PL/I|ASM)

-------------------------------- Setup Defaults -------------------------------

Jobcard Name . . . . . . . YOUNG

Jobcard Operands . . . . . (12345678),

YOUNG,NOTIFY=YOUNG,USER=YOUNG,

MSGCLASS=H,CLASS=A,REGION=32M

JES Control Cards. . . . .

Breakpoint Table Dsn . . . 'YOUNG.SAMPLE.COB01.BRKTAB'

Type . . . . . . . . . . BRKTAB

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(2 2)


DCB=(DSORG=PS,RECFM=FB,LRECL=256,BLKSIZE=0)

Debug Table Dsn. . . . . . 'YOUNG.SAMPLE.COB01.DBGTAB'

Type . . . . . . . . . . DBGTAB

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(2 2)



Variable Cntl Dsn. . . . . 'YOUNG.SAMPLE.COB01.VARCTL'

Type . . . . . . . . . . VARCTL

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


\ ]

Figure 3 (Part 1 of 3). ATC Defaults panel


Z [TRACKS SPACE(2 2)



SVC number for 2 byte BP . FE (in HEX)

SVC number for 4 byte BP . FF (in HEX)

Performance Mode . . . . . YES (Yes|No)

Debug Mode . . . . . . . . NO (Yes|No)

Frequency Count Mode . . . NO (Yes|No)

------------------------------- Monitor Defaults ------------------------------

Loadlib Dsn. . . . . . . . 'LSTTOOL.TA.APF.LOAD'




MSGCLASS=H,CLASS=A,REGION=32M,MSGLEVEL=(1,1)


Min Wait time to Write Buf 20 (1/100 secs)

Max Wait time to Write Buf 800 (1/100 secs)

Breakout Table Dsn . . . . 'YOUNG.SAMPLE.COB01.BRKOUT'

Type . . . . . . . . . . BRKOUT

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(3 3)



Variable Table Dsn . . . . 'YOUNG.SAMPLE.COB01.VARTAB'

Type . . . . . . . . . . VARTAB

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(3 3)



--------------------------- Coverage Report Defaults --------------------------

Combined Cntl Dsn. . . . . 'YOUNG.SAMPLE.CBCTL(COB01)'

Type . . . . . . . . . . CBCTL

DSORG. . . . . . . . . . PDS (SEQ|PDS)

Combined Breakout Dsn. . . 'YOUNG.SAMPLE.COB01.CMBOUT'

Type . . . . . . . . . . CMBOUT

DSORG. . . . . . . . . . SEQ (SEQ|PDS)






Report File Dsn. . . . . . 'YOUNG.SAMPLE.COB01.REPORT'

Summary File Dsn . . . . . 'YOUNG.SAMPLE.COB01.SUMMARY'

Report File Type . . . . REPORT

Summary File Type. . . . SUMMARY

DSORG. . . . . . . . . . SEQ (SEQ|PDS)

Alloc Parms. . . . . . . LRECL(133) RECFM(F B A) BLKSIZE(27930)

TRACKS SPACE(10 10)


DCB=(DSORG=PS,RECFM=FBA,LRECL=133,BLKSIZE=27930)

Summary Type . . . . . . . INTERNAL (Internal|External)

| Summary Assembler Stmts. . YES

\ ]



Z [ Summary PL/X Inline. . . . N (I|N)

Annotation Symbols . . . . :¬>V%@& (L for default)

Report User Options. . . . A (A|U)

Print Report File Dataset. YES (Yes|No)

-------------------------- Unit Test Report Defaults --------------------------

Variable Report Type . . . FULL (Full|Combine)

Variable ID Dsn. . . . . . 'YOUNG.SAMPLE.COB01.VARID'

Type . . . . . . . . . . VARID

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(2 2)


DCB=(DSORG=PS,RECFM=VB,LRECL=255,BLKSIZE=27998)

Variable Data Dsn. . . . . 'YOUNG.SAMPLE.COB01.VARDATA'

Type . . . . . . . . . . VARDATA

DSORG. . . . . . . . . . SEQ (SEQ|PDS)


TRACKS SPACE(2 2)


DCB=(DSORG=PS,RECFM=VB,LRECL=255,BLKSIZE=27998)

File Warp Control Dsn. . . 'YOUNG.SAMPLE.FWCTL(COB01)'

Type . . . . . . . . . . FWCTL

DSORG. . . . . . . . . . PDS (SEQ|PDS)

-------------------------- Targeted Summary Defaults --------------------------

Targeted Summary Ctl Dsn . 'YOUNG.SAMPLE.TARGCTL(COB01)'

Type . . . . . . . . . . TARGCTL

DSORG. . . . . . . . . . PDS (SEQ|PDS)

Targeted Sum. Report Dsn . 'YOUNG.SAMPLE.COB01.TARGREP'

Type . . . . . . . . . . TARGREP

DSORG. . . . . . . . . . SEQ (SEQ|PDS)

----------------------- Source Audit Assistant Defaults -----------------------






Programming Language . . . COBOL (ASM|COBOL|PL/I)

----------------------- SAA Comparison Analysis Defaults ----------------------

Change Validation Rpt Dsn. 'YOUNG.SAMPLE.COB01.CHNGREP'

Type . . . . . . . . . . CHNGREP

DSORG. . . . . . . . . . SEQ (SEQ|PDS)

Enable DBCS. . . . . . . . N (Y|N)

\ ]



Resetting your user defaults to the system defaultsTo reset your user defaults to the site defaults:

1. Select option 2 from the Manipulate ATC Defaults panel. This displays thepanel shown in Figure 4.

Z [ ---------------------- Reset Defaults to System Defaults ----------------------

Command ===>

Project Qualifier. . . . . YOUNG.SAMPLE

Program Name . . . . . . . COB01

Enter ENTER to Reset Defaults

Enter END to Cancel and Terminate

\ ]

Figure 4. Reset Defaults to System Defaults panel

The panel's fields are as follows:

Project Qualifier Specifies the qualifier to be used to construct filenames for user and project files.

Program Name Specifies the file_type qualifier to be used when filenames for user and project files. Use ProgramName for File Name is set to Yes.

2. If you want to reset all of your user defaults to the system defaults using theproject high-level qualifier and the program name specified in the panel, pressEnter. If you do not want to reset your defaults, press the End key (PF3) toreturn to the previous panel.

Accessing the Language Environment runtime libraryThe Language Environment for MVS & VM 1.5 (or later) runtime library is requiredfor some ATC functions. For batch jobs, if this library is not available through yoursystem's normal search path for load modules, then add this library name to theAlternate JOBLIB Dsn list in the ATC Defaults panel (see Figure 3 on page 22).

For the foreground function (only the Targeted Summary function, at this time), thislibrary must be available either through your system's normal search path for loadmodules or through a STEPLIB, TSOLIB, or ISPLLIB mechanism for your TSOsession. This runtime library is typically named CEE.V1R5M0.SCEERUN.


Starting the ATC ISPF interfaceTo start the ATC ISPF dialog, issue one of the following commands:

1. If your installation installed the ATC data sets into your normal logon proce-dure, issue this command from ISPF option 6:

ATGSTART common_parameters

2. If ATC was installed as a stand alone application, issue this command fromISPF option 6:

EX 'hi_lev_qual.SATGEXEC(ATGSTART)' 'common_parameters'

where common_parameters are optional and specify any of the parametersdescribed in Appendix F, “Parameters Common To Multiple Routines” on page 381(separated by blanks). Note that if any of these common_parameters are specified,these specifications are remembered by ATGSTART and become the default if theparameters are not specified on subsequent invocations of ATGSTART.


Chapter 4. ATC samples

ATC provides samples for Coverage Assistant, Distillation Assistant, Unit TestAssistant, and Source Audit Assistant. This section describes how to set up yoursample data sets before running the samples.

1. Allocate the sample data sets.

Allocate at least 10 tracks for each data set. Partitioned data sets should haveat least 10 blocks for the directory.

Table 1. CA, DA, and UTA data sets

Data set name LRECL BLKSIZE RECFM DSORG

prefix.SAMPLE.ASM 80 * FB PO

prefix.SAMPLE.ASMLST 133 forHigh LevelAssembler

* FBA/M PO

137 forHigh LevelAssembler

* VBA/M PO

121 forAssembler H

* FBA PO

prefix.SAMPLE.CACTL 255 * VB PO

prefix.SAMPLE.COBOL 80 * FB PO

prefix.SAMPLE.COBOLST 133 * FBA PO

121 for OS/VSCOBOL

12100 FBA PO

prefix.SAMPLE.COB03.MASTER 80 * FB PS

prefix.SAMPLE.FWCTL 255 * VB PO

prefix.SAMPLE.FWARPIN 80 * FB PS

prefix.SAMPLE.JCL 80 * FB PO

prefix.SAMPLE.OBJ 80 3200 FB PO

prefix.SAMPLE.PLI 80 * FB PO

| prefix.SAMPLE.PLILST| 132 for| VisualAge PL/I| *| VBA| PO

125 forOS PL/I orPL/I for MVS& VM

* VBA PO

prefix.SAMPLE.PLI02.MASTER 80 * FB PS

prefix.SAMPLE.RUNLIB 0 * U PO

prefix.SAMPLE.TARGCTL 255 * VB PO

prefix.SAMPLE.ZAPOBJ 80 3200 FB PO

Note: A value of * in the BLKSIZE column indicates that you can use any valid blocksize.

Chapter 4. ATC samples 27

2. Copy the following members from hi_lev_qual.SATGSAMP into the appropriatedata set (renaming the members as required). Only copy those members forthe functions and languages in which you are interested. The naming conven-tion shown below assumes that you will only select one language for eachfunction.

Table 2. SAA data sets

Data set name LRECL BLKSIZE RECFM DSORG

prefix.SAMPLE.NEW.COBOL 80 * FB PO

prefix.SAMPLE.OLD.COBOL 80 * FB PO

prefix.SAMPLE.SEEDLIST 255 * VB PO

Note: A value of * in the BLKSIZE column indicates that you can use any valid blocksize.

Table 3. CA COBOL sample

SATGSAMPmember name Your sample data set Description of member

ATGXCC1C prefix.SAMPLE.CACTL(COB01) CA control cards

ATGXGC1M prefix.SAMPLE.JCL(GCOB01) GO JCL, COBOL for MVS &VM

ATGXGC1O prefix.SAMPLE.JCL(GCOB01) GO JCL, OS/VS COBOL

ATGXGC12 prefix.SAMPLE.JCL(GCOB01) GO JCL, VS COBOL II

ATGXGC19 prefix.SAMPLE.JCL(GCOB01) GO JCL, COBOL for OS/390& VM

ATGXLC1M prefix.SAMPLE.JCL(LCOB01) Link JCL COBOL for MVS &VM

ATGXLC1O prefix.SAMPLE.JCL(LCOB01) Link JCL, OS/VS COBOL

ATGXLC12 prefix.SAMPLE.JCL(LCOB01) Link JCL, VS COBOL II

ATGXLC19 prefix.SAMPLE.JCL(LCOB01) Link JCL, COBOL for OS/390& VM

ATGXMCM prefix.SAMPLE.JCL(COMPILE) Compile JCL, COBOL forMVS & VM

ATGXMCO prefix.SAMPLE.JCL(COMPILE) Compile JCL, OS/VS COBOL

ATGXMC2 prefix.SAMPLE.JCL(COMPILE) Compile JCL, VS COBOL II

ATGXMC9 prefix.SAMPLE.JCL(COMPILE) Compile JCL, COBOL forOS/390 & VM

ATGXSC1A prefix.SAMPLE.COBOL(COB01A)

COBOL source codeATGXSC1B prefix.SAMPLE.COBOL(COB01B)

ATGXSC1C prefix.SAMPLE.COBOL(COB01C)

ATGXSC1D prefix.SAMPLE.COBOL(COB01D)


Table 4. CA PL/I sample


ATGXCP1C prefix.SAMPLE.CACTL(PLI01) CA control cards

| ATGXGP1V| prefix.SAMPLE.JCL(GPLI01)| GO JCL, VisualAge PL/I

ATGXGP1M prefix.SAMPLE.JCL(GPLI01) GO JCL, PL/I for MVS & VM

ATGXGP11 prefix.SAMPLE.JCL(GPLI01) GO JCL, PL/I 1.5.1


| ATGXLP1V| prefix.SAMPLE.JCL(LPLI01)| Link JCL, VisualAge PL/I

ATGXLP1M prefix.SAMPLE.JCL(LPLI01) Link JCL, PL/I for MVS & VM

ATGXLP11 prefix.SAMPLE.JCL(LPLI01) Link JCL, PL/I 1.5.1


| ATGXMPV| prefix.SAMPLE.JCL(COMPILE)| Compile JCL, VisualAge PL/I

ATGXMPM prefix.SAMPLE.JCL(COMPILE) Compile JCL, PL/I for MVS &VM

ATGXMP1 prefix.SAMPLE.JCL(COMPILE) Compile JCL, PL/I 1.5.1


ATGXSP1A prefix.SAMPLE.PLI(PLI01A)

PL/I source codeATGXSP1B prefix.SAMPLE.PLI(PLI01B)

ATGXSP1C prefix.SAMPLE.PLI(PLI01C)

ATGXSP1D prefix.SAMPLE.PLI(PLI01D)

Table 5. CA assembler sample


ATGXCA1C prefix.SAMPLE.CACTL(ASM01) CA control cards

ATGXGA1H prefix.SAMPLE.JCL(GASM01) GO JCL, Assembler H

ATGXGA1L prefix.SAMPLE.JCL(GASM01) GO JCL, High Level Assem-bler

ATGXLA1H prefix.SAMPLE.JCL(LASM01) Link JCL, Assembler H

ATGXLA1L prefix.SAMPLE.JCL(LASM01) Link JCL, High Level Assem-bler

ATGXMAH prefix.SAMPLE.JCL(COMPILE) Compile JCL, Assembler H

ATGXMAL prefix.SAMPLE.JCL(COMPILE) Compile JCL, High LevelAssembler

ATGXSA1A prefix.SAMPLE.ASM(ASM01A)

Assembler source codeATGXSA1B prefix.SAMPLE.ASM(ASM01B)

ATGXSA1C prefix.SAMPLE.ASM(ASM01C)

ATGXSA1D prefix.SAMPLE.ASM(ASM01D)


Table 6. DA COBOL sample


ATGXCC3D prefix.SAMPLE.CACTL(COB03) DA control cards

ATGXC3M prefix.SAMPLE.COB03.MASTER DA input master data set





ATGXLC3M prefix.SAMPLE.JCL(LCOB03) Link JCL, COBOL for MVS &VM








ATGXSC3 prefix.SAMPLE.COBOL(COB03) COBOL source code

Table 7. DA PL/I sample


ATGXCP2D prefix.SAMPLE.CACTL(PLI02) DA control cards

ATGXC3M prefix.SAMPLE.PLI02.MASTER DA input master data set

ATGXGP2M prefix.SAMPLE.JCL(GPLI02) GO JCL, PL/I for MVS & VM



ATGXLP2M prefix.SAMPLE.JCL(LPLI02) Link JCL, PL/I for MVS & VM



ATGXMPM prefix.SAMPLE.JCL(COMPILE) Compile JCL, PL/I for MVS &VM



ATGXSP2 prefix.SAMPLE.PLI(PLI02) PL/I source code


Table 8. UTA sample


ATGXCC2U prefix.SAMPLE.CACTL(COB02) UTA control cards





ATGXLC2M prefix.SAMPLE.JCL(LCOB02) Link JCL, COBOL for MVS &VM








ATGXSC2 prefix.SAMPLE.COBOL(COB02) COBOL source code

Table 9. UTA File Warp sample


ATGXFW prefix.SAMPLE.FWCTL(FWARP) UTA File Warp control cards

ATGXFWM prefix.SAMPLE.FWARPIN File Warp input data set

Table 10. SAA sample


ATGXDS1 prefix.SAMPLE.SEEDLIST(COB01) Seed list

ATGXS1NA prefix.SAMPLE.NEW.COBOL(COB01A)

New COBOL sourceATGXS1NB prefix.SAMPLE.NEW.COBOL(COB01B)

ATGXS1NC prefix.SAMPLE.NEW.COBOL(COB01C)

ATGXS1ND prefix.SAMPLE.NEW.COBOL(COB01D)

ATGXS1OA prefix.SAMPLE.OLD.COBOL(COB01A)

Old COBOL sourceATGXS1OB prefix.SAMPLE.OLD.COBOL(COB01B)

ATGXS1OC prefix.SAMPLE.OLD.COBOL(COB01C)

ATGXS1OD prefix.SAMPLE.OLD.COBOL(COB01D)


3. Edit the CACTL and JCL members.

a. Edit the CACTL members that you copied and change the high-level qual-ifier of each sample data set name to your TSO prefix.

b. Edit the JCL members that you copied and do the following:

1) Change the high-level qualifier of each sample data set name to yourTSO prefix.

2) Change the compiler and link-edit library data set names to match yoursystem's compiler and link-edit names.

3) Change the JOB cards to match your local job card conventions.


Part 3. Using Coverage Assistant

Part 3. Using Coverage Assistant 33


Chapter 5. Introduction

This chapter contains the following topics:

� What is Coverage Assistant?� What does CA require?� How does CA work?� Where can you get further details?

What is Coverage Assistant?Coverage Assistant (CA) contains programs that allow you to execute applicationprograms in a test environment and retrieve information that helps you determinewhich code statements have been executed. This process is called measuring testcase coverage.

CA supports applications generated by the following compilers and assemblers:

� IBM COBOL for OS/390 & VM 2.1 (5648-A25)� VisualAge COBOL Millennium Language Extensions for OS/390 & VM 1.0

(5648-MLE)� IBM COBOL for MVS & VM 1.2 (5688-197)� VisualAge COBOL Millennium Language Extensions for MVS & VM 1.0

(5654-MLE)� VS COBOL II Version 1 Release 4.0 (5688-022, 5688-023)� OS/VS COBOL Version 1 Release 2.4 (5740-CB1, 5740-LM1)� VisualAge PL/I Compiler Version 2 Release 2 (5655-B22)� IBM PL/I for MVS & VM 1.1.1 (5688-235)� VisualAge PL/I Millennium Language Extensions for MVS & VM 1.0

(5648-MLX)� OS PL/I Optimizing Compiler 2.3.0 (5668-909, 5668-910, 5668-911)� OS PL/I Optimizing Compiler 1.5.1 (5734-PL1, 5734-PL3, 5734-LM4,

5734-LM5)� High Level Assembler (HLASM) Version 1 Release 2 and 3 (5696-234)� High Assembler H (HASM) Version 2 (5668-962)

For each COBOL paragraph, PL/I procedure, ON-unit, Begin-block, or assemblerlisting, CA can provide you with:

� The percentage of statements executed and a list of unexecuted statements

� The percentage of conditional branches executed and a list of conditionalbranches that have not executed in both directions

� Annotated Listing report showing the execution status of each statement

In addition, Targeted Summary reports allow you to obtain similar information,which is “targeted” on specific statements of interest. You can specify a statementby its number, or you can specify all statements that reference specific COBOL orPL/I variables.

Chapter 5. Introduction to CA 35

CA has the following characteristics:

� Low overhead.

For a test case coverage run, CA typically adds very little to the execution timeof the program. CA inserts SVC instructions into the application objectmodules as breakpoints and then is given control by MVS when these SVCsare executed. Most breakpoints are removed after their first execution. Byusing this technique, the increase in test program execution time is minimal.

� Panel-driven user interface.

You can use an ISPF panel-driven interface to create JCL for executing CAprograms.

What does CA require?CA has the following requirements:

� CA runs under MVS. Detailed MVS system resource requirements for CA aredescribed in Appendix B, “ATC requirements and resources” on page 359. CAuses ISPF services to display dialogs and to produce the JCL to run the CAsteps.

� As part of its input, CA requires listings created by the application programcompilers and assemblers that it supports. These compilers and assemblersoffer options that allow you to include assembler statements in the listings. CAuses these statements to determine where to insert breakpoints. If the COBOLTEST option (COUNT for OS/VS COBOL) is used, compiler listings are notrequired unless an Annotated Listing or Targeted Summary report is desired.

� CA also requires the application program object modules or load modules asinput. CA creates copies of these object modules or load modules with break-points inserted into them.

For a description of how the CA authorized programs intercept breakpoints, see“Execution” on page 39. For CA program runtime library requirements, see“Accessing the Language Environment runtime library” on page 25. No change tothe runtime environment of the programs you are testing is required.


How does CA work?Running CA consists of the following steps. This list is an overview of the process.Each activity is described in more detail in topics that follow in this chapter.

Step 1 Setup

a. Compile the source code that you want to analyze, using therequired compiler options.

b. Generate CA JCL using the CA ISPF dialog:

1) Edit the CA control file.2) Create the Setup JCL.3) Create the monitor JCL.4) Create the report or summary JCL.

c. Edit the link-edit JCL to include the modified object modules, whichare created by the Setup step. Note that you can also instrumentload modules after your build process.

d. Edit the GO JCL (or program invocation) to point to the instru-mented load module from step 1c.

Step 2 Execution

a. Run the Setup JCL (created at step 1b2).b. Run the link-edit JCL (created at step 1c).c. Run the JCL to start a monitor session (created at step 1b3).d. Run your application using the load module(s) from step 2b.e. Stop the monitor session (with the ATGSTOP command).

Step 3 Report

a. Run the report or summary JCL (created at step 1b4).b. Run as many Targeted Summary reports as you want.

If you change your program and want to rerun the test cases, you must repeat step1a using the changed source code, and then complete steps 1b through 3a again.

Figure 5 on page 38 shows a diagram of the entire process.


Figure 5. CA—flow diagram. The asterisk (*) indicates that user program listings are notneeded for COBOL programs if the TEST (COUNT for OS/VS COBOL) compiler option isused and an Annotated Listing report and Targeted Summary report are not desired.


SetupCA Setup analyzes assembler statements included in the compiler or assembleroutput listings. From this analysis, CA determines where to insert breakpoints indisk-resident copies of the object or load modules you want to examine, and theninserts them.

To run Setup, you need:

1. Source/assembler listings of the object modules. For COBOL programs com-piled with the TEST (COUNT for OS/VS COBOL) compiler option, listings arenot needed for the Setup step.

2. The object modules or load modules you want to test.

The Setup step produces:

1. Modified test programs containing breakpoints

2. A file of breakpoint-related information (called a BRKTAB in this book) requiredfor the monitor program in the Execution step

ExecutionIf you instrumented object modules, you must link the modified object modules intoan executable load module.

Start a monitor session and run your test case programs. As breakpoints areencountered, the monitor gains control, updates test case coverage statistics, andthen returns control to your program. After your test cases have completed, stopthe monitor session. The results are written to a file called BRKOUT in this User'sGuide.

The monitor inserts reserved supervisor call (SVC) instructions as breakpoints andis given control by MVS when these SVC instructions are executed in a program.Using SVCs as breakpoints is the architected way to receive control from MVS, andrequires no modification to MVS. This technique is called user SVCs.

Two SVC instructions are used, one for two-byte instructions, and one for four- orsix-byte instructions. During installation, the monitor is installed as the handler forthe two SVC instructions used as breakpoints.


ReportThe CA report program uses the results from the monitor to produce a Summaryreport and an Annotated Listing report. You can print a summary report of overalltest case coverage and Annotated Listing report for each module tested. Thesereports are described at Chapter 8, “Coverage Assistant reports” on page 63.

To run reports you need:

1. The BRKTAB data set from the Setup step2. The BRKOUT data set from the Execution step3. Any listings you want to annotate

In addition to the basic CA reports, you can also produce targeted summaryreports, which allow you to target certain statements and/or COBOL or PL/I vari-ables. The format of a targeted Summary report is identical to the format of aSummary report, but the content is restricted to statements that you specify. (Youcan specify a statement number, or you can specify all statements that referencespecific COBOL or PL/I variables.)

To run Targeted Summary reports you need:

1. A control file that specifies the statements and/or COBOL or PL/I variables ofinterest

2. The BRKTAB data set from the Setup step

3. The BRKOUT data set from the Execution step

4. The listings for any program called out in the control cards

Where can you get further details?Refer to the following sections for additional information.

For information about... See...

Installing ATC on your system Chapter 2, “System installation” onpage 7

Samples of CA test case coverage,including sample reports

Chapter 6, “Coverage Assistant samples”on page 41

Editing the CACTL file, which containsthe names of the listing data sets

Chapter 7, “Editing the CoverageAssistant control file” on page 61

Setting up the table of breakpoints fromthe listings

Chapter 22, “CA, DA, and UTA setup” onpage 211

Starting the monitor session and runningtest cases on your programs

Chapter 23, “Monitor execution” onpage 227

Reports on the test run Chapter 8, “Coverage Assistant reports”on page 63

Using CA in a large project environment Chapter 9, “Using Coverage Assistant ina large project environment” on page 99

Commands that control the monitorprogram

Chapter 24, “Monitor commands” onpage 239

System resources needed by CA Appendix B, “ATC requirements andresources” on page 359


Chapter 6. Coverage Assistant samples

This section describes samples of CA test case coverage support using examplesprovided with the ATC package.

CA provides statistics on each program area (PA) in your programs. A PA can beany of the following:

� A COBOL paragraph� A PL/I external or internal procedure, an ON-unit, or a Begin-block� An assembler listing

CA does not have to examine all object modules in your program. You can selectwhich areas of the program you want to test. You can also test multiple programs(load modules) simultaneously.

Running the samples will generate a summary of test case coverage and Anno-tated Listing reports for the following COBOL, PL/I, and assembler programs:

� COB01 (COBOL sample)� PLI01 (PL/I sample)� ASM01 (assembler sample)

A flow diagram of the steps required to run these samples is shown in Figure 6 onpage 42. The names in the steps are the member names of the JCL executed forthe step.

The following CA samples use the ATC ISPF dialog to create the JCL to run theCA steps. The ATC ISPF dialog is provided as an aid in creating the JCL. Oncethe JCL is created for a test environment, it does not have to be recreated from thedialog. In a typical user test environment, the creation of the JCL can be incorpo-rated into the user's procedures. You do not have to use the ISPF dialog to useCA. For information on integrating the creation and running of the CA JCL, seeChapter 9, “Using Coverage Assistant in a large project environment” on page 99.

Before proceeding with the rest of this chapter, see Chapter 4, “ATC samples” onpage 27 for information on what data sets you need to create and what membersyou need to copy from hi_lev_qual.SATGSAMP first.

These samples describe instrumenting object modules from listings. For informa-tion on instrumenting load modules, see “Instrumenting load modules using listings”on page 219. If listings are not available and the COBOL TEST option can beused, see “Instrumenting load modules without listings” on page 220.

Chapter 6. CA samples 41

Figure 6. Sample run—flow diagram

Note: The JCL member names for the steps, such as SCOB01, depend on thetest case you are running. For example, the Setup JCL for the PLI01 test casewould be SPLI01.


COBOL summary of test case coverageTo produce a summary for COB01, perform the following steps. Steps 2a through6 are described in more detail in topics that follow in this chapter.

1. Compile the COBOL source you want to test. This produces listings thatinclude the assembler statements needed by CA.

Make sure to use the compiler options specified in “Setup” on page 211.

2. Start the ATC ISPF dialog by entering the following from ISPF option 6:

EX 'hi_lev_qual.SATGEXEC(ATGSTART)'

The ATC Primary Option Menu is displayed (shown in Figure 1 on page 19).

a. Edit the CA control file.

Verify that the control file includes the listings of the object modules youwant to test.

b. Create the Setup JCL.

Create the JCL that enables the Setup job to produce a file containingbreakpoint data and to instrument programs.

c. Create the monitor JCL.

Create the JCL to start a monitor session.

d. Create the Summary report JCL.

Create the JCL to produce the test case coverage summary after COB01has executed.

3. End the ATC ISPF dialog by pressing the End key (PF3) on the ATC PrimaryOption Menu.

4. Edit the JCL to link the modified object modules.

After the Setup step, you must link the modified object modules into an execut-able program you can test. Edit the link JCL and specify the library that willcontain the modified object modules for the OBJECT ddname and the librarythat will contain the modified load module for the SYSLMOD ddname.

5. Edit the JCL to run the GO step.

Edit the JCL to run your program. Specify the same modified load module asin step 4.

6. Execute the JCL.

Execute the created JCL files for COB01 in the correct order. (This order isshown in “Execute the JCL” on page 48.)


Figure 7 shows a sample Summary report. For details about the informationincluded in the report, see “Summary report” on page 67.

1 LLLLLLLLL CA SUMMARY: PROGRAM AREA DATA LLLLLLLL

0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:

0 |<-- PROGRAM IDENTIFICATION -->|

| | | STATEMENTS: | BRANCHES: |

| PA LOAD MOD PROCEDURE | LISTING NAME | TOTAL EXEC % | CPATH TAKEN % |

----------------------------------------------------------------------------------------------------------------------

1 COB01 PROG YOUNG.SAMPLE.COBOLST(COB01A) 6 6 100.0

2 PROGA 5 4 80.0

3 PROCA 1 0 0.0

4 LOOP1 3 3 100.0

5 LOOP2 2 2 100.0

6 COB01 PROGB YOUNG.SAMPLE.COBOLST(COB01B) 6 5 83.3

7 PROCB 1 1 100.0

8 LOOP1 3 3 100.0

9 COB01 PROGC YOUNG.SAMPLE.COBOLST(COB01C) 5 5 100.0

10 PROCC 3 2 66.7

11 LOOP1 4 3 75.0

12 LOOP2 2 2 100.0

13 COB01 PROGD YOUNG.SAMPLE.COBOLST(COB01D) 4 0 0.0

14 PROCD 1 0 0.0

15 LOOP1 1 0 0.0

----------------------------------------------------------------------------------------------------------------------

Summary for all PAs: 47 36 76.6 0 0 100.0

1 LLLLLLLLL CA SUMMARY: UNEXECUTED CODE LLLLLLLL

0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:


| | |

| PA LOAD MOD PROCEDURE | LISTING NAME | start end start end start end

----------------------------------------------------------------------------------------------------------------------

2 COB01 PROGA YOUNG.SAMPLE.COBOLST(COB01A) 59 59

3 PROCA 69 69

6 COB01 PROGB YOUNG.SAMPLE.COBOLST(COB01B) 41 41

10 COB01 PROCC YOUNG.SAMPLE.COBOLST(COB01C) 47 47

11 LOOP1 56 56

13 COB01 PROGD YOUNG.SAMPLE.COBOLST(COB01D) 33 38

14 PROCD 42 42

15 LOOP1 46 46

----------------------------------------------------------------------------------------------------------------------

1 LLLLLLLLL CA SUMMARY: BRANCHES THAT HAVE NOT GONE BOTH WAYS LLLLLLLL

0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:


| | |

| PA LOAD MOD PROCEDURE | LISTING NAME | stmt stmt stmt stmt stmt

----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------

Figure 7. Summary report for COB01


Compile the source code1. Edit the sample compile JCL that was copied from hi_lev_qual.SATGSAMP so

that it will run on your system.

a. Change the job card to match your system requirements.

b. Update the compiler data set names to match your local compiler data setnames.

c. Update the sample data set names to match your sample data set names.

d. Un-comment the COB01 member names.

2. Execute the JCL.

3. Make sure that all steps run with a return code of zero and that the listings andobject modules were created.

Edit the CA control fileCA uses assembler statements from the compiler listings to determine where toinsert breakpoints. You supply the names of the listing files in the CA control file(CACTL). “Setup” on page 211.

The CACTL control file for the COBOL summary example is shown in Figure 8 onpage 46. This example shows how to instrument object modules.

To edit the CACTL for the COB01 summary example:

1. Select option 1 from the ATC Primary Option Menu.

The Coverage, Distillation, and Unit Test Assistant panel is displayed.

2. Select option 1.

The Work with the CA/DA/UTA Control File panel is displayed.

3. Specify the following:

Use Program Name for File Name YES

Program Name COB01

Listing Type COBOL

An ISPF edit session for the CA control file you requested is displayed.

The data in the control file consists of the following:

� The type of listing file (COBOL)� Names of the listing files for the programs you want to test� Names of the load modules that contain the code of each listing� Copy to/from information for making copies of the object modules into

which the breakpoints are inserted

If the control file you requested did not previously exist, it is created from asample template containing comments, which help you enter the appropriateinformation in the fields.

4. Verify that the listing file names and the copy to/from object module names arecorrect. Typically these will be the same as shown in Figure 8 on page 46except that your TSO prefix is used as each data set's high-level qualifier.

5. Press the End key (PF3) to terminate the edit session.


For more detailed information, see Chapter 7, “Editing the Coverage Assistantcontrol file” on page 61.

Defaults ListDsn=YOUNG.SAMPLE.COBOLST(L),

LoadMod=COB01,

FromObjDsn=YOUNG.SAMPLE.OBJ,

ToObjDsn=YOUNG.SAMPLE.ZAPOBJ

COBOL ListMember=COB01A

COBOL ListMember=COB01B

COBOL ListMember=COB01C

COBOL ListMember=COB01D

Figure 8. Control file for COB01

Create Setup JCLBefore the COB01 program can be monitored, CA must insert breakpoints into thetest program. CA does this using the Setup JCL.

When you execute the Setup JCL, the CA Setup program analyzes the assemblerstatements in the compiler listings and creates a table containing breakpoint data(address, op code, and so on). User SVC instructions are inserted for theinstructions at the breakpoints in the instrumented object modules or load modules.If you instrumented object modules, you then link these modified object modulesinto a modified COB01 load module for CA to use.

To create the Setup JCL:



2. Select option 2.

The Create JCL for Setup panel is displayed. You create the JCL for the Setupof COB01 from this panel.

All of the default values on this panel are correct for the COB01 example. Thedefaults will usually be correct for your test coverage run. The only field thatyou may need to change is the Program Name field.

3. If necessary, change the program name to COB01.

4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername SCOB01.

5. Press the End key (PF3) to exit the panel.

For more detailed information, see Chapter 22, “CA, DA, and UTA setup” onpage 211.


Create JCL to start a monitor sessionJCL is required to start a CA monitor session.

To create the JCL to start a monitor session:


The Coverage, Distillation and Unit Test Assistant panel is displayed.

2. Select option 3.

The Create JCL to Start the Monitor panel is displayed. You create the JCL tostart a CA monitor session for COB01 from this panel.


4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername XCOB01.


Use the monitor JCL to start a monitor session before you run your test caseprogram. Note that you can perform CA execution on a system other than theone on which you have stored the listing.

For more detailed information, see Chapter 23, “Monitor execution” on page 227.

Create JCL for a Summary reportJCL is required to generate a Summary report.

To create the Summary report JCL:



2. Select option 4.

The Coverage Reports panel is displayed.

3. Select option 1.

The Create JCL for Summary report panel is displayed. You create the JCL forgenerating the COB01 Summary report from this panel.

4. If necessary, change Program Name to COB01.

5. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername TCOB01.


For more detailed information, see “Summary report” on page 67.


Edit JCL to link the modified object modulesYou must link the modified object modules (modified by the Setup step) into anexecutable program for testing. Edit the sample link-edit JCL that was copied fromhi_lev_qual.SATGSAMP so that it will run on your system, use your local librarynames and your sample data set names.

Edit JCL to run the GO stepEdit the sample GO JCL that was copied from hi_lev_qual.SATGSAMP so that itwill run on your system, use your local library names and your sample data setnames.

Execute the JCLWhen you have created all of the COB01 JCL, you can run the COB01 summaryexample by executing the following functions in the order listed. To see a flowdiagram of these steps, go to Figure 6 on page 42.

1. Compile

Performs the compile step. All JCL steps should complete with condition code0.

2. SCOB011

Performs the Setup step. All JCL steps should complete with condition code 0.

3. LCOB012

This links the object modules that were modified with breakpoints in the Setupstep into the COB01 load module.

4. XCOB011

Starts the monitor. All JCL steps should complete with condition code 0.

5. GCOB012

Runs sample program COB01. COB01 runs to completion with condition code0.

6. ATGSTATS3

Displays statistics with the ATGSTATS command. You should see a nonzeroEVNTS count in the TOTALS line. (This is an optional step for illustrative pur-poses.)

7. ATGSTOP3

Stops the monitor session. CA writes the statistics to disk.

1 JCL created from the panels and put into the JCL library.

2 JCL supplied with the installation materials in hi_lev_qual.SATGSAMP.

3 Monitor commands can be issued from either the Control the CA/DA/UTA Monitor panel or the TSO command processor (ISPFoption 6) by entering:

EX 'hi_lev_qual.SATGEXEC(cacmd)'

where cacmd is the command issued (such as, ATGSTATS, ATGSTOP, and so on).


8. TCOB011

Creates the summary of COB01. The summary is in data setproj_qual.COB01.SUMMARY.

COBOL Annotated Listing reportsTo produce an annotated COBOL listing of COB01, perform the following steps.Steps 2a through 6 are described in more detail in topics that follow in thischapter. This procedure is similar to the one described in “COBOL summary oftest case coverage” on page 43, except that a Summary report and an AnnotatedListing reports are created in this case.

1. Compile the COBOL source you want to test. This produces listings thatinclude the assembler statements needed by CA.




The ATC Primary Option Menu is displayed (shown in Figure 1 on page 19).

a. Edit the CA control file.

Verify that the control file includes the listings of the object modules youwant to test.


Create the JCL that enables you to produce a file that contains breakpointdata and that modifies copies of your object modules by inserting break-points.

c. Create the JCL to start a monitor session.

d. Create the JCL for an Annotated Listing report.

Create the JCL to produce the Annotated Listing report after COB01 hasexecuted.



After the Setup step, and before starting the monitor, you must link the modifiedobject modules into an executable program you can test. Edit the link JCL andspecify the library that will contain the modified object modules for the OBJECTddname and the library that will contain the modified load module for theSYSLMOD ddname.



6. Execute the JCL.



If you want more information on some or all of the modules that have been tested,you can create an Annotated Listing report of the COBOL listing. This listing con-tains information about each breakpoint. To the right of each statement number,one of the following symbols is shown to indicate the results of the execution of thatstatement:

: Instruction has executed.

¬ Instruction has not executed.

Figure 9 shows a sample Annotated Listing report.

LINEID PL SL ----+-LA-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|

000001 L COB01A - COBOL EXAMPLE FOR CA

000002

000003 IDENTIFICATION DIVISION.

000004 PROGRAM-ID. COB01A.

000005 LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

000006 L L

000007 L LICENSED MATERIALS - PROPERTY OF IBM L

000008 L L

000009 L 5655-B97 L

000010 L L

000011 L (C) COPYRIGHT IBM CORP. 1997, 1999 ALL RIGHTS RESERVED L

000012 L L

000013 L US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR L

000014 L DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM L

000015 L CORP. L

000016 L L

000017 L L


000019

000020 ENVIRONMENT DIVISION.

000021

000022 DATA DIVISION.

000023

000024 WORKING-STORAGE SECTION.

000025 01 TAPARM1 PIC 99 VALUE 5.


000027 01 COB01B PIC X(6) VALUE 'COB01B'.

000028 01 P1PARM1 PIC 99 VALUE 0.

000029

000030 01 TASTRUCT.

000031 05 LOC-ID.

000032 10 STATE PIC X(2).

000033 10 CITY PIC X(3).

000034 05 OP-SYS PIC X(3).

000035

000036 PROCEDURE DIVISION.

000037

000038 L THE FOLLOWING ALWAYS PERFORMED

000039

000040 PROG.

000041 L ACCESS BY TOP LEVEL QUALIFIER

000042 : MOVE 'ILCHIMVS' TO TASTRUCT

000043

000044 L ACCESS BY MID LEVEL QUALIFIERS

000045 : MOVE 'ILSPR' TO LOC-ID

000046 : MOVE 'AIX' TO OP-SYS

000047

Figure 9 (Part 1 of 2). COBOL Annotated Listing report


000048 L ACCESS BY LOW LEVEL QUALIFIERS

000049 : MOVE 'KY' TO STATE

000050 : MOVE 'LEX' TO CITY

000051 : MOVE 'VM ' TO OP-SYS

000052 .

000053

000054 PROGA.

000055 : PERFORM LOOP1 UNTIL TAPARM1 = 0

000056

000057 : IF TAPARM2 = 0 THEN

000058 L PROCA NOT EXECUTED

000059 ¬ 1 PERFORM PROCA.

000060

000061

000062 : PERFORM LOOP2 UNTIL TAPARM2 = 0

000063 .

000064 : STOP RUN

000065 .

000066

000067 PROCA.


000069 ¬ MOVE 10 TO P1PARM1

000070 .

000071 LOOP1.

000072 : IF TAPARM1 > 0 THEN

000073 : 1 SUBTRACT 1 FROM TAPARM1.

000074 : CALL 'COB01B'

000075 .

000076 LOOP2.

000077 : IF TAPARM2 > 0 THEN


000079


Compile the test caseThis step is identical to the corresponding procedure for Summary reports at“Compile the source code” on page 45.

Edit the CA control fileThis step is identical to the corresponding procedure for summary reports at “Editthe CA control file” on page 45.

Create Setup JCLThis step is identical to the corresponding procedure for summary reports at“Create Setup JCL” on page 46.

Create JCL to start a monitor sessionThis step is identical to the corresponding procedure for summary reports at“Create JCL to start a monitor session” on page 47.


Create JCL for an Annotated Listing reportTo create the Annotated Listing report JCL:



2. Select option 4.

The Coverage Reports panel is displayed.

3. Select option 2.

The Create JCL for Summary and Annotation Report panel is displayed. Youcreate the JCL for printing the Annotated Listing report (along with a summary)for COB01 from this panel.


5. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername RCOB01.


For more detailed information, see “Annotated Listing report” on page 77.

Edit JCL to link the modified object modulesThis step is identical to the corresponding procedure for summary reports at “EditJCL to link the modified object modules” on page 48.

Edit JCL to run GO stepThis step is identical to the corresponding procedure for summary reports at “EditJCL to run the GO step” on page 48.

Execute the JCLWhen you have created all of the COB01 JCL, you can run the COB01 example byexecuting the following JCL in the order listed. See Figure 6 on page 42 for a flowdiagram of these steps.

1. Compile

Performs the compile step. All JCL steps should complete with condition code0.

2. SCOB014


3. LCOB015

This links the object modules that were modified with breakpoints during theSetup step into the COB01 load module.




4. XCOB014

Starts the monitor. All JCL steps should complete with condition code 0.

5. GCOB015


6. ATGSTATS6

Displays statistics with the ATGSTATS command. You should see a nonzeroEVNTS count in the TOTALS line. (This is an optional step for illustrative pur-poses.)

7. ATGSTOP6

Stops the monitor session. CA writes the statistics to disk.

8. RCOB014

Creates the Annotated Listing report (and Summary report) of COB01. Thereport is in data set proj_qual.COB01.REPORT.

PL/I summary of test case coverageTo produce a Summary report for PLI01, follow the same steps as those describedin “COBOL summary of test case coverage” on page 43, except use PLI01 as thesample name.

Figure 10 on page 54 shows a sample Summary report. For details about theinformation included in the report, see “Summary report” on page 67.






0 DATE: 07/22/1999

TIME: 12:29:55

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 PLI01 PLI01A YOUNG.SAMPLE.PLILST(PLI01A) 9 9 100.0

2 PROC2A 2 0 0.0

3 PLI01 PLI01B YOUNG.SAMPLE.PLILST(PLI01B) 11 8 72.7

4 PROC1 2 2 100.0

5 PLI01 PLI01C YOUNG.SAMPLE.PLILST(PLI01C) 7 4 57.1

6 PROC1 4 3 75.0

7 PLI01 PLI01D YOUNG.SAMPLE.PLILST(PLI01D) 2 0 0.0

8 PROC1 4 0 0.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 07/22/1999

TIME: 12:29:55

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

2 PLI01 PROC2A YOUNG.SAMPLE.PLILST(PLI01A) 17 18

3 PLI01 PLI01B YOUNG.SAMPLE.PLILST(PLI01B) 9 9 15 16

5 PLI01 PLI01C YOUNG.SAMPLE.PLILST(PLI01C) 6 6 10 11

6 PROC1 16 16

7 PLI01 PLI01D YOUNG.SAMPLE.PLILST(PLI01D) 3 11

8 PROC1 6 10

----------------------------------------------------------------------------------------------------------------------


0 DATE: 07/22/1999

TIME: 12:29:55

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------

Figure 10. Summary report for PLI01

Figure 11 shows a sample CA control file for PLI01.

Defaults ListDsn=YOUNG.SAMPLE.PLILST(L),

LoadMod=PLI01,



PL/I ListMember=PLI01A

PL/I ListMember=PLI01B

PL/I ListMember=PLI01C

PL/I ListMember=PLI01D

Figure 11. Control file for PLI01


PL/I Annotated Listing reportTo produce a PL/I Annotated Listing report of PLI01, follow the same steps asthose described in “COBOL Annotated Listing reports” on page 49, except usePLI01 as the sample name.

Figure 12 shows a sample Annotated Listing report for PLI01.

STMT LEV NT

1 0 PLI01A:PROC OPTIONS(MAIN); /L PL/I CA TESTCASE L/

/LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL/

/L L/

/L Licensed Materials - Property of IBM L/

/L L/

/L 5655-B97 L/

/L L/

/L (C) Copyright IBM Corp. 1997, 1999 All Rights Reserved L/

/L L/

/L US Government Users Restricted Rights - Use, duplication or L/

/L disclosure restricted by GSA ADP Schedule Contract with IBM Corp.L/

/L L/


2 1 0 DCL EXPARM1 FIXED BIN(31) INIT(5);


4 1 0 DCL PARM2 FIXED BIN(31) INIT(2);

5 1 0 DCL PLI01B EXTERNAL ENTRY; /L L/

6: 1 0 DO WHILE (EXPARM1 > 0); /L THIS DO LOOP EXECUTED 5 TIMESL/

7: 1 1 EXPARM1 = EXPARM1 -1; /L L/

8: 1 1 CALL PLI01B(PARM2); /L PLI01B CALLED 5 TIMES L/

9: 1 1 END;

10: 1 0 IF (EXPARM2 = 0) THEN /L THIS BRANCH ALWAYS TAKEN L/

CALL PROC2A(EXPARM2); /L PROC2A NEVER CALLED L/

11: 1 0 DO WHILE (EXPARM2 > 0); /L DO LOOP EXECUTED TWICE L/

12: 1 1 EXPARM2 = EXPARM2 - 1;

13: 1 1 END;

14: 1 0 RETURN;

15 1 0 PROC2A: PROCEDURE(P1PARM1); /L THIS PROCEDURE NEVER EXECUTED L/

16 2 0 DCL P1PARM1 FIXED BIN(31);

17¬ 2 0 P1PARM1 = 10;

18¬ 2 0 END PROC2A;

19 1 0 END PLI01A;

Figure 12. PL/I Annotated Listing report

Assembler summary of test case coverageTo produce a Summary report for ASM01, follow the same steps as thosedescribed in “COBOL summary of test case coverage” on page 43, except useASM01 as the sample name.

Figure 13 on page 56 shows a sample Summary report. For details about theinformation included in the report, see “Summary report for assembler” on page 74.



0 DATE: 09/19/2000

TIME: 06:08:26

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 ASM01L TEST2 YOUNG.SAMPLE.ASMLST(ASM01AL) S 41 31 75.6

2 ASM01L TEST2B YOUNG.SAMPLE.ASMLST(ASM01BL) S 45 39 86.7

3 ASM01L TEST2C YOUNG.SAMPLE.ASMLST(ASM01CL) S 39 32 82.1

4 ASM01L TEST2D YOUNG.SAMPLE.ASMLST(ASM01DL) S 25 0 0.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 09/19/2000

TIME: 06:08:26

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

1 ASM01L TEST2 YOUNG.SAMPLE.ASMLST(ASM01AL) 000056 000062 000086 0000A0

2 ASM01L TEST2B YOUNG.SAMPLE.ASMLST(ASM01BL) 000050 00005A 000078 000082

3 ASM01L TEST2C YOUNG.SAMPLE.ASMLST(ASM01CL) 000034 00003A 000050 00005A 000092 000098

4 ASM01L TEST2D YOUNG.SAMPLE.ASMLST(ASM01DL) 000000 000000 000016 00006C

----------------------------------------------------------------------------------------------------------------------


0 DATE: 09/19/2000

TIME: 06:08:26

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------

Figure 13. Summary report for ASM01

Figure 14 shows a sample CA control file for ASM01.

Defaults ListDsn=YOUNG.SAMPLE.ASMLST(L),

LoadMod=ASM01,



ASM ListMember=ASM01A

ASM ListMember=ASM01B

ASM ListMember=ASM01C

ASM ListMember=ASM01D

Figure 14. Control file for ASM01


Assembler Annotated Listing reportTo produce an assembler Annotated Listing report of ASM01, follow the samesteps as those described in “COBOL Annotated Listing reports” on page 49, exceptuse ASM01 as the sample name.

In addition to the annotation symbols used for COBOL and PL/I, the followingsymbols are used:

@ Data area in the assembler Annotated Listing report

% Unconditional branch that has been executed in the assembler Anno-tated Listing report

Figure 15 shows a sample Annotated Listing report for ASM01.

Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R2.0 1999/07/22 08.58

1 LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL 00000100

2 L L 00000200

3 L LICENSED MATERIALS - PROPERTY OF IBM L 00000300

4 L L 00000400

5 L 5655-B97 L 00000504

6 L L 00000600

7 L (C) COPYRIGHT IBM CORP. 1997, 1999 ALL RIGHTS RESERVED L 00000706

8 L L 00000800

9 L US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR L 00000900

10 L DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM L 00001000

11 L CORP. L 00001100

12 L L 00001200

13 L L 00001300



16 L L 00001600

17 L CA ASSEMBLER TESTCASE. L 00001702

18 L L 00001800


000000 20 TEST2 CSECT , 01S0001 00002000

000000 21 @MAINENT DS 0H 01S0001 00003000

R:F 00000 22 USING L,@15 01S0001 00004000

000000 47F0 F016 00016 23% B @PROLOG 01S0001 00005000

000004 10 24@ DC AL1(16) 01S0001 00006000

000005 E3C5E2E3F2404040 25@ DC C'TEST2 97.295' 01S0001 00007000

26 DROP @15 00008000

000015 00

000016 90EC D00C 0000C 27:@PROLOG STM @14,@12,12(@13) 01S0001 00009000

00001A 18CF 28: LR @12,@15 01S0001 00010000

00000 29 @PSTART EQU TEST2 01S0001 00011000

R:C 00000 30 USING @PSTART,@12 01S0001 00012000

00001C 50D0 C0B0 000B0 31: ST @13,@SA00001+4 01S0001 00013000

000020 41E0 C0AC 000AC 32: LA @14,@SA00001 01S0001 00014000

000024 50E0 D008 00008 33: ST @14,8(,@13) 01S0001 00015000

000028 18DE 34: LR @13,@14 01S0001 00016000

35 L DO WHILE(EXPARM1>0); /L THIS DO LOOP EXECUTED 5 TIMES L/ 00017000

00002A 47F0 C042 00042 36% B @DE00006 01S0006 00018000

00002E 37 @DL00006 DS 0H 01S0007 00019000

38 L EXPARM1 = EXPARM1 - 1; /L L/ 00020000

00002E 5810 C100 00100 39: L @01,EXPARM1 01S0007 00021000

000032 0610 40: BCTR @01,0 01S0007 00022000

000034 5010 C100 00100 41: ST @01,EXPARM1 01S0007 00023000

42 L CALL TEST2B(PARM2); /L TEST2B CALLED 5 TIMES L/ 00024000

000038 58F0 C0F8 000F8 43: L @15,@CV00063 01S0008 00025000

00003C 4110 C0A4 000A4 44: LA @01,@AL00002 01S0008 00026000

000040 05EF 45% BALR @14,@15 01S0008 00027000

46 L END; 01S0009 00028000

Figure 15 (Part 1 of 3). Assembler Annotated Listing report


000042 5800 C100 00100 47:@DE00006 L @00,EXPARM1 01S0009 00029000

000046 1200 48: LTR @00,@00 01S0009 00030000

000048 4720 C02E 0002E 49: BP @DL00006 01S0009 00031000

50 L IF (EXPARM2 = 0) THEN /L THIS BRANCH ALWAYS TAKEN L/ 00032000

00004C 5810 C104 00104 51: L @01,EXPARM2 01S0010 00033000

000050 1211 52: LTR @01,@01 01S0010 00034000

000052 4770 C06C 0006C 53: BNZ @RF00010 01S0010 00035000

54 L CALL PROC1(EXPARM2); /L PROC1 NEVER CALLED L/ 00036000

000056 4110 C0A8 000A8 55¬ LA @01,@AL00003 01S0011 00037000

00005A 45E0 C086 00086 56¬ BAL @14,PROC1 01S0011 00038000

57 L DO WHILE(EXPARM2>0); /L DO LOOP EXECUTED TWICE L/ 00039000

00005E 47F0 C06C 0006C 58¬ B @DE00012 01S0012 00040000

000062 59 @DL00012 DS 0H 01S0013 00041000

60 L EXPARM2 = EXPARM2 - 1; 01S0013 00042000

000062 5820 C104 00104 61: L @02,EXPARM2 01S0013 00043000

000066 0620 62: BCTR @02,0 01S0013 00044000

000068 5020 C104 00104 63: ST @02,EXPARM2 01S0013 00045000

64 L END; 01S0014 00046000

00006C 5830 C104 00104 65:@DE00012 L @03,EXPARM2 01S0014 00047000

000070 1233 66: LTR @03,@03 01S0014 00048000

000072 4720 C062 00062 67: BP @DL00012 01S0014 00049000

68 L RETURN CODE(0); 01S0015 00050000

000076 1FFF 69: SLR @15,@15 01S0015 00051000

000078 58D0 D004 00004 70: L @13,4(,@13) 01S0015 00052000

00007C 58E0 D00C 0000C 71: L @14,12(,@13) 01S0015 00053000

000080 980C D014 00014 72: LM @00,@12,20(@13) 01S0015 00054000

000084 07FE 73% BR @14 01S0015 00055000

74 L END TEST2; 01S0020 00056000

75 LPROC1: 01S0016 00057000

76 L PROCEDURE(P1PARM1); /L THIS PROCEDURE NEVER EXECUTED L/ 00058000

000086 90EC D00C 0000C 77¬PROC1 STM @14,@12,12(@13) 01S0016 00059000

00008A D203 C0F4 1000 000F4 00000 78¬ MVC @PC00002(4),0(@01) 01S0016 00060000

79 L P1PARM1 = 10; 01S0018 00061000

000090 5820 C0F4 000F4 80¬ L @02,@PA00064 01S0018 00062000

000094 4130 000A 0000A 81¬ LA @03,10 01S0018 00063000

000098 5030 2000 00000 82¬ ST @03,P1PARM1(,@02) 01S0018 00064000

83 L END PROC1; 01S0019 00065000

00009C 84 @EL00002 DS 0H 01S0019 00066000

00009C 85 @EF00002 DS 0H 01S0019 00067000

00009C 98EC D00C 0000C 86¬@ER00002 LM @14,@12,12(@13) 01S0019 00068000

0000A0 07FE 87¬ BR @14 01S0019 00069000

0000A2 88 @DATA DS 0H 00070000

0000A4 89 DS 0F 00071000

0000A4 90 @AL00002 DS 0A 00072000

0000A4 00000108 91@ DC A(PARM2) 00073000

0000A8 92 @AL00003 DS 0A 00074000

0000A8 00000104 93@ DC A(EXPARM2) 00075000

0000AC 94 DS 0F 00076000

0000AC 95@@SA00001 DS 18F 00077000

0000F4 96@@PC00002 DS 1F 00078000

0000F8 97 DS 0F 00079000

0000F8 00000000 98@@CV00063 DC V(TEST2B) 00080000

000100 99 LTORG 00081000

000100 100 DS 0D 00082000

000100 00000005 101@EXPARM1 DC F'5' 00083000

000104 00000002 102@EXPARM2 DC F'2' 00084000

000108 00000002 103@PARM2 DC F'2' 00085000

00000 104 @DYNSIZE EQU 0 00086000

00000 105 @00 EQU 0 00087000

00001 106 @01 EQU 1 00088000

00002 107 @02 EQU 2 00089000

00003 108 @03 EQU 3 00090000

00004 109 @04 EQU 4 00091000

00005 110 @05 EQU 5 00092000

00006 111 @06 EQU 6 00093000

00007 112 @07 EQU 7 00094000

00008 113 @08 EQU 8 00095000

00009 114 @09 EQU 9 00096000



0000A 115 @10 EQU 10 00097000

0000B 116 @11 EQU 11 00098000

0000C 117 @12 EQU 12 00099000

0000D 118 @13 EQU 13 00100000

0000E 119 @14 EQU 14 00101000

0000F 120 @15 EQU 15 00102000

00000 121 P1PARM1 EQU 0,4,C'F' 00103000

000F4 122 @PA00064 EQU @PC00002,4,C'F' 00104000

0006C 123 @RF00010 EQU @DE00012 00105000

000110 124 DS 0D 00106000

00110 125 @ENDDATA EQU L 00107000

00110 126 @MODLEN EQU @ENDDATA-TEST2 00108000

127 END , 00109000




Chapter 7. Editing the Coverage Assistant control file

This chapter describes the function of the control file (CACTL) used by CA. TheCACTL contains the names of the compiler listings and copy to/from information.CA, DA, and UTA share the CACTL file. See Chapter 21, “CA, DA, and UTAcontrol file” on page 187 for a complete description of this control file. This chapteronly explains how to use the control file with Coverage Assistant.

Contents of the control fileThe control file defines the programs to be analyzed. A sample control file(CACTL) used to produce a COBOL summary or an annotated COBOL listing isshown in Figure 8 on page 46.

� The DEFAULTS statement specifies default values to be used by subsequentCOBOL , PL/I, and ASM statements.

� The COBOL statement indicates a COBOL program specification.

� The PL/I statement indicates a PL/I program specification.

� The ASM statement indicates an assembler program specification.

� The operand of the LISTDSN= keyword specifies the data set containing theprogram's compiler listing.

� The operand of the LISTMEMBER= keyword specifies the member name of aparticular program listing in the LISTDSN data set. This operand replaces theasterisk in the LISTDSN specification in the DEFAULTS statement.

� The operand of the EXTPROGRAM-ID= keyword (on the COBOL statement)specifies the external program ID of a COBOL program compiled with the TEST(COUNT for OS/VS COBOL) compiler option. If this is coded, LISTDSN,LISTMEMBER, and FROMLOADDSN are optional and TOLOADDSN isrequired.

� The operand of the LOADMOD= keyword specifies the load module membername.

� The operand of the FROMOBJDSN= keyword specifies the data set name ofthe partitioned data set that contains the object code.

� The operand of the TOOBJDSN= keyword specifies the data set name of thepartitioned data set that is to contain the instrumented object code generatedby the CA Setup job.

� The OBJMEMBER= keyword that indicates the member name of the objectcode within the FROMOBJDSN and TOOBJDSN data sets. If it is not speci-fied, it defaults to the value of the LISTMEMBER operand.

� The FROMLOADDSN= keyword specifies the data set name of the partitioneddata set that contains the input load module.

� The TOLOADDSN= keyword specifies the data set name of the partitioneddata set that is to contain the instrumented load module generated by the CASetup job.

Note: The FROMOBJDSN and TOOBJDSN keywords are mutually exclusive ofthe FROMLOADDSN and TOLOADDSN keywords.

Chapter 7. Editing the CA control file 61

See “Contents of the control file” on page 189 for a description of the syntax of thecontrol file.


Chapter 8. Coverage Assistant reports

CA can generate three kinds of reports to describe test case coverage:

Summary reportA summary of the test case coverage using statement numbers of ahigh-level language or offsets for the assembler language.

Annotated Listing reportAnnotated compiler and assembler listings with a character on eachbreakpointed statement to describe how each statement was executed.

Targeted Summary reportA Summary report that provides coverage information on specific“target” statements, which can be identified by statement number or, forCOBOL and PL/I, by statements that reference specific variables.

You can select the type of CA report you want from the Coverage Reports panel.

Creating coverage reportsTo create a coverage report, select option 1 from the ATC Primary Option Menu,and then option 4 from the Coverage, Distillation, and Unit Test Assistant panel.The Coverage Reports panel, shown in Figure 16 is displayed. This panel allowsyou to select the kind of report you want.

Z [ ------------------------------- Coverage Reports ------------------------------

Option ===>

1 Summary Create JCL for Summary report

2 Annotation Create JCL for Summary and Annotation Report

3 Combine Create JCL for Combining Multiple Runs

4 Targeted Generate a Targeted Summary report


\ ]

Figure 16. Coverage Reports panel

The panel's options are as follows:

Summary Create JCL for a Summary report.

Annotation Create JCL for both summary and Annotated Listing reports.

Combine Create JCL for combining multiple CA coverage runs.

Targeted Generate a Targeted Summary report from a coverage run.

Chapter 8. CA reports 63

Creating Summary and Annotated Listing report JCL using the panelsTo create a Summary report, select option 1 on the Coverage Reports panel. TheCreate JCL for Summary report panel, shown in Figure 17, allows you to specifySummary report options and parameters.

Z [ ------------------------ Create JCL for Summary Report ------------------------

Option ===>

1 Generate Generate JCL from parameters

2 Edit Edit JCL

3 Submit Submit JCL


Use Program Name for File Name YES (Yes|No) Program Name COB01

Input Files:

Breakpoint Table Dsn. 'YOUNG.SAMPLE.COB01.BRKTAB'

Breakout Dsn. . . . . 'YOUNG.SAMPLE.COB01.BRKOUT'

JCL Library and Member:

JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(TCOB01)'

Output Summary Type and File:

Type. . . . . . . . . INTERNAL (Internal|External)

Report Dsn . . . . . 'YOUNG.SAMPLE.COB01.SUMMARY'

(L for default sysout class)

\ ]

Figure 17. Create JCL for Summary Report panel

The panel's optons and fields are as follows:

GenerateGenerate JCL from the parameters you have specified on the panel.

EditMake changes to existing JCL.

SubmitSubmit for execution the JCL specified in the JCL Dsn field on thispanel.

Use Program Name for File NameIf you want to construct the data set names from the default high-levelqualifier, the specified program name, and the default low-level qualifierfor each data set, enter YES.

When you press Enter, the file names on the panel are changed auto-matically. Using the program name to construct the data set names isthe normal CA procedure.

Program NameName to use for CA files if you enter YES in the Use Program Name forFile Name field. Note that this can be any valid name. It does not haveto be the name of any of your programs. Names of the following formare created:

� Sequential data sets:




� Partitioned data sets:



Input FilesNames of the breakpoint table and breakout data sets.

JCL DsnSpecifies the name of the JCL data set that contains the JCL for thisaction.

Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beTxxxxxxx, where xxxxxxx is the last seven characters of the programname.

Output Summary Type and FileType of Summary report (internal or external) and the name of the dataset containing the Summary report.

To create a Summary report and Annotated Listing report, select option 2 on theCoverage Reports panel. The Create JCL for Summary and Annotation Reportpanel, shown in Figure 18, allows you to specify Summary report and AnnotatedListing report options.

Z [ ----------------- Create JCL for Summary and Annotation Report ----------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL



Input Files:

Control File Dsn. . . 'YOUNG.SAMPLE.CACTL(COB01)'




JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(RCOB01)'

Output Summary Type and Annotation File:


Report Dsn . . . . . 'YOUNG.SAMPLE.COB01.REPORT'


\ ]

Figure 18. Create JCL for Summary and Annotated Listing Report panel

The panel's options and fields are as follows:






When you press Enter, the file names on the panel are changed auto-matically. Using the program name is the normal CA procedure.

Program NameName to use for CA files if you enter YES in the Use Program Name forFile Name field. Note that this can be any valid name. It does not haveto be the name of any of your programs. Names of the following formare created:







Input FilesNames of the control file (CACTL), breakpoint table, and breakout datasets.


Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beRxxxxxxx, where xxxxxxx is the last seven characters of the programname.

Output Summary Type and Annotation FileType of Summary report (internal or external) and the name of the dataset containing the summary and Annotated Listing report.


Summary reportThe Summary report gives statistics on the coverage of all program areas (PAs)during the test run. The Summary report is divided into the following sections:

Program Area DataLists summary data on each PA. Lists the total number of code state-ments and the number that were executed. Also lists the total numberof branches and the number of branches executed. See “PROGRAMAREA DATA” on page 70 for details.

Unexecuted CodeLists the unexecuted code statements in each PA. See “UNEXECUTEDCODE” on page 71 for details.

Branches That Have Not Gone Both WaysLists the conditional branches that have not executed in both directionsfor each PA. See “BRANCHES THAT HAVE NOT GONE BOTHWAYS” on page 71 for details.

Examples of Summary reports are shown in Figure 19 on page 68 and Figure 20on page 69.

Note: These examples were run with the Performance Mode flag set to N, (thedefault is Y). For information about Performance Mode's effect on Summaryreports, see “Suppression of conditional branch coverage with Performance Mode”on page 71.

Each section of a report contains the date, time, and test case ID (if provided) ofthe CA test run. You may provide the test case ID with the ATGRIDAD operatorcommand during a monitor session. For details on this command, see“ATGRIDAD” on page 249. A summary of data for all PAs is displayed followingthe PA-specific data.


The INTERNAL option was used to create the Summary report for a set of COBOLroutines shown in Figure 19. Paragraphs and their related statistics appear onseparate lines. If the EXTERNAL option had been used, statistics for all para-graphs in the object module would have been combined on one line.


0 DATE: 07/22/1999

TIME: 12:57:19

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 COB01 PROG YOUNG.SAMPLE.COBOLST(COB01A) 6 6 100.0 0 0 100.0

2 PROGA 5 4 80.0 6 5 83.3

3 PROCA 1 0 0.0 0 0 100.0

4 LOOP1 3 3 100.0 2 1 50.0

5 LOOP2 2 2 100.0 2 1 50.0

6 COB01 PROGB YOUNG.SAMPLE.COBOLST(COB01B) 6 5 83.3 6 4 66.7

7 PROCB 1 1 100.0 0 0 100.0

8 LOOP1 3 3 100.0 2 1 50.0

9 COB01 PROGC YOUNG.SAMPLE.COBOLST(COB01C) 5 5 100.0 6 6 100.0

10 PROCC 3 2 66.7 2 1 50.0

11 LOOP1 4 3 75.0 4 2 50.0

12 LOOP2 2 2 100.0 2 1 50.0

13 COB01 PROGD YOUNG.SAMPLE.COBOLST(COB01D) 4 0 0.0 4 0 0.0

14 PROCD 1 0 0.0 0 0 100.0

15 LOOP1 1 0 0.0 0 0 100.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 07/22/1999

TIME: 12:57:19

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------


3 PROCA 69 69



11 LOOP1 56 56


14 PROCD 42 42

15 LOOP1 46 46

----------------------------------------------------------------------------------------------------------------------


0 DATE: 07/22/1999

TIME: 12:57:19

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

2 COB01 PROGA YOUNG.SAMPLE.COBOLST(COB01A) 57

4 LOOP1 72

5 LOOP2 77


8 LOOP1 49

10 COB01 PROCC YOUNG.SAMPLE.COBOLST(COB01C) 45

11 LOOP1 52 54

12 LOOP2 60


----------------------------------------------------------------------------------------------------------------------

Figure 19. Summary report for COB01 in COBOL


The INTERNAL option was used to create the Summary report for a set of PL/Iroutines shown in Figure 20 on page 69. Procedures, ON-units, Begin-blocks, andtheir related statistics are shown on separate lines. If the EXTERNAL option hadbeen used, statistics for all procedures, ON-units, and Begin-blocks in the objectmodule would have been combined on one line.


0 DATE: 07/22/1999

TIME: 12:57:51

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 PLI01 PLI01A YOUNG.SAMPLE.PLILST(PLI01A) 9 9 100.0 6 5 83.3

2 PROC2A 2 0 0.0 0 0 100.0

3 PLI01 PLI01B YOUNG.SAMPLE.PLILST(PLI01B) 11 8 72.7 6 4 66.7

4 PROC1 2 2 100.0 0 0 100.0

5 PLI01 PLI01C YOUNG.SAMPLE.PLILST(PLI01C) 7 4 57.1 6 3 50.0

6 PROC1 4 3 75.0 2 1 50.0

7 PLI01 PLI01D YOUNG.SAMPLE.PLILST(PLI01D) 2 0 0.0 2 0 0.0

8 PROC1 4 0 0.0 2 0 0.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 07/22/1999

TIME: 12:57:51

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

2 PLI01 PROC2A YOUNG.SAMPLE.PLILST(PLI01A) 17 18

3 PLI01 PLI01B YOUNG.SAMPLE.PLILST(PLI01B) 9 9 15 16

5 PLI01 PLI01C YOUNG.SAMPLE.PLILST(PLI01C) 6 6 10 11

6 PROC1 16 16

7 PLI01 PLI01D YOUNG.SAMPLE.PLILST(PLI01D) 3 11

8 PROC1 6 10

----------------------------------------------------------------------------------------------------------------------


0 DATE: 07/22/1999

TIME: 12:57:51

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

1 PLI01 PLI01A YOUNG.SAMPLE.PLILST(PLI01A) 10

3 PLI01 PLI01B YOUNG.SAMPLE.PLILST(PLI01B) 8 14

5 PLI01 PLI01C YOUNG.SAMPLE.PLILST(PLI01C) 5 8 9

6 PROC1 15

7 PLI01 PLI01D YOUNG.SAMPLE.PLILST(PLI01D) 3

8 PROC1 7

----------------------------------------------------------------------------------------------------------------------

Figure 20. Summary report for PLI01 in PL/I


Areas of the Summary report

PROGRAM AREA DATAThe portion of the report called PROGRAM AREA DATA contains the followinginformation:

� PROGRAM IDENTIFICATION

– The load module name, paragraph name, and listing name (COBOL)– The load module name, the procedure, ON-unit, or Begin-block name, and

the listing name (PL/I)– The load module name, CSECT name, and listing name (ASM)

� Coverage statistics

Data on test case coverage for each PA.

PROGRAM IDENTIFICATIONThe columns in the PROGRAM IDENTIFICATION area are:

PA Number of the program area (PA)

LOAD MOD Load module name.

PROCEDURE COBOL: Paragraph name. These are shown insource order. Section names are listed only ifthey contain statements outside of paragraphs.

PL/I: Procedure, ON-unit, or Begin-block name(a user-supplied label, the compiler-generatedname, or a CA-generated name). These areshown in source order.

ASM: CSECT name.

LISTING NAME Listing name.

COVERAGE STATISTICSThe columns in Coverage Statistics are:

STATEMENTS: TOTAL The statements of code for this test case run

STATEMENTS: EXEC The statements of code that were executed

STATEMENTS: % The percentage of statements that were exe-cuted

BRANCHES: CPATH The number of conditional branch paths(number of conditional branches multiplied by 2)

BRANCHES: TAKEN The number of conditional branch paths thatwere executed

BRANCHES: % The percentage of conditional branch paths thatwere executed


UNEXECUTED CODEThe portion of the report called UNEXECUTED CODE contains the following infor-mation:

PROGRAM IDENTIFICATION Described previously under PROGRAM IDEN-TIFICATION.

start The line number of the first unexecuted instruc-tion in this unexecuted segment.

end The line number of the last unexecuted instruc-tion in this unexecuted segment.

BRANCHES THAT HAVE NOT GONE BOTH WAYSThe portion of the report called BRANCHES THAT HAVE NOT GONE BOTHWAYS contains the following information:

PROGRAM IDENTIFICATION Described previously under PROGRAM IDEN-TIFICATION.

stmt The line number of the conditional branchinstruction that did not execute in bothdirections.

Suppression of conditional branch coverage with Performance ModeWhen the Performance Mode (described at “Using the Performance Mode toreduce monitor overhead” on page 235) is used, the breakpoints for conditionalbranches are not kept in storage, and the conditional branch coverage data is inac-curate. For summaries produced from test runs when the Performance Mode isenabled during Setup, the conditional branch coverage data is suppressed. In thePROGRAM AREA DATA section of the Summary report, the BRANCHES section isblank. In the BRANCHES THAT HAVE NOT GONE BOTH WAYS section, the con-ditional branches are not listed.

If the summary is performed on a test run where some object modules are testedwith Performance Mode enabled and some with it disabled, those object modulesthat are tested with Performance Mode disabled have their conditional branch cov-erage listed.

An example of a Summary report generated with the Performance Mode flagenabled during Setup is shown in Figure 21 on page 72.



0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 COB01 PROG YOUNG.SAMPLE.COBOLST(COB01A) 6 6 100.0

2 PROGA 5 4 80.0

3 PROCA 1 0 0.0

4 LOOP1 3 3 100.0

5 LOOP2 2 2 100.0

6 COB01 PROGB YOUNG.SAMPLE.COBOLST(COB01B) 6 5 83.3

7 PROCB 1 1 100.0

8 LOOP1 3 3 100.0

9 COB01 PROGC YOUNG.SAMPLE.COBOLST(COB01C) 5 5 100.0

10 PROCC 3 2 66.7

11 LOOP1 4 3 75.0

12 LOOP2 2 2 100.0

13 COB01 PROGD YOUNG.SAMPLE.COBOLST(COB01D) 4 0 0.0

14 PROCD 1 0 0.0

15 LOOP1 1 0 0.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------


3 PROCA 69 69



11 LOOP1 56 56


14 PROCD 42 42

15 LOOP1 46 46

----------------------------------------------------------------------------------------------------------------------


0 DATE: 07/22/1999

TIME: 12:27:02

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------

Figure 21. Summary report with Performance Mode enabled during Setup


Summary report when no listings are available during SetupIf the COBOL TEST (COUNT for OS/VS COBOL) compiler option was used in con-junction with the EXTPROGRAM-ID keyword on the COBOL statement in the CAcontrol file, the Summary report changes in the following ways:

Areas of the Summary report

PROGRAM AREA DATA� The PROCEDURE column is replaced by the STMT column, which lists the

statement number of each COBOL paragraph.

� The LISTING NAME column is replaced by the EXT PROGRAM ID/COMPILEDATE column, which lists the external program ID for each external COBOLprogram along with its compile date and time.

� The BRANCHES section is suppressed.

UNEXECUTED CODE� The PROCEDURE column is replaced by the STMT column, which lists the

statement number of each COBOL paragraph that had unexecuted code.

� The LISTING NAME column is replaced by the EXT PGM column, which liststhe external program ID for each external COBOL program that had unexe-cuted code.

BRANCHES THAT HAVE NOT GONE BOTH WAYSThis portion of the report is suppressed.

An example of this type of Summary report is shown in Figure 22 on page 74.


1 LLLLLLLLL CA SUMMARY: PROGRAM AREA DATA LL

0 DATE: 07/22/1999

TIME: 13:11:13

TEST CASE ID:


| | STATEMENTS: |

| PA LOAD MOD STMT EXT PROGRAM ID/COMPILE DATE | TOTAL EXEC % |

----------------------------------------------------------------------------

1 COB01 40 COB01A 1999 JUL 22 13:05:45 6 6 100.0

2 54 5 4 80.0

3 67 1 0 0.0

4 71 3 3 100.0

5 76 2 2 100.0

6 COB01 32 COB01B 1999 JUL 22 13:05:49 6 5 83.3

7 45 1 1 100.0

8 48 3 3 100.0

9 COB01 32 COB01C 1999 JUL 22 13:05:52 5 5 100.0

10 43 3 2 66.7

11 51 4 3 75.0

12 59 2 2 100.0

13 COB01 32 COB01D 1999 JUL 22 13:05:55 4 0 0.0

14 41 1 0 0.0

15 45 1 0 0.0

----------------------------------------------------------------------------

Summary for all PAs: 47 36 76.6

1 LLLLLLLLL CA SUMMARY: UNEXECUTED CODE LL

0 DATE: 07/22/1999

TIME: 13:11:13

TEST CASE ID:

0 |<-- PROGRAM IDENTIFICATION->|

| PA LOAD MOD STMT EXT PGM start end start end start end

----------------------------------------------------------------------------

2 COB01 54 COB01A 59 59

3 67 69 69

6 COB01 32 COB01B 41 41

10 COB01 43 COB01C 47 47

11 51 56 56

13 COB01 32 COB01D 33 38

14 41 42 42

15 45 46 46

----------------------------------------------------------------------------

Figure 22. Summary report when no listings are available during Setup

Summary report for assemblerThe summary for a High Level Assembler or an Assembler H program differs fromthe high-level summaries described previously. For sample assembler Summaryreports, see Figure 23 on page 76 and Figure 24 on page 77.

| Fields in the report| The fields PA, LOAD MOD, PROCEDURE, and LISTING NAME are common to all areas of| the report. All of these fields have same contents as the high-level summaries| described previously except for the following field:


| PROCEDURE| This field contains the CSECT name used in the assembler code. Note that in| cases where a CSECT is interrupted by another CSECT and then, later, the original| CSECT is resumed, a new PA will be generated each time a CSECT is resumed.| For example:

| C1 CSECT

| . . .

| C2 CSECT

| . . .

| C1 CSECT

| . . .

| will create three PA's (C1, C2, and C1).

Areas of the report

PROGRAM AREA DATA| STATEMENTS: TOTAL The number of executable assembler statements in the| program. If desired, the bytes of executable code in the| program can be listed. Data areas occurring anywhere| in the listing are excluded from this count.

| STATEMENTS: EXEC The number of executable assembler statements that| executed. If desired, the bytes of executable code in the| program can be listed.

| By default (unless the default has been changed), the number of executable| assembler statements appears in the statement columns (total and executed) (see| Figure 23 on page 76). The character 'S' appears in front of the statement| columns to indicate that these columns relate to number of statements. If you run| Summary with the Summary Assembler Stmts flag enabled (with a value of Y) and| you are analyzing assembler programs, the BRKTAB / BRKOUT files must have| been generated by a V2R1M3 or later version of ATC. Otherwise, all statement| counts will be zero.

| You may want to measure the bytes of executable code (total and executed)| instead of the number of statements (see Figure 24 on page 77). To do this,| change the "Summary Assembler Stmts" default to 'N' from the Defaults panel,| and then create the summary JCL via the Create JCL for Summary or Create JCL| for Summary and Reports panel. You can also change a parameter in previously| created summary JCL (see “Parameters for the Summary and Report programs” on| page 87).

| If you show the number of bytes executed you may see an * in the STATEMENT| TOTALS column. This indicates that if your code contains relative branching, for| example:

B L+20

your coverage data may not be accurate. To get accurate coverage in this case,enable the Frequency Mode flag in defaults and recreate your Setup JCL (andrerun all steps).


UNEXECUTED CODESTART The offset within the PA of the first unexecuted instruc-

tion in this unexecuted segment

END The offset within the PA of the last unexecuted instruc-tion in this unexecuted segment

BRANCHES THAT HAVE NOT GONE BOTH WAYSSTMT The offset within the PA of the conditional branch

instruction that did not execute in both directions

| 1 LLLLLLLLL CA SUMMARY: PROGRAM AREA DATA LLLLLLLL

| 0 DATE: 09/18/2000

| TIME: 13:45:51

| TEST CASE ID:

| 0 |<-- PROGRAM IDENTIFICATION -->|

| | | | STATEMENTS: | BRANCHES: |

| | PA LOAD MOD PROCEDURE | LISTING NAME | TOTAL EXEC % | CPATH TAKEN % |

| ----------------------------------------------------------------------------------------------------------------------

| 1 ASM01L TEST2 YOUNG.SAMPLE.ASMLST(ASM01AL) S 41 31 75.6 6 5 83.3

| 2 ASM01L TEST2B YOUNG.SAMPLE.ASMLST(ASM01BL) S 45 39 86.7 6 4 66.7

| 3 ASM01L TEST2C YOUNG.SAMPLE.ASMLST(ASM01CL) S 39 32 82.1 8 5 62.5

| 4 ASM01L TEST2D YOUNG.SAMPLE.ASMLST(ASM01DL) S 25 0 0.0 4 0 0.0

| ----------------------------------------------------------------------------------------------------------------------

| Summary for all PAs: 150 102 68.0 24 14 58.3

| 1 LLLLLLLLL CA SUMMARY: UNEXECUTED CODE LLLLLLLL

| 0 DATE: 09/18/2000

| TIME: 13:45:51

| TEST CASE ID:


| | | |

| | PA LOAD MOD PROCEDURE | LISTING NAME | start end start end start end

| ----------------------------------------------------------------------------------------------------------------------

| 1 ASM01L TEST2 YOUNG.SAMPLE.ASMLST(ASM01AL) 000056 000062 000086 0000A0

| 2 ASM01L TEST2B YOUNG.SAMPLE.ASMLST(ASM01BL) 000050 00005A 000078 000082

| 3 ASM01L TEST2C YOUNG.SAMPLE.ASMLST(ASM01CL) 000034 00003A 000050 00005A 000092 000098

| 4 ASM01L TEST2D YOUNG.SAMPLE.ASMLST(ASM01DL) 000000 000000 000016 00006C

| ----------------------------------------------------------------------------------------------------------------------

| 1 LLLLLLLLL CA SUMMARY: BRANCHES THAT HAVE NOT GONE BOTH WAYS LLLLLLLL

| 0 DATE: 09/18/2000

| TIME: 13:45:51

| TEST CASE ID:


| | | |

| | PA LOAD MOD PROCEDURE | LISTING NAME | stmt stmt stmt stmt stmt

| ----------------------------------------------------------------------------------------------------------------------

| 1 ASM01L TEST2 YOUNG.SAMPLE.ASMLST(ASM01AL) 000052

| 2 ASM01L TEST2B YOUNG.SAMPLE.ASMLST(ASM01BL) 000040 00008C

| 3 ASM01L TEST2C YOUNG.SAMPLE.ASMLST(ASM01CL) 000030 000064 00008E

| 4 ASM01L TEST2D YOUNG.SAMPLE.ASMLST(ASM01DL) 000030 00005E

| ----------------------------------------------------------------------------------------------------------------------

| Figure 23. Summary report for ASM01 showing executable statements



0 DATE: 07/22/1999

TIME: 12:58:24

TEST CASE ID:




----------------------------------------------------------------------------------------------------------------------

1 ASM01 TEST2 YOUNG.SAMPLE.ASMLST(ASM01A) L 144 104 72.2 6 5 83.3

2 ASM01 TEST2B YOUNG.SAMPLE.ASMLST(ASM01B) L 164 144 87.8 6 4 66.7

3 ASM01 TEST2C YOUNG.SAMPLE.ASMLST(ASM01C) L 140 118 84.3 8 5 62.5

4 ASM01 TEST2D YOUNG.SAMPLE.ASMLST(ASM01D) L 92 0 0.0 4 0 0.0

----------------------------------------------------------------------------------------------------------------------



0 DATE: 07/22/1999

TIME: 12:58:24

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

1 ASM01 TEST2 YOUNG.SAMPLE.ASMLST(ASM01A) 000056 000062 000086 0000A0

2 ASM01 TEST2B YOUNG.SAMPLE.ASMLST(ASM01B) 000050 00005A 000078 000082

3 ASM01 TEST2C YOUNG.SAMPLE.ASMLST(ASM01C) 000034 00003A 000050 00005A 000092 000098

4 ASM01 TEST2D YOUNG.SAMPLE.ASMLST(ASM01D) 000000 000000 000016 00006C

----------------------------------------------------------------------------------------------------------------------


0 DATE: 07/22/1999

TIME: 12:58:24

TEST CASE ID:


| | |


----------------------------------------------------------------------------------------------------------------------

1 ASM01 TEST2 YOUNG.SAMPLE.ASMLST(ASM01A) 000052

2 ASM01 TEST2B YOUNG.SAMPLE.ASMLST(ASM01B) 000040 00008C

3 ASM01 TEST2C YOUNG.SAMPLE.ASMLST(ASM01C) 000030 000064 00008E

4 ASM01 TEST2D YOUNG.SAMPLE.ASMLST(ASM01D) 000030 00005E

----------------------------------------------------------------------------------------------------------------------

| Figure 24. Summary report for ASM01 showing executable bytes

Annotated Listing reportYou can create two kinds of Annotated Listing reports to show code coverage:

All Every line of the listing is printed.

Unexecuted Only unexecuted instructions or conditional branch instructionsthat have not gone both ways are printed.

Each instruction line in the listings has an annotation character placed to the rightof the statement number to indicate what happened during the test run:

& A conditional branch instruction has executed both ways.7

> A conditional branch instruction has branched, but not fallen through.7

7 The annotation of statements with conditional branches is affected by the Performance Mode. For more information, see“Changes in annotation symbols with Performance Mode” on page 86.


V A conditional branch instruction has fallen through, but not branched.7

: A non-branch instruction has executed.

¬ An instruction has not executed.

@ Data area in the assembler listing.

% Unconditional branch that has been executed in the assembler listing

These characters are the defaults. You can replace them with any others youprefer by supplying a parameter to the Report program.

Figure 25 on page 79 shows a sample COBOL Annotated Listing report in whichall lines have been printed.

Figure 26 on page 81 shows a sample PL/I Annotated Listing report in which alllines have been printed.

Figure 27 on page 82 shows a sample ASM Annotated Listing report in which alllines have been printed.

Note: These examples were run with the Performance Mode flag set to N. Forinformation about Performance Mode with Annotated Listing reports, see “Changesin annotation symbols with Performance Mode” on page 86.


LineID PL SL ----+-LA-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8 Map and Cross Reference

000001 L COB01A - COBOL EXAMPLE FOR CA

000002

000003 IDENTIFICATION DIVISION.

000004 PROGRAM-ID. COB01A.


000006 L L

000007 L LICENSED MATERIALS - PROPERTY OF IBM L

000008 L L

000009 L 5655-B97 L

000010 L L

000011 L (C) COPYRIGHT IBM CORP. 1997, 1999 ALL RIGHTS RESERVED L

000012 L L

000013 L US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR L

000014 L DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM L

000015 L CORP. L

000016 L L

000017 L L


000019

000020 ENVIRONMENT DIVISION.

000021

000022 DATA DIVISION.

000023

000024 WORKING-STORAGE SECTION.



000027 01 COB01B PIC X(6) VALUE 'COB01B'.

000028 01 P1PARM1 PIC 99 VALUE 0.

000029

000030 01 TASTRUCT.

000031 05 LOC-ID.

000032 10 STATE PIC X(2).

000033 10 CITY PIC X(3).

000034 05 OP-SYS PIC X(3).

000035

000036 PROCEDURE DIVISION.

000037

000038 L THE FOLLOWING ALWAYS PERFORMED

000039

000040 PROG.

000041 L ACCESS BY TOP LEVEL QUALIFIER

000042 : MOVE 'ILCHIMVS' TO TASTRUCT

000043

000044 L ACCESS BY MID LEVEL QUALIFIERS

000045 : MOVE 'ILSPR' TO LOC-ID

000046 : MOVE 'AIX' TO OP-SYS



000047

000048 L ACCESS BY LOW LEVEL QUALIFIERS

000049 : MOVE 'KY' TO STATE

000050 : MOVE 'LEX' TO CITY

000051 : MOVE 'VM ' TO OP-SYS

000052 .

000053

000054 PROGA.

000055 & PERFORM LOOP1 UNTIL TAPARM1 = 0

000056

000057 > IF TAPARM2 = 0 THEN


000059 ¬ 1 PERFORM PROCA.

000060

000061

000062 & PERFORM LOOP2 UNTIL TAPARM2 = 0

000063 .

000064 : STOP RUN

000065 .

000066

000067 PROCA.


000069 ¬ MOVE 10 TO P1PARM1

000070 .

000071 LOOP1.

000072 V IF TAPARM1 > 0 THEN


000074 : CALL 'COB01B'

000075 .

000076 LOOP2.

000077 V IF TAPARM2 > 0 THEN


000079



STMT LEV NT

1 0 PLI01A:PROC OPTIONS(MAIN); /L PL/I CA TESTCASE L/


/L L/

/L Licensed Materials - Property of IBM L/

/L L/

/L 5655-B97 L/

/L L/

/L (C) Copyright IBM Corp. 1997, 1999 All Rights Reserved L/

/L L/

/L US Government Users Restricted Rights - Use, duplication or L/

/L disclosure restricted by GSA ADP Schedule Contract with IBM Corp.L/

/L L/




4 1 0 DCL PARM2 FIXED BIN(31) INIT(2);

5 1 0 DCL PLI01B EXTERNAL ENTRY; /L L/

6& 1 0 DO WHILE (EXPARM1 > 0); /L THIS DO LOOP EXECUTED 5 TIMESL/

7: 1 1 EXPARM1 = EXPARM1 -1; /L L/

8: 1 1 CALL PLI01B(PARM2); /L PLI01B CALLED 5 TIMES L/

9: 1 1 END;

10> 1 0 IF (EXPARM2 = 0) THEN /L THIS BRANCH ALWAYS TAKEN L/

CALL PROC2A(EXPARM2); /L PROC2A NEVER CALLED L/

11& 1 0 DO WHILE (EXPARM2 > 0); /L DO LOOP EXECUTED TWICE L/

12: 1 1 EXPARM2 = EXPARM2 - 1;

13: 1 1 END;

14: 1 0 RETURN;

15 1 0 PROC2A: PROCEDURE(P1PARM1); /L THIS PROCEDURE NEVER EXECUTED L/

16 2 0 DCL P1PARM1 FIXED BIN(31);

17¬ 2 0 P1PARM1 = 10;

18¬ 2 0 END PROC2A;

19 1 0 END PLI01A;

Figure 26. PL/I Annotated Listing report


Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R2.0 1999/07/22 08.58


2 L L 00000200

3 L LICENSED MATERIALS - PROPERTY OF IBM L 00000300

4 L L 00000400

5 L 5655-B97 L 00000504

6 L L 00000600

7 L (C) COPYRIGHT IBM CORP. 1997, 1999 ALL RIGHTS RESERVED L 00000706

8 L L 00000800

9 L US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR L 00000900

10 L DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM L 00001000

11 L CORP. L 00001100

12 L L 00001200

13 L L 00001300



16 L L 00001600

17 L CA ASSEMBLER TESTCASE. L 00001702

18 L L 00001800


000000 20 TEST2 CSECT , 01S0001 00002000

000000 21 @MAINENT DS 0H 01S0001 00003000

R:F 00000 22 USING L,@15 01S0001 00004000

000000 47F0 F016 00016 23% B @PROLOG 01S0001 00005000

000004 10 24@ DC AL1(16) 01S0001 00006000

000005 E3C5E2E3F2404040 25@ DC C'TEST2 97.295' 01S0001 00007000

26 DROP @15 00008000

000015 00

000016 90EC D00C 0000C 27:@PROLOG STM @14,@12,12(@13) 01S0001 00009000

00001A 18CF 28: LR @12,@15 01S0001 00010000

00000 29 @PSTART EQU TEST2 01S0001 00011000

R:C 00000 30 USING @PSTART,@12 01S0001 00012000

00001C 50D0 C0B0 000B0 31: ST @13,@SA00001+4 01S0001 00013000

000020 41E0 C0AC 000AC 32: LA @14,@SA00001 01S0001 00014000

000024 50E0 D008 00008 33: ST @14,8(,@13) 01S0001 00015000

000028 18DE 34: LR @13,@14 01S0001 00016000

35 L DO WHILE(EXPARM1>0); /L THIS DO LOOP EXECUTED 5 TIMES L/ 00017000

00002A 47F0 C042 00042 36% B @DE00006 01S0006 00018000

00002E 37 @DL00006 DS 0H 01S0007 00019000

38 L EXPARM1 = EXPARM1 - 1; /L L/ 00020000

00002E 5810 C100 00100 39: L @01,EXPARM1 01S0007 00021000

000032 0610 40: BCTR @01,0 01S0007 00022000

000034 5010 C100 00100 41: ST @01,EXPARM1 01S0007 00023000

42 L CALL TEST2B(PARM2); /L TEST2B CALLED 5 TIMES L/ 00024000

000038 58F0 C0F8 000F8 43: L @15,@CV00063 01S0008 00025000

00003C 4110 C0A4 000A4 44: LA @01,@AL00002 01S0008 00026000

000040 05EF 45% BALR @14,@15 01S0008 00027000

46 L END; 01S0009 00028000

Figure 27 (Part 1 of 3). ASM Annotated Listing report


000042 5800 C100 00100 47:@DE00006 L @00,EXPARM1 01S0009 00029000

000046 1200 48: LTR @00,@00 01S0009 00030000

000048 4720 C02E 0002E 49& BP @DL00006 01S0009 00031000

50 L IF (EXPARM2 = 0) THEN /L THIS BRANCH ALWAYS TAKEN L/ 00032000

00004C 5810 C104 00104 51: L @01,EXPARM2 01S0010 00033000

000050 1211 52: LTR @01,@01 01S0010 00034000

000052 4770 C06C 0006C 53> BNZ @RF00010 01S0010 00035000

54 L CALL PROC1(EXPARM2); /L PROC1 NEVER CALLED L/ 00036000

000056 4110 C0A8 000A8 55¬ LA @01,@AL00003 01S0011 00037000

00005A 45E0 C086 00086 56¬ BAL @14,PROC1 01S0011 00038000

57 L DO WHILE(EXPARM2>0); /L DO LOOP EXECUTED TWICE L/ 00039000

00005E 47F0 C06C 0006C 58¬ B @DE00012 01S0012 00040000

000062 59 @DL00012 DS 0H 01S0013 00041000

60 L EXPARM2 = EXPARM2 - 1; 01S0013 00042000

000062 5820 C104 00104 61: L @02,EXPARM2 01S0013 00043000

000066 0620 62: BCTR @02,0 01S0013 00044000

000068 5020 C104 00104 63: ST @02,EXPARM2 01S0013 00045000

64 L END; 01S0014 00046000

00006C 5830 C104 00104 65:@DE00012 L @03,EXPARM2 01S0014 00047000

000070 1233 66: LTR @03,@03 01S0014 00048000

000072 4720 C062 00062 67& BP @DL00012 01S0014 00049000

68 L RETURN CODE(0); 01S0015 00050000

000076 1FFF 69: SLR @15,@15 01S0015 00051000

000078 58D0 D004 00004 70: L @13,4(,@13) 01S0015 00052000

00007C 58E0 D00C 0000C 71: L @14,12(,@13) 01S0015 00053000

000080 980C D014 00014 72: LM @00,@12,20(@13) 01S0015 00054000

000084 07FE 73% BR @14 01S0015 00055000

74 L END TEST2; 01S0020 00056000

75 LPROC1: 01S0016 00057000

76 L PROCEDURE(P1PARM1); /L THIS PROCEDURE NEVER EXECUTED L/ 00058000

000086 90EC D00C 0000C 77¬PROC1 STM @14,@12,12(@13) 01S0016 00059000

00008A D203 C0F4 1000 000F4 00000 78¬ MVC @PC00002(4),0(@01) 01S0016 00060000

79 L P1PARM1 = 10; 01S0018 00061000

000090 5820 C0F4 000F4 80¬ L @02,@PA00064 01S0018 00062000

000094 4130 000A 0000A 81¬ LA @03,10 01S0018 00063000

000098 5030 2000 00000 82¬ ST @03,P1PARM1(,@02) 01S0018 00064000

83 L END PROC1; 01S0019 00065000

00009C 84 @EL00002 DS 0H 01S0019 00066000

00009C 85 @EF00002 DS 0H 01S0019 00067000

00009C 98EC D00C 0000C 86¬@ER00002 LM @14,@12,12(@13) 01S0019 00068000

0000A0 07FE 87¬ BR @14 01S0019 00069000

0000A2 88 @DATA DS 0H 00070000

0000A4 89 DS 0F 00071000

0000A4 90 @AL00002 DS 0A 00072000

0000A4 00000108 91@ DC A(PARM2) 00073000

0000A8 92 @AL00003 DS 0A 00074000

0000A8 00000104 93@ DC A(EXPARM2) 00075000

0000AC 94 DS 0F 00076000

0000AC 95@@SA00001 DS 18F 00077000

0000F4 96@@PC00002 DS 1F 00078000

0000F8 97 DS 0F 00079000

0000F8 00000000 98@@CV00063 DC V(TEST2B) 00080000

000100 99 LTORG 00081000

000100 100 DS 0D 00082000

000100 00000005 101@EXPARM1 DC F'5' 00083000

000104 00000002 102@EXPARM2 DC F'2' 00084000

000108 00000002 103@PARM2 DC F'2' 00085000

00000 104 @DYNSIZE EQU 0 00086000

00000 105 @00 EQU 0 00087000

00001 106 @01 EQU 1 00088000

00002 107 @02 EQU 2 00089000

00003 108 @03 EQU 3 00090000

00004 109 @04 EQU 4 00091000

00005 110 @05 EQU 5 00092000

00006 111 @06 EQU 6 00093000

00007 112 @07 EQU 7 00094000

00008 113 @08 EQU 8 00095000

00009 114 @09 EQU 9 00096000



0000A 115 @10 EQU 10 00097000

0000B 116 @11 EQU 11 00098000

0000C 117 @12 EQU 12 00099000

0000D 118 @13 EQU 13 00100000

0000E 119 @14 EQU 14 00101000

0000F 120 @15 EQU 15 00102000

00000 121 P1PARM1 EQU 0,4,C'F' 00103000

000F4 122 @PA00064 EQU @PC00002,4,C'F' 00104000

0006C 123 @RF00010 EQU @DE00012 00105000

000110 124 DS 0D 00106000

00110 125 @ENDDATA EQU L 00107000

00110 126 @MODLEN EQU @ENDDATA-TEST2 00108000

127 END , 00109000


Selecting specific listings to annotateYou do not always have to produce Annotated Listing reports. You may create aSummary report first, and then, based on the summary, decide to produce Anno-tated Listing reports on only a few selected program areas.

To select the specific listings you want to annotate after completing a test case run:

1. Edit the CACTL, leaving in the names of the listings you want to annotate:

a. Select option 1 from the ATC Primary Option Menu, then select option 1from the Coverage, Distillation, and Unit Test Assistant panel.

b. On the Work with the CA/DA/UTA Control File panel, select option 1, whichdisplays an ISPF edit session to allow you to modify the control file. (Youmay also edit the control file directly, using the ISPF editor.)

c. Delete the unwanted listings. The easiest way to do this is to comment outthe line by putting an asterisk (*) in column 1.

2. Create the report JCL:

Select option 1 from the Create JCL for Summary and Annotation Report panel.See “Creating Summary and Annotated Listing report JCL using the panels” onpage 64 for details.

3. Submit the report JCL:

Select option 3 from the Create JCL for Summary and Annotation Report panel.

CA produces an Annotated Listing report for each listing file specified in theCACTL.

Reducing the size of an Annotated Listing reportTo save paper when printing Annotated Listing report, you may want to set theUSEROPT parameter in your defaults to U (display only unexecuted code) ratherthan A (display all code). The report then lists only those lines that were not exe-cuted or that had conditional branches that did not go both ways.


Displaying execution counts in an Annotated Listing reportThe number of times each statement was executed can be displayed in an Anno-tated Listing report. To do so, change the Debug Mode and Frequency CountMode flags in your ATC defaults before generating the JCL for the Setup step.

To change your ATC defaults:


The Manipulate ATC Defaults panel is displayed.

2. Select option 1.

The ATC Defaults panel is displayed.

3. In the Setup Defaults area of the panel, change Debug Mode to Yes and Fre-quency Count Mode to Yes.

Every time Setup JCL is created, these flags will be set. You can also changethese flags in Setup JCL that has already been created. This may be simpler thanchanging the defaults (and then changing them back) if you want to get executioncounts for just one test case. To identify these flags in the parameters passed tothe Setup program, see the comments in the created Setup JCL.

When Debug Mode flag is set to Yes, breakpoints are left in storage for the entiretest run instead of being removed after their first execution. Each time the break-point is executed, the count field is incremented.

When the Frequency Count Mode flag is Yes, the execution counts are saved inthe BRKOUT file of coverage results. The Annotated Listing report will displaythem on the right hand side of the listing, as shown in Figure 28:

000067 PROCA.

e


000069 ¬ MOVE 10 TO P1PARM1 28 >0000 0000 <

000070 .

000071 LOOP1.

000072 V IF TAPARM1 > 0 THEN 25 >0005 0000 <

000073 : 1 SUBTRACT 1 FROM TAPARM1. 25 >0005 0000 <

000074 : CALL 'COB01B' EXT >0005 0000 <

000075 .

000076 LOOP2.

000077 V IF TAPARM2 > 0 THEN 26 >0002 0000 <

000078 : 1 SUBTRACT 1 FROM TAPARM2. 26 >0002 0000 <

000079

Figure 28. Annotated Listing report with execution counts

The execution counts for each statement are on the right between the right arrow(>) and the left arrow (<). For example, statement 72 was executed five times andstatement 77 was executed two times. The other field between the arrows (alwayszeros in this example) is used to display the first key number that executed thisstatement when Distillation Assistant is used. For more information about keynumbers, see “Recording which keys execute a statement” on page 126.

Note: Enabling Debug Mode and Frequency Count Mode may significantlydegrade the performance of the monitored program.


Differences in CA reports when DA and UTA are usedWhen DA or UTA is used with CA, extra breakpoints are inserted. Some of theseextra breakpoints can be on conditional branch instructions, which will alter the con-ditional branch coverage in the summary. For example, if a test case were set upto read variables with UTA as well as to measure code coverage, its conditionalbranch coverage could be as follows:

| BRANCHES: |

| CPATH TAKEN % |

-----------------------

18 9 50.0

-----------------------

18 9 50.0

Figure 29. Sample conditional branch coverage with UTA

If you run the sample test case with UTA disabled, the extra breakpoints for readingvariables are not inserted, and the conditional branch coverage is as follows:

| BRANCHES: |

| CPATH TAKEN % |

-----------------------

2 2 100.0

-----------------------

2 2 100.0

Figure 30. Sample conditional branch coverage without UTA

Note: Statement coverage is not affected if you enable UTA and DA.

The Annotated Listing report will show the added conditional branches. Forexample, a test case with UTA enabled produced the following in the AnnotatedListing report:

000089 L OPERATIONS ON A DATE

000090 VV¬ COMPUTE INTEGER-DATE = FUNCTION INTEGER-OF-DATE(CURR-DATE)

Figure 31. Sample Annotated Listing report with UTA

Because variables are read on statement 90, any conditional branches in the state-ment are monitored for coverage. Without UTA, no conditional branches are moni-tored on assignment statements, as shown in the following:

000089 L OPERATIONS ON A DATE

000090 : COMPUTE INTEGER-DATE = FUNCTION INTEGER-OF-DATE(CURR-DATE)

Figure 32. Sample Annotated Listing report without UTA

Changes in annotation symbols with Performance ModeWhen the Performance Mode (described at “Using the Performance Mode toreduce monitor overhead” on page 235) is used, the breakpoints for conditionalbranches are not kept in storage and the conditional branch coverage data is inac-curate. For reports produced from test runs when the Performance Mode isenabled during Setup, the following annotation changes occur:


Conditional statements, such as IF, PERFORM (COBOL), DO WHILE (PL/I), andothers, that were annotated with one conditional annotation symbol (>,V,&) per con-ditional branch within the statement, are now annotated with one : (a colon), if thestatement is executed, or one ¬ (a not symbol), if the statement is not executed.

Changes in annotation symbols with the EXTPROGRAM-ID optionIf the EXTPROGRAM-ID keyword was used on the COBOL statement in the CAcontrol file in conjunction with the COBOL TEST (COUNT for OS/VS COBOL) com-piler option, the results displayed in the Annotated Listing report are the same as ifthe Performance Mode was enabled during Setup. For more information, see“Changes in annotation symbols with Performance Mode” on page 86.

Parameters for the Summary and Report programsThis section describes the input parameters specified via the PARM field on theEXEC JCL statement for the Summary and Report programs.

SummaryThe Summary program (load module ATGOSMRY) produces a Summary reportfrom test case results. Its parameters are built automatically by the ISPF dialog.The syntax of the parameter string is:

─ ──┬ ┬─I─ ──────────────────────────────────────────────────────────────── └ ┘─E─

─ ──┬ ┬──────────────────────────────────────────────────────────────── ─── � └ ┘ ─␣─ ──┬ ┬─I─ ──┬ ┬────────────────────────────────────────────────── └ ┘─N─ └ ┘ ─␣─ ──┬ ┬─Y─ ──┬ ┬────────────────────────────────────

| └ ┘─N─ └ ┘| ─␣─ ──┬ ┬─Y─ ──┬ ┬──────────────────────| └ ┘─N─ └ ┘| ─␣──common_parameters─

Internal/ExternalI Summary with each PA listed separately.E Combine all PAs into one entry per object module.␣ Represents one or more blanks.Inline/NoInlineI Include PL/X inlined code.N Do not include PL/X inlined code.Target/NoTargetY Indicates targeted summary.N Indicates normal summary.

Note: This parameter is ignored for assembler.| Assembler statements / assembler bytes of code| Y8 Show number of assembler statements in total and exe-| cuted columns.| N Show bytes of code in total and executed columns.| Note: This parameter is ignored for COBOL and PL/I.

| 8 If you run Summary with the Summary Assembler Stmts flag enabled (with a value of Y) and you are analyzing assembler pro-| grams, the BRKTAB / BRKOUT files must have been generated by a V2R1M3 or later version of ATC. Otherwise, the counts will| be zero.


common_parameters Any of the common parameters described in Appendix F,“Parameters Common To Multiple Routines” on page 381(separated by blanks).

ReportThe Report program (load module ATGORPT) produces annotated source listingsfrom test case results. Its parameters are built automatically by the ISPF dialog.The syntax of this parameter string is:

─ ──┬ ┬─A─ ─␣─ ──┬ ┬─B─ ───────────────────────────────────────────────────────────────────────── └ ┘─U─ ├ ┤─P─ └ ┘─A─

─ ──┬ ┬─────────────────────────────────────────────────────────────────────── ─────────────── � └ ┘ ─␣─ ──┬ ┬─listing_name─ ──┬ ┬────────────────────────────────────────────── └ ┘─L──────────── └ ┘ ─␣─ ──┬ ┬─annotation_chars─ ──┬ ┬───────────────── └ ┘─L──────────────── └ ┘ ─␣──common_parms─

User code to display — This flag indicates which part of the user code is displayedin the report.A All user code displayed.U Only unexecuted user code displayed.␣ Represents one or more blanks.Listing TypeB COBOL listing.P PL/I listing.A assembler listing.listing_name Fully-qualified name of data set containing the compiler

listing. This parameter is used only for VisualAge PL/IVersion 2 Release 2, in which case it is required. In allother cases, it can be omitted if no following parametersare present or specified as an asterisk if any followingparameters are present.

annotation_chars List of annotation characters. If the default characters areto be used and any of the following parameters are speci-fied, an asterisk must be specified for this parameter.The default list is as follows:

: ¬ > V % @ and &

For a description of each of these annotation characters,see “Annotated Listing report” on page 77.

common_parms Any of the common parameters described in Appendix F,“Parameters Common To Multiple Routines” on page 381(separated by blanks).

Printing reportsYou can reduce the size of Annotated Listing reports by printing only the lines withunexecuted code. To do this, specify U instead of A as the User Options variable inthe Coverage Report Defaults section of the ATC Defaults panel, shown inFigure 3 on page 22.


Targeted Summary reportsThe Targeted Summary report is similar to a summary report except that it is basedon a specific subset of statements. You can select statements by specifying thestatement numbers directly, or by specifying that all statements that reference givenCOBOL or PL/I variables are of interest. You can also specify a range of state-ments to target.

The Targeted Summary report includes a header section containing a stylizedversion of the target control cards to generate the report. This provides an easymeans for identifying the control cards used to generate the report in case youchoose to produce multiple different Targeted Summary reports from a single cov-erage run.

The other difference between the Targeted Summary report and the summaryreport is in the unexecuted code section. The Targeted Summary report lists alltargeted unexecuted statements rather than the starting and ending statementnumbers of unexecuted code segments. For a description of the summary format,see “Summary report” on page 67.

To create a Targeted Summary report, you must supply:

� Breakpoint table (BRKTAB) and breakout (BRKOUT) data sets from a coveragerun

� A Targeted Summary control file data set� Complier listings for the programs of interest

The target control cards, which specify the statements to be targeted, can beincluded by the user in the same CA control file used for the coverage run, or canbe in a separate Targeted Summary control file. The SAA Comparison Analysistool can also be used to produce a template Targeted Summary control file basedon a SuperC comparison report, which targets all statements containing variablesthat appeared on changed lines. For details, see Chapter 29, “Source AuditAssistant Comparison Analysis tool” on page 281.

Targeted Summary control fileA Targeted Summary control file is used to specify the statements that are ofinterest in the Targeted Summary report. It must be a sequential file or a memberof a partitioned data set, and can have any DCB attributes. It is generally free-formand subject to the following requirements:

� Statements are free-form (not column dependent).

� An asterisk in column 1 indicates a comment.

� The characters // (two consecutive slashes) indicate that the rest of the linefollowing the two slashes is a comment.

� Lines containing nothing but blanks are ignored.

� Keywords and operands may be coded in any combination of upper and lowercase.

� Operands may appear in any order.

� Operands must be separated by a comma.


� One or more blanks can appear between keywords and the correspondingequal sign as well as between the equal sign and the operand and between theoperand and the following comma.

� The order of statements is not significant except that:

– All labels must be defined before they are referenced.

– The DEFAULTS9 statement is position dependent (it applies only to thestatements that follow it).

– The default value for some operands is the previous statement of theproper type.

� Statements may be continued, if desired, by interrupting the line after a commaand continuing the statement on the next line.

� Labels, if present, are specified preceding the statement name and must beimmediately followed by a colon. Labels cannot contain embedded blanks,commas, parentheses, or equal signs.

� Labels specified on COBOL, PL/I, and PLI statements cannot be repeated onany of those statements. Likewise, labels on SCOPE statements cannot berepeated on another SCOPE statement and labels on TARGETVAR statementscannot be repeated on another TARGETVAR statement.

� Operands shown in the syntax diagrams as being enclosed in parentheses,need not be enclosed in these parentheses if the operand contains noembedded blanks or commas.

DBCS support for the control file statements is explained in Appendix C, “DBCSsupport” on page 365.

The format of these statements is shown in the following sections.

9 The DEFAULTS statement is described in “DEFAULTS statement” on page 191.


Compilation Unit Definition (COBOL or PL/I) StatementThe COBOL and PL/I statements identify the compilation unit to which subsequentTarget Control statements apply.

Note: The purpose and syntax of the COBOL and PL/I control statements is thesame as that of the corresponding CA/DA/UTA control statement. However, not allinformation that is required for CA/DA/UTA is required in the Target Control state-ment.

─ ──┬ ┬────────── ──┬ ┬─COBOL─ ─LISTDSN──=─ ──(1)──┬ ┬─listdsname─ ─────────────── � └ ┘ ─label──:─ ├ ┤─PL/I── └ ┘─L────────── └ ┘─PLI───

Note:1 All other operands that can be specified on the corresponding CA control file

statement (see “Control file statement syntax” on page 190) may be specified butare ignored.

where:

labela label that can be used to refer to this statement in subsequent statements.

COBOLindicates that this compilation unit is for a COBOL program.

PL/IPLIindicates that this compilation unit is for a PL/I program.

listdsnamethe data set name of the data set which contains the compiler listing for thisprogram.

* indicates that all listings in the coverage run are of interest. (* cannot be speci-fied in a COBOL or PL/I statement referenced by a TARGETVAR statement.)


SCOPE StatementThe SCOPE statement identifies a name scope in a COBOL or PL/I program whichcontains variables of interest.

Note: The purpose and syntax of the SCOPE target control statement is the sameas that of the SCOPE CA/DA/UTA control statement.

─ ──┬ ┬────────── ─SCOPE─ ──┬ ┬──────────────────────────────── ────────────── └ ┘ ─label──:─ └ ┘──┬ ┬─COBOL─ ─=──cobolplilabel──,─ ├ ┤─PL/I── └ ┘─PLI───

─ ──┬ ┬ ─EXTPROGRAM-ID──=─ ──┬ ┬─extname─ ──┬ ┬─────────────── ───────────────── � │ │└ ┘─L─────── └ ┘─┤ NestedPgm ├─ │ │┌ ┐─.─────────── └ ┘ ──┬ ┬─PROCEDURE─ ─=─ ──┬ ┬───

�┴──┬ ┬─pliname─ ───────────

└ ┘─PROC────── │ │└ ┘─stmt──── └ ┘─L───────────────

NestedPgm:├──,──NESTEDPROGRAM-ID──=─ ──┬ ┬─intname─ ───────────────────────────────────┤ └ ┘─L───────

where:

cobolplilabelA label on the COBOL or PL/I statement that defines the compilation unit con-taining this scope. If this operand is omitted, the default is the previousCOBOL or PL/I statement.

extnameThe COBOL program-id of the external COBOL program which contains itemsto be referenced.

*Indicates that the search for the referenced items is to be done through allexternal COBOL programs in the specified listing.

intnameThe COBOL program-id of the internal (nested) COBOL program which con-tains items to be referenced. This operand should be specified only if the vari-ables of interest are defined in a nested COBOL program. If this keyword isnot specified, the variable is assumed to be defined in the external COBOLprogram.

*Indicates that the search for the referenced items is to be done through allinternal program-ids in the specified external COBOL program-id or through allprocedures in the specified external PL/I procedure in the specified listing.

plinameThe PL/I procedure or BEGIN block which contains items to be referenced. ForPL/I internal procedures, the form PROC1.PROC2 must be used where PROC1is the external procedure and PROC2 is an internal procedure contained inPROC1. Also, in the case of PL/I, named BEGIN blocks are considered to beequivalent to named procedures and are specified in exactly the same way.For unnamed BEGIN blocks, the statement number (stmt) where the BEGINblock is defined is used in place of the procedure name.


For example, PROCEDURE=P0.P1.B1.2451.P3 would specify an external pro-cedure named P0 which contains an internal procedure or named BEGIN blocknamed P1 which contains an internal procedure or named BEGIN block namedB1 which contains an unnamed BEGIN block defined in statement 2451 whichcontains an internal procedure or named BEGIN block named P3.

stmtSee the description of pliname above.

*Indicates that the search for the referenced items is to be done through all PL/Iprocedures and BEGIN blocks in the specified listing.

INCLUDE StatementThe INCLUDE statement can be used to include information from a CA/UTA/DAcontrol file. When such a control file is included, all statements exceptDEFAULTS9, COBOL, PL/I, and SCOPE are ignored.

Note: The INCLUDE statement allows labels defined on these statements to bereferenced on subsequent TARGETVAR and TARGETSTMT control statements.

─ ──┬ ┬────────── ─INCLUDE─ ──┬ ┬─DSNAME──=──dsname─ ──────────────────────── � └ ┘ ─label──:─ └ ┘─DDNAME──=──ddname─

where:

dsnameSpecifies the data set name of the CA/DA/UTA control file to be included.

ddnameSpecifies a ddname which has been previously allocated to a CA/DA/UTAcontrol file.


TARGETVAR StatementThe TARGETVAR statement specifies that all COBOL or PL/I statements that refer-ence a specific variable are of interest.

For COBOL variables, all statements that refer to the specified variable eitherdirectly (via the variable's name) or indirectly (via the name of a containing or con-tained group) are considered to be of interest.

For PL/I variables, only statements that refer to the specified variable directly (viathe variable's name) are considered to be of interest.

The SCOPE specified for a PL/I variable must be the procedure or begin block inwhich the variable is defined (either explicitly or implicitly) although it may be refer-enced in other, contained blocks. This means that the scope for implicitly declaredvariables (other than parameters) must be defined as the external procedure.

The syntax of the TARGETVAR statement is:

──TARGETVAR─ ──┬ ┬───────────────────────── ─NAME──=──(──────────────────── └ ┘─SCOPE──=──scopelabel──,─

─ ─── ───┬ ┬─varname─ ──┬ ┬─────────────────────── ─)───────────────────────── � │ ││ │┌ ┐───────────────────── │ │├ ┤───

�┴──┬ ┬─IN─ ─groupname─

│ ││ │└ ┘─OF─ │ │└ ┘ ──┬ ┬─IN─ ─L───────────── │ │└ ┘─OF─ └ ┘ ──┬ ┬─────────────────── ─varname───── │ │┌ ┐───────────────── ├ ┤───

�┴─structname──.─

└ ┘─L──.──────────────

where:

scopelabel A label on a SCOPE statement that defines the scope con-taining the specified variable. If this operand is omitted, thedefault is the previous SCOPE statement.

varname The name of the variable of interest.

groupname The name of a group containing the referenced variable.

* Specifies that the variable is an unqualified name. In thiscase, all occurrences of this name will be selected irrespectiveof the containing group name(s).

structname The name of a structure containing the referenced variable.


TARGETSTMT StatementThe TARGETSTMT statement identifies specific statements of interest for TargetedSummary. It has the following syntax:

──TARGETSTMT─ ──┬ ┬──────────────────────────────── ─STMTS──=──(─────────── └ ┘──┬ ┬─COBOL─ ─=──cobolplilabel──,─ ├ ┤─PL/I── └ ┘─PLI───

┌ ┐─────────────────── ─ ──┬ ┬───

�┴──┬ ┬─stmt──────── ─)──────────────────────────────────────────── �

│ │└ ┘─stmt1-stmt2─ └ ┘─L───────────────────

where:

cobolplilabel A label on a COBOL or PL/I statement that defines the compile unitcontaining the specified statements. If this operand is omitted, theprevious COBOL or PL/I statement will be used.

* Indicates that all statements in the source listing are to be selected.

stmt One or more statement numbers from the executable statements inthe source listing.

For COBOL listings, use the line number field shown in the com-piler listing (under the LINEID header in the more recent compilers).For statements that span more than one line in the listing, use thefirst line number on which the statement occurs.

For PL/I listings generated by compilers other than VisualAge PL/IVersion 2 Release 2, use the statement number field (STMTheader) if the STMT compiler option is used or use the line numberfield (NUMBER header) if the NUMBER compiler option is used.For PL/I listings generated by the VisualAge PL/I Version 2 Release2 compiler, use the line number field (NUMBER header).

stmt1-stmt2 One or more ranges of statement numbers from the source listing.All statements within the range are selected. stmt1 must not begreater than stmt2.

Example

Cobol ListDsn=YOUNG.SAMPLE.COBOLST(COB01A)

Scope ExtProgram-Id=COB01A

TargetVar Name=(STATE In LOC-ID In TASTRUCT)

TargetStmt Stmts=(46,62,64)

Cobol ListDsn=YOUNG.SAMPLE.COBOLST(COB01C)

Scope ExtProgram-Id=COB01C

TargetVar Name=(TCPARM1)

Figure 33. Targeted Summary control file


Creating Targeted Summary reportsTo create a Targeted Summary report, select option 4 on the Coverage Reportspanel. The Create JCL for Targeted Summary report panel, shown in Figure 34,allows you to specify targeted summary report parameters.

Z [ ---------------------- Generate a Targeted Summary Report ---------------------

Option ===>

1 EditCtl Edit Target Control File

2 ResetCtl Reset Target Control File from system master


4 Edit Edit JCL

5 Submit Submit JCL

6 Foreground Run Targeted Summary in the foreground



Input Files:

Control File Dsn. . . 'YOUNG.SAMPLE.TARGCTL(COB01)'



Listing Type. . . . . COBOL (COBOL|PL/I)


JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(QCOB01)'

Output Summary Type and File Name:


Report Dsn . . . . . 'YOUNG.SAMPLE.COB01.TARGREP'


\ ]

Figure 34. Generate a Targeted Summary Report panel

EditCtlStart an edit session for the control file specified in the Control File Dsnfield.

ResetCtlReplaces the information in the control file specified in the Control FileDsn field with information from the system sample control file (typicallyhi_lev_qual.SATGSAMP).




ForegroundRun Targeted Coverage in the foreground using the parameters youhave specified on the panel.


Use Program Name for File NameTo construct all data set names from the default high-level qualifier, thespecified program name, and the default low-level qualifier for each dataset, enter YES.

When you press Enter, the file names on the panel are changed auto-matically.

Program NameName to use to construct data set names if you enter YES in the UseProgram Name for File Name field. Note that this can be any validname. It does not have to be the name of any of your programs.

Names of the following forms are created:







Control File DsnName of the targeted coverage control data set.

Breakpoint Table DsnName of the breakpoint (BRKTAB) data set created by the coveragerun.

BreakOut DsnName of the breakout (BRKOUT) data set created by the coverage run.

Listing TypeType of CACTL template that is retrieved from hi_lev_qual.SATGSAMPif you select Edit (and the data set or member in the Control File Dsnfield does not exist) or Reset.


Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beQxxxxxxx, where xxxxxxx is the last seven characters of the programname.

TypeType of Targeted Summary report to produce. An Internal summarylists totals for each PA separately. An External summary combines allPAs into one entry per object module.

Report DsnName of the targeted coverage report data set. This data set will becreated if it does not currently exist.



Chapter 9. Using Coverage Assistant in a large projectenvironment

Typically, large projects involve many code developers and testers, the compilationof continually changing application program modules over an extended period oftime, (a process which produces the listings needed by CA), and a testing intervalthat may last many days or weeks. This chapter explains how CA supports thistype of complex testing environment.

Creating CA files during code developmentThe creation of the listings and modified object modules used by CA can be incor-porated into the coder's standard development procedure.

In this chapter:

� Coder refers to the code developer(s) developing multiple compilable objectmodules for a product.

� Tester refers to the person(s) running test cases on the product to obtain testcase coverage data.

� Module refers to a separately compilable object module of the project that hasa listing.

A flow diagram of test case coverage in a large project environment is shown inFigure 35 on page 100.

To create CA files during code development, complete the following steps:

1. Each coder should generate breakpoint data on object modules when they areready to be tested. The breakpoint data could be created automatically by aCA Setup (ATGOSETP program) step included in the coder's compile proce-dure or JCL. At that time, a breakpoint table would be created to match theobject module. In the CA step, you should include a ATGOZAPT program thatuses the breakpoint data and modifies the object module by inserting thebreakpoints.

2. The tester selects the object modules to be measured by CA (created in step1) and links them with the remaining unmodified object modules to create theexecutable load module.

3. The tester enters the names of the modules to be measured by CA into theCACTL.

4. The tester starts a monitor session, runs test cases, and stops the monitor.When the monitor is stopped, it writes its output data to a results file.

5. The tester produces a report on selected modules from the test case coverageresults.

6. The tester performs steps 2 through 4 for as many coders or test case cov-erage runs as desired.

7. For overall test case coverage, the tester combines results from each coder ortest case coverage run into one report.

Chapter 9. Using CA in a large project environment 99

Figure 35. Using CA in a large project environment—flow diagram

Breakpoint dataYou can generate breakpoint data for an object module every time you compile themodule or for any number of listings at the same time. To update the breakpointdata for a module every time you compile, insert a CA Setup step into the coder'scompile job stream.

When the tester is ready to do a test case coverage run, the tester edits theCACTL by entering the file names of each object module to be measured. Whenthe monitor JCL is run, the breakpoint files need to be concatenated as DD state-ments for use by the monitor during the test case coverage run.

Test case coverage resultsIf you stop a monitor session, it writes the test case coverage results for eachmodule to a test case results (BRKOUT) file. To create a Summary and AnnotatedListing report for selected modules, the tester puts their names in the CACTL.These names can be any modules that have been tested in any test coverage run,as long as the results are in a BRKOUT file.


Combining test case coverage resultsTo combine individual test case coverage runs into a report showing overall testcase coverage, the tester executes the CA test case coverage combine program.For an example of combining test case results, see Figure 36.

Figure 36. Combining results of multiple testers—flow diagram

Three test case coverage runs were made, each with a different set of test cases:

� Tester 1 measured modules A, B, and C.� Tester 2 measured modules B, C, and D.� Tester 3 measured modules A, B, and D.

The test case results were put into different BRKOUT files. Run the CA combineprogram to combine the results from the three test case coverage runs into one file.The combined results show the overall test case coverage. A summary or Anno-tated Listing report can then be produced using the combined BRKOUT file.

The BRKTAB files used for the reports must include all modules that have cov-erage in BRKOUT (modules A through D). If the BRKTABs for modules A throughD exist in different files, you can concatenate them in the BRKTAB DD JCL state-ment in the report JCL.


Creating the combine JCL using the panelsTo combine test case coverage results using the panels:

1. Select option 1 from the ATC Primary Option Menu to display the Coverage,Distillation and Unit Test Assistant panel.

2. Select option 4 to display the Coverage Reports panel.

3. Select option 3 to display the Create JCL for Combining Multiple Runs panel,shown in Figure 37.

Z [ -------------------- Create JCL for Combining Multiple Runs ------------------

Option ===>

1 EditCtl Edit Combined Control File

2 ResetCtl Reset Combined Control File


4 Edit Edit JCL

5 Submit Submit JCL


Use Program Name for File Name YES (Yes|No) Program Name COB06M

Combined Control File:

Combined Cntl Dsn . . 'YOUNG.SAMPLE.CBCTL(COB06M)'


JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(CCOB06M)'

Combined Breakout File:

Breakout Dsn. . . . . 'YOUNG.SAMPLE.COB06M.CMBOUT'

\ ]

Figure 37. Create JCL for Combining Multiple Runs panel

4. Select option 1 and change the values entered in each field as appropriate.


EditCtlEdit the combined control file.

ResetCtlReset the combined control file.

GenerateGenerate JCL using the parameters you have specified on thepanel.



Use Program Name for File NameIf you want to construct the data set names from the default high-level qualifier, the specified program name, and the default low-levelqualifier for each data set, enter YES. Using the program name isthe normal CA procedure.


When you press Enter, the file names on the panel are changedautomatically.

Program NameName to use for CA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.








Combined Cntl DsnName of the data set containing the list of breakout data sets youwant to combine.


Note: If Use Program Name for File Name is set to YES, then themember name or program name qualifier of the data set will beCxxxxxxx, where xxxxxxx is the last seven characters of theprogram name.

Breakout DsnName of the combined BRKOUT data set created by running thecombine JCL.

5. The EditCtl option puts you into an ISPF edit session in which you list thedata sets to be combined (see Figure 38 for an example). You must enter thecomplete data set name for each data set.

Z [EDIT YOUNG.SAMPLE.CBCTL(COB06M) - 01.00 Columns 00001 00072

Command ===> Scroll ===> CSR

LLLLLL LLLLLLLLLLLLLLLLLLLLLLLLLLLLL Top of Data LLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

000001 L

000002 L List the input files (PDS or SEQ) you wish to combine (one per line),

000003 L using JCL naming conventions. All comment lines must start with 'L'.

000004 L

000005 YOUNG.SAMPLE.BRKOUT(COB06M1) <= Input DSN 1




000009 <= Input DSN 5

000010 <= Input DSN 6

000011 <= Input DSN 7

000012 <= Input DSN 8

000013 <= Input DSN 9

000014 <= Input DSN 10

LLLLLL LLLLLLLLLLLLLLLLLLLLLLLLLLLL Bottom of Data LLLLLLLLLLLLLLLLLLLLLLLLLLLL

\ ]

Figure 38. ISPF edit screen for combining results


Rules for combining resultsTwo coverage runs will be combined only if there were no changes to the programbetween coverage runs. The combine program checks to ensure that eachprogram area contains the same number of breakpoints (statements) in theBRKTAB file. The following coverage runs will be combined:

1. Run Setup, create BRKTAB file2. Coverage run 1 uses BRKTAB file3. Coverage run 2 uses same BRKTAB file

The following coverage runs will not be combined because the program haschanged (contains a different number of statements).

1. Run Setup, create BRKTAB1 file2. Coverage run 1 uses BRKTAB1 file

3. Modify program4. Rerun Setup, create new BRKTAB2 file5. Coverage run 2 uses BRKTAB2 file

If Setup is rerun, but the program has not changed (i.e., it contains the samenumber of statements), the combine program will combine the results.

Measuring coverage for individual test casesTesters may want to keep coverage results on a test case basis. This allows themto run test cases for regression testing of fixes that affect only a few modulesinstead of running all of the test cases.

Test case coverage results are saved in a BRKOUT file if the monitor is runningand the tester issues either the ATGSNAP or ATGSTOP command. When thesecommands are executed, the tester can select the file name of the BRKOUT file.

For example:

XTEST2 Start the monitor

TEST2 parm1 Run TEST2 for test case 1

ATGSNAP TC1 Save the coverage results in file proj_qual.TC1.BRKOUT

ATGRESET Reset statistics


ATGSNAP TC2 Save the coverage results in file proj_qual.TC2.BRKOUT

ATGRESET Reset statistics


ATGSTOP TC3 Save the coverage results in file proj_qual.TC3.BRKOUT

and stop the monitor session

The BRKOUT files TC1, TC2, and TC3 contain coverage results for their respectivetest cases. Testers can run the CA report program on the BRKOUT files to obtaincoverage results for the specific test cases. To obtain overall coverage, executethe Combine program on TC1, TC2, and TC3.


Part 4. Using Distillation Assistant

Part 4. Using Distillation Assistant 105




� What is Distillation Assistant?� What does DA require?� How does DA work?� Where can you get further details?

What is Distillation Assistant?Distillation is the reduction of a data set to the minimum size that provides thesame test coverage as the complete data set. Distillation Assistant (DA) supportsdistillation of QSAM or VSAM input data sets that are processed by applicationsgenerated with the following IBM COBOL and PL/I compilers:



(5654-MLE)� VS COBOL II Version 1 Release 4.0 (5688-022, 5688-023)� OS/VS COBOL Version 1 Release 2.4 (5740-CB1, 5740-LM1)� IBM PL/I for MVS & VM 1.1.1 (5688-235)� VisualAge PL/I Millennium Language Extensions for MVS & VM 1.0

(5648-MLX)� OS PL/I Optimizing Compiler 2.3.0 (5668-909, 5668-910, 5668-911)� OS PL/I Optimizing Compiler 1.5.1 (5734-PL1, 5734-PL3, 5734-LM4,

5734-LM5)

Note that although the VisualAge PL/I Compiler Version 2 Release 2 (5655-B22) issupported by Coverage Assistant and Source Audit Assistant, it is not currentlysupported by Distillation Assistant.

While the program under test is running, DA records all logical keys (for data readfrom a specified input data set) that cause new coverage. When you have com-pleted testing, you can run a DA program that makes a copy of your input data set,but includes only the records that have these keys. Further testing using this dis-tilled input data set results in much faster test runs with coverage that is equivalentto that produced by using the complete input data set.

For example, your input master data set may contain thousands of employee orcustomer records. DA may distill the input master data set to several hundredrecords that caused new coverage during your original test run. Further testingtime is greatly reduced by using the distilled input master data set.

The distillation process consists of two steps:

Step 1 Logical distillation

This step consists of instrumenting your object code and executing theinstrumented code under the DA monitor. As the instrumented codereads records from the specified input master data set, the monitor

Chapter 10. Introduction to DA 107

determines which “keys” in the input master data set caused new codecoverage in the instrumented code. The list of these keys is thensaved for the second step.

Step 2 Physical distillation

This step consists of creating a new master data set by reading the listof keys produced in the first step and the input master data set. Thenew master data set consists of only those records in the input masterdata set whose logical key appears in the list of keys.

DA has the following characteristics:

� Low overhead

For a test case run, DA typically adds very little to the execution time of theprogram. DA inserts user SVC instructions as breakpoints and then interceptsthe interrupts.

� Panel-driven user interface

You can use an ISPF panel driven interface to create JCL for executing DAprograms.

� Simple, flexible control

The control file used to define your input master data set provides a simplemethod of controlling DA operations.

What does DA require?DA runs under MVS. Detailed MVS system resource requirements for DA aredescribed in “DA and UTA resources” on page 362. DA uses ISPF services todisplay dialogs and to produce the JCL to run the DA steps.

Input master data set restrictionsThe input master data set can be any sequential or VSAM data set which containslogical10 keys. However, note the following input master data set restrictions:

� If the data set is sequential, the RECFM may be any valid MVS RECFM exceptVS and VBS. Spanned records are not supported.

� VSAM data sets with either KSDS or ESDS organizations can be distilled.However, VSAM data sets that have alternate indexes will not have the corre-sponding alternate indexes built into the new master data set.

� Any type of VSAM data set that cannot be distilled directly, can be copied usingthe IDCAMS REPRO function to a sequential data set, which can be distilledand copied back to a VSAM data set.

In addition to the previously described restrictions, the logical keys:

� Cannot exceed 126 bytes in length� Must appear at the same offset in each record� Must be the same length in each record

10 A logical key is simply a field which can be used to identify the record. These need not be defined as physical keys. Forexample, a VSAM ESDS or a sequential data set can be distilled as long as a field exists that can be logically used as a key.


Logical distillation requirementsDA requires, as part of its input, listings created by the application program com-pilers that it supports. These compilers offer options that allow you to includeassembler statements, data maps, and data cross-references in the listings, all ofwhich DA uses.

DA also requires the application program object modules as input. DA createscopies of these object modules with breakpoints inserted into them.

See “Execution” on page 112 for a description of how the DA authorized programsintercept breakpoints.

Notes:

1. Logical distillation cannot be performed on more than one physical file ata time. This means that if more than one FILE control statement is specifiedfor a logical distillation run, all of the specified COBOL FDs or PL/I file con-stants must resolve to the same DDNAME.

2. UTA variable monitoring should not be done in conjunction with DA key gath-ering. If the two are performed at the same time, the variable reads are inter-mixed with the keys, and no process is provided for separating them.

3. PL/I distillation does not support the following constructs:

� Stream I/O. Only record I/O is supported.

� Files which have the ENVIRONMENT(TOTAL) attribute.

� READ operations on file variables. Only READs of file constants are sup-ported.

� READ statements that specify the EVENT option.

4. COBOL distillation is not supported under CICS for routines compiled with theOS/VS COBOL compiler. Reentrant COBOL routines are only supported forcompilers that support the RENT compiler option.

How does DA work?Running DA consists of the following steps. This list is an overview of the process.Each activity is described in more detail in topics that follow in this chapter.

Step 1 Setup


b. Generate DA JCL using the DA ISPF dialog:

1) Edit the DA control file.2) Create the Setup JCL.3) Create the monitor JCL.4) Create the distillation JCL.

c. If you instrumented object modules, edit your program’s link-editJCL to pick up the modified object modules, which are created bythe Setup step.


d. Edit your program’s GO JCL (or program invocation) to point to thenew load module that will be created when you run the JCLcreated in step 1c.

Step 2 Execution

a. Run the Setup JCL (created at step 1b2).

b. Run the link-edit JCL (created at step 1c).

c. Run the monitor JCL to start a monitor session (created at step1b3).

d. Run your application using the load module(s) created in step 2b.

e. Stop the monitor session (using the ATGSTOP command).

Step 3 Distillation

Run the distillation JCL (created at 1b4 on page 109).

If you change your program and want to rerun the test cases, you must repeat step1a using the changed source code, and then complete steps 1b through 3 again.

Figure 39 on page 111 shows a diagram of the entire process.


Figure 39. DA—flow diagram


SetupDA Setup analyzes assembler statements and cross-reference information includedin the compiler output listings to determine where to insert breakpoints into disk-resident copies of the object modules. It then inserts the breakpoints.


1. Compiler listings of the object modules2. The object modules or load modules you want to test3. The user control file listing the input data set to distill


1. Modified test programs (object modules or load modules) containing break-points

2. A file of breakpoint-related information (called BRKTAB in this User's Guide)required for the monitor program in the Execution step

3. A file of data for the data set to be monitored (called DBGTAB in this book)

4. A file of locations where the input data set is read by the monitor (calledVARCTL in this User's Guide)


Then start a DA monitor session and run your test case programs. As the selectedbreakpoints are encountered, the monitor gains control, logs a key if it caused newcoverage, then returns control to your program. After your test cases have com-pleted, use ATGSTOP to stop the monitor session. It writes the results (the list ofkeys that caused new coverage) to a file called VARTAB.



Physical distillationDA physical distillation has two steps:

1. Format the list of keys that caused new coverage (the VARTAB file created byexecution step).

2. Distill the input master data set.

The key list from step 1 is used in step 2 to make a distilled copy of your inputmaster data set.

You can create JCL to run these two steps consecutively, or you can create JCL torun each step separately. If you run the steps separately, you can inspect and editthe key list to produce a customized distillation data set.


For example, you may want to include keys in a distilled data set even though theydid not cause new coverage, or you may want to remove keys that caused newcoverage, but are not important to your testing.



Samples of DA test case coverage,including sample reports

Chapter 11, “Distillation Assistantsamples” on page 115

Editing the CACTL file that contains thenames of the listing data sets

Chapter 13, “Editing the DistillationAssistant control file” on page 129



Starting the DA monitor session andrunning test cases on your programs


Commands that control the DA monitorprogram


Distilling your data Chapter 14, “Physical distillation” onpage 133

System resources needed by DA “DA and UTA resources” on page 362



Chapter 11. Distillation Assistant samples

This chapter describes a sample distillation using an example provided with theATC package.

Distillation Assistant (DA) performs the distillation based on information that youspecify in the control file.

This sample distills data read by the COBOL and PL/I test cases:

� COB03 (COBOL sample)� PLI02 (PL/I sample)

A flow diagram of the steps required to run these samples is shown in Figure 40on page 116. The names in the steps are the member names of the JCL executedfor the step. For COBOL, the steps are jCOB03. The PL/I steps are jPLI02. In theflow diagram, ccc is the compiler identification: COB for COBOL (for example,SCOB03) or PLI for PL/ I (for example, SPLI02). The first letter of the JCL memberused for that step is j.

The following DA samples use the ATC ISPF dialog to create the JCL to run theDA steps. The ATC ISPF dialog is provided as an aid in creating the JCL. Oncethe JCL is created for a test environment, it does not have to be recreated from thedialog. In a typical user test environment, the creation of the JCL can be incorpo-rated into the user's procedures. You do not have to use the ISPF dialog to useDA.


Chapter 11. DA samples 115

Figure 40. Sample run—flow diagram


COB03 and PLI02 test casesThe COB03 (for COBOL) and PLI02 (for PL/I) test cases are examples of reading afile from one compile unit. The control files are shown in Figure 43 on page 120and Figure 44 on page 120, the input master data set is shown in Figure 41 onpage 118, and the new master data set is shown in Figure 42 on page 118. Inthe following descriptions, the test cases are referred to as cccnn, where ccc is thecompiler (COB for COBOL or PLI for PL/I).

Breakpoints are inserted into the object modules during Setup. These breakpointsare positioned so that the reads of the specified file can be monitored when thebreakpoint interrupt occurs. When you are ready to test your program, you link theobject modules that have been modified with the breakpoints.

To distill the input master data set read by cccnn, perform the following steps.steps 2a through 6 are described in more detail in topics that follow in thischapter.

1. Compile the source you want to test. This produces listings that include theassembler statements needed by DA.




The ATC Primary Option Menu is displayed.

a. Edit the DA control file.

Verify that the control file includes the listings of the object modules youwant to test and information about the file that you want to distill.


Create the JCL that enables the Setup job to produce files containingbreakpoint data, file read data, and instrumented programs.

c. Create the monitor JCL.


d. Create the JCL to perform the physical distillation.

Create the JCL to perform the physical distillation after the cccnn test casehas executed.



After the Setup step, and before starting the monitor session, you must link themodified object modules into an executable program you can test. Specify thelibrary that will contain the modified object modules and the library that willcontain the modified load module.



Edit the JCL to run your program. Specify the same modified load module asin step 4 on page 117.

6. Execute the JCL.

Execute the created JCL files for cccnn in the correct order. (This order isshown in “Execute the JCL” on page 122.)

Figures 41 and Figure 42 show portions of the input master data set and new (dis-tilled) master data set for this example.

%%Lincoln's Ge4a++++++++++++++0402ttysburg Address, given November 19, 1863

%%Four score a8b++++++++++++++5154nd seven years ago, our fathers brought fo

%%dedicated to9c++++++++++++++1108 the proposition that all men are created

%%Now we are e5d++++++++++++++8036ngaged in a great civil war. . .testing wh

... 21 Line(s) not Displayed ...

%%can long end1e++++++++++++++6086ure. We are met on a great battlefield of

%%to that caus7a++++++++++++++7844e for which they gave the last full measur


%%that this na3b++++++++++++++1954tion, under God, shall have a new birth of

%%Four score a5h++++++++++++++4984nd seven years ago, our fathers brought fo


%%dedicated to4i++++++++++++++0805 the proposition that all men are created

%%Now we are e8j++++++++++++++7778ngaged in a great civil war. . .testing wh

%%can long end1k++++++++++++++0571ure. We are met on a great battlefield of

%%We have come5l++++++++++++++3642 to dedicate a portion of that field as a

%%It is altoge6m++++++++++++++3062ther fitting and proper that we should do

%%But, in a la5n++++++++++++++0198rger sense, we cannot dedicate. . .we cann

%%who struggle4o++++++++++++++4265d here have consecrated it, far above our

%%what we say 1p++++++++++++++4415here, but it can never forget what they di

%%It is for us7q++++++++++++++3956 the living, rather, to be dedicated here


%%It is rather7r++++++++++++++6855 for us to be here dedicated to the great

%%to that caus2s++++++++++++++3218e for which they gave the last full measur

%%that this na7n++++++++++++++1182tion, under God, shall have a new birth of


%%shall not pe8o++++++++++++++9571rish from this earth.

%%Lincoln's Ge5p++++++++++++++6657ttysburg Address, given November 19, 1863

%%Four score a2q++++++++++++++1631nd seven years ago, our fathers brought fo

%%We have come6v++++++++++++++5217 to dedicate a portion of that field as a


%%It is altoge4w++++++++++++++3135ther fitting and proper that we should do

%%But, in a la4x++++++++++++++3418rger sense, we cannot dedicate. . .we cann

%%shall not pe2k++++++++++++++3999rish from this earth.

Figure 41. Input master data set for COB03 and PLI02

%%Lincoln's Ge4a++++++++++++++0402ttysburg Address, given November 19, 1863

%%Four score a8b++++++++++++++5154nd seven years ago, our fathers brought fo

%%It is for us1z++++++++++++++0649 the living, rather, to be dedicated here

%%shall not pe8f++++++++++++++4843rish from this earth.

%%It is for us7q++++++++++++++3956 the living, rather, to be dedicated here


%%shall not pe6x++++++++++++++7555rish from this earth.

%%Lincoln's Ge5p++++++++++++++2033ttysburg Address, given November 19, 1863

%%that this na7n++++++++++++++1182tion, under God, shall have a new birth of

%%dedicated to6r++++++++++++++5167 the proposition that all men are created

%%It is for us8l++++++++++++++1857 the living, rather, to be dedicated here

%%shall not pe2k++++++++++++++3999rish from this earth.

Figure 42. New (distilled) master data set for COB03 and PLI02



that it will run on your system.




d. Remove any comment characters next to the COB03 or PLI02 membernames.

2. Execute the JCL.


Edit the DA control fileDA uses assembler listings to determine where to insert breakpoints to monitor filereads. You supply the names of the listing files and data on the variables to readin each listing in the DA control file (CACTL).

The CACTL control file for this example is shown in Figure 43 on page 120.

To edit the CACTL for the cccnn example:



2. Select option 1 from the Coverage, Distillation and Unit Test Assistant panel.


3. Enter option 1 and specify the following:

Use Program Name for File Name YES

Program Name cccnn

Listing Type COBOL or PLI

4. Press Enter.

An ISPF edit session for the DA control file you requested is displayed.

The data in the control file consists of the following types of statements:

COBOL or PLIIndicates that the program is a COBOL (or PL/I) program and speci-fies information about the compiler listing, object module, and loadmodule.

SCOPESpecifies information about the scope of the program in which thefile of interest is defined.

FILESpecifies information about the file that is to be distilled, includinglogical key information.



5. Verify that the listing file names and the copy to/from object module names arecorrect for your installation. Typically, these will be the same as shown infigures 43 or 44, except that your TSO ID prefix is used as each data set'shigh-level qualifier.


For more detailed information about the control file, see Chapter 13, “Editing theDistillation Assistant control file” on page 129.

COBOL ListDsn=YOUNG.SAMPLE.COBOLST(COB03),

LoadMod=COB03,



Scope ExtProgram-Id=COB03

File File=QSAMIN,KeyPosition=15,KeyLen=20


PL/I ListDsn=YOUNG.SAMPLE.PLILST(PLI02),

LoadMod=PLI02,



Scope PROCEDURE=PLI02

File File=QSAMIN,KeyPosition=15,KeyLen=20,Stmts=38

Figure 44. Control file for PLI02

Create Setup JCLBefore the cccnn program can be monitored, DA must insert breakpoints into thetest program. DA does this using the Setup program. When you execute theSetup JCL, the DA Setup program analyzes the assembler listings and creates atable containing breakpoint data (address, op code, and so on). User SVCinstructions are inserted for the instructions at the breakpoints in the objectmodules. You then link the modified object modules into an executable loadmodule for DA to use.




2. Select option 2.

The Create JCL for Setup panel is displayed. You create the JCL for the Setupof cccnn from this panel. All of the default values on the panel are correct forthe cccnn examples except for possibly the Enable DA and the ProgramName fields.


3. Ensure that Enable DA is set to Yes, that Enable UTA is set to No, and that theentry in the Program Name field is correct.

4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername Scccnn.



Create JCL to start a monitor sessionTo create the JCL to start a monitor session:



2. Select option 3.

The Create JCL to Start the Monitor panel is displayed. You create the JCL forthe DA execution of cccnn from this panel.

3. Ensure that Enable DA is set to YES and that the entry in the Program Namefield is correct.

4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername Xcccnn.


Use the monitor JCL to start a monitor session before you run your test caseprogram. Note that you can perform DA execution on a system other than theone on which you have stored the listing.


Create physical distillation JCLTo create the physical distillation JCL:



2. Select option 5.

The Distillation panel is displayed.

3. Select option 3.

The Generate JCL to Generate Key List and Distill Data panel is displayed.


4. Specify the following:

� Enter 'prefix.SAMPLE.cccnn.MASTER' in the Master Data Dsn field.� Enter 15 in the Key Position field.� Enter 20 in the Key Length field.� Enter the name you would like to give to the new (distilled) master data set

in the Distilled Master Dsn field.� Enter cccnn in the Program Name field.

5. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername Dcccnn.


Edit JCL to link the modified object modulesEdit the sample link-edit JCL that was copied from hi_lev_qual.SATGSAMP so thatit will run on your system, use your local library names, and use your sample dataset names.

Edit JCL to run the GO stepEdit the sample GO JCL that was copied from hi_lev_qual.SATGSAMP so that itwill run on your system, use your local library names, and use your sample data setnames.

Execute the JCLWhen you have created all of the cccnn JCL, you can run the cccnn example byexecuting the following functions in the order listed. To see a flow diagram of thesesteps, see Figure 40 on page 116

1. Scccnn11


2. Lcccnn12

Links the object modules that have been modified with breakpoints in the Setupstep into the cccnn load module.

3. Xcccnn11

Starts a monitor session. For DA, a program continuously runs to write variabledata to disk. The JCL does not complete until your session is stopped by step6 on page 123.

4. Gcccnn12

Runs sample program cccnn. cccnn runs to completion with condition code 0.




5. ATGSTATS13

Displays statistics using the ATGSTATS command. You should see a nonzeroEVNTS count in the TOTALS line. (This is an optional step for illustrative pur-poses.)

6. ATGSTOP13

Stops the monitor session. DA writes the variable data to disk.

7. Dcccnn11

Performs the physical distillation for cccnn.






Chapter 12. Logical distillation

This chapter contains information about logical distillation. Logical distillation is theprocess of instrumenting your object code and executing the instrumented codeunder the Distillation Assistant monitor. As the instrumented code reads recordsfrom the specified input master data set, the monitor determines which keys in theinput master data set caused new code coverage in the instrumented code. Thelist of these keys is then saved for the physical distillation process, which isdescribed in Chapter 14, “Physical distillation” on page 133.

Description of reading input data setsAfter each read of the input data set that you specified in the Setup step, DA readsand saves the associated key. Breakpoints are inserted in your program so thatnew statement and conditional branch coverage can be measured. Whenever astatement is executed for the first time, the last key read is saved (if not previouslysaved). Whenever a condition in a conditional statement (for COBOL: IF,PERFORM, EVALUATE, and GO; for PL/I: IF, DO/END, and SELECT) takes a newpath, the last key read is saved (if not previously saved). After termination of yourtest run using the DA command ATGSTOP, this list of saved keys is written to disk.

Coverage of the distilled data setNo distilled data set will give equivalent coverage in all cases.

For example, your input data set may be customer purchase records. You may dospecial processing for customers whose total purchases exceed $1000. DA willrecord the key of the first customer record that caused the $1000 total to beexceeded. However the distilled data set will probably not contain all of the pur-chase records that totaled $1000. Therefore the path to process the $1000 cus-tomer totals will never be executed while running the distilled data set. In general,any “quantity” type paths executed while processing your input master data set willnot be executed while processing the distilled data set.

PL/I ON-unitsIf an ON-unit that handles an input condition in a PL/I program returns control to astatement following a READ for which distillation data is being recorded, themonitor cannot tell whether valid data was read or not. This may result in the pre-vious record being included in the distilled output, even if it did not cause anyunique coverage.

For example, an ON ENDFILE condition that returns control to the point after theREAD causing the condition will cause the last record in the master data set to beincluded in the distilled data set, even though the end of file occurred after it hadbeen processed.

Chapter 12. Logical distillation 125

How much data can be readOne read of the input data set can save up to 126 bytes of key data.

Keys that cause new coverage are kept in storage buffers while your program isrunning, and periodically the keys are written to disk. Two buffers are used: one iswritten to disk while the other is being used. It is possible that the buffers could befull when a new key is to be written to the buffer. However, this is unlikelybecause:

1. Very few keys cause new coverage, and little data is written to the buffers.The size of each buffer is 65536 bytes. Each data entry contains the key pluseight bytes of other data.

2. To cause a new key to be read, the user program must do I/O. This allowstime for the buffer monitor program to write any full buffers to disk.

If a buffer overrun occurs and causes loss of new key data, you will see a state-ment similar to the following in the VARDATA file of key data:

11915 1 1 38 KYLEX 3722AIX.

11916 1 1 38 KYLEX 3723AIX.

LLLLLLLL !!! BUFFER OVERFLOW !!! LLLLLLLL

11917 1 1 38 KYLEX 0000MVS.

If a buffer overflow occurs, the program that creates the VDR report of variabledata (stepname ATGOMVAR) completes with a return code of 4.

Recording which keys execute a statementYou can produce an Annotated Listing report (similar to the Coverage Assistantreport described in “COBOL Annotated Listing reports” on page 49, or “PL/I Anno-tated Listing report” on page 55) that contains the key numbers that first executeeach statement. Figure 45 shows the portion of an Annotated Listing report thatlists these numbers.

000133 101-CASE.

000134 : ADD 1 TO WS-COUNT-101. 68 >0001 0001 <

000135

000136 102-CASE.

000137 : ADD 1 TO WS-COUNT-102. 69 >0001 0016 <

000138

000139 103-CASE.

000140 : ADD 1 TO WS-COUNT-103. 70 >0001 0017 <

000141

000142 104-CASE.

000143 : ADD 1 TO WS-COUNT-104. 71 >0001 0010 <

000144

000145 105-CASE.

000146 : ADD 1 TO WS-COUNT-105. 72 >0001 0013 <

000147

000148 106-CASE.

000149 : ADD 1 TO WS-COUNT-106. 73 >0001 0008 <

000150

000151 107-CASE.

000152 : ADD 1 TO WS-COUNT-107. 74 >0001 0003 <

000153

Figure 45. Partial Annotated Listing report for COB03 showing key numbers


In addition to the annotation symbols on each executable statement that appear onthe left, two columns of numbers appear to the right of each statement withinbrackets:

� The number in the first of these columns is the number of times the statementwas executed

� The number in the second column is the key number of the key that firstcaused the statement to execute.

In most cases, DA removes the breakpoint the first time that the statement is exe-cuted, therefore the count on most lines will be one. However, the breakpoint onthe file read statement in the file being distilled is left in for the entire execution.The count shown on this line will show how many reads to the file were executed.

The key number refers to the keys listed in the DA Key List of keys that causednew coverage.

In Figure 45 on page 126, key 1 (with key 4a) caused 101-CASE to execute first,and key 16 (with key 7n) caused 102-CASE to execute first.

You create an Annotated Listing with key data by changing your defaults beforegenerating the Setup JCL. To change your defaults:

1. Select option 0 from the ATC Primary Option Menu.This displays the Manipulate ATC Defaults panel.

2. Select option 1.The ATC Defaults panel is displayed.

3. In the Setup Defaults area of the panel, change Frequency Count Mode toYES.

Complete the remaining DA steps to run the program under test.

Then generate the annotated listing with key data by executing a CA AnnotatedListing report, as described in “Creating Summary and Annotated Listing report JCLusing the panels” on page 64.

Chapter 12. Logical distillation 127


Chapter 13. Editing the Distillation Assistant control file

This chapter describes the function of the control file (CACTL) used by DA. TheCACTL contains information that tells DA what compile units to analyze and the filethat is to be monitored. CA, DA, and UTA share the CACTL file. See Chapter 21,“CA, DA, and UTA control file” on page 187 for a complete description of thiscontrol file. This chapter only explains how to use the control file with DistillationAssistant.

Contents of the control fileThe control file consists of a series of lines that specify information about the file tobe distilled. The following describes the contents of the control file as it is used byDA. See “Contents of the control file” on page 189 for a description of the syntaxof the control file.

� The COBOL statement specifies the following:

– The source language (COBOL)

– The data set containing the compiler listing file

– The name of the load module containing the program

– The data set containing either the object code generated by the complier orthe load module created by the linkage editor/binder

– The data set that is to contain either the instrumented object code gener-ated by the Setup job or the instrumented load module generated by theSetup job

� The PL/I statement specifies the following:

– The source language (PL/I)

– The data set containing the compiler listing file


– The data set containing either the object code generated by the complier orthe load module created by the linkage editor/binder


� The SCOPE statement specifies the following:

– COBOL

- The PROGRAM-ID of the external program in which the file is defined.The external program ID is the first program ID in the listing file.

- The PROGRAM-ID of the nested (internal) program in which the file isdefined. This operand is required only if the file is defined within anested program.

– PL/I

- The name of the procedure or begin block in which the file is defined.

Chapter 13. Editing the DA control file 129

� The FILE statement specifies the following:

– That all reads of the specified file are to be monitored

– For COBOL, the FD name of the file to be monitored

– For PL/I, the name of the file constant to be monitored

– The position and length of the logical key within the file

– For PL/I, the statement number where the file is read.

When performing distillation, you would normally want to monitor all reads of the fileas is done using the statements previously described. If, however, for some reasonyou only want to monitor reads into a specific variable or group, the FILE statementpreviously described could be replaced by a VARIABLE and COVERAGE state-ment specifying the FILE option (for COBOL only). The syntax of these statementsis described in “Contents of the control file” on page 189.


ExamplesThe following figure shows an example of a file read in a COBOL program:

COBOL ListDsn=YOUNG.SAMPLE.COBOLST(COB03),

LoadMod=COB03,




File File=QSAMIN,KeyPosition=15,KeyLen=20

Figure 46. CACTL statements for distillation (COBOL)

The example in Figure 46 is based on the following COBOL declarations:

IDENTIFICATION DIVISION.

...

DATA DIVISION.

FILE SECTION.

FD QSAMIN

RECORDING MODE IS F

BLOCK CONTAINS 0 RECORDS

LABEL RECORDS ARE STANDARD.

01 INPUT-RECORD PIC X(76).

EJECT

WORKING-STORAGE SECTION.

...

Figure 47. COBOL file definition. All reads for the file QSAMIN are monitored. Whenever arecord causes new code coverage, the key field located in columns 15 to 34 of the record issaved.

The following figure shows an example of a file read in a PL/I program:

PL/I ListDsn=YOUNG.SAMPLE.PLILST(PLI02),

LoadMod=PLI02,




File File=QSAMIN,KeyPosition=15,KeyLen=20,Stmts=38

Figure 48. CACTL statements for distillation (PL/I)

Chapter 13. Editing the DA control file 131


Chapter 14. Physical distillation

This chapter describes physical distillation. Physical distillation is the process ofcreating a new master data set by reading the list of keys produced in the logicaldistillation step (described in Chapter 12, “Logical distillation” on page 125) and theinput master data set. The new master data set consists of only those records inthe input master data set whose logical keys appear in the list of keys.

Physical distillation summaryThe physical distillation process has two steps:

1. Format the list of keys that caused new coverage from the data saved by theexecution monitor.

2. Use this key list to distill the input master data set.

You can create JCL to run these two steps consecutively, or you can create JCL torun each step separately. If you run the steps separately, you can inspect and editthe key list to produce a customized distillation data set. For example, you maywant to include keys in a distilled data set even though they did not cause newcoverage, or you may want to remove other keys that caused new coverage, butare not important to your testing.

Before the physical distillation begins, the new master data set is, in most cases,deleted if it currently exists, and allocated with the attributes of the input masterdata set. The exceptions to this rule are:

� If the new master data set is a member of a partitioned data set, the data set isnot deleted and reallocated. However, if the attributes of the new master parti-tioned data set do not match those of the input master data set, the physicaldistillation process is ended.

� If a volume is specified for the new master data set, the data set is not deletedand reallocated. However, if the attributes of the new master data set do notmatch those of the input master data set, the physical distillation process ends.

� If the new master data set is on tape, no check is made to see if the data setexists; the specified file on the tape is simply rewritten.

Chapter 14. Physical distillation 133

The following table shows the input/output combinations that are supported:

Table 11. Supported input/output combinations

Input

Output

seq pds(mem) vsam

Exists New Exists New Exists New

seq del/realloca alloc like add/replace no no no

pds(mem)nob no add/replace alloc like

addno no

vsam no no no no del/realloca alloc like

Notes:

del/realloc Delete and reallocate like input data set.add/replace Add or replace member in existing PDS.add Add member in existing PDS.alloc like Allocate like input data set.

a If the volume/unit is specified for the output data set, no del/realloc will be done (the output data set will bereused).

b If the volume/unit is specified for the output data set, pds(mem) to seq is allowed.

Parameters used by physical distillationThe inputs to the physical distillation process are:

� Input master data set� Input master data set's volume� Input master data set's unit� Key position in master data set� Key length in master data set

Outputs from the logical distillation process are:

� Debug table � Variable table

The following intermediate files are created during the physical distillation process:

� Variable ID file� Variable data file

The physical distillation process creates the new master data set.


Running physical distillationYou generate the JCL to run the physical distillation from the Distillation panel. Todisplay the Distillation panel:


The Coverage, Distillation and Unit Test Assistant panel is displayed.2. Select option 5.

The Distillation panel is displayed.3. Select option 3.14

The Create JCL to Generate a Key List and Distill Data panel, shown inFigure 49, is displayed. From this panel, you can select whether you want toprocess a DASD or tape data set for physical distillation.

Z [ -------------- Create JCL to Generate a Key List and Distill Data -------------

Option ===>

1 Distill DASD Create JCL to Generate a Key List and Distill DASD Data

2 Distill Tape Create JCL to Generate a Key List and Distill Tape Data


\ ]

Figure 49. Create JCL to Generate a Key List and Distill Data panel

The panel's options are as follows:

Distill DASDCreates the JCL required to perform both steps in the physicaldistillation. Use this option when the new distilled master data setwill be stored on DASD (direct access storage device).

Distill TapeCreates the JCL required to perform both steps in the physicaldistillation. Use this option when the input master data set is on tapeand the new distilled master data set will be stored on tape.

14 If you would like to edit the key list after it is produced, you can select the KeyList option (option 1) to generate the key list andedit it. Select the DistillKey option (option 2) to complete the distillation. Because the fields used in these options are verysimilar to those used in the Distill option, they are not discussed here.


Generating JCL for physical distillationTo generate the JCL required for physical distillation, select the appropriate gen-erate option (option 1 or 2) from the Create JCL to Generate a Key List and DistillData panel. Either of these options allow you to perform both steps of the physicaldistillation.

If you select option 1, the Create JCL to Generate a Key List and Distill DASD Datapanel, shown in Figure 50, is displayed. If you select option 2, the Create JCL toGenerate a Key List and Distill Tape Data panel, shown in Figure 51 on page 139,is displayed.

The following topics describe how to complete these panels.

Generating JCL for DASDIf the new distilled master data set will be stored on DASD, complete the CreateJCL to Generate a Key List and Distill DASD Data panel as described in this topic,and then press Enter. This panel allows you to generate, edit, or submit the JCLrequired for both steps of the physical distillation: (1) generate a key list, and (2)distill the new master data set from the input master data set.

Z [ ----------- Create JCL to Generate a Key List and Distill DASD Data -----------

Command ===>


2 Edit Edit JCL

3 Submit Submit JCL


Input Master File:

Master Data Dsn . . . 'YOUNG.SAMPLE.COB03.MASTER'

Volume Serial . . . . Unit . . (If not cataloged)

Key Position . . . . 15 (1 is first character of record)

Key Length . . . . . 20

Output Master File:

Distilled Master Dsn SAMPLE.COB03.DISTILL

Volume Serial . . . . Unit . .


Input Files:

Debug Table Dsn . . . 'YOUNG.SAMPLE.COB03.DBGTAB'

Variable Table Dsn. . 'YOUNG.SAMPLE.COB03.VARTAB'


JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(DCOB03)'

Output Files:

Variable ID Dsn . . . 'YOUNG.SAMPLE.COB03.VARID'


Variable Data Dsn . . 'YOUNG.SAMPLE.COB03.VARDATA'

\ ]

Figure 50. Create JCL to Generate a Key List and Distill DASD Data panel






Master Data DsnData set name of the input master data set to be distilled.

Volume SerialVolume on which the data set resides.

UnitDevice on which the data set resides.

Key PositionPosition of the logical key in each input master data set record. Position1 is the first byte of the record.

Key LengthLength of each logical key in the input master data set.

Distilled Master DsnName of the new master data set (the result of the distillation).

Volume SerialVolume on which the new data set will be stored.

UnitDevice on which the new data set will be stored.

Use Program Name for File NameIf you want to construct the subsequent data set names from the defaulthigh-level qualifier, the specified program name, and the default low-level qualifier for each data set, enter YES.

When you press Enter, the file names on the panel are changed auto-matically. Using the program name is the normal DA procedure.

Program NameName to use for DA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.









Debug Table DsnName of the debug table produced by the DA logical distillation.

Variable Table DsnName of the variable table produced by the DA logical distillation.

JCL DsnName of the JCL data set that contains the JCL for this action.

Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beDxxxxxxx, where xxxxxxx is the last seven characters of the programname.

Variable ID DsnName of the data set that will contain the variable ID intermediate filecreated during the physical distillation process.

Variable Data DsnName of the data set that will contain the variable data intermediate filecreated during the physical distillation process.


Generating JCL for tapeIf the new distilled master data set will be stored on tape, complete the Create JCLto Generate a Key List and Distill Tape Data panel as described in this topic, andthen press Enter. This panel allows you to generate, edit, or submit the JCLrequired for both steps of the physical distillation: (1) generate a key list, and (2)distill the new master data set from the input master data set.

Z [ ----------- Create JCL to Generate a Key List and Distill Tape Data -----------

Command ===>


2 Edit Edit JCL

3 Submit Submit JCL


Input Master File:

Master Data Dsn . . . 'YOUNG.SAMPLE.COB03.MASTER'

Volume Serial . . . . DADST1 Unit . . 3480 (If not cataloged)

File Number . . . . . 1

Key Position . . . . 15 (1 is first character of record)

Key Length . . . . . 20

Output Master File:

Distilled Master Dsn SAMPLE.COB03.DISTILL

Volume Serial . . . . DADST2 Unit . . 3480

File Number . . . . . 2 Expiration Date 1999/365

Catalog Data Set . . NO (Yes|No)


Input Files:




JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(DCOB03)'

Output Files:




\ ]

Figure 51. Create JCL to Generate a Key List and Distill Tape Data panel





Master Data DsnName of the input master data set to be distilled.

Volume SerialVolume on which the data set resides.


UnitDevice on which the data set resides.

File NumberPosition count of the data set relative to other data sets on the tape.The first data set is number 1.

Key PositionPosition of the logical key in each input master data set record. Position1 is the first byte of the record.

Key LengthLength of each logical key in the input master data set.

Distilled Master DsnName of the new master data set (the result of the distillation).

Volume SerialVolume on which the new data set will be stored.

UnitDevice on which the new data set will be stored.

File NumberPosition count of the data set relative to other data sets on the tape.The first data set is number 1.

Expiration DateExpiration date for the new data set. The recommended format isYYYY/DDD.

Catalog data setSpecifies whether the system is to make an entry pointing to the dataset in the system or user catalog.

Use Program Name for File NameIf you want to construct the subsequent data set names from the defaulthigh-level qualifier, the specified program name, and the default low-level qualifier for each data set, enter YES.

When you press Enter, the file names on the panel are changed auto-matically. Using the program name is the normal DA procedure.

Program NameName to use for DA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.








Debug Table DsnName of the debug table produced by the DA logical distillation.


Variable Table DsnName of the variable table produced by the DA logical distillation.

JCL DsnName of the JCL data set that contains the JCL for this action.

Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beDxxxxxxx, where xxxxxxx is the last seven characters of the programname.

Variable ID DsnName of the data set that will contain the variable ID intermediate filecreated during the physical distillation process.

Variable Data DsnName of the data set that will contain the variable data intermediate filecreated during the physical distillation process.

Physical distillation return codesWhen physical distillation is done successfully, the return codes for all steps arezero. The following information is available in the SYSPRINT DD name of theDISTILL step:

� Number of keys: 0000000019� Number of input master records: 0000001440� Number of output master records: 0000000019

The previous values are for the distillation test case shipped with ATC.

When physical distillation fails, the return code of the DISTILL step is nonzero. Anyerror messages are printed in the SYSPRINT DDNAME of the DISTILL step. Formore information about the error, see Appendix A, “Problem determination” onpage 287.



Part 5. Using Unit Test Assistant

Part 5. Using Unit Test Assistant 143




� What is Unit Test Assistant?� What does UTA require?� How does UTA work?� Where can you get further details?

What is Unit Test Assistant?Unit Test Assistant (UTA) allows you to capture and log the values assigned toselected variables in your application programs at selected points during their exe-cution. This is called unit testing. Unit testing allows you to confirm the effective-ness of changes that have been made to an application program.

In addition, Unit Test Assistant offers the ability to perform data warping. Thismeans that variables can be modified automatically as they are encountered duringprogram execution. UTA will intercept data entering or leaving a program at I/Otime (or at other times where application logic dictates) and change the value ofthat data in a manner that you specify.

UTA provides two types of data warping:

1. File warping2. Dynamic data warping

A standard file warping process is to age, or warp, occurrences of dates in theinput data files. UTA's File Warp feature copies VSAM or QSAM files and warpsrecord data fields in the copied files under user control. File warping is describedin more detail in Chapter 20, “Unit Test Assistant file warping” on page 175. Theremainder of this chapter describes logging and dynamic runtime warping of vari-ables.

Dynamic data warping lets you modify COBOL variables and PL/I input buffers.You can:

� Set � Increment � Decrement � Multiply � Divide

these variables by a value that you supply.

UTA supports applications generated by the following compilers:



(5654-MLE)� VS COBOL II Version 1 Release 4.0 (5688-022, 5688-023)� OS/VS COBOL Version 1 Release 2.4 (5740-CB1, 5740-LM1)

Chapter 15. Introduction to UTA 145

Note that although the VisualAge PL/I Compiler Version 2 Release 2 (5655-B22) issupported by Coverage Assistant and Source Audit Assistant, it is not currentlysupported by Unit Test Assistant.

The following PL/I compilers are supported for data warping of file buffers only:

� IBM PL/I for MVS & VM 1.1.1 (5688-235)




For variables that you select to monitor in any compile units in any of your pro-grams, UTA saves the contents of the variables while your program is executing,and writes this data to a log file for later analysis. (Warped variables are onlylogged if there is an error.)

UTA has the following characteristics:

� Low overhead. For a test case run, UTA typically adds very little to the exe-cution time of the program. UTA inserts SVC instructions as breakpoints andthen is given control of MVS when these SVCs are executed.

� Panel-driven user interface. You can use an ISPF panel-driven interface tocreate JCL for executing UTA programs.

� Simple, flexible control. The control file used to define what variables tomonitor provides a simple method of controlling UTA operations.

What does UTA require?UTA has the following requirements:

� UTA runs under MVS. Detailed MVS system resource requirements for UTAare described at “DA and UTA resources” on page 362. UTA uses ISPF ser-vices to display dialogs and to produce the JCL to run the UTA steps.

� As part of its input, UTA requires listings created by the application programcompilers that it supports. These compilers offer options that allow you toinclude assembler statements, data maps, and data cross-references in thelistings, all of which UTA uses.

� UTA also requires the application program object modules or load modules asinput. UTA creates copies of these object modules or load modules with break-points inserted into them.

See “Execution” on page 149 for a description of how the UTA authorized pro-grams intercept breakpoints.


How does UTA work?Running UTA consists of the following steps: This list is an overview of the process.Each activity is described in more detail in topics that follow in this chapter.

Step 1 Setup


b. Generate UTA JCL using the UTA ISPF dialog:

1) Edit the UTA control file.2) Create the Setup JCL.3) Create the monitor JCL.4) Create the variable report JCL.

c. If you instrumented object modules, edit your program’s link-editJCL to pick up the modified object modules, which are created bythe Setup step.

d. Edit your program’s GO JCL (or program invocation) to point to thenew load module that is created when you run the JCL created instep 1c.

Step 2 Execution

a. Run the Setup JCL (created at step 1b2).b. Run the link-edit JCL (created at step 1c).c. Run the monitor JCL to start a monitor session (created at step

1b3).d. Run your application using the load module(s) created in step 2b.e. Stop the monitor session (using the ATGSTOP command).

Step 3 Report

a. Run the variable report JCL (created at 1b4).

If you change your program and want to rerun the test cases, you must repeat step1a using the changed source code, and then complete steps 1b through 3a again.

Figure 52 shows a diagram of the entire process.


Figure 52. UTA—flow diagram


SetupUTA Setup analyzes assembler statements and cross-reference informationincluded in the compiler output listings to determine where to insert breakpoints intodisk-resident copies of the object modules containing variables you want toexamine. It then inserts the breakpoints.


1. Compiler listings of the object modules2. The object modules or load modules you want to test3. The user control file listing variables to monitor


1. Modified test programs (object modules or load modules) containing break-points

2. A file of breakpoint-related information (called BRKTAB in this User's Guide)required for the monitor program in the Execution step.

3. A file of variable control data on variables to monitor (called DBGTAB in thisUser's Guide).

4. A file of variable locations to be used by the monitor (called VARCTL in thisUser's Guide).


Start the UTA monitor program and run your test case programs. As the selectedbreakpoints are encountered, the monitor gains control, logs the predefinedselected variable values, changes (warps) predefined variables or buffers, and thenreturns control to your program. After your test cases have completed, useATGSTOP to stop the monitor session. It writes the results (variable values) to afile called VARTAB.




ReportThe UTA Report program uses the results from the monitor and from DBGTAB toproduce a report of all logged user-defined variables.

To run reports, you need:

1. The DBGTAB data set from the Setup step2. The VARTAB data set from the Execution step

The reports produced are as follows:

� Monitored Variables Report (MVR). A table of monitored variables and theirread specifications. The MVR is always generated.

� Either of the following reports:

– Variable Data report (VDR). A table of data that is read during executionwith references to the MVR for variable identification.

– Combined Variable Data report (CVDR). A variation of the VDR, whichincludes a fully-qualified variable name for each entry.

See pages 169 and 170 for examples of these reports.



Samples of UTA test case coverage,including sample reports

Chapter 16, “Unit Test Assistant samples”on page 151

Editing the CACTL file that contains thenames of the listing data sets

Chapter 18, “Editing the Unit TestAssistant control file” on page 165



Starting a UTA monitor session andrunning test cases on your programs


Reports on the test run Chapter 19, “Unit Test Assistant reports”on page 167

Commands that control the UTA monitorprogram


System resources needed by UTA “DA and UTA resources” on page 362


Chapter 16. Unit Test Assistant samples

This chapter describes samples of Unit Test Assistant (UTA) variable monitoringand warping support using an example provided with the ATC package.

UTA monitors or warps the values of the variables that you select in the control file.

The sample shows monitoring and warping for the COBOL test case COB02.

A flow diagram of the steps required to run this sample is shown in Figure 53 onpage 152. The names in the steps are the member names of the JCL executed forthe step.

The following UTA sample uses the ATC ISPF dialog to create the JCL to run theUTA steps. The ATC ISPF dialog is provided as an aid in creating the JCL. Oncethe JCL is created for a test environment, it does not have to be recreated from thedialog. In a typical user test environment, the creation of the JCL can be incorpo-rated into the user's procedures. You do not have to use the ISPF dialog to useUTA.


Chapter 16. UTA samples 151

Figure 53. Sample UTA run—flow diagram


COB02 test caseThe COB02 test case is an example that includes reading variables from a singlecompile unit and using data warping to set or modify variables. The control file isshown in Figure 56 on page 157, the MVR is shown in Figure 54 on page 154,and the VDR is shown in Figure 55 on page 155.

The variable JULIAN-DATE is set from the system date. UTA is used to set it to2000001 at statement 59, and read it at statement 62. JULIAN-DATE is incre-mented by 5 by UTA at statement 64, and read by UTA at statement 67.

The variable LOAN is initialized to 10000 and INTEREST-RATE is initialized to .05in the program. The INTEREST-DUE (LOAN multiplied by INTEREST-RATE) is cal-culated. LOAN and INTEREST-DUE are read by UTA at statement 78. UTA isused to multiply LOAN by 2.5 at statement 81. INTEREST-DUE is recalculated,then LOAN and INTEREST-DUE are read by UTA at statement 86. LOAN isdivided by 2.5 at statement 91. INTEREST-DUE is recalculated, then LOAN andINTEREST-DUE are read by UTA at statement 94.

A loop executes paragraph INCDATE 1000 times, incrementing J-DAY for eachexecution. UTA reads J-DAY at statement 120, with the ReadEvery UTA keywordused to read J-DAY every 100 times the statement is executed, and the UTAkeyword MaxSave used to read J-DAY a maximum of 5 times.

For COBOL programs, breakpoints are inserted into the object modules duringSetup. These breakpoints are positioned so that the requested variable data can beread when the breakpoint interrupt occurs. When you are ready to test yourprogram, you link the object modules that have been modified with the breakpoints.

To produce the reports for COB02, you need to perform the following steps. steps2a through 6 are described in more detail in topics that follow in this chapter.

1. Compile the COBOL source you want to test. This produces listings thatinclude the assembler statements needed by UTA.




The ATC Primary Option Menu is displayed.

a. Edit the UTA control file.

Verify that the control file includes the listings of the object modules youwant to test and information on the variables you want to monitor.


Create the JCL that enables the Setup job to produce files containingbreakpoint data and variable read data, and to modify copies of your objectmodules by inserting breakpoints.

c. Create the start monitor session JCL.


d. Create the variable report JCL.


Create the JCL to produce the MVR and VDR reports after the COB02 testcase has executed.



After the Setup step, and before the Execution step, you must link the modifiedobject modules into an executable program you can test. Edit the link JCL andspecify the library that will contain the modified object modules for the OBJECTddname and the library that will contain the modified load module for theSYSLMOD ddname.



6. Execute the JCL.


Figures 54 and 55 on page 155 show sample variable reports. For details aboutthe information included in the report, see Chapter 19, “Unit Test Assistant reports”on page 167.

L DATE: 03/28/2000

L TIME: 05:19:47

L

L

LCU Name: YOUNG.SAMPLE.COBOLST(COB02)

LExternal Program Id: COB02

L

L CU var var data read read read read read prog var

L numbr ID mode type offst lngth freq max stmts id name

L-----------------------------------------------------------------------------------------------

1 1 I C 0 7 1 62 COB02 01 JULIAN-DATE


1 3 I Z 0 7 1 59 COB02 01 JULIAN-DATE


1 5 I C 0 6 1 78 COB02 01 LOAN

1 6 I C 0 6 1 78 COB02 01 INTEREST-DUE

1 7 I C 0 6 1 86 COB02 01 LOAN

1 8 I Z 0 6 1 81 COB02 01 LOAN


1 10 I C 0 6 1 94 COB02 01 LOAN

1 11 I Z 0 6 1 91 COB02 01 LOAN


1 13 I C 0 3 100 5 120 COB02 01 J-DATE 02 J-DAY

Figure 54. MVR for COB02


L DATE: 03/28/2000

L TIME: 05:19:47

L

L

L seq CU var at data

L numbr numbr ID stmt stat read

L-----------------------------------------------

1 1 1 62 2000001

2 1 2 67 2000006

3 1 6 78 000500

4 1 5 78 010000

5 1 9 86 001250

6 1 7 86 025000

7 1 12 94 000500

8 1 10 94 010000

9 1 13 120 106

10 1 13 120 206

11 1 13 120 306

12 1 13 120 040

13 1 13 120 140

Figure 55. VDR for COB02


that it will run on your system:




d. Remove any comment characters next to the COB02 member names.

2. Execute the JCL.


Edit the UTA control fileUTA uses assembler listings to determine where to insert breakpoints to monitorvariables. You supply the names of the listing files and data on the variables toread in each listing in the UTA control file (CACTL).

The CACTL control file for the COBOL example is shown in Figure 56 onpage 157.

To edit the CACTL for the COB02 example:



2. Select option 1 from the Coverage, Distillation and Unit Test Assistant panel.


3. Enter option 1 and specify the following:

Control file Dsn COB02

Listing Type COBOL

4. Press Enter.


An ISPF edit session for the UTA control file you requested is displayed.

The data in the control file consists of the following types of statements:

DEFAULTS Specifies default values for operands not specified on subse-quent COBOL statements.

COBOL Specifies the data sets containing the compiler listing, objectmodule, instrumented object module, and load module for theprogram that is to be tested.

SCOPE Specifies the program scope in which the variables to be testedare defined.

VARIABLE Specifies the name of the variables to be tested.

COVERAGE Specifies detailed information about the type of coveragetesting to be performed on a particular variable.

WARP Specifies detailed information about the type of data warping tobe performed on a particular variable or buffer.


5. Verify that the data set names are correct for your installation. Typically thesewill be the same as shown in Figure 56 on page 157, except that your TSO IDprefix is used on each data set's high-level qualifier.


For more detailed information about the control file, see Chapter 18, “Editing theUnit Test Assistant control file” on page 165.



LoadMod=COB02,



COBOL ListMember=COB02


Variable Name=JULIAN-DATE

L set JULIAN-DATE using Data Warping

Warp Action=Set, Value=2000001,

Datatype=Zoned,Unsigned,Stmts=(59)

L read JULIAN-DATE after it is set

Coverage Stmts=(62)

L add 5 to JULIAN-DATE

Warp Action=Increment, Value=5,


L read JULIAN-DATE after 5 has been addeed to it

Coverage Stmts=(67)

Variable Name=LOAN

L read LOAN before it is multiplied

Coverage Stmts=(78)

Variable Name=INTEREST-DUE

L read INTEREST-DUE before LOAN is multiplied

Coverage Stmts=(78)

Variable Name=LOAN

L multiply LOAN by 2.5

Warp Action=multiply, Value=2.5,


L read LOAN after multiply by 2.5

Coverage Stmts=(86)


L read INTEREST-DUE after LOAN is multiplied

Coverage Stmts=(86)

Variable Name=LOAN

L divide LOAN by 2.5

Warp Action=divide, Value=2.5,


L read LOAN after divide by 2.5

Coverage Stmts=(94)


L read INTEREST-DUE after LOAN is divided

Coverage Stmts=(94)

L read J-DAY in loop every 100 times, maximum of 5 times

Variable Name=J-DAY IN J-DATE

Coverage Length=3,ReadEvery=100,

MaxSave=5,Stmts=(120)



Create Setup JCLBefore the COB02 program can be monitored, UTA must insert breakpoints into thetest program. UTA does this using the Setup JCL.

When you execute the Setup JCL, the UTA Setup program analyzes the assem-bler listings and creates a table containing breakpoint data (address, op code, andso on). User SVC instructions are inserted for the instructions at the breakpoints inthe object modules. You then link these modified object modules into a modifiedCOB02 load module for UTA to use.




2. Select option 2.

The Create JCL for Setup panel is displayed. You create the JCL for the Setupof COB02 from this panel. All of the default values on the panel are correct forthe COB02 example except for possibly the Enable UTA and the ProgramName fields.

3. Ensure that Enable UTA is set to YES, that Enable DA is set to NO, and that theentry in the Program Name field is correct.

4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername SCOB02.



Create JCL to start a monitor sessionTo create the JCL to start a monitor session:



2. Select option 3.

The Create JCL to Start the Monitor panel is displayed. You create the JCL forthe UTA execution of COB02 from this panel.

3. Ensure that Enable UTA is set to YES, that Enable DA is set to NO, and that theentry in the Program Name field is correct.

4. Select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername XCOB02.


Use the monitor JCL to start a monitor session before you run your test caseprogram. Note that you can perform UTA execution on a system other than theone on which you have stored the listing.



Create JCL for a Variable reportJCL is required to create a variable report. To create the variable report JCL:


2. Select option 6.


The Unit Test Report panel is displayed.

3. Change the Program Name to COB02, and then select option 1.

Informational messages are written to your screen as the JCL is created. Thecreated JCL is put into the JCL library identified on the panel using membername VCOB02.


Edit JCL to link the modified object modulesEdit the sample link-edit JCL that was copied from hi_lev_qual.SATGSAMP so thatit will run on your system, use your local library names, and use your sample datasets.

Edit JCL to run the GO stepEdit the sample GO JCL that was copied from hi_lev_qual.SATGSAMP so that itwill run on your system, use your local library names, and use your sample datasets.

Execute the JCLWhen you have created all of the COB02 JCL, you can run the COB02 example byexecuting the following functions in the order listed.

To see a flow diagram of these steps, see Figure 53 on page 152.

1. SCOB0215


2. LCOB0216

Links the object modules that have been modified with breakpoints in the Setupstep into the COB02 load module.

3. XCOB0215

Starts a monitor session. For UTA, a program continuously runs to write vari-able data to disk. The JCL does not complete until your session is stopped bystep 6 on page 160.

4. GCOB0216





5. ATGSTATS17

Displays statistics using the ATGSTATS command. You should see a nonzeroEVNTS count on the TOTALS line. (This is an optional step for illustrative pur-poses.)

6. ATGSTOP17

Stops the monitor session. Unit Test Assistant writes the variable data to disk.

7. VCOB0215

Creates the variable reports for COB02. The reports are in data setsproj_qual.COB02.VARID and proj_qual.COB02.VARDATA.





Chapter 17. Unit Test Assistant read and warp descriptions

This chapter describes what variables can be read or warped by Unit Test Assistant(UTA) and when reading and warping takes place.

Description of the variable read operationThe control file identifies the variables to read, the statements on which to readthem, the number of times to read them, where variables are to be warped, and soon. See Chapter 18, “Editing the Unit Test Assistant control file” on page 165 formore information.

Where a variable is readA variable is read when the statement in which it is located is executed, and themaximum reads for that statement are not exceeded. A variable is read before thestatement is executed. If the statement is a looping or iterative statement (such asa PERFORM), the variable will only be read before the first iteration.

Which COBOL storage areas can be readUTA does not support CICS routines compiled with the OS/VS COBOL compiler.Reentrant COBOL routines are only supported for compilers that support the RENTcompiler option.

UTA uses the compiler listings that contain the assembler code and cross-referenceto determine where variables reside in storage. The variables to be read mustappear in the cross-reference and reside in one of the following areas:

� Working storage� Variably located data

� Linkage � File

Consider the following when identifying COBOL storage areas that can and cannotbe read:

� UTA can only read the first occurrence of a variable that is defined multipletimes by way of the OCCURS clause.

� UTA cannot read variables defined in a LOCAL storage area. The LOCALstorage area is an IBM extension available in the COBOL for MVS & VM com-piler. UTA also cannot read linkage variables in a program in which local vari-ables are defined.

� If a variable is the object of a REDEFINE, all names should be monitored toensure full coverage (that is, each name should have an entry in the controlfile).

� If a variable is declared as EXTERNAL, and is used in more than one level ofnested programs, the control file must include entries for the variable for eachinternal program name in which it is used for full coverage.

Chapter 17. UTA read and warp descriptions 161

� If a variable is the object of a USING statement (passed to another program asa parameter), entries must be included in the control file for the variable in thecalling program and for the linkage variable in all called programs that use it inorder to ensure full coverage.

� UTA cannot monitor COBOL variables accessed through pointer references.

How much data can be readOne read of one variable can save up to 126 bytes of data. If the data item youwant to save is longer than 126 bytes, you can do multiple reads with appropriateoffsets and lengths defined.

Variable data is kept in storage buffers while your program is running, and period-ically the data is written to disk. Two buffers are used: one is written to disk whilethe other is being used. It is possible that the buffers may be full when new data isto be written to the buffer. The size of each buffer is 65536 bytes. Each data entrycontains the variable data plus eight bytes of other data.

If a buffer overrun occurs and causes loss of new variable data, you will see astatement similar to the following in the VARDATA file of data:

11915 1 1 38 KYLEX 3722AIX.

11916 1 1 38 KYLEX 3723AIX.


11917 1 1 38 KYLEX 0000MVS.

If a buffer overflow occurs, the program that creates the VDR report of variabledata (stepname EXVAR) completes with a return code of 4.

To reduce buffer overflows, try the following:

1. If you are reading a variable that is in a loop, only read it at intervals (forexample, once every 10th time or 100th time).

2. Reduce the size of each read (for example, the variable may be 100 byteslong, but you may just need to look at the first 10 bytes).

3. Reduce the number of reads (for example, a variable may occur in hundreds oflines in your program, but you may only be interested in its value at a fewlocations).


Description of the variable warp operationThe control file identifies the variable to warp, the statement that contains the vari-able to warp, the warp value, and so on. For more information about the contentsand function of the control file, see Chapter 18, “Editing the Unit Test Assistantcontrol file” on page 165.

What COBOL variables can be warpedAny COBOL variable that can be read by UTA can be warped. For more informa-tion, see “Which COBOL storage areas can be read” on page 161.

When a COBOL variable is warpedA COBOL variable is warped before the execution of the statement. For example,suppose a file is read into a buffer via this COBOL READ statement:

000226 READ QSAMIN INTO WS-INPUT-RECORD

A warp of WS-INPUT-RECORD on line 226 would be performed before the fileread was complete. Therefore, to warp the data in WS-INPUT-RECORD, the warpshould be done on the statement following WS-INPUT-RECORD.

What PL/I variables can be warpedOnly PL/I file input buffers can be warped. In the following example, any field inIN_RECORD can be warped on statement 38. Any other variables (includingIN_RECORD located on other statements) cannot be warped.

38 2 0 READ FILE(QSAMIN) INTO(IN_RECORD);

PL/I warps can only be performed on the statement where the file read occurs.

When a PL/I variable is warpedThe warp is performed after the file read is complete, and the new data is in thebuffer.

Reading and warping on the same statementIf a variable or buffer is read and warped on the same statement, the ordering ofthe read and warp is indeterminate. If you want to read a variable or buffer thathas been warped, do the read on the following statement.

Chapter 17. UTA read and warp descriptions 163


Chapter 18. Editing the Unit Test Assistant control file

This chapter describes the function of the control file (CACTL) used by UTA. TheCACTL contains information that tells UTA what compile units to analyze and thevalues of which variables to record. CA, DA, and UTA share the CACTL file. SeeChapter 21, “CA, DA, and UTA control file” on page 187 for a complete descriptionof this control file. This chapter only explains how to use the control file with UnitTest Assistant.

Contents of the control fileThe control file defines the variable to be recorded. The following describes thecontents of the control file as it is used by Unit Test Assistant. See “Contents ofthe control file” on page 189 for a description of the syntax of the control file.

� The COBOL statement specifies the following:

– The source language (COBOL)

– The data containing the compiler listing file


– The data set containing either the object code generated by the compiler orthe load module created by the linkage editor/binder


� The SCOPE statement specifies the following:

– The PROGRAM-ID of the external program in which variables are defined.The external program ID is the first program ID in the listing file.

– The PROGRAM-ID of the nested (internal) program in which the variablesare defined. This operand is required only if variables are defined within anested program.

� The VARIABLE statement specifies the following:

– The scope in which the variable is defined– The name of the variable

� The COVERAGE statement specifies attributes and coverage details for a spe-cific variable.

� The WARP statement specifies details about how warping of a specific variableor buffer on a specific statement (or statements) is to be performed.

Chapter 18. Editing the UTA control file 165

ExamplesThe examples show how you might construct a UTA control file (1) for capturingand logging COBOL variables and (2) for warping a PL/I input buffer.

1. The following example shows how variables in structures are read:

COBOL ListDsn=YOUNG.Sample.CoboLst(COB01A),LoadMod=COB01,

FromObjDsn=YOUNG.Sample.Obj,ToObjDsn=YOUNG.Sample.ZapObj,ObjMember=COB01A

Scope ExtProgram-Id=COB01A

Variable Name=(CITY In LOC-ID In TASTRUCT)

Coverage MaxSave=10,Name

Variable Name=(STATE In LOC-ID In TASTRUCT)

Coverage ReadEvery=2,Full

Figure 57. Sample UTA control file. The variable CITY In LOC-ID In TASTRUCT is read upto a maximum of 10 times, for each statement where CITY is accessed by name. The vari-able STATE In LOC-ID In TASTRUCT is read every second time a statement is executed onwhich it is accessed through any level of the structure TASTRUCT. There is no maximumnumber of reads for this variable.

The example in Figure 57 is based on the following COBOL declarations:

In COB01A:


01 TAPARM1 PIC 99 VALUE 5.

01 TAPARM2 PIC 99 VALUE 0.

01 TASTRUCT.

05 LOC-ID.

10 STATE PIC X(2).

10 CITY PIC X(3).

In COB01B:


01 TBPARM1 PIC 99 VALUE 5.

01 TBPARM2 PIC 99 VALUE 0.

Figure 58. COBOL file definitions

For an example of a control file for warping COBOL variables, see Figure 56on page 157.

2. Figure 59 is an example of a control file for warping a PL/I input buffer:

PL/I ListDsn=YOUNG.Sample.PLILST(PLI12),

LoadMod=PLI12M,

FromObjDsn=YOUNG.Sample.OBJ,

ToObjDsn=YOUNG.Sample.ZAPOBJ


Variable Name=sfile

Warp Position=1,Length=4,Stmts=(33),Action=INCREMENT,VALUE=10,

DataType=zoned,signed

Figure 59. Control file for warping a PL/I input buffer

In the following statement, the field in buffer si (position 1 for a length of 4) iswarped by incrementing it by 10 after each file read. This position must hold azoned, signed integer.

33 1 0 read file(sfile) into(si);


Chapter 19. Unit Test Assistant reports

This chapter describes the following reports, which UTA creates for the monitoredvariables:

� Monitored variables report (MVR). A table of the monitored variables defined inthe control file and their read specifications.

� Variable Data report (VDR). A table of data for each time a monitored variableis read during the program execution.

� Combined Variable Data report (CVDR). An alternative version of the VDR,which includes the fully-qualified variable names for each read along with theread data.

Monitored Variables report (MVR)The monitored variables report lists the data for all monitored variables as definedin the control file. For an example of an MVR, see Figure 60 on page 169. For adescription of the variable information in the control file, see Chapter 7, “Editing theCoverage Assistant control file” on page 61. All data in the MVR is derived fromthe control file and the compiler listings.

Each monitored compile unit (CU) is listed in the report. The CU NAME is thelisting file name that was used in the Setup step. The External Program ID is theexternal program ID of your COBOL program.

Each monitored variable has one entry in this report. Each entry contains the fol-lowing data:

CU numbr (compile unit number)The sequential number of the CU containing this monitored variable.The VDR lists the CU Number of the variable.

Var ID (variable ID)The sequential number of this monitored variable. The VDR identifiesthe variable by this variable ID.

Var mode (variable mode)The mode for this variable, which can be either of the following:

I Internal (UTA variable read)F File (DA file read)

Data typeFormat in which data is displayed in the report:

C Character representation of dataX Hexadecimal representation of data

Read offst (read offset)The offset within the variable data area to read. For example, a variablemight be defined as 132 characters in length, but you only want to reada serial number field that is at offset 40 within the field. This entry is0-based (that is, 0 is the offset of the first byte).

Chapter 19. UTA reports 167

Read lngth (read length)The length of the variable data item to read. This may be the length ofthe entire data item, or some subset of it. A maximum of 126 bytes canbe read from one variable. If more than 126 bytes is desired, you canhave two (or more) reads of the same variable. All 256 bytes ofCUST-REC can be read by the control file entries:

Definition of CUST-REC:

01 CUST-REC PIC X(256)

control file entries:

VARIABLE NAME=(CUST-REC)

COVERAGE Offset=0,Length=126,Name





The first variable/coverage pair reads the first 126 bytes of CUST-REC,the second reads the next 126 bytes, and the third reads the last 4bytes.

Read freq (read frequency)How often to read the variable when the statement in which the variableis located is executed. For example, if read frequency is one, the vari-able is read and the data is saved on each execution of the monitoredstatement. If the read frequency is five, it is read every fifth time thestatement is executed.

Read max (Read maximum)The maximum number of times to read the variable. If blank, it is readon each execution of monitored statements. You may only be interestedin the value of the variable the first time a statement is executed, of thefirst n times the statement is executed; therefore, this is useful to reducethe number of reads (and consequently the amount of variable datasaved).

Read stmts (read statements)All statement numbers where the UTA control file requested (eitherexplicitly or implicitly) that the specified variable be monitored.

Prog ID (program ID)The program ID (external or internal) that contains the variable. Thesame variable name may be used in different program IDs.

Var name (variable name)The variable name contains all qualifying level names if this is a readfrom a structure. A two-digit level number (starting with 01) precedeseach level name:

01 Level1-name 02 level2-name ...


The following example shows an MVR:

L DATE: 03/28/2000

L TIME: 05:19:47

L

L

LCU Name: YOUNG.SAMPLE.COBOLST(COB02)

LExternal Program Id: COB02

L

L CU var var data read read read read read prog var

L numbr ID mode type offst lngth freq max stmts id name

L---------------------------------------------------------------------------------------------





1 5 I C 0 6 1 78 COB02 01 LOAN


1 7 I C 0 6 1 86 COB02 01 LOAN

1 8 I Z 0 6 1 81 COB02 01 LOAN


1 10 I C 0 6 1 94 COB02 01 LOAN

1 11 I Z 0 6 1 91 COB02 01 LOAN


1 13 I C 0 3 100 5 120 COB02 01 J-DATE 02 J-DAY

Figure 60. MVR for COB02

Variable Data report (VDR)The VDR is a table of variable data. Each row shows the data of one variable readat one statement number. Columns of the row (for example, CU numbr and var ID)are used to reference the characteristics and names of the variables in the MVR.

The columns in the VDR are:

Seq numbr (sequence number)A sequential number identifying the variable data row.

CU numbr (CU number)The CU number containing the variable in the MVR.

Var ID (variable ID)The variable ID number in the MVR.

At stmt (at statement)The statement number where the variable was read.

Stat (status)This field is only used for data warp errors. For information about datawarp errors, see “Errors during data warping” on page 170.

Data readThe variable data read at this statement number. The length of the datais specified by the read lngth column in the MVR. A maximum of 126bytes can be read. Hexadecimal numbers are flagged with an X to theleft of the number and are displayed as two hexadecimal digits for eachbyte represented.


The following example shows a VDR.

L DATE: 03/28/2000

L TIME: 05:19:47

L

L

L seq CU var at data

L numbr numbr ID stmt stat read

L-----------------------------------------------

1 1 1 62 2000001

2 1 2 67 2000006

3 1 6 78 000500

4 1 5 78 010000

5 1 9 86 001250

6 1 7 86 025000

7 1 12 94 000500

8 1 10 94 010000

9 1 13 120 106

10 1 13 120 206

11 1 13 120 306

12 1 13 120 040

13 1 13 120 140

Figure 61. VDR for COB02

Errors during data warpingA sign check is done if you increment or decrement a packed or zoned variable.The sign you specify for the variable must match the sign of the variable in storagebefore the warp is performed. If there is a sign mismatch, a read of the variable instorage is done. You can view the error information by running the Unit TestAssistant reports described in this chapter.

The reads of variables with sign mismatches have an error number in the statusfield:

4 Packed signed error. The variable was specified as a signed packednumber, but the variable read in the user program was unsigned.

5 Packed unsigned error. The variable was specified as an unsignedpacked number, but the variable read in the user program was signed.

6 Zoned signed error. The variable was specified as a signed zonednumber, but the variable read in the user program was unsigned.

7 Zoned unsigned error. The variable was specified as an unsignedzoned number, but the variable read in the user program was signed.


Combined Variable Data report (CVDR)The CVDR, an alternative to the VDR, combines elements of the MVR and theVDR. Each row shows the data from one variable read at one statement numberand enough information to uniquely identify the variable. The var-ID column isused to reference the variable read characteristics in the MVR.

The columns in the CVDR are:

var-ID (variable ID)The variable ID number in the MVR.

CU-Name (compile unit name)The name of the CU containing the variable.

prog-ID (program ID)The name of the program containing the variable.

var-name (variable name)The fully-qualified variable name.

stmt-num (statement number)The statement number at which the variable data was read.

dataThe variable data read at this statement number.

L DATE: 03/28/2000

L TIME: 05:24:46

L

L

L var-ID CU-Name prog-ID var-name stmt-num data

L-------------------------------------------------------------------------------------------

1 COB02 COB02 JULIAN-DATE 62 2000001

2 COB02 COB02 JULIAN-DATE 67 2000006

6 COB02 COB02 INTEREST-DUE 78 000500

5 COB02 COB02 LOAN 78 010000


7 COB02 COB02 LOAN 86 025000


10 COB02 COB02 LOAN 94 010000

13 COB02 COB02 J-DAY of J-DATE 120 106





Figure 62. CVDR for COB02


Creating Unit Test report JCL using the panelsTo display the Unit Test Report panel:


The Coverage, Distillation and Unit Test Assistant panel is displayed.2. Select option 6.

The Unit Test Report panel, shown in Figure 63, is displayed.

Z [ ------------------ Create JCL for Unit Test Assistant Reports -----------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL



Variable Report Type FULL (Full|Combine)

Input Files:




JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(VCOB02)'

Output Files:





\ ]

Figure 63. Create JCL for Unit Test Assistant Reports panel





Use Program Name for File NameIf you want to construct the data set names from the default high-level qualifier, the specified program name, and the default low-levelqualifier for each data set, enter YES.

When you press Enter, the file names on the panel are changedautomatically. Using the program name to construct the data setnames is the normal UTA procedure.


Program NameName to use for UTA files if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name. Itdoes not have to be the name of any of your programs. Names ofthe following form are created:







Variable Report TypeSpecifies the parameter to be used for the variable report program(ATGOPVAR). FULL produces the VDR and COMBINE producesthe CVDR.

Debug Table DsnSpecifies the name of the file containing the variables that UTA is tomonitor.

Variable Table DsnSpecifies a UTA work file containing intermediate results of informa-tion gathered when variables were monitored.


Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data setwill be Vxxxxxxx, where xxxxxxx is the last seven characters of theprogram name.

Variable ID DsnSpecifies the name of the file to contain various information aboutthe variables being monitored (MVR). This includes the location ofthe variables in the listing, the compilation unit, and so on. (Enter *for the default SYSOUT class.)

Variable Data DsnSpecifies the name of the file to contain the final monitoring results(VDR). This is formatted output based on the variable table workfile. (Enter * for the default SYSOUT class.)


Parameters for the UTA report programThe parameters to the UTA report program (load module ATGOPVAR) are:

─ ──┬ ┬─FULL────── ──┬ ┬────────────────────── ───────────────────────────── � ├ ┤─COMBINE─── └ ┘ ─␣──common_parameters─ ├ ┤─KEYS_ONLY─ └ ┘─BOTH──────

FULLProduces the standard VDR report as described in “Variable Data report (VDR)”on page 169.

COMBINEProduces the CVDR report as described in “Combined Variable Data report(CVDR)” on page 171.

KEYS_ONLYProduces a report containing some informational comments followed by linescontaining only the Data read information (starting in column 2).

BOTHProduces a report similar to FULL, but with the data lines prefixed by L (indi-cating a comment) followed by lines containing only the Data read information(starting in column 2).

␣ One or more blanks.

common_parametersAny of the common parameters described in Appendix F, “ParametersCommon To Multiple Routines” on page 381 (separated by blanks).

The MVR report is always produced.


Chapter 20. Unit Test Assistant file warping

File warping is the modification of variables in program input files to simulate inputconditions for testing. File warping may be used to modify dates (e.g., to simulateend-of-quarter or end-of year), currency values (e.g., Euro conversion testing), etc.during testing of converted programs.

The UTA File Warp feature enables you to statically warp dates in input files. FileWarp can copy any QSAM or VSAM file and warp fields in the copied file fortesting. Any zoned or packed numeric field can be incremented, decremented, orset. Any zoned, packed, or character field can be set to a common value. A usefulimplementation of this file warping capability might be clearing fields in test copiesof production input files for privacy or security reasons.

File Warp operationThe following figure illustrates the UTA file warping process:

Figure 64. UTA—file warp flow diagram

The UTA file warping feature can perform the following types of warps:

� Warps on all records� Warps on matching record types

The warp control file controls the warping of file fields.

Chapter 20. UTA file warping 175

For record type warps, a field is identified as the record type. A warp record isthen defined to do the warp if the record type matches the record type field valuesupplied. Note how a file record is defined in the following example copy book:

01 EMPLOYEE-RECORD.

03 EMPLOYEE_NAME PIC 20(X).

03 SOCIAL_SECURITY_NUMBER PIC 9(9).

03 SPACE1 PIC 1(X).

03 HIRE_DATE

05 YEAR PIC 9(2).

05 MONTH PIC 9(2).

05 DAY PIC 9(2).

03 SPACE2 PIC 1(X).

03 LAST_PROMOTION_DATE

05 YEAR PIC 9(2) PACKED-DECIMAL.

05 MONTH PIC 9(2) PACKED-DECIMAL.

05 DAY PIC 9(2) PACKED-DECIMAL.

03 SPACE3 PIC 1(X).

03 CURRENT_LEVEL PIC 9(1).

03 SPACE4 PIC 1(X).

03 CURRENT_SALARY PIC 9(7).

Figure 65. Copy book defining a file record

The following warp control file could be used for the copy book in Figure 65:

01 EMPLOYEE-RECORD.

03 EMPLOYEE_NAME 20 CHARACTER

03 SOCIAL_SECURITY_NUMBER 9 ZONED = � 03 SPACE1 1 CHARACTER

03 HIRE_DATE

05 YEAR 2 ZONED = �1 05 MONTH 2 ZONED

05 DAY 2 ZONED

03 SPACE2 1 CHARACTER

03 LAST_PROMOTION_DATE

05 YEAR 2 PACKED SIGNED

R1: 1 2 PACKED SIGNED + 1 R1: 2 2 PACKED SIGNED + 2 R1: DEFAULT 2 PACKED SIGNED - 1

05 MONTH 2 PACKED SIGNED

05 DAY 2 PACKED SIGNED


1: 03 CURRENT_LEVEL 1 ZONED


03 CURRENT_SALARY 7 ZONED = �

Figure 66. Example of a warp control file

For all records:

� The SOCIAL_SECURITY_NUMBER and CURRENT_SALARY are set to 0.

� The 2-digit zoned field YEAR in HIRE_DATE is set to 01.

� For records with CURRENT_LEVEL=1, 1 is added to the packed field YEAR inLAST_PROMOTION_DATE.

� For records with CURRENT_LEVEL=2, 2 is added to the packed field YEAR inLAST_PROMOTION_DATE.

� For records with any other CURRENT_LEVEL, 1 is subtracted from the packedfield YEAR in LAST_PROMOTION_DATE.


File Warp samplesThe samples shipped with ATC include a File Warp sample.


To create file warp JCL and execute this sample, complete the following steps:

1. Select option 1 from the ATC Primary Option menu. The Coverage, Distillationand Unit Test Assistant panel is displayed.

2. Select option 6. The Unit Test Assistant panel is displayed.

3. Select option 2. The Generate JCL for File Warping panel is displayed.

Z [ ------------------------ Generate JCL for File Warping ------------------------

Command ===>

1 EditCtl Edit File Warp Control File

2 ResetCtl Reset File Warp Control File from system master


4 Edit Edit JCL

5 Submit Submit JCL


Input Dsn . . . . . . 'YOUNG.SAMPLE.FWARPIN'

Volume Serial . . . Unit . . (If not cataloged)

Output Dsn. . . . . . 'YOUNG.SAMPLE.FWARPOUT'

Volume Serial . . . Unit . .

Use Identifier for File Name YES (Yes|No) Identifier FWARP

File Warp Control Dsn 'YOUNG.SAMPLE.FWCTL(FWARP)'

(If the File Warp Control Dsn is blank, the input file is copied unchanged.)


JCL Dsn . . . . . . 'YOUNG.SAMPLE.JCL(FFWARP)'

\ ]

Figure 67. Generate JCL for File Warping panel

4. Specify the following on the Generate JCL for File Warping panel:

� The 'preifx.SAMPLE.FWARPIN' in the Input Dsn field

� The name you would like to use for the new warped copy in the OutputDsn field

� YES in the Use Identifier for File Name field

� FWARP in the Identifier field

� 'prefix.SAMPLE.FWCTL(FWARP)' in the File Warp Control Dsn field.

� The data set and member name you want to use for the JCL name in theJCL Dsn field.

5. Press Enter to return to the command line. Select option 1.

Informational messages are written to your screen as the JCL is created. TheJCL is created in the JCL library member you specified.


6. If you want to edit the JCL you just generated, select option 2.

An edit session is opened for the JCL data set.

7. Select option 3.

Your JCL will be submitted to run file warping.

The output file is created with fields warped as defined in the File Warp control file.The record structure and File Warp control file contents are the same as thoseused in the example in “File Warp operation” on page 175.

File Warp control file syntaxThe File Warp control file contains the following types of lines:

� Field definition� Record type definition

The warp control file structure allows copy books to be the basis for the definitions.For structures, the lowest level variables have to have a length and data type.Higher level variables can have length/data type information, or this information canbe left blank. If provided, the keyword LEVEL must be present. The entire copybook does not need to be used for the control file. You can just select the fields tobe warped, and use filler field names to define the spaces between warped vari-ables.

You might use a definition similar to the following if you were only interested inwarping two fields and you calculated the offsets to them. The offsets are suppliedin the fill fields.

01 master_file

03 fill 20 character

03 warp_field1 2 zoned + 28

03 fill 40 character

03 warp_field2 4 packed signed - 28

Field definitionA field definition is the lowest level of a structure (copy book). A field can bewarped or it can just be present as a filler. The following is an example of a fielddefinition:

03 BEGIN-DATE 8 Packed Signed + 2

03 SKIP_UNTIL_WARP 100 Character

1: 05 BIRTH-DATE 4 Binary + 100

LAST_NAME 16 Character = ABCDEFGHIJLMNOPS

FIRST_NAME 6 Character = " "

birthday 4 Binary = '0000'x

The syntax for field definition statements is as follows:

─ ──┬ ┬────────── ──┬ ┬────────────── ─field_name─ ─length──data_type───────── └ ┘ ─label──:─ └ ┘ ─level_number─

─ ──┬ ┬────── ──┬ ┬──────── ──┬ ┬──────────── ───────────────────────────────── � └ ┘ ─sign─ └ ┘ ─action─ └ ┘ ─warp_value─


Group-level definitionA group-level definition is a higher level structure that contains field definitions. Thefollowing is an example of a group-level definition that is not warped:

// length data_type optional:

03 EMP-HIRE-DATE

// If length and data_type are present,

// keyword LEVEL must be supplied

03 EMP-HIRE-DATE LEVEL 6 Zoned

// followed by structure definition:

05 YY 2 Zoned

05 MM 2 Zoned

05 DD 2 Zoned

The syntax for group-level field definition statements that are not warped is asfollows:

─ ──┬ ┬────────── ──┬ ┬────────────── ─field_name──────────────────────────── └ ┘ ─label──:─ └ ┘ ─level_number─

─ ──┬ ┬──────────────────────────────────── ─────────────────────────────── � └ ┘─LEVEL──length──data_type─ ──┬ ┬────── └ ┘ ─sign─

The following is an example of a group level definition that is warped:

L length, data_type and keyword LEVEL must be present if warped

03 EMP-HIRE-DATE LEVEL 6 character = 991231

05 YY 2 Zoned

05 MM 2 Zoned

05 DD 2 Zoned

The syntax for group-level field definition statements that are warped is as follows:

─ ──┬ ┬────────── ──┬ ┬────────────── ─field_name──LEVEL───────────────────── └ ┘ ─label──:─ └ ┘ ─level_number─

─ ─length──data_type─ ──┬ ┬────── ─action──warp_value─────────────────────── � └ ┘ ─sign─

Record type definitionRecord type definitions define record type fields used to selectively perform warpingbased on the contents of the record type field:

r1: 1 2 packed + 1

r1: 2 2 packed - 1

r6: '00001'x 2 Zoned signed = 99

r99: DEFAULT 4 character = ABCD

Record type definitions follow the field definition that they warp. The record typelabel must end with a number that is defined in the warp file as a field definitionlabel.

The syntax for record type definition statements is as follows:

─ ─record_type_label──:─ ─record_type_value──length──data_type────────────

─ ──┬ ┬────── ─action──warp_value────────────────────────────────────────── � └ ┘ ─sign─


Positional parameter definitionsAll parameters are positional and separated by at least one blank. Parameters arenot case sensitive.

label A label is a positive integer followed by a colon (:). It is usedon field definition statements to define them as record types.It is recommended (but not required) that label numbers startwith one and be sequential. The following example shows alabel parameter definition:

1:

99:

-5: // illegal: negative integer

4.5: // illegal: not an integer

level_number The level_number is an optional positive integer typicallyused in structures. It is ignored by file warping and can beomitted. The following example shows a level numberparameter definition:

03 EMP-DATE 2 packed

05 BIRTHDAY 6 zoned level

-9 EMP-DATE // illegal: negative

field_name The name of the field. It can be any characters (it need notbe a legal compiler name) but must be present. The fol-lowing example shows a field name parameter definition:

05 LAST_NAME 20 character

1: @%$&#( 4 zoned

03 fill 50 // Fill to define record length

// until field to be warped

03 4 packed + 1 // error: no field name

length The length of the field:

Packed Number of digits. File Warp translatesthe number to bytes needed for the field:(digits + 2)/2

Binary Number of digits. File warp translatesthe number to bytes needed for the field:

1 to 4 2 bytes5 to 9 4 bytes10 to 18 8 bytes

Zoned Number of digits. One byte per digit.

Character Number of characters. One byte percharacter.

Any other data type cannot be warped. It must be defined asa character field of the proper length. The length must be apositive integer.


data_type One of the following types of fields:

� Packed � Zoned � Binary � Character

The above types follow COBOL definitions. Only the firstcharacter of the data_type is examined. For example, P maybe used for packed.

sign For packed and zoned numbers, the sign (Signed orUnsigned) of the field. For binary and character fields, thesign (if supplied) is ignored. If supplied, the sign must followthe data_type. If omitted, the default is Unsigned. Signedcan be abbreviated to S; Unsigned can be abbreviated U.To add or subtract from zoned and packed fields, the sign inthe control file must match the sign of the field in the recordor an error will occur.

action One of the following warp actions to take:

+ Add the warp_value to the field.− Subtract the warp_value from the field.= Replace the field with the warp_value.

For character fields, only = is valid.

warp_value The warp value used in conjunction with the action. For + or−, the warp_value must be a positive integer. For =, the fieldcan be a:

� Hexadecimal value enclosed in quotes and followed byX:'0001'X.

� Character string. If the string contains spaces, enclose inquotes. For example: 'AB CD'Either single quotes (') or double quotes (") can beused.

record_type_label The definition of a record type for record type warping. Itmust be of the format: the character r followed by a positiveinteger, followed by a colon (:). For example:

r1:

r99:


record_type_value The value to be matched with the record type in order to dothe warp. If DEFAULT, the warp is done if none of thedefined record type values matches the record type. Forexample:

r4: 1 2 z + 1

r4: 2 2 z + 2

r4: default 2 z = 3 // if record type 4

// is not 1 or 2, do

// this warp

The record_type_value is treated as a character (byte) fieldfor comparison to the record type. In the previous examples,the values character 1 ('F1'x) or 2 ('F2'x) are compared tothe record type.

comments Comments can be as follows:

Entire line The line must start with *.End of line Anything following // is commented

The following example shows an end of line comment:

fieldName 4 zoned + 1 // end of line comment on

// a field definition

Control file exampleThe following is an example of the control file with the file warping definitions:

01 hi_level_name1

1: 03 what_record1 1 char // record type field used for warping

03 fill 39 char // user can leave out

// fields as long

// as they put in a field with

// cumulative offset

03 some_date 8 packed signed = 2001

some_number 2 z + 1 // level numbers are

// optional

05 rec_warp1 2 packed signed

r1: '01'x 2 p s = 99 // if '01'x records set rec_warp

r1: '02'x 2 p s = 01 // if '02'x records set rec_warp

r1: '03'x 2 p s + 1 // if '03'x records add 1 to rec_warp

r1: default 2 p s = 98 // otherwise set to 98

05 rec_warp2 4 z

r2: CUST1 4 z + 1 // if CUST1 record add 1 to rec_warp2

r2: CUST2 4 z + 2 // if CUST2 record add 2 to rec_warp2

r2: ' C 3' 4 z + 3 // if ' C 3 ' record add 3 to

// rec_warp2

2: what_record2 5 c // record type field for rec_warp2 field

fill 100 c // space to next warp

some_name 10 c = 1234567890

Figure 68. Example control file with file warping definitions

In the previous example:

� The some_date field is set to the packed signed number 2001 for all records.

� The some_number field is incremented with the zoned unsigned value 1 for allrecords.


� The what_record1 field defines a record type. The rec_warp1 field is warpedas follows:

– If '01'x, records (hex) are set to the packed, signed number 99.– If '02'x, records (hex) are set to the packed, signed number 01.– If '03'x, records (hex) add 1.– Any records that do not have one of the previous values will be set to 98.

� The what_record2 field is a record type used to warp rec_warp2 as follows:

– CUST1 records (character) are incremented by 1.– CUST2 records are incremented by 2.– ' C 3 ' records (character) are incremented by 3.

� The some_name field is set to the character string '1234567890' for allrecords.

File Warp return codesFor file warping, there are two job steps:

1. Check the File Warp control file for syntax (job step CVTCTL).2. Perform the File Warp (job step FWARP).

If the File Warp JCL returns a nonzero return code, there was a failure in the warpprocess.

When the CVTCTL step fails, an error message is printed in the SYSTSPRT DDstatement of the CVTCTL step. When the FWARP step fails, an error message isprinted in the SYSPRINT DD statement of the FWARP step. For an explanation offile warping error messages, see Appendix A, “Problem determination” onpage 287.



Part 6. Common CA, DA, and UTA Information

Part 6. Common CA, DA, and UTA Information 185


Chapter 21. CA, DA, and UTA control file

This chapter describes the function of the CA/DA/UTA control file (CACTL). TheCACTL file contains information that describes the compile units to be analyzed,the file that is to be monitored, and the values of the variables to be recorded.

Note: CA, DA, and UTA share the CACTL file.

To edit the control file:

1. Select option 1 from the ATC Primary Option Menu. The Coverage, Distillationand Unit Test Assistant panel is displayed.

Z [ ------------ Coverage, Distillation and Unit Test Assistant--------------------

Option ===>

1 Cnt1File Work with the CA/DA/UTA control file

2 Setup Create JCL for Setup

3 StartMon Create JCL to Start the Monitor

4 CA Coverage Reports

5 DA Distillation

6 UTA Unit Test Report

7 Monitor Control the CA/DA/UTA Monitor


\ ]

Figure 69. Coverage, Distillation and Unit Test Assistant panel

2. Select option 1 to display the Work with the CA/DA/UTA Control File panel,shown in Figure 70.

Z [ --------------------- Work with the CA/DA/UTA Control File --------------------

Option ===>

1 Edit Edit CA/DA/UTA Control File

2 Reset Reset CA/DA/UTA Control File from System Master



CA/DA/UTA Control File:


Listing Type. . . . . COBOL (COBOL|PL/I|ASM)

\ ]

Figure 70. Work with the CA/DA/UTA Control File panel

3. Enter option 1 and change the values for Control File Dsn and Listing Type

as appropriate.


EditStarts an edit session for the control file specified in the ControlFile Dsn field.

Chapter 21. CA, DA, and UTA control file 187

ResetReplaces the information in the Control File specified in the ControlFile Dsn field with information from the system sample control file.(See also Listing Type, which follows in this list.)


When you press Enter, the file names on the panel are changedautomatically. Using the program name is the normal CA, DA, andUTA procedure.

Program NameName to use for CA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.








Control file DsnSpecifies the name of the control file data set to be used.

Listing TypeType of CACTL template that is retrieved fromhi_lev_qual.SATGSAMP if you select Edit (and the data set ormember in the Control File Dsn field does not exist) or Reset.

4. Press Enter.

An ISPF edit session for the data set you identified is displayed. If the data setdid not previously exist, it is created with comments to help you enter theappropriate information in the fields.

5. Edit the control file to include all programs and variables to be monitored in thissession.

6. Press the End key (PF3) key to save your information and exit the edit session.


Contents of the control fileThe control file consists of a series of statements that specify information about thedesired coverage, unit testing, or distillation.

The following describes the contents of the control file:

� The INCLUDE statement. This statement allows control statements in a sepa-rate data set to be processed as if they were a part of the current data set.The operand of the INCLUDE statement must specify either of the following:

– The data set name of the file to be included

– The DDNAME of a previously allocated file that is to be included

� The DEFAULTS statement. This statement allows defaults to be set for certainkeywords on subsequent COBOL, PL/I, or ASM statements.

� The compilation unit (COBOL , PL/I, or ASM) statement. This statement identi-fies the following:

– The type of listing file (COBOL, PL/I, or ASM)

– The name of the data set containing the compiler listing of the compilationunit of interest, the PROGRAM-ID of the external program generated by aCOBOL compiler using the TEST or COUNT compiler option, or both.

– The name of the load module that contains the code from the listing

– The data set containing either the object code generated by the compiler orthe load module created by the linker/binder


Notes:

1. If breakpoints are placed in object modules, then a specific compila-tion unit should be specified only once in a control file. If the compila-tion unit is link-edited into more than one load module, it should be listedfor just one of the load modules.

2. Within a control file, each compilation unit should contain a unique externalprogram name (for COBOL, PROGRAM-ID; for PL/I, procedure name; andfor assembler, CSECT name).

� The scope definition (SCOPE) statement.18 This statement does either of thefollowing:

– Defines the scope for subsequent COBOL variable or file definitions andidentifies:

- The PROGRAM-ID of the external program containing the variable- The PROGRAM-ID of the internal (nested) program containing the vari-

able (if the variable is defined within a nested program)

– Defines the scope for subsequent PL/I file definitions and identifies thename of the procedure or begin-block containing the variable

18 SCOPE statements are used only by Distillation Assistant and Unit Test Assistant. They are not used by Coverage Assistant.


� The variable definition (VARIABLE ) statement. This statement identifies thefully-qualified name of the COBOL variable for which unit test coverage isrequested or the partially-qualified name of a variable when unit test coverageis requested for all variables containing this qualifier.

� The coverage definition (COVERAGE) statement. This statement specifiesattributes and coverage details for a particular variable.

� The warp definition (WARP) statement. This statement specifies attributes andwarping details for a particular variable or buffer.

� The file definition (FILE) statement. This statement specifies that all reads ofthe specified COBOL or PL/I file are to be monitored for distillation. The VARI-ABLE and FILE statements should never be used in the same control file.

DBCS support for the control file statements is explained in Appendix C, “DBCSsupport” on page 365.

Control file statement syntaxThis section describes the syntax of the control statements described previously.The syntax of all control statements follows the same general rules:

� Statements are free-form (not column dependent).

� An asterisk in column 1 indicates a comment.

� Two consecutive slashes (//) indicate that the rest of the line following the twoslashes is a comment.

� Lines containing nothing but blanks are ignored.

� Keywords and operands may be coded in any combination of uppercase andlowercase characters.

� Operands may appear in any order.

� Operands must be separated by a comma.

� One or more blanks can appear between keywords and the correspondingequal sign, the equal sign and the operand, and the operand and the followingcomma.

� The order of statements is not significant except that:

– All labels must be defined before they are referenced.

– The DEFAULTS statement is position dependent (it applies only to thestatements that follow it).

– The default value for some operands is the previous statement of theproper type.

� Statements may be continued, if desired, by interrupting the line after a commaand continuing the statement on the next line.

� Labels, if present, are specified before the statement name and must be imme-diately followed by a colon. Labels cannot contain embedded blanks, commas,parentheses, or equal signs.

� Labels specified on COBOL, PL/I, and ASM statements cannot be repeated onany of those statements. Likewise, labels on SCOPE statements cannot berepeated on other SCOPE statements and labels on VARIABLE statementscannot be repeated on other VARIABLE statements.


� Operands shown in the syntax diagrams as being enclosed in parentheses, donot have to be enclosed in parentheses if the operand contains no embeddedblanks or commas.

INCLUDE statementThe INCLUDE statement can be used to include information from anotherCA/UTA/DA control file. When such a control file is included, all statements areprocessed as if they were in the original control file.

─ ──┬ ┬────────── ─INCLUDE─ ──┬ ┬─DSNAME──=──dsname─ ──────────────────────── � └ ┘ ─label──:─ └ ┘─DDNAME──=──ddname─

where:

dsname Specifies the data set name of the CA/DA/UTA control file to beincluded.

ddname Specifies a ddname which has been previously allocated to aCA/DA/UTA control file.

DEFAULTS statementThe DEFAULTS statement specifies defaults to be used for certain keywords onsubsequent COBOL, PL/I, and ASM statements.

If a COBOL, a PL/I, or an ASM statement that does not specify a keyword isencountered, and the statement was preceded by a DEFAULTS statement thatspecified the keyword, the value specified on the DEFAULTS statement is used. Ifmore than one DEFAULTS statement is found, the last DEFAULTS statement thatspecified the keyword in question is used.

──DEFAULTS─ ──┬ ┬─────────────────────────── ────────────────────────────── └ ┘─LISTDSN──=──listdsname──,─

─ ──┬ ┬─────────────────────────── ───────────────────────────────────────── └ ┘─LOADMOD──=──membername──,─

─ ──┬ ┬───────────────────────────────────────── ─────────────────────────── └ ┘──┬ ┬──FROMOBJDSN=fromobjdsn ── ─,──┤ FVU ├─

└ ┘──FROMLOADDSN=fromloaddsn

─ ──┬ ┬────────────────────────────────── ───────────────────────────────── � └ ┘──┬ ┬──TOOBJDSN=toobjdsn ── ─┤ TVU ├─

└ ┘──TOLOADDSN=toloaddsn

FVU:├─ ──┬ ┬────────────────────────────────────────────────── ──────────────────┤ └ ┘─FROMVOL──=──fromvol──,──FROMUNIT──=──fromunit──,─

TVU:├─ ──┬ ┬────────────────────────────────────────── ──────────────────────────┤ └ ┘─,──TOVOL──=──tovol──,──TOUNIT──=──tounit─

where:

listdsname The name of the data set that contains the compiler listing for thiscompilation unit. If listdsname is specified on the DEFAULTSstatement, an asterisk must be specified as the member name ifthe data set is partitioned or as one of the qualifiers if the data setis sequential. If LISTDSN= is not specified on a subsequentCOBOL, PL/I, or ASM statement, the LISTMEMBER= operand


must be specified. In this case the LISTMEMBER= operand willbe used to replace the asterisk to create the name to be used forthat statement.

membername The name of the load module containing this compilation unit.

fromobjdsn The data set name of the partitioned data set containing theobject generated by the compiler for this compilation unit.

fromloaddsn19 The data set name of the partitioned data set containing the loadmodule generated by the linker/binder.

fromvol The volume containing the fromobjdsn or fromloaddsn data set if itis not cataloged.

fromunit The unit specification for the fromobjdsn or fromloaddsn data set ifit is not cataloged.

toobjdsn The data set name of the partitioned data set that will contain theinstrumented object created by the Setup for this compilation unit.

toloaddsn19 The data set name of the partitioned data set that will contain theinstrumented load module generated by Setup.

tovol The volume containing the toobjdsn or toloaddsn data set if it isnot cataloged.

tounit The unit specification for the toobjdsn or toloaddsn data set if it isnot cataloged.

19 Instrumentation of load modules is not supported for VisualAge PL/I Version 2 Release 2.


COBOL statement (COBOL compilation unit definition) withlistings availableThe COBOL statement identifies a COBOL compilation unit. Use this form of theCOBOL statement if compiler listings are available.

Notes:

1. If breakpoints are placed in object modules, then a specific compilationunit should be specified only once in a control file. If the compilation unit islink-edited into more than one load module, it should be listed for just one ofthe load modules.

2. Within a control file, each compilation unit should contain a unique externalprogram name (for COBOL, PROGRAM-ID; for PL/I, procedure name; and forassembler, CSECT name).

The syntax of the COBOL statement is:

─ ──┬ ┬────────── ─COBOL──LISTDSN──=──listdsname──,─ ──┬ ┬────────────────────────────── ──────────────────── └ ┘ ─label──:─ └ ┘─LISTMEMBER──=──listmember──,─

──LOADMOD──=──membername──,─────────────────────────────────────────────────────────────────────────────

─ ──┬ ┬──FROMOBJDSN=fromobjdsn,─┤ FVU ├─ ──┬ ┬────────────────────── TOOBJDSN=toobjdsn─┤ TVU ├─ ───────────── � │ │└ ┘──OBJECTmember=objmem, └ ┘ ──┬ ┬─────────────────────────────────── ──TOLOADDSN=toloaddsn─┤ TVU ├─ ──────────────── └ ┘──FROMLOADDSN=fromloaddsn,─┤ FVU ├─

FVU:├─ ──┬ ┬────────────────────────────────────────────────── ─────────────────────────────────────────────────┤ └ ┘─FROMVOL──=──fromvol──,──FROMUNIT──=──fromunit──,─

TVU:├─ ──┬ ┬────────────────────────────────────────── ─────────────────────────────────────────────────────────┤ └ ┘─,──TOVOL──=──tovol──,──TOUNIT──=──tounit─

where:

label A label that can be used to refer to this statement in subsequentstatements.

listdsname The name of the data set that contains the compiler listing for thiscompilation unit.

listmember The member name to be substituted for an asterisk specificationin the listdsname. This operand would usually be specified onlywhen the LISTDSN operand is specified on the DEFAULTS state-ment.

membername The name of the load module (member name) containing thiscompilation unit.

fromobjdsn The data set name of the partitioned data set that contains theobject modules generated by the compiler.

fromloaddsn The data set name of the partitioned data set that contains theload module generated by the linker/binder.




objmem The member name in the fromobjdsn for the object for this compi-lation unit. If fromobjdsn is specified and this operand is notspecified, listdsname must be specified and must contain amember name specification (which may be obtained from theLISTMEMBER= operand). In this case, the member name speci-fied as a part of listdsname will be used for objmem.

toobjdsn The data set name of the partitioned data set that will contain themodified object modules generated by Setup.

toloaddsn The data set name of the partitioned data set that will contain theinstrumented load module generated by Setup.



In a set of control cards you can process either object modules or load modules,but not both. Thus, the FROMOBJDSN and FROMLOADDSN keywords are mutu-ally exclusive, as are the TOOBJDSN and TOLOADDSN keywords.

If TOOBJDSN is coded, then FROMOBJDSN is required.

If TOLOADDSN is coded, FROMLOADDSN is optional. Coding FROMLOADDSNindicates that the load module membername is to be copied from fromloaddsn totoloaddsn before the breakpoints are applied via AMASPZAP to membername intoloaddsn.

The fromloaddsn load module may be coded as an * to prevent copying of the loadmodules before AMASPZAP is called (typically, this is only used ifFROMLOADDSN has a default value).

AMASPZAP is used to instrument breakpoints in a load module. It is invoked wheneither the membername or toloaddsn changes, or when the last control card isprocessed.

If the load module being instrumented has aliases, you should not use theFROMLOADDSN keyword, but should do the copy yourself using a method thatpreserves the aliases. Note that applying breakpoints to load modules is slowerthan applying them to object modules and requires access to AMASPZAP.However, it may be preferable if your normal build process does not keep a copy ofthe object modules for later processing or you do not want to maintain a separateset of link/bind JCL.


COBOL statement (COBOL compilation unit definition) withoutlistingsThe COBOL statement identifies a COBOL compilation unit. Use this form of theCOBOL statement a compiler listing is not available and you compiled your sourcewith the TEST (COBOL for OS/390 & VM, COBOL for MVS & VM, or VS COBOLII) or COUNT (OS/VS COBOL) compiler option. For further information concerningTEST or COUNT, see “Instrumenting load modules without listings” on page 220.

This form of the COBOL statement is only allowed for CA (it is not supported forDA or UTA). In addition, within a set of control cards, if this type of COBOL state-ment is used, you cannot use the COBOL statement without the TEST or COUNToption, and you cannot use the PL/I or ASM statements.

Note: Within a control file, each compilation unit should contain a unique externalprogram name. (For example: for COBOL, PROGRAM-ID; for PL/I, procedurename; or for assembler, CSECT name.)

The syntax of the COBOL statement is:

─ ──┬ ┬────────── ─COBOL──EXTPROGRAM-ID──=──extname──,──────────────────────────────────────────────────── └ ┘ ─label──:─

─ ──┬ ┬───────────────────────────────────────────────────────────── ─LOADMOD──=──membername──,──────────── └ ┘─LISTDSN──=──listdsname──,─ ──┬ ┬────────────────────────────── └ ┘─LISTMEMBER──=──listmember──,─

─ ──┬ ┬─────────────────────────────────────── ──TOLOADDSN=toloaddsn─┤ TVU ├─ ───────────────────────────── � └ ┘─FROMLOADDSN──=──fromloaddsn,──┤ FVU ├─



where:

extname The COBOL program-ID of the external COBOL program to beanalyzed.
















LISTDSN is only required if you want to generate a CA Annotated Listing report.


PL/I statement (PL/I Compilation Unit Definition)The PL/I statement identifies a PL/I compilation unit.

Notes:


2. Within a control file, each compilation unit should contain a unique externalprogram name. (For example: for COBOL, PROGRAM-ID; for PL/I, procedurename; or for assembler, CSECT name.)

The syntax of the PL/I statement is:

─ ──┬ ┬────────── ──┬ ┬─PL/I─ ─LISTDSN──=──listdsname──,─ ──┬ ┬────────────────────────────── ─LOADMOD──=────── └ ┘─label──:─ └ ┘─PLI── └ ┘─LISTMEMBER──=──listmember──,─

──membername──,─────────────────────────────────────────────────────────────────────────────────────────




where:





fromobjdsn The data set name of the partitioned data set that contains theobject modules generated by the compiler.

fromloaddsn20 The data set name of the partitioned data set that contains theload module generated by the linker/binder.


20 Instrumentation of load modules is not supported for VisualAge PL/I Version 2 Release 2.





toloaddsn20 The data set name of the partitioned data set that will contain theinstrumented load module generated by Setup.










ASM statement (assembler compilation unit definition)The ASM statement identifies an assembler program compilation unit.

Notes:


2. Within a control file, each compilation unit should contain a unique externalprogram name. (For example: for COBOL, PROGRAM-ID; for PL/I, procedurename; or for assembler, CSECT name.)

The syntax of the ASM statement is:

─ ──┬ ┬────────── ─ASM──LISTDSN──=──listdsname──,─ ──┬ ┬────────────────────────────── ─LOADMOD──=─────────── └ ┘ ─label──:─ └ ┘─LISTMEMBER──=──listmember──,─

──membername──,─────────────────────────────────────────────────────────────────────────────────────────




where:


listdsname The name of the data set which contains the assembler listing forthis compilation unit.



fromobjdsn The data set name of the partitioned data set that contains theobject modules generated by the assembler.












If TOLOADDSN is coded, FROMLOADDSN is optional. Coding FROMLOADDSNindicates that the load module membername is to be copied from fromloaddsn totoloaddsn before the breakpoints are applied via AMASPZAP to membername intoloaddsn. statement





SCOPE statementThe SCOPE statement identifies a program scope in a COBOL or PL/I compilationunit that contains variables or files of interest.

Each SCOPE statement must be preceded by (and applies to) a COBOL or PL/Istatement that specifies the listing containing the scope defined by the SCOPEstatement.

The syntax of the SCOPE statement is:

─ ──┬ ┬────────── ─SCOPE─ ──┬ ┬──────────────────────────────── ────────────── └ ┘ ─label──:─ └ ┘──┬ ┬─COBOL─ ─=──cobolplilabel──,─ ├ ┤─PL/I── └ ┘─PLI───

─ ──┬ ┬ ─EXTPROGRAM-ID──=─ ──┬ ┬─extname─ ──┬ ┬─────────────── ───────────────── � │ │└ ┘─L─────── └ ┘─┤ NestedPgm ├─ │ │┌ ┐─.─────────── └ ┘ ──┬ ┬─PROCEDURE─ ─=─ ──┬ ┬───

�┴──┬ ┬─pliname─ ───────────

└ ┘─PROC────── │ │└ ┘─stmt──── └ ┘─L───────────────

NestedPgm:├──,──NESTEDPROGRAM-ID──=─ ──┬ ┬─intname─ ───────────────────────────────────┤ └ ┘─L───────

where:

cobolplilabel A label on the COBOL or PL/I statement that defines the compila-tion unit containing this scope. If this operand is not specified, thedefault is the previous COBOL or PL/I statement.

extname The COBOL program-ID of the external COBOL program that con-tains items to be referenced.

* Indicates that the search for the referenced items is to be donethrough all external COBOL programs in the specified listing.

intname The COBOL program-ID of the internal (nested) COBOL programthat contains items to be referenced. This operand should be spec-ified only if the variables of interest are defined in a nested COBOLprogram. If this keyword is not specified, the variable is assumedto be defined in the external COBOL program.

* Indicates that the search for the referenced items is to be donethrough all internal program IDs in the specified external COBOLprogram-ID or through all procedures in the specified external PL/Iprocedure in the specified listing.

pliname The PL/I procedure or BEGIN-block that contains items to be refer-enced. For PL/I internal procedures, the form PROC1.PROC2must be used, where PROC1 is the external procedure and PROC2is an internal procedure contained in PROC1. Also, in the case ofPL/I, named BEGIN blocks are considered to be equivalent tonamed procedures and are specified in exactly the same way. Forunnamed BEGIN-blocks, the statement number (stmt) where theBEGIN-block is defined is used in place of the procedure name.

For example, PROCEDURE=P0.P1.B1.2451.P3 specifies anexternal procedure named P0 that contains an internal procedure,


or named BEGIN-block, called P1 that contains an internal proce-dure, or named BEGIN-block, called B1 that contains an unnamedBEGIN-block defined in statement 2451 that contains an internalprocedure, or named BEGIN-block, called P3.

stmt See the previous description of pliname.

* Indicates that the search for the referenced items is to be donethrough all PL/I procedures and BEGIN-blocks in the specifiedlisting.

VARIABLE statementThe VARIABLE statement identifies a COBOL variable for which coverage or awarp action is to be requested. The VARIABLE statement can also identify a PL/I21

file constant whose associated input file buffer is to be warped. VARIABLE state-ment can be used to specify either of the following:

1. The name of a fully-qualified variable.

2. The name of a single qualifier. In this case any fully-qualified names containingthis qualifier are considered to be a match.

The SCOPE specified for a PL/I variable must be the procedure or BEGIN-block inwhich the variable is defined (either explicitly or implicitly), although it can be refer-enced in other, contained blocks. This means that the scope for implicitly declaredvariables (other than parameters) must be defined as the external procedure.

The syntax of the VARIABLE statement is:

─ ──┬ ┬────────── ─VARIABLE─ ──┬ ┬───────────────────────── ─NAME──=──(─────── └ ┘ ─label──:─ └ ┘─SCOPE──=──scopelabel──,─

─ ─── ──── ──varname─ ──┬ ┬─────────────────────── ─)───────────────────────── � │ │┌ ┐───────────────────── ├ ┤───

�┴──┬ ┬─IN─ ─groupname─

│ │└ ┘─OF─ └ ┘ ──┬ ┬─IN─ ─L───────────── └ ┘─OF─

where:

scopelabel The label specified on a SCOPE statement (which can refer to eithera COBOL or a PL/I statement) that defines the scope in which thisvariable was defined. If this operand is not specified, the default isthe previous SCOPE statement.

varname The name of the variable to be referenced.

groupname The name of a group containing the referenced variable.

* indicates that a single qualifier is specified and that any fully-qualifiedvariable that contains this qualifier is considered to be a match.

21 The VARIABLE statement is not supported for programs compiled with the VisualAge PL/I Version 2 Release 2 compiler.


COVERAGE statementThe COVERAGE statement specifies the coverage desired for a specific COBOLvariable. COVERAGE with VARIABLE (coded or implied) causes the logging of thevariable value at the beginning of the statement (for additional details, see “Wherea variable is read” on page 161). COVERAGE with FILE causes logging of thevariable after a READ but before any other type of COBOL statement.

The syntax of the COVERAGE statement is:

┌ ┐─VARIABLE─ ──COVERAGE─ ──┬ ┬─────────────────────────────── ──┼ ┼────────── ─,────────── └ ┘─VARIABLE──=──variablelabel──,─ └ ┘─FILE─────

┌ ┐─CHAR─ ─ ──┼ ┼────── ─,─ ──┬ ┬────────────────────────────── ───────────────────────── └ ┘─HEX── │ │┌ ┐─!────── ├ ┤ ─OFFSET──=─ ──┴ ┴─offset─ ─,───── │ │┌ ┐─1──────── └ ┘ ─POSITION──=─ ──┴ ┴─position─ ─,─

─ ──┬ ┬────────────────────────── ──┬ ┬──────────────────────────── ────────── │ │┌ ┐─-1───── │ │┌ ┐─1───── └ ┘ ─LENGTH──=─ ──┴ ┴─length─ ─,─ └ ┘ ─READEVERY──=─ ──┴ ┴─times─ ─,─

┌ ┐─,──── ─ ──┬ ┬──────────────────────── ──┬ ┬─STMTS──=──(─ ───

�┴─stmt─ ─)─ ───────────── �

│ │┌ ┐─!─── ├ ┤─NAME───────────────────── └ ┘ ─MAXSAVE──=─ ──┴ ┴─max─ ─,─ └ ┘─FULL─────────────────────

where:

variablelabelThe label on the VARIABLE statement to which this coverage applies.If this operand is not specified, the default is the previous VARIABLEstatement.

VARIABLE Indicates an internal (program) variable.

FILE Indicates a File read variable to be processed for distillation.

CHAR specifies that variable data will be displayed as characters.

HEX Specifies that variable data will be displayed as hexadecimal numbers,two hexadecimal digits per byte.

offset Specifies the offset from the start of the data item where the read ofthe value is to begin. (An offset of 0 indicates the beginning of theitem.)

position Specifies the position of the first byte of the data item where the readof the value is to begin. (A position of 1 indicates the beginning of theitem.)

length Specifies the number of bytes of the data item to be read. A value of-1 indicates that the length is to be taken from the listing. Themaximum length supported is 126 bytes.

times Specifies the number of times to skip reading this data item. A valueof 1 indicates that the value of the item is to be saved each time theitem is referenced.


max Specifies the maximum number of values that are to be saved for theitem. A value of 0 indicates that all values are to be saved.

STMTS Specifies that the variable is to be monitored only at specific state-ments.

stmt Specifies the specific statements at which the variable is to be moni-tored.

NAME Specifies that the contents of the variable are to be read at all state-ments that reference it by the specified, fully-qualified name.

FULL specifies that the contents of the variable are to be read at all state-ments that reference it by the specified, fully-qualified name or by thename of any containing or contained group or element.

WARP statementThe WARP statement specifies that a COBOL variable or PL/I22 file buffer is to bemodified at a particular statement or statements (taken from the listing). This mod-ification takes place before the statement has executed for COBOL, and after thestatement has executed for PL/I.

The syntax of the WARP statement is:

──WARP─ ──┬ ┬─────────────────────────────── ─DATATYPE──=──datatype──,───── └ ┘─VARIABLE──=──variablelabel──,─

─ ──┬ ┬───────────── ──┬ ┬────────────────────────────── ───────────────────── ├ ┤─SIGNED──,─── │ │┌ ┐─!────── └ ┘ ─UNSIGNED──,─ ├ ┤ ─OFFSET──=─ ──┴ ┴─offset─ ─,───── │ │┌ ┐─1──────── └ ┘ ─POSITION──=─ ──┴ ┴─position─ ─,─

─ ──┬ ┬────────────────────── ─ACTION──=──action──,──VALUE──=──value──,───── └ ┘─LENGTH──=──length──,─

┌ ┐─,──── ──STMTS──=──(─ ───

�┴─stmt─ ─)────────────────────────────────────────────── �

where:

variablelabelthe label on the VARIABLE statement to which this warp actionapplies. If this operand is not specified, the default is the previousVARIABLE statement. For COBOL, this label can refer to any vari-able that represents a number. For PL/I, this label must refer to a fileconstant, and warping can occur only at file reads.

datatype Specifies the type of data that is to be warped. Valid types are:

ZONED Indicates that the variable or file segment contains zoneddecimal data (for example, 99='F9F9'x).

PACKED Indicates that the variable or file segment contains packeddecimal data (for example, 99='099F'x).

BINARY Indicates that the variable or file segment contains binarydata (for example, 99='63'x).

22 The WARP statement is not supported for programs compiled with the VisualAge PL/I Version 2 Release 2 compiler.


SIGNED Specifies that the data is signed. This is the default for PL/I PACKEDand PL/I BINARY datatypes.

UNSIGNED Specifies that the data is unsigned. This is the default for all COBOLdatatypes and also PL/I ZONED data types.

offset Specifies the offset of the first byte of the data item where the read ofthe value is to begin. (An offset of 0 indicates the beginning of theitem.)

position Specifies the position of the first byte of the data item where the readof the value is to begin. (A position of 1 indicates the beginning of theitem.)

length Specifies the length of the data item to be warped.

This parameter indicates the number of:

� Digits (1-15) for ZONED and PACKED data� Bytes (2 or 4) for BINARY data

The default values are as follows:

� For COBOL, the default of -1 indicates that the length is to betaken from the listing.

� For PL/I, the defaults are 2, if the data type is BINARY, and 1, ifthe datatype is ZONED or PACKED.

action Specifies the warp action to be taken on the data. Valid actions are:

INCREMENT Add the VALUE parameter to the data.DECREMENT Subtract the VALUE parameter from the data.MULTIPLY Multiply the data by the VALUE parameter.DIVIDE Divide the data by the VALUE parameter.SET Set the data equal to the VALUE parameter.

value Indicates the numeric value to be used by the specified ACTION.

� For INCREMENT and DECREMENT: The value must be a non-negative integer.

� For MULTIPLY and DIVIDE:– The value must be a nonnegative decimal number.– The value can be a maximum of 8 digits, not counting the

decimal point.– If a value is specified which causes data overflow, no indi-

cation will be given, and data will be lost.– Binary numbers must fit in 4 bytes (including intermediate

values).– Binary numbers are truncated, not rounded.– Packed and zoned numbers are rounded.

stmt Specifies the specific statements at which the variable or file segmentis to be warped.


COBOL and PL/I syntax conversion tables: The following tables may be helpfulin converting COBOL and PL/I syntax to control card syntax for WARP statements:

Table 12. COBOL syntax conversion table

COBOL Data Division Entry Datatype Sign Length

Pic 9(P) Usage Display Zoned Unsigned P

Pic S9(P) Usage Display Zoned Signed P

Pic 9(P) Usage Comp-3 Packed Unsigned P

Pic S9(P) Usage Comp-3 Packed Signed P

Pic 9(1...4) Usage Comp Binary Unsigned 2

Pic 9(5...9) Usage Comp Binary Unsigned 4

Pic S9(1...4) Usage Comp Binary Signed 2

Pic S9(5...9) Usage Comp Binary Signed 4

Note: P=any integer 1-15 inclusive

Table 13. PL/I syntax conversion table

PL/I Declare Datatype Sign Length

Character (P)1 Zoned Unsigned P

Picture '(P)9'2 Zoned Unsigned P

Picture '(P-1)9T'2 Zoned Signed P

Fixed Decimal (P,0) Packed Signed P

Fixed Binary (15,0) Binary Signed/Unsigned 2

Fixed Binary (31,0) Binary Signed/Unsigned 4

Notes:

P=any integer 1-15 inclusive

For Fixed Decimal (P,Q) and Fixed Binary (P,Q), 0 is the only valid value for Q.

1 Data must be right-justified within the field and padded on the left with zeros.

2 Only characters 9 and T are supported (if used, T must be the rightmost char-acter).


FILE Read statementThe FILE statement identifies a COBOL or PL/I23 file to be processed for distillation.The file buffer is processed after the execution of the READ statement.

Note: Never use the FILE statement with VARIABLE statements in the samecontrol file. If you use these statements together, the variable read data will bemixed with the key list, preventing distillation.

The syntax of the File statement is:

──FILE─ ──┬ ┬───────────────────────── ─FILE──=──filename──,─────────────── └ ┘─SCOPE──=──scopelabel──,─

─ ──┬ ┬─KEYOFFSET──=──keyoff─── ─,──KEYLEN──=──keylen─────────────────────── └ ┘─KEYPOSITION──=──keypos─

─ ──┬ ┬───────────────────────────── ────────────────────────────────────── � │ │┌ ┐─,──── └ ┘─,──STMTS──=──(─ ───

�┴─stmt─ ─)─

where:

scopelabel The label specified on the SCOPE statement that defines the scopein which this file was defined. If this operand is not specified, thedefault is the previous SCOPE statement.

filename The COBOL filename as specified on the FD statement or the nameof a PL/I file constant with the RECORD attribute. PL/I file variablescannot be specified.

keyoff Specifies the offset from the start of the record to the start of thelogical key. (An offset of 0 indicates the beginning of the record.)

keypos Specifies the position of the start of the logical key within the record.(A position of 1 indicates the beginning of the record.)

keylen The length of the logical key.

stmt A list of COBOL or PL/I statement numbers at which reads of the fileare to be monitored.

For COBOL, if no stmt values are specified, all reads of the specifiedfile are monitored.

For PL/I, stmt values are required. Only reads of the specified fileat the specified statements are monitored.

23 The FILE Read statement is not supported for programs compiled with the VisualAge PL/I Version 2 Release 2 compiler.


Control file examplesThe following examples show how these statements might be used.

Coverage Assistant control file examplesThese examples show two control files that might be used for Coverage Assistantonly.

Coverage Assistant example 1: This example shows a typical control file wherecoverage is requested for a single compilation unit.

Cobol ListDsn=YOUNG.SAMPLE.Cobolst(Cob01),

LoadMod=Cob01,

FromObjDsn=YOUNG.SAMPLE.Obj,

ToObjDsn=YOUNG.SAMPLE.ZapObj

Coverage Assistant example 2: This example shows a typical control file wherecoverage is requested for multiple compilation units.

Defaults ListDsn=YOUNG.SAMPLE.Cobolst(L),

LoadMod=Cob01,



L

Cobol ListMember=Cob01A

Cobol ListMember=Cob01C

Cobol ListMember=Cob01D

Coverage Assistant example 3: This example shows a typical control file wherecoverage is requested for multiple compilation units and breakpoints are to beplaced directly into a load module (rather than into object modules):

Defaults ListDsn=YOUNG.SAMPLE.Cobolst(L),

LoadMod=Cob01,

FromLoadDsn=YOUNG.SAMPLE.LOADLIB,

ToLoadDsn=YOUNG.SAMPLE.RUNLIB

L

Cobol ListMember=Cob01A

Cobol ListMember=Cob01C

Cobol ListMember=Cob01D

Coverage Assistant example 4: This example shows a typical control file wherecoverage is requested for multiple compilation units for which no compiler listingsare available and for which the TEST (COUNT for OS/VS COBOL) compiler optionwas specified. Only a CA Summary report is desired.

Defaults LoadMod=COB01,



Cobol ExtProgram-ID=Cob01A

Cobol ExtProgram-ID=Cob01C

Cobol ExtProgram-ID=Cob01D


Distillation Assistant control file exampleThis example shows a control file that might be used for Distillation Assistant. Inthis example, all reads of the specified file are monitored.

Cobol ListDsn=YOUNG.SAMPLE.Cobolst(Cob092),

LoadMod=Cob092,



Scope ExtProgram-Id=Cob092

File File=VSAMIN,KeyPosition=1,KeyLen=11

Unit Test Assistant control file exampleThis example shows a control file that might be used for Unit Test Assistant(including data warping).


LoadMod=COB02,



COBOL ListMember=COB02


Variable Name=JULIAN-DATE

L set JULIAN-DATE using Data Warping

Warp Action=Set, Value=2000001,


L read JULIAN-DATE after it is set

Coverage Stmts=(62)

L add 5 to JULIAN-DATE

Warp Action=Increment, Value=5,


L read JULIAN-DATE after 5 has been addeed to it

Coverage Stmts=(67)

Variable Name=LOAN

L read LOAN before it is multiplied

Coverage Stmts=(78)


L read INTEREST-DUE before LOAN is multiplied

Coverage Stmts=(78)

Variable Name=LOAN

L multiply LOAN by 2.5

Warp Action=multiply, Value=2.5,


L read LOAN after multiply by 2.5

Coverage Stmts=(86)


L read INTEREST-DUE after LOAN is multiplied

Coverage Stmts=(86)

Variable Name=LOAN

L divide LOAN by 2.5

Warp Action=divide, Value=2.5,



L read LOAN after divide by 2.5

Coverage Stmts=(94)


L read INTEREST-DUE after LOAN is divided

Coverage Stmts=(94)

L read J-DAY in loop every 100 times, maximum of 5 times

Variable Name=J-DAY IN J-DATE

Coverage Length=3,ReadEvery=100,

MaxSave=5,Stmts=(120)


Chapter 22. CA, DA, and UTA setup

This chapter describes the CA, DA, and UTA setup steps. You create the JCL tostart the CA, DA, and UTA Setup program from the Create JCL for Setup panel,shown in Figure 73 on page 222.

SetupThe Setup process uses assembler statements from the listings produced by thecompiler or debug information provided by the COBOL TEST (COUNT for OS/VSCOBOL) compiler option (CA only) to determine where to place breakpoints. ForDA and UTA, Setup also uses data map and data cross-reference (XREF) toextract variable storage and access information.

You must supply the following items for Setup:

1. Compiler listings with assembler statements included (for DA and UTA, alsoinclude data map and XREF). These are not required if the COBOL TEST(COUNT for OS/VS COBOL) compiler option was used.

2. The original object modules created during the source compile step or the ori-ginal load modules created during the link-edit step.

3. An object library (allocated like the original) to receive the new object modules(after they have been modified with breakpoints), or a load library to receive thenew load modules.

4. Information on what variables (UTA only) or files (DA only) to monitor.

Modify this information as necessary in the control file (CACTL), as described atChapter 7, “Editing the Coverage Assistant control file” on page 61, Chapter 13,“Editing the Distillation Assistant control file” on page 129, Chapter 18, “Editing theUnit Test Assistant control file” on page 165, and Chapter 21, “CA, DA, and UTAcontrol file” on page 187.

Note: When using CA Targeted Summary, you must use the instructions, whichfollow, under DA and UTA Setup .

Compiler optionsCA Setup

COBOL For COBOL for OS/390 & VM and COBOL for MVS & VM,specify the following compiler options:24

� SOURCE25

� LIST25

24 Specifying the *CBL (*CONTROL) NOSOURCE Compiler-Directing Statement to suppress printing of COBOL executable state-ments prevents these statements from being included in the Annotated Listing report. Specifying the *CBL (*CONTROL) NOLISTCompiler-Directing Statement to suppress printing of the assembler code prevents Setup from inserting any breakpoints into thesuppressed assembler code.

25 You can run Setup without listings by enabling the TEST compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. If you choose to do this, you do not have to use the LIST compiler option. The SOURCE compiler option isonly needed if you want to run an Annotated Listing report. For more information, see “Instrumenting load modules withoutlistings” on page 220.

Chapter 22. CA, DA, and UTA Setup 211

� OBJECT � NOOPTIMIZE � NONUMBER � LIB26

For VS COBOL II, specify the following compiler options:24

� SOURCE27

� LIST27

� OBJECT � NOOPTIMIZE � NONUMBER � LIB26

For OS/VS COBOL, specify the following compiler options:

� SOURCE28

� PMAP28

� OBJECT � NOLST � NOOPTIMIZE � NONUM � NOBATCH � NOTEST � NOFLOW � NOSYMDMP � NOCOUNT28

For COBOL, each listing may contain multiple COBOL para-graphs. Each paragraph is listed in the Summary report as aseparate program area (PA). The PA name is the paragraphname.

All COBOL listings must have the following DCB attributes:

� RECFM=FBA� LRECL=133 for COBOL for OS/390 & VM, COBOL for

MVS & VM, and VS COBOL II� LRECL=121 for OS/VS COBOL

26 The LIB compiler option is only required by ATC if you have multiple source programs separated by CBL (Process) Compiler-Directing Statements.

27 You can run Setup without listings by enabling the TEST compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. The RESIDENT compiler option is also required. If you choose to do this, you do not have to use the LISTcompiler option. The SOURCE compiler option is only needed if you want to run an Annotated Listing report. For more informa-tion, see “Instrumenting load modules without listings” on page 220.

28 You can run Setup without listings by enabling the COUNT compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. If you choose to do this, you do not have to use the PMAP compiler option. The SOURCE compiler optionis only needed if you want to run an Annotated Listing report. For more information, see “Instrumenting load modules withoutlistings” on page 220.


PL/I For VisualAge PL/I Version 2 Release 2, specify the followingcompiler options:

� SOURCE � LIST � OBJECT

| � NOINSOURCE29

� NOOFFSET � NOOPTIMIZE� NOTEST or TEST(NONE)

For PL/I for MVS & VM, specify the following compileroptions:31

� SOURCE � LIST � OBJECT � NOOPTIMIZE� NOTEST or TEST(NONE)

For PL/I 2.3.0, specify the following compiler options:30 31

� SOURCE � LIST � OBJECT � NOOPTIMIZE � NOTEST � NOCOUNT � NOFLOW


� SOURCE � LIST � OBJECT � NOOPTIMIZE � NOCOUNT � NOFLOW

For PL/I, each listing may contain (1) one external procedure,and (2) multiple internal procedures, ON-units, and BEGINblocks. Each of these is listed in the Summary report as aseparate program area (PA). The PA name is the name ofthe procedure or labeled BEGIN block, or is a compiler-generated name or CA-generated name for ON-units andunlabeled BEGIN blocks.

The following PL/I condition prefixes should not be enabled:

� SUBSCRIPTRANGE

| 29 NOINSOURCE is only required if you are running VisualAge PL/I 2.2.0 without APAR PQ40062.

30 ATC requires that PTF PN49349 be applied to the IBM OS PL/I Optimizing Compiler 2.3.0 to provide support for more than 9999statements. The IBM PL/I Optimizing Compiler 1.5.1 does not support more than 9999 statements.

31 Specifying the %NOPRINT statement to suppress printing of PL/I executable statements prevents these statements from beingincluded in the Annotated Listing report produced by CA.Multiple PL/I external source programs separated by *PROCESS statements are not supported.The use of the REORDER Procedure or BEGIN block option is not supported.


� STRINGRANGE � CHECK

All PL/I listings must have the following DCB attributes:

� RECFM=VBA � LRECL=125

ASM For the High Level Assembler, specify the following assem-bler options:

� NOBATCH � ESD� NOGOFF (Release 3 only)

� LIST� OBJECT or DECK

� NOXOBJECT� PCONTROL(GEN, MSOURCE, ON)

For Assembler H, specify the following assembler options:32

� NOBATCH � ESD � LIST� OBJECT or DECK

All ASM listings must have the following DCB attributes:

� RECFM=FBM� LRECL=133 for the High Level Assembler� LRECL=121 for Assembler H

Each listing can contain one assembly. If you only want a Summaryreport of code coverage, you can discard the compiler listings after theSetup step.

| ATC does not support breakpointing of self-modifying code.

DA and UTA Setup and CA Targeted Summary

COBOL For COBOL for OS/390 & VM and COBOL for MVS & VM,specify the following compiler options:33

� SOURCE34

� LIST � OBJECT � XREF � MAP � NOOPTIMIZE � NONUMBER

32 Specifying the PRINT assembler directive to suppress printing of executable instructions or data prevents Setup from inserting anybreakpoints into the suppressed assembler code.

33 Specifying the *CBL (*CONTROL) NOLIST Compiler-Directing Statement to suppress printing of the assembler code preventsSetup from inserting any breakpoints into the suppressed assembler code.

Specifying the *CBL (*CONTROL) NOMAP Compiler-Directing Statement to suppress the printing of storage map entries willprevent ATC from analyzing the affected data items.

34 You can run Setup without listings by enabling the TEST compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. The SOURCE compiler option is only needed if you want to run an Annotated Listing report. For moreinformation, see “Instrumenting load modules without listings” on page 220.


� LIB26

For VS COBOL II, use the following compiler options:33

� SOURCE35

� LIST � OBJECT � XREF � MAP � NOOPTIMIZE � NONUMBER � LIB26

For OS/VS COBOL, use the following compiler options:36

� SOURCE37

� DMAP � PMAP � OBJECT � XREF � NOLST � NOCLIST � NOOPTIMIZE � NONUM � NOBATCH � NOSXREF � NOTEST � NOFLOW � NOSYMDMP � NOCOUNT37

For COBOL, each listing may contain multiple COBOL para-graphs. Each paragraph is listed in the Summary report as aseparate program area (PA). The PA name is the paragraphname.

All COBOL listings must have the following DCB attributes:

� RECFM=FBA� LRECL=133 for COBOL for OS/390 & VM, COBOL for

MVS & VM, and VS COBOL II� LRECL=121 for OS/VS COBOL

PL/I For VisualAge PL/I38 Version 2 Release 2, specify the fol-lowing compiler options:

� ATTRIBUTES(FULL) � NOGRAPHIC

35 You can run Setup without listings by enabling the TEST compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. The RESIDENT compiler option is also required. The SOURCE compiler option is only needed if you wantto run an Annotated Listing report. For more information, see “Instrumenting load modules without listings” on page 220.

36 DA and UTA do not support CICS routines compiled with the OS/VS COBOL compiler.

37 You can run Setup without listings by enabling the COUNT compiler option and using the EXTPROGRAM-ID option on the CACOBOL control card. The SOURCE compiler option is only needed if you want to run an Annotated Listing report. For moreinformation, see “Instrumenting load modules without listings” on page 220.

38 VisualAge PL/I Version 2 Release 2 is supported for CA Targeted Summary but is not supported for DA and UTA.


| � NOINSOURCE39

� LIST � MAP � NEST � OBJECT � NOOFFSET � NOOPTIMIZE � OPTIONS � SOURCE � XREF(FULL)� NOTEST or TEST(NONE)

For PL/I for MVS & VM, specify the following compileroptions:31

� ATTRIBUTES(FULL) � NOGRAPHIC � LIST � MAP � NEST � OBJECT � OFFSET � NOOPTIMIZE � OPTIONS � SOURCE � XREF(FULL)� NOTEST or TEST(NONE)


� ATTRIBUTES(FULL) � NOGRAPHIC � LIST � MAP � NEST � OBJECT � OFFSET � NOOPTIMIZE � OPTIONS � SOURCE � XREF(FULL) � NOTEST � NOCOUNT � NOFLOW

For PL/I 1.5.1, specify the following compiler options:31

� ATTRIBUTES(FULL) � NOGRAPHIC � LIST � MAP � NEST � OBJECT � OFFSET

| 39 NOINSOURCE is only required if you are running VisualAge PL/I 2.2.0 without APAR PQ40062.


� NOOPTIMIZE � OPTIONS � SOURCE � XREF(FULL) � NOCOUNT � NOFLOW

For PL/I, each listing may contain (1) one external procedure,and (2) multiple internal procedures, ON-units, and BEGINblocks. Each of these is listed in the Summary report as aseparate program area (PA). The PA name is the name ofthe procedure or labeled BEGIN block, or is a compiler-generated name or CA-generated name for ON-units andunlabeled BEGIN blocks.

The following PL/I condition prefixes should not be enabled:

� SUBSCRIPTRANGE � STRINGRANGE � CHECK

All PL/I listings must have the following DCB attributes:

� RECFM=VBA� LRECL=132 (for VisualAge PL/I Version 2 Release 2)

LRECL=125 (for all other PL/I compilers)

Setup creates a breakpoint table (BRKTAB) and uses it along with the objectmodule created at compile time to create a new object module containing thebreakpoint data. Once the breakpoints have been inserted into the object moduleor modules, link-edit the object modules into the executable load module. Alterna-tively, the Setup job can insert breakpoints directly into load modules. In addition, ifthe COBOL TEST (COUNT for OS/VS COBOL) compiler option is used in conjunc-tion with the COBOL control statement EXTPROGRAM-ID keyword, no listing isrequired by Setup and the load module is processed directly. For more information,see “Instrumenting load modules without listings” on page 220.

For DA and UTA, Setup also creates a debug table (DBGTAB) of data on variablesto read. DA and UTA use the DBGTAB table during the Execution and Reportsteps.

Also for DA and UTA, Setup creates a VARCTL file that contains variable locationinformation. DA and UTA use the VARCTL file during Execution.

The steps involved in the Setup procedure for CA are shown in Figure 71 onpage 218. The DA and UTA Setup procedure is shown in Figure 72 on page 218.The names outside the boxes in the figures (for example, BRKTAB) correspond tothe DDNAMEs in the created JCL.


Figure 71. CA Setup—flow diagram. The asterisk (*) indicates that user program listingsmay not be needed for COBOL programs if the TEST (COUNT for OS/VS COBOL) compileroption is used.

Figure 72. DA and UTA Setup—flow diagram


Instrumenting load modules using listingsYou can instrument breakpoints into your object modules before you link them intoan executable load module, or you can instrument breakpoints into the executableload module. For locations where instrumenting object modules is difficult becausethe link step is built into the standard location-wide build procedures, instrumenta-tion of load modules can be used.

Note that instrumenting load modules is not supported for VisualAge PL/I Version 2Release 2.

The samples shipped with ATC show how to instrument object modules.

To instrument object modules for the COB01 test case, the following control filewould be used:


LoadMod=COB01,



COB01A: COBOL ListMember=COB01A

COB01B: COBOL ListMember=COB01B

COB01C: COBOL ListMember=COB01C

COB01D: COBOL ListMember=COB01D

To instrument load modules, the control file is changed. All other steps remain thesame, except you can skip the step that links the instrumented object modules intoa program to test.

For example, to instrument the load module for the COB01 test case, the followingCOBOL control file would be used:


LoadMod=COB01,



COB01A: COBOL ListMember=COB01A

COB01B: COBOL ListMember=COB01B

COB01C: COBOL ListMember=COB01C

COB01D: COBOL ListMember=COB01D

The FromObjDsn and ToObjDsn keywords that identify object module libraries arenot used. Instead you use the FromLoadDsn and ToLoadDsn keywords. If bothFromLoadDsn and ToLoadDsn are supplied, the load module is copied beforebeing instrumented. If only the ToLoadDsn keyword is supplied, the load module isinstrumented in place.

You cannot use both object module instrumentation (use of FromObjDsn andToObjDsn keywords) and load module instrumentation (FromLoadDsn andToLoadDsn keywords) in the same set of control cards.

Within a control file, each compilation unit should contain a unique externalprogram name (for COBOL, PROGRAM-ID; for PL/I, procedure name; and forassembler, CSECT name).


The load module copy step (using IEBCOPY) will not work for load modules thathave aliases.

The instrumentation of the load module is done using the IBM utility AMASPZAP(sometimes referred to as the Superzap utility). Your location may restrict the useof this utility. Contact your system support personnel if you cannot access it.

Instrumenting load modules using the AMASPZAP utility takes significantly longerthan instrumentation of object modules for large programs.

Instrumenting load modules without listingsFor COBOL programs, you can measure coverage without providing listings. If youcompile your COBOL program with the TEST option (the COUNT option for OS/VSCOBOL) and use the EXTPROGRAM-ID keyword on the COBOL control state-ment, listings are not required for the Setup step that inserts breakpoints into yourprogram.

The advantages of this method are:

� No listings are needed for the Setup step that instruments your program.

� Instrumented programs can execute successfully when no monitor session hasbeen started for them.

The disadvantages are:

� Branch coverage cannot be measured.

� Only a Summary report can be generated (however, if you have a listing, youcan generate an Annotated Listing report and a Targeted Summary report fromit).

� Only coverage is measured; UTA and DA functions require listings.

� Within a control file, each compilation unit should contain a unique externalprogram name (for COBOL, PROGRAM-ID).

� Load modules will be larger.

� For OS/VS COBOL, the Verb counts written to the SYSCOUNT DD will all be0. In addition, if the SYSCOUNT and SYSDBOUT DDs are not allocated, thefollowing messages will be issued (but the program will function normally):

IEC130I SYSCOUNT DD STATEMENT MISSING

IEC130I SYSDBOUT DD STATEMENT MISSING

+IKF180I UNABLE TO OPEN THE SYSDBOUT DATA SET -- DEBUGGING OPTIONS CANCELLED

If you test programs from a common program library, where all of the programshave been instrumented, the simplicity of being able to only start monitor sessionsfor programs of interest can be useful. Testers who are not interested in coveragedo not need to be concerned about testing from a separate library. A tester whowants to measure coverage on some programs but not others does not need to beconcerned about selecting the correct program libraries for each test scenario; thetester just starts monitor sessions for the programs to be measured and alwaystests from the same library. As shipped, the feature that allows you to run instru-mented programs without a monitor session is not active, see the end of thissection for information describing how to enable this feature.


To measure code coverage without listings via the COBOL TEST option, do thefollowing:

1. Compile programs of interest with the TEST option (for OS/VS COBOL, compilewith the COUNT option):

� COBOL for OS/390 & VM and COBOL for MVS & VM: TEST,TEST(ALL,NOSYM), or TEST(ALL,SYM)

TEST with no suboptions defaults to TEST(ALL,SYM). ATC does notrequire the SYM suboption that puts symbol table data in the module fordebuggers. This increases the size of the module. Only use the SYM sub-option if you want to use a debugger.

� VS COBOL II: TEST and RESIDENT

The use of RESIDENT requires that the VS COBOL II (or Language Envi-ronment for MVS & VM) runtime library be available at runtime.

� OS/VS COBOL: COUNT

2. Create a control file for the TEST option:

Note: In the following example:

� ExtProgram-ID is the external program-ID of the COBOL programyou want to analyze.

� ExtProgram-ID, FromLoadDsn, ToLoadDsn, and LoadMod must bespecified.

� ListDsn and ListMember are only needed if you want to generate anAnnotated Listing report.


LoadMod=COB02,



COBOL ListMember=COB02,ExtProgram-ID=COB02

3. Create and execute the Setup JCL.

4. Start monitor session for your testing.

5. Execute your test cases.

6. Stop monitor session.

7. Create and execute summary JCL (and Annotated Listing report JCL and Tar-geted Summary report JCL, if you have listings and desire these reports).

As shipped, the ATC monitor will abend instrumented (as described in this topic)COBOL programs when there is no monitor session started for them. To be able torun instrumented COBOL programs with no monitor session, have your system pro-grammer reinstall the monitor after changing the parameters passed to the installprogram (SATGSAMP members ATGXISVC and ATGXPSVC) to add theTESTOPT option. For more information, see “Installing and enabling the monitorSVCs” on page 14.

//L INSTALL PARMS TO RUN INSTRUMENTED COBOL PGMS WITH NO SESSION

//L SEE USERS GUIDE ABOUT USE OF COBOL TEST COMPILE OPTION

//L SVC number1, SVC number 2, TESTOPT

//INSTATC EXEC PGM=ATGOMNST,PARM=(FE,FF,TESTOPT)


Creating the Setup JCL using the panelsTo create the setup JCL:



2. Select option 2.

The Create JCL for Setup panel, shown in Figure 73, is displayed. Each fieldon the panel is described following the figure.

3. Enter any information you want to change, select option 1, and press Enter.

Z [ ----------------------------- Create JCL for Setup ----------------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL


Process Options:

Enable CA YES (Yes|No) Enable DA NO (Yes|No) Enable UTA YES (Yes|No)


CA/DA/UTA Control File:



JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(SCOB01)'

Output Breakpoint Table:


DA/UTA Output Debug Table and Variable Control Files:


Variable Control Dsn. 'YOUNG.SAMPLE.COB01.VARCTL'

\ ]

Figure 73. Create JCL for Setup panel

The panel's options and fields are as follows. In most cases, you only need tochange the Program Name field and then press Enter. The defaults for theSetup step are used.

GenerateGenerates JCL using the parameters you have specified on thepanel.

EditDisplays an ISPF edit session for you to make changes to existingJCL.

SubmitSubmits for execution the JCL specified in the JCL Dsn field on thispanel.


Enable CASpecifies whether Coverage Assistant's Setup JCL is to be gener-ated.

Enable DASpecifies whether Distillation Assistant's Setup JCL is to be gener-ated. If you set this option to YES, set Enable UTA to NO.

Enable UTASpecifies whether Unit Test Assistant's Setup JCL is to be gener-ated. If you set this option to YES, set Enable DA to NO.


When you press Enter, the file names on the panel are changedautomatically. Using the program name is the normal ATC proce-dure.

Program NameName to use for ATC files if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name. Itdoes not have to be the name of any of your programs. Names ofthe following form are created:







Control File DsnSpecifies the control file (CACTL) data set containing the names ofthe listing files being annotated and the variables being read. If youwant to edit the control file, you can do so from the Work with theCA/DA/UTA Control File panel.


Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data setwill be Sxxxxxxx, where xxxxxxx is the last seven characters of theprogram name.

Breakpoint Table DsnName of the BRKTAB data set created during Setup and used bythe monitor program.


Debug Table DsnName of the data set containing the variables that UTA is to monitorand the files that DA is to monitor.

Variable Control DsnName of the data set containing the variable information.

When to create or submit Setup JCLRun the Setup JCL if:

� A user program (and consequently, the listing) changes.� You change the variables to read.

You only need to recreate the Setup JCL if the test environment changes.

For example, if you:

� Add or delete listings in the CACTL, recreate the Setup JCL from the panel,and run the new Setup JCL.

� Change a listing, then submit the old Setup JCL without changes.� Change a variable in the CACTL, submit the old Setup JCL without changes.

Setup JCL for the compile job streamIf you insert the JCL that creates Setup output files in your compile job stream,whenever you change a module and recompile, the Setup output files are createdand saved automatically.

You can create this JCL by modifying the sample JCL in the ATC JCL library or bygenerating the Setup JCL from the Create JCL for Setup panel.

Parameters for the Setup and Zaptxt programsThis section describes the input parameters you can provide to the Setup andZaptxt programs.

SetupThe Setup program input parameters are created automatically from the defaultsfile. The ATGOSETP load module is used when listings are analyzed. TheATGOSETL load module is used when the COBOL control card'sEXTPROGRAM-ID keyword is used in conjunction with the COBOL TEST (COUNTfor OS/VS COBOL) compiler option.

The parameters are as follows:

──LoadMod──,──LPDFRP──,──Listing_file_name──,──2-byte_SVC_#──,──────────

──4-byte_SVC_#─ ──┬ ┬────────────────────── ─────────────────────────────── � └ ┘ ─,──common_parameters─

LoadMod Load module name. This is the name of the load module that containsthe PA or CSECT name.


LPDFRP This is a string of six characters with no imbedded blanks. Each char-acter specifies a separate parameter in the following order:

� List_Type � PA_Type � Debug_mode � Frequency_count_mode � Read_Variable_data � Performance_mode

─ ──┬ ┬─B─ ─── ──0─ ──┬ ┬─Y─ ──┬ ┬─Y─ ──┬ ┬─Y─ ──┬ ┬─Y─ ────────────────── �├ ┤─P─ └ ┘─N─ └ ┘─N─ └ ┘─N─ └ ┘─N─

└ ┘─A─

List_TypeThe type of listing.B For COBOLP For PL/IA For Assembler

PA_TypeProgram Area Type.0 For DASD resident program

Debug_modeUse Debug Mode?

Y Use debug mode: execute breakpoints as many times asencountered. Note: Use debug mode only at the direction ofATC support personnel or as directed by this manual.

N Do not use debug mode: only execute breakpoints once.Note: For CA, DA, and UTA, set to N. See also “Displayingexecution counts in an Annotated Listing report” on page 85for more information about the use of this flag.

Frequency_count_modeUse Frequency Count Mode?

Y Save frequency and branch to information (for branches) in thecoverage file (BRKOUT). This adds 16 bytes per breakpoint tothe BRKOUT size. This can be set to N, unless you want theEvents count information in the Annotated Listing report.

N Do not save the Events count and branch to information in theBRKOUT file. Note: For CA, set to N unless analyzing assem-bler code with relative branches (see “PROGRAM AREADATA” on page 75), displaying execution counts (see “Dis-playing execution counts in an Annotated Listing report” onpage 85). For DA, set to N unless recording first execution ofDA keys (see“Recording which keys execute a statement” onpage 126). For UTA, set to N.


Read_Variable_dataRead Variable Data?

Y DA and UTA can read file keys and variable data.

N Do not set read points for DA and UTA. Note: For CA, set toN. For UTA and DA, set to Y.

Performance_modeUse Performance Mode?

Y Conditional branch coverage is disabled.

N Conditional branch coverage is enabled.

For more information, see “Using the Performance Mode to reducemonitor overhead” on page 235.

Listing_file_nameListing file name used to determine breakpoint placement, or externalprogram ID for a COBOL program if you used the COBOL control state-ment's EXTPROGRAM-ID keyword.

2-byte_SVC_#SVC number (in hexadecimal notation) for breakpointing 2-byteinstructions.

4-byte_SVC_#SVC number (in hexadecimal notation) for breakpointing 4- and 6-byteinstructions.

common_parametersAny of the parameters described in Appendix F, “Parameters CommonTo Multiple Routines” on page 381 (separated by commas).

ZaptxtThe Zaptxt program inserts breakpoints in user programs. The ATGOZAPT loadmodule inserts breakpoints into object modules. The ATGOZAPL load modulebuilds input for AMASPZAP to insert breakpoints into load modules. These pro-grams have one required input parameter, which is built automatically by the ISPFdialog during the creation of the Setup job.

//OBJZAP EXEC PGM=ATGOZAPT,PARM='x'

or

//OBJZAP EXEC PGM=ATGOZAPT,PARM='x,common_parameters'

where:

x is a number that indicates which BRKTAB in the BRKTAB data set to use.

common_parametersare any of the common parameters described in Appendix F, “ParametersCommon To Multiple Routines” on page 381 (separated by commas).


Chapter 23. Monitor execution

This chapter describes the procedures for running a monitor session on MVS. Themonitor handles the user supervisor call instructions (SVCs) that are used asbreakpoints (BPs).

You install the monitor by running the monitor installation program during ATCinstallation. For details about installing the monitor, see Chapter 2, “Systeminstallation” on page 7.

You create the JCL to start a monitor session from the Create JCL to Start theMonitor panel (shown in Figure 77 on page 229). Multiple user sessions can beactive at the same time.

The monitor program examines the breakpoint table information (and for UTA andDA, the variable control information) produced by the Setup step and accumulatesdata as the application program test case executes. When you execute theATGSTOP command, the monitor writes the results to disk. The CA execution flowis shown in Figure 74, the DA execution flow is shown in Figure 75 on page 228,and the UTA execution flow is shown in Figure 76 on page 228.

When the monitor session is started, the tables needed for handling the session arecreated in ECSA. For the amount of storage used for a user session, seeAppendix B, “ATC requirements and resources” on page 359. For more details onrunning multiple sessions, see page 231.

Figure 74. CA test case execution—flow diagram

Chapter 23. Monitor execution 227

Figure 75. DA test case execution—flow diagram

Figure 76. UTA test case execution—flow diagram


Creating the monitor JCL using the panelsTo create the monitor JCL:



2. Select option 3.

The Create JCL to Start the Monitor panel, shown in Figure 77 is displayed.

3. Enter any information you want to change, select option 1, and press Enter.

Z [ ----------------------- Create JCL to Start the Monitor -----------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL


Process Options:

Enable CA YES (Yes|No) Enable DA NO (Yes|No) Enable UTA YES (Yes|No)


Session ID . . . . . . YOUNG

Input File:


DA/UTA Input File:

Variable Control Dsn. 'YOUNG.SAMPLE.COB01.VARCTL'


JCL Dsn . . . . . . . 'YOUNG.SAMPLE.JCL(XCOB01)'

Output File:


DA/UTA Output File:


\ ]

Figure 77. Create JCL to Start the Monitor panel


GenerateGenerates JCL from the parameters you have specified on the panel.

EditDisplays an ISPF edit session for you to make changes to existing JCL.


Enable CASpecifies whether Coverage Assistant's execution JCL is to be gener-ated.


Enable DASpecifies whether Distillation Assistant's execution JCL is to be gener-ated. If you set this option to YES, set Enable UTA to NO.

Enable UTASpecifies whether Unit Test Assistant's execution JCL is to be gener-ated. If you set this option to YES, set Enable DA to NO.

Use Program Name for File NameIf you want to construct the data set name from the default high-levelqualifier, the specified program name, and the default low-level qualifierfor each data set, enter YES.

When you press Enter, the file names on the panel are changed auto-matically. Using the program name to construct the data set names isthe normal ATC procedure.

Program NameName to use for ATC files if you enter YES in the Use Program Namefor File Name field. Note that this can be any valid name. It does nothave to be the name of any of your programs. Names of the followingform are created:







Session IDSession ID for your session. This defaults to your TSO user ID. Mul-tiple testers can use the monitor simultaneously. For more information,see “Multiple user sessions” on page 231 for details.

Breakpoint Table DsnName of the BRKTAB data set created during Setup and used by themonitor program.

Variable Control DsnName of the data set containing the variable control information (createdduring Setup).


Note: If the Use Program Name for File Name field is set to YES,then the member name or program name qualifier of the data set will beXxxxxxxx, where xxxxxxx is the last seven characters of the programname.

Breakout DsnName of the BRKOUT data set created during Execution and used bythe Report program.


Variable Table DsnName of the variable table data set, which is a work file containing inter-mediate results of information gathered when variables were monitored.

Parameters for Start monitor (ATGOMCMD)You can provide the following input parameters to the start monitor routine:

──START──,──Session_ID─ ──┬ ┬───────────────────────────────────── ─────── � └ ┘─,──,──,──,──,──,──common_parameters─

START The user is trying to start a new session (with the ID passed inthe Session ID parameter). Up to 32 sessions can be active onthe same MVS system.

Session_ID An eight-character string that identifies the session.

common_parametersAny of the common parameters described in Appendix F,“Parameters Common To Multiple Routines” on page 381 (sepa-rated by commas).

Parameters for Variable monitor (ATGOMVAR)You can provide the following input parameters to the variable monitor routine.

──Session_ID──,──MinWait──,──MaxWait─ ──┬ ┬────────────────────── ──────── � └ ┘ ─,──common_parameters─

Session_ID An eight-character string that identifies the session. This mustmatch the Session ID passed to ATGOMCMD.

MinWait The minimum wait time to write buffers (in 1/100 seconds)

MaxWait The maximum wait time to write buffers (in 1/100 seconds)

common_parametersAny of the common parameters described in Appendix F,“Parameters Common To Multiple Routines” on page 381 (sepa-rated by commas).

Multiple user sessionsMore than one tester can execute simultaneously on an MVS system. Each sepa-rate invocation of the monitor is called a session. The monitor identifies sessionsby a session ID passed to it as a parameter. The Create JCL to Start the Monitorpanel, which creates the JCL, creates a session ID from the tester's TSO user IDor a user-specified session ID. Each tester can start or stop a session independ-ently of any other tester.


Change the session ID to a user-defined ID by either changing the Session IDoption on the Create JCL to Start the Monitor panel or by editing the start monitorJCL. To change the session ID by editing the start monitor JCL, change each ofthe following to the ID you choose:

� The second qualifier in the following data set names: – prefix.sessid.EXTEMP.EXEC – prefix.sessid.TEMP.VMTEMP

� The second parm to the ATGOMCMD program� The first parm to the ATGOMVAR program (optional; only used for DA and

UTA)

Changing the session ID lets you create custom batch test runs for automation pur-poses.

Any user can stop or cancel any session if the user knows the session ID (whichcan be determined by issuing the ATGSESSN command). This may be necessary,for example, if there are plans to IPL the system, which will cause the loss of testdata.

Coverage of common modules with multiple user sessionsWhen multiple testers simultaneously execute shared modules, coverage reportsare affected. In some environments (for example, CICS), only one copy of amodule is in storage for all users of that module.

In general the following rules apply. When multiple testers execute a monitoredmodule, and the module is monitored by:

1. Only one session (its BRKTAB appears in only one session), all coverage fromall testers appears in that session's coverage data.

2. Multiple sessions (its BRKTAB appears in multiple sessions), the first session inwhich the module is started will usually receive all of the coverage data. Othersessions where the module is monitored will show no coverage data.

The following topics in this chapter describe various scenarios in which the monitormay be used:

1. “Multiple testers executing code in a module monitored by one session” onpage 233

2. “Multiple testers executing code in a module monitored by multiple sessions” onpage 234

3. “Multiple testers executing code in a module, but each tester with a uniquecopy of the module” on page 235


Multiple testers executing code in a module monitored by one session: Thisexample describes multiple testers executing the same module, but only onesession is monitoring the module:

Table 14. Multiple testers executing code in a module monitored by one session

Setup Start SessionExecuteCode

Tester 1 � Listings for module A,module C, and module D

� Instrumented objectslinked into executablemodules A through F

� Session 1 � BRKTABs from

module A,module C, andmodule D

In modules Athrough F

Note: Tester 1 is monitoring the coverage of modules A, C, and D, butrunning test cases that execute modules A through F.

Tester 2 � Listings for module B andmodule E



module B andmodule E


Note: Tester 2 is monitoring modules B and E, but executing test casesthat execute modules A through F.

Tester 3 � Listings for module F � Instrumented objects

linked into executablemodules A through F


module F


Note: Tester 3 is monitoring module F, but executing test cases thatexecute modules A through F.

The coverage data from session 1 will be the cumulative coverage of all threetesters for modules A, C, and D. There is no way for Tester 1 to know what cov-erage data was caused by each tester. The same is true for the coverage datafrom session 2 and session 3.


Multiple testers executing code in a module monitored by multiple sessions:This example describes multiple testers executing the same module, with multiplesessions monitoring identical modules.

Common Setup is performed for modules A through F and instrumented objects arelinked into executable modules A through F

Table 15. Multiple testers executing code in a module monitored by multiple sessions


Tester 1 � Listings for modules Athrough F



module A,module C, andmodule D


Note: In session 1, Tester 1 is monitoring the coverage of modules A, C,and D, but running test cases that execute Modules A through F.




module B,module C, andmodule E


Note: In session 2, Tester 2 is monitoring modules B, C and E, but exe-cuting test cases that execute modules A through F.




module B andmodule F


Note: In session 3, Tester 3 is monitoring modules B and F, but exe-cuting test cases that execute modules A through F.

Assume the order that the sessions were started is session 1, session 2, and thensession 3. Note that module C is being monitored in sessions 1 and 2, and moduleB is being monitored in sessions 2 and 3.

Any coverage in C from any tester will usually be shown in session 1. Even thoughSession 2 is monitoring C, the coverage data for C from session 2 will probablyshow no coverage. The same is true for module B, monitored by sessions 2 and 3.Coverage for B will show up in session 2.

However if session 1 is stopped, any subsequent execution of module C will nowappear in the session 2 coverage data. The same will be true for module B, ifsession 2 is stopped but session 3 is still active.


Multiple testers executing code in a module, but each tester with a uniquecopy of the module: Each tester can ensure unique coverage data for test casesrun by that tester, by using the following procedure:

Table 16. Multiple testers executing code in a module, but each tester with a uniquecopy of the module



� Link into modules A1through F1


modules Athrough F fromTester 1 Setup

In modulesA1 throughF1











Each tester performed a unique Setup for the code to be monitored in modules Athrough F. Then the instrumented objects were linked into unique executablemodules Ax through Fx. The coverage statistics represent testing done by an indi-vidual tester and no one else.

Using the Performance Mode to reduce monitor overheadMeasuring when a conditional branch branches takes more overhead because thebreakpoint at the conditional branch must be left in storage. If the increased over-head is unacceptable for your testing, conditional branch coverage can be turnedoff. You can do this by setting the Performance Mode. Set the Performance Modein either of the following ways:

1. Change a default setting. Change the Performance Mode default (in the SetupDefaults section of ATC Defaults) to Yes. For more information, see “Modifyingyour ATC defaults” on page 19. Any BRKTAB files created in the Setup stepwill have a flag set to indicate that conditional branches should not be left instorage.

2. Issue a command to turn Performance Mode on temporarily during testing.After a session is started, turn Performance Mode on or off by entering thefollowing commands:

a. EX 'hi_lev_qual.SATGEXEC(ATGPRON)' enables Performance Modeb. EX 'hi_lev_qual.SATGEXEC(ATGPROFF)' disables Performance Mode


When the Performance Mode is set on via Setup, the Summary report for the testrun will not show conditional branch coverage. For more information, see “Sup-pression of conditional branch coverage with Performance Mode” on page 71. Theannotation for conditional statements in an Annotated Listing report is also modi-fied. For more information, see “Changes in annotation symbols with PerformanceMode” on page 86.

When the Performance Mode is set off via Setup, and then later enabled viaATGPRON, then Summary reports and Annotated Listing reports will still includeconditional breakpoint information, although the data may be incomplete.

Restrictions on types of programs that can be monitoredATC can only replace breakpoints in user programs using the key of the userprogram. This means that user programs running in read-only storage cannot beexecuted if they are instrumented with the breakpoints needed for the CA, DA, orUTA tools.

A reentrant program runs in read-only storage when it is executed as follows:

1. Loaded in a CICS region with reentrant program protection (controlled by theCICS RENTPGM=PROTECT system initilization parameter)

2. Loaded from an authorized library

3. Loaded from the link pack area (LPA)

For item 1 in the previous list, testing can be done in a CICS region without reen-trant program protection (RENTPGM=NOPROTECT).

For item 2 in the previous list, relink the program as non-reentrant, or place theprogram in a non-authorized library (if possible).

System abend 0F8 on user programA type 3 user SVC is used for a breakpoint. There are some system modes thatcannot be in effect when this type of SVC is issued. Typically these would only beused in assembler code. If a breakpoint is hit when one of these system modes isin effect, an 0F8 system abend occurs.

For details on which system modes can lead to this abend, see the reason code listfor an 0F8 system abend code in the MVS/ESA System Codes or OS/390 MVSSystem Codes manuals (except for reason code 18, AR mode, which is not arestriction with the ATC breakpoint SVCs).

Restrictions on where programs can be monitoredYou must start and stop the monitor session on the same MVS image on whichmonitored programs are run.


Buffer monitorA buffer monitor program is available for UTA and DA. The buffer monitor staysresident while your session is active in order to write full buffers of data to disk.Two buffers are used: one is written to disk and the other saves data.

The size of each buffer is 65536 bytes. These buffers reside in ECSA storage.

You can specify the minimum and maximum times that the buffer monitor programchecks for full buffers. As shipped, the minimum time is 20 (.2 seconds) and themaximum time is 800 (8 seconds). These times are in hundredths of a second.Valid settings range from 20 to 1600. If you try to set times outside of this range, awarning message is displayed and the time is set within this range.

Your program may access variables to be saved faster than they can be written todisk, which causes a buffer overflow and a loss of data occurs. The followingstatement appears in the VARDATA report if a buffer overflow and a loss of dataoccurs:

11915 1 1 38 KYLEX 3722AIX.

11916 1 1 38 KYLEX 3723AIX.


11917 1 1 38 KYLEX 0000MVS.

The buffer monitor program is resident as long as your session is active. The jobthat started your monitor session stays active until you end your session with theATGSTOP or ATGQUIT command. This is not true for CA monitor sessions. ForCA sessions, there is no buffer monitor program, and your start monitor job endsonce your monitor session has been established.



Chapter 24. Monitor commands

Several commands are available to control the execution monitor and to displaystatistics. These commands, which are described in this chapter, can only be exe-cuted while the monitor is running.

Note: A common monitor program executes for the CA, DA, and UTA tools andthe commands described in this chapter are valid for all three tools.

The command execs are shipped in a partitioned data set (PDS) namedhi_lev_qual.SATGEXEC. Any status messages resulting from the commands arewritten to the data set prefix.MSGS.FILE. If this data set does not exist, it iscreated when a command is issued.

Issuing commandsYou can issue commands in the following ways:

� From the Control the CA/DA/UTA Monitor panel, shown in Figure 78 onpage 240. The commands are listed on the panel. If you select a command, apanel is displayed allowing you to enter any command parameters.

� From the TSO command line. Some commands have optional parameters thatcan be passed. The explicit invocation shows the method for passing parame-ters to the command. The following is an example of issuing a command fromthe TSO command line:

EX 'hi_lev_qual.SATGEXEC(cmdname)' 'parm1 parm2'

� From MVS BATCH using JCL. This method is useful in automating test caseruns. The JCL can be embedded in your batch stream. When the commandsare executed in batch mode, the MSGS.FILE is appended with messages fromeach command executed in the job. You can view this file for problem determi-nation. The following is an example of issuing commands using JCL:

//YOUNGC JOB (12345678),

// YOUNG,NOTIFY=YOUNG,USER=YOUNG,

// TIME=1,MSGCLASS=H,CLASS=A,REGION=2M

//L SAMPLE JCL TO EXECUTE CA COMMANDS:

//L FIRST A ATGSTATS COMMAND IS EXECUTED, WITH RESULTS IN

//L YOUNG.MSGS.FILE

//L NEXT A ATGSTOP COMMAND IS EXECUTED

//TSOTMP EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K

//SYSEXEC DD DSN=hi_lev_qual.SATGEXEC,DISP=SHR//SYSTSPRT DD SYSOUT=L

//SYSUDUMP DD SYSOUT=L

//SYSTSIN DD L

ATGSTATS YOUNG 1 1 9999

ATGSTOP

/L

To see a list of the ATC operator commands common to CA, DA, and UTA, selectoption 1 from the ATC Primary Option Menu and option 7 from the Coverage,Distillation, and Unit Test Assistant panel. This displays the Control theCA/DA/UTA Monitor panel, shown in Figure 78 on page 240, which contains a listof commands you can select.

Chapter 24. Monitor commands 239

Each command on the Control the CA/DA/UTA Monitor panel is described in moredetail in the topics that follow in this chapter.

Z [------------------------ Control the CA/DA/UTA Monitor -----------------------

Option ===>

1 Start Create JCL to Start the Monitor

2 Stop Stop monitor execution normally (ATGSTOP)

3 SessDisplay Display all active sessions (ATGSESSN)

4 Listings Display listings (ATGSLIST)

5 Statistics Display statistics (ATGSTATS)

6 BPDisplay Display Breakpoint status (ATGRBPDS)

7 VADisplay Display Variable status (ATGRVADS)

8 AddId Specify a unique testcase id (ATGRIDAD)

9 Snapshot Take snapshot of data (ATGSNAP)

10 Reset Reset all data in monitor (ATGRESET)

11 Quit Terminate monitor without saving breakpoint data (ATGQUIT)


\ ]

Figure 78. Control the CA/DA/UTA Monitor panel


ATGPROFFThe ATGPROFF command turns the monitor Performance Mode off. This enablesconditional branch coverage. The BPs needed for conditional coverage are left instorage. Note that overhead will be higher when these BPs are left in storage.

If you are not interested in conditional coverage, turn the Performance Mode on,either by changing the default parameter that controls Performance Mode beforeyou generate the JCL for the Setup step, or by using the ATGPRON command.Performance mode can be turned on and off for all PAs or for a selected PA.

You enter this command on the command line:

EX 'hi_lev_qual.SATGEXEC(ATGPROFF)' 'parameters'

where parameters are specified in the following syntax:

─ ──┬ ┬──────────── ──┬ ┬──────────────────────────────────────────── ────── � └ ┘─session_id─ └ ┘ ─,─ ──┬ ┬─────────── ──┬ ┬────────────────────── └ ┘─PA_number─ └ ┘ ─,──common_parameters─

where:

session_id The session for which to turn Performance Mode off. The defaultis the TSO user ID.

PA_number The PA number. The default is all PA's in the requested session.

common_parametersAny of the common parameters described in Appendix F, “Param-eters Common To Multiple Routines” on page 381 (separated bycommas).

Use the ATGSTATS command to get the PA number for selectively resetting break-points.

Example 1:

To turn Performance Mode off for all PAs, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGPROFF)'

Example 2:

To turn Performance Mode off for session YOUNG, PA 2, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGPROFF)' 'YOUNG, 2'


ATGPRONThe ATGPRON command turns the monitor Performance Mode on. This disablesconditional branch coverage. The BPs needed for conditional coverage are not leftin storage. Note that overhead will be higher when these BPs are left in storage. Ifyou are not interested in conditional coverage, turn the Performance Mode on,either by changing the default parameter that controls Performance Mode beforeyou generate the JCL for the Setup step or by using the ATGPRON command.Performance Mode can be turned on and off for all PAs or for a selected PA.


EX 'hi_lev_qual.SATGEXEC(ATGPRON)' 'parameters'



where:

session_id The session for which to turn Performance Mode on. The defaultis the TSO user ID.




Note: If the BRKTAB for this session was built with the Performance Mode flagset to N (off), then the Summary and Annotated Listing reports will still include(possibly incomplete) conditional breakpoint information after this command isissued.

Example 1:

To turn Performance Mode on for all PAs, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGPRON)'

Example 2:

To turn Performance Mode on for session YOUNG, PA 2, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGPRON)' 'YOUNG, 2'


ATGQUITThe ATGQUIT command, issued from the panel shown in Figure 79, is the sameas ATGSTOP, except that no output file is written (BRKOUT or VARTAB).

Z [---------------------------- Monitor: Quit Monitor ----------------------------

Option ===>_

Quit Monitor Without Saving Breakpoint Data:

Override default session id NO (Yes|No)

\ ]

Figure 79. Monitor: Quit Monitor panel 1

When you press Enter from this panel, the monitor displays the panel shown inFigure 80, allowing you to enter additional parameters.

Z [---------------------------- Monitor: Quit Monitor ----------------------------

Option ===>_

Press ENTER to Quit Monitor Without Saving Breakpoint Data:


Session Id . . . .

\ ]

Figure 80. Monitor: Quit Monitor panel 2


EX 'hi_lev_qual.SATGEXEC(ATGQUIT)' 'parameters'


─ ──┬ ┬──────────── ──┬ ┬────────────────────── ──────────────────────────── � └ ┘─session_id─ └ ┘ ─,──common_parameters─

where:

session_id The session to cancel. The default is the TSO user ID.


When the quit command completes, a panel such as the one shown in Figure 81on page 244 is displayed.


Z [ -------------------------------------------------------------------------------

BROWSE YOUNG.MSGS.FILE Line 00000000 Col 001 080

Command ===>_ Scroll ===> PAGE

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL Top of Data LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

Session YOUNG ended no data written.

LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL Bottom of Data LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL

\ ]

Figure 81. Quit monitor status panel

ATGRBPDSThe ATGRBPDS command, issued from the panel shown in Figure 82, displays thestatus of breakpoints.

Z [---------------------- Monitor: Display Breakpoint Status --------------------

Command ===>

To display breakpoint status, complete the menu below and press ENTER:

Session id . . . . . . . . YOUNG

List number . . . . . . . 1

PA number. . . . . . . . . 1

First breakpoint number . 1

Last breakpoint number . . 9999

\ ]

Figure 82. Monitor: Display Breakpoint Status panel

Note: This command may produce a large amount of data, so use it with dis-cretion.



EX 'hi_lev_qual.SATGEXEC(ATGRBPDS)' 'parameters'


─ ───(1) ──┬ ┬────────────────────────────────────────────────────────────────── ───── � └ ┘ ─session_id─ ──┬ ┬────────────────────────────────────────────────── │ │┌ ┐─1──── └ ┘ ─␣─ ──┴ ┴─list─ ──┬ ┬───────────────────────────────── │ │┌ ┐─1───────── └ ┘─␣─ ──┴ ┴─PA_number─ ─┤ MoreParms ├─

MoreParms:├─ ──┬ ┬────────────────────────────────────────────────────────────── ──────────────┤ │ │┌ ┐─1──────── └ ┘ ─␣─ ──┴ ┴─bp_start─ ──┬ ┬───────────────────────────────────────── │ │┌ ┐─9999─── └ ┘ ─␣─ ──┴ ┴─bp_end─ ──┬ ┬────────────────────── └ ┘ ─␣──common_parameters─

Note:1 Trailing commas may be omitted.

where:

session_id Session ID to be displayed. The default is the TSO user ID.


list Listing number.

PA_number The PA number. The PA number is 1 origined for the specifiedlisting.

bp_start BP number of the first breakpoint in the PA you want displayed.

bp_end BP number of the last breakpoint in the PA you want displayed.

common_parametersAny of the common parameters described in Appendix F, “Param-eters Common To Multiple Routines” on page 381 (separated byblanks).

Example 1

To display all breakpoints in LIST 1, PA 1 of your session ID, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGRBPDS)'

Example 2

To display all breakpoints for session YOUNG in LIST 1, PA 2 with a bp≥10 and≤50, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGRBPDS)' 'YOUNG 1 2 10 50'


A status panel, such as that shown in Figure 83, is displayed.

Z [ -------------------------------------------------------------------------------




Num Listing Date Time PAs BPs VAs

--------------------------------------------------------------------------------

001 YOUNG.SAMPLE.COBOLST(COB01A) 99.204 07:08.54 00005 000031 00000

PA ADR BPS EVNTS ACTVE

--------------------------------------------------------------------------------

00001 00000000 000006 0000000000 000006

RNUM OFFSET OPCD BRNCH TO EVENTS 1ST KY VRIX LB NB AB DE CT CF BV B> AC

--------------------------------------------------------------------------------

4F39 00025C D2078020 00000000 000000000 000000 X X

419D 000262 D2048020 00000000 000000000 000000 X X

4ED1 000268 D2028025 00000000 000000000 000000 X X

4824 00026E D2018020 00000000 000000000 000000 X X

F131 000274 D2028022 00000000 000000000 000000 X X

948B 00027A D2028025 00000000 000000000 000000 X X


\ ]

Figure 83. Breakpoint status panel

The following fields are displayed for the selected listing and PA:

NumSequential listing number.

ListingListing data set name.

DateDate of compile.

TimeTime of compile.

PAsNumber of PAs in listing.

BPsNumber of BPs in listing.

VAsNumber of variable reads in listing.

PASequential PA number.

ADRIf the program has executed, this is the storage address of the PA.

BPSNumber of BPs in this PA.

EVNTSNumber of events (BP executions) for this PA.

ACTVENumber of active BPs in the PA.


The following fields are displayed for each breakpoint:

RNUMRandom number for this long SVC BP (0 if short SVC BP).

OFFSETThe hexadecimal offset of the breakpoint in the PA.

OPCD (op code)The op code of the instruction at the breakpoint.

BRNCH TO (branch to)If this is a branch instruction that has branched, this is the targetaddress. If it starts with FF, the address is an offset within this PA.

EVENTSThe number of times this breakpoint was executed before it wasremoved. For CA, breakpoints are removed as soon as possible, sothat most breakpoints are only executed once. In some cases, condi-tional branch breakpoints must stay in memory and are executed morethan once.

1ST KYFor Distillation Assistant, the key number that caused the BP to executefor the first time.

VRIXThe index into the VARCTL file for a UTA/DA read at this BP.

LBFor UTA/DA, this BP left in storage.

NB (not a branch)If not a branch instruction, this is an X.

AB (always branch)If an unconditional branch instruction, this is an X.

DE (dummy entry)If a dummy entry, this is an X. A dummy entry is the instruction after aconditional branch instruction that is breakpointed to tell when thebranch falls through.

CT (condition true)A conditional branch instruction has branched.

CF (condition false)A conditional branch instruction has fallen through.

BV (conditional branch fall through)A conditional branch that has always fallen through and never branched.

B> (conditional branch branched)A conditional branch that has always branched and never fallen through.The breakpoint is not active. When the dummy entry following thisinstruction is executed, this breakpoint is updated as fallen through.

AC (active)The breakpoint is active.


ATGRESETThe ATGRESET command, issued from the panel shown in Figure 84, resets allstatistics in the current monitor session to zero.

Z [---------------------- Monitor: Reset All Data in Monitor ---------------------

Option ===>_

To reset data to zero, complete the menu below and press ENTER:


PA Number. . . . . . . ALL

\ ]

Figure 84. Monitor: Reset All Data in Monitor panel

The monitor resumes updating statistics immediately.


EX 'hi_lev_qual.SATGEXEC(ATGRESET)' 'parameters'



where:

session_id The session ID for which to reset statistics. The default is theTSO user ID.





ATGRIDADThe ATGRIDAD command, issued from the panel shown in Figure 85, allows youto add a unique test case ID.

Z [------------------------------- Monitor: Add ID -------------------------------

Option ===>_

To assign a test case ID, complete the menu below and press ENTER:

Test Case ID . . . . .


\ ]

Figure 85. Monitor: Add ID panel

The test case ID is printed in the Summary report.


EX 'hi_lev_qual.SATGEXEC(ATGRIDAD)' 'parameters'


─ ──┬ ┬───────── ──┬ ┬───────────────────────────────────────────── ──────── � ├ ┤─test_id─ └ ┘ ─,─ ──┬ ┬──────────── ──┬ ┬────────────────────── └ ┘─L─────── └ ┘─session_id─ └ ┘ ─,──common_parameters─

where:

test_id Assigned test ID. The default is a time stamp comprised of thedate and time the command was invoked. The test case ID isprinted in the Summary report.

session_id The ID of the session for which the test case ID is to be set. Thedefault is the TSO user ID.



Z [ -------------------------------------------------------------------------------




The TEST ID has been set to 05/14/9713:38:38


\ ]

Figure 86. Add ID status panel


ATGRVADSThe ATGRVADS command, issued from the panel shown in Figure 87, allows youto display various information on variables being monitored.

Z [----------------------- Monitor: Display Variable Status ---------------------

Command ===>

To display the variable status for a session, complete the menu below and

press ENTER:


\ ]

Figure 87. Monitor: Display Variable Status panel


EX 'hi_lev_qual.SATGEXEC(ATGRVADS)' 'parameters'


─ ──┬ ┬──────────── ──┬ ┬────────────────────── ──────────────────────────── � └ ┘─session_id─ └ ┘ ─,──common_parameters─

where:

session_id The session for which variable status is to be displayed. Thedefault is the TSO user ID.


Example 1:

To display variable information, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGRVADS)'

Example 2:

To display variable information for session YOUNG, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGRVADS)' 'YOUNG'

An information panel, such as that shown in Figure 88 on page 251, is displayed.


Z [ -------------------------------------------------------------------------------




DBGI LNTH TIMES MAX BLOC BOFF EX TOT EX CNT FI PL

--------------------------------------------------------------------------------

0000 0007 000001 999999 01280009 0070 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0000 000000 000000 N N

0000 0007 000001 999999 01280009 0070 000000 000000 N N

0000 0008 000001 999999 01280009 0000 000000 000000 N N

0000 0002 000001 999999 01280009 0002 000000 000000 N N

0000 0004 000001 999999 01280009 0010 000000 000000 N N

0000 0004 000001 999999 01280009 0010 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0002 000001 999999 01280009 0018 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0008 000001 999999 01280009 0020 000000 000000 N N

0000 0007 000001 999999 01280009 0070 000000 000000 N N

0000 0003 000100 000005 01280009 0074 000000 000000 N N


\ ]

Figure 88. Variable information panel

For each variable, the following fields are displayed:

DBGI Index of DBGTAB section this variable read came fromLNGTH Length of variableTIMES Times to read variable (1 means to read every time)MAX Maximum times to read variableBLOC Base offset and register that points to working storageBOFF Offset of variable in working storageEX TOT Total times variable readEX CNT Number of times BP executed since last variable readFI File readPL DA read for PL/I program


ATGSESSNThe ATGSESSN command displays a list of the current active sessions. Figure 89shows a typical display in response to selecting option 3 (Display all active

sessions) on the Control the CA/DA/UTA Monitor panel.

Z [ BROWSE YOUNG.MSGS.FILE Line 00000000 Col 001 080

Command ===> Scroll ===> PAGE


Session name = YOUNG in use.


\ ]

Figure 89. Active session display panel

Use this command to identify session names or currently active users who need tostop or cancel their sessions before the monitor is terminated.


EX 'hi_lev_qual.SATGEXEC(ATGSESSN)' 'parameters'


─ ──┬ ┬───────────────────────────────────── ───────────────────────────── � └ ┘ ──┬ ┬─────── ──┬ ┬────────────────────── ├ ┤─level─ └ ┘ ─␣──common_parameters─ └ ┘─L─────

where:

level Requests that the current release of the ATC monitor is to be dis-played. Otherwise, all active sessions will be displayed.



The ATGSESSN command with the level parameter displays the release level andtable address data used by ATC support. For example:

Z [ -------------------------------------------------------------------------------




| Monitor Release: V2R1M3 Date: 2000.334

MAST: 00F9B270 PSA: 00FB4000 CPU: 00FB4000 SEST: 00F9BCE8 UNID: 0000001E

SESSION ID: YOUNG PA: 01AF07D0 BP: 01AB1C38 VA: 00000000


\ ]

Figure 90. Release level and table address data


ATGSLISTThe ATGSLIST command, issued from the panel shown in Figure 91, allows you toselect listings for which you want to display statistics.

Z [-------------------------- Monitor: Display Listings -------------------------

Command ===>

To display the listings for a session, complete the menu below and press

ENTER:


Starting List number . 1

Ending List number . . 9999

\ ]

Figure 91. Monitor: Display Listings panel


EX 'hi_lev_qual.SATGEXEC(ATGSLIST)' 'parameters'


─ ──┬ ┬───────────────────────────────────────────────────────────────────── ──────────────── � │ │┌ ┐─1────────── ┌ ┐─9999───── └ ┘ ─session_id──␣─ ──┴ ┴─start_list─ ─␣─ ──┴ ┴─end_list─ ─␣─ ──┬ ┬────────────── └ ┘─common_parms─

where:

session_id The session for which statistics are to be displayed. The default isthe TSO user ID.


start_list The first listing number to be displayed.

end_list The last listing number to be displayed.

common_parmsAny of the common parameters described in Appendix F, “Param-eters Common To Multiple Routines” on page 381 (separated byblanks).

Example 1:

To display statistics on all listings, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSLIST)'

Example 2:

To display statistics for session YOUNG starting with listing 2, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSLIST)' 'YOUNG 2'


Example 3:

To display statistics for session YOUNG starting for listings 2 to 4, enter thiscommand:

EX 'hi_lev_qual.SATGEXEC(ATGSLIST)' 'YOUNG 2 4'

A statistics panel, such as that shown in Figure 92 is displayed.

Z [ -------------------------------------------------------------------------------





--------------------------------------------------------------------------------


002 YOUNG.SAMPLE.COBOLST(COB01B) 99.204 07:08.56 00003 000021 00000

003 YOUNG.SAMPLE.COBOLST(COB01C) 99.204 07:08.59 00004 000032 00000

004 YOUNG.SAMPLE.COBOLST(COB01D) 99.204 07:09.01 00003 000013 00000


\ ]

Figure 92. Listings statistics panel

For each listing, the following fields are displayed:

Num Sequential listing numberListing Listing data set nameDate Date of compileTime Time of compilePAs Number of PAs in listingBPs Number of BPs in listingVAs Number of variable reads in listing


ATGSNAPThe ATGSNAP command, issued from the panel shown in Figure 93, writes thecurrent statistics (BRKOUT) to disk.

Z [------------------------ Monitor: Take Snapshot of Data ----------------------

Command ===>

Override Default File and Session Info

Specify a test case id NO (Yes|No)


\ ]

Figure 93. Monitor: Take Snapshot of Data panel 1

When you press Enter on this panel, the monitor displays the panel shown inFigure 94, allowing you to enter additional parameters.

Z [------------------------ Monitor: Take Snapshot of Data ----------------------

Command ===>

Complete information to be overridden and press ENTER to write stats:

Specify a test case id . . . . NO (Yes|No)

Test case id. . . . .

Override default session id . . NO (Yes|No)

Session id. . . . . .

\ ]

Figure 94. Monitor: Take Snapshot of Data panel 2

Statistics are not reset. This command allows you to take a snapshot of thecurrent coverage activity and run a report (for example, for each test case).


EX 'hi_lev_qual.SATGEXEC(ATGSNAP)' 'parameters'


─ ──┬ ┬───────── ─,─ ──┬ ┬──────────── ─,─ ──┬ ┬──────── ──────────────────────── ├ ┤─test_id─ └ ┘─session_id─ └ ┘─USE_DD─ └ ┘─L───────

─ ──(1)──┬ ┬────────────────────── ─────────────────────────────────────────── � └ ┘ ─,──common_parameters─

Note:1 Trailing commas may be omitted.

where:

test_id Assigned test ID. The test ID is used to build the BRKOUT filename. If you do not provide the test ID parameter (or it is speci-fied as an asterisk), the default time stamp (date and time) is used.The BRKOUT file name is created using the day of the year andthe number of seconds that have elapsed since the start of theday.


session_id Session ID for the snapshot. The default is the TSO user ID.

USE_DD Indicates that ATGSNAP is being called via Fast Path and that apre-allocated DD BRKOUT is provided for the output BRKOUT file.


Example 1

To allow the test ID to default to a time stamp and the BRKOUT name to be builtusing that same time stamp, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSNAP)'

Example 2

To add the test ID to the BRKOUT data and write the BRKOUT file touserid.TCASE1.BRKOUT, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSNAP)' 'TCASE1'


Z [ -------------------------------------------------------------------------------




The TEST ID has been set to 05/14/9713:38:59

The data has been written to 'YOUNG.M134.M49139.BRKOUT'


\ ]

Figure 95. Snapshot status panel


ATGSTATSThe ATGSTATS command, issued from the panel shown in Figure 96, allows youto select a session ID and PAs for which to display statistics.

Z [------------------------- Monitor: Display Statistics ------------------------

Command ===>

To display PA statistics, complete the menu below and press ENTER:


List number . . . . . 1

Starting PA number . . 1

Ending PA number . . . 9999

\ ]

Figure 96. Monitor: Display Statistics panel


EX 'hi_lev_qual.SATGEXEC(ATGSTATS)' 'parameters'


─ ──┬ ┬──────────────────────────────────────────── ────────────────────── � └ ┘ ─session_id─ ──┬ ┬──────────────────────────── │ │┌ ┐─1──── └ ┘─␣─ ──┴ ┴─list─ ─┤ MoreParms ├─

MoreParms:├─ ──┬ ┬────────────────────────────────────────────────────────────── ──────┤ │ │┌ ┐─1──────── └ ┘ ─␣─ ──┴ ┴─start_PA─ ──┬ ┬───────────────────────────────────────── │ │┌ ┐─9999─── └ ┘ ─␣─ ──┴ ┴─end_PA─ ──┬ ┬────────────────────── └ ┘ ─␣──common_parameters─

where:

session_id The session ID for which statistics are to be displayed. Thedefault is the TSO user ID.


list The listing number to display.

start_PA The first PA number to be displayed in this listing. The start_PAnumber is 1 origined for the specified listing.

end_PA The last PA number to be displayed. The end_PA number is 1origined for the specified listing.



Example 1:

To display statistics on all PAs, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSTATS)'

Example 2:

To display statistics for session YOUNG for LIST 1 starting with PA 1, enter thiscommand:

EX 'hi_lev_qual.SATGEXEC(ATGSTATS) 'YOUNG 1 1'

Example 3:

To display statistics for LIST 1 on PAs 2 through 4 of session YOUNG, enter thiscommand:

EX 'hi_lev_qual.SATGEXEC(ATGSTATS) 'YOUNG 1 2 4'

A statistics panel, such as that shown in Figure 97, is displayed.

Z [ -------------------------------------------------------------------------------





--------------------------------------------------------------------------------


PA ADR BPS EVNTS ACTVE

--------------------------------------------------------------------------------

00001 00000000 000006 0000000000 000006

00002 00000000 000015 0000000000 000015

00003 00000000 000001 0000000000 000001

00004 00000000 000005 0000000000 000005

00005 00000000 000004 0000000000 000004

--------------------------------------------------------------------------------

TOTAL 00000000 000031 0000000000 000031


\ ]

Figure 97. PA statistics panel

For each PA, the following fields are displayed:

NumSequential listing number.

ListingListing data set name.

DateDate of compile.

TimeTime of compile.

PAsNumber of PAs in listing.

BPsNumber of BPs in listing.

VAsNumber of variable reads in listing.


PASequential PA number of PAs in listing.

ADRWhen PA has executed, the storage address of the PA.

BPSNumber of BPs in PA.

EVNTS (events)Number of BPs that have executed in the PA.

ACTVE (active)Number of BPs still in storage in the PA.

ATGSTOPThe ATGSTOP command, issued from the panel shown in Figure 98, writes currentstatistics to disk, removes all remaining breakpoints for all PAs and terminates themonitor session.

Z [---------------------------- Monitor: Stop Monitor ---------------------------

Command ===>

Stop Monitor Normally:


Override breakout dsn NO (Yes|No)

\ ]

Figure 98. Monitor: Stop Monitor panel 1

When you press Enter for this panel, the monitor displays the panel shown inFigure 99, allowing you to enter additional parameters.

Z [---------------------------- Monitor: Stop Monitor ---------------------------

Command ===>

Press ENTER to Stop Monitor Normally:


Session id . . . . .

Override breakout dsn NO (Yes|No)

Breakout Dsn . . . .

\ ]

Figure 99. Monitor: Stop Monitor panel 2

The statistics (BRKOUT file) are written to the BRKOUT data set name as suppliedin the JCL that started the monitor session. You can supply a different data setname with the ATGSTOP command. The variable data for UTA and DA is writtento the VARTAB file as supplied in the JCL that started the monitor session.



EX 'hi_lev_qual.SATGEXEC(ATGSTOP)' 'parameters'


─ ──┬ ┬───────────────────────────────────────────────────────── ───────── � └ ┘ ──┬ ┬──────────── ─␣─ ──┬ ┬─brkout─ ──┬ ┬────────────────────── └ ┘─session_id─ └ ┘─L────── └ ┘ ─␣──common_parameters─

where:

session_id The session ID to stop.


brkout Name of the breakout table data set. If this parameter is not spec-ified or is specified as an asterisk, an exec namedprefix.sessionid.EXTEMP.EXEC, which is built when the monitorsession is started, is executed to allocate the BRKOUT andVARTAB files based on the data set names used when themonitor JCL was created. Otherwise, the statistics are written tothe BRKOUT file you specify.


Warning: ATGSTOP does not currently support the BRKOUT parameters ifthe monitor session has DA or UTA enabled.

Example 1

To write data to the default files and set the BRKOUT session ID to the defaultvalue of the TSO user ID, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSTOP)'

Example 2

To write data from MySessId to proj_qual.TEST1.BRKOUT, enter this command:

EX 'hi_lev_qual.SATGEXEC(ATGSTOP)' 'MySessID TEST1.BRKOUT'

When the stop command completes, a status panel, such as that shown inFigure 100, is displayed.

Z [ -------------------------------------------------------------------------------


Command ===>_ Scroll ===> CSR


Monitor session YOUNG stopped - session data written to disk


\ ]

Figure 100. Stop completed panel


Chapter 25. Diagnosing monitor problems

This chapter describes how to solve the following problems:

� 047 abend when trying to start a monitor session� 7C3 abend on user program during test case run� 0C4 abend on user program during test case run� 0F8 abend on user program during test case run� Fnn abend on user program during test case run� Insufficient SQA or ECSA space� Poor performance when measuring conditional branch coverage

System abend 047If this abend occurs when submitting the monitor JCL or when using the monitorinterface commands, the command handler program was not in an authorized dataset. To identify the ATC program that must meet this requirement, see “Setting upthe authorized data sets” on page 12.

System abend 7C3 on user programIf an instrumented user program is executed and a session has not been started tohandle it, or the session is started with a BRKTAB file that does not match theexecutable program, the user program is abended when the monitor cannot identifythe user SVC installed as the breakpoint. When this occurs, the program termi-nates with a system abend 7C3, reason code 1. The monitor may not recognizethe user SVC as a breakpoint if:

� The listing used during Setup does not match the code in the module undertest.

� The program has changed, but the Setup step has not been re-executed.

� You have not relinked your program with the modified object modules afterrunning the Setup step.

� A monitor session that matches the code in the module under test is notrunning.

� You have not stopped and restarted the monitor session after the Setup stephas completed.

If you are monitoring a COBOL program for which Setup was run using theEXTPROGRAM-ID option, also see “Instrumenting load modules without listings” onpage 220.

Other reason codes you may receive for the 7C3 abend are:

2 ATC control block error. Reinstall the ATC monitor SVCs.40

3 ATC control block error. Reinstall the ATC monitor SVCs.40

40 For information on reinstalling the ATC monitor SVCs, see “Installing and enabling the monitor SVCs” on page 14.

Chapter 25. Diagnosing monitor problems 261

4 Cannot get dynamic storage for user. Rerun your program being tested.If this error persists, reinstall the ATC monitor SVCs.40

5 Cannot get dynamic storage for user. Rerun your program being tested.If this error persists, reinstall the ATC monitor SVCs.40

6 Cannot get lock to update coverage data. Rerun your program beingtested. If the error persists, stop all monitor sessions, then start themagain.

Protection exception 0C4 (reason code 4) on user programWhen a breakpoint in an instrumented programs is hit, it is replaced with the realinstruction and the program continues. This replacement is done using the userstorage key, therefore the user program must not be in read-only storage. If anupdate is attempted to read-only storage, the user program terminates with an 0C4system abend (in CICS, this will be an 0C4/AKEA abend, which will be reflected toyou as an ASRA transaction abend). For more information, see “Restrictions ontypes of programs that can be monitored” on page 236.

System abend 0F8 on user programA type 3 user SVC is used for a breakpoint. There are some system modes thatcannot be in effect when this type of SVC is issued. Typically these would only beused in assembler code. If a breakpoint is hit when one of these system modes isin effect, an 0F8 system abend occurs.

For details on which system modes can lead to this abend, see the reason code listfor an 0F8 system abend code in the MVS/ESA System Codes or OS/390 MVSSystem Codes manuals (except for reason code 18, AR mode, which is not arestriction with the ATC breakpoint SVCs).

System abend Fnn on user programIf the monitor is not installed and an instrumented program is executed, the userprogram terminates with a system abend code of Fnn, where nn is the SVCnumber used as the breakpoint.

Lack of SQA or ECSA spaceThe monitor is loaded in SQA and ECSA storage and allocates ECSA storage forthe tables. For storage requirements, see “Monitor ECSA and SQA usage” onpage 360. If you encounter ECSA storage limitations, contact your systems pro-grammer to see if ECSA storage can be increased.

Because of ECSA storage fragmentation, there may be sufficient free storage avail-able, but not in a segment of sufficient size to load the tables. When a request forECSA storage is made to the operating system, it fails if there is no free segmentlarge enough to honor the request.


Poor performance when measuring conditional branch coverageMeasuring coverage when a conditional branch branches takes more overhead (thebreakpoint at the conditional branch must be left in storage). If the increased over-head is unacceptable for your testing, you can turn off conditional branch coverage.For instructions on turning off conditional branch coverage, see “Using the Perform-ance Mode to reduce monitor overhead” on page 235.

Chapter 25. Diagnosing monitor problems 263


Part 7. Using Source Audit Assistant

Part 7. Using Source Audit Assistant 265




� What is Source Audit Assistant?

� What does SAA require?

� How does SAA work?

What is Source Audit Assistant?SAA is a set of utilities for use in conjunction with SuperC to aid in the analysis ofchanges to your code base.

The Source Extraction tool extracts source code from compiler listings. This allowsyou to run your SuperC comparisons on the source as seen by the compiler afterany preprocessor has run, complete with copybooks and/or includes in place.

The Comparison Analysis tool analyzes a SuperC comparison report and generatesa prototype CA Targeted Summary control file for use in Targeted Summary basedon variables found in mismatched lines, and generates a Change Validation reportwhich lists seed variables not found in any changed lines and changed lines whichdid not contain any seed variables.

What does SAA require?SAA supports the following languages for seed analysis and template control filegeneration:

� COBOL � PL/I

Note: SAA does not support redefined character operators for PL/I (that is, use ofthe NOT or OR compiler options is not supported). The supported NOT symbol isX'5F'; the supported OR symbol is X'4F'.

Source Audit Assistant supports the following compiler and assembler listings forthe listing extractor:








� IBM PL/I for MVS & VM 1.1.1 (5688-235)

Chapter 26. Introduction to SAA 267




� High Level Assembler (HLASM) Version 1 Releases 1, 2 and 3 (5696-234)

� High Assembler H (HASM) Version 2 (5668-962)

You specify these listing types by entering PL/I, COBOL, or ASM in the ProgrammingLanguage field on the Extract Source Code from Listings panel. When you gen-erate this listing, specify the appropriate language processor option to produce alisting of the source code. For the DCB requirements of each listing type, see“Compiler options” on page 211.

Note: Any preprocessor source will be ignored in a PL/I listing.

SAA Comparison Analysis runs against the output of the ISPF SuperC function.(SuperC is typically options 3.12 and 3.13 from the main ISPF panel.) The SuperCcomparison must be done as a Line compare, generating a listing showing insertedand deleted lines (listing type Delta , CHNG, or Long ).

The following SuperC options cannot be used with SAA Comparison Analysis:

SuperC option Listing type

OVSUM Overall summary only.

Nolist No listing

SuperC option Input process control options

CKPACKL Check and unpack data before comparing data sets ormembers.

SuperC option Output process control options

DLMDUP Do not list matched old DS lines in side-by-side listing.

NOSUMS Exclude listing summary sections.

SuperC option Listing control options

| NARROW Up to 55 columns side-by-side (line length=132/133)

GWCBL Generate LINE Change Bar Listing

NOPRTCC No print control column and page separators

Note: If the FMVLNS (Flag moved lines) option is used, moved lines will not beexamined or appear in the Change Validation report.


How does SAA work?If you choose to compare compiler listing files, you can use SAA to extract thesource code from the listings prior to performing the comparison. This provides acopy of the source which contains any include files or copybooks, as well as outputfrom any preprocessor. This allows you to compare all of the source which makesup a compile unit at once rather than a piece at a time.

After generating a SuperC comparison report of your baseline and changed source,you can run the SAA Comparison Analysis. The Comparison Analysis generates aprototype CA Targeted Summary control file and a Change Validation report. Theprototype CA Targeted Summary control file can be used with few or no changesas input to CA Targeted Summary. CA Targeted Summary can then produce aSummary report on coverage of all statements containing variables found onchanged lines. The Change Validation report is based on matching the changesfound in the comparison report against a list of variables, the seed list, which areexpected to be involved in any changes. The Change Validation report identifies:

� All specified seed variables that did not appear in any new line in the SuperCcomparison report

� All lines in the comparison report that did not contain at least one of the speci-fied variables

Chapter 26. Introduction to SAA 269


Chapter 27. Source Audit Assistant samples

This chapter describes the sample delivered with SAA and how to verify your instal-lation.

The sample demonstrates running the SAA Comparison Analysis against a SuperCcomparison of the same member (new and old code) in two partitioned data sets,and a simple seed list, to produce a Targeted Summary control file and a ChangeValidation report.

To run the sample, complete the following steps to run the SAA ComparisonAnalysis:

1. Create and populate the sample SAA data sets under your TSO user ID prefixas described in Chapter 4, “ATC samples” on page 27.

2. Run SuperC (ISPF 3.13) as shown in Figure 101 using the two sample sourcedata sets that you set up in step 1.

Z [Menu Utilities Options Help

------------------------------------------------------------------------------

SuperCE Utility

Command ===>

New DS Name . . . 'YOUNG.SAMPLE.NEW.COBOL'

Old DS Name . . . 'YOUNG.SAMPLE.OLD.COBOL'

PDS Member List L (blank/pattern - member list, L - compare all)

(Leave New/Old DSN "blank" for concatenated-uncataloged-password panel)

Compare Type Listing Type Display Output

2 1. File 2 1. OVSUM 3 1. Yes

2. Line 2. Delta 2. No

3. Word 3. CHNG 3. Cond

4. Byte 4. Long 4. UPD

5. Nolist

Listing DSN . . . . SUPERC.LIST

Process Options . .

Statements Dsn . . .

Update DSN . . . . .

Execution Mode . . . 1 1. Foreground Output Mode . . 1 1. View

2. Batch 2. Browse

\ ]

Figure 101. SuperC panel

3. Start ATC and select option 2 on the Source Audit Assistant panel. The CreatePrototype Targeted Summary Data set & Validate Changes panel is displayed,as shown in Figure 102 on page 272.

Chapter 27. Source Audit Assistant samples 271

Z [ ---------- Create Prototype Target Control Dataset & Validate Changes ----------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL

4 Foreground Run the SAA Comparison Analysis in the foreground


Input Data Sets:

Compare Dataset Dsn. . SUPERC.LIST

Seed List Dsn . . . . SAMPLE.SEEDLIST(COB01)

Programming Language: COBOL (COBOL or PL/I)

Margins: (PL/I only)

Left Margin: Right Margin:

DBCS Support Enable: N (Y or N)

Target Listing Dsn . .


Output Data Sets:

Target Control Dsn . . 'YOUNG.SAMPLE.TARGCTL(COB01)'

Chg Validation Rpt Dsn 'YOUNG.SAMPLLE.COB01.CHNGREP'


JCL Dsn. . . . . . . 'YOUNG.SAMPLE.JCL(ACOB01)'

\ ]

Figure 102. Create Prototype Target Control Dataset & Validate Changes panel

4. Complete the Create Prototype Targeted Summary Data set & ValidateChanges panel as follows:

a. Enter SUPERC.LIST in the Compare Dataset Dsn field.

b. Enter the name of the seed list data set that you set up in step 1 onpage 271 in the Seed List Dsn field.

c. Enter COBOL in the Programming Language field.

d. Leave the Left Margin and Right Margin fields blank.

e. Enter N in the DBCS Support Enable field.

f. Leave the Target Listing Dsn field blank.

g. Enter Yes in the Use Program Name for File Name field.

h. Enter COB01 in the Program Name field.

5. Select option 4 to run the Comparison Analysis as an ISPF foreground job.

After the SAA Change Validation report is generated, a session in which youcan view the report is displayed. An example of the report is shown inFigure 103 on page 273.


-------------------------------------------------------------------------------

BROWSE YOUNG.SAMPLE.COB01.CHNGREP Line 00000000 Col 001 080



- - - - - - - - - - - - SAA Change Validation Report - - - - - - - - - - -

Date:07/23/1999 Time:07:26:35

Comparison Dataset: SUPERC.LIST

Comparison Created: 1999/07/23 7:22

New Source Dataset: 'YOUNG.SAMPLE.NEW.COBOL(COB01A)'

Old Source Dataset: 'YOUNG.SAMPLE.OLD.COBOL(COB01A)'

- - - - - - - - Input Seeds Not Found In Any Changed Lines - - - - - - - -

TBPARM2 NOT-THERE

- - - - - - - - - New Lines Containing No Seed References - - - - - - - -

Line Contents


Date:07/23/1999 Time:07:26:35



New Source Dataset: 'YOUNG.SAMPLE.NEW.COBOL(COB01B)'

Old Source Dataset: 'YOUNG.SAMPLE.OLD.COBOL(COB01B)'


TAPARM1 NOT-THERE


Line Contents


Figure 103. Sample SAA Change Validation report. This report was generated with a seed list data set consisting ofTAPARM1 TBPARM2 NOT-THERE.

6. When you are finished viewing the report, press the End key (PF3) to return tothe Create Prototype Target Control Dataset & Validate Changes panel.

7. Exit the ATC application.

8. Use the ISPF Browse function to view the Target Control Dsn member COB01created by following these steps. Figure 104 shows an example of a TargetedSummary control file.

-------------------------------------------------------------------------------

BROWSE YOUNG.SAMPLE.TARGCTL(COB01) Line 00000000 Col 001 080



Defaults LoadMod=L,ToObjDsn=T,FromObjDsn=F

COBOL ObjMember=m,ListDsn=YOUNG.SAMPLE.NEW.LISTING(COB01A)

Scope ExtProgram-Id=L

TargetVar Name=(LOOP1 In L)

TargetVar Name=(TAPARM1 In L)

COBOL ObjMember=m,ListDsn=YOUNG.SAMPLE.NEW.LISTING(COB01B)

Scope ExtProgram-Id=L

TargetVar Name=(TBPARM2 In L)


Figure 104. Sample SAA Targeted Summary control file

Chapter 27. Source Audit Assistant samples 273


Chapter 28. Starting Source Audit Assistant

You start SAA by selecting option 2 from the ATC Primary Option Menu. From theSource Audit Assistant panel, shown in Figure 105, you can select option 1 toextract source code from listings, or option 2 to create a prototype CA TargetedSummary control file and a Change Validation report based on the changes found.

Z [ ---------------------------- Source Audit Assistant ---------------------------

Option ===>

1 Extraction Extract Source Code from Listings

2 Analysis Create Prototype Target Control Dataset & Validate Changes


\ ]

Figure 105. Source Audit Assistant panel

Executing the SAA source extractorWhen you select option 1 on the Source Audit Assistant panel, the Extract SourceCode from Listings panel, shown in Figure 106, is displayed.

Z [ ---------------------- Extract Source Code from Listings -----------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL

4 Foreground Run the SAA Source Extractor in the foreground


New Datasets:

New Listing Dsn: . . 'YOUNG.SAMPLE.NEW.COBOLST(L)'

New Source Dsn:. . . 'YOUNG.SAMPLE.NEW.COBOL(L)'

Old Datasets:

Old Listing Dsn: . . 'YOUNG.SAMPLE.OLD.COBOLST(L)'

Old Source Dsn:. . . 'YOUNG.SAMPLE.OLD.COBOL(L)'

Programming Language: COBOL (ASM,COBOL,or PL/I)


Left Margin: Right Margin: MarginI: (Yes|No)



JCL Dsn: . . . . . . 'YOUNG.SAMPLE.JCL(BCOB01)'

\ ]

Figure 106. Extract Source Code from Listings panel

Chapter 28. Starting Source Audit Assistant 275





ForegroundExtract source from the listings in the foreground.

New Listing DsnThe name of the data set that contains compiler listings for your modi-fied code. This can be a sequential data set or a partitioned data set(PDS). If it is a PDS and an asterisk is used in place of a membername, all members will be processed. The Target Listing Dsn field onthe SAA Comparison Analysis panel will also use this Dsn.

New Source DsnThe name of the data set into which the extracted source code is to bewritten. This can be a sequential data set or a PDS. If the New ListingDsn is a PDS with all members to be processed, this must be a PDS;any member name given is ignored.

Old Listing Dsn - (optional)The name of the data set that contains compiler listings for your originalcode base. The rules from New Listing Dsn apply. If the Old ListingDsn field is blank, the Old Source Dsn is ignored.

Old Source Dsn - (optional)The name of the data set into which the extracted source code is to bewritten. The rules from New Source Dsn apply.

Programming LanguageEnter the programming language of your listing file. The followingvalues are accepted:

� ASM � COBOL � PL/I

Left MarginLeft source margin (for PL/I only ). For COBOL column 2 is alwaysused. For PL/I this value should be the first value of the MARGINScompiler option (which defaults to 2 for fixed-length records and 10 forvariable-length and undefined-length records).

Right MarginRight source margin (for PL/I only ). For COBOL column 72 is alwaysused. For PL/I this value should be the second value of the MARGINScompiler option (which defaults to 72 for fixed-length records and 100 forvariable-length and undefined-length records).

MarginIindicates whether the MARGINI compier option is in effect. (Used forPL/I only but ignored for VisualAge PL/I Version 2 Release 2.).


Yes Indicates that MARGINI is in effect.No Indicates that NOMARGINI is in effect.


When you press Enter, the file names on the panel change automat-ically. Using the program name to construct the data set names is thenormal procedure for the ATC tools.

Program NameName to use for SAA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.








This can be any valid name.

JCL Library and MemberSpecifies the name of the JCL library data set and member to hold thegenerated JCL.

Executing the SAA Comparison Analysis toolWhen you select option 2 on the Source Audit Assistant panel, the Create Proto-type Targeted Summary Data set & Validate Changes panel, shown in Figure 107on page 278, is displayed. This panel allows you to invoke the SAA comparisonanalysis, which uses a compare file generated by SuperC and a list of seed vari-ables that you are interested in monitoring to generate:

1. A prototype CA Targeted Summary control file, which can be used with few orno changes as input to CA Targeted Summary report. CA Targeted Summaryreport can then produce a Summary report on all statements containing vari-ables found in the New Source Dsn's changed lines.

2. A Change Validation report, which shows changed lines that did not containany seed variables and seed variables that did not appear in any changedlines. The Change Validation report allows you to ensure that:

� Only planned changes to your source code were made.� All seed variables were changed.

This report is optional and will be produced only if a seed list data set name isspecified.

Upon completion, the Change Validation report data set is displayed for viewing ifyou chose to create one.


Z [ ---------- Create Prototype Target Control Dataset & Validate Changes ----------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL

4 Foreground Run the SAA Comparison Analysis in the foreground


Input Data Sets:

Compare Dataset Dsn. . 'YOUNG.SUPERC.LIST'

Seed List Dsn . . . . 'YOUNG.SAMPLE.SEEDLIST(COB01)'

Programming Language: COBOL (COBOL or PL/I)


Left Margin: Right Margin:

DBCS Support Enable: N (Y or N)

Target Listing Dsn . . 'YOUNG.SAMPLE.COBOLST'


Output Data Sets:

Target Control Dsn . . 'YOUNG.SAMPLE.TARGCTL(COB01)'

Chg Validation Rpt Dsn 'YOUNG.SAMPLLE.COB01.CHNGREP'


JCL Dsn. . . . . . . 'YOUNG.SAMPLE.JCL(ACOB01)'

\ ]

Figure 107. Create Prototype Targeted Summary Dataset & Validate Changes panel





ForegroundExecute the SAA analysis in the foreground.

Compare Dataset DsnThe output of a SuperC comparison of source data sets.

Seed List DsnName of a data set containing a list of those variables that were to bechanged and that you may be interested in monitoring if you run Tar-geted Summary report.

If no Seed List Dsn is specified, the Change Validation report is not gen-erated.


Programming LanguageEnter the programming language of your comparison file.

The following values are accepted:

� COBOL � PL/I

Left MarginLeft source margin (for PL/I only ). For COBOL column 2 is alwaysused. For PL/I this value should be the first value of the MARGINScompiler option (which defaults to 2 for fixed-length records and 10 forvariable-length and undefined-length records).

Right MarginRight source margin (for PL/I only ). For COBOL column 72 is alwaysused. For PL/I this value should be the second value of the MARGINScompiler option (which defaults to 72 for fixed-length records and 100 forvariable-length and undefined-length records).

DBCS SupportSelect whether DBCS support is enabled.

EnableEnter N if the source code does not contain DBCS characters. Enter Y ifit does.

DBCS support for the control file statements is described in Appendix C,“DBCS support” on page 365.

Target Listing Dsn (optional)The data set name to use in the prototype Target Control data set asthe location of your listing data sets. If this is not given, the source dataset will be used with the low-level qualifier changed to LISTING. Thisfield is shared with the New Listing Dsn field of the Source Extractiontool.

Use Program Name for File NameIf you want to construct the data set names from the default high-levelqualifier, the specified program name, and the default low-level qualifierfor each data set, enter Yes.

When you press Enter, the file names on the panel change automat-ically. Using the program name to construct the data set names is thenormal procedure for the ATC tools.

Program NameName to use for SAA data sets if you enter YES in the Use ProgramName for File Name field. Note that this can be any valid name; itdoes not have to be the name of any of your programs.









This can be any valid name.

Target Control DsnA prototype Targeted Summary data set, which can be used with little orno modification as input to CA Targeted Summary report to target thosevariables found on new or changed lines in the new source. (TheCOBOL or PL/I control card may require modification to specify thecorrect listing data set unless the Target Listing Dsn value was speci-fied.)

Chg Validation Rpt DsnIf you do not specify a data set name in the Seed List Dsn field, thisfield is not used. A Change Validation report has two parts:

1. A list of seed variables that did not appear in any of the changedlines

2. A list of all the changed lines that did not contain any seed variables


For information about SAA Change Validation reports and about the contents ofinput and output files, see Chapter 29, “Source Audit Assistant Comparison Anal-ysis tool” on page 281 .


Chapter 29. Source Audit Assistant Comparison Analysistool

The SAA Comparison Analysis tool allows you to validate the changes found in theSuperC comparison report by matching variables found on changed lines againstyour seed list in order to make sure that:

1. Only planned changes were made.2. All seed variables were changed.

In order to create an SAA Change Validation report, you need a SuperC linecompare, which compares two COBOL or PL/I source files and a list of COBOL orPL/I variables (seeds) that you intended to change.41 The SAA Change Validationreport that is generated identifies:

1. All specified variables that did not appear in any new line in the SuperC com-parison report

2. All lines in the SuperC comparison report that did not contain at least one ofthe specified variables

In addition, a prototype CA Targeted Summary control file is generated, whichselects all variables referenced in all mismatched new file lines. This file can beused as an input file for CA Targeted Summary. However, first you may need tomodify the listing data set name to specify the correct listing data set name unlessyou provided it in the Target Listing Dsn field on the Create Prototype TargetedSummary Data set & Validate Changes panel.

SAA Comparison Analysis tool inputsIn order to create a prototype CA Targeted Summary control file and an SAAChange Validation report, you need a SuperC line comparison of two COBOL ortwo PL/I source or listing files. For information about SuperC processing optionsrequirements, see “What does SAA require?” on page 267.

In addition, a seed list file is required if you want to create a Change Validationreport. This contains a list of COBOL or PL/I variables (seeds) that you intended tochange. The seed list file is a sequential data set or a member of a partitioneddata set and can have any DCB attributes. The format of this file is a free-form listof COBOL or PL/I variable names subject to the following restrictions:

1. Variable names cannot be continued from one line to the next.

2. When more than one variable name appears on a line, the variable namesmust be separated by one or more blanks.

DBCS support for the seed list file entries is described in Appendix C, “DBCSsupport” on page 365.

41 “Change” in this context means that you want to change either the definition of the variable or references to the variable.

Chapter 29. Source Audit Assistant Comparison Analysis tool 281

SAA Comparison Analysis tool outputsTwo output data sets are created by the SAA Comparison Analysis:

1. A prototype CA Targeted Summary control file2. An SAA Change Validation report (optional)

The Targeted Summary data set contains a prototype Targeted Summary controlfile that can be used to create a CA Targeted Summary report for all variablesfound in mismatched new file records. However, before this data set can be usedas a CA Targeted Summary control file, you must ensure that the listing data setname is correct. If the Target Listing Dsn is specified on the panel or in the JCL, itis used for the listing data set name in the target control file. Otherwise, the SAAComparison Analysis creates the listing data set name by replacing the low-levelqualifier in the new file data set name with LISTING. If this is not correct, you mustmodify the line to specify the correct listing data set name. For more informationon Targeted Summary report, see “Targeted Summary reports” on page 89.

The SAA Change Validation report data set contains three sections. The firstsection simply identifies the old and new files used in the SuperC comparison, thedate and time of the run, and so on. The second section of the report, Input SeedsNot Found In Any Changed Lines, identifies all specified seed variables which werenot found in any new line in the SuperC comparison. The last section of the report,New Lines Containing No Seed References, identifies new lines in the SuperCcomparison that did not contain at least one of the specified variables.

Figure 108 on page 283 shows a sample SAA Change Validation report generatedusing a seed list data set consisting of:

TAPARM1 TBPARM2 NOT-THERE


-------------------------------------------------------------------------------

BROWSE YOUNG.SAMPLE.COB01.CHNGREP Line 00000000 Col 001 080




Date:07/23/1999 Time:07:26:35



New Source Dataset: 'YOUNG.SAMPLE.NEW.COBOL(COB01A)'

Old Source Dataset: 'YOUNG.SAMPLE.OLD.COBOL(COB01A)'


TBPARM2 NOT-THERE


Line Contents


Date:07/23/1999 Time:07:26:35



New Source Dataset: 'YOUNG.SAMPLE.NEW.COBOL(COB01B)'

Old Source Dataset: 'YOUNG.SAMPLE.OLD.COBOL(COB01B)'


TAPARM1 NOT-THERE


Line Contents


Figure 108. Sample SAA Change Validation report. This report was generated with a seed list data set consisting ofTAPARM1 TBPARM2 NOT-THERE.

Chapter 29. Source Audit Assistant Comparison Analysis tool 283


Part 8. Appendixes

Part 8. Appendixes 285


Appendix A. Problem determination

This appendix describes error messages that you may receive during ATC installa-tion and operation.

Appendix A. Problem determination 287

ATGO0003S � ATGO0008S

ATGO: CombineThe following messages may be issued while executing the Combine JCL:

ATGO0003S Combine: Error opening input file: dsn.

Explanation: Combine could not open the specified data set.

Action: Combine terminates.

User Response: Ensure that the data set exists and is available.

ATGO0004S Combine: Error opening output file: dsn.

Explanation: Combine could not open the specified data set.


User Response: Ensure that the data set is allocated and can be accessed.

ATGO0005S Combine: Insufficient storage to satisfy request.

Explanation: The CA combine program got an error code from the operating systemcommand used to request storage for the BRKOUT table. Thirty two bytes are needed foreach breakpoint (plus 96 byte per PA and 32 bytes per logical file number).


User Response: Check the region size on your job card for the step, and increase it. CAobtains job card information from the user defaults.

ATGO0006S Combine: Input file 1 is not a BRKOUT or BRKTAB file.

Explanation: Input file 1 is not a BRKOUT or BRKTAB file.


User Response: Ensure that input file 1 is a valid BRKOUT or BRKTAB file.

ATGO0007S Combine: Input file 2 is not a BRKOUT or BRKTAB file.

Explanation: Input file 2 is not a BRKOUT or BRKTAB file.


User Response: Ensure that input file 2 is a valid BRKOUT or BRKTAB file.

ATGO0008S Combine: Input files do not match. One is a BRKTAB and one is aBRKOUT.

Explanation: The input files are of a matching type (either both BRKTAB or bothBRKOUT).


User Response: Ensure that the file types (BRKOUT or BRKTAB) match.


ATGO0009S � ATGO0010S

ATGO0009S Combine: Invalid keyword or value keyword

Explanation: An invalid keyword or keyword operand was detected.


User Response: Correct the specified keyword or operand.

ATGO0010S Combine: Unsupported value specified in parameter parm

Explanation: An invalid value was specified for the indicated parameter.


User Response: Correct the specified value.


ATGR0001S � ATGR0005S

ATGR: ReportsThe following messages may be issued while executing the report JCL:

ATGR0001S Summary: Invalid invocation.

Explanation: The parameter passed to Summary is invalid.

Action: Summary terminates.

User Response: Refer to “Summary” on page 87 for a list of the valid parameters.

ATGR0002S Summary: EOF of BRKTAB before finding the testid test case

Explanation: The testid test case was not found in the BRKTAB file provided.


User Response: Make sure that the BRKTAB file in the BRKTAB DD statement of the JCLis the same one that was used when running the monitor session that created the BRKOUTfile in the BRKOUT DD statement. If you have run Setup to create a new BRKTAB file sincecreating the BRKOUT file, the BRKOUT and the BRKTAB files will not match.

ATGR0003S Summary: Invalid file name file_name cannot be opened

Explanation: The file file_name cannot be opened.


User Response: Ensure that the DDNAME file-name is specified in the JCL, that the file itpoints to exists, is available to the Report job, and that the job that created the file completedsuccessfully.

ATGR0004S Summary: Invalid BRKTAB file

Explanation: The BRKTAB file is not valid.


User Response: Make sure you are passing the correct BRKTAB file in the BRKTAB DDstatement of the JCL.

ATGR0005S Summary: Invalid BRKOUT file

Explanation: The BRKOUT file is not valid.


User Response: Make sure you are passing the correct BRKOUT file in the BRKOUT DDstatement of the JCL.



ATGR0006S Summary: Invalid DBGTAB file.

Explanation: The DBGTAB is not valid.

Action: Targeted Summary terminates.

User Response: Check that the data set name specified for the DBGTAB is correct andcontains a valid DBGTAB created by Setup from the listing of interest.

ATGR0007S Summary: No space for BRKTAB file

Explanation: The CA Summary program received an error code from the operating systemcommand used to request storage for the BRKTAB file. For storage requirements, seeAppendix B, “ATC requirements and resources” on page 359.


User Response: Increase the region size on your job card for this step. CA obtains jobcard information from the user defaults.

ATGR0008S Summary: No space for BP table or Bit map

Explanation: The CA Summary program received an error code from the operating systemcommand used to request storage for the BP table or Bit map.



ATGR0009S Summary: Error allocating DBGTAB character storage.

Explanation: The Summary program received an error code from the operating systemcommand used to request storage for the DBGTAB character table.


User Response: Increase the region size on your job card for this step. Job card informa-tion is obtained from the user defaults.

ATGR0010S Summary: Error allocating DBGTAB statement storage.

Explanation: The Summary program received an error code from the operating systemcommand used to request storage for the DBGTAB statement table.


User Response: Increase the region size on your job card for this step. Job card informa-tion is obtained from the user defaults.

ATGR0011S Report: Invalid invocation.

Explanation: One or more of the parameters passed to Report are invalid.

Action: Report terminates.

User Response: Refer to the User's Guide for a list of the valid parameters for Report.



ATGR0012S Report: Invalid file name file_name cannot be opened

Explanation: The file file_name cannot be opened.


User Response: Ensure that the DDNAME file-name is specified in the JCL, that the file itpoints to exists, is available to the Report job, and that the job that created the file completedsuccessfully.

ATGR0013S Report: Illegal listing input file

Explanation: Report detected something wrong with the assembler listing. Report expectsa standard Assembler H or High Level Assembler listing format.


User Response: Check that you are using a standard Assembler H or High Level Assem-bler listing. This may also be caused by having more than one compile unit in a BRKTAB orBRKOUT file that contains the same external CSECT name. This is not supported.

ATGR0014S Report: No procedures or entry name found in listing.

Explanation: The CA Report program did not find an entry name in the listing being proc-essed. For COBOL for MVS & VM and VS COBOL II, Report expects to find an entname DS

0H instruction in the assembler listing section of the listing, where entname is the name usedduring Setup to identify this PA. For OS/VS COBOL, the name of the first PROGRAM-ID isused (extracted from the title line). For PL/I, Report expects to find Procedure entname in theassembler listing section of the listing.


User Response: Verify that you are using the BRKOUT file of test case coverage resultswith the listings that go with it.

ATGR0015S Report: Invalid BRKTAB file

Explanation: The input BRKTAB file does not contain valid BRKTAB data.


User Response: Ensure that Setup has completed creating the BRKTAB file successfully.If it has, contact ATC support, else correct any errors that Setup issued and rerun the job.

ATGR0016S Report: Invalid BRKOUT file

Explanation: The input BRKOUT file does not contain valid BRKOUT data.


User Response: Ensure that ATGSTOP or ATGSNAP has been issued in order to createthe BRKOUT file. If it has, contact ATC support.


ATGR0017S � ATGR0021E

ATGR0017S Report: Entry name: ename not found in BRKTAB file

Explanation: The entry name of the listing being processed was not found in the BRKTABtable. For COBOL, the entry name is from the PROGRAM-ID paragraph. For PL/I, the entryname is the name of the external procedure.


User Response: Verify that the listing you are trying to process is one that has coveragedata in the BRKTAB file being used. You should be able to find the first CSECT name ofyour listing in the BRKOUT file.

ATGR0018S Report: Entry name: ename not found in BRKOUT file

Explanation: The entry name of the listing being processed was not found in the BRKOUTtable. For COBOL, the entry name is from the PROGRAM-ID paragraph. For PL/I, the entryname is the name of the external procedure.


User Response: Verify that the listing you are trying to process is one that has coveragedata in the BRKOUT file being used. You should be able to find the first CSECT name ofyour listing in the BRKOUT file.

ATGR0019S Report: No space for BRKTAB table

Explanation: The CA Report program received an error code from the operating systemcommand used to request storage for the BRKOUT table. For storage requirements, seeAppendix B, “ATC requirements and resources” on page 359.


User Response: Increase the region size on your job card for the Report step. CA obtainsjob card information from the user defaults.

ATGR0020S Report: No space for Bit map

Explanation: The CA Report program received an error code from the operating systemcommand used to request storage for the Bit map.



ATGR0021E Report: Miscompares of opcode in storage during execution.listing_name

Explanation: An opcode in the listing did not match that in the BRKTAB. The BRKTABand listing may be out of synch.

Action: The opcode is discarded and processing continues.

User Response: Ensure that the listing being annotated is the same one used to generatethe BRKTAB.



ATGR0022S Target: DDname cannot be allocated.

Explanation: The specified DDname could not be allocated.

Action: Processing terminates.

User Response: Contact your system programmer.

ATGR0023S Target: Error detected in Summary. RC = rc

Explanation: The Summary report routine returned RC = rc.


User Response: See the associated messages for more information.

ATGR0024W Target: Function messages issued. RC = rc

Explanation: The function routine has issued messages and returned RC = rc.

Action: See the associated messages.

User Response: See the associated messages for more information. This message isissued since the associated messages appear in a separate SYSOUT data set.

ATGR0025W Target: No statements targeted.

Explanation: There were no statements targeted.


User Response: Ensure that the control data set contains the appropriate TARGETVARand/or TARGETSTMT entries.

ATGR0026S Target: EXECIO write of dsn data set failed, RC = rc.

Explanation: A failure occurred while writing to the output data set dsn. rc contains thereturn code from the write.


User Response: Correct the error indicated by the return code and retry.

ATGR0027S Target: DD name dd1 found when DD dd2 was expected.

Explanation: The DD name dd1 was found when dd2 was expected.


User Response: Ensure that all required parameters were provided with the correct DDnames and in the correct order.


ATGR0028S � ATGR0034I

ATGR0028S Target: EXECIO read of dsn failed, RC= rc

Explanation: An error occurred while reading dsn. rc contains the return code fromEXECIO.

Action: Target file creation terminates.


| ATGR0030S Target: Invalid statement in control file:

Explanation: An invalid statement was discovered in the targeted coverage control file. Anaccompanying message indicates the invalid statement.


User Response: Correct the control statement and retry.

ATGR0031S Target: Procedure name is not a valid procedure name in the speci-fied report file

Explanation: The indicated procedure does not exist in the listing file.


User Response: Specify the proper procedure name or listing name.

ATGR0032S Target: * is not a valid listing name when a variable name is speci-fied

Explanation: You must specify a listing name if a variable name is specified.


User Response: Specify the name of the listing where the variable is located.

ATGR0033S Target: Invalid control statement:

Explanation: An invalid statement was discovered in the targeted coverage control file. Anaccompanying message indicates the load module, procedure, and so on containing theinvalid statement.


User Response: Correct the control statement and retry.

ATGR0034I Target: Reading Targeted Summary data set.

Explanation: The Targeted Summary data set is being read and processed.

Action: Processing continues.

User Response: None.


ATGR0035I � ATGR0041S

ATGR0035I Target: Processing listing dsn.

Explanation: The listing data set dsn is being read and processed.



ATGR0036I Target: Generating Targeted Summary report

Explanation: The Targeted Summary report is being generated.



ATGR0037S Target: DDname cannot be allocated. dsn may not exist.

Explanation: The specified dsn could not be allocated to DDname.


User Response: Ensure that the specified data set is accessible.

ATGR0038S Target: DDname cannot be allocated to dsn.

Explanation: The specified dsn could not be allocated to DDname.


User Response: Ensure that the specified data set is accessible.

ATGR0039S Variable Report: Missing Parameter(s)

Explanation: No parameter for the VARDATA output file was specified.

Action: Variable report terminates.

User Response: Verify that the VARDATA parameter in the report JCL exists.

ATGR0040S Variable Report: Variable Data List File Parameter is Invalid.

Explanation: The parameter for the VARDATA file is incorrect.

Action: Variable Report terminates.

User Response: Verify that the VARDATA parameter in the report JCL is valid. Refer tothe User’s Guide for a list of the valid parameters for the VARDATA Variable Report.

ATGR0041S Variable Report: Debug Table File Open Failure

Explanation: The input debug table file (DDNAME DBGTAB) could not be opened.


User Response: Verify that the name supplied in the Variable Report JCL for the DBGTABfile is valid and the file exists.



ATGR0042S Variable Report: Variable ID List File Open Failure

Explanation: The output variable ID list file (DDNAME VARID) could not be opened.


User Response: Verify that the name supplied in the report JCL for the VARID file is validand there are no JCL errors in its definition.

ATGR0043S Variable Report: Variable Table File Open Failure

Explanation: The input variable data file (DDNAME VARTAB) could not be opened.


User Response: Verify that the name supplied in the report JCL for the VARTAB file isvalid and the file exists.

ATGR0044S Variable Report: Variable Data List File Open Failure

Explanation: The output variable data list file (DDNAME VARDATA) could not be opened.


User Response: Verify that the name supplied in the report JCL for the VARDATA file isvalid and there are no JCL errors in its definition.

ATGR0045S Variable Report: Debug Table File is invalid

Explanation: The input debug table file is invalid (not a DBGTAB file or at the wrongrelease level).


User Response: Verify that the name supplied in the report JCL for the DBGTAB file isvalid and at the correct release level for the release you have installed (was not created byan earlier UTA release that is not compatible with this release). Valid DBGTAB files haveVAR03 as the first five characters of the file.

ATGR0046S Variable Report: Array Bounds for Reading DBGTAB Records HasBeen Exceeded.

Explanation: The number of DBGTAB records has exceeded the 10,000 array index limit.

Action: Variable Report Terminates.

User Response: Decrease the number of DBGTAB records per DBGTAB file to 10,000 orfewer or contact ATC support.



ATGR0047S Variable Report: Variable Table File is invalid

Explanation: The input variable data file is invalid (not a VARTAB file or at the wrongrelease level).


User Response: Verify that the name supplied in the report JCL for the VARTAB file isvalid and at the correct release level for the release you have installed (was not created byan earlier UTA release that is not compatible with this release). A valid VARTAB file hasVTAB7 as the first five characters of the file.

ATGR0048S ATGOVARD: Internal error 160.

Explanation: An internal error has caused a program failure.

Action: Output message and terminate.

User Response: Contact ATC support.

ATGR0049S ATGOVARD: Invalid internal control card.

Explanation: An invalid internal control card has caused a program failure, or you coded acontrol card for a tool for which you are not licensed.


User Response: Ensure that all parameters in the control file are specified correctly, orremove the control card that specifies the unlicensed function from your control cards.

ATGR0050S Variable Report: Failure in Allocating Storage for Debug TableHeader Section.

Explanation: The allocation of storage for the debug table header failed.


User Response: Check your system for storage allocation problems and check that theDBGTAB file is valid.

ATGR0051S Variable Report: Failure in Allocating Storage for Debug Table Char-acter Data Section

Explanation: The allocation of storage for the debug table character data failed.





ATGR0052S Variable Report: Failure in Allocating Storage for Debug Table State-ment Records Section

Explanation: The allocation of storage for the debug table statement records failed.



ATGR0053S Variable Report: Failure in Allocating Storage for Debug Table Vari-able Records Section

Explanation: The allocation of storage for the debug table variable records failed.



ATGR0054S Variable Report: Failure in Allocating Storage for Variable TableRecords Section

Explanation: The allocation of storage for the variable table records failed.


User Response: Check your system for storage allocation problems and check that theVARTAB file is valid.

ATGR0055E Variable Report: Buffer Overflow—A Loss of Data May HaveOccurred.

Explanation: Data was read from the input file faster than it could be written to theVARTAB file.

Action: Warning messages are generated at the beginning of VARDATA file and on lineswhere data was lost.

User Response: Scale down the amount of your variable data or contact ATC support.

ATGR0063E Report: Listing name dsn not found in BRKTAB file.

Explanation: The specified listing data set name was not found in the BRKTAB file.


User Response: Correct the dsn specification.

ATGR0064S Report: Listing name dsn not found in BRKOUT file.

Explanation: The specified listing data set name was not found in the BRKOUT file.


User Response: Correct the dsn specification.



ATGR0065S Report: Unsupported value specified in parameter keyword.

Explanation: The operand of the specified keyword contained an invalid value.


User Response: Correct the operand of the specified keyword.

ATGR0066S Summary: Unsupported value specified in parameter keyword.

Explanation: The operand of the specified keyword contained an invalid value.



ATGR0067S Variable Reports: Invalid keyword or value keyword

Explanation: The specified keyword or keyword operand is not recognized.


User Response: Correct the specified keyword or keyword operand.

ATGR0068S Variable Reports: Unsupported value specified in parameter keyword

Explanation: The operand of the specified keyword is invalid.




ATGS0001S � ATGS0004S

ATGS: SetupThe following messages may be issued while executing the Setup JCL:

ATGS0001S Setup: Load and Object datasets can not both be specified within aset of control cards.

Explanation: The object library control cards FROMOBJDSN and TOOBJDSN are mutuallyexclusive with the load library control cards FROMLOADDSN and TOLOADDSN within agiven control data set.

Action: Setup terminates.

User Response: Ensure that only object library control cards or only load library controlcards are used within a single control data set.

ATGS0002S Setup: If ExtProgram-ID (COBOL TEST option) is used for one lan-guage control card, it must be used on all language control cards.

Explanation: The ExtProgram-ID keyword, which indicates that the COBOL TEST option isto be used, cannot be mixed with non-TEST control cards within the same control file.


User Response: Use the COBOL TEST option for all programs in the control file, or splitthe control file into one for TEST only and one for NOTEST and run Setup for each inde-pendently.

ATGS0003S Setup: ExtProgram-ID (COBOL TEST option) can not be used ifeither DA or UTA is enabled.

Explanation: The ExtProgram-ID keyword indicates that the COBOL TEST option is to beused. This option is incompatible with DA and UTA.


User Response: In order to run DA or UTA, recompile without the TEST option and editthe control file to remove the ExtProgram-ID keyword.

ATGS0004S Setup: Illegal listing type in CA control file

Explanation: The Listing type value (first field) in the CACTL was neither B, P or A. Thischaracter is passed to Setup as parameter 1.


User Response: Correct the value. Rerun Setup.



ATGS0005S Setup: No BRKTAB written. Too few bpoints.

Explanation: No BRKTAB was written because Setup could not find assembler instructionsat which to insert breakpoints.


User Response: Check the input listing to Setup and verify that it is correct, including theassembler statements.

ATGS0006S Setup: Illegal assembler listing

Explanation: The assembler listing is not valid.


User Response: Check that the assembler listing passed to Setup is a valid Assembler Hor High Level Assembler listing.

ATGS0007S Setup: DBGTAB file not valid.

Explanation: The DBGTAB file does not contain valid data.


User Response: Ensure that a ATGOVARD step was run successfully to create theDBGTAB file. If it was, contact ATC support, else correct any errors that ATGOVARDissued and rerun the job.

ATGS0008S Setup: Error allocating storage for DBGTAB file statements.

Explanation: Setup could not acquire enough storage to process the DBGTAB file state-ments.


User Response: Specify a larger REGION size for the Setup job.

ATGS0009S Setup: Error allocating storage for DBGTAB file variables.

Explanation: Setup could not acquire enough storage to process the DBGTAB file vari-ables.



ATGS0010S Setup: Invalid statement read type - must be R/C/N.

Explanation: A DBGTAB record contains an invalid statement read type.





ATGS0011S Setup: Error allocating storage for DBGTAB character data.

Explanation: Setup could not acquire enough storage to process the DBGTAB characterdata.



ATGS0012S Setup: Cannot find requested listing in DBGTAB.

Explanation: No DBGTAB entry was found for the compiler listing being processed.



ATGS0013S Setup: Cannot find assembler line that reads TGT.

Explanation: For UTA and DA, Setup reads the assembler listing for the statement wherethe TGT register is loaded. This line was not found.


User Response: Verify that you have passed a correct listing to Setup, that includes theassembler listing. If so, contact ATC support.

ATGS0014S Setup: Undefined error: errnum

Explanation: An unexpected error occurred.


User Response: Contact ATC support with the value of errnum.

ATGS0015S Setup: Cannot find CSECT: csect_name

Explanation: Setup was unable to find the specified CSECT, csect_name, in the listing.


User Response: Ensure that the CSECT name is spelled correctly and is associated withthe correct listing in the control file.

ATGS0016S Setup: Wrong load module.

Explanation: The specified CSECT name was not found in the load module.


User Response: Ensure that the correct CSECT and load module names were specified inthe control file.



ATGS0017S Setup: CSECT: csect_name not compiled with TEST option or previ-ously instrumented.

Explanation: The ExtProgram-ID keyword indicates that the COBOL TEST option is to beused, but the CSECT csect_name was not compiled with the TEST option. You can also getthis error if the program has been previously instrumented with breakpoints by the setupprogram.


User Response: Recompile with the TEST compiler option, or run setup on a copy of theprogram that has not been previously instrumented.

ATGS0018S Setup: Requested CSECT: csect_name not compiled with COUNToption.

Explanation: The ExtProgram-ID keyword indicates that the OS/VS COBOL COUNT optionis to be used, but the CSECT csect_name was not compiled with the COUNT option.


User Response: Recompile with the COUNT compiler option.

ATGS0019S Setup: Requested CSECT: csect_name not a COBOL program.

Explanation: The specified CSECT, csect_name, is not a COBOL program.


User Response: Ensure that ExtProgram-ID is only used with COBOL routines. Checkthat the CSECT name is spelled correctly, and is associated with the correct load module inthe control file.

ATGS0020S Setup: TXT record not found to match this BRKTAB record.

Setup: OFFSET ( oooo) OPCODE (cccc)

Explanation: During the scan of an object module, a TXT record was found not to matchthe breakpoint code (cccc) at offset (oooo) in the BRKTAB data set. The BRKTAB data setcontains all of the breakpoints as identified from the source listings. The Setup reads theBRKTAB data set and looks through the object for each breakpoint. If a breakpoint cannotbe found, the program terminates.

Action: Program terminates.

User Response: Ensure the object module passed as input to the program was created bythe same source listing as the BRKTAB file. Rerun Setup.

ATGS0021S Setup: Breakpoint record not found. Errors possible.

Setup: Check the RPTMSGS dataset for additional information.

Explanation: No match in the object module for this breakpoint in BRKTAB.

Action: Program continues.

User Response: Ensure the object module passed as input to the program was created bythe same source listing as the BRKTAB file. Rerun Setup.



ATGS0022S Setup: BRKTAB header not found! Cannot continue.

Setup: BRKTAB header is not record # nnnnn.

Explanation: A BRKTAB header number could not be found. The number passed isoutside the range of possibilities for this BRKTAB.


User Response: Correct the errors found in the Setup run and rerun Setup.

ATGS0023S Setup: Storage could not be allocated. Program ending.

Setup: Insufficient storage.

Explanation: Setup could not acquire enough storage in order to process the objectmodule.


Problem Determination: Not enough storage was available to the job.


ATGS0024S Setup: Cannot open BRKTAB file created during Setup.

Explanation: The BRKTAB file of breakpoint data created in a previous step cannot beopened.


User Response: The BRKTAB file is created in a previous step. You should not see thiserror unless you modified the JCL for inclusion into your build process. Check the modifiedSetup JCL.

ATGS0025S Setup: Cannot open output file for VER/REP records.

Explanation: The output file containing update records for the AMASPZAP utility thatinstruments load modules cannot be opened.


User Response: This file is created as a temporary data set in the JCL. You should notsee this error unless you modified the JCL for inclusion into your build process. Check themodified Setup JCL.

ATGS0026S Setup: Illegal BRKTAB file.

Explanation: The BRKTAB file of breakpoint data created in a previous step is not acorrect BRKTAB.


User Response: The BRKTAB file is created in a previous step. You should not see thiserror unless you modified the JCL for inclusion into your build process. Check the modifiedSetup JCL.


ATGS0027S � ATGS0034W

ATGS0027S Setup: Unsupported value specified in parameter keyword.

Explanation: The value specified as the operand of the indicated keyword is invalid.


User Response: Correct the indicated operand.

ATGS0028S Setup: Invalid keyword or value keyword.

Explanation: The indicated keyword or keyword operand is invalid.


User Response: Correct the indicated keyword or operand.

ATGS0033S Setup: UTA/DA not supported for VisualAge PL/I 2.2

Explanation: Unit Test Assistant and Distillation Assistant functions are not currently sup-ported for programs generated by the VisualAge PL/I Version 2 Release 2 compiler.


User Response: Remove the UTA or DA request.

| ATGS0034W Setup: Listing has no executable statements: no breakpoints| inserted

| Explanation: A listing submitted to setup has no executable statements.

| Action: Setup program continues. A correct BRKTAB is created that can be used for exe-| cution and reports.

| User Response: The user can continue with execution and reports. A summary report can| be produced. Any listings with no executable statements will still be listed, with 0 for the| statement total.


ATGT0001S � ATGT0005E

ATGT: SAAThe following messages may be issued while executing the SAA functions:

ATGT0001S SAA: Output report file Dsname not found

Explanation: The data set to contain the SAA Change Validation report cannot be found.

Action: SAA Comparison Analysis terminates.

User Response: Make sure the report data set is allocated and accessible.

ATGT0002S SAA: Error rc from EXECIO reading dsn

Explanation: The input data set dsn could not be read. rc contains the return code fromEXECIO.


User Response: Ensure the input data set is in the proper format and is accessible.

ATGT0003S SAA: Dsn was not generated from a COBOL or PL/I source file

Explanation: The specified data set is not a COBOL or PL/I source listing.


User Response: Specify the proper source listing data set and retry.

ATGT0004S SAA: Error rc from EXECIO writing dsn

Explanation: The output data set dsn could not be written. rc contains the return code fromEXECIO.


User Response: Ensure the output data set is accessible.

ATGT0005E SAA: Invalid DBCS string str on line num of the seed list data set.

Explanation: An invalid DBCS string str was found on line num in the seed list data setwith DBCS scanning enabled.

Action: The input line is discarded and processing continues.

User Response: Ensure that any DBCS in the seed list complies with the rules for gener-ating DBCS as required by the compilers, REXX, and so on. For information about DBCSsupport, see Appendix C, “DBCS support” on page 365.


ATGT0006E � ATGT0011S

ATGT0006E SAA: Invalid DBCS string in the compare data set at input str.

Explanation: An invalid DBCS string str was found in the compare data set.

Action: The input is discarded and processing continues.

User Response: Ensure that DBCS scanning is only enabled if the source was compiledwith the DBCS (COBOL) or GRAPHIC (PL/I) compiler option and it compiled without errors.

ATGT0007S SAA: Old dataset dsn not found.

Explanation: The original source listing cannot be found.

Action: SAA terminates.

User Response: Make sure the original source listing is accessible.

ATGT0008S SAA: New listing dataset dsn not found.

Explanation: The changed source listing cannot be found.


User Response: Make sure the modified source listing is accessible.

ATGT0009S SAA: A member name or * must be specified for dsn

Explanation: dsn is a partitioned data set so a member name or * (that is, ALL) must bespecified.


User Response: Specify a member name or *.

ATGT0010S SAA: Invalid new and old file DSORG combination

Explanation: The DSORG for the original source listing data set and the modified sourcelisting data set must be the same.


User Response: Ensure both data sets have the same DSORG or specify a member nameif one is a partitioned data set.

ATGT0011S SAA: COBOL listing must have RECFM = FB or FBA

Explanation: The COBOL listings input to SAA must have RECFM = FB or FBA.


User Response: Check that the listings are stored as FB or FBA.


ATGT0012S � ATGT0017S

ATGT0012S SAA: Member name specified on a sequential dataset

Explanation: A member name was specified on a sequential data set.


User Response: Correct the data set name and rerun SAA.

ATGT0013S SAA: Member name must be specified for PDS to SEQ

Explanation: A member name must be specified for a PDS input in order to use a sequen-tial data set for the output. Input and output data sets must have a one to one mapping.



ATGT0014S SAA: Member name not allowed on output with * on input

Explanation: A member name was specified for the output data set when an asterisk wasused for the input member name. Input and output data sets must have a one to onemapping.



ATGT0015S SAA: Member name must be specified for SEQ to PDS

Explanation: If the input is a sequential data set and the output is a PDS, a member namemust be specified for the output data set.


User Response: Correct the dataset name and rerun SAA.

ATGT0016S SAA: Output dataset must have LRECL= Irecl

Explanation: The output data set must have the LRECL = Irecl.


User Response: Reallocate the output data set with the required LRECL or specify a non-existent data set and alllow SAA to allocate it for you.

ATGT0017S SAA: Ouput dataset must have RECFM = FB

Explanation: The output data set must have the RECFM = FB.


User Response: Reallocate the output data set with RECFM = FB, or specify a nonexistentdata set and allow SAA to allocate it for you.



ATGT0018S SAA: Invalid DSORG for output dataset

Explanation: The output data DSORG is invalid. It must be a sequential data set or aPDS.


User Response: Reallocate the output data set with a valid DSORG or specify a nonex-istent data set and allow SAA to allocate it for you.

ATGT0019S SAA: Invalid language specified lang

Explanation: lang is not a supported language.


User Response: Specify a supported language.

ATGT0020S SAA: Unrecognized listing type listing

Explanation: The input listing, listing, is not a recognized listing type.


User Response: Check that the listing name was specified correctly and that the correctlanguage was specified for that listing.

ATGT0021I SAA: Extracting source from listing into dataset.

Explanation: The source code is being extracted from listing into dataset.

Action: SAA continues.


ATGT0022S SAA: Listing dataset not found listing

Explanation: The input listing, listing, was not found.



ATGT0023S SAA: Member name found, but not a PDS dsName

Explanation: A member name was found, but the data set dsName is not a PDS.





| ATGT0024S SAA: The SuperC listing format is not supported

| Explanation: The SuperC listing format does not match one that is supported by SAA. The| ID line (if found) is not in a supported format.

| Action: Program terminates.

| User Response: Provide a valid SuperC listing (using only SAA supported SuperC| options).


ATGV0001E � ATGV0004E

ATGV: ATGOVARDDA, UTA, and Targeted Summary may issue the following messages while exe-cuting the ATGOVARD program:

ATGV0001E ATGOVARD: Level 88 flag variables cannot be monitored. Variable: str

Explanation: The level 88 flag variable str was listed to be monitored. These flags cannotbe monitored.

Action: The variable is discarded.

User Response: Ensure that the variable was specified correctly.

ATGV0002E ATGOVARD: Invalid control character found in internal control card.At input: str

Explanation: The first character in the internal control card, str, is not a valid control char-acter.

Action: Output message. The line is ignored.

User Response: Check for errors from the CVTCTL step of Setup. Look for errors in oraround fields in the control file that match elements in str.

Note: The control file is converted by CVTCTL into internal control cards. The controlcards may or may not contain data in a recognizable format, but will be provided for supportpurposes.

ATGV0003E ATGOVARD: Internal control card sequence error.At Input: str

Explanation: The internal control card str is not valid at this point in the internal controlcard sequence.

Action: Output message. The entry is ignored.

User Response: Check for errors from the CVTCTL step of Setup. Look for errors in oraround fields in the control file that match elements in str.

ATGV0004E ATGOVARD: No data found in internal control card.At Input: str

Explanation: No data fields were found in the internal control card str.

Action: Output message. The entry is ignored.

User Response: Check for errors from the CVTCTL step of Setup.


ATGV0005E � ATGV0009E

ATGV0005E ATGOVARD: Invalid variable level number in internal control card.At Input: str

Explanation: The variable level number field on internal control card str was either morethan two numeric digits or was an invalid alphabetic value.

Action: Output message. If numeric, truncate to two digits, otherwise the line is ignored. Ifignored, this will typically be followed by Variable not found messages.

User Response: Check for errors from the CVTCTL step of Setup. Check for control fileerrors in any variable entries that contain a level with the variable name found in str.

ATGV0006E ATGOVARD: Missing data field in internal control card.At Input: str

Explanation: One or more required keyword fields were missing in the control file.

Action: Output message. The control card is ignored.

User Response: Check for errors from the CVTCTL step of Setup. Include all requiredfields in the control file.

ATGV0007E ATGOVARD: Invalid variable residence entry in internal control card.At Input: str

Explanation: In an internal control card, an invalid value was found for the variable resi-dence. This relates to the VARIABLE and FILE keywords of the coverage statement in thecontrol file. This error should only occur as a side effect of another problem.

Action: Output message. The control card is ignored, but processing continues.


ATGV0008E ATGOVARD: Invalid variable type entry in internal control card.At Input: str

Explanation: In an internal control card, an invalid value was found for the variable typefield. This relates to the CHAR keyword of the coverage statement in the control file. Thiserror should only occur as a side effect of another problem.



ATGV0009E ATGOVARD: Invalid variable offset entry in control file.At Input: str

Explanation: A nonnumeric character was found in the operand of either the OFFSET orPOSITION keywords of a coverage statement, or the KEYOFFSET, or KEYPOSITIONkeywords in a file statement in the control file.

Action: Output message. The entry is ignored, but the processing continues.

User Response: Check for errors from the CVTCTL step of Setup. Correct the control fileentry.


ATGV0010E � ATGV0014W

ATGV0010E ATGOVARD: Invalid variable length entry in internal control card.At Input: str

Explanation: A nonnumeric character was found in the operand str to the LENGTH orKEYLEN keyword in the control file.

Action: Output message. The entry is ignored, but processing continues.


ATGV0011E ATGOVARD: Invalid variable read times entry in internal controlcard.

At Input: str

Explanation: A nonnumeric character was found in the operand str of the READEVERYkeyword in the control file.

Action: Output message. The entry is ignored, but processing continues.


ATGV0012E ATGOVARD: Invalid variable read max entry in internal control card.At Input: str

Explanation: A nonnumeric character was found in the operand str of the MAXSAVEkeyword in the control file.

Action: Output message. The statement is ignored, but processing continues.


ATGV0013E ATGOVARD: Invalid statement list entry in internal control card.At Input: str

Explanation: A nonnumeric entry was found as the operand to the STMTS keyword in thecontrol file.

Action: Output message. The statement is ignored, but processing continues.


ATGV0014W ATGOVARD: An unrecognized base locator type was found in thelisting.

Base Locator: str

Explanation: An unknown base locator type was found in the listing file.

Action: This message is issued.

User Response: None required.


ATGV0015W � ATGV0019W

ATGV0015W ATGOVARD: Read exceeds the variable length.Read length truncated to variable length.

Variable: str1

Explanation: The combined read length and offset given in the control file for the variablestr1 exceeds the actual length of the variable as read from the listing file data map.

Action: Reset the read length to the actual variable data length less the given offset.

User Response: Ensure that the variable read length and offset were correctly specified inthe control file.

ATGV0016E ATGOVARD: Read exceeds the maximum length supported.Read length truncated to nnnn.

Variable: str1

Explanation: The read length specified for the variable str1 exceeds the maximum sup-ported read length of nnnn.

Action: Reset the read length to nnnn.

User Response: Ensure that the variable read length and offset were correctly specified inthe control file. If the desired read length exceeds the supported maximum, use multiplereads with appropriate offsets.

ATGV0017E ATGOVARD: Offset exceeds the variable data length.Offset set to 0.

Variable: str1

Explanation: The read offset specified for the variable str1 exceeds the actual data lengthof variable str1.

Action: Reset the offset to 0.

User Response: Ensure that the variable read offset is correctly specified in the control file.

ATGV0018E ATGOVARD: Invalid wildcard character found in control file. Variable: str

Explanation: The wildcard character * was found in an invalid location in the control file,associated with the variable str.

Action: Output message and attempt to process normally.

User Response: Check for errors from the CVTCTL step of Setup. Edit the control file toremove or correct the wildcard usage.

ATGV0019W ATGOVARD: Failed to find a variable in the listing file.Variable Name: var-name

Explanation: The variable var-name was not found in the listing file.

Action: Output message and continue with the next variable.

User Response: Edit the control file to verify that the variable name is spelled correctly. Ifthere are multiple programs in the listing, also check that the correct program is beingsearched for the given variable.


ATGV0020I � ATGV0024E

ATGV0020I ATGOVARD: No statements were found for a variable.Variable Name: str1Program ID: str2

Explanation: The variable str1 in the program str2 was not accessed on any statementswithin the specified search.

Action: The variable is discarded.

User Response: Edit the control file to ensure that the variable was specified in the formdesired. Try using the FULL option for the variable statement list. The variable may beunused.

ATGV0021W ATGOVARD: Unknown line format in listing file data map. Line: str

Explanation: The line str is not a recognized format for a listing file data map line.

Action: Ignore the line and continue.


ATGV0022E ATGOVARD: Invalid action entry in internal control card. At Input: str

Explanation: An invalid action key was found in an internal control card. This error shouldonly occur as a side effect of another problem.



ATGV0023E ATGOVARD: Invalid sign entry in internal control card. At Input: str

Explanation: An invalid sign value was found in an internal control card. This error shouldonly occur as a side effect of another problem.



ATGV0024E ATGOVARD: Invalid value entry in internal control card. At Input: str

Explanation: A nonnumeric value was found in an internal control card where a numericvalue was expected. This error should only occur as a side effect of another problem.




ATGV0025E � ATGV0029W

ATGV0025E ATGOVARD: Error normalizing a DBCS string.At Input: str

Explanation: The program was not able to properly interpret the DBCS string in str.

Action: The string is discarded and processing continues.

User Response: Ensure that any DBCS characters are valid and properly delimited.

ATGV0026E ATGOVARD: Program name not found in listing.File Name: str1

Explanation: The program name str1 was not found in the listing file.

Action: Output message.

User Response: Ensure that the program name is entered under the correct listing file inthe control file, and that it is spelled correctly.

ATGV0027E ATGOVARD: Targeted statement num is not in executable code.In listing: list

Explanation: Statement number num was targeted in listing list, but is not within execut-able code. The statement cannot be resolved to an executable statement.

Action: The statement is discarded and processing continues.

User Response: Ensure that only executable statements are targeted. See the descriptionof the TARGETSTMT control statement in the “Targeted Summary control file” on page 89of this document for the rules for determining statement numbers.

ATGV0028W ATGOVARD: Targeted statement(s) was resolved to different execut-able statement(s).

In listing: list Statement(s): stmts

Explanation: One or more statement numbers was targeted in listing list, but is not anexecutable statement. In each pairing in the statements list the first number was given, butwas not an executable statement. The second is the statement number actually used in gen-erating the Targeted Summary report.

Action: The second statement of each pair is used in place of the first. Processing con-tinues.

User Response: Ensure that only executable statements are targeted. See the descriptionof the TARGETSTMT control statement in the “Targeted Summary control file” on page 89of this document for the rules for determining statement numbers.

ATGV0029W ATGOVARD: Key gathering and variable monitoring detected in thesame run

Explanation: Keys from file reads (DA) are being read in the same run as variables arebeing monitored (UTA). The values read from the keys and variables will be mingled in theoutput reports and key lists. You must separate these if you want to do distillation.

Action: This message is issued.

User Response: Create two control files, one for DA and the other for UTA, and then runDA and UTA as separate jobs.


ATGV0030S � ATGV0035S

ATGV0030S ATGOVARD: UTA or DA commands mixed with Targeted Coveragecommands.

Explanation: UTA or DA commands were mixed with targeted coverage commands in thesame run.

Action: The ATGOVARD program terminates.

User Response: Check for an invalid program invocation. Contact ATC support.

ATGV0031S ATGOVARD: Control file open failure.

Explanation: The program was unable to open the control file.


User Response: Ensure that the file name and path were correctly specified, and that thefile exists.

ATGV0032S ATGOVARD: Listing file open failure.

Explanation: The program was unable to open the listing file.



ATGV0033S ATGOVARD: DBGTAB file open failure.

Explanation: The program was unable to open the DBGTAB file.



ATGV0034S ATGOVARD: Invalid listing file.

Explanation: The listing file passed to the ATGOVARD program could not be identified asa valid listing file for any supported language or compiler.


User Response: Ensure that the file is a valid listing file from a supported compiler, andthat the correct compiler options were specified. For a list of compiler options, see “Setup”on page 211.

ATGV0035S ATGOVARD: Memory allocation failure for statement record.

Explanation: A request for a memory allocation for a statement record failed.


User Response: Increase the region size on your job card for the Setup step.



ATGV0036S ATGOVARD: Memory allocation for variable record failed.

Explanation: A request for a memory allocation for a variable record failed.


User Response: Increase the region size on your job card for the Setup step.

ATGV0037S ATGOVARD: Variable record index overflow.

Explanation: The number of variable records has exceeded the index limits.

Action: ATGOVARD terminates.


ATGV0038S ATGOVARD: No Data Cross-reference found in the compiler listing.

Explanation: No data cross-reference was found in the compiler listing file.


User Response: Ensure that the compiler option to generate a cross-reference was usedfor the compile.

ATGV0039S ATGOVARD: No Data Map section found in the compiler listing.

Explanation: No data map section was found in the compiler listing file.


User Response: Ensure that the compiler option to generate the data map was used forthe compile.

ATGV0040S ATGOVARD: No assembler code section found in the compilerlisting.

Explanation: No assembler code section was found in the compiler listing file.


User Response: Ensure that the compiler option to include pseudo-assembler code in thelisting was used for the compile.

ATGV0041S ATGOVARD: No Table of Offsets found in the compiler listing.

Explanation: The listing section labeled “TABLES OF OFFSETS AND STATEMENTNUMBERS” was not found. The OFFSET compiler option is required to produce this table.


User Response: Ensure that you specify the OFFSET option when you compile.



ATGV0042S ATGOVARD: Listing file name argument required.

Explanation: The listing file name is a required parameter for this program.


User Response: Include the listing file name as a parameter exactly as it appears in thecontrol file.

ATGV0043S ATGOVARD: No entry found in control file for specified listing.File Name: str1

Explanation: The listing file name str1 was not found in the control file.


User Response: Include the listing file name as a parameter exactly as it appears in thecontrol file.

ATGV0044S ATGOVARD: A fully qualified variable name was too long for thebuffer. Variable Name: str1

Explanation: The fully qualified variable name str1 was too long for the program buffer.


User Response: Check that an R, C, or N line follows each set of type L lines which fullyqualify a variable in the control file.

Note: The buffer is longer than the longest valid COBOL variable name.

ATGV0045S ATGOVARD: Internal error 160.

Explanation: An internal error has caused a program failure.



ATGV0046S ATGOVARD: Invalid internal control card.

Explanation: An invalid internal control card has caused a program failure, or you coded acontrol card for a tool that you are not licensed for.


User Response: Ensure that all parameters in the control file are specified correctly, orremove the control card that specifies the unlicensed function from your control cards.

ATGV0047S ATGOVARD: Invalid keyword or value keyword.






ATGV0048S ATGOVARD: Unsupported value specified in parameter keyword.

Explanation: The operand of the indicated keyword is invalid.




ATGW0001S � ATGW0006S

ATGW: Distill and File WarpThe following messages may be issued while executing DA or UTA file warping:

ATGW0001S Error xxxx opening File Warp dataset dsn

Explanation: The File Warp control file cannot be opened.

Action: File Warp is not done.

User Response: Verify the name of the File Warp control file that you entered on thecreate File Warp JCL screen.

ATGW0002S Return Code xxxx from ALLOCATE allocating dsn

Explanation: The program could not allocate the intermediate file of warp statements to bepassed to the File Warp program.


User Response: Check that the File Warp JCL has not been corrupted. This is an inter-mediate temporary file passed between job steps.

ATGW0003S Return Code xxxx from EXECIO reading dsn

Explanation: An I/O failure occurred reading the File Warp control file.


User Response: Verify that the File Warp control file is readable.

ATGW0004S Invalid DBCS or mixed string. Check DBCS name(s) on line xxxx ofthe control file

Explanation: There was a control file error with DBCS names.


User Response: Check the DBCS names used for the DBCS control characters.

ATGW0005S xxxx is not a valid option for the yyyy statement

Explanation: An incorrect use of options for a statement was detected.


User Response: Check the indicated statement for correct syntax.

ATGW0006S Required operand omitted from: xxxx

Explanation: A required warp operand was omitted (for example, warp value).





ATGW0007S Return Code xxxx from EXECIO writing yyyy

Explanation: An I/O error occurred writing to the intermediate file.


User Response: Check that the created JCL has not been corrupted. Recreate it if neces-sary.

ATGW0008S Dsn file is not allocated

Explanation: The intermediate output file is not allocated.



ATGW0009S Return Code xxxx from ALLOCATE allocating dsn

Explanation: The intermediate output file could not be allocated.



ATGW0010S Last line is continued. It is ignored.

Explanation: A continuation character was found on the last control card in the control file.

Action: The function terminates.

User Response: Correct the control file and restart.

ATGW0011S opnd is not a valid operand for the kwd keyword opt_line.

Explanation: opnd is not a valid operand for the kwd keyword.


User Response: Correct the operand and restart.

ATGW0012S Record label mismatch detected at statement: xxxx

Explanation: A statement used to define a record label has incorrect syntax.





ATGW0013S xxxx is not a valid operand for yyyy

Explanation: A statement has incorrect syntax.



ATGW0014S Warp control file has no warps

Explanation: The warp control file contained no warp actions.


User Response: Check that you used a valid warp control file.

ATGW0015S Required operand omitted

Explanation: An operand required to run Distillation has not been specified.

Action: Distillation/File Warp terminates.

User Response: Specify the omitted operand and retry.

ATGW0016S Error rc from LISTDSI for dsn

Explanation: An error has occurred while obtaining data set information for dsn. rc containsthe return code from LISTDSI.



ATGW0017S Error rc allocating dsn like model dsn

Explanation: An error has occurred while allocating dsn like the model data set. rc containsthe return code from allocate.



ATGW0018S New Master DCB not identical to Master DCB

Explanation: The DCBs for the original data file and the output file do not match.


User Response: Reallocate the data set to contain the output file with the same DCB attri-butes as the original data set.



ATGW0019S Master/New file volser specified without Unit (or vice versa)

Explanation: You have specified a UNIT or VOLSER, but not both, for either the originaldata file or the output file.


User Response: If a data set is not cataloged, specify both UNIT and VOLSER parame-ters.

ATGW0020S Key positions and/or length not specified

Explanation: The key position and/or length was not supplied on the create distillation JCLscreen.

Action: Distillation is not done.

User Response: Supply the values on the screen and recreate the JCL.

ATGW0021S Unable to OPEN KEYFILE DCB

Explanation: The key file cannot be opened.


User Response: Verify that a key file of keys that caused new coverage was created.Usually the key file will be in a PDS with the last qualifier being VARDATA. If it is a sequen-tial data set, the last qualifier is usually VARDATA. Look at the distillation JCL (Dxxxxxx)DISTILL step, KEYFILE DDNAME for the data set name used for the key file.

ATGW0022S Illegal function requested

Explanation: The option supplied to the file conversion program was illegal.

Action: Distillation/File Warp is not done.

User Response: The option is supplied automatically within the ATGRDADF orATGRFWRP REXX exec, so you should never see this error. Contact ATC support.

ATGW0023S RECFM=VS is not currently supported

Explanation: You specified an input data set with VS record format.


User Response: VS record formats are not supported.

ATGW0024S Unable to OPEN MASTER(INPUT) DCB

Explanation: The input data set could not be opened.


User Response: Verify that you specified the correct input data set.



ATGW0025S Unable to OPEN NEWMASTER(OUTPUT) DCB

Explanation: The output data set could not be opened.


User Response: Verify that you specified correct qualifiers for the output data set.

ATGW0026S Specified key position lies outside of KeyFile record

Explanation: The key position supplied on the create distillation JCL screen is greater thanthe size of the record.


User Response: Correct the key position on the panel and recreate the JCL.

ATGW0027S DSORG of MASTER(INPUT) is not supported

Explanation: The organization of the input data set is not supported. Supported organiza-tions are: PS, PSU, PO, POU, or VSAM.


User Response: Specify a correct input data set.

ATGW0028S Error from Dynamic Allocation. Error/Info Code: xxxx

Explanation: An error obtaining dynamic storage occurred.


User Response: Use the error code to obtain further information. Verify your parameterson the create distillation JCL screen.

ATGW0029S Specified key position lies outside of Master record

Explanation: The key position supplied on the create distillation JCL screen is greaterthan the size of the record.


User Response: Correct the key position on the panel and recreate the JCL.

ATGW0030S I/O error reading VSAM Master(INPUT). Feedback: xxxx

Explanation: An error occurred reading the input data set.


User Response: Check that the input data set is valid. Feedback contains the errorreturned from the I/O routine.



ATGW0031S I/O error writing VSAM Master(OUTPUT). Feedback: xxxx

Explanation: An error occurred writing the output data set.


User Response: Check that the output data set is valid. "Feedback" contains the errorreturned from the I/O routine.

ATGW0032S xxxx is not a valid decimal parameter

Explanation: A number passed to the distillation program (key position, length) is notvalid.

Action: Distillation warp is not done.

User Response: Correct the number on the create distillation JCL screen.

ATGW0033S Unable to OPEN Warp File or file empty.

Explanation: The intermediate warp control file created by the warp control file conversionstep could not be opened.


User Response: Verify that the first step (warp control file conversion) executed success-fully. Verify that your warp control file is correct.

ATGW0034S Warping signed, but value in file is unsigned offset: xxxx

Explanation: You specified that the field to warp was a signed number in the warp controlfile, but the field in the file contains an unsigned number.


User Response: Correct the warp control file.

ATGW0035S Warping unsigned, but value in file is signed offset: xxxx

Explanation: You specified that the field to warp was an unsigned number in the warpcontrol file, but the field in the file contains an signed number.


User Response: Correct the warp control file.

ATGW0036S No space for warp array

Explanation: The dynamic allocation of storage for the warp action array failed.


User Response: Check that the warp control file is valid, and that the warp file conversionprogram ran successfully.



ATGW0037S Unable to OPEN MASTER(INPUT) ACB. Error Code: xxxx

Explanation: The input data set could not be opened.


User Response: Verify that you specified the correct input data set.

ATGW0038S Unable to OPEN NEWMASTR(OUTPUT) ACB. Error Code: xxxx

Explanation: The output data set could not be opened.


User Response: Verify that you specified correct qualifiers for the output data set.

ATGW0039S Unsupported value specified in parameter keyword.

Explanation: The operand of the indicated keyword is invalid.



ATGW0040S Invalid keyword or value keyword.





ATGX0001S � ATGX0004S

ATGX: Monitor and commandsThe following messages may be issued when the monitor SVCs are installed andenabled, when monitor commands are executed, or while the buffer monitor is exe-cuting.

Note that messages that indicate they are not translated are messages issuedduring the monitor SVC installation or by the monitor SVCs. These messagesalways appear in English regardless of the NATLANG specification.

ATGX0001S Can not find monitor program (ATGOMONS) in authorized library.

Explanation: Failure finding the monitor program (ATGOMONS).

Action: The monitor installer terminates.

User Response: Verify that the monitor program is installed in an authorized library in theload module search path for the installation job.

Translation: This message is not translated.

ATGX0002S Cannot allocate space in ECSA for monitor.

Explanation: The install program cannot allocate ECSA (extended common service area)storage for the monitor. Insufficient ECSA storage was available to install the monitorprogram.


User Response: The amount of storage used by the monitor is listed in Appendix B, “ATCrequirements and resources” on page 359. Verify with your system programmer that thismuch ECSA storage is available.


ATGX0003S Error loading monitor in ECSA storage.

Explanation: Failure loading the monitor into ECSA (extended common service area).


User Response: Verify that the monitor program is installed in an authorized library in theload module search path for the installation job.


ATGX0004S Error updating SVC table with new SVC numbers.

Explanation: Failure updating the SVC table with the new user SVC numbers.


User Response: Verify that the user SVC numbers passed to the monitor install program(ATGOMNST) are available.




ATGX0005S Error removing prior SVC token.

Explanation: An operating system error occurred while trying to remove an SVC token.


User Response: This is an operating system error when trying to remove an SVC token.Retry, and if the problem persists, contact systems support or ATC support.


ATGX0006S Error setting SVC token.

Explanation: An operating system error occurred while trying to obtain an SVC token.


User Response: This is an operating system error when trying to obtain an SVC token.Retry, and if the problem persists, contact systems support or ATC support.


ATGX0007S Invalid short SVC number.

Explanation: The SVC number supplied for short opcodes (the first number passed toATGOMNST) is not allowed. It must be a hexadecimal number between C8 and FF.


User Response: Ensure that the first parameter passed to the ATGOMNST program in themonitor install JCL is a hexadecimal number between C8 and FF without any surroundingquotation marks.


ATGX0008S Invalid long SVC number.

Explanation: The SVC number supplied for long opcodes (the second number passed toATGOMNST) is not allowed. It must be a hexadecimal number between C8 and FF.


User Response: Ensure that the second parameter passed to the ATGOMNST program inthe monitor install JCL is a hexadecimal number between C8 and FF without any sur-rounding quotation marks.


ATGX0009S Error writing VARTAB file

Explanation: A user tried to stop a session, but the VARTAB file of variable read datacould not be written.

Action: The program that writes full buffers of variable data terminates.

User Response: Check that the VARTAB file (DD name VARTAB in the monitor JCLXnnnnnn) is valid.



ATGX0010S Minimum wait time >= Maximum wait time

Explanation: The minimum wait time specified for the buffer monitor in the ATC defaultswas greater than the maximum time.

Action: The buffer monitor program terminates.

User Response: Terminate the monitor (using the ATGQUIT command), correct theminimum and maximum times in the ATC defaults, and recreate the monitor JCL from thepanels.

ATGX0011W The lowest wait time is lower than 10 (.1 seconds). It is set to 10.

Explanation: The minimum wait time specified for the buffer monitor in the ATC defaultswas less than 10 (.1 seconds). It is set to 10, and the buffer monitor continues.

Action: The buffer monitor program continues.

User Response: Correct the minimum wait time in the ATC defaults, and recreate themonitor JCL so that you will not get this message.

ATGX0012W The highest wait time is higher than 1600 (16 seconds). It is set to16.

Explanation: The maximum wait time specified for the buffer monitor in the ATC defaultswas greater than 1600 (16 seconds). It is set to 1600, and the buffer monitor continues.

Action: The buffer monitor program continues.

User Response: Correct the maximum wait time in the ATC defaults, and recreate themonitor JCL so that you will not get this message.

ATGX0013S Session name xxxxxxxx not found. Write buffer program ending.

Explanation: The session name xxxxxxxx was not found as an active session. This shouldonly occur if you have modified your monitor JCL incorrectly.


User Response: Terminate the monitor (using the ATGQUIT command), and correct thesession name in the ATGOMVAR step of the monitor JCL.

ATGX0014S No session table exists. Cannot continue.

Explanation: The monitor is not installed, or has been corrupted.


User Response: Reinstall the monitor.


ATGX0015I � ATGX0019S

ATGX0015I Session has ended - variable write program for this session ending.

Explanation: The session being monitored has ended. The buffer monitor program isending. This is the normal termination message.



ATGX0016S Error opening VARTAB file.

Explanation: A user tried to stop a session, but the VARTAB file of variable read datacould not be opened.


User Response: Check that the VARTAB file (DD name VARTAB in the monitor JCLXnnnnnn) is valid.

ATGX0017S Invalid command

Explanation: An invalid command was issued.

Action: Ignored.

User Response: Since the commands are generated by REXX programs or created JCL,check that the REXX or JCL that issued the command has not been corrupted.

ATGX0018S Error reading BRKTAB file

Explanation: A user tried to start a session, but there was an error reading the BRKTABfile of breakpoint data.

Action: Command not executed.

User Response: Check that the BRKTAB file (DD name BRKTAB in the monitor JCLXnnnnnn) is accessible and is a valid BRKTAB file (starts with characters BT8).

ATGX0019S Invalid BRKTAB file

Explanation: A user tried to start a session, but the BRKTAB file of breakpoint data isinvalid.


User Response: Check that the BRKTAB file (DD name BRKTAB in the monitor JCLXnnnnnn) is a valid BRKTAB file and was created by the V2R1M3 or later Setup program(starts with characters BT8).



ATGX0020S Error opening BRKOUT file

Explanation: A user tried to stop a session, but the BRKOUT file of breakpoint data couldnot be opened.


User Response: Check that the BRKOUT file (DD name BRKOUT in the monitor JCLXnnnnnn) exists and is accessible.

ATGX0021S Error writing BRKOUT file

Explanation: A user tried to stop a session, but the BRKOUT file of breakpoint data couldnot be written.


User Response: Check that the BRKOUT file (DD name BRKOUT in the monitor JCLXnnnnnn) exists and is accessible.

ATGX0022S Error opening VARCTL file

Explanation: A user tried to start a session, but the VARCTL file of variable read datacould not be opened.


User Response: Check that the VARCTL file (DD name VARCTL in the monitor JCLXnnnnnn) exists and is accessible.

ATGX0023S Invalid VARCTL file

Explanation: A user tried to start a session, but the VARCTL file of variable read datacould not be opened.


User Response: Check that the VARCTL file (DD name VARCTL in the monitor JCLXnnnnnn) is a valid VARCTL file produced by Setup and starts with the characters VAR03.

ATGX0024S Error reading VARCTL file

Explanation: A user tried to start a session, but an error occurred reading the VARCTL fileof variable read data.


User Response: Check that the VARCTL file (DD name VARCTL in the monitor JCLXnnnnnn) is a valid VARCTL file produced by Setup and starts with the characters VAR03.



ATGX0025S No ECSA space for BP table

Explanation: A user tried to start a session, but the monitor could not allocate sufficientspace for the breakpoint (BP) table in ECSA.


User Response: For the storage requirements of the BP table, see Appendix B, “ATCrequirements and resources” on page 359. Reduce the number of object modules beingtested, or contact the system programmer to increase ECSA storage.

ATGX0026S No ECSA space for PA table

Explanation: A user tried to start a session, but the monitor could not allocate sufficientspace for the program area (PA) table in ECSA.


User Response: For the storage requirements of the PA table, see Appendix B, “ATCrequirements and resources” on page 359. Reduce the number of object modules beingtested, or contact the system programmer to increase ECSA storage.

ATGX0027S No ECSA space for VA table

Explanation: A user tried to start a session, but the monitor could not allocate sufficientspace for the variable read table in ECSA.


User Response: For the storage requirements of the breakpoint (BP) table, seeAppendix B, “ATC requirements and resources” on page 359. Reduce the number of vari-able reads, or contact the system programmer to increase ECSA storage. Because thestorage requirements of the variable (VA) table are small, this may be a symptom of aninvalid VARCTL table.

ATGX0028S Downlevel Monitor running - cannot execute command

Explanation: The installed monitor is at a previous level that is now incompatible.


User Response: Install the current monitor.


ATGX0029S No storage in SQA for monitor tables

Explanation: During installation of the ATC monitor, the monitor could not obtain SQAspace for its tables.

Action: The installation of the monitor is terminated.

User Response: See Appendix B, “ATC requirements and resources” on page 359 for theamount of SQA needed by the monitor during installation. Contact your systems pro-grammer to determine the amount of SQA space available on your system.



ATGX0030W � ATGX0034S

ATGX0030W Dup listing in ID: user_ID listing_name

Explanation: A monitor session was started that contains a BRKTAB for a listing/objectmodule that is being monitored by another session.

Action: The session is started.

User Response: Note that if two or more sessions share a BRKTAB for a listing/objectmodule, the first session started will get all coverage for the listing/object module (sessionsstarted after the first will have incomplete coverage for any shared listings/object modules).

ATGX0031S The requested session id sess_id was not found.

Explanation: A command that requires a session ID was issued, but the session ID(sess_id) was not found.


User Response: Check that the sess_id is valid. The session ID is usually your TSOsession ID.

ATGX0032S The requested session id is not active. Command rejected.

Explanation: A command that requires a session ID was issued, but the session ID wasnot active.

Action: Command rejected.

User Response: Check that the sess_id is active by using the ATGSESSN command.

ATGX0033S The requested PA# pa_num was not found.

Explanation: A command that requires a program area (PA) number was issued, but thePA number pa_num was not found.


User Response: Check that the pa_num is valid. The ATGLIST command lists the numberof PAs for each listing in a session.

ATGX0034S No free sessions in session table - session not started

Explanation: A user attempted to start a new session, but there are new free sessions inthe monitor session table.


User Response: Use the ATGSESSN to display active sessions. Stop or quit sessionsthat are not needed. A maximum of 32 sessions can be active.



ATGX0035S Session already active, cannot be started again

Explanation: A user attempted to start a new session, but a session is already started withthat session ID.


User Response: Use the ATGSESSN command to display active sessions. Stop or quitthe session with the name that you are trying to start, or start a session with a differentname.

ATGX0036S No previous copy of the monitor exists - cannot do commands to it

Explanation: The monitor is not installed, or has been corrupted.



ATGX0037S No session table exists.

Explanation: The session table does not exist or has been corrupted.



ATGX0038S The command was not recognized by CA

Explanation: The command was not recognized by the command processor.

Action: The command is not executed.

User Response: Since the commands are generated by REXX execs or created JCL,check that the REXX or JCL that issued the command has not been corrupted.

ATGX0039S Error number err_num occurred. Contact ATC support.

Explanation: An undocumented error occurred.

Action: The operation terminates.

User Response: Contact ATC support with the error number and explain the circum-stances that caused it.

ATGX0040S Browse of Messages file was unable to complete.

Explanation: The messages file could not be browsed. The messages file is used by themonitor commands to return messages or data.


User Response: Check for other messages or ISPF problems.



ATGX0041S Error executing the cmd command. Be sure that ATGOMCMD is inauthlib

Explanation: The call to the command processor failed.


User Response: Be sure that ATGOMCMD is in the specified authorized library.

ATGX0042I No sessions currently active.

Explanation: There are no monitor sessions currently active.

Action: This message is displayed.


ATGX0043S Session sess_id has not been stopped. Verify that the sessionexists.

Explanation: An error occurred in the ATGSTOP routine, and the session has not beenstopped. The likely cause for the associated errors is that the specified session ID does notexist.


User Response: Verify that the session indicated exists. If it does, address other mes-sages and retry, or issue the ATGQUIT command.

ATGX0044S ATC unidentified BP at addr xxxxxxxx BP yyyyyyyy

Explanation: ATC could not identify an SVC breakpoint inserted into the user's program.The breakpoint is at address xxxxxxxx in the program. The unidentified breakpoint isyyyyyyyy.

Action: The user's program terminates with a 7C3 abend.

User Response: See Chapter 25, “Diagnosing monitor problems” on page 261 for possiblecauses.


ATGX0045S ATC unidentified BP at addr xxxxxxxx BP yyyyyyyy

Explanation: ATC could not identify an SVC breakpoint inserted in the user's program (thatwas running in a CICS environment). The breakpoint is at address xxxxxxxx in the program.The unidentified breakpoint is yyyyyyyy.

Action: The user's program terminates with a 7C3 abend.

User Response: See Chapter 25, “Diagnosing monitor problems” on page 261 for possiblecauses.




ATGX0067S Invalid parameter: xxx

Explanation: The parameter xxx passed to a monitor program is invalid.


User Response: Provide a correct parameter (or none to get the installation default).

ATGX0068S Unsupported value specified in parameter xxx.

Explanation: The value passed to parameter xxx is invalid.


User Response: Provide a correct value for the parameter (or none to get the installationdefault).

ATGX0069S No BPs in BRKTAB. - session not started

Explanation: You tried to start a monitor session with a BRKTAB file (the data on BPs fromthe setup step) that contained no breakpoints.

Action: Requested monitor session is not started.

User Response: Check that you are providing the correct BRKTAB file in the JCL thatstarts the session. Check that the setup step that created this BRKTAB had a listing toprocess that contained executable code.

ATGX0070S INTERNAL SOFTWARE ERROR: Literal xxx was not found.

Explanation: An internal software error occurred.



ATGX0071S Error executing xxxxxxxx. Possible allocation error

Explanation: ATGSTOP ran the 'prefix.sessionid.EXTEMP.EXEC' REXX EXEC to allocatethe output BRKOUT data set. This EXEC could not allocate the BRKOUT data set OLD.

Action: ATGSTOP terminates without stopping the session.

User Response: Determine why the BRKOUT data set could not be allocated OLD.Correct the problem and re-run ATGSTOP.


ATGY0001S � ATGY0005S

ATGY: Control filesThe following messages may be issued while control files are processed:

ATGY0001S Control: Error xxxxxxxx for dataset dddddddd.

Explanation: The specified message (xxxxxxxx) was returned from the SYSDSN commandindicating that the specified data set (dddddddd) could not be found or could not be proc-essed.


User Response: Correct the data set name specification or make sure that the data setcan be accessed.

ATGY0002S Control: oooooooo is not a valid option.

Explanation: The specified option was found on the command invocation but is not a validoption recognized by this command.


User Response: Remove or correct the specified option.

ATGY0003S Control: Return Code rr from ALLOCATE allocating dddddddd.

Explanation: Return Code rr was returned from the ALLOCATE command attempting toallocate the specified input data set.


User Response: Correct the data set name specification or ensure that the data set can beallocated.

ATGY0004S Control: Return Code rr from EXECIO reading dddddddd.

Explanation: Return code rr was returned from the EXECIO command attempting to readthe specified data set.


User Response: Correct the indicated error or correct the data set name specification.

ATGY0005S Control: Invalid DBCS or mixed string. Check DBCS name(s) on linenum of the control file.

Explanation: The statement shown in the second line of the message contains an invalidDBCS or mixed string. This statement was found on line number num in the control file.


User Response: Correct the DBCS usage in the statement indicated.



ATGY0006S Control: oooooooo is not a valid option for the ssss statement.

Explanation: A keyword (oooooooo) was specified for the ssss statement which is not validon that statement.

Action: Processing terminates. The statement in error is shown in the second line of theerror message.

User Response: Correct the specified option.

ATGY0007S Control: Volume and Unit cannot be specified without the corre-sponding DSName.

Explanation: A keyword FromVol or FromUnit was specified without FromObjDsn orToVol or ToUnit was specified without ToObjDsn statement which is not valid on that state-ment. These operands can only be specified when the corresponding data set name isspecified.



ATGY0008S Control: oooooooo is not a valid option for the ssss statement.

Explanation: A keyword (oooooooo) was specified for the ssss statement which is not validon that statement.



ATGY0009S Control: The operand of the COBOL or PL/I operand does not pointto a statement of that type.

Explanation: The SCOPE statement is coded with a COBOL or PL/I operand whoseoperand does not point to a matching COBOL or PL/I statement.


User Response: Correct the control statement.

ATGY0010S Control: Required operand omitted from:

Explanation: A required operand was omitted from the statement shown in the second lineof the message.


User Response: Correct the statement by adding all required operands.



ATGY0011S Control: LISTDSN= dddddddd contains an asterisk specification.However LISTMEMBER= was not specified. stmt

Explanation: When the data set name dddddddd contains an asterisk, LISTMEMBER=must be specified to replace the asterisk.


User Response: Correct the statement by adding the LISTMEMBER= operand or removingthe asterisk from the LISTDSN= operand.

ATGY0012S Control: llll is a duplicate label on the following statement. It isignored. stmt

Explanation: The specified label was previously found on a statement of the same type.


User Response: Change the label to be unique.

ATGY0013S Control: llll is not a previously defined label. The following statementis ignored. stmt

Explanation: The statement shown in the second line of the message referenced a labelwhich was not previously defined.


User Response: Correct the label reference.

ATGY0014S Control: Return Code rr from EXECIO writing dddddddd.

Explanation: Return Code rr was returned from the EXECIO command attempting to writethe specified data set.


User Response: Correct the indicated error or correct the data set name specification. *

ATGY0015S Control: Invalid NAME= operand in statement: stmt

Explanation: The statement shown in the second line of the message contains an invalidoperand of the NAME=.


User Response: Correct the variable name specification.



ATGY0016S Control: A SCOPE cannot be defined in an ASM program. stmt

Explanation: The SCOPE control statement is not supported for assembler programs.


User Response: Remove the indicated control statement.

ATGY0017S Control: The SCOPE referenced by the following statement must beCOBOL. stmt

Explanation: The indicated control statement is only supported for COBOL programs.


User Response: Remove the indicated control statement.

ATGY0018S Control: ffffffff file is not allocated.

Explanation: The specified DDNAME was not previously allocated.


User Response: Correct the DDNAME specification or ensure that the file is allocated.

ATGY0019S Control: Last line is continued. It is ignored.

Explanation: The last non-comment line in the control file ended in a comma indicating thatit was continued. Since no more lines were found in the file, the partial line is ignored.



ATGY0020S Control: Statement ssssssss not recognized.

Explanation: The indicated keyword is not a valid control statement type.



ATGY0021S Control: oooooooo is not a valid operand for the kkkkkkkk keyword.stmt

Explanation: The indicated operand is not valid for the indicated keyword.





ATGY0022S Control: Load and Object datasets can not both be specified within aset of control cards. stmt

Explanation: The object library control cards FROMOBJDSN and TOOBJDSN are mutuallyexclusive with the load library control cards FROMLOADDSN and TOLOADDSN within agiven control data set.

Action: Processing terminates. The statement at which the error was detected is shown inthe second line of the error message.

User Response: Ensure that only object library control cards or only load library controlcards are used within a single control data set.

ATGY0023S Control: The cntl control statement is not supported when theExtProgram-Id option is used on the COBOL statement.

Explanation: The control statement cntl is incompatible with the ExtProgram-ID option.



ATGY0024S Control: Empty control file data set.

Explanation: The control file data set (CACTL) exists, but is empty.


User Response: Check that the correct CACTL data set is specified.

ATGY0025S Control: No compilation unit statement found (COBOL, PL/I, ...). Nooutput will be generated.

Explanation: The specified control file data set (CACTL) does not contain any compilationunit statements (COBOL, PL/I, etc.).


User Response: Ensure that the CACTL contains at least one compilation unit statement.

ATGY0026S The warp value for multiply and divide cannot exceed 10 digits stmt.

Explanation: The warp value for multiplication and division can not be longer than tendigits


User Response: Ensure that the warp value is ten digits or less.



ATGY0028S Control: Error at line lll in the control file.control_file_statementReturn Code= rc

Explanation: The indicated control file statement at the indicated line in the control file isinvalid.


User Response: Correct the indicated statement.


ATGZ0001I � ATGZ0006S

ATGZ: CommonThese following messages are common across most areas of CA, DA, and UTAand can be issued by many of the functions:

ATGZ0001I function is starting

Explanation: The specified function is starting.

Action: The function begins execution


ATGZ0002I function is verifying your parameters

Explanation: The specified function is verifying the parameters are correct.

Action: The function continues.


ATGZ0003I function is done.

Explanation: The specified function has completed.



ATGZ0004I Data saved data

Explanation: The specified data has been saved.



ATGZ0005S Dataset dataset name not found

Explanation: The specified data set was not found.


User Response: Specify the name of an existing data set.

ATGZ0006S Unknown option

Explanation: An unknown option was encountered when trying to execute a function.





ATGZ0007I JCL submitted

Explanation: The JCL to execute the requested function has been submitted.

Action: A batch job is submitted and the function terminates.


ATGZ0008I Dataset dsn reset

Explanation: The specified control data set has been reset to the default values.



ATGZ0009S Copy error occurred trying to reset dataset dsn

Explanation: When trying to reset a control data set from the default template, an erroroccurred either reading the default template file SATGSAMP or writing to the user controlfile.


User Response: Ensure that the default template file SATGSAMP is available on thesystem and that the user control file that is to be reset can be written to.

ATGZ0010S Form frm not found.

Explanation: The control file template frm was not found.


User Response: Check that the Sample Dsn field under “General Defaults” in your userdefaults specifies the data set in which the control file templates have been installed.

ATGZ0011S option is not a valid option

Explanation: The specified option is invalid for this function.


User Response: Correct the option and retry the function.

ATGZ0012S Error rc allocating dsn

Explanation: An error occurred when trying to allocate the specified data set. The allo-cation return code is indicated by rc.


User Response: Determine the allocation error and retry the function. Ensure that datasets required for this function exist.



ATGZ0013I data

Explanation: This message displays information in support of the previous message.

Action: See the corresponding message.

User Response: See the corresponding message.

ATGZ0014S No output dataset specified

Explanation: The function requires the name of an output data set and none was specified.


User Response: Specify the name of a data set to contain output from the function.

ATGZ0015S Error processing input/output dataset dsn : message

Explanation: An error occurred processing the data set specified by dsn. Further informa-tion about the error is contained in message. For example, message may indicate a dataset or member not found.


User Response: Correct the specified error and retry the function.

ATGZ0016S Members specified but input not PDS

Explanation: A member has been specified for a data set that is not a partitioned data set.


User Response: Do not specify a member name or specify the correct data set.

ATGZ0017S Invalid operand operand

Explanation: An invalid operand has been specified.


User Response: Correct the error and retry the function.

ATGZ0018S Input is PDS but output is not

Explanation: You cannot place the members of a partitioned data set into a sequentialdata set. Both input and output files must be the same organization.


User Response: Specify a partitioned data set as the output data set.


ATGZ0019S � ATGZ0024S

ATGZ0019S Input is sequential but output is PDS

Explanation: The input is a sequential data set but the output is a partitioned data set andno member name has been specified.


User Response: Specify a sequential data set as the output data set or specify a membername.

ATGZ0020S Error rc from function

Explanation: The specified function returned the indicated return code.


User Response: Check for other error messages.

ATGZ0021S ISPF not active

Explanation: This function requires ISPF to execute.


User Response: Start ISPF and retry the function.

ATGZ0022S Operand operand of function is message

Explanation: The indicated operand for this function is incorrect. Further information is con-tained in message.


User Response: Correct the operand and retry the function.

ATGZ0023S operation is not currently supported

Explanation: The indicated operation for this function is not supported.


User Response: Specify a supported operation.

ATGZ0024S Error rc deleting dsn

Explanation: An error occurred when trying to delete the specified data set. rc containsthe return code from delete.





ATGZ0025S JCL submit error rc

Explanation: The TSO submit failed with rc=rc.



ATGZ0026I Performing File Tailoring step jcldsn

Explanation: File Tailoring is being performed for step step on data set jcldsn.



ATGZ0027S FTOpen error rc= rc

Explanation: The FTOpen failed with rc=rc.



ATGZ0028S FTIncl error rc= rc

Explanation: The FTIncl failed with rc=rc.



ATGZ0029S FTClose error rc= rc

Explanation: The FTClose failed with rc=rc.



ATGZ0030S Unable to alloc ddname dataset dsname

Explanation: The TSO alloc for ddname and dsname failed.



ATGZ0031S Unable to read ddname dataset dsname

Explanation: Unable to read dsname via ddname.





ATGZ0032S Unable to write ddname dataset dsname

Explanation: Unable to write dsname via ddname.



ATGZ0033S DD not found ddname

Explanation: DD ddname not found allocated.



ATGZ0034S ISPExec Error command rc= rc

Explanation: ISPExec Command command failed with rc=rc.



ATGZ0035S Member in use member dsname

Explanation: Member member of data set dsname is already in use.



ATGZ0036S Member not found member dsname

Explanation: Member member of data set dsname could not be found.



ATGZ0037S DA and UTA may not be enabled together

Explanation: The Enable DA and Enable UTA process options on the Create JCL forSetup panel or the Create JCL to Start the Monitor panel cannot be set to Yes at the sametime.


User Response: Enable only one (or neither) of these options.



ATGZ0038S Data set dataset name has a DCB characteristic of invalid value, but itshould be valid value

Explanation: The specified data set name has a DCB characteristic (such as LRECL) ofinvalid value. The JCL created expects this data set to be preallocated and therefore cannotchange its DCB characteristics.


User Response: Reallocate dataset name with a DCB characteristic of valid value.

ATGZ0039I Reset of dataset cntl canceled

Explanation: The reset of the control file was canceled by the user.



ATGZ0040S Invalid invocation: Missing or invalid operand

Explanation: A required operand was missing, or an invalid operand was specified in aprogram invocation.



ATGZ0041S Dataset dsName not found

Explanation: The data set dsName was not found.


User Response: Correct the data set name and restart.

ATGZ0042S Unable to create dataset dsName

Explanation: The program was unable to create the data set dsName.


User Response: Check for other messages or data set allocation or space problems, orcontact your systems programmer.

ATGZ0043S Dataset dsName has a bad DSORG

Explanation: The specified data set has the wrong DSORG.


User Response: Specify a data set that has the correct organization for the function.


ATGZ0044S � ATGZ0050I

ATGZ0044S Unable to alloc import dataset dsn

Explanation: The import defaults data set could not be allocated.

Action: Defaults terminates.

User Response: Ensure the import defaults data set is accessible and the name is correct.

ATGZ0045S Unable to read import dataset dsn

Explanation: The import defaults data set could not be read.


User Response: Ensure the import defaults data set is accessible and is the proper format.

ATGZ0046S Unable to alloc export dataset dsn

Explanation: The export data set to contain the ATC defaults could not be allocated.


User Response: Ensure the export defaults data set is accessible and the name is correct.

ATGZ0047S Unable to write export dataset dsn

Explanation: The export defaults data set could not be written.


User Response: Ensure the export defaults data set is accessible and is the proper format.

ATGZ0048I ATC ISPF variables saved

Explanation: The ISPF variables have been saved.

Action: Defaults continues.


ATGZ0049I ATC ISPF variable edit canceled

Explanation: The ISPF variables edit has been cancelled



ATGZ0050I ATC ISPF variables reset from system defaults

Explanation: The ISPF variables have been reset to the system defaults.





ATGZ0051I ATC ISPF variables imported from user dataset

Explanation: The ISPF variables have been imported from your import data set.



ATGZ0052I ATC ISPF variables exported to user dataset

Explanation: The ISPF variables have been exported to your export data set.



ATGZ0053S Unknown command cmd

Explanation: An unknown command was encountered when trying to execute defaults.



ATGZ0054S ATC incorrectly installed. ATGStart not modified.

Explanation: The ATC installation is not complete. The required modifications of theATGStart exec were not done.


User Response: Have your systems programmer make the required edits to the ATGStartexec.

ATGZ0055S Required Dataset dsName not found.

Explanation: The specified required dataset was not found.


User Response: Correct the data set name if you specified it, otherwise contact yourinstaller or systems programmer.



ATGZ0056S Unable to LIBDEF library dsName

Explanation: The specified data set dsName could not be LIBDEFed to the specifiedlibrary.


User Response: Contact your installer or systems programmer.

ATGZ0057S Unable to ALTLIB APPLICATION type dsName.

Explanation: The specified data set could not be accessed via an ALTLIB command.



ATGZ0058I JCL generation canceled

Explanation: Errors were found before JCL generation which precluded it from being gen-erated.

Action: Generation of the JCL was not done.

User Response: Correct the errors indicated by previous messages and re-run.

ATGZ0059I You must link the instrumented objects into executables afterrunning Setup JCL

Explanation: The instrumented object modules must be linkedited before executing theprogram.


User Response: Perform the required linkedit prior to execution.

ATGZ0060S INTERNAL SOFTWARE ERROR: Literal lll was not found.

Explanation: An internal software error has occurred.



ATGZ0061S Return code rc from IEANTCR creating Name/Token pair forNATLANG.

Explanation: The indicated return code was received from the IEANTCR MVS service.




ATGZ0062S � ATGZ0066W

ATGZ0062S Return code rc from IEANTCR creating Name/Token pair forLOCALE.

Explanation: The indicated return code was received from the IEANTCR MVS service.



ATGZ0063W The value specified for the NATLANG option is invalid or disabled.

Explanation: The value specified for the NATLANG option is either not a supported valueor this specification has been disabled when ATC was installed at your installation.

Action: Processing continues using the default NATLANG specification.

User Response: Correct the indicated value.

ATGZ0064W The value specified for the Numeric Format suboption of theLOCALE option is invalid or disabled.

Explanation: The value specified for the third operand of the LOCALE option is either not asupported value or this specification has been disabled when ATC was installed at yourinstallation.

Action: Processing continues using the default LOCALE specification.


ATGZ0065W The value specified for the Date Format suboption of the LOCALEoption is invalid or disabled.

Explanation: The value specified for the first operand of the LOCALE option is either not asupported value or this specification has been disabled when ATC was installed at yourinstallation.



ATGZ0066W The value specified for the Time Format suboption of the LOCALEoption is invalid or disabled.

Explanation: The value specified for the second operand of the LOCALE option is eithernot a supported value or this specification has been disabled when ATC was installed atyour installation.




ATGZ0067W � ATGZ0078S

ATGZ0067W The value specified for the LINECOUNT option is not a positivedecimal number less than 99999.

Explanation: The value specified for the LINECOUNT option is either not a positivedecimal number or it is too large.

Action: Processing continues using the default LINECOUNT specification.


ATGZ0068W NATLANG, LOCALE, or LINECOUNT was specified as a parameter toan EXEC when already running under ATC ISPF.

Explanation: One of the indicated options was specified on an ATC command whilerunning under the ATGSTART command.

Action: Processing continues. The values specified or defaulted on the ATGSTARTcommand are used.

User Response: Invoke the ATC command without the specified option or invoke thecommand while not running under ATGSTART.

ATGZ0069E Invalid parameter: pppp

Explanation: The indicated parameter is not valid.


User Response: Correct the indicated parameter.

ATGZ0076E Text not found from iiii invocation of ATGO4 with parms pppp qqqq

Explanation: The iiii REXX EXEC could not access its literal text from the ATC REXXmessage module (ATGO4xxx).



ATGZ0077E Error RC= rc from IRXEXCOM via iiii invocation of ATGO4 with parmspppp qqqq

Explanation: The indicated return code was returned by IRXEXCOM while trying to setREXX variables for the iiii EXEC.



ATGZ0078S No parameters were specified on the invocation of iiii.

Explanation: The iiii REXX EXEC was invoked with no parameters. One or more parame-ters are required.


User Response: Correct the invocation of the EXEC.



ATGZ0079S Unable to emulate ADDRESS LINKMVS for program

Explanation: ATC could not find the indicated program in the search path for executedprograms.


User Response: If you are running in the TSO foreground, ensure that the ATC loadmodule library is specified correctly in ATC defaults. In TSO batch, ensure that the ATCload library is available via either the JOBLIB or STEPLIB.

ATGZ0080S Return code rc from IDENTIFY macro loading NLS message tableATGO4.

Explanation: The specified return code was issued by the MVS IDENTIFY macro whileloading the ATC message table.





Appendix B. ATC requirements and resources

This chapter lists the resources you need to Setup, execute, and run reports inCoverage Assistant, Distillation Assistant, and Unit Test Assistant. Data set attri-butes and data set definition (DD) names are also provided.

CA resourcesThe following system resources are required by CA.

SetupCA provides the following programs used during the Setup process:

� ATGOSETP and ATGOSETL create the breakpoint data file (BRKTAB). Theyrequire the following resources:

� ATGOZAPT modifies user object modules to insert breakpoints. It requires thefollowing resources:

Description Requirements

Disk space needed for the breakpointtable (BRKTAB) upon completion ofATGOSETP or ATGOSETL.

Determine the size of the BRKTAB data set inbytes using the following formula:128 + (64 + PA name length) × number ofPAs + 32 × number of breakpoints42 43

Disk space needed for the breakouttable (BRKOUT) upon completion ofATGOSETP or ATGOSETL.

128 + (number of breakpoints ÷ 8)


Storage allocated while ATGOZAPT isrunning

Size of object module

Disk space needed for modified objectmodule on completion of ATGOZAPT

Same size as unmodified object module

42 For COBOL, a PA is a paragraph; for PL/I, a PA is a procedure; for assembler, a PA is a CSECT.

43 For COBOL and PL/I, there is approximately one breakpoint per high-level executable statement. For assembler, there areapproximately two breakpoints per assembler instruction that change program flow (that is, branch instructions).

Appendix B. ATC requirements and resources 359

Monitor ECSA and SQA usageBecause the monitor must trace programs in any address space, it is loaded inECSA and SQA space and uses ECSA storage for tables. The monitor uses thefollowing system storage when it is installed:

Note: Each of these values is approximate.

� Fixed amount when monitor is installed/enabled:

ECSA 17368 bytesSQA 13208 bytes

� Each session started uses the following storage in ECSA:

– 96 bytes per program area (PA)– 52 bytes per breakpoint (BP)

Note: Each of the following is a PA:

– COBOL paragraph – PL/I procedure

– Assembler object module

Breakpoints are placed at the start of each high-level instruction for COBOL andPL/I and at conditional branches in high-level statements that can cause a changeof program flow (IF, DO WHILE, PERFORM, and others).

When variables are monitored for UTA/DA, about 132K of additional ECSA storageis used.

UTA/DA may have a few extra BPs per location where a variable is read.

If you want an exact count of BPs for any given session, count the number ofVERIFY or REPLACE statements in the RPTMSGS DDs in the Setup job, or issuea ATGSTATS command for a running monitor session and look at the BPSTOTALS column.

If you want an exact count of PAs for any given session, look at the last entry inthe Summary report Program Area Data section for the highest PA number. Thenumber of PAs in a session is also in the Annotated Listing report.

ReportsCA provides two reports programs:

� ATGOSMRY produces a Summary report.� ATGORPT produces an Annotated Listing report.


The reports programs require the following resources:


Storage needed by breakpoint table whileATGOSMRY is running

24 bytes per breakpoint

Disk space needed for the Summary report on com-pletion of ATGOSMRY

Negligible

Storage size of ATGORPT 22KB

Storage needed by breakpoint table while high-levelreport program is running


Storage needed by breakpoint table while assemblerreport program (ATGORPT) is running


Disk space needed for the Annotated Listing reporton completion of ATGORPT program

Size of listing

Data set attributesCA uses several data sets, whose requirements are as follows:

DDNAME LRECL BLKSIZE RECFM

BRKOUT 256 2790445 FB

BRKTAB 256 2790445 FB

CACTL 255 2799845 VB

LISTINB44 133 2793045 FBA

LISTINP 125 for PL/I compilersother than VisualAgeVersion 2 Release 2

2799845 VBA

132 for VisualAge PL/IVersion 2 Release 2compiler

2799845

LISTINA 133 for the High LevelAssembler

2793045 FBM

121 for Assembler H 2795145

LISTOUT 133 2793045 FBA

SUM 133 2793045 FBA

DDNAMEsFILEDEF Description

BRKOUT Contains CA test case results

BRKTAB Contains all breakpoint data used by the monitor program

CACTL Control file used for creation of CA runtime environment

LISTINB Input listing from COBOL

44 LRECL=121, BLKSIZE=12100 (or smaller) for OS/VS COBOL listings.

45 Any valid BLKSIZE can be used.


FILEDEF Description

LISTINP Input listing from PL/I

LISTINA Input listing from ASM

LISTOUT Output from ATGORPT program (Annotated Listing report)

SUM Output from ATGOSMRY program

DA and UTA resourcesThe following system resources are required by DA and UTA.

SetupDA and UTA provide three programs used during the Setup process:

� ATGOSETP and ATGOSETL create the breakpoint data file (BRKTAB). Theyrequire the following resources:


Disk space needed for the breakpoint table(BRKTAB) upon completion of ATGOSETPor ATGOSETL.

Determine the size of the BRKTAB data set in bytes using thefollowing formula:128 + (64 + PA name length) × number ofPAs + 32 × number of breakpoints42 43

Disk space needed for the variable table(VARCTL) upon completion of ATGOSETPor ATGOSETL.

64 bytes for each occurrence of a monitored variable in a state-ment

Disk space needed for the breakout table(BRKOUT) upon completion of ATGOSETPor ATGOSETL.

128 + (number of breakpoints ÷ 8)

� ATGOZAPT modifies user object modules to insert breakpoints. It requires thefollowing resources:


Storage allocated while ATGOZAPT isrunning

Size of object module

Disk space needed for modified objectmodule upon completion of ATGOZAPT

Same size as unmodified object module

� ATGOVARD creates the variable data file (DBGTAB). It requires the followingresources:


Disk space needed for the debug table(DBGTAB) upon completion of ATGOVARD

128 bytes + file name lengths + 56 bytes per variable + vari-able name length + 16 bytes per statement record


Monitor ECSA and SQA usageThis information is identical to the information in the Coverage Assistant topic“Monitor ECSA and SQA usage” on page 360.

Data set attributesDDNAME LRECL BLKSIZE RECFM

BRKOUT 256 2790445 FB

BRKTAB 256 2790445 FB

CACTL 255 2799845 VB

LISTINB44 133 2793045 FBA

DBGTAB 128 2790445 FB

VARCTL 64 2796845 FB

VARTAB 128 2790445 FB

VARID 255 2799845 VB

VARDATA 255 2799845 VB

DDNAMEsFILEDEF Description

BRKOUT Contains DA and UTA test case results

BRKTAB Contains all breakpoint data used by the monitor program

CACTL Control file used for creation of DA and UTA runtime environment

LISTINB Input listing from COBOL

LISTINP Input listing from PL/I

DBGTAB Variable read information and associated statement numbers

VARCTL Variable location information

VARTAB Variable data read during execution

VARID A table of data on the monitored variables defined in the controlfile. Also known as a Monitored Variables Report (MVR).

VARDATA A table of data for each time a monitored variable was readduring program execution. Also known as a Variable Data report(VDR).



Appendix C. DBCS support

This appendix describes ATC DBCS (double-byte character set)46 support. ATCsupport for DBCS varies among the tools as follows.

DBCS requirements for ATC compilers and assemblersThe compilers and assemblers supported by ATC implement DBCS support that isconsistent with the following rules:

1. DBCS characters are delimited by a leading Shift Out (0x0E) byte and a trailingShift In (0x0F) byte.

2. There must be an even number of bytes between Shift Out and Shift, whichhave values between 0x41 and 0xFE (except the DBCS space 0x4040).

3. In identifiers, all lowercase DBCS EBCDIC47 (0x42 in the first byte) will be con-verted to uppercase.

4. If an identifier is all DBCS EBCDIC, it will be converted to its SBCS (single-bytecharacter set) equivalent.

5. If an identifier contains one or more non-EBCDIC DBCS characters, the wholeidentifier will be converted to its DBCS representation.

6. Any DBCS, SBCS, or mixed DBCS and SBCS identifiers that convert to thesame identifier by the previous rules are considered equivalent.

7. The DBCS EBCDIC form of a character is only allowed in an identifier name ifthe SBCS version is allowed.

8. Each compiler/assembler has an option that tells the tool whether DBCS is tobe recognized as such (also referred to as enabled).

Notes:

a. In the previous list, identifier only pertains to COBOL and PL/I.b. PL/I allows DBCS EBCDIC characters in keywords.

DBCS support with CA, DA, and UTADBCS support is implemented in the following way by CA, DA, andUTA:

� CA, DA, and UTA control files and Targeted Summary control files will acceptDBCS identifiers and DBCS strings within comments.

� CA, DA, and UTA will provide DBCS support that is consistent with supportprovided by the compilers, except that the DBCS space will not be supportedwithin the control files except in comments.

� DBCS in control cards is always enabled.

46 Double-byte character set. A set of characters in which each character is represented by 2 bytes. Languages such as Japanese,Chinese, and Korean, which contain more symbols than can be represented by 256 code points, require double-byte charactersets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and pro-grams that support DBCS.

47 Extended binary-coded decimal interchange code. A coded character set of 256 8-bit characters.

Appendix C. DBCS support 365

� DBCS identifiers will be normalized according to the above rules before anycomparisons are performed.

� DBCS identifiers in all outputs will be in the normalized form.

� All control file keywords, delimiters, and MVS data set names must be enteredin SBCS.

� The COBOL LANGUAGE(JAPANESE) compiler option is allowed.

DBCS support with the SAA Comparison Analysis toolDBCS support is implemented in the following way by the SAA Comparison Anal-ysis tool:

� The Comparison Analysis tool accepts DBCS identifiers (COBOL and PL/I),DBCS keywords (PL/I ), DBCS strings, and DBCS comments within inputsource lines in the compare files.

� The seed list can contain DBCS entries.

� The Comparison Analysis tool provides DBCS support consistent with that pro-vided by the compilers.

� DBCS input identifiers and keywords are normalized according to the previousrules before any comparisons are done.

� DBCS identifiers and keywords in the output files are in the normalized form.

� If the input source contains DBCS characters, the DBCS support Enable fieldmust be set to Y.

� All control information and MVS data set names must be entered in SBCS.


Appendix D. Converting existing ATC systems and users toV2R1M3

You may have to make modifications when converting your existing ATC systemsand users to the current ATC release. The following information provides detailedconversion instructions based upon the release you are presently using.

| V2R1M0, V2R1M1,or V2R1M2 systems and users to V2R1M3| When converting from ATC release V2R1M0, V2R1M1, or V2R1M2 to release| V2R1M3, you must:

� Re-install the monitor authorized modules as described in “Setting up theauthorized data sets” on page 12.

� Re-install the monitor as described in “Installing and enabling the monitorSVCs” on page 14.

� Ensure that the required modules are installed in a linklist data set asdescribed in “Setting up the linklist data set” on page 12.

� Customize the common parameters as described in “Customizing commonparameters” on page 12 (if desired).

| � Generate your BRKTAB / BRKOUT files with V2R1M3 or later if you run| Summary with the Summary Assembler Stmts flag enabled (with a value of Y)| and you are analyzing assembler programs. Otherwise, the counts will be zero.| If you want to analyze assembler programs without re-generating your BRKTAB| / BRKOUT files, you must set the Summary Assembler Stmts flag to N.

V1RxMx systems and users to V2R1M3When converting from ATC release V1RxMx to release V2R1M3, note the fol-lowing:

� Running more than one release at the same time. V2R1M3 is intended to beinstalled in a separate code base so that you can have both releases of thetool available at the same time.

� V1RxMx and V2R1M3 monitors.

– Running the V1R2M0 monitor and the V2R1M3 monitor at the same time.

If you intend to run the V1R2M0 and V2R1M3 tools at the same time onthe same MVS image, you should apply the V1R2M2 monitor maintenancebefore installing the V2R1M3 monitor.

– Running the V1R2M4–V1R5M0 monitor and the V2R1M3 monitor at thesame time.

If you intend to run the V1R2M4–V1R5M0 and the V2R1M3 tools at thesame time on the same MVS image, you should do the following:

- Select the same two user SVC numbers for the two versions of thetools.

- Install/enable the older monitor SVCs first, and then the V2R1M3 SVCs(both via direct installation/enablement and both at IPL time).

Appendix D. Converting existing ATC systems and users to V2R1M3 367

Note: When you do this, a CASESSN command with the LEVEL operandwill show a V2R1M3 monitor version.

� Defaults changes. Redo any user-customized defaults. Note that the installa-tion default for Performance Mode has been changed from N (No) to Y (Yes).

� JCL. Regenerate any existing ATC-generated JCL. Update any user-generated JCL to match the V2R1M3 JCL requirements and module and execnames.

� Binary data sets. The binary data sets (BRKOUT, BRKTAB, DBGTAB,VARTAB, and VARCTL) are upwards compatible between V1R2M4–V1R5M0and V2R1M3. Block size restrictions have also been removed. Regenerateany binary data sets from V1R2M0. Also, reallocate VARCTL data sets with aLRECL of 64.

� New abend codes. If a breakpoint is not recognized by the monitor, the userprogram receives a 7C3 system abend rather than an 0C1 abend. If a break-point is found in storage protected memory, an 0C4 abend now occurs. If abreakpoint is executed when certain restrictive system modes are in effect, an0F8 abend now occurs. For more information, see Chapter 25, “Diagnosingmonitor problems” on page 261 and “Restrictions on types of programs thatcan be monitored” on page 236.

� New restrictions. For new restrictions related to programs running in read-only storage, see “Restrictions on types of programs that can be monitored” onpage 236.


Appendix E. Coverage Assistant FastPath

The Coverage Assistant FastPath provides a streamlined way to gather coverageinformation for your programs. FastPath condenses the process into three steps:

1. Quick Start

Quick Start combines the setup and start monitor steps into one step. For pro-grams consisting of one source file, you can enter all the required informationon the panels and eliminate the need for a control file.

2. Snapshot Summary

Snapshot Summary allows you to check your progress without disrupting yourtesting.

3. Quick Stop

Quick Stop stops the monitor session and automatically generates a Summaryreport. The report indicates the overall effectiveness of your test suite, and canhelp you decide what Targeted Summary or Annotated listing reports to gen-erate.

FastPath minimizes the steps required to run Coverage Assistant for the averageuser. Advanced users, or those with atypical situations may prefer to use thestandard panels in some cases.

To display the Coverage Assistant FastPath panel:

1. Select option 1 from the ATC Primary Option Menu. The Coverage, Distillationand Unit Test Assistant panel is displayed.

2. Select option 8. The Coverage Assistant FastPath panel, shown in Figure 109,is displayed.

Z [------------------------- Coverage Assistant FastPath -------------------------

Option ===>

1 Quick Start Create JCL for Quick Start

2 Snapshot Create JCL for Snapshot Summary

3 Quick Stop Create JCL for Stop & Summary


\ ]

Figure 109. Coverage Assistant FastPath panel

This panel's options are as follows:

Quick StartGenerates JCL to setup and start a monitor session.

SnapshotGenerates JCL to create a summary for a monitor session without stop-ping the session.

Quick StopGenerates JCL to stop a monitor session and generate a summaryreport.

Appendix E. Coverage Assistant FastPath 369

Creating Quick Start JCL from the panelsQuick Start combines the setup and start monitor session steps. Besides reducingthe number of steps involved with running ATC coverage, this also ensures thatyou start the monitor session with the most recent version of your input data sets.If your programs consist of a single object per load module, and you use the samemember name for the listings, object modules, and load modules, you avoidneeding a control file by providing all the required information directly from thepanels. For more complex situations, you can use a CA control file to drive QuickStart.

For the following cases, it may be more efficient to start and stop the monitorsession via the normal CA setup, start session, and stop session commands:

� Testing a large program that does not change over a period of time� Collecting coverage per test case

Quick Start always analyzes your listings or load modules to create a new break-pointed program and breakpoint data. You do not need to do this if your programdoes not change. For large programs that do not change, you can save time bynot doing this setup analysis via Quick Start.

If you want to collect coverage per test case (for example, to determine the mostefficient test case bucket), you can use the CA DATA and RESET commands aftereach test case. The Quick Stop command always stops the session and producesa Summary report. The Snapshot command produces a cumulative summary oftesting up to that point, but does not reset coverage statistics.

If you are instrumenting object modules, you must link them into executable loadmodules after running Quick Start and before running your tests. Also, if you areinstrumenting load modules in place (which is not recommended) you must ensurethat Quick Start did not previously instrument your load module.

To setup and start a monitor session to measure code coverage, select option 1from the Coverage Assistant FastPath panel. The Create JCL for Quick Startpanel, shown in Figure 110 on page 371, is displayed.


Z [ -------------------------- Create JCL for Quick Start ------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL

4 Parameters Quick Start Parameters


Session ID . . . . . . PBEGGS

Programming Language. . COBOL (ASM,COBOL,or PL/I)

CA Control File (optional):

Control File Dsn. . .

(If the Control File is specified, any program names below are ignored.)

Program Names:

Primary Program Name. COB02

Additional Programs . COB03

\ ]

Figure 110. Create JCL for Quick Start panel





ParametersDisplays a panel which allows you to set additional parameters used inthe JCL generation.

Session IDSpecifies a session ID for your session. This defaults to your TSO userID. Multiple testers can use the monitor simultaneously. For more infor-mation, see “Multiple user sessions” on page 231.

Programming LanguageEnter the programming language of your source code.



Control File Dsn (optional)Specifies the control file (CACTL) data set containing the locations ofthe listing files, the object or load module libraries, and the libraries tocopy the instrumented versions into, and specifies the members to beprocessed.


If you specify the Control File Dsn , the Primary Program Name willonly be used for generated program names if Use Program Name forFile Name (available on the Quick Start Parameters panel) is Yes, andQuick Start will ignore the Additional Programs field.

Primary Program NameSpecifies the name of a program monitored by Quick Start. Generateddata set names will also use this name if Use Program Name for FileName (available on the Quick Start Parameters panel) is Yes.

Note: The listing, object and load modules must all have the samemember name, and you must have only one object per load module inorder to run FastPath using program names. Otherwise, you must usea control file.

Additional ProgramsSpecifies other programs monitored by Quick Start.

Quick Start parametersThe Quick Start Parameters panel allows you to provide information on the datasets to be used for setup and the monitor session. If you do not specify a controlfile, some of the fields on this panel are required. If the fields are not filled in, thispanel will be displayed the first time you request JCL generation.

Z [---------------------------- Quick Start Parameters ---------------------

Command ===>

Enter END (to Exit and Save changes) or CANCEL (to Exit without saving)

Session ID . . . . . . PBEGGS

Programming Language. . COBOL (ASM,COBOL,or PL/I)

Object, Load, or Test . LOAD (OBJ, LOAD,or TEST)

Compiler Listing. . . . 'PBEGGS.SAMPLE.COBOLST'

Original Library. . . . 'PBEGGS.SAMPLE.OBJ'

Instrumented Library. . 'PBEGGS.SAMPLE.ZAPOBJ'

CA Control File:

Control File Dsn. . .

Use Program Name for File Name Yes (Yes]No) Program Name COB02


JCL Dsn . . . . . . . 'PBEGGS.SAMPLE.JCL(SCOB02)'

Breakpoint Table:

Breakpoint Table Dsn. 'PBEGGS.TEST.COB02.BRKTAB'

Monitor Output File:

Breakout Dsn. . . . . 'PBEGGS.TEST.COB02.BRKOUT'

\ ]

Figure 111. Quick Start Parameters panel



Session IDSpecifies a session ID for your session. This defaults to your TSO userID. Multiple testers can use the monitor simultaneously. For more infor-mation, see “Multiple user sessions” on page 231.

Programming LanguageEnter the programming language of your source code.



Object, Load, or TestSpecifies the type of setup to be done. You instrument object modules,load modules,48 or COBOL load modules compiled with the TEST com-piler option. If you instrument object modules, you must link the instru-mented objects into executable load modules after running Quick Start,and before running your tests.

Note: This field is required if you do not specify the Control File Dsn .

Compiler ListingSpecifies the data set containing the compiler listings for the programsto be monitored. If you specify the COBOL TEST compiler option,Quick Start ignores this field.


Original LibraryDefines the data set containing the object or load modules to be instru-mented. This field is only required if instrumenting object modules. Ifinstrumenting load modules in place (this is not recommended) you canleave this field blank, and enter the data set containing the load modulesin the Instrumented Library field.


Instrumented LibraryDefines the data set where ATC stores the instrumented copies of theobject or load modules.


Control File Dsn (optional)Specifies the control file (CACTL) data set containing the locations ofthe listing files, the object or load module libraries, and the libraries tocopy the instrumented versions into, and specifies the members to beprocessed.

If you specify the Control File Dsn , the Object, Load, or Test; Com-piler Listing ; Original Library ; and Instrumented Library fields will beignored.

48 Instrumenting of load modules is not supported for VisualAge PL/I Version 2 Release 2.


Use Program Name for File NameEnter Yes, if you want to construct data set names from the default high-level qualifier, the specified program name, and the default low-levelqualifier for the following datasets:

� JCL Dsn� Breakpoint Table Dsn

� Breakout Dsn

When you press Enter, the affected data set names on the panelchange automatically. The normal CA procedure uses the programname to construct the data names.

Program NameThe name to use for CA files if you enter Yes in the Use ProgramName for File Name field. Note that this can be any valid name. Itdoes not have to be the name of any of your programs. Names of thefollowing form are created:


'proj_qual.program_name.file_type'For example: 'YOUNG.TEST.COB01.BRKTAB'


'proj_qual.file_type(program_name)'For example: 'YOUNG.TEST.BRKTAB(COB01)'


Note: If the Use Program Name for File Name field is set to Yes,then the member name or program name qualifier of the data set will beTxxxxxxx, where xxxxxxx is the last seven characters of the programname.


Breakout DsnName of the BRKOUT data set created during Execution and used bythe summary and report programs.


Creating Snapshot Summary JCL from the panelsA Snapshot Summary is a Summary report generated against the data collected bya running monitor session, without stopping the session. You can use SnapshotSummaries to check the status of your testing efforts. By issuing the ATGRESETcommand after each Snapshot Summary, you can generate independent Summaryreports for each test in your test suite without stopping and restarting the monitor.Otherwise, each Summary will be the cumulative result of all testing since themonitor session was started.

Note: Snapshot Summary does not save the coverage data for a snapshot. If youwish to save the coverage data, particularly if you are issuing ATGRESET, youshould use the snapshot command from the Control the CA/DA/UTA Monitor panelto generate a BRKOUT data set containing the raw coverage data.

To create JCL to generate a Snapshot Summary, select option 2 from the Cov-erage Assistant FastPath panel. The Create JCL for Snapshot Summary panel,shown in Figure 112, is displayed.

Z [----------------------- Create JCL for Snapshot Summary -----------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL


Session ID. . . . . . . PBEGGS


Input Files:



JCL Dsn . . . . . . . 'PBEGGS.SAMPLE.JCL(TCOB02)'


Type. . . . . . . . . INTERNAL (Internal]External)

Report Dsn . . . . . 'PBEGGS.SAMPLE.COB02.SUMMARY'


\ ]

Figure 112. Create JCL for Snapshot Summary panel





Session IDSpecifies the session ID for your session. This defaults to your TSOuser ID. This defaults to your TSO user ID. Multiple testers can use


the monitor simultaneously. For more information, see “Multiple usersessions” on page 231.


When you press Enter, the file names on the panel change automat-ically. The normal CA procedure uses the program name to constructthe data set names.

Program NameName to use for CA files if you enter Yes in the Use Program Name forFile Name field. Note that this can be any valid name. It does not haveto be the name of any of your programs. Names of the following formare created:










Creating Quick Stop JCL from the panelsQuick Stop allows you to generate JCL to stop a monitor session and generate aSummary report in one step. This is convenient since you will normally want to runa Summary report on the overall coverage, even if you intend to run one or moreTargeted Summary reports on the gathered data later. You do not need to useQuick Start in order to use Quick Stop.

To create JCL to stop a monitor session and generate a Summary report, selectoption 3 from the Coverage Assistant FastPath panel. The Create JCL for Stop &Summary panel, shown in Figure 113, is displayed.

Z [------------------------ Create JCL for Stop & Summary ------------------------

Option ===>


2 Edit Edit JCL

3 Submit Submit JCL

4 Parameters Quick Stop Parameters




Output Summary Dsn:



\ ]

Figure 113. Create JCL for Stop & Summary panel


GenerateGenerates JCL from the parameters you specified on the panel.



ParametersDisplays a panel which allows you to set additional parameters used inthe JCL generation.

Session IDSpecifies the session ID for your session. Multiple testers can use themonitor simultaneously. For more information, see “Multiple usersessions” on page 231.



When you press Enter, the file names on the panel are changed auto-matically. The normal CA procedure uses the program name to con-struct the data set names.






Report DsnThe name of the data set to contain the Summary report.

Quick Stop ParametersThe Quick Stop Parameters panel allows you to specify additional information onthe data sets to be used for the output data and report, as well as specify the typeof Summary report produced.

Z [---------------------------- Quick Stop Parameters ----------------------------

Command ===>

Enter END to Exit and Save changes



Input Files:


Breakout Dsn. . . . . 'PBEGGS.TEST.COB02.BRKOUT'


JCL Dsn . . . . . . . 'PBEGGS.SAMPLE.JCL(TCOB02)'


Type. . . . . . . . . INTERNAL (Internal]External)



\ ]

Figure 114. Quick Stop Parameters panel



Session IDSpecifies the session ID for your session. This defaults to your TSOuser ID. Multiple testers can use the monitor simultaneously. For moreinformation, see “Multiple user sessions” on page 231.


When you press Enter, the file names on the panel change automat-ically. The normal CA procedure uses the program name to constructthe data set names.







Breakout DsnName of the BRKOUT data set created during Execution and used bythe summary and report programs.






Appendix F. Parameters Common To Multiple Routines

The parameters described in this appendix can be specified it several different con-texts:

� They can be specified as part of a blank delimited PARM string for various ATCprograms.

� They can be specified as part of a comma delimited PARM string for variousATC programs.

� They can be specified as blank delimited operands on various TSO commandssuch as ATGSTART.

When these parameters are passed to ATC programs via the PARM field, anyparameters specific to a particular routine must precede the parameters describedin this section. These specific parameters must generally appear in a specific orderas described in the documentation for that routine.

The following general syntax rules apply to the common parameters described inthis section (but do not necessarily apply to parameters specific to a routine):

1. Parameters may appear in any order.

2. When passed as operands to the following commands or as parameters to thefollowing commands and programs, each parameter must be separated frompreceding and following parameters by one or more blanks:

� ATGOPVAR � ATGOVARD � ATGOSMRY � ATGORPT � ATGRBPDS � ATGSESSN � ATGSLIST � ATGSTART � ATGSTATS � ATGSTOP

When passed as parameters to the following commands and programs, eachparameter must be separated from preceding and following parameters by acomma:

� ATGOMCMD � ATGOMVAR � ATGOSETL � ATGOSETP � ATGOZAPL � ATGOZAPT � ATGPROFF � ATGPRON � ATGQUIT � ATGRESET � ATGRIDAD � ATGRVADS � ATGSNAP

Appendix F. Parameters Common To Multiple Routines 381

3. Each parameter is identified by a keyword. The keyword may be abbreviatedby shortening it to the minimum number of characters required to make itunique from other valid keywords.

4. If a value is expected for the keyword, the value must be enclosed in paren-thesis following the keyword.

5. If multiple values for a keyword, each of the values must be separated bycommas.

6. Blanks may appear before or after commas and / or parenthesis.

The following keywords and associated values can be specified whereever thecommon_parameters are allowed. If one or more of these keywords are not speci-fied, a default value is used. Note, however, that although the standard defaultvalues are indicated below, these defaults may be changed when ATC is installedon your machine.

Note that if any of these parameters are specified on an invocation of ATGSTART,these specifications are remembered by ATGSTART and become the default if theparameters are not specified on subsequent invocations of ATGSTART. In addi-tion, when any of the other TSO commands are invoked under an ISPF sessioninitiated by ATGSTART, these parameters cannot be specified on the TSO com-mands. In this case, the commands use the values specified or defaulted on theATGSTART invocation. Similarly, when any of the monitor commands are exe-cuted under ISPF but not under ATGSTART, they remember these specificationsand use them as the default the next time one of the monitor commands is rununder ISPF.

Whenever one of the following options is allowed, all are accepted and used in anyappropriate situation. However, the corresponding specification will only be usedwhen applicable. For example, all operands of LOCALE will be accepted even ifthe program never displays a date or time value.

NATLANGThe NATLANG option specifies that national language to be used to displayprogram messages. The syntax of this option is:

┌ ┐─ENU───────── ──NATLANG──(─ ──┴ ┴─language_id─ ─)─────────────────────────────────────── �

where

language_idis one of the following id's:

ENU English


LOCALEThe LOCALE option specifies the way dates, times, and numbers are to be for-matted. The syntax of this option is:

┌ ┐─1──────── ──LOCALE──(─ ──┼ ┼────────── ────────────────────────────────────────────── └ ┘─date_fmt─

─ ──┬ ┬───────────────────────────────────────── ─)──────────────────────── � │ │┌ ┐─1──────── └ ┘ ─,─ ──┼ ┼────────── ──┬ ┬──────────────────── └ ┘─time_fmt─ │ │┌ ┐─1─────────── └ ┘ ─,─ ──┼ ┼───────────── └ ┘─numeric_fmt─

where

date_fmtspecifies how dates are to be formatted. In addition to the following predefinedformats, additional installation specific formats may be available. See yourlocal installer for information about installation specific date formats.

1 MM/DD/YYYY

2 MM/DD/YY

3 DD/MM/YYYY

4 DD/MM/YY

5 YY.DDD

6 YYYY.DDD

7 YYYY/MM/DD

8 YYYYMMDD

9 June DD, YYYY

10 Jun DD, YYYY

11 DD-Jun-YYYY

12 DD June YYYY

13 JUNE DD, YYYY

14 JUN DD, YYYY

15 DD-JUN-YYYY

16 DD JUNE, YYYY

time_fmtspecifies how time values are to be formatted. In addition to the following pre-defined formats, additional installation specific formats may be available. Seeyour local installer for information about installation specific date formats.

1 HH:MM:SS

2 HH:MM:SSam

3 HH:MM:SSAM

Appendix F. Parameters Common To Multiple Routines 383

numeric_fmtspecifies how numbers are to be formatted. In addition to the following prede-fined formats, additional installation specific formats may be available. Seeyour local installer for information about installation specific date formats.

1 1,234,567.89

2 1.234.567,89

LINECOUNTThe LINECOUNT option controls the number of lines (including any headings)printed on a page. Note that not all output files contain carriage control charactersand some files that do contain control characters are not created with pages of anypredetermined size. Hence, not all output files will be governed by this option.

┌ ┐─66────── ──LINECOUNT──(─ ──┴ ┴─line_ct─ ─)───────────────────────────────────────── �

where

line_ctis a decimal number less than 99999.

ExamplesThe following examples show how these same parameters might be passed to theATC routine ATGOSMRY:

1. This example requests LOCALE Date Format 2, the default LOCALE TimeFormat, LOCALE Numeric Format 2, and a LINECOUNT of 72.

//STEP1 EXEC PGM=ATGOSMRY,PARM='I N N LOC(2,,2) LINEC(72)'

2. This example requests National Language ENU and LOCALE Time Format 2.

//STEP1 EXEC PGM=ATGOSMRY,PARM='I N N NATL(ENU) LOCALE(,2)'

Finally, these examples show how these same parameters might be passed toATGSTART:

1. This example requests LOCALE Date Format 2, the default LOCALE TimeFormat, LOCALE Numeric Format 2, and a LINECOUNT of 72.

ATGSTART LO(2,,2) LINE(72)

2. This example requests National Language ENU and LOCALE Time Format 2.

ATGSTART NATL(ENU) LOCALE(,2)


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in othercountries. Consult your local IBM representative for information on the products and ser-vices currently available in your area. Any reference to an IBM product, program, or serviceis not intended to state or imply that only that IBM product, program, or service may beused. Any functionally equivalent product, program, or service that does not infringe anyIBM intellectual property right may be used instead. However, it is the user's responsibility toevaluate and verify the operation of any non-IBM product, program, or service.

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

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any other countrywhere such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICA-TION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes areperiodically made to the information herein; these changes will be incorporated in new edi-tions of the publication. IBM may make improvements and/or changes in the product(s)and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience onlyand do not in any manner serve as an endorsement of those Web sites. The materials atthose Web sites are not part of the materials for this IBM product and use of those Websites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appro-priate without incurring any obligation to you.

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

IBM CorporationJ74/G4555 Bailey AvenueP.O. Box 49023San Jose, CA 95161-9023U.S.A.

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

Notices 385

The licensed program described in this document and all licensed material available for it areprovided by IBM under terms of the IBM Customer Agreement, IBM International ProgramLicense Agreement or any equivalent agreement between us.

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

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustratesprogramming techniques on various operating platforms. You may copy, modify, and dis-tribute these sample programs in any form without payment to IBM, for the purposes ofdeveloping, using, marketing or distributing application programs conforming to the applica-tion programming interface for the operating platform for which the sample programs arewritten. These examples have not been thoroughly tested under all conditions. IBM, there-fore, cannot guarantee or imply reliability, serviceability, or function of these programs. Youmay copy, modify, and distribute these sample programs in any form without payment to IBMfor the purposes of developing, using, marketing, or distributing application programs con-forming to IBM's application programming interfaces.

TrademarksThe following terms are trademarks of International Business Machines Corporation in theUnited States, or other countries, or both:

BookManager CICS DFSMS/MVS IBM Language Environment Library Reader MVS MVS/ESA OS/390 VisualAge

Other company, product, and service names may be trademarks or service marks of others.


Glossary

This glossary defines terminology and acronyms uniqueto this document or not commonly known.

AAnnotated Listing report . An annotated listing thatshows which code statements have been executed.

APF-authorized . Authorized program facility.

ATGOMCMD. The Coverage Assistant step that moni-tors your program while it is being executed to collecttest case coverage statistics.

ATGOZAPT . A program that uses breakpoint data tomodify object modules by inserting breakpoints.

ATGQUIT. An execution monitor command that func-tions like the ATGSTOP command. However, unlikethe ATGSTOP command, ATGQUIT does not writeoutput to disk. Contrast with ATGSTOP.

ATGRBPDS . An execution monitor command that dis-plays the status of breakpoints.

ATGRESET. An execution monitor command thatresets all statistics in the current monitor session tozero.

ATGRIDAD . An execution monitor command thatallows you to add a unique test case ID.

ATGSESSN. An execution monitor command that dis-plays a list of the current active sessions.

ATGSLIST . An execution monitor command thatallows you to select listings for which to display statis-tics.

ATGSNAP . An execution monitor command that writesthe coverage statistics (BRKOUT) to the file name spec-ified on the panel.

ATGSTATS . An execution monitor command thatallows you to select the session ID, listing number, andprogram areas (PAs) for which you want statistics dis-played.

ATGSTOP. An execution monitor command that writescurrent statistics to disk and terminates the monitorsession. Contrast with ATGQUIT.

Bbackground execution . The execution of lower-priority computer programs when higher-priority pro-grams are not using the system resources. Contrastwith foreground execution.

BP. Breakpoint.

breakpoint (BP) . The practice of replacing an instruc-tion op code with a user SVC instruction so that theATC monitor gets control from the operating system.

breakpoint library . A library (partitioned data set) ofbreakpoint data for your listings. Each memberincludes the data for one listing.

BRKOUT . The DDNAME of the file of test case cov-erage results (breakpoint output) created during Cov-erage Assistant Execution and used during CoverageAssistant Report.

BRKTAB . The DDNAME of the file of breakpoint data(breakpoint table) created during Coverage AssistantSetup and used during Coverage Assistant Execution.

CCACTL . The DDNAME of the Coverage Assistant,Distillation Assistant, and Unit Test Assistant control file.

Change Validation report . A report that allows you toverify changes found in a SuperC comparison aschecked against your seed list in order to make surethat only planned changes were made and that all seedvariables were changed.

code coverage . A measurement of the number ofcode statements that have been executed.

Combined Variable Data report (CVDR) . A table ofdata that is read during execution. A CVDR includesreferences to the monitored variable report (MVR) forvariable identification and a fully-qualified variable namefor each entry.

compile unit (CU) . The programs contained withinone compiler listing.

control file . A file that contains information describingthe compile units to be analyzed, the file that is to bemonitored, and the values of the variables to berecorded. Coverage Assistant, Distillation Assistant,and Unit Test Assistant share the same control file.

CU. Compile unit.

Glossary 387

CVDR. Combined Variable Data report.

DDBCS. double-byte character set.

DBGTAB . Debug table. The DDNAME of a file gener-ated by the Setup step when Distillation Assistant orUnit Test Assistant is enabled. The DBGTAB is usedduring the Distillation Assistant logical distillation stepand the Unit Test Assistant Report step. For a standardcoverage run, this file contains no useful data and itsDD card is coded DD DUMMY.

ddname . The symbolic representation for a nameplaced in the name field of a DD statement.

distillation . The reduction of a data set to theminimum size that provides the same test coverage asthe complete data set.

Double-byte character set . A set of characters inwhich each character is represented by 2 bytes. Lan-guages such as Japanese, Chinese, and Korean, whichcontain more symbols than can be represented by 256code points, require double-byte character sets.Because each character requires 2 bytes, the typing,display, and printing of DBCS characters requires hard-ware and programs that support DBCS. Contrast withsingle-byte character set.

dsname . Data set name.

dynamic data warping . The process of changing pre-defined variable values during runtime. Dynamic datawarping might be used to age, or warp, dates in inputdata files, for example. Contrast with file warping.

EEBCDIC. Extended binary-coded decimal interchangecode. A coded character set of 256 8-bit characters.

Ffile warping . The process of statically modifying pre-defined variables in copies of VSAM or QSAM inputfiles to simulate input conditions for testing. Filewarping might be used to clear fields in test copies ofproduction input files for privacy or security reasons.Contrast with dynamic data warping.

foreground execution . The execution of a computerprogram that preempts the use of computer facilities.

Iinput master data set . A data set to be distilled intoan output master data set by physical distillation.

Jjcldsn . JCL data set name.

Kkey . One or more characters used to identify therecord and establish the order of the record within anindexed file.

key list . A list of characters used to identify the recordand establish the order of the record within an indexedfile.

LLISTINA . DDNAME of the Assembler H or High LevelAssembler listing file used in Setup or Reports.

LISTINB . DDNAME of the COBOL assembler listingfile used in Setup or Reports.

LISTINP. DDNAME of the PL/I assembler listing fileused in Setup or Reports.

logical distillation . Instrumenting your object codeand executing the instrumented code under theDistillation Assistant monitor. As the instrumented codereads records from the specified input master data set,the monitor determines which keys in the input masterdata set caused new code coverage in the instrumentedcode. The list of these keys is then saved for the phys-ical distillation step.

logical key . As used in reference to distillation, alogical key is simply a field within a data record that canbe used to identify the record. This field may, or maynot, be identified as a physical key to the file system ordatabase manager involved in actually reading therecord.

Multiple records can have the same logical key. In thiscase, it is assumed that all records with this key arerequired to obtain the necessary code coverage.


MMillennium Language Extensions (MLE) . A compiler-assisted solution for the Year 2000 problem. Availablefor IBM's COBOL and PL/I compilers.

MLE. Millennium Language Extensions.

monitor . The program (ATGOMONS) that measurestest case coverage during execution of your programs.

monitored variable report (MVR) . A table of moni-tored variables and their read specifications.

monitor session . A distinct invocation of the monitorprogram.

MVR. Monitored variable report.

Oop code . Operation code. A code for representing theoperation parts of the machine instructions of a com-puter.

PPA. program area.

physical distillation . This step consists of creating anew master data set by reading the list of keysproduced in the first step (logical distillation) and theinput master data set. The new master data set con-sists of only those records in the input master data setwhose logical key appears in the list of keys.

Program area (PA) . Each specific PA contains all ofthe breakpoints for one COBOL paragraph, PL/I block,or assembler listing.

QQSAM. queued sequential access method.

Queued sequential access method (QSAM) . Anextended version of the basic sequential access method(BSAM). When this method is used, a queue is formedof input data blocks that are awaiting processing or ofoutput data blocks that have been processed and areawaiting transfer to auxiliary storage or to an outputdevice.

Rreentrant program . A computer program that may beentered at any time before any prior execution of theprogram has been completed.

Report . The Coverage Assistant job that produces thesummary and Annotated Listing report reports after atest case run.

SSAA Comparison Analysis tool . Generates aChange Validation report and a prototype CoverageAssistant Targeted Summary control file using acompare file generated by the SuperC Compare Utilityand a list of seed variables that you want to monitor.

SBCS. Single-byte character set.

seed list . A list of seed variables.

seed variable . A variable name used as input to theSource Audit Assistant comparison analyzer. This isgenerally a variable that was identified as one thatwould be involved in changes.

session . A distinct invocation of the monitor program.

session ID . The identification of your session to themonitor program. This defaults to your TSO user ID.

Setup . The Coverage Assistant job that analyzes yourassembler listings in order to produce a table of break-point data and insert breakpoints into disk resident pro-grams.

single-byte character set (SBCS) . A character set inwhich each character is represented by a one-bytecode. Contrast with double-byte character set.

SQA. system queue area.

Summary report . A Coverage Assistant report thatgives statistics on the coverage of all program areas(PAs) during the test run.

Summary report . A Coverage Assistant report thatprovides the summary statistics for PAs.

supervisor call (SVC) . A request that serves as theinterface into operating system functions, such as allo-cating storage. The SVC protects the operating systemfrom inappropriate user entry. All operating systemrequests must be handled by SVCs.

SVC. Supervisor call.

Glossary 389

System queue area (SQA) . An area of MVS storageused for running authorized programs or for storageallocation.

Ttargeted summary . A measurement of the number ofspecific code statements and/or variables that havebeen executed.

Targeted Summary report . A report that allows you totarget certain statements and/or COBOL or PL/I vari-ables. The format of a Targeted Summary report isidentical to the format of a Summary report, except thatthe content is restricted to statements that you specify.(You can specify a statement number, or you canspecify all statements that reference specific COBOL orPL/I variables.)

Uunit testing . A method of capturing and logging valuesassigned to selected variables in your applicationprogram at selected points during their execution.

user defaults . Default settings that only affect yourpersonal ATC sessions. You can change these defaultsusing the ATC panels. Contrast with site defaults.

VVARCTL . A file used by Distillation Assistant and UnitTest Assistant that lists variable locations where theinput data set is read by the monitor.

Variable Data report (VDR) . A table of data that isread during execution with references to the monitoredvariable report (MVR) for variable identification.

VDR. Variable Data report.

virtual storage access method (VSAM) . An IBMlicensed program that controls communication and theflow of data in an SNA network. It provides single-domain, multiple-domain, and interconnected networkcapability.

VSAM. Virtual storage access method.

Wwarping . The process of statically (file warping) ordynamically (dynamic data warping) modifying prede-fined variables to simulate input conditions for testing.See dynamic data warping and file warping.


Index

Aage, data 145Annotated Listing report

creating JCL for an Annotated Listing report 52creating specific 84displaying execution counts 85

debug mode 85frequency count mode 85

PL/I 55reducing size 84

annotation symbolsAnnotated Listing report 57, 77changes with Performance Mode 86changes with the EXTPROGRAM-ID option 87

APF authorized programsuser access prohibited 13user access to 13

assembler options required 214ATC defaults, modifying 19ATGO3ENU 13ATGO4ENU 12ATGOMCMD 13ATGOMVAR 13ATGONIOP 12ATGONIRL 12ATGPROFF 241ATGPRON 242ATGQUIT 243ATGRBPDS 244ATGRESET 248ATGRIDAD 249ATGRVADS 250ATGSESSN 252ATGSLIST 253ATGSNAP 255ATGSTART 26

parameters 381ATGSTATS 257ATGSTOP 259authorized data sets 12, 261

Bbranch, conditional

breakpoints 247, 259coverage 67, 76

distilled data set 125samples 86statistics 71

instruction 77, 247

breakpoint data 100breakpoints

definitionCA 39DA 112UTA 149

displaying status using ATGRBPDS 244errors executing 261purpose in execution step

CA 39DA 112UTA 149

BRKOUTdefinition 39specifying file name with ATGSNAP command 255

BRKTABcreating 217definition 39, 112

buffer monitor 237

CC/370 access 25CACTL

See control filecoder, definition 99Combine edit screen 103Combine JCL, creating 102Combine panel 102Combined Variable Data report 171commands

issuing 239monitor 244parameters 239—260

common CA, DA, and UTA informationcommands

ATGPROFF 241ATGPRON 242ATGQUIT 243ATGRBPDS 244ATGRESET 248ATGRIDAD 249ATGRVADS 250ATGSESSN 252ATGSLIST 253ATGSNAP 255ATGSTATS 257ATGSTOP 259issuing commands 239

control file 187—210monitor

commands 239—260execution 227—237

Index 391

common CA, DA, and UTA information (continued)monitor (continued)

problems 261setup 211—226

common parameterscustomizing 12

compiler optionsCA 211CA targeted coverage 214DA and UTA 214

compilers supportedCA 35DA 107UTA 145

conditional branchbreakpoints 247, 259coverage

distilled data set 125samples 86statistics 76suppression 71

instructionAnnotated Listing report 77fields 247symbols 50

conditional branch coverageoverhead 235poor performance when measuring 263suppressing with Performance Mode 71

control fileCA

ASM sample 56COBOL sample 46editing the control file 61PL/I sample 54Targeted Summary control file 89

combined 187common CA, DA, and UTA 187

contents 189statement syntax 190

DACOBOL example 120editing the control file 129PL/I example 120

UTACOBOL example 157editing 165

warp 175, 183coverage

conditional branch, measuring 263overhead 235suppressing conditional branch 71

customizing ATC 19

DDA Setup 112data set, site defaults 17data sets

attributes 361, 363installation 11

data warpingconversion tables 206statement 204

date format, specifying 383DBCS support 365debug mode 85defaults file, creating and modifying 19defaults, site 17defaults, user 19diagnosing problems

See also error messages047 abend 2617C3 abend on user program 261conditional branch coverage, poor performance 263ECSA storage depleted 262SQA storage depleted 262

distillationlogical

description 107outputs 134requirements 109

physicalDASD data 136description 108generating JCL 136parameters 134process 133return codes 141running 135tape data 139

EECSA storage depleted 262ECSA usage 360, 363editing the control file (CACTL)

CA 61DA 129UTA 165

Englishspecifying as national language 382

ENU 382error messages and return codes

See also troubleshootingARCOxxxx 288ASETxxxx 301COMNxxxx 345N2Oxxxxx 339OCUSxxxx 290


error messages and return codes (continued)SAAFxxxx 307VAR0xxx 312

executionCA overview 39DA overview 112monitor 227multiple user sessions 231UTA overview 149

FFastPath

overview 369Quick Start

JCL 370parameters 372

Quick StopJCL 377parameters 378

Snapshot Summary JCL 375File Warp

control file 175, 178—183return codes 183samples 177

frequency count mode 85, 127

Hhigh-level qualifier (hi_lev_qual) 11

Iinput data sets 125input master data set 108installation

See system installationintroducing

Coverage Assistant (CA) 35Distillation Assistant (DA) 107Source Audit Assistant (SAA) 267Unit Test Assistant (UTA) 145

JJCL

CAcreating combine 102creating report 64for assembler examples 55for COBOL examples 53for PL/I examples 53

CA/DA/UTA Setupcreating monitor 229creating Setup 222creating Setup for compile job stream 224

DAfor COBOL and PL/I examples 117—123

JCL (continued)DA (continued)

generating for physical distillation 136UTA

creating report 172for COBOL examples 153

LLanguage Environment runtime library 25language, national

specifying 382languages supported

CA 35DA 107UTA 145

large project environments 99libraries, ATC 11

modifying FORMS and REXX 11LINECOUNT option 384linklist data sets 12listings

assembler 57example 77

COBOL 49, 267example 50, 77

PL/I 55example 55, 77

LOCALE option 383logical distillation, requirements 109

Mmessages, displaying

See also error messagesSetup 222

module, definition 99monitor program

CA 39commands 239DA 112execution 227problems, diagnosing 261SQA and ECSA usage 360UTA 149

monitored variables report 167multiple user sessions 227

Nnational language

specifying 382NATLANG option 382numeric format, specifying 383

Index 393

Ooperating systems

CA 36DA 108SAA 267UTA 146

options, compilerCA 211CA targeted coverage 214DA and UTA 214

overhead 235overview, ATC 3

PPA

See program areapage size 384panel interface 36, 108panels

ATC Defaults 21ATC Primary Option Menu 19CACommon CA, DA, and UTA

Coverage, Distillation and Unit TestAssistant 187

DAManipulate ATC Defaults 20Reset Defaults to System Defaults 25SAA

Create Prototype Targeted Summary Dataset &Validate Changes 278

Extract Source Code from Listings 275Source Audit Assistant 275SuperC 271

UTAGenerate JCL for File Warping 177Unit Test Report 172

parametersATGOPVAR program 174command 239—260common 26, 88, 174, 226, 231, 241, 242, 243, 245,

248, 249, 250, 252, 253, 256, 257, 260, 381setting default values 12

physical distillation 134Setup and ZAPTXT 224

debug mode 225frequency count mode 225

Performance Modechanges in annotation symbols 86reducing monitor overhead 235suppressing conditional branch coverage 71

physical distillation 133problem diagnosis

See also error messages

problem diagnosis (continued)047 abend 2617C3 abend on user program 261conditional branch coverage, poor performance 263ECSA storage depleted 262SQA storage depleted 262

program areadefinition 41displaying statistics for 257

RRACF program profiles

setting up 14REPORT program

parameters 174resources required 360

reportsAnnotated Listing report 77

creating specific listings 84CA with DA or UTA 86Combined Variable Data 171monitored variables 167printing 88summary for assembler 74Summary report 67targeted summary 89variable data 169

requirements, ATC 359, 365resources required

CA 359DA and UTA 362

resultscombining 101, 104rules used 104

return codesFile Warp 183physical distillation 141

runtime library, accessing 25

Ssample

Annotated Listing reportAnnotated Listing reportsCA 41DA 115, 125File Warp 177files, list of 11summary of test case coverage 43UTA 151, 161

sessionsdefinition 231determining active sessions 252multiple 231


setupcreating JCL using the panels 222for summary and listings 211JCL for the compile job stream 224overview 39parameters 224

Setup 224Zaptxt 226

when to create or submit JCL 224Setup program

parameters 224resources required 359, 362

site defaults data setediting 17example 17

SQA storage depleted 262SQA usage 360, 363starting ATC 19statistics, resetting 248stopping the monitor 259Summary program

parameters 87resources required 360

summary test case coverageassembler

COBOL 43sample 29Setup 39summary 55

COBOLcreate JCL to start a monitor session 47create Setup JCL 46create summary JCL 47edit JCL to link the modified object modules 48edit JCL to run the GO step 48editing the control file 45execute the JCL 48

PL/I 53supervisor call (SVC)

definition 389installing and enabling 14problems, diagnosing 261used as breakpoints 146, 227

SVCdefinition 389installing and enabling 14problems, diagnosing 261used as breakpoints 146, 227

symbols, annotationAnnotated Listing report 57, 77changes with Performance Mode 86changes with the EXTPROGRAM-ID option 87

syntaxconversion tables 206statements and options

ASM 199COBOL 193, 195

syntax (continued)statements and options (continued)

compilation unit definition (COBOL or PL/I) 91COVERAGE 203, 204defaults 191examples 208FILE Read 207INCLUDE 93, 191PL/I 197reading xviiSCOPE 92, 201TARGETSTMT 95TARGETVAR 94VARIABLE 202WARP 204

system considerationsCA 36DA 108SAA 267UTA 146

system installationmodifying the FORMS and REXX libraries 11setting up the authorized data set 12site defaults file, editing 19

TTargeted Summary control file 89terminating ATC

ATGQUIT command 243ATGSTOP command 259

test casescombining results 101individual, measuring coverage 104rules used 101sample 18specifying ID 249

tester, definition 99time format, specifying 383timeout, monitor 248

Uunexecuted 76user defaults

editing 20panel 21resetting 25

user SVCsCA 39DA 112UTA 149

Index 395

VVariable Data report 169variable read operation 161, 162variable warp operation 163verification of installation 18

Wwarping

control file 175, 178—183conversion tables 206dynamic data 145file 175return codes 183samples 177statement 204

ZZaptxt program

parameters 226resources required 359, 362


We'd Like to Hear from You

Application Testing Collectionfor MVS/ESA & OS/390User's GuideVersion 2 Release 1

Publication No. SC26-9871-03

Please use one of the following ways to send us your comments about this book:

� Mail—Use the Readers' Comments form on the next page. If you are sending the formfrom a country other than the United States, give it to your local IBM branch office orIBM representative for mailing.

� Fax—Use the Readers' Comments form on the next page and fax it to this U.S.NUMBER: (859) 243-4345.

� Electronic mail—Use the following network ID:

– Internet: [email protected]

Be sure to include the following with your comments:

– Title and publication number of this book– Your name, address, and telephone number if you would like a reply

Your comments should pertain only to the information in this book and the way the informa-tion is presented. To request additional publications, or to comment on other IBM informa-tion or the function of IBM products, please give your comments to your IBM representativeor to your IBM authorized remarketer.

IBM may use or distribute your comments without obligation.

Readers' Comments

Application Testing Collectionfor MVS/ESA & OS/390User's GuideVersion 2 Release 1

Publication No. SC26-9871-03

How satisfied are you with the information in this book?

Please tell us how we can improve this book:

May we contact you to discuss your comments? � Yes � No

Name Address

Company or Organization

Phone No.

VerySatisfied Satisfied Neutral Dissatisfied

VeryDissatisfied

Technically accurate � � � � �Complete � � � � �Easy to find � � � � �Easy to understand � � � � �Well organized � � � � �Applicable to your tasks � � � � �Grammatically correct and consistent � � � � �Graphically well designed � � � � �Overall satisfaction � � � � �

Cut or FoldAlong Line

Cut or FoldAlong Line

Readers' CommentsSC26-9871-03 IBM

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

International Business Machines CorporationApplication Testing Collection DevelopmentDepartment TNZA / Building 962-2745 West New Circle RoadLexington, KY 40511-1846

Fold and Tape Please do not staple Fold and Tape

SC26-9871-03

IBM

Program Number: 5655-B97

Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

SC26-9871-03

Spine information:

IBM ATC User's Guide Version 2 Release 1

Date post:	19-Feb-2022
Category:	Documents
Upload:	others
View:	15 times
Download:	0 times

Application Testing Collection for MVS/ESA & OS/390 IBM

Documents