Copepga

COPE for IMS/DC Programmers Guide
Document: COPEPGA Modified: Wednesday, September 12, 2007 9:19 am
Standardware Incorporated 424 Pelham Manor Road Pelham Manor NY 10803 USA Tel: 914-738-6382 Fax: 914-738-7136 Email: cope@standardware.com Internet: http://www.standardware.com
Copyright (c) 1989-2006 Standardware Incorporated. All rights reserved. This material may not be reproduced in whole or in part, by any means, without written permission from Standardware Inc.
Contents
Preface 11 About this Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE Family of Products General Information Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC Administration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC Distribution Tape Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC Messages Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE for IMS/DC New Features Bulletin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution of Manuals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Technical support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction 15 The COPE System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How COPE Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Programmer Responsibilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The COPE Parsers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to use this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common COPE facilities 19 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ISPF Edit, View, and Utility Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Re-submitting COPE Generated Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Message explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Member Selection Lists and Data Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selection mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Problem Solving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of the COPE External Interface 24 Modifying Existing Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary of Information required for External Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What happens in the External COPE Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing COPYLIB members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparation of the External Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the User Jobcard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling Multiple Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACBGEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PSBGEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ISPF Facilities 29 Accessing ISPF facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COPE Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit (Default option). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Foreground and Background Generate/Submit (Options 1-2) . . . . . . . . . . . . . . . . . . . . . .
COPE for IMS/DC Programmers Guide 1
11 11 11 11 11 11 12 12 12 12 12
15 15 16 16 17
19 19 19 20 20 22 23
24 24 24 25 25 26 26 27 28
29 29 37 38 39
COPE Import (Option 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Importing load modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Compile options (Option 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Specify program i/o data and handling of unavailable DBDs (Option 5) . . . . . . . . . . . . . . 43 Cases when Program I/O Data must be Specified Manually. . . . . . . . . . . . . . . . . . . . . 48 Parse all unparsed members (Option 6). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Edit/Browse DL/1 calls (Option 7). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Jobcard parameter specification (Option J) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 COPE Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 The LIBRARY utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 The PROMOTION utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Example "P" Option Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Example of the PM and PA options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 The EXPORT utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Export commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Input specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Output specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 The SCAN utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 The REPLACE utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 The COMPARE utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 The PDS MAINT utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 AMBLIST and Load Module Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 IMS Online Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 The IMS commands facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 The IMS trace display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Xpediter support feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Xpediter Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Xpediter IMS Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Problems running Xpediter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Convert JCL for an Lsys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Execution time Unconverted JCL Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Explicit JCL conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Convert JCL in one step (XJCLDSN=NO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Convert JCL in multiple steps (XJCLDSN=YES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Convert JCL Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Running Converted JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Logical System Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Lsys specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Non-COPE switch considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 MSC considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Libset Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Display COPE name translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 IMS Facilities 94 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Commands for programmers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Commands for administrators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Using the tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Logon to an Lsys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
2 COPE for IMS/DC Programmers Guide
Suspending conversational transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMS / Commands (with * wild characters) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display COPE Message Explanations (nnn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Program Load Libraries (LIB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logoff from COPE (not normally necessary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send a Message to a User or all Users (MSG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Start/Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Groups of databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database stopped counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why /DBR, etc. commands are prohibited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command line STA and STO commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why /STO TRAN, etc. commands are prohibited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command line transaction STA and STO commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . System Start/Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command line system STA and STO commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Turning DLI and SQL call trace on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trace display for MPP programs (ISPF option 7.2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What to do if you get no Trace output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details of Trace display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COBOL Ready Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function/PCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I/O Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSA Lines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logic trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRACE OFF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRACE NOTRUNC command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRACE LOGIC command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Activity Display (ISPF 7.2.T). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Update bytes by DB details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Number of Get calls and number of Update calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple transactions in one program scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend Summary Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Abend description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Abend offset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Status code description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Module call trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Last DLI call display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Module offsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abend summary - Date link-edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bring in new Versions of COPE tables (REFRESH) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Link Date/DSN of a Program (VERSION). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Commands for COPE Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setup of ViaSoft Smart-Test option 139
101 101 102 102 104 105 105 109 110 110 110 114 114 114 116 116 117 118 120 121 122 122 123 123 123 124 124 124 125 125 126 126 129 129 130 131 131 132 133 133 134 135 135 136 136 137 137
Smart-Test setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Setup of HourGlass support 147 JCL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 HourGlass Abends. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Use and Setup of the IBM Debug Tool under COPE and IMS for non Language Environment Programs 150 IDebugging a MPP program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Debugging a BMP program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 The DFSRRC00 PARM field changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Add a COPEBSYS DD card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Add a PARMFILE DD statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Add additional DD statements as required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Debugging a DLI or DBB program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 SETUP of DEBUG TOOL for COPE 153 Change EQAOPTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Update the Global Preferences File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SPOC Feature of COPE setup and use 154 Description of the COPE SPOC Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Accessing the COPE SPOC Command application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Example of inputting IMS command and the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Using UMS DRD (Dynamic Resource Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
List of Figures
Figure 1: Job Status Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 2: Data Display example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 3: Selection Mask prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 4: JCL Interface screen (Option 5.7) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 5: COPE Primary menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 6: COPE Browse screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 7: Project/Group Selection menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 8: COPE List Library display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 9: Browse Member display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 10: Object Data screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 11: Secondary Browse Information display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 12: COPE Edit Command screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 13: COPE Edit Session screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 14: COPE Import screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 15: COPE Compile Option Override screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 16: Compile Option Data Entry screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 17: COPE Database Not Available Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . Figure 18: COPE Database Not Available Action Propagation screen . . . . . . . . . . . . . . . . . . . . Figure 19: COPE Program I/O Specification Selection screen . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 20: Edit/Browse DL/1 Calls screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 21: COPE Jobcard screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 22: COPE Utility Selection screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 23: Library Management Control screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 24: Promotion Data Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 25: The "P" Promote Option screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 26: The PM and PA Promote screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 27: Export Option Selection screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 28: Scan Utility screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 29: Replace Utility screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 30: Lsys Sibling Relationship Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 31: Compare Utility Selection menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 32: Compare two Datasets menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 33: External Dataset Compare menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 34: PDS Maint Option menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 35: Load Module Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 36: Load Module Attribute screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 37: IMS Online menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 38: Xpediter Primary menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 39: Xpediter Installation Options screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 40: Xpediter Exit Routine screen (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 41: Xpediter Exit Routine screen (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 42: Xpediter BTS Setup screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 43: Xpediter Test Setup menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 44: Xpediter Loadlib Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 45: Xpediter Test Setup menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 46: Xpediter BTS Setup menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20 21 23 25 29 30 31 32 33 34 36 37 38 40 42 42 43 44 45 49 50 51 52 53 54 55 56 58 59 60 61 62 63 64 65 66 66 68 68 69 69 70 71 72 73 73
5
Figure 47: Figure 48: Figure 49: Figure 50: Figure 51: Figure 52: Figure 53: Figure 54: Figure 55: Figure 56: Figure 57: Figure 58: Figure 59: Figure 60: Figure 61: Figure 62: Figure 63: Figure 64: Figure 65: Figure 66: Figure 67: Figure 68: Figure 69: Figure 70: Figure 71: Figure 72: Figure 73: Figure 74: Figure 75: Figure 76: Figure 77: Figure 78: Figure 79: Figure 80: Figure 81: Figure 82: Figure 83: Figure 84: Figure 85: Figure 86: Figure 87: Figure 88: Figure 89: Figure 90: Figure 91: Figure 92: Figure 93: Figure 94: Figure 95:
6
Xpediter BTS DL/1 Parameter List screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Xpediter Test Setup menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Xpediter IMS Setup menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Xpediter PSB/DBD Libraries screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 COPE Xpediter Interface screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76 Xpediter Initial Test screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Convert MSG/BMP/Batch JCL screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Convert MSG/BMP/Batch JCL (XJCLDSN=YES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Libset Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90 Translation of a non-COPE name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Translation of a COPE name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 COPE Online Main screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 DRAW, Libset display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 COPE Online Main screen (Not logged on) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 COPE Online Main screen (after logging on) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 COPE Online - LIB command screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 COPE Online - Not Logged On screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 COPE Online - Start/Stop Selection screen (DB side) . . . . . . . . . . . . . . . . . . . . . . . . 106 COPE Online - Start/Stop System List screen (DB side) . . . . . . . . . . . . . . . . . . . . . .107 COPE Online - Database List screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 COPE Online - Stopped Database screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 COPE Online - Start/Stop Selection screen (TR side) . . . . . . . . . . . . . . . . . . . . . . . . 111 COPE Online - Start/Stop System List screen (TR side) . . . . . . . . . . . . . . . . . . . . . . 112 COPE Online - Transaction List screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 COPE Online - System Start/Stop screen (DB side) . . . . . . . . . . . . . . . . . . . . . . . . . 115 COPE Online - Turning Trace On. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 COPE Online - Trace Status screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Option 7.2 IMS Online Traces menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Option 7.2 Trace Search in Progress screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Trace Records screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Trace Selection screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Transaction Activity screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Abend Description screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Abend S0C7 display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132 Abend Offset display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Abend Status Code display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Abend Summary - Module Call Trace display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Abend Summary - Last DL/1Call display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Abend Summary - Module Offsets display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Abend Summary - Date Link-edited display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Viasoft - Initial screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Viasoft - Setup Test Option Selection screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Viasoft Current Environment Setup Selection screen . . . . . . . . . . . . . . . . . . . . . . . . 142 Initial BMC Delta/IMS Selection menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Viasoft IMS Setup Selection menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Viasoft RESLIB and MODBLK Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . 145 Viasoft IMSID/Lsys Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Administration menu with Hourglass option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Virtual Date Specification screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Figure 96: Prime ISPF COPE Panel with SPOC Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 97: IMS Application Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 98: SPOC Command Entry Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 99: Options Preferences panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 100: Example of inputting a Type 2 command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figure 101: Response from Type 2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
154 155 156 157 158 158
List of Tables
Table 1: Specification of Program I/O Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
10
Preface
About this Manual
COPE for IMS/DC Programmer's Guide Explains how to edit, generate, compile, and test programs and MFS blocks under ISPF and IMS/ DC from within the COPE environment. This manual is for programmers who will be using COPE for IMS/DC for application development or maintenance.
Related Manuals
COPE Family of Products General Information Manual Gives an overview of COPE products (including COPE for IMS/DC) and explains the benefits to be gained by their use. This manual is for individuals who wish to evaluate the use of COPE products.
COPE for IMS/DC Installation Guide Explains how to install or upgrade a COPE for IMS/DC system. Details are given on unloading the distribution tape, setting up ISPF logons, and specifying system-related parameters. This manual should be read in conjunction with the COPE for IMS/DC Distribution Tape Information, which accompanies each distribution tape. This manual is for individuals who are responsible for the installation or upgrade of a COPE for IMS/ DC system.
COPE for IMS/DC Administration Guide Explains how to create, maintain, and run a COPE for IMS/DC system. This manual is for a Database or System Administrator who is setting up a COPE for IMS/DC system. The reader should be familiar with IMS concepts, such as Program Specification Block (PSB) and Database Descriptor (DBD).
11
COPE for IMS/DC Distribution Tape Information Accompanies a distribution tape. It explains the contents of the tape and gives instructions for uploading the data to your libraries. This manual should be read in conjunction with the COPE for IMS/ DC Installation Guide. This manual is for individuals who will receive and process a COPE for IMS/DC distribution tape. This person should be familiar MVS JCL.
COPE for IMS/DC Messages Manual Contains a list of all messages generated by COPE for IMS/DC. Each message is explained, and the system action and recommended user response are described. This manual is for programmers or technical support personnel who need details of messages generated by the COPE for IMS/DC system.
COPE for IMS/DC New Features Bulletin Explains new features of the latest release of COPE for IMS/DC which have not yet been included in the appropriate manuals. This manual is for individuals who require details about new features of the latest release of the COPE for IMS/DC system.
Distribution of Manuals
Manuals can be provided on diskette or can be viewed and/or downloaded from Standardware's web site (http://www.standardware.com). Manuals are distributed in PDF format and must be viewed with the Acrobat 3.0 reader. The reader can be downloaded from the above mentioned web site. The PDF reader allows printing all or part of a manual if your PC is attached to a suitable printer. Manuals provided on diskette come with installation and viewing instructions. Printed manuals can be provided upon special request.
Technical support
For COPE for IMS/DC technical support, you may contact Standardware by phone, fax, or email. Contact information is found on the front of this manual. If you are reporting a problem or unexpected condition, try to have descriptive materials such as the following available:
12
For online IMS problems: screen images or descriptions and IMS job log and error message file
For COPE-generated batch jobs: the job log, job message and SYSTSPRT files For problems under ISPF: a list of exactly what was entered on which screens, together with any messages that may have been issued
13
14
Introduction
The COPE System
The COPE System allows an installation to operate separate and distinct versions of related IMS DB/DC applications under one IMS control region. Without COPE, separate DB/DC environments are typically required to support unit testing, system testing, or customized versions of the same application system. Some installations devise complicated, manual naming conventions to allow multiple versions of programs and databases to co-exist in one IMS system. COPE automates and controls the renaming process and allows the operation of multiple versions of an application system in one IMS Control Region. Throughout the COPE documentation, you will encounter the terms: Physical system (or Psys) and Logical system (or Lsys). A Psys refers to a real executing IMS control region. A Lsys refers to a version of an application system that executes in the COPE- generated physical IMS control region. COPE Lsys's are built and maintained with either: 1. 2. The COPE ISPF Development Facility, or, An External COPE Interface that may be added to the PSB, DBD, and MFS compile procedures.
The Development Facility operates under ISPF and uses the ISPF Editor, and will not be difficult to learn for programmers already familiar with ISPF. The External COPE interface allows your existing development environment to be used with no change to the current development practices. Programs will run in COPE using your current load libraries, without any copying. The development facility of COPE has a promote ability. Promotion is the process of moving modules through the standard stages of unit testing to systems testing, towards a final production stage. A COPE user specifies a set of LIBSETs or dataset collections, and modules are promoted through them in an orderly manner. COPE understands the source/load relationship of modules, and will promote them together. A powerful feature of COPE is its ability to capture and browse DL/1 calls for programs running in an IMS message region. The DL/1 call trace is turned on and off by commands issued when connected to an IMS/DC session. The trace is then viewed from an ISPF session.
How COPE Works

COPE contains two parts: one that operates under ISPF, and one that executes in IMS message regions. The ISPF part of COPE produces an environment that lets IMS operate several Lsys's within a single Psys, by parsing information from source modules into ISPF tables, and then regenerating DBDs, Dynamic Allocation Macro specifications, IMS/VS Stage 1 source specifications and PSBs for the
combined system. The IMS part of COPE controls the operation of Lsys's within the single physical IMS system that COPE generates. A Control database is used to record the state (started or stopped) of databases and transactions under COPE control, and tracks the name of the Lsys that a user is connected to. COPE provides transactions to start and stop databases and transactions one at a time or in userdefined groups. All naming is automatically controlled by the COPE system. The COPE interfaces must be used for all development work associated with a COPE environment.
Application Programmer Responsibilities

If the COPE External Interface is used, the application programmer needs to: Understand that when a PSB, DBD, or MFS source module is recompiled, a job will be generated to import it into COPE. Another job will be generated to recompile a modified version of the module for use by COPE. Be familiar with the Logon, Start/Stop, Call Trace and Abend Summary features of the COPE for IMS/DC online system (see "IMS Facilities" on page 94 ).
If the full COPE Development Environment is used, the application programmer needs to: Be familiar with the COPE Edit, Browse, and Import facilities. Understand the LIBSET hierarchy that has been defined by the installation, and understand LIBSET terminology (see "Libset Terminology" on page 90). Be able to import, compile, and test programs using the COPE facilities (see "Accessing ISPF facilities" on page 29). Be familiar with the Logon, Start/Stop, Call Trace and Abend Summary features of the COPE for IMS/DC online system (see "IMS Online Facilities" on page 66). Interface with the person administering the COPE environment to generate PSBs, DBDs, and ACBs. Interface with the installation's Quality Control personnel to manage the COPE promotion and Export facilities.
The COPE Parsers

The IMS/DC system controls its environment with information supplied in DBDs, PSBs, MFS, Stage 1 and Dynamic Allocation source members. Since COPE for IMS/DC does not modify IMS code at execution time, a technique is required to obtain the same type of information for the manipulation
of the objects that COPE controls. A convenient method of extracting the information is by parsing the same source that drives IMS. This allows COPE to adapt to existing environments and requires no re-entry of information by system or application programmers. COPE parses DBDs, PSBs, and MFS control blocks to allow the renaming of objects required to run multiple logical environments in one IMS/DC system. The parsed tokens are maintained in ISPF tables in a form that allows the information to be manipulated without errors. The COPE compile processes for DBDs, PSBs, and MFS control blocks, generate a new module from the ISPF tables and compile the generated module rather than the original source. If developers look at the compiler output, they will notice statements in a different order, and the suppression of all comments. The original source is maintained in PDS members. It may be accessed by the ISPF editor provided in the 'full development' COPE environment. When a change is made with the editor, the source is automatically reparsed without any specific user actions. If an error is detected, the EDIT session is re-entered with the cursor positioned at the error. If the user wishes to exit without correcting an error, a CANCEL command may be issued. When a module with an error is compiled, no source will be generated, and the compile will fail. If the COPE External Interface is used, a source module will be imported, and will replace any existing source module associated with the Lsys. A check that all source modules have been parsed may be made with Option 2.6. This will generate a batch job that detects unparsed modules and invokes the parser for each. Any errors encountered are noted in the listing (they are surrounded by "********" indicators), and it is the application programmer's responsibility to correct any problems by using the COPE editor. Optionally, using the full COPE development environment, application programs may be parsed if they are COBOL or Assembler. The parse process extracts COPYLIB member names and static calls. In Assembler source, macros are extracted and treated as COPYLIB members. If the application source is not COBOL or Assembler, the COPYLIB and call information may be entered via the i/o specification facility described later. It should be noted that specification of the COPYLIB and macros used by applications is only required if they are maintained in a COPE "shared" library dataset. Sharing of a dataset is accomplished by renaming all members within it. Referenced members have to be extracted and renamed before a compile. In the case of a non-shared library, the information is for documentation only.
How to use this Manual

If the full COPE development environment is to be used, the following sections should be read: "Common COPE facilities" on page 19 "ISPF Facilities" on page 29 "IMS Facilities" on page 94
17
If the External Interface is to be used, the following sections should be read: "Common COPE facilities" on page 19 "Use of the COPE External Interface" on page 24 "IMS Facilities" on page 94
18
Common COPE facilities

Overview
There are a series of facilities that are available from all COPE ISPF panels. These facilities are intended to provide convenience of operation for the user of COPE. The common facilities are: Invoke ISPF Edit by entering 'EDIT' in the command or option field Invoke ISPF View by entering 'VIEW or 'BROW' in the command or option field Invoke ISPF Utility selection menu (ISPF option 3) by entering 'UTIL' in the command or option field Access previously generated JCL together with job execution results by entering 'JOB' in the command or option field Find the explanation and user action for all COPE generated messages beginning with the letters 'COP'. These messages will be seen in the IMS portion of COPE. The same message description may be accessed from IMS or ISPF by entering 'COPnnn' in the command field of any COPE controlled menu (nnn represents a numeric suffix).
Another feature of COPE is the common method for selecting options from a menu. Some applications require multiple items to be selected. A summary of the selection technique is given at the end of this section. ISPF Edit, View, and Utility Access Instead of accessing the ISPF facilities of 1 (for View), 2 (for Edit), or 3 (for Utilities), the commands VIEW/BROW, EDIT, or UTIL can be entered from any COPE controlled ISPF menu. Re-submitting COPE Generated Jobs When you perform many of the functions in COPE, such as importing PSBs or DBDs, or generating MFS, batch jobs are submitted. Entering 'JOB' in the command or option field of any menu, accesses a dataset in which all submitted job JCL has been stored. The most recently submitted job is displayed first. This option is controlled by the XJOBSAVE installation parameter (refer to the COPE for IMS/DC Installation Guide appendix). If the XJOBSAVE parameter has been set to NO, a message will be displayed indicating the option is not available. When JOB is entered, the following screen will be displayed:
19
: Figure 1: Job Status Display
Browse JOB STATUS INFORMATION - Table Date Panel -- ROW 1 OF 1 --Command ===> Scroll ===> CSR MORE Commands: FIND/POPUP/REPORT View.: none Rcd(s): S View.: E/SUB MEMBER STATUS STEP INVOK Rcd NAME CODE NUMB STEP ...... JOB00073 CC=00008 003 _______ ...... JOB00354 AB=0C4 004 _______ ****** ******************* BOTTOM OF DATA STEP PROG VERSION NAME NAME LEVL COPEBTCH IKJEFT01 _______ TDUMP TDUMP _______ *************************
--------------------------------------------------- STANDARDWARE --
The display shows the maximum return code from any step in a job. If E is entered next to a job record, the user is placed into edit on a copy of the job JCL. If a job is to be resubmitted, SUB may be entered next to the job name. The job name will be replaced with the name of the resubmitted job. The copy of the JCL and status record may be deleted by entering a D next to the job name. Error Message explanation The COPE product has an error message manual. The text of error messages that begin with 'COP' and end with a three-digit numeric suffix, can be accessed online, from any screen, under ISPF or IMS, by entering the numeric suffix or the full COPnnn message number. Member Selection Lists and Data Display COPE ISPF applications allow both data entry and display of member lists. Both operations have standard commands and procedures. Data entry is performed from a common application that allows the display of existing data in row/ column format. An example of a data display format follows:
20
Figure 2: Data Display example
Browse PSB -------------------- Table Data Panel --- ROW 1 OF 1 --Command ===> Scroll ===> CSR Commands: FIND/POPUP/REPORT Rcd(s): S View.: ALL/INLIBS/L/NOTCOMP/NOTINACB View.: S
ORIG COPE LOGICAL PSB Rcd PSBNAME PSBNAME NAME STATUS DESCRIPTION ..... A C0280327 *ALL* ________ ONLINE PSB ..... AAA C0295466 *ALL* ________ ONLINE PSB ..... AAA1 C0295467 *ALL* ________ ONLINE PSB ..... AAMS0085 C0221821 *ALL* ________ ONLINE PSB ..... AAMS0085 C0232361 IMSA ________ ADDED PSB ..... AAMS0330 C0221822 *ALL* ________ ONLINE PSB ..... AAMS0330 C0232362 IMSA ________ ADDED PSB ..... AAMS0340 C0221823 *ALL* ________ ONLINE PSB ..... AAMS0345 C0221824 *ALL* ________ ONLINE PSB ..... AAMS0345 C0232364 IMSA ________ ADDED PSB ..... AAMS0365 C0221825 *ALL* ________ ONLINE PSB ..... AAMS0365 C0232365 IMSA ________ ADDED PSB ..... AAMS0370 C0221826 *ALL* ________ ONLINE PSB ..... AAMS0390 C0221827 *ALL* ________ ONLINE PSB ..... AAMS0519 C0221828 *ALL* ________ ONLINE PSB --------------------------------------------------- STANDARDWARE --
In the above example a data table is displayed for update. Data may be changed by overtyping. Sometimes there is more data present than can fit on a line. In this event the word "MORE" will appear on the third line with a right pointing arrow. The screen may be scrolled right and left by using the <PF11> and <PF10> keys, or by using the RIGHT and LEFT commands. If data from an entire row is to be displayed, S may be entered on the row selection field and a screen will appear that shows all data from a row. Again, data may be updated by overtyping. The previous or next row data may be displayed by pressing <PF7> or <PF8>. Row commands specific to the application are noted on the 5th line opposite "Rcd(s):" (in this case S) and commands that apply to the entire data are noted on the right of the 4th line (in this example ALL, INLIBS, L, NOTCOMP ,NOTINACB). There are several standard functions that apply to all data display applications. A description of the other functions may be obtained by typing 'POPUP' in the command field.
Standard functions include finding data in a column, sorting rows based on the contents of a column, and changing data in a column. In addition, the contents of a display can be formatted and written to a dataset by entering the 'REPORT' command. Many of the COPE panels display member selection lists, of which there are two types: 1. 2. Selection for a single member Selection for multiple members
The single member list is used in the edit panel, and requires <Enter> to be pressed after entering an S next to the desired member. The multiple member selection list requires <PF3> to be pressed after selecting one or more members. The action to be taken is always noted in the top left-hand corner of the screen. You may select multiple members by scrolling through the list and entering an S next to the desired members. If all members are required, ALL is entered in the command field, and an S will appear next to all members in the list. If some members are to be excluded from processing, the S can be blanked out. If a set of selections is invalid, the RESET command will cause all selections to be removed. When the selection process is completed, <PF3> is pressed to begin processing. Selection mask In general, whenever the name of a member may be entered, a mask may be specified that results in a display of the set of members that match the mask. Whenever a selection list is displayed, a select command followed by a mask specification may be entered to select multiple members. If help with the mask conventions is desired, a S with no mask may be entered on the command line to display the following prompt screen:
22
Figure 3: Selection Mask prompt
-Browse -table-of-all-ACBs----Table Data Panel ------- ROW 1 OF10723 CO ----------------------------------------------------------------. ----------------- Selection Mask Definition ---------------Co Command ===> Mask ===> A* * *O B*
.. -------------------------------------- Standardware Inc. --.. --------------------------------------------------- STANDARDWARE --
The description of the masking options is given in the above example. It should be noted that there is an AND NOT function available when a mask is specified with the character preceding it.
Problem Solving
In the unlikely event that a "BREAK" is invoked while executing under ISPF, it is important that <PF1> be pressed, and the long and short message information be carefully recorded before contacting Standardware for assistance. Standardware support is available by phone, fax, or email as indicated on the cover of this manual. Note: A "BREAK" is the result of an unexpected condition having occurred within the COPE for IMS/ DC software.
23
Use of the COPE External Interface

Modifying Existing Procedures
If the COPE External Interface is used, the compile procedures for PSBs, DBDs, and MFS must be modified by adding a step to import the source into COPE. An example of such a step follows: //COPE1 EXEC COPECOPE, COPE SYSTEM // PROJECT=LSYS1, LOGICAL IMS SYSTEM // INDSN='INST.PSBsORCE', INPUT SOURCE DATASET NAME // INMEM=PSB99, SOURCE MEMBER NAME // USER=FTIDEF1, ISPF LOGON ID FOR JOBCARD IDENTIF'N // LIBTYPE=PSBsOURC DESTINATION COPE LIBRARY TYPE // PARMS='%ONLNE(YES)' COMPILE PARAMETERS In this example, a COPE system named COPECOPE will have a PSB named PSB99 transferred from the source dataset 'INST.PSBsORCE' to the LIBSET type PSBSOURC. The userid that the recompilation of the PSB is to be performed for is FTIDEF1. The userid is used for JOB card control and security. There is a compile option of ONLNE(YES) that will cause a PSBGEN for an online PSB. The above job step may be added to the installation's normal compile procedure. It may also be generated by CLISTS or ISPF PROCS, depending on the techniques used to compile modules. Note: Parameters passed through the External Interface must begin with a percent sign (%) to avoid problems with ampersands (&) in the JCL.
Summary of Information required for External Interface

The information required for the external interface is: 1. 2. 3. 4. COPE System Name (There may be several COPE Psys's in an Installation). Logical IMS system name for COPE. Source dataset and member name for PSB, DBD, or MFS modules. Userid for JCL job cards
What happens in the External COPE Interface

The External Interface invokes TSO and ISPF, and executes a COPE application under ISPF. The application imports the module into the appropriate COPE library. Then, if it is either a program, PSB, DBD, or MFS module, regenerates it and submits a job to recompile it with the appropriate name changes required for execution in a shared environment.
The user will see two jobs executing every time the External Interface is used, if the module regenerates successfully. If, for some reason such as the absence of a COPY member, the module cannot be regenerated, only one job will be seen, and the messages that the job generates must be reviewed to diagnose and correct the problem.
Importing COPYLIB members

If PSBs, DBDs, or MFS utilize copy members, the copy members must be imported before any compilations take place. The COPE external interface can import any member into any COPE library. Recompilation will not take place for modules that are not programs, PSBs, DBDs, or MFS.
Preparation of the External Interface

The JCL procedure that controls the External Interface, has the same name as the COPE physical name. The procedure contains variables that are dependent on the definition of the Psys, and must be generated using the COPE ISPF Option 5.7 (COPEUTIL.7). The panel that is displayed when this option is selected is as follows: Figure 4: JCL Interface screen (Option 5.7)
------------------- GENERATE EXTERNAL INTERFACE TO COPE ----------Option ===> GP GI E J - GENERATE EXTERNAL INTERFACE PROCS. AND SAMPLE STEP - GENERATE IMPORT JOB - EDIT GENERATED JCL - SPECIFY JOBCARD
- - - - - - - - - FOR IMPORT JOB GENERATION ONLY - - - - - - - - -
IMS SYSTEM NAME
===> TEST
OR PROJECT NAME ===> LEVEL NAME ===>
COPE LIBRARY TYPE ===> PSBsRC INPUT DATASET NAME ===> 'CSD.TEST.PSBsRC' --COPEEXGN----------------------------------------- STANDARDWARE --
25
Option GP must be used. This will cause the generation of two JCL procedures. These procedures may be accessed with the E Option. One of the procedures will have the same name as the COPE system, and the other will be named COPEJOB. The COPEJOB member is a sample JCL member that contains instructions on the external interface similar to those contained in this section. The member with the same name as the COPE system, will contain further details about all possible values that may be provided to it for its correct execution. The GI option on the above panel will cause a dataset to be accessed, and the members in the dataset displayed for selection. All selected members will be generated into a job stream that accesses the COPE external interface. The JOB is saved in a member called IMPORT. The generated JCL may be submitted for execution or may be used as an example of how to interface with COPE from an external development environment.
Controlling the User Jobcard

Some installations have unique requirements for the format of a job card. COPE supports either a single default job card, or a specific job card for each userid. All Jobcard are contained in a dataset named '&XCOPE1.CTLCD' (where the value of &XCOPE1 is that specified in the ZDEFAULT member (refer to the COPE for IMS/DC PSBs Installation Manual appendix). The default job card is contained in a member named 'DEFLTJOB'. It consists of the following statements: //&XXXXXXZ JOB (4011,F08),TB4.DAVE,CLASS=5, // NOTIFY=&XXXXXX,MSGCLASS=V,MSGLEVEL=(1,1) /*JOBPARM P=TFTI /*ROUTE PRINT U144 //** N O T E **************************************** N O T E ******* //* THIS JOBCARD IS THE DEFAULT JOBCARD PROVIDED IN THE CTLCD * //* DATASET MEMBER NAME DEFLTJOB. IF THE JOBCARD IS INCORRECT * //* THE DEFLTJOB MEMBER MUST BE CHANGED * //******************************************************************* The userid is identified with a 7-character string beginning with an ampersand (&). The userid supplied in the external JCL interface will be substituted for the ampersand and the six characters following it, before submitting. If a user needs a different job card from this overall default, an individual member with the same name as the userid may be set up in the CTLCD dataset.
Compiling Multiple Members

Frequently, multiple members have to be recompiled. Submitting a separate job for each member is tedious. The external JCL interface allows multiple members to be specified in a single job, using an instream file of member names. All the members are imported with one invocation of TSO/ISPF, and the members are also batched together for recompilation into the COPE system (The compile job invokes the Assembler once to compile multiple DBDs or PSBs). An example of the interface follows: //COPE1 EXEC COPECOPE, COPE SYSTEM // PROJECT=LSYS1, LOGICAL IMS SYSTEM // INDSN='INST.PSBsORCE', INPUT SOURCE DATASET NAME // INMEM=PSB99, SOURCE MEMBER NAME // USER=FTIDEF1, ISPF LOGON ID FOR JOBCARD IDENTIF'N // LIBTYPE=PSBsOURC DESTINATION COPE LIBRARY TYPE // PARMS='%ONLNE(YES)' COMPILE PARAMETERS //PUNCH.MULTIPLE DD * LIBTYPE INPUT-DATASET-NAME MEMBER-NAME COMPILE-PARMS .... .... .... LIBTYPE INPUT-DATASET-NAME MEMBER-NAME COMPILE-PARMS /* As you can see, multiple import members can be added to the compile JCL. For details about the continuation of compile parameters see the instructions in the generated COPEJOB member described in "Preparation of the External Interface" on page 25.
ACBGEN
The external interface supports ACBGEN processing as follows: //COPE1 EXEC COPECOPE, COPE SYSTEM // PROJECT=LSYS1, LOGICAL IMS SYSTEM // INDSN='DUMMY', INPUT SOURCE DATASET NAME // INMEM=PSB99, SOURCE MEMBER NAME // USER=FTIDEF1, ISPF LOGON ID FOR JOBCARD IDENT // LIBTYPE=ACBsOURC DESTINATION COPE LIBRARY TYPE // PARMS='%ONLNE(YES) %ACBTYPE(PSB)' The input dataset is ignored, and two symbolic parameters must be supplied to indicate if the member name refers to a PSB or a DBD and whether the ACBGEN is to be performed while the online IMS/DC system is executing. (This requires a /PREPARE, /COMMIT sequence when the ACBGEN is completed, to execute the results).
27
PSBGEN
The PSB import and regeneration process requires an additional parameter in the PARM field. This parameter is the same as that used in the ACBGEN process described in the previous section and is %ONLNE(YES). This parameter allows a PSB to be generated even if it is used in the online system. If ONLNE(YES) is not specified, batch PSBs will be generated and compiled, but online PSBs will not. Online PSB generation may be performed using option 4.7 in the ISPF portion of COPE. It should be noted that online PSBs should not be generated until all PSBs of the same (external) name have been imported for all Lsys's. COPE generates maximal online PSBs that contain PCBs from the PSBs associated with each Lsys. Generating PSBs before all imports are complete will produce redundant PSBGEN jobs that will be harmless, but which consume unnecessary CPU resources.
28
ISPF Facilities
Accessing ISPF facilities
COPE is accessed by entering the command "COPE" on the primary ISPF menu, or by selecting an appropriate option from some installation-supplied menu. The following menu will be displayed:
Figure 5: COPE Primary menu
---------------------- COPE DEVELOPMENT SYSTEM -------------------Option ===> 1 - Browse Version 4.0.6 2 - Edit Time 11:29 3 - Utilities Date 94/01/10 4 - Administration Julian 94.013 5 - Special Utilities 6 - Dictionary 7 - IMS Online X - Exit Physical IMS COPE1 Procs dataset TEST.COPEUMOD.PROCS Lsys Licenced 12 .-------------. | Enter JOB | | to review | | Job Status | ------------- .-------------. | Enter EDIT | | to access | | ISPF Edit | ------------- .-------------. | Enter BROW | | to access | | ISPF View | ------------- .-------------. | Enter UTIL | | to access | | ISPF Utils | -------------
Copyright (c) 1989-2000 Standardware Inc.
Most of the Programmer facilities are accessed from options 1, 2, 3 and 7. The remaining options are used for administration of the system environment.
COPE Browse
To browse a library, enter the Project, Group, and Type fields, as shown below:
Figure 6: COPE Browse screen
--------------------------- COPE - BROWSE ------------------------Command ===> (L, TO LIST LIBRARIES) COPE LIBRARY: PROJECT ===> CSD GROUP ===> T TYPE ===> COPEADEF NAME ===> INCLUDE CONCATENATED LIBRARIES
===> NO
(YES/NO)
--------------------------------------------------- STANDARDWARE --
To display all members in a libset concatenation, enter YES in the concatenated libraries field. The concatenated libraries were predefined when COPE was initially set up. Entering a question mark (?) or an incorrect name in the Project or Group field will cause a selection list of valid libset names to be displayed:
30
Figure 7: Project/Group Selection menu
PROJECT/LEVEL SELECTION -----------------------------------------Command ===> Scroll ===> CSR ENTRY INDICATOR *ENTRY* *ENTRY*
PROJECT . CSD . CSD . CSD . CSD
GROUP DESCRIPTION DEVL ACCOUNTING DEVELOPMENT PROJECT TESTPROD PRODUCTION TESTING ACTING ACCOUNTING INTEGRATION PROD PRODUCTION VERSION
--------------------------------------------------- STANDARDWARE --
A list of valid libset "Types" may be obtained with the L command. The L command results in the following display:
31
Figure 8: COPE List Library display
LIST OF DEFINED TYPES FOR CSD/T ------------------ ROW 1 OF 31 --SCROLL ===> CSR SELECT FUNCTION===> DEFINED TYPE TYPE DESCRIPTION . ASM ASSEMBLER SOURCE . BCTLCARD BATCH CONTROL CARDS . BTSPUNCH REGRESSION SESSION TESTING CARDS . COBOL COBOL SOURCE . COPYLIB COPYLIB MEMBERS FOR ASM AND COBOL . CTLCARD CONTROL CARDS DIFFERENT FROM BCTLCARD . DBDLIB DBD LOAD LIBRARY FOR IMS . DBDsCRLB DBD SOURCE LIBRARY . DESCLOAD DBAID SCREEN PAINTER SCREEN DESCRIPTIONS . DESCRIBE SCREEN PAINTER DESCRIBE MODULES . FORMAT IMS MFS FORMAT LOAD LIBRARY . ICTLCARD IMS CONTROL CARD LIBRARIES . IMSLOAD IMS EXIT PROGRAM LOAD LIBRARY . IMSSOURC IMS SOURCE LIBRARY . JCL JCL MEMBERS FOR LIBSET . LINKCTLB LINKEDIT CONTROL CARD LIBRARY . LOADLIB PROGRAM LOAD LIBRARY . MACROLIB ASM MACRO LIBRARY . MCOPYLIB META COBOL COPYLIB LIBRARY --------------------------------------------------- STANDARDWARE --
To Browse a particular member, enter the member name in the Browse panel NAME field. The name field supports entry of partial member names in the form "X....X", where "X....X" is a character string. Pressing <Enter> with a blank name field results in the display of a scrollable member list as shown below:
32
Figure 9: Browse Member display
BROWSE INDEX EXTRACT - TABLE DATA PANEL ----------- ROW 1 OF 6 --Command ===> Scroll ===> CSR MORE --> COMMANDS: REPORT/SHOOT/POPUP/FIND VIEW.: LMEM RCD(S): "S" VIEW.: B OBJECT OBJECT CONCAT STATUS CREATED CREATED CURRENT RCD NAME TYPE NUMB EXPTN DATE SIZE SIZE ..... ABCCMBDB DBDsCRCLB 3 ________ 85/01/30 43 69 ..... ABCCMBPR DBDsCRCLB 3 ________ 85/01/30 8 8 ..... ABCPKGS1 DBDsCRCLB 3 ________ 85/12/20 14 14 ..... ABCPNDDB DBDsCRCLB 3 ________ 86/06/10 99 99 ..... ABHTR1S2 DBDsCRCLB 3 ________ 86/04/10 18 18 ..... ABHTR1S3 DBDsCRCLB 3 ________ 86/04/10 39 41 ***** ********************** BOTTOM OF DATA ********************** --------------------------------------------------- STANDARDWARE --
Each member in the concatenated libsets is displayed together with the information associated with the member. Since the associated information is too large to be displayed on a single row, it may be viewed by moving right <PF11>, or left <PF10> (or by using the RIGHT and LEFT commands), or by entering an S in the row command (RCD) field opposite the name. If a row is selected with an S, the following screen is shown:
33
Figure 10: Object Data screen
BROWSE INDEX EXTRACT - ROW DATA PANEL ------------ ROW 1 OF 8 --Command===> MORE DOWN COMMANDS: REPORT/SHOOT/POPUP/FIND VIEW.: B 'INDEX EXTRACT' ROW DATA IS: MORE --> OBJECT NAME..: ABCDF100 OBJECT TYPE..: MFSSOURC CONCAT NUMB..: 1 STATUS EXPTN.: CREATED DATE..:89/02/14 CREATED SIZE.: 564 CURRENT SIZE.: 0 MOD DATE.....: 89/02/15 MOD TIME.....: 13:05 UPDATED USER.: APPMM5B PDS IND......: Y LOCK FLAG....: Y ALT-NAME FLG.: FIRST NAME...: ABCDF100 DELTA IND....: N VTYPE ID.....: C0023615 DATASET NAME.: CSD.DEVL.MFSSOURC PROMOTE TIME.: PROMOTE DATE.: PROMOTE USER.: LOGGED TIME..: 15:07 LOGGED DATE..: 88/11/25 --------------------------------------------------- STANDARDWARE --
Each panel field is described below: Field OBJECT NAME Usage COPE maintains information for internal ISPF tables as well as PDS members. The term Object is used to describe either a table or a PDS member. The NAME is the name that the object is known by externally (not the internal name). This is the class that the object belongs to. It is the same as the third level qualifier that is used to access the object from primary COPE panels. If concatenated libraries have been specified, this field reflects the library number that the member is in. "1" refers to the first library specified on the primary Browse panel. The date the object was created. This field is extracted either from the
OBJECT TYPE
CONCAT NUMB
CREATED DATE
34
PDS Directory (for PDS Objects) or from TBSTATS information (for ISPF tables). CURRENT SIZE MOD TIME PDS IND ALT-NAME FLG The current size is the number of table rows or PDS records that the table or member currently contains. The modification time is the time at which the table or member was last changed. The PDS indicator field contains a Y or N depending on whether the Object is a PDS member or a ISPF table. The alternate name flag field will be Y or N. If Y, the member whose name is held in the ALT NAME field is the most recently modified member. If N, the object whose name is held in the FIRST NAME field is the current version. The "Alternate" PDS member name of the object. This name is used to save a modified object when the "Primary Name" is locked. Not used in the current version of COPE. The name of the dataset in which the object is stored. The time that the object was last promoted. The date that the object was last promoted. The Userid of the user that last promoted the object. The time the object was imported. The date the object was imported. The status explanation field is used to flag objects when processing has been performed against them. It frequently contains "*DONE" for some objects. This field is not significant otherwise. The created size is the number of table rows or records when the table or member was created. The date of the last modification of the object. The userid of the user that last changed the table or PDS member. The LOCK FLAG field will contain Y or N, and is used to "Lock" an object. An object is considered locked when an object of the same name has been modified at a higher level in a libset hierarchy. If the Lock Flag is set to Y, the COPE edit facility will not replace the primary copy, but will process the alternate copy instead. The "Actual" PDS member name of the Object. This is the name under
35
ALT NAME DELTA IND DATASET NAME PROMOTE TIME PROMOTE DATE PROMOTE USER LOGGED TIME LOGGED DATE STATUS EXPTN
CREATED SIZE MOD DATE UPDATED USER LOCK FLAG
FIRST NAME
which the object is first stored when an import operation is performed. VTYPE ID An internal identifier used by COPE to distinguish between objects of the same name. The VTYPE id is unique across all COPE libsets. If a situation exists where objects from many libsets are combined into a single libset, there may be duplicate names present that actually refer to different versions of the same source. The specification of an "Entry" libset identifies a unique VTYPE. This process ensures correct identification of an Object.
The "MORE -->" indicator on line 5 of the Object Data panel indicates that more data is available for display by scrolling in the direction indicated by the arrow. Pressing <PF11> (scroll right) or entering the RIGHT command will result in the following screen: Figure 11: Secondary Browse Information display
BROWSE INDEX EXTRACT - ROW DATA PANEL ------------ ROW 1 OF 8 --Command ===> Commands: REPORT/SHOOT/POPUP/FIND "INDEX EXTRACT" OBJECT OBJECT LOGGED CHANGE CHANGE NAME..: TYPE..: USER..: DATE..: USER..: ROW DATA IS: VIEW.: B MORE DOWN
ABCDF100 MFSSOURC APPMM5B 04:57 APPMM5B
--------------------------------------------------- STANDARDWARE --
The fields on the previous screen are explained below: Field LOGGED USER CHANGE TIME Usage Userid of the user that imported the object. The time the object was last changed. This field is maintained by the COPE internal data management routines and will contain a value close to the time displayed in the MOD TIME field (maintained by ISPF) described above.
36
CHANGE DATE
The date that the object was last changed. This field is maintained by the COPE internal data management routines and will contain a value close to the date displayed in the MOD DATE field (maintained by ISPF) described above. The userid that last changed the object. This field is maintained by the COPE internal data management routines and will always contain the same id as the one displayed in the UPDATED USER field (maintained by ISPF) described above.
CHANGE USER
COPE Edit
Option "2" from the primary COPE panel accesses the Edit screen shown below: Figure 12: COPE Edit Command screen
----------------------------- COPE - EDIT ------------------------Command ===> (L to list library Types) Blank - Edit 4 1 - Foreground Gen/Submit 5 2 - Background Gen/Submit 6 3 - Import to COPE library 7 J - Enter JOB Card COPE LIBRARY: PROJECT ===> CSD GROUP ===> DEVL TYPE ===> COPEADF NAME ===> --------------------------------------------------- STANDARDWARE -Compile Options Program I/O Specifications Parse Modified Source Display Online Traces
From the Edit panel, you can Import, Describe, Edit, Parse, or Compile any or all modules. If your installation has chosen to use the full COPE development environment, all modules to be controlled by COPE must first be imported with Option 3. The import process is the only valid way to introduce objects to the COPE environment. New members must first be created in an external dataset, then imported into COPE. If your installation does not use the full COPE development environment, then importing is done usCOPE for IMS/DC Programmers Guide 37
ing COPEUTIL.7 and the External Interface, which are described in the COPE for IMS/DC Administration Guide. In this case, importing of PSBs, DBDs and MFS is handled automatically, and import of programs is not necessary at all. We will assume for the most part of this section, that you are using the full development environment, and are therefore importing everything. The various options on the above panel are described below. Edit (Default option) To invoke an edit session, enter a library name and a member name. A typical member edit screen is shown below: Figure 13: COPE Edit Session screen
EDIT --- CSD.DEVL1.TABLES (C0007253) -- 01.21 -- COLUMNS 001 072 -Command ===> Scroll ===> CSR ----COPE LIBRARY--CSD.DEVL.COBOL(DLMTKT02) ---20:59 ------------************************** TOP OF DATA *************************** 000001 001300 IDENTIFICATION DIVISION. 000002 001400 PROGRAM-ID. DLMTKT02. 000003 001500 AUTHOR. J.SMITH. 000006 001800 DATE-COMPILED. 000007 001900 SKIP2 000008 002000 *************************************************** 000009 002100 *** ** 000010 002200 ** THIS 'STDWARE KEY SELECT PROGRAM' ** 000011 002300 *** WAS GENERATED: ** 000012 002400 *** BY THE STDWRE PROGRAM PAINTER, ON: 84/06/28 ** 000013 002500 *** FROM "ISPF" TABLE: K0008373 ** 000014 002600 *** ** 000015 002700 *************************************************** 000016 002500 *************************************************** 000017 002960 *** 000018 002970 *** PROGRAM FRONTAGE PIECE: 000019 002980 *** 000020 002990 *** KEY SELECT PROGRAM BEING USED TO ADD TABLES TO --------------------------------------------------- STANDARDWARE --
The COPE Edit Panel displays the actual dataset and member name on line 1. The COPE logical dataset and member is displayed on the third line for information purposes only. (Refer to the COPE for IMS/DC Administration Guide for an explanation of the relationship between actual dataset
names and COPE logical dataset names). The edit session may be exited by pressing <PF3> or by entering CANCEL in the Command field. If CANCEL is entered, the results are not saved. For <PF3>, the source is parsed if it is a DBD, PSB or MFS source member. DBD, PSB or MFS source member. If a syntax error is detected, the edit session is re-entered with the cursor positioned under the error. If the source is to be saved with an error, a CANCEL command may be entered to exit from the edit session, otherwise corrections should be made and <PF3> pressed again. A blank in the member name field will result in the display of a member selection list. Select a member by placing an S next to the member name and pressing <Enter>. Foreground and Background Generate/Submit (Options 1-2) Options 1 and 2 on the COPE Edit panel are used to compile application program, DBD, PSB, and MFS source modules. Both options allow entry of a single member name or an asterisk (*) for all members of a library. Option 1 is used to generate and submit compile jobs in the foreground. Option 2 generates and submits the appropriate JCL in the background and leaves the terminal free for other work. If the name field is blank, a scrollable selection list is displayed. Pressing <PF3> after the desired selections are made causes jobs to be submitted. The JES job number is displayed at submission time. The background option (Option 2) is recommended for processing multiple members, since several members are automatically "batched" into a single job. This enhances compilation efficiency for DBD, PSB, and MFS compiles. COPE Import (Option 3) Option 3 on the Edit panel displays the "Import from Library" screen shown below:
39
Figure 14: COPE Import screen
---------------------Command ===>
Import - From Library
--------------------
Importing to COPE Library: FTCOPE.COPEH.DBDSRCLB
Import From Other COPE Library: PROJECT GROUP TYPE MEMBER ===> FTCOPE ===> COPEH ===> DBDSRCLB ===> Validate Indexes ===> NO (Yes/No)
(* for all)
Import From Non-COPE Library: DATASET NAME ===> For PSBs, DBDs and Programs only, import all referenced in Stage 1 for logical system ===> (? for list) For COPYLIB, MACLIB, MFS, DBDs and Called and Loaded Programs only, import members referenced by existing Program I/O ===> NO (Yes/No) --------------------------------------------------- STANDARDWARE --
The Import process moves modules from another COPE library or from "outside" the COPE system into the library entered in the "Specification of Import" field. If modules are to be imported from "outside", the dataset name must be supplied. In both cases, member selection lists will be displayed for selection and scrolling. <PF3> must be pressed when all desired selections have been made. In order to assist in the selection of members from shared libraries, a logical IMS system name may be specified if DBDs, PSBs, or application programs are to be imported. This facility allows the use of IMS Stage 1 specifications to control the selection of members from large source libraries. This capability eases the error prone process of manually selecting members for a particular Lsys if the Lsys is a subset of the one that is normally operated in production. An additional filter is available to allow a subset of members in a library to be displayed. If the i/o information about application programs has been added, (refer to Edit Option 5, described later), the information may be used to extract the members from Copylib, MFS, and Program libraries. All members in a library that are not declared as being referenced are not displayed. All members that
are referenced, and which exist from a previous import process, are displayed with the notation "*EXISTS" opposite them. The Import process requires all datasets in "higher" libsets to be allocated. This is because the Import process copies members to the target dataset as well as to higher libraries if the member is missing from them. If a member already exists, the member in the target library is replaced, and the members in "higher" libraries in the promotion sequence are left unchanged. The "validate indexes" option may be used to recover from occasional import failures. Such failures may occur due to system outages or due to lack of directory or DASD space. These problems may result in members being copied to non-entry datasets but not to entry datasets. This condition will result in incorrect operation of the COPE system. All indexes in the entry and non-entry libraries may be synchronized by specifying YES in the VALIDATE INDEXES field. This option should be used only if inconsistencies have been detected between libraries in a specific promotion path. Importing load modules Load modules need not be imported if your installation does not use the full development environment, and the XTSKSWIT installation parameter is set to YES (refer to the COPE for IMS/DC Installation Guide). When XTSKSWIT is YES, you specify the load libraries for each Lsys in Administration option 4.1 (Libset definition). When XTSKSWIT is NO, a special feature of the Import function is the ability to import load modules. Once a load module is detected (from the "Relation" table maintained by the COPE Administrator), a special process is invoked to update COPE tables and copy and rename the load module to the COPE for IMS/DC program library. In addition to the copy process, object code is generated to provide a default DYNX module. This module is used to "direct" the loading of the dynamically-called module that is associated with a particular Lsys. The DYNX is link-edited into the COPE program library. The load module import capability is used to provide a set of load modules to a combined COPE system. These copied modules are replaced if application source is imported and recompiled. This technique avoids having to import and recompile all of the source. Compile options (Option 4) The COPE compile procedures contain symbolic variables. Although default values are provided, users may need to override them to reflect specific module characteristics. If you select Option 4 from the COPE Edit panel, you must specify valid Project, Group, Type and Name values; if you do not, selection screens will be shown. A display similar to the following will result:
41
Figure 15: COPE Compile Option Override screen
EDIT COMPILE OPTIONS - TABLE DATA PANEL ----------- ROW 1 0F 2 -Command ===> Scroll ===> CSR MORE --> COMMANDS: REPORT/SHOOT/POPUP/FIND VIEW.: NONE Rcd(s): S/R/I/D/C/M/DD/RR VIEW.: NONE Rcd PARAMETER ..... COBOL VERSION=2 FOR VS OR 3 FOR VS II ..... LINKEDIT OPTIONS ***** ******************************BOTTOM OF DATA **************
--------------------------------------------------- STANDARDWARE --
If an S is entered next to a row, the data in the row will be displayed on a single panel. The data screen for Compiler Options will appear as below: Figure 16: Compile Option Data Entry screen
EDIT COMPILE OPTIONS - ROW DATA PANEL ------------COMMAND ===> COMMANDS: REPORT/SHOOT/POPUP/FIND VIEW.: NONE
ROW 1 OF 2 -MORE DOWN
ENTER/UPDATE "COMPILE OPTIONS" DATA: PARAMETER....: COBOL VERSION=2 FOR 11 OR 3 FOR VS II VALUE........:
--------------------------------------------------- STANDARDWARE --
The field definitions are as follows:
42
Field PARAMETER VALUE
Usage Contains a short description of the parameter. The description may not be updated. Initially contains the default value. This value may be overridden for the defined module, and automatically substituted in the Compile JCL. Whenever compile options are saved, a panel is displayed to request permission to propagate the new specifications to "higher" levels. If the modules in the "higher" libsets require the same modified specifications, permission should be granted. If the compile options were not changed, or were specific to the current version, <PF3> should be pressed to bypass propagation of the specifications.
Specify program i/o data and handling of unavailable DBDs (Option 5) This option is required if specification of the actions that COPE is to take for not available databases is to be changed. Normally, COPE will not schedule an application if a database is not available, however in IMS Release 2 and later, an option exists for an application to issue an 'INIT STATUS GROUPA' call to allow it to compensate for unavailable databases. If this option is selected for a PSB, specification of the action that COPE is to take may be made. If this option is selected for a program, a similar specification together with many other specifications may be made. To specify the action COPE is to take for a not available database, select the 'PSB-SOURCE-LIBRARY' type for a COPE project and level and select option 5. The following screen will be displayed. It allows specification of YES/NO/FORCE for the PSB. Figure 17: COPE Database Not Available Specification screen
Edit Program changed Info. - Table Data Panel ------ROW 1 OF 1 Command ===> Scroll ===> CSR Commands: FIND/POPUP/REPORT Rcd(s): S/R/I/D/C/M/DD/RR View.: COPYIO View.: none
Rcd ..... *****
PROGRAM UPDATED UPDATED INIT USES NAME DATE TIME STATUS DB2 ABCAF100 92/10/19 371805214 FOR NO *********************** BOTTOM OF DATA *********************
-------------------------------------------------------------------
43
The INIT STATUS field should be changed to YES, NO, or FOR, to indicate the required action. When <PF3> is pressed, the following panel will be displayed requesting the action to be performed for related systems. The actions available are propagation or no propagation to related Lsys's. Figure 18: COPE Database Not Available Action Propagation screen
IO Definition Propagation Control --------------------------------Command ===> PRESS "ENTER" TO propagate the new I/O definition to a higher level PRESS "END" TO save the new I/O definition at this level You have just defined new I/O parameters for FTCOPE/COPEA/PSBSRCLB Member ABCAF100
If you press "ENTER" this definition will replace the existing DEFINITIONS for members of the same name at higher levels
If you press "END" the definition will be saved but will not be propagated to higher levels -------------------------------------------------------------------
Generally, with the possible exception of the not available database check modification described above, these specifications are not required for correct operation of COPE. Particular circumstances where they are required are described at the end of this section. The main reason you would want to make these specifications, is to build a "Dictionary-like" facility for documenting the objects used by programs. By "Program I/O" is meant the names of objects input and output to a program, when it is compiled, linked or run. These are:
44
Table 1: Specification of Program I/O Data Numb 1 2 3 4 5 6 7 Specification Init. Call Issued/DB2 Status Switched-to transactions MFS MOD names (screens) Dynamically called programs COPY books or macros MFS MID names (screens) Called program names In or Out Program In/Out Out Out In In In In When Used Compile/Link Run Run Run Compile Run Link
This is not a complete list of all things used by programs. It does not include segments, fields, files, and many other objects named in programs. However, this list contains objects that must be controlled by COPE. COPE automatically fills in most of this information using its parsers. You can use Option 5 to view the Program I/O information filled in by COPE. You can also update this information, but this is not necessary for correct operation of COPE. Selecting Option 5 will result in the following display: Figure 19: COPE Program I/O Specification Selection screen
EDIT - SELECT OPTION ------------------------------- ROW 1 OF 7 -Option ===> YOU MAY: SELECT WITH S. POINT AND SHOOT, OR ENTER NO OR NAME ABOVE. NO. 1 2 3 4 5 6 7 NAME SET SWI MOD LOD CPY MID CAL DESCRIPTION ENTER/UPDATE ENTER/UPDATE ENTER/UPDATE ENTER/UPDATE ENTER/UPDATE ENTER/UPDATE ENTER/UPDATE REDQ PROGRAM CHANGED INFO. Y MESSAGE SWITCH TRANSACN'S OUTPUT MOD'S FROM PROGRAM DYNAMIC PROGRAMS LOADED CALLED COPYLIB MEMBER INPUT MID NAMES CALLED PROGRAM NAMES LMT 1 CNT 1 0 0 0 8 0 1
--------------------------------------------------- STANDARDWARE --
45
For COBOL and Assembler, COPE automatically fills in most Program I/O information, but you can manually view or modify all or some of it. The types of information are described below. In each case, descriptive text can be entered alongside the name of the object used by the program. Name 1 - SET Description Init. Call Issued, DB2 status. Whether a program uses DB2 or not is filled in by the COPE parser automatically, and is used by COPE when generating the DB2 compile. The Init. Call may be set to YES, NO, or FORCE. If YES, an "Init. Status GroupA" DL/1 call must be issued as the first non TP call, otherwise the program will be terminated if a stopped database exists. If NO, the program will not be scheduled if any database is unavailable, and a message will be sent to the originating terminal. If FORCE, the program will always be scheduled irrespective of whether an "Init. Status GroupA" call is issued. 2 - SWI Switched-To trancodes. This is documentation only; it is not automatically provided, nor is it needed. Future releases of COPE may provide this automatically. 3 - MOD MFD MOD names. This is filled in automatically by COPE by the "Capture Load" facility, which is described under "COPEUTIL", in the COPE for IMS/DC Administration Guide. Manual MOD name specification is not needed by COPE for correct operation, but if you pre-specify them, there is a slight performance benefit for the IMS online system. 4 - LOD "Loaded", or dynamically-called program names. This is filled in automatically by COPE by the "Capture Load" facility, described in the COPE for IMS/DC Administration Guide. Manual specification is not needed for correct operation. If the dynamically loaded module names are prespecified, there is a slight performance benefit for the IMS online system. 5 - CPY COPY books, or Macros. This is filled in automatically by the COPE parser, for COPY books in COBOL and for COPY books and Macros in Assembler. Manual specification is not required for correct COPE operation, unless your COPE administrator has chosen to define MACLIBs as Shared Storage Datasets, which is normally not recommended. Consult your COPE administrator for further details. 6 - MID MFS MID names. Documentation only - not required for COPE operation. 7 - CAL
46
Statically-called programs.
This is filled in automatically for COBOL by the COPE parser, and for Assembler, if CALL macros are used. For Assembler, if V-types are used directly, this information must be specified manually. Note: There is also a special requirement for statically-called modules which have multiple entry points. Refer to the COPE for IMS/DC Administration Guide for further details. In the special cases where you must enter Program i/o information (these cases are listed at the end of this section) you can enter it either using Option 5, or, more conveniently, using special Edit commands. These commands are entered on the command line when you are editing the program source. The special edit commands are as follows: Command LOOK Explanation Review Program I/O Data. Typing LOOK in the command field, displays the I/O Specification selection panel. Data may be viewed and entered in the same way as from the COPE Edit Option 5. PARSE COB Parse a COBOL program. Typing a command of "PARSE COB" or "PARSE ASM" invokes the COBOL or Assembler parser, which extracts COPYLIB member names and "Static" module names from the source. PARSE ASM Parse an Assembler program. Typing a command of "PARSE COB" or "PARSE ASM", invokes the COBOL or Assembler parser, which extracts COPYLIB member names and "Static" module names from the source. A O modname Add modname to i/o specification. Typing A (Add) followed by O, I, C, L or S, followed by a name, causes entry of the MOD name in the appropriate portion of the i/o specification table. Duplicate names are always eliminated. A I midname Add midname to i/o specification. Typing A (Add) followed by I, followed by a name, causes entry of a MIDNAME to the appropriate portion of the i/o specification table. Duplicate names are always eliminated and any description is preserved. A C copylib-name Add a copylib name to i/o specification. Typing A (for ADD) followed by C, followed by a name, causes entry of
a Copylib to the appropriate portion of the i/o specification table. Duplicate names are always eliminated and any description is preserved. A L subroutine-name Add called subroutine name to i/o specification. Typing A (for ADD) followed by L, followed by a name, causes entry of a subroutine to the appropriate portion of the i/o specification table. Duplicate names are always eliminated and any description is preserved. A S transaction-name Add switched transaction name to i/o specification. Typing A (for Add) followed by S, followed by a name, causes entry of a transaction to the appropriate portion of the i/o specification table. Duplicate names are always eliminated and any description is preserved.
Cases when Program I/O Data must be Specified Manually As stated above, you do not normally need to enter anything in Option 5 to make COPE work. However, your COPE Administrator may choose to have you use Option 5 in the following special circumstances: 1. If your COPE Administrator wants complete "Dictionary-like" information kept for programs, you may have to fill in program i/o information fully. Option 5, and the Edit commands are a convenient way to record this information. You can enter descriptive text against each object. If you use Option 5 for documentation purposes, you need to be aware of the things COPE fills in automatically (described above), so that you do not unnecessarily duplicate the effort. When initially installing COPE, your COPE Administrator may ask you to enter MOD names and LOD (dynamically called program) names through option 5, or via the "A" Edit commands. This is because these two pieces of information are not available to COPE until COPE has run the program at least once under online COPE for IMS/DC . COPE performs correctly, but slightly more slowly if the information is not "pre-entered". Thus there is a performance benefit from entering MOD and LOD data, for new programs. If your Administrator has elected to define Assembler MACLIB's in Shared Storage Datasets, you will have to enter the names of "inner macros" (as "CPY" names, even though they are Macros, not COPY books) for assemblies to work. Normally, it is recommended that Assembler MACLIBs be defined as Non-shared Storage Datasets because of the extra work involved when they are placed in the "Shared" (that is, COPE-renamed) variety. Similar requirements apply for languages and program generators not directly supported by the COPE parsers (e.g. Metacobol). Ask your Administrator for more information. Assembler programs which statically call subroutines without using a CALL macro (for example, using V-types, or other macros) must have their "CAL" data entered. If omitted, the linkedit will fail.
2.
3.
4.
48
Parse all unparsed members (Option 6) COPE obtains information about the IMS environment by parsing PSB, DBD, and MFS source members. In addition, COPE can parse application programs to extract the COPYLIB member names and MACRO usage (in the case of Assembler). If any of these modules are modified by the ISPF Editor outside the COPE environment, Option 2.6 allows all such modified modules to be detected and reparsed to ensure that the information is in synchronization with that input to IMS. If this option is selected, a background job is generated to compare the index entries and reparse any modules that are inconsistent. If all modules are to be parsed irrespective of their current status, the PALL command is entered to cause a complete reconstruction of all parsed information. This option is used after a failure of a large import operation due to DASD dataset limitations, or system failure, or to recreate damaged COPE Program i/o information tables. Note: The PALL option should not be used if modules in a "higher" level of libset are not identical with those in the specified libset.
Edit/Browse DL/1 calls (Option 7) Figure 20: Edit/Browse DL/1 Calls screen
------------------ IMS ONLINE TRACES - COPE SYSTEM ---------------Command ===> BLANK - DL/1 CALL TRACE T - TRANSACTION ACTIVITY (`COPE TRACE ON' UNDER IMS) (PICTURE OF TRANSACTIONS BY REGION)
LTERM LINES EDIT/BROWSE
===> DFTI8L07 ===> 500 ===> B
* - ON END FOR GENERIC (MAXIMUM TO DISPLAY) E OR B
Optional Range Restriction: From Date ===> 891130 From Time To Date ===> 891130 To Time Optional Filters: Trancode ===> * Display ===> N
===> ===>
(Blank, or HHMM) (Blank, or HHMM)
* - on end for generic N - no calls, S - summary, D - details
--------------------------------------------------- STANDARDWARE --
49
The information for DL/1 Calls is extracted from the IMS system log. The number of records extracted is determined from a combination of the "Lterm", and "Lines" parameters on the panel shown above. The Lterm specification may end with an asterisk (*); this indicates any combination of characters. If an asterisk is entered as the only character, all calls from all terminals will be extracted and displayed. The "Lines" parameter limits the display of DL/I calls to the number specified. The Edit/Browse parameter specifies whether ISPF Edit or Browse is entered. If Browse is used, long lines (> 256 characters) can be displayed. If Edit is used, edit commands such as X and Find may be used, and edit macros used to scan the DL/1 information. The 'Optional Range Restrictions' are used to limit the search time for records. The 'Optional Filters' increase the readability of the extracted trace records by removing detail. For full details of the call trace display, refer to "Trace display for MPP programs (ISPF option 7.2)" on page 118. Jobcard parameter specification (Option J) Before any compiles are submitted, the JOB card parameters must be reviewed for correctness. These parameters are saved in the ISPF Profile pool and must be entered once by every user. The J option results in the following display: Figure 21: COPE Jobcard screen
------------------ COPE SYSTEM - JOB CARD SPECIFICATION ----------Command ===> COPE ===> ===> ===> ===> JOB CARD: //APPMM5BS JOB (4011,6EC), TB4.DEVL, CLASS=4, // NOTIFY=APPMM5B. MSGCLASS=V, MSGLEVEL=(1,1) /*JOBPARM QUEUE=FETCH /*JOBPARM P=FTI
--------------------------------------------------- STANDARDWARE --
50
COPE Utilities
The Utility selection menu is accessed via Option 3 on the Primary COPE menu. The Selection menu appears as follows: Figure 22: COPE Utility Selection screen
----------------------- COPE UTILITY SELECTION MENU --------------Option ===> 1 2 3 4 5 6 7 8 LIBRARY - Print members, Delete members LIBSET - Allocate Datasets for Libset groups PROMOTE - Promote Members of a dataset EXPORT - Export Members to Dataset or Tape SCAN - Scan a COPE and/or NON-COPE Library for a string REPLACE - Replace members in a COPE Library COMPARE - Compare members of COPE and/or NON-COPE Libraries PDS MAINT - Compress or Expand PDS Datasets
--------------------------------------------------- STANDARDWARE --
The LIBRARY utility The Library utility (Option 1) is used to delete or print PDS members or internal COPE tables. The Library Management Control screen is shown below:
51
Figure 23: Library Management Control screen
---------------- LIBRARY MANAGEMENT - COPE SYSTEM ----------------Option ===> (L, TO LIST LIBRARIES) D - DELETE AN OBJECT P - PRINT AN OBJECT COPE LIBRARY: PROJECT LEVEL TYPE NAME ===> TFTPROD ===> TFT411 ===> JCL ===> ===> NO (YES/NO) (WARNING DELETES FROM HIGHER LEVELS)
INCLUDE CONCATENATED LIBRARIES
CONFIRM DELETE ===> YES (YES/NO) --------------------------------------------------- STANDARDWARE --
To delete a PDS or COPE ISPF table, enter a D in the command field. To print a PDS member or COPE ISPF table, enter a P in the command field. If YES is specified in the concatenated libraries field, whatever libraries are concatenated will be automatically included in the set of members being deleted or printed. NOTE: Modules can be deleted only from entry libsets. On initial entry to the panel, the "WARNING" message will be blinking. Pressing the <Enter> key without entering anything in the command field will cause it to stop blinking. The blinking warning message is meant to induce caution when using the delete functions. The PROMOTION utility The Promotion utility (Option 3) is used to copy a member from a given libset to a "higher" libset.
52
Figure 24: Promotion Data Specification screen
------------------- PROMOTION MANAGEMENT - COPE SYSTEM -----------COMMAND ====> (L, TO LIST LIBRARIES) A R P ALTERNATE COPY REMOVE ALTERNATE COPY DISPLAY PARENT PROJECTS PM PA LIST MODIFIED MEMBERS FOR PROMOTION LIST ALL MEMBERS FOR PROMOTION
COPE LIBRARY: PROJECT ===> CSD GROUP ===> DEVL TYPE ===> MFSSOURC SET ===>
REPLACE EXISTING COPY ===> NO (YES/NO) --------------------------------------------------- STANDARDWARE --
The options allowed on the Promotion panel are: Option A Usage Implements the "Promote Sideways" function. When a "locked" module is edited, the modified version is saved under an alternate name. Use this command if you want the newly modified version to replace the locked version. The replaced module will remain in the locked state. Remove the alternate copy and make the prime module copy the active one. This is used to remove an emergency fix from the system. The SET name field should be left blank to obtain a list of current alternate copies. Use the P Option to display the libset that objects are to be promoted to. A user cannot override the libset in the promote application. The COPE Administrator can redefine the promotion hierarchy in the 4.1 Libset Definition facility. The PM Option displays only members that have been modified. The PA Option displays the names of all members in a Library regardless of whether or not they have been modified.
53
PM PA
Example "P" Option Display When the P or Parent option is entered, a single line display of the libset that is defined to receive the members is shown. An example of this display follows: Figure 25: The "P" Promote Option screen
-DISPLAY OF PARENTS FOR CSD.DEVL ------------ ROW 1 OF 1 ---------Command ===> PROJECT NAME CSD LEVEL NAME TOP
DESCRIPTION HIGH LEVEL TEST PROJECT
--------------------------------------------------- STANDARDWARE --
Example of the PM and PA options. Similar displays result from the PM and PA Options. The PA display may contain more entries than the PM Option. An example of the display follows:
54
Figure 26: The PM and PA Promote screen
-BROWSE INDEX EXTRACT - TABLE DATA PANEL --- MEMBER NOT PROMOTED -Command ===> Scroll ===> CSR ENTER "ERRORS" IN COMMAND FIELD TO SEE REASONS PROMOTIONS FAILED COMMANDS: REPORT/SHOOT/POPUP/FIND VIEW.: ERRORS Rcd(s): "S" VIEW.: P OBJECT OBJECT STATUS CHANGE CHANGE CHANGE
Rcd NAME TYPE EXPTN ..... ABCDF100 MFSSOURC *FAILED ..... ABCD0080 MFSSOURC ..... ABCD0120 MFSSOURC ***** ******************* BOTTOM OF
TIME DATE USER 04:57 89/02/14 APPMM5B 12:56 88/11/09 APPMM5B 23:42 88/10/29 APPMM5B DATA ************************
--------------------------------------------------- STANDARDWARE --
To promote a member, enter P next to the member name. In the example shown, a "*FAILED" status is displayed next to the member ABCDF100. The "*FAILED" indicator would be displayed following an attempt to promote this member. The actual error encountered may be analyzed by entering ERRORS in the command field to receive a scrolling display of all encountered errors for all members. The EXPORT utility The EXPORT utility (Option 4) copies modules from COPE datasets and writes them to a PDS with their original names. The Export panel is displayed below
55
: Figure 27: Export Option Selection screen
--------------- COPE EXPORT LIBRARY SPECIFICATION ----------------Command ===> L - LIST LIBRARY TYPES J - DEFINE JOB CARD E - EDIT GENERATED JCL (FOR TAPE OUTPUT) SOURCE COPE LIBRARY (S): PROJECT ===> CSD GROUP ===> DEVL TYPE ===> MFSSOURC (MAY USE `*' FOR EXPORTING ALL LIBRARIES) MEMBER ===> (MAY USE `*' TO INDICATE ALL OBJECTS) INCLUDE CONCATENATED LIBRARIES ===> (YES/NO) MEMBERS CHANGED AFTER ===> (YY/MM/DD) ------------------------------------------------------------------TARGET SPECIFICATION DATASET NAME ===> OR TAPE ===> (YES/NO) REPLACE DUPLICATE MEMBERS ===> YES (YES/NO) --------------------------------------------------- STANDARDWARE --
Export commands The commands that are allowed are: Command Blank L J E Usage Perform the Export processing. List the Libset Types defined. Review and modify the JOB card parameters (for tape output only). Edit and Submit the generated tape export Job.
When Exporting to a dataset, the module copy is accomplished in the foreground. When Exporting
to a tape, JCL is generated and must be submitted from Edit (by entering the E command). The menu is divided into an input specification part at the top, and an output specification part below the dividing center line. Input specification The COPE Project and Group must be specified and must reflect predefined libsets. If an error is made, selection menus will appear. The Type and Name fields may be specified as asterisk (*) to indicate the exporting of all libraries and all members in the libraries. The type field may only be specified as an asterisk (*) if tape output is requested (TAPE=YES in the Output Specification part). If a single library is to be moved to a dataset, specification of the library type and an asterisk (*) in the name field will accomplish it. If only members that have been modified after a particular date are to be exported, the "MEMBERS CHANGED AFTER" field may be filled in with a valid date. If the field is left blank, all members are exported. Output specification Output may be to a DASD dataset or to tape. If DASD dataset output is requested, an option to either replace or not replace duplicate members is provided. If TAPE=YES is specified, the dataset name and replace option are ignored. The SCAN utility The process of scanning for a string, and then selecting from the set of members containing the string, is implemented in the SCAN utility (Option 5). This utility is necessary because of the renamed members that COPE uses. With the SCAN utility, all displays use external names rather than the COPE internal name. A selection menu allows the scanning of non-COPE libraries. The non-COPE scan utility is identical in operation to the SCAN utility except that it allows scanning of datasets that are not COPE-controlled. It is included as a convenience, and has no special function in the operation of COPE systems. The utility allows searching for a string in Load, CLIST VB, or CLIST FB record formats. The SCAN utility control menu is as follows:
57
Figure 28: Scan Utility screen
----------------------------- SCAN COPE SYSTEM -------------------Command ===> (L, TO LIST LIBRARIES) COPE LIBRARY: PROJECT ===> TFTPROD LEVEL ===> TFT411 TYPE ===> JCL INCLUDE CONCATENATED LIBRARIES ===> NO TEXT STRING TO SCAN FOR: ===> IMSGUNI
(YES/NO)
(QUOTES OPTIONAL AT BEGINNING AND END)
DISPLAY DIRECTORY FOR BROWSE/EDIT, OR PRINT DIRECTORY: ===> DISPLAY (DISPLAY/PRINT) OPTIONALLY YOU MAY CHANGE YOUR PF1 AMD PF2 KEY DEFINITIONS: PF1 ===> F IMSGUNI (IN EFFECT FOR THIS) PF2 ===> F CIF (SCAN/EDIT SESSION ONLY) --------------------------------------------------- STANDARDWARE --
When a scan is completed, a selection list of members that contain the string is displayed, Edit or Browse may be entered by entering E or B next to the members. <PF1> and <PF2> may have commands defined for them on the SCAN menu to allow searching or changing of data to occur with little additional typing. The REPLACE utility The REPLACE Utility (Option 6) provides a means of replacing (not adding to) source members in a COPE libset from an external source library. REPLACE allows source members to be replaced at any libset level.
58
Figure 29: Replace Utility screen
------------------ COPE REPLACE LIBRARY SPECIFICATION ------------Command ===> SOURCE SPECIFICATION: DATASET NAME ===> `TFTPROD.CTF411.JCL'
----------------------------------------------------------------TARGET SPECIFICATION: PROJECT GROUP TYPE ===> TFTPROD ===> TFT411 ===> JCL
--------------------------------------------------- STANDARDWARE --
Enter the external source library name in the dataset name field. When <Enter> is pressed, a selection of modules that exist in the source library with the same names as modules defined to the COPE system will be displayed. All other members will be excluded from the selection list. Appropriate selections may be made, and <PF3> pressed to copy the modules to the target library. The COMPARE utility The Compare utility (Option 3.7) is intended to generate jobs that synchronize COPE environments with external environments or datasets. The utility is most useful for preparing COPE environments during the initial definition of a Psys. Suppose two Lsys's have been defined in a sibling arrangement as follows:
59
Figure 30: Lsys Sibling Relationship Example
LSYS 1
LSYS 2
LSYS1 is the parent of LSYS2, that is, whenever any module is imported into LSYS1, COPE will check LSYS2 and automatically make a copy of the module in LSYS2 if there is not one there (the copy is a virtual one). Suppose that there are two external datasets with DBD's that reflect the specification of LSYS1 and LSYS2 respectively for existing IMS systems. Suppose that the DBD's for LSYS2 are 90% similar to the DBD's for LSYS1. A COPE system would be installed by importing all DBD's into LSYS1 and then running the compare utility to import DBD's that are different into LSYS2. The comparison options are: Compare two datasets and import differences into a COPE library Compare a COPE library with a concatenated set of datasets and import differences into COPE
60
Figure 31: Compare Utility Selection menu
----------------Command ===> 1 -
COPE Compare Selection Menu -------------------
Do you want to compare two datasets and import any differences into a COPE library Do you want to compare a COPE library with a dataset and import any different members from the dataset into COPE to make them identical
2 -
-----------------------------------------------STANDARDWARE INC---
The following menus allow specification of the various parameters and datasets that are required. The compare may be performed either in the foreground, or the background. A job to import differences into COPE may be generated if the appropriate options are selected. The compare of external datasets and import into COPE specification panel is as follows. It allows a dataset to be compared with up to 4 concatenated datasets and the differences noted.
61
Figure 32: Compare two Datasets menu
------ COMPARE TWO DATSETS AND UPDATE COPE WITH DIFFERENCES -----Option ===> ( L, LIST LIBRARY TYPES) CF - FOREGROUND COMPARE (Fill in this panel and press enter) CB - BACKGROUND COMPARE (Fill in this panel and press enter) E - EDIT GENERATED JCL J - SPECIFY JOBCARD Upgrade EITHER COPE Logical System name ===> OR --PROJECT name ===> FTCOPE LEVEL name ===> COPEB Upgrade COPE Library TYPE ===> PSBSRCLB
Dataset that members are to be copied from ===> Processing Options Copy Missing members into COPE Replace different members
===> N ===> N
(Y/N) (Y/N)
-----------------------------------------------STANDARDWARE INC---
The "COPE library compare with external datasets" may be specified with the following panel. If the delete option is chosen, PSB, DBD or MFS generations may be automatically generated if a sibling member still exists. For example, if a member of the same name exists in LSYS1 and LSYS2, and it is deleted from LSYS1, a regeneration of the member from LSYS1 will be performed.
62
Figure 33: External Dataset Compare menu
----------- COMPARE COPE WITH EXTERNAL DATASET CONTENTS ---------Option ===> ( L, LIST LIBRARY TYPES) CF - FOREGROUND COMPARE (Fill in this panel and press enter) CB - BACKGROUND COMPARE (Fill in this panel and press enter) E - EDIT GENERATED JCL J - SPECIFY JOBCARD FOR COPE Logical System name OR PROJECT name LEVEL name Compare COPE Library TYPE ===> ===> FTCOPE ===> COPEB ===> PSBSRCLB
Processing Options Copy Missing members into COPE Replace different members Delete Extra members from COPE
===> N ===> N ===> N
(Y/N) (Y/N) (Y/N)
--COPECCOM-------------------------------------STANDARDWARE INC---
The PDS MAINT utility The PDS MAINT utility is used to generate compress jobs for PDS libraries. It may also be used to generate JCL which allocates a new dataset with different attributes, performs a copy and then renames the new dataset to the original name after deleting the original. Additional features include the capability to review the space available on a volume, as well as identifying a set of volumes to scan for dataset reallocation. Options allow specification of COPE or non-COPE Libraries. The main panel is as follows:
63
Figure 34: PDS Maint Option menu
--------------- Display Dataset Attributes for Re-allocation -----Option ===> Press ENTER to display Dataset Attributes after entering Dataset name J - Jobcard C - Compress E - Expand S - Specify VOLSERs for allocation of datasets
Dataset Name
===> 'TFTPROD.COPE.MANUALS' Dir Space Used ===> 10 Tracks Used ===> 75 Primary Amount ===> 5 Recfm Lrecl CYLS 27 1 ===> FB ===> 80 Members Extents Secondary ===> 40 ===>2 ===>1
Dir Space Alo ===> 30 Tracks Allo Alloc. Unit Dsorg Blksize ===> 90 ===> CYLS ===> PO ===> 6400
Free Space: FTI840 TRACKS Size: 1159 Largest: 29
--------------------------------------------------- STANDARDWARE --
The commands that are allowed are: Command J C(ompress) E(xpand) S Usage Specify job card parameters. Generate JCL to compress a dataset Generate JCL for reallocating and copying datasets with new attributes. Specify DASD volumes to be used to receive expanded datasets
The field next to the "Free Space" description may be changed at any time to enquire on the free space on any specified volume. If the E option is then specified, the selected volume will be used if it has sufficient space to hold the dataset.
AMBLIST and Load Module Dates

Whenever details about a load module are required, the IBM AMBLIST utility provides a decomposition of the load module's records. COPE provides an application in which load modules are scanned for the linkedit date and whether or not the module uses DB2. This information is then extracted and displayed. If greater detail is required, a series of selections may be made and AMBLIST JCL generated and submitted for execution. The application is accessed by typing LOAD on the primary COPE menu. The following menu is presented: Figure 35: Load Module Specification screen
----------------Command ===>
Display load library attributes ----------------
J Specify Jobcard E Edit Generated AMBLIST JCL ISPF LIBRARY: Project ===> Group ===> Type ===> Name ===>
TFTPROD COPE LOAD C*UJ
===>
===>
===>
Dataset
===>
--------------------------------------------------- STANDARDWARE --
Note the use of the member selection mask specification. When <Enter> is pressed, the following display of the load module linkedit date and DB2 usage is shown. This panel may be used to select members for AMBLIST JCL generation, by entering an S next to the desired member name.
65
Figure 36: Load Module Attribute screen
SELECT MEMBERS AND PRESS 'END' TWICE TO EXIT ---------- ROW 1 OF 2 Command ===> SCROLL ===> CSR NAME STATUS . COPEALUJ . COPERCUJ USESDB2 ENTRY COPEBA11 DFSRRC00 LINKEDIT DATE 92/11/13 92/11/13
--------------------------------------------------- STANDARDWARE --
IMS Online Facilities

The IMS Online facilities are accessed from Option 7 on the COPE primary menu. The Selection menu appears as follows: Figure 37: IMS Online menu
-------------------------- COPE - IMS Online ---------------------Option ===> 1 2 3 4 Commands Trace Display Xpediter - COPE Xpediter Trace Display
User(s) ===> DFTI6L22 Logical Sys ===> TFT4 Stubx Lib IMSid Physical ===> T.COPE.COPEPGM ===> CIMSW ===> IMSW
--------------------------------------------------- STANDARDWARE --
66
The IMS commands facility You can issue IMS commands, such as /STA DC, /DIS DB, etc. from ISPF in option 7.1. The IMS trace display You can display your call trace from option 7.2 (formerly option 2.7). Refer to "Trace display for MPP programs (ISPF option 7.2)" on page 118 of this manual. Xpediter support feature This is an optional COPE feature that will not appear if the feature is not installed. Xpediter is an interactive debugger sold by Compuware. It intercepts IMS transactions and directs them to an MPP region executing under ISPF. The programmer can set breakpoints, view and change working storage, and see the results of execution as the program is running. Xpediter, without COPE, intercepts transactions by changing the transaction class. The class is the same as that used in the ISPF MPP region. The consequence of this approach is that all transactions from all users of the IMS system get directed to the testing region. This can cause problems in a shared environment. COPE provides additional support that allows only transactions entered from a specific terminal to be directed to a test region operating under ISPF. All other transactions with the same transaction code that are initiated from other terminals or application programs, remain unaffected, and continue to execute in the normal way. Xpediter Setup Xpediter has several features. Exits must be specified to Xpediter and certain datasets must be added to the STEPLIB before execution is attempted. The PSB and DBD library definitions must be changed, and the dynamic PSB library added to. The PSBLIB and DBDLIB datasets used by COPE must also be changed. Xpediter must be invoked under COPE so that the correct LIBDEF definitions are in place for correct execution. The COPE Xpediter exits are specified as follows. On the primary panel type in 'DEF'.
67
Figure 38: Xpediter Primary menu
----------------- XPEDITER/TSO 5.3 - PRIMARY MENU ----------------OPTION ===> DEF 0 DEFAULTS - Specify defaults 1 ALLOCATE - Create and maintain file allocation lists 2 XPEDITER - Debug and test applications interactively 3 UTILITIES - Perform utility functions 4 BATCH - Submit jobs and connect to a batch region 5 N/A - Connect to a CICS region B BULLETIN - Display release announcement T TUTORIAL - Display information on Compuware products X EXIT - Exit primary menu Profile ===> DEFBTSC - BTS PROFILE Copyright (c) 1992 by Compuware Corporation. All rights reserved. (800) 538-7822 ADS - (800) 538-7822 Press ENTER to Process or Enter END Command to Terminate
On the resulting panel, enter Option 6 as shown: Figure 39: Xpediter Installation Options screen
Profile: DEFBTSC ---- STANDARD INSTALLATION OPTIONS ---------------OPTION ===> 6 1 OPTIONS - Basic Options 2 NEW - New Data Set Allocation Defaults 3 PRODUCT - Product Data Sets 4 WORK - Work File Allocations 5 PRINTERS - Local Printer Options 6 EXITS - Exit Routines 10 COMPILE - Compile and LinkEdit Processors 13 PRODUCT2 - Product Data Sets (2) A ALL - Display All Of The Above In Succession Press ENTER to Process or Enter END Command to Terminate
68
Select Option 2 (Execution Time Exit Routines) as shown: Figure 40: Xpediter Exit Routine screen (1)
Profile: DEFBTSC ----------- EXIT ROUTINES -----------------------Option ===> 2 1 GENERAL - General Purpose Exit Routines 2 EXECUTION - Execution Time Exit Routines A ALL - Display All Of The Above In Succession Press ENTER to Process or Enter END Command to Terminate
If you have only the BTS feature of Xpediter ONLY specify the BTS exits. DO NOT specify the IMS exit.
Figure 41: Xpediter Exit Routine screen (2)
Profile: DEFBTSC --------- EXIT ROUTINES (2) ---------------------COMMAND ===> STANDARD EXIT: (Executed every STANDARD or DIALOG test session) Before Test ===> PGM(COPEXPP1) PARM(01) After Test ===> PGM(COPEXPP1) PARM(02) IMS EXIT: (Executed every IMS test session) Before Test ===> PGM(COPEXPP1) PARM(03) After Test ===> PGM(COPEXPP1) PARM(04) BTS EXIT: (Executed every BTS test session) Before Test ===> PGM(COPEXPP1) PARM(05) After Test ===> PGM(COPEXPP1) PARM(06) MPP EXIT: (Executed every XPEDITER/IMS MPP test session) Before Test ===> PGM(COPEXPP1) PARM(07) After Test ===> PGM(COPEXPP1) PARM(08) BMP/IFP EXIT: (Executed every XPEDITER/IMS BMP/IFP test session) Before Test ===> PGM(COPEXPP1) PARM(09) After Test ===> PGM(COPEXPP1) PARM(10) HOGAN EXIT: (Executed every HOGAN test session) Before Test ===> PGM(COPEXPP1) PARM(11) After Test ===> PGM(COPEXPP1) PARM(12) Note: Changes made to this screen override installed defaults Press ENTER to Process or Enter END Command to Terminate
Before executing BTS, several library specifications must be made for correct operation of the product. To do this, enter 'SE' on the transaction specification panel as shown below. Figure 42: Xpediter BTS Setup screen
Profile: DEFBTSC ------ XPEDITER/TSO - BTS (2.4) ------------------COMMAND ===> SE COMMANDS: SEtup (Display Setup Menu) BTsin (Display BTSIN Menu) Down (Scroll Down) INTERCEPTS Row 1 of 2 PROGRAM TRANCODE INITSCR POSTSCR START MAX ===> CIF41445 ===> CIF ===> ===> ===> ===> ===> ATC39110 ===> ATC002 ===> ===> ===> ===> ===> ===> ===> ===> ===> ===> BTSIN ===> 'DPC01.COMMON.JCL(DAVEEVAN)' Program Type ===> BMP (, BMP, DLI) PARM Passing Option ===> STD (STD) File Allocation List ===> Press ENTER to Process or Enter END Command to Terminate
The IMS RESLIB and the COPE PGMLIB must be added to the STEPLIB definitions as follows
70
Figure 43: Xpediter Test Setup menu
Profile: DEFBTSC ---- XPEDITER/TSO - TEST SETUP MENU ---------------OPTION ===> 1 0 ENVIRONMENT - Execution environments menu 1 LOADLIBS - Application load module libraries 2 SIR - Shared Information Repository libraries 3 INCLUDES - Test script libraries 4 LOG - Session log data set disposition 5 SCRIPT - Test script data set disposition I IMS - IMS setup options menu B BTS - BTS setup options menu A ALL - Display all of the above in succession (except 0) Press ENTER to Process or Enter END Command to Terminate
71
Figure 44: Xpediter Loadlib Specification screen
Profile: DEFBTSC --- XPEDITER/TSO - LOAD MODULE LIBRARIES ----------COMMAND ===> COMMANDS: DOWN (for additional User Libraries) User Libraries: (1) ===> 'IMS.TEST.RESLIB' (2) ===> 'IMS2.PGMLIB03' (3) ===> 'IMSVS.TEST.COPE.PGMLIB' (4) ===> (5) ===> (6) ===> (7) ===> (8) ===> Installation Libraries: Changes made to this list override installed default (9) ===> 'TSTLIB01' (10) ===> 'SYS1.XPEDITER.LOADLIB' (11) ===> (12) ===> (13) ===> (14) ===> (15) ===> (16) ===> Press ENTER to Process or Enter END Command to Terminate
The COPE/Xpediter interface receives it's knowledge of what system the user is executing in from the IMSID field in the IMS PARM field specification. This field must be changed to reflect a token which identifies the Lsys. This token is the same as that specified in option 4.9;2 and may be used for BMP and batch jobs to identify the Lsys in the same way. An example of the specification of an Lsys token to BTS Xpediter follows.
72
Figure 45: Xpediter Test Setup menu
Profile: DEFBTSC ----- XPEDITER/TSO - TEST SETUP MENU --------------OPTION ===> B 0 ENVIRONMENT - Execution environments menu 1 LOADLIBS - Application load module libraries 2 SIR - Shared Information Repository libraries 3 INCLUDES - Test script libraries 4 LOG - Session log data set disposition 5 SCRIPT - Test script data set disposition I IMS - IMS setup options menu B BTS - BTS setup options menu A ALL - Display all of the above in succession (except 0) Press ENTER to Process or Enter END Command to Terminate
Figure 46: Xpediter BTS Setup menu
Profile: DEFBTSC ------ XPEDITER/TSO - BTS SETUP MENU --------------OPTION ===> 1 1 PARMS - BTS processing types and parameters 2 BTSLOAD - BTS load libraries 3 FORMAT - MFS libraries 4 BTSOUT - BTS output listing file 5 BTSPUNCH - BTS regression test input file 6 BTSDEBUG - BTS debug output file 7 QIOPCB - Work file for output message queue (IOPCB) 8 QALTPCB - Work file for output message queue (ALTPCB) 9 QALTRAN - Work file for alternate PCB output A ALL - Display all of the above in succession Press ENTER to Process or Enter END Command to Terminate
In this example a token of 'TRAINING' identifies an Lsys. This token is placed in the position shown.
73
Figure 47: Xpediter BTS DL/1 Parameter List screen
Profile: DEFBTSC ---- XPEDITER/TSO - BTS PARAMETER LISTS -----------COMMAND ===> TYPE PARM LIST (1) ===> ===> (2) ===> BMP ===> BMP,,,N00000,,,,,,,,TRAINING,TESTPSB (3) ===> DLI ===> DLI,7,0000,,0,,N,0,T,,,N (4) ===> ===> (5) ===> ===> (6) ===> ===> (7) ===> ===> (8) ===> ===> Note: This list contains overrides to installed defaults Press ENTER to Process or Enter END Command to Terminate
If batch or BMP jobs are to be executed, a similar requirement exists for the IMS parameter specification. Again the IMSID field must contain the token which identifies the Lsys the job is to be executed against. Figure 48: Xpediter Test Setup menu
Profile: DEFBTSC ----- XPEDITER/TSO - TEST SETUP MENU --------------OPTION ===> I 0 ENVIRONMENT - Execution environments menu 1 LOADLIBS - Application load module libraries 2 SIR - Shared Information Repository libraries 3 INCLUDES - Test script libraries 4 LOG - Session log data set disposition 5 SCRIPT - Test script data set disposition I IMS - IMS setup options menu B BTS - BTS setup options menu A ALL - Display all of the above in succession (except 0) Press ENTER to Process or Enter END Command to Terminate
The COPE PSBLIB and DBDLIB datasets must be specified for BTS and IMS. In addition the dy74 COPE for IMS/DC Programmers Guide
namic PSBLIB dataset must be specified as shown in the following panels. Figure 49: Xpediter IMS Setup menu
Profile: DEFBTSC ------ XPEDITER/TSO - IMS SETUP MENU --------------OPTION ===> 3 1 PARMS - IMS processing types and parameters 2 DFSRESLB - IMS authorized load libraries 3 IMS - PSB and DBD libraries 4 IMSACB - ACB libraries 5 PROCLIB - IMS PROCLIB containing the preload list 6 IEFRDER - IMS logging and recovery data set 7 IMSMON - IMS DB monitor data set 8 DFSVSAMP - VSAM shared resource pool data set 9 IMSERR - IMS error data set A ALL - Display all of the above in succession Press ENTER to Process or Enter END Command to Terminate
Figure 50: Xpediter PSB/DBD Libraries screen
Profile: DEFBTSC ----- XPEDITER/TSO - PSB/DBD LIBRARIES ------------COMMAND ===> PSB/DBD Library DSNAMEs (DDNAME IMS): (1) ===> 'IMSVS.TEST.PSBLIB' (2) ===> 'IMSVS.TEST.DBDLIB' (3) ===> 'IMSVS.TEST.COPE.PSBLIBD' (4) ===> (5) ===> (6) ===> (7) ===> (8) ===> (9) ===> (10) ===> (11) ===> (12) ===> Note: This list contains overrides to installed defaults Press ENTER to Process or Enter END Command to Terminate
75
Xpediter supports BTS and IMS interactive debugging. If BTS is used under COPE, COPE will translate the control cards and substitute the correct PSB names before execution takes place. Execution of the Xpediter session remains the same once the program that is being tested is invoked. Xpediter IMS Operation To access the Xpediter interactive debugger, first enter the Signon id, or Lterm name that you plan to use against the User(s) arrow on the option 7 screen. This tells COPE which terminal(s) will have transactions sent to your TSO region. Next, note the STUBX Lib, Dopt PSBLIB, DBDLIB and IMSid shown on the option 7 screen. You will need these later, to put in Xpediter's Setup Loadlibs, PSBLIB/DBDLIB concatenation for GSAM, and PARM. Next, select option 3, and follow the Xpediter menus to IMS test (2.3), MPP test (2.8), or BMP Test (2.9). The following menu will be displayed for MPP Test: Figure 51: COPE Xpediter Interface screen
COMPUWARE-------------------- TEST (MPP) --------------------------COMMAND ===> COMMANDS: SETup (Display Setup Menu) INTer (Display Intercepts)
INTERCEPTS PROGRAM TRANCODE INITSCR POSTSCR ===> ===> ===> ===> ===> ===> ===> ===> ===> ===> ===> ===> File Allocation List ===> NBA ===> OBA ===> Is This a DB2 Test? ===>
START MAX ===> ===> ===> ===> ===> ===>
(Normal Buffer Allocation) (Overflow Buffer Allocation)
--------------------------------------------------- STANDARDWARE --
1.
76
Type SE for Setup. Make sure the load libraries include the COPE PGMLIB (STUBXs Library)
specified in the XCOPEPGM variable in ZDEFAULT and shown on the COPE option 7 entry screen as STUBXs Lib. Make sure your IMS Region Id, in the PARM setup, matches the one that appears on the Option 7 screen. There are 13 commas preceding the Region Id. <PF3> back to the program/trancode screen. 2. 3. Fill in Program (PSB) and/or Trancode(s), as in regular Xpediter. Press <Enter>, and you will see "*** The COPE intercepts are being set ***", then the Xpediter messages. Go to IMS and enter your Transaction. When the transaction is "caught", you will see "Before Stubx" in the top right-hand corner.
Figure 52: Xpediter Initial Test screen
Source: ------------------- LOG ------------------- Before STUBX COMMAND ===> SCROLL ===> HALF NO SIR - QUIT TO TERMINATE OR USE EXPLICIT SOURCE COMMAND ******************************************************************* ----------------------------------------------------------------JOB: CB0DEVA XPEDITER/TSO RELEASE 5.01.00 CUSTOMER 002575 STEP: LPROC TAPE CREATE DATE 91065 DATE: 03/14/92 TIME: 11.06.25 ----------------------------------------------------------------XPED MSG *** IMS TRANSACTION CODE C0008435 LTERM NAME CB0DEVA MEMBER C0008435 INTERCEPT C0008435 TRANCODE C0008435 PARM 'MSG,031000000000,N00000000,,,,,,,,0,0,IMSID' XPD0523 RA151 NO SIR DATA SET MEMBER FOR STUBX ************************* BOTTOM OF DATA ************************** -------------------------------------------------------------------
From here, continue as under regular Xpediter (SOURCE, set breakpoints, GO etc). Multiple users can test with the same Trancode/program, and they will not be aware of each other. There is a limit to simultaneous users in Xpediter itself, and another limit in COPE that depends on trancode type. Both these limits can easily be raised by your System Administrator. Multiple users can test the same BMP without being aware of each other.
Problems running Xpediter 1. 2. Check that you have all the program libraries you need in SE.1 (Loadlibs). These DO require quotes around them. Under ISPF watch out for CSV msgs, such as: CSV003I REQUESTED MODULE RP145PSB NOT FOUND This message means that the module is not in your SE.1 (Loadlibs). Under IMS, you can find out which library the module is in by issuing VERSION RP145PSB (for example) from the COPE screen: RP145PSB link-edited 91/09/05, dsn=EMVSP.IMSVS.PGMLIB This refers to the IMS (non-Xpediter) message regions. You would fix the problem under Xpediter by putting EMVSP.IMSVS.PGMLIB in your SE.1 list, in this example. 3. Under IMS, after an Xpediter abend, you will get the COPE abend summary screen, which is a compact summary of the abend. This is explained in the General Information section of the Tutorial. Press <Clear> and <PA1> to eliminate this screen. When you start your Xpediter test, you will see "Before Stubx" in the top right hand corner, and "No SIR data for Cnnnnnnn". Ignore these references to COPE's internal STUBXs; do a SOURCE on your program and proceed normally. If you QUIT out of Xpediter, you get message "IMS User xxxxxxxx quitted". From this point on, IMS transactions from your terminal will not be sent to your Xpediter TSO region. If you go back in under TSO, it is from "The COPE intercepts are being set" point, that transactions will be sent from your terminal to your Xpediter TSO region. If you quit, COPE checks and unlocks your IMS terminal. It produces a message "IMS User xxxxxxxx terminal is being unlocked". If you accidentally lock your IMS terminal in other situations, you can unlock it from TSO by issuing command: TSO UNLOCK from the command line of an Xpediter screen. 7. If your transaction ends, and you type GO, you have to go to IMS and enter another transaction. There is no "setting IMS intercepts" message after the first transaction. This is exactly how Xpediter works under non-COPE. To see your own intercepts, go to IMS, and type "XP" from the COPE screen (or "COPE XP" from a cleared screen): Intercept #1 XP BC0CSWE 16:33 Thu Jan 23 CHIPSRD
4.
5.
6.
8.
User=BC0CSWE Tran Xtran C-Psb RCAPHDC C0008435 C0032091 Here, user BC0CSWE started their last Xpediter test at 16:33 on trancode RCAPHDC. The Cnumbers are the internal trancode and psb that COPE uses. 9. To see who is using Xpediter, under IMS type "XP ALL" from the COPE screen.
10. To unhang a TSO terminal, go to IMS. If that is also hung, Terminate and re-enter. /DIS A and /STO REG n, for your id. 11. For a DLI or DBB test, if the PSB is an online one, you can use the non C-number name on the 2.3 panel. If the PSB is batch-only, you need to use the C-number psb name, and C-number "Load Module name" in 2.3. This will be fixed in a future COPE release (so that you don't have to use the C-number even for batch-only). 12. For MPP and BMP tests, COPE defaults to giving you a "Database xxxx is Stopped" message, if a database is unavailable. For DLI/DBB tests (under TSO only), it bypasses the check for databases stopped, because it is probably due to you leaving the database out of the file allocation list. The Trace (7.4) shows "NA" or "NU" against the pcbs that are stopped. 13. If your BMP or MPP program can process NA and NU status codes, you can turn off the "Database Stopped" message in COPE ISPF 2.5 (This needs a 4.7 Psbgen and 4.8 Acbgen, to take effect).
79
Convert JCL for an Lsys

COPE changes PSB and DBD and DD names so that they may share a common Psys. This has the effect of making BMP and batch programs inoperative without changing the appropriate fields in the EXEC Parm parameter and the DD names associated with the DBD's referenced by the PSB. COPE allows two methods of providing this translation: 1. Execution time conversion by means of substituting the DLI program DFSRRC00 with a COPE program of the same name. The COPE program makes the appropriate changes and then calls the DLI DFSRRC00 region controller. Explicit conversion via a JCL parser and regenerator. This results in the modification of all JCL parameters for a JOB which may then be submitted for execution in a COPE environment.
2.
Execution time Unconverted JCL Option The COPE for IMS/DC Administration Guide describes the procedure by which Psys and Lsys systems are identified by a token, and the DLI DFSRRC00 module relinked to provide an intercept. The XCONVJCL ZDEFAULT variable must be set to NO. Within an installation, there may be many Psys's with many Lsys's defined for each. It is the responsibility of the application programmer to identify the Psys and Lsys that the BMP or batch program are to operate in by specifying an identifying token in one of the following positions: 1. 2. 3. In the IMSID parameter of the Job PARM statement. (the 14th parameter). In the programmer's name field of the job card, (the second positional job card parameter). In a special DD card of the form //COPEBSYS DD DSN=&&TOKEN,UNIT=SYSDA,SPACE=(TRK,(1)) The new DD statement may be inserted anywhere in the job stream, alternatively, an IEFBR14 step may be added. Whenever a step with a PGM=DFSRRC00 statement is executed, the job step Parm IMSID is scanned, followed by the Programmer name field, followed by a scan for COPEBSYS DD cards. Once a Psys/Lsys combination has been identified, the appropriate translations and reallocations are made. NOTE: COPE does not translate dataset names for an Lsys. If database dataset names are defined in the JCL they must refer to the databases associated with the Psys/Lsys identified by the method described above.
Explicit JCL conversion This Option is made available when the XCONVJCL ZDEFAULT variable is set to YES. The Convert MSG/BMP/Batch JCL facility is used to convert JCL for an Lsys. The process changes all references to COPE controlled objects in the JCL, to names appropriate for execution in the COPE environment. In addition to converting JCL, there exists a capability to change control cards for utilities such as backup and restore, where DBD names are encoded in them. This is done via the EO option described below. To convert JCL, go to option 4.9, from the COPE primary menu. Two ways are provided to import, parse and regenerate JCL. They are controlled by the XJCLDSN variable in ZDEFAULT. XJCLDSN=NO XJCLDSN=YES Normal option. Import and re-generate occurs in one step Special option. Import, parse, DSN specify, and Generate steps. You should use this option only if you require "cloning" of JCL for many Lsys's.
Both methods do the following: 1. 2. 3. Translate PSB and DBD DD names to internal C-numbers Adjust STEPLIB, IMS and IMSACB DD statements Substitute COPERC00 for DFSRRC00 (if XCDLIBMP=YES)
You normally must convert DFSRRC00 to COPERC00. The only case where you could elect not to do this is when you can guarantee that all programs are insensitive to the DBD names in the PCBs. The option not to use COPERC00 is provided only for downward compatibility with previous releases of COPE. Convert JCL in one step (XJCLDSN=NO) This is the normal way to convert JCL. Go into option 4.9:
81
Figure 53: Convert MSG/BMP/Batch JCL screen
--------------------- Convert MSG/BMP/Batch JCL ------------------Command ===> I I G EG ES EO - Import and Re-Generate JCL - Re-Generate JCL - Edit Generated JCL - Edit Source JCL - Edit non-COPE Online libraries for DBD name conversion, etc J - Specify Jobcard
COPE LIBRARY: PROJECT ===> CSD PROJECT ===> CSD GROUP ===> DEVL NAME ===>
<-<-<--
Must be Libset associated with an Must be Libset associated with an IMS Lsys
--------------------------------------------------- STANDARDWARE --
To convert JCL, follow these steps: J PROJECT/GROUP Enter Libset Check job card The Libset identifier Enter the Project and Group names for the libset that you want to convert in. Must be a libset that has an Lsys (Logical system) associated with it. Leave NAME blank, or blank out. NAME must be blank for importing. Select I and press <Enter>. Specify the dataset name within quotes of the From (source) library. Press <Enter>. Use S to select from the member list. Hit <PF3> when all selections made. Enter the PROCLIB(s) that the JCL uses (the JCL will be generated with instream procs). Hit <PF3>.
I Import From dataset Select members Specify PROCLIB(s)

82
Note job number EG
Note the job number that appears in the top right hand corner. When this job completes, the JCL will have been converted. Generated JCL may be edited with this option. If the member name is entered, edit may be entered directly, otherwise a selection list of available members will be displayed. When a member is being edited, control cards that are associated with in-stream datasets (SYSIN * datasets) are also present. These control cards may have DBD names in them. The names must be changed to the names used by COPE. To do this, an ISPF edit macro has been provided. The macro can be invoked by entering T (for Translate) on the command line. An explanation of the T can always be obtained by pressing <PF1> when in Edit. The format of the T command is as follows:
T Lsys-name (DBD) {label-range} {NEXT} {x} {col1-col2} (DD) {ALL} {NX} (PSB) {FIRST} (PGM) {LAST} {PREV} Lsys-name is the COPE logical system name, and DBD/PSB/DD/PGM defines the internal translate table to access to perform the control card translation. Translation is performed by extracting every word beginning with a character and looking for it in the translate table. It is important to limit the number of lines scanned with the range and column modifiers to reduce the number of searches. If a match is found, the edited line is changed to contain the internal Cnumber name, and the original line is displayed under it as a note. If the translation is incorrect, the note line can be made a "real" statement again by typing the characters MD (for "Make Data") in the line command field. ES EO Editing of the input to the import operation is accomplished with this option. If control cards or other JCL must be altered to contain COPE C-number names, use the EO option. Press <Enter>, and a panel is displayed for entering the non-COPE dataset and member to be edited. The T command (see above) can be used to scan for and alter data.
If EG does not show the correct converted JCL, check the batch job; you probably got an E37 abend,
in which case you should compress the output library and rerun. Convert JCL in multiple steps (XJCLDSN=YES) Follow these steps to convert JCL in multiple steps, with replacement of DSNs according to a DSN list, for "cloning" of JCL to many Lsys's (logical systems): 1. 2. 3. 4. Import the JCL into COPE Parse the imported JCL Specify replacement DSNs Generate the converted JCL
If XJCLDSN=YES, there are additional P and D options on the option 4.9 panel: Figure 54: Convert MSG/BMP/Batch JCL (XJCLDSN=YES)
-------------------- Convert MSG/BMP/Batch JCL ------------------Command ===> I I P D G EG ES EO - Import JCL - Parse JCL (first step) - Define DSNs replaced (second step) - Re-Generate JCL (third step) - Edit Generated JCL - Edit Source JCL - Edit non-COPE Online libraries for DBD name conversion, etc J - Specify Jobcard
COPE LIBRARY: PROJECT ===> CSD GROUP ===> DEVL NAME ===>
<-<--
Must be Libset associated with an IMS Lsys
-------------------------------------------------- STANDARDWARE --
Convert JCL Options The following is an explanation of the options that are available from the option 4.9 screens:
Command I
Explanation Import JCL. Only libraries that contain JCL are eligible for the import operation (The library must be of the JCL "Type"). In addition, as with any import operation, the library must be an "Entry" library. The NAME field must be blank, for option I. You will enter the source dataset name, with an optional member name, on the next screen (not on the option 4.9 screen).
Parse JCL. If XJCLDSN=YES all imported members must be parsed to extract the dataset names.
Define system specific dataset names. After the dataset names have been extracted, a scan is made against the IMS Dynamic Allocation data for a particular IMS system. Any datasets that do not match the Database dataset names, or the DBD, PSB, and ACB libraries, are saved in a table and displayed when the D option is selected. Two columns of information are displayed: "Original dataset names" and "Replaced dataset names". The user has available a "CHNG" command that operates on the "Replaced Dataset names" column only. The CHNG command has a format similar to the ISPF Edit "Change" command as follows: CHNG <from-string> <to-string> {PREFIX/SUFFIX} The prefix/suffix options cause the modification of a string at the beginning or ending of a dataset name and the ignoring of any occurrence of a string elsewhere.
Generate JCL. JCL may be generated for a particular IMS system by selecting the G option. This substitutes the Dynamic Allocation dataset names and the modified dataset names into the parsed JCL and constructs a job that is specific to a COPE for IMS/DC system. The JCL is generated into a dataset that has been specified as a JCG type (JCL Generated type) by the COPE Administrator using Option 4.1.
EG
Edit generated JCL. Generated JCL may be edited with this option. If the member name is entered, edit may be entered directly, otherwise a selection list of available members will be displayed. When a member is being edited, control cards that are associated with in-
85
stream datasets (SYSIN * datasets) are also present. These control cards may have DBD names in them. The names must be changed to the names used by COPE. To do this, an edit macro has been provided. The macro can be invoked by entering T (for Translate) on the command line. An explanation of the T can always be obtained by pressing <PF1> when in Edit. The format of the T command is as follows: T Lsys-name (DBD) {label-range} {NEXT} {x} {col1-col2} (DD) {ALL} {NX} (PSB) {FIRST} (PGM) {LAST} {PREV} Lsys-name is the COPE logical system name, and DBD/PSB/DD/PGM defines the internal translate table to access to perform the control card translation. Translation is performed by extracting every word beginning with a character and looking for it in the translate table. It is important to limit the number of lines scanned with the range and column modifiers to reduce the number of searches. If a match is found, the edited line is changed to contain the internal C-number name, and the original line is displayed under it as a note. If the translation is incorrect, the note line can be made a "real" statement again by typing the characters MD (for "Make Data") in the line command field. ES Edit source JCL. Editing of the input to the import operation is accomplished with this option. EO Edit "other" JCL. If control cards or other JCL must be altered to contain COPE C-number names, use the EO option. Press Enter, and a panel is displayed for entering the non-COPE dataset and member to be edited. The T command (see above) can be used to scan for and alter data. J Specify job card. The generation process is performed in batch. A valid Jobcard is required for Jobcard submission. The Jobcard can be specified or altered with this option. Scan SYSIN cards Do you want to scan SYSIN cards for dataset names? Occasionally, control cards contain dataset names that must match those dataset names on the JOBLIB or STEPLIB statements. In the event that the D option has been used to allow dataset names to be changed on regeneration, a facility exists to automatically scan SYSIN statements and substitute the modified dataset names.
DLI and BMP jobs Are DLI and BMP jobs to use the COPE region controller? If the system variable XCDLIBMP is set to YES, this option will appear. YES is normally required. This option is only provided with the G option, and should always be specified as YES. If NO is specified, the JCL will not execute the COPERC00 region controller, and PCB names (DBD names) will not be translated at executed time. NO is provided only for downward compatibility with previous releases of COPE. You should always specify YES.
Running Converted JCL When you run Converted JCL, the following considerations apply: To get a COPE trace of Lsys name, Plan name, and all DLI calls, for DLI, DBB and BMP steps, add a //COPETRAC DD SYSOUT=class to the JCL step. You should remove this DD, or change it to DUMMY, for production runs. If you get a problem with a batch job under COPE, you should add the COPETRAC DD, and have the output available, before calling Standardware technical support. For MSG and IFP regions, you can get this trace by typing TRACE LOGIC from the COPE screen in IMS, running your transaction, then typing FLUSH from the COPE screen in IMS, then viewing the trace in ISPF COPE option 7.2 (the trace goes to the IMS log, not to the COPETRAC DD). The JCL converter currently changes STEPLIB libraries to a COPESTEP DD. This is only necessary for MSG and IFP regions, and is unnecessary for BMP, DLI and DBB regions. The effect is that COPERC00 will run authorized, which is not desirable in batch jobs, but which to date has not caused any problem. A future release of COPE will correct this. If you program issues CMD calls, then you must understand that these calls are not translated in any way by COPE. This means that you might have to take one of the following actions. 1. 2. 3. Use the JCL converter to translate input control cards, where those cards specify trancodes or database names used in your CMD calls. Change your program so that it issues AIB INQY instead of "/DIS TRAN". This call is translated by COPE. Change your program so that it does not issue CMD calls. If your program duplicates the function of the COPE start/stop facilities, for example, you could opt to use the COPE facilities and deactivate the CMD part of your processing in a COPE environment. Call COPESXP5 to translate trancodes or database names. If this is necessary, you can either read the documentation in ASM(COPESXP5), or call Standardware technical support. This method is not encouraged, because you will have to relink your program with each new release of COPE. A future release of COPE will have CMD and GCMD call translation. Keep this in mind when implementing a solution to this problem.
87
4.
5.
Note: If you want a BMP to switch to transactions or BMPs in other logical systems, you will have to take special action (such as coding a COPE-dependent version of the BMP program). This is described in the next section. The normal case (all switches are within one Lsys) does not require any special changes.
Logical System Selection This section explains what Lsys (Logical System) a transaction or BMP program runs in, within a Psys (Physical System). The main complicating factors are: 1. 2. 3. 4. MPPs can switch transactions to BMPs, or vice versa Non-COPE MPPs or BMPs can switch to COPE MPPs or BMPs, or vice versa In an MSC environment, transactions can switch from one Psys to another In a Fast Path environment, routing considerations apply
Lsys specification There are three methods for specifying the Lsys: 1. Logon. The userid is "logged on" to an Lsys in a Psys. This means that database USTDLMGR for the Psys (there is one USTDLMGR for each Psys) has a segment with the userid as key, which contains the current Lsys in the Lsys field. COPE "Logon" transactions are used by the user to change this Lsys. An example of the format follows: COPE COPE COPE COPE TFT4 LOGON TFT4 LOGON TFT4 FROM USER69 B.TFT4 ...logs ...same ...logs ...logs current user onto Lsys TFT4 (LOGON can be omitted online) USER69 onto Lsys TFT4 user onto Lsys TFT4 in Psys B
These commands can be issued from SYSIN statements to BMP COPEIMS3, see JCL(LJOB) for an example. The logon command is the only processing that changes a user's logical system in USTDLMGR; no other COPE processing ever changes this value, except that the LOADJCL job from 4.2.GS will re-initialize USTDLMGR, with all users logged off. To display a user's logon segment, use the @DLM command from the COPE screen under IMS, as in this example: @DLM 'DFTI9S02' The quotes are necessary. The user's current Lsys is at +10 hex (+16 dec) in the resulting display. GE status means the user has never been logged onto an Lsys.
2.
Transmitted Lsys on Switch. When an MPP or BMP "switches" a transaction to another MPP or BMP, the Lsys is passed on the end of the first segment by COPE. Applications will not see this Lsys name, because COPE strips it off at the time the application does a GU (Get Unique) for the switched message. Lsys transmission overrides Logon, except in the case of an MSC switch, where the destination Psys does not have the same Lsys name defined that the source Psys had. In that case, the user must be logged on (via a Psys.Lsys "remote logon" command) in the destination Psys to whatever Lsys the user wants to use. COPEBSYS. The logical system name is coded on batch or BMP jobs on a JCL //COPEBSYS DD statement. This always overrides any Logon in USTDLMGR, and any Transmitted Lsys. An example that specifies logical system TFT4 to the batch or BMP step is: //COPEBSYS DD DSN=&&TFT4,UNIT=SYSDA,SPACE=(CYL,(1))
3.
Non-COPE switch considerations The Lsys is not transmitted if the destination is not a COPE transaction (COPE checks this by looking up COPEXRF2). A non-COPE MPP can switch to a COPE MPP or BMP (the Lsys will come from the user's logon record in USTDLMGR). A non-COPE BMP can switch to a COPE MPP or BMP as long as either there is a Userid associated with the resulting transaction, or in the case of a destination BMP, a COPEBSYS DD is coded. This means that a non-message-driven BMP can only switch transactions to one Lsys (not to a mix of Lsys's). If you need to switch to different Lsys's in this case, you should add "@COPELS lsysname" to the end of the first segment switched, either in the BMP program, or in the COPESXUX user exit if it is a COPE BMP and you do not wish to make your code COPE-dependent. An unmodified nonCOPE BMP cannot switch to multiple Lsys's. Please note that COPE BMPs get there COPEBSYS coded automatically by the JCL converter (it is slightly hazardous to do it manually because the correct C-number psb must be used). MSC considerations In MSC, if you want the user to always have control over the Lsys they run in, then you should define Lsys names to be unique across all Psys's. This will "turn off" the "Transmitted Lsys" mechanism, simply because the Transmitted Lsys will never be defined in the destination Psys. If you want the user never to have control over the Lsys used in a remote Psys, then you should define the same set of Lsys names in each Psys, and then the Transmitted Lsys will always be used. If you want some other degree of user control over the Lsys, you should either control the combinations of Lsys's the user can logon to (as a security control), or code a COPESXUX exit to set the Lsys name that you require under whatever circumstances that you require. Please contact Standardware for further information in the latter case.
89
Libset Terminology
Libsets are a mechanism for controlling groups of datasets that contain the objects, such as PSBs, DBDs, and programs, that define an application system. A Libset is a group of datasets that hold a related set of source modules and their associated load modules. The recommended approach is to use one libset for development, one for production, and one for each intermediate system integration test phase. This allows a hierarchy of libsets which supports migration of applications from test to production. The term promotion is used to describe the process of module migration between libsets. Libsets frequently do not contain complete copies of application systems. Maintenance usually takes place on some subset of existing applications, and concatenated libsets are used. Concatenation is defined as the specification of a list of libsets to be scanned for a particular module. This technique eliminates redundant, unmodified versions of modules. The following diagram demonstrates some of the COPE libset capabilities and also the terms used by COPE to describe libset manipulation. Figure 55: Libset Relationships
? (A) v ? ? ? (H) (D) (B) Production LIBSET v > v ? ? ? ? (G) < (F) < (E) < (C) < Promotion Direction
Development LIBSETs
Each box in the above diagram represents a libset. Libset G represents the "Production" libset and Libsets A, B, C, and D represent "Entry" or development level libsets.
COPE uses the following terminology: Term Entry Libset Import Export Sibling Libset Meaning Libsets used for development. They contain modules which may be in a state of development for uncompleted systems. The input of a module into a development or ENTRY level COPE libset. The process of removing any module from any COPE libset to another system or dataset. A libset that is immediately "lower" in the search hierarchy of libsets. For instance libset B is a sibling of libset A, and libset C is a sibling of libset B. Libset C is not a sibling of libset A as it is not immediately lower in the search hierarchy. The sequence of libsets that a module must pass through when it migrates from development to production. The libset that is immediately "higher" (more production oriented version) in the PROMOTION hierarchy. For example, E is a parent of C. E is also a parent of D, B, and A. A "handle" that defines the entry (or lowest level) libset that a module comes from. The category name is arbitrary and may be the same as the libset name. Specification of the entry categories that a libset may receive is important for controlling the "Promotion" of modules. In the example above, libset E may receive Entry Categories A, B, C, and D. Libset H, however, may only receive Entry Category B. Libset F may receive the categories A, C, and D. A logical IMS COPE system may be defined wherever there is an unambiguous entry concatenation sequence defined. In the above example, IMS systems may be defined for libsets A, B, C, D and H (assuming only a single entry category is put in H). IMS logical COPE systems may not be defined for libsets E, and G since they have been defined as having multiple entry categories.
Promotion Hierarchy Parent Libset
Entry Category
Logical IMS System
Display COPE name translations

The COPE main menu has a T option. When specified, this options allows either a COPE name or a real name to be entered and the corresponding translated name to be displayed.
91
The following examples demonstrate the operation of the translate feature Figure 56: Translation of a non-COPE name
---------------------------------- COPE for IMS ------------------------------Option ===> T .--------------------- COPE Name Translation ----------------------. : Option ===> : : (D)ynalloc, (B)rowse source/load, (F)ind : : : : : : Name ===> ivpdb3 : : Lsys ===> (CICSA,CICSB,CICSC : : Type ===> (DBD, DD, PSB, TRANSACT) : : : : : : : Lsys Lic : : Physical '------------------------------------------------------------------' Procs Dataset TFTPROD.COPE1.PROCS .---------------. | Enter "JOB" | | to review JOB | | status | '---------------' .---------------. | Enter "EDIT" | | to access | | ISPF Edit | '---------------' .--------------. | Enter "BROW" | | to access | | ISPF View | '--------------' .--------------. | Enter "UTIL" | | to access | | ISPF Utility | '--------------'
Copyright (c) 1994-2000 Standardware Inc.
When the Enter key is pressed, the application scans internal dictionary tables and generates a display that contains all known translations of the object name for all known Logical Systems.
92
Figure 57: Translation of a COPE name
--------------------------------- COPE for IMS -------------------------------Option ===> T .---------------------- COPE Name Translation -----------------------. : .------------------- Name Translation ---------------- Row 1 of 2 : : ]Option ===> ] : : ] (D)ynalloc, (B)rowse source/load, (F)ind ] : : ] ] : : ] Name ===> C0023749 IVPDB3 ] : : ] LSYS ===> CICSA CICSA,CICSB,CICSC ] : : ] Type ===> DBD (DBD, DD, PSB, TRANSACT) ] : : ] ] : : ] Name Lsys/Tran Type ] : : '---------------------------------------------------------------' : Lsys L : C0023749 CICSA DBD : Physic : C0023753 CICSB DBD : Procs : ************************* Bottom of data ************************* : : : .----- : : | Ente '--------------------------------------------------------------------' | to review JOB | | to access | | to access | | to access | | status | | ISPF Edit | | ISPF View | | ISPF Utility | '---------------' '---------------' '--------------' '--------------' Copyright (c) 1994-2000 Standardware Inc.
If a DBD is displayed, option D may be selected to generate Dynalloc source from the load associated with the Physical system. The user is then placed into browse on the generated source. If option B is chosen, the user is placed into browse on the COPE copy of the source, or (if a Cnumber is displayed), the source is generated from the load, and then displayed. Option F requires generic characters to be used, e.g. F *53 will position the cursor on the second row in the scrolling list, F *2* will position the cursor on the first row.
93
IMS Facilities
Overview
To access the IMS facilities of COPE, you logon to IMS, then type COPE. This brings up the main COPE screen. Figure 58: COPE Online Main screen
------------------------------------------------------------------COPE INVDEVL DFTI8L07 15:37 MSGIMS1 J2853 =====> XYZ INC Wed 03/21/91 Enter a command above, hit PF1 to access the tutorial. Lsys /FOR Format ABS SS TRACE ON AVAIL> INVDEVL PROD - Logon to, or change to logical system - Display MFS format - Display last Abend Summary screen - Start/Stop databases or transactions - Turn DLI and SQL call trace on TEST
=STOP> INVDEMO -------------------------------------------------------------------
In the above example: Value COPE INVDEVL DFTI8L07 15:37 MSGIMS1

94
Represents In the top left-hand corner identifies this as the COPE screen Next to COPE on the top line is the current Lsys you are logged onto (will be blank if you have never logged on before) Your Lterm (or Signon-id, if you use the IMS /SIGN command) The time (24 hr clock) The message region Jobname
J2853 =====> XYZ INC Wed 03/21/91 Enter a ... AVAIL> =STOP>
The message region Job number Indicates the line where you enter commands Your installation's name, as known to COPE for this CPU The current day and date And the lines down to TRACE ON is text reminding you of the major commands available Lists the names of the Lsys's that are available (not Stopped), and that you could logon to by typing their name on the "=====>" line Lists the names of the Lsys's that are Stopped (usually a person stops a system so that they can access all the databases in the system in batch)
From this COPE screen you can: Issue COPE commands, to logon to an Lsys (just type the Lsys name), or display an MFS format, etc. Issue IMS commands, and translate internal C-numbers to real names in the output. Press <PF1>, to access the COPE tutorial, which works exactly the same as an ISPF tutorial. Issue SS to access the Start/Stop scrolling screens for databases and transactions, to deallocate databases (for example). Type in a COPE Message Number of form nnn, to get an explanation for the message. The Messages Manual is online.
You can issue these commands from any screen that, like the main screen shown above, has COPE in the top left-hand corner. You can also issue any of these commands from a cleared screen, by preceding the command with the word COPE followed by a space. To issue multiple commands with one pressing of the Enter key, type them one command after another, separated by a semi-colon, in the same way as with commands under ISPF, for example: COPE TEST;/FOR MYMENU You could issue the above to logon to the Lsys called TEST and display the MFS format called MYMENU, in one operation. This example could be issued from a cleared screen (as shown by the COPE preceding the first command, TEST). From the COPE screen, as opposed to from a cleared screen, you omit the COPE (It will be accepted if you accidentally include it). This section describes the main commands that are useful to programmers. There are other commands that are useful to COPE Administrators, which are described in detail in the Tutorial. You access the Tutorial by pressing <PF1>.
Note: Administrator's commands are best documented in the tutorial, so if you want, or need, to find out about them, we suggest you press <PF1>.
Commands for programmers The commands described in this section are: Logon /... Logon to an Lsys Issue an IMS command. Note that you can use an asterisk (*) within database, transaction and terminal names in /DIS commands, to display all matching names:
/DIS DB ISSREF* /DIS NODE DFTI*
/FOR
Displays an MFS format, as with an IMS /FOR command. However, if formats are different in different Lsys's, you must issue the /FOR from the COPE screen to pick up the correct format, unless you have special "/FOR-from-clearedscreen" support installed. Contact your COPE Administrator if you are unsure if this support is installed. Displays COPE message explanation, for message COPnnn Displays the program library dataset names for an Lsys Sends a message to one user, or all users Accesses the Start/Stop Database/Transaction scrolling screens Turns DLI and SQL call traces on or off for your terminal Displays the linkedit date, and library dataset name for a program
nnn LIB MSG SS TRACE VERSION
BACKUP/RESTORESubmits jobs to either backup or restore databases
Commands for administrators Commands that are useful for COPE Administrators, are described in the tutorial and in the COPE for IMS/DC Administration Guide. The fullest descriptions are usually in the tutorial, and in the detailed explanations for COPnnn msgs (available by typing COPnnn on the command line). They are: Command
96
Purpose
COLDS DEBUG IMS nn REFRESH SUB SYNC VERSION LLE @<storage>
Automatic Cold start command (also WARMS and EMERS) Debug Cope itself Set physical IMS system number Bring in latest version of COPE tables Submit a job from the JCL library Synchronize Start/Stop to "wake up" terminals Display the Load List Elements (shows Preloaded/Loaded modules) Display Storage by hex-address, module name or label
Using the tutorial You view the descriptions in the tutorial, which are arranged in a panel hierarchy, using the same PF keys as in an ISPF Tutorial: PF Key PF1 PF3 PF7 PF8 PF10 Purpose Accesses the Tutorial Exits the Tutorial (does not go to a higher level in the panel hierarchy) Goes UP to the parent panel in the hierarchy (use this key to return after selecting a topic) Goes to the NEXT panel in sequence, and is the same as pressing <Enter> Goes BACK to the previous panel that you viewed, ignoring the hierarchy
Logon to an Lsys
To use COPE, you need to know what physical IMS system (Psys), and within that system, which logical IMS (Lsys), to logon to. The logical IMS associated with a given libset level can be easily determined in the ISPF environment by going into COPE 4.3 (Administration Functions, DRAW option), which displays a diagram of the libsets. For example:
97
Figure 59: DRAW, Libset display
XYZ INVDEVL IMS=INVDEVL
Here, the libset called XYZ.INVDEVL has a logical IMS associated with it called INVDEVL. Usually, your COPE administrator will set up the second part of the libset name to correspond to the Lsys name, as in this example. Logon (via VTAM) to the physical IMS that contains the COPE Lsys called INVDEVL. Your COPE administrator will tell you which physical IMS to logon to. Once in IMS, from a cleared screen, enter COPE. The system responds with the "COPE Main screen", which looks like the following:
98
Figure 60: COPE Online Main screen (Not logged on)
------------------------------------------------------------------COPE DFTI8L07 15:37 MSGIMS1 J2853 =====> XYZ INC Wed 03/21/91 Enter a command above, PF1 to access the tutorial. Lsys /FOR Format ABS SS TRACE ON AVAIL> INVDEVL PROD - Logon to, or change to logical system - Display MFS format - Display last Abend Summary screen - Start/Stop databases or transactions - Turn DLI and SQL call trace on TEST
=STOP> INVDEMO -------------------------------------------------------------------
Type INVDEVL in the "=====>" field, press <Enter>. You will see the following screen: Figure 61: COPE Online Main screen (after logging on)
------------------------------------------------------------------COPE INVDEVL DFTI8L07 15:37 MSGIMS1 J2853 =====> User DFTI8L07 logged on to INVDEVL
=LIB=> T.COPE.PGMLIB =LIB=> COBVS.COBLIB
-------------------------------------------------------------------
99
The top line fields are: Message Region
Lsys ######## =====>
Lterm
The Lsys field will be blank if you are not currently logged on to a COPE Lsys. Once you are logged on to a COPE Lsys, you proceed with entering transactions, /FOR commands, or options from menus, exactly as you would under a non-COPE IMS system. If you run transactions without having logged on, you will get the COPE screen, with message COP204, telling you that you are not logged on. You would logon by typing in the Lsys name, then repeat the transaction (the transaction was not invoked when you weren't logged on). When you logon to an Lsys, the "=LIB=>" arrows on the left point to the dataset names of the program load libraries. The libraries are concatenated in order from top to bottom, as in a JCL concatenation. To check what the libraries are at any time, type LIB on the "====>" line. Figure 62: COPE Online - LIB command screen
------------------------------------------------------------------COPE INVDEVL DFTI8L07 15:37 MSGIMS1 J2853 =====> LIB
=LIB=> T.COPE.PGMLIB =LIB=> COBVS.COBLIB
-------------------------------------------------------------------
The COPE screen always contains the name of the Lsys you are currently logged on to, next to the word COPE in the top left-hand corner. This screen can be called up at any time by clearing the screen and typing COPE.
Suspending conversational transactions If you do not use IMS conversational transactions, please skip this section. If you use conversational transactions, you can temporarily suspend the conversation, so that you can run a COPE transaction. To do this, type: /HOLD IMS suspends the conversation, and responds with a message: DFS999 13:13:51*HELD CONVERSATION ID IS 0014 **
You can then run other transactions, such as the COPE transaction to check what Lsys you are on. To resume the conversation, press <Clear>, and type: /REL CONV 0014 quoting the 4-digit ID that was in the DFS999 message. The screen that was showing before you issued /HOLD will reappear.
IMS / Commands (with * wild characters)

You can enter just about any IMS command from the "=====>" prompt on the COPE screen, such as /DIS A, /DIS Q TRAN, /DIS DB xxxx, etc. /DIS DB, TRAN, PROG, NODE and LTERM commands can be entered with an asterisk (*) on the end of the name in order to display all those names which match the characters preceding the asterisk. For example: /DIS DB ISSREF* displays all databases beginning with the characters ISSREF. The * "wild" character can be used anywhere in the name, as in ISPF member-list masks. Other wild characters, +, #, etc. are also possible. + means a single non-blank character, # means a number, and all the 'pic' characters usable in the ISPF FIND P'...' command, are supported. The output of / commands will have C-numbers on the right-hand side of the screen, to assist in debugging. The output is limited to one screen. Use the * feature to display only those databases, transactions, or programs you are interested in. Append the LSYS keyword, followed by the name of a Lsys, to issue a command in a system you
are not logged onto. For example, /DIS DB ISSREF* LSYS PROD. This also works for "unused" systems. Use /DIS DB ISSREF* LSYS * to issue the command in all systems. Summary of wildcard mask characters: * + = @ # $ . < > any chars, any lth, incl lth=0, incl blanks non-blank (single character) any char, incl blank alphabetic, incl lower case, and @ itself numeric, and # itself special char (displayable non-alpha, non-num) non-blank (same as +) non-displayable non-numeric (incl blank, alpha, non-displ) lower case alpha upper case alpha
* is the only wild character that matches variable length. Wild characters other than asterisk (*) and plus sign (+) are the same as the 'pic' characters in the ISPF Edit FIND P'...' command, except that @ and # also match themselves. In practice, only *, + and # are useful in display commands.
Display COPE Message Explanations (nnn)

You can type in a COPE message number and get an explanation of the message, together with a description of the system action, and the appropriate user response. COPE messages always have a COPnnn message number on the front, as in this example: COP204 You are not logged on - enter logical system name above You would type in COP204, or just 204, on the "=====>" line of the main COPE screen, or any tutorial screen, to get the explanation. You can list all message numbers by typing in MI (Message Index).
Display Program Load Libraries (LIB)

LIB displays the program load libraries being used for an Lsys. For example: =LIB=> T.COPE.PGMLIB =LIB=> COBVS.COBLIB
102
The command lists the program libraries in their concatenation order. You can also add a ddname parameter, to look at the datasets on any DD in the message region. If you type LIB COPESTEP, for example, you will see the libraries on the special COPESTEP DD. The COPESTEP libraries are important, because they are concatenated after the libraries for each Lsys. So if a module is not found in the Lsys libraries, it will be searched for in the COPESTEP. To assist you with detailed understanding of library concatenations and ESTAEs, the LIB screen shows you the actual DDname concatenation, and currently active Estaes The DDname search order is: C0000002 COPESTEP STEPLIB Estaes curr active: COPESXP7 DFSPCC20 The implications of these display lines are: 1. In COPE message regions, the three DDnames C0000002, COPESTEP and STEPLIB are "concatenated", so that it is as if all the libraries on the DDs were on a single STEPLIB. The order is C0000002 first (it is C0000002 in this example, other Lsys's will have a different C000000n DDname). This means: C0000002 is the Lsys-specific DDname used for loading programs in this message region for this Lsys. If you change Lsys's, you will see a different DDname here (different Cnnnnnnn). The libraries come from the ISPF 4.11 definition ("Define Msg Region Datasets"), and are set up by your COPE Administrator. COPESTEP is logically concatenated after C0000002. If your program loads a module that is not in the Lsys-specific concatenation, the next DD searched by MVS is the COPESTEP. Preloaded modules are loaded from COPESTEP (followed by STEPLIB, then LNKLSTxx). STEPLIB is logically concatenated after COPESTEP. If your program loads a module that is not in the Lsys-specific concatenation, nor in the COPESTEP concatenation, the next DD searched by MVS is the STEPLIB. Since in a COPE message region you should only have ONE library on STEPLIB (the authorized library containing COPERC00), none of your loads should be resolved from STEPLIB. LINKLSTxx libraries are logically concatenated after STEPLIB, as in all MVS regions. If your program loads a module that is not in the Lsys-specific concatenation, nor in the COPESTEP concatenation, nor in the STEPLIB concatenation, the next DD searched by MVS is the STEPLIB.
The term "Tasklib Switching" as used in the COPE manuals refers to the way COPE dynamically changes the Lsys-specific DDname (the top C000000n one) to the appropriate Lsys, for each transaction that runs in a COPE message region. This is the essence of shared (by Lsys's) message region support in COPE. 2. ESTAEs are displayed to assist with problems where your application program either leaves ESTAEs active in the message region, or cancels other module's ESTAEs. To diagnose such a problem, you would issue the LIB command (which displays the same screen as when you logon to an Lsys). The screen will show you the current ESTAEs in this message region. If all
103
is well, you should see COPESXP7 and DFSPCC20 (only) as above. We are not implying here that ESTAEs are related to program library concatenations, these are two separate unrelated issues.
Logoff from COPE (not normally necessary)

The normal IMS Logoff (/RCL) works under COPE, but does not affect your COPE logon status. Since the name of the COPE Lsys you are logged onto is stored in a database, it is retained across IMS logons. You can do a "quick change" of Lsys at any time, by entering COPE followed by a space, followed by the Lsys you want to change to, from a cleared screen. This is useful when you are comparing the results of running the same test transaction, under two different logical IMS systems. It is also possible, though normally unnecessary, to remove the association between your terminal and a particular logical IMS (in other words, to "logoff COPE"). To do this, enter COPE LOGOFF from a cleared screen, or just LOGOFF from the COPE screen. This facility is provided to assist COPE Administrators when they are testing your logon procedure under COPE. Note: Any attempt to run a COPE-controlled transaction on a COPE system from a terminal that is not "COPE logged-on", will give a COPE message screen, with an invitation to logon, as follows:
Figure 63: COPE Online - Not Logged On screen
------------------------------------------------------------------COPE DFTI8L07 15:37 MSGIMS1 J2853 =====> COP204 You are not logged on - enter logical system name above
-------------------------------------------------------------------
The attempted transaction cannot run, because COPE does not know what logical IMS you wanted to run it in.
If there is a disk-drive hardware failure, or similar problem, your COPE Administrator will re-initialize the COPE USTDLMGR Database (which contains a record of the current Lsys for each user) and you will find that you are "COPE logged-off". In this case, follow normal logon procedures as described above. If your COPE Administrator adds or deletes Lsys's, they must log all users off. This is done as follows: LOGOFF FROM ALL Alternatively, your Administrator can re-initialize the Control Database (USTDLMGR). The effect in either case is that you will find yourself logged off, and you must logon again.
Send a Message to a User or all Users (MSG)

You can send a message to a user, or all users. The messages appear on the COPE main screen. The persons receiving the messages can read them and delete them. You can also delete messages you have sent. You would send a message to ALL users as follows: Msg Sent =====> MSG ALL P NOTHING LIKE A PINK MESSAGE TO CHEER UP A LOGON SCREEN This would appear on every user's screen, in pink if you have color screens, on a =MSG=> line (max 4 lines): =MSG=> NOTHING LIKE A PINK MESSAGE TO CHEER UP A LOGON SCREEN DFTI8L07
For further details, access the tutorial, and select the MSG topic (number 7). From there you can select the following topics: 1. 2. 3. 4. 5. Sending messages with MSG <dest> <color> <text> Deleting messages sent to you, with MSG DEL Deleting messages sent from you, with MSG DEL <dest> Deleting messages sent by others, with MSG DEL <dest> FROM <source> Automatic deleting of msgs, with MSG <dest> <c> ADEL <mins> <text>
Database Start/Stop
To take a database offline, you must "stop" it, using the COPE Database Start/Stop menus. This is equivalent to the normal IMS /DBR command, but provides an easier-to-use display. From the COPE screen, enter SS to access the Start/Stop selection screen. From a cleared screen, you can enter COPE SS, to go to the same place. Start and Stop functions are not distinguished from each other, at this point. SS displays a selection screen, as follows: Figure 64: COPE Online - Start/Stop Selection screen (DB side)
------------------------------------------------------------------COPE DATABASE/TRANSACT START/STOP SELECT FUNCTION ===> ACTION ===> (S-START P-STOP OR BLANK TO DISPLAY) DB/TR ===> DB NAME ===> SYSTEM ===> INVDEVL (BLANK FOR LIST) USER NAME ===> EC DISPLAY ===> (G-GROUPS P-STOPPED BLANK-ALL) LOG SWITCH ===> NOFEOV (NORMALLY NOFEOV) -------------------------------------------------------------------
Leave the ACTION field blank, enter DB for Database, next to DB/TR, and enter your name or initials ("EC" in this example) against USER NAME. For USER NAME, you can enter up to 30 characters of a message to send to users who try to use a Database that you are going to stop. All other fields are optional. You can leave the SYSTEM as INVDEVL (which is initialized to whatever system you are logged on to) or you can blank it out, to get a list of the Lsys's.
106
Figure 65: COPE Online - Start/Stop System List screen (DB side)
------------------------------------------------------------------COPE START/STOP DATABASE SELECT FUNCTION ===> SYSTEM: DB: USER: EC 14:09 DFTI8L07 91.045 DISPLAY: LOG SWITCH: NOFEOV (S-START P-STOP X-DISPLAY) S/P/X SYSTEM G STOPPED DESCRIPTION DEVL 0/432 Development Base SYSSTOP INVDEMO 0/440 Inventory Demonstration X INVDEVL 3/440 Inventory Development PROD 0/432 Production -------------------------------------------------------------------
If there are more systems than will fit on one page, use <PF7> and <PF8> to scroll the list up or down. You can select only one Lsys at a time, but you can later <PF3> back here for another one. Enter an X next to the Lsys in which you want to Start/Stop a database (INVDEVL in the above example). A scrollable display of the databases that can be started or stopped is shown as follows:
107
Figure 66: COPE Online - Database List screen
------------------------------------------------------------------COPE START/STOP DATABASE SELECT FUNCTION ===> SYSTEM: INVDEVL DB: USER: EC 14:09 DFTI8L07 91.045 DISPLAY: LOG SWITCH: NOFEOV (S-START P-STOP X-DISPLAY) S/P/X DATABASE G STOPPED DESCRIPTION ABC G 3/17 Account Booklet Capture S ABC1 G 3/8 ABC Model, Instructions, Pending P ABC2 G 0/9 ABC Combi, Log, Package, Paq Queue AM G 0/11 Asset Management History AT G 0/7 Asset Management Transaction History -------------------------------------------------------------------
Enter S for Start, and/or P for stoP, against the groups of databases that you wish to bring online, or take offline. In the above example, the group called ABC1 is to be started, and the group called ABC2 is to be stopped. The G column is a Group indicator that shows whether the line represents an individual database, or a Group of databases. In the above, all the lines are marked G, so they are all Groups. When you stop a group or database, you will see that your name or initials (as entered in the USER NAME field of the selection screen) appears next to it, in place of the Description. This is so that other users may check with you, if they want to use the database that you brought offline. When a user runs a transaction that needs an offline database, COPE gives them a message saying the database is stopped. That message also contains the USER NAME information, as follows:
108
Figure 67: COPE Online - Stopped Database screen
------------------------------------------------------------------COPE INVDEVL DFTI4L44 15:37 MSGIMS1 J2853 =====> COP112 =ERR=> Databases NA (Not Available) in Lsys INVDEVL: ABCCMBDB COP116 Last reason ABCCMDB Stopped is "EC 14:36 DFTI8L07 91.045" COP117 Start the DB in COPE SS and rerun -------------------------------------------------------------------
Note that COPE appends the "14:36 DFTI8L07 91.045" to the user name initials, to help identify the time, the user who stopped the database, and the date they stopped it. As much as will fit in the 30 characters available will be appended. You can use a message of up to 30 characters, and it will "push" these fields out of view if necessary. The database that is started or stopped is the one in the logical IMS that you either entered on the first screen, or selected from the list of systems screen. There will be other databases of the same name, but in other Lsys's, which are not affected. The stopping and starting in one system is completely independent of other systems. Use <PF3> to return through the previous screens, or just press <Clear>, for a quick exit from the Database Start/Stop screens. The "SELECT FUNCTION ===>" line cannot be used for any commands (you must clear and say COPE to return to the COPE main screen). Groups of databases COPE databases are always stopped in pre-defined groups. For example, a database with all its secondary indexes (and its primary index if HIDAM) is an indivisible unit, as far as COPE stopping and starting goes, and will always be together in the same group. If databases have IMS logical relationships between them, the logically-related databases also form an indivisible Start/Stop group. The reason for this grouping is to alleviate problems when IMS starts to process a DLI call (through a secondary index), and then finds that it cannot continue because the main database is offline. IMS issues a U85x, or a BA status code, in this situation. Also, it is generally much more convenient to be able to start and stop related databases together, rather than individually.
The COPE Database Start/Stop Facility also provides "Groups of Groups", so that you can stop and start common application-related databases together. Your COPE Administrator defines these groups to COPE, with descriptive text for each, in ISPF option 4.2.DG. To see what databases are in a group, enter an X against the group. This will go down one level in the hierarchy. Press <PF3> to go back up the hierarchy. The ultimate group, is the group of all databases in one Lsys, and you can start or stop these all at once. You do this by entering S and P against the logical system name in the list of systems. To receive this list, you blank out the SYSTEM on the initial selection screen, as described in the example above. Alternatively, you may enter S or P in the ACTION field of the initial selection screen, with the group name not blanked out, but with a blank NAME field. This is referred to as "Start/Stop of a System, DB Side" and is further described in "System Start/Stop" on page 114, later in this section. Database stopped counts The STOPPED column on Start/Stop screens shows you counts of databases stopped, as a "fraction". For example: S/P/X DATABASE G STOPPED DESCRIPTION ABC1 G 3/8 ABC Model, Instructions, Pending
Here, ABC1 is a Group in which 3 of the total of 8 databases are stopped. These stopped counts are correct when you first display the list, but won't necessarily be correct at other times (for example when you <PF7> and <PF8> up and down the list). Why /DBR, etc. commands are prohibited Normal IMS commands for changing the Start/Stop status of databases cannot be used under a COPE system. They would bypass COPE's internal control of the status of databases. Therefore you cannot use the following IMS DB commands in a COPE system: /DBR /STO /DBD /STA DB DB DB DB ...use ...use ...use ...use COPE COPE COPE COPE SS SS SS SS "P" "P" (also takes database offline) "P" (does not allow read trans to run) "S"
NOTE: COPE combines the functions of the IMS /STO and /DBR commands. When you Stop a group of databases, they are taken offline (de-allocated) so that batch jobs can access them, when you Start the group of databases, they come back online. Command line STA and STO commands You can start or stop databases from the command line of the COPE main screen by using the fol110 COPE for IMS/DC Programmers Guide
lowing commands: STA STA STO STO DB DB DB DB <name> <name> LSYS <lsys> <name> <name> LSYS <lsys>
Note that there is no slash (/) preceding these commands. For Fast-Path DEDB databases, substitute the word "AREA" for "DB". COPE provides these commands mainly so that you can issue them via PF keys or batch programs. This is described in the COPE for IMS/DC Administration Guide. You start and stop transactions using the same set of screens as databases. Enter COPE SS from a cleared screen, or just SS from the COPE screen, to get the selection screen below: Figure 68: COPE Online - Start/Stop Selection screen (TR side)
------------------------------------------------------------------COPE DATABASE/TRANSACT START/STOP SELECT FUNCTION ===> ACTION ===> (S-START P-STOP OR BLANK TO DISPLAY) DB/TR ===> TR NAME ===> SYSTEM ===> INVDEVL (BLANK FOR LIST) USER NAME ===> EC DISPLAY ===> (G-GROUPS P-STOPPED BLANK-ALL) LOG SWITCH ===> NOFEOV (NORMALLY NOFEOV) -------------------------------------------------------------------
Enter TR for TRansaction, against the DB/TR, and blank out the SYSTEM name to get a scrollable list of Lsys's:
111
Figure 69: COPE Online - Start/Stop System List screen (TR side)
------------------------------------------------------------------COPE START/STOP TRANSACT SELECT FUNCTION ===> SYSTEM: DB: USER: EC 14:09 DFTI8L07 91.045 DISPLAY: LOG SWITCH: NOFEOV (S-START P-STOP X-DISPLAY) S/P/X SYSTEM G STOPPED DESCRIPTION DEVL 0/738 Development Base INVDEMO 0/761 Inventory Demonstration X INVDEVL 1/761 Inventory Development PROD 0/738 Production -------------------------------------------------------------------
Select an IMS system with an X, and press <Enter>. The following screen then appears: Figure 70: COPE Online - Transaction List screen
------------------------------------------------------------------COPE START/STOP TRANSACT SELECT FUNCTION ===> SYSTEM: INVDEVL DB: USER: EC 14:09 DFTI8L07 91.045 DISPLAY: LOG SWITCH: NOFEOV (S-START P-STOP X-DISPLAY) S/P/X TRANSACT G STOPPED DESCRIPTION INVMENU Inventory Menu S INVTRAN1 STOPPED INVTR001+34 S0C7! Pgm&c.INVTRPGM INVTRAN2 Inventory Summary -------------------------------------------------------------------
Entering S or P against a trancode starts or stops that transaction and its associated program. In the above example, transaction INVTRAN1 was previously stopped by an S0C7 abend. The S on
the left-hand side is a command to start the transaction again, to make it available to all users. Note that the Description field of the stopped transaction contains the module name, PMAP offset, and abend code, for the abend which caused the transaction to stop. COPE programs have the same status as the Trancode. When there are multiple trancodes for one program, the program is started for started trancodes and stopped for stopped ones. The difference from Databases, is that transactions will almost always be stopped by MPP abends, rather than by a user. Users start the transaction when they know the program has been fixed. Sometimes you will want to stop a transaction and leave an explanation. This is achieved in the same way as for databases. Use the 30-character User Name field on the first Start/Stop selection screen. If your transaction is stopped by an MPP abend, normally the next thing you want to do (after fixing the application program) is to start the transaction. You can use SS screens to start it, or you can use the "Quick-Start" command: COPE STA trancode This will start the transaction and program. Note there is no slash (/) and no TRAN keyword above. Sometimes after issuing a STA trancode, when you run the transaction, it is still stopped. This happens in situations where your abend was in a DLI call, and you are using dedicated (by Lsys) message regions. If this happens, just issue "STA trancode" again, and after the second time you will find that the transaction is started. However, issuing STA trancode twice, without testing whether the trancode was started between, will not protect you from this problem. The reason is that the intervening test transaction is needed by COPE to resynchronize the status. In other words, "if it is stopped, start it". If you want a more detailed explanation of this behavior, contact your COPE Administrator. Note: /DIS TRAN commands are of no use in determining the Stopped status of a transaction, because the COPE status is a separate entity from the IMS status. The way to determine whether a transaction is stopped is to run the transaction, or display it in COPE SS. As with databases, groups of transactions may be pre-defined, for mass starting and stopping. See your COPE Administrator for details. You can start or stop all transactions in an Lsys at once, from either the list of Lsys's, or from the initial selection screen (with the NAME field blank). This is referred to as "Start/Stop of a System, TR Side" and is further described in "System Start/Stop" on page 114. You start or stop a system on the TR Side, if you need to either: Make the system unavailable, but do not want to deallocate all the databases, or, Deallocate the system's program load libraries
113
Why /STO TRAN, etc. commands are prohibited The standard IMS commands for changing the Start/Stop status of Transactions and Programs cannot be used under a COPE system, because they would have an effect across Lsys's. The following IMS commands should not be used: /STA /STA /RST /STO /STO TRAN .. use PROG .. use .. use TRAN .. use PROG .. use COPE COPE COPE COPE COPE SS SS SS SS SS "S" "S" (on the Tran) "S" (no different from /STA) "P" "P" (stops the Tran)
The COPE equivalent commands internally generate the appropriate IMS command, and also provide a "Stopped" status at the Lsys level, which is necessary so that Lsys's do not interfere with each other. In special test situations, you may need to PSTOP a transaction so that you can create a queue of transactions for testing program reusability (for example). In such a case, the IMS /PST command can be used, but with caution, because it PSTOPs the transaction in all Lsys's. Command line transaction STA and STO commands You can start or stop transactions from the command line of the COPE main screen by issuing the following commands: STA STA STO STO <tran> <tran> LSYS <lsys> <tran> <tran> LSYS <lsys>
Note that there is no slash (/), and no TRAN keyword between the STA or STO and the trancode. COPE provides these commands so that you can "Quick-Start" the transaction and program after an abend, and so that you can issue them via PF keys or batch programs. This is described in the COPE for IMS/DC Administration Guide.
System Start/Stop
You start and stop Systems using the Start/Stop Selection screen, or the Start/Stop System List screen. You can start either Side of a system, or both Sides. The two sides, and the effects of stopping them are: DB Deallocates all databases in the Lsys. If there are many databases, this can take a minute or two, because many internal /DBR commands are issued. You would do this if you need to access all, or many of, the databases in the system, in batch, with DISP=OLD.
114
TR
Deallocates the program load libraries that are allocated to an Lsys. This also stops all transactions in the Lsys. You would do this if: 1. You need to access the program load libraries in the Lsys in batch, with DISP=OLD. For example, you need to move the libraries from one disk to another. 2. You need to stop users from using programs in the Lsys, but you do not need to deallocate the databases (and you therefore want to avoid the overhead of doing this). For example, you need to compile many programs in a system due to a global COPYLIB member change, and do not wish any of the old programs to run, because they might put fields wrongly in segments in databases that are being converted to the new COPYLIB layout.
When you stop a system on either Side, that system appears on the COPE main screen next to the =STOP> arrow. Transactions cannot run in the system, even if only one Side is stopped. As an example, you would deallocate all databases as follows. Enter COPE SS from a cleared screen, or just SS from the COPE screen, to get the Start/Stop Selection screen. Type DB opposite DB/TR, and blank out the SYSTEM field, to get the DB Side system list: Figure 71: COPE Online - System Start/Stop screen (DB side)
------------------------------------------------------------------COPE START/STOP DATABASE SELECT FUNCTION ===> SYSTEM: DB: USER: EC 14:09 DFTI8L07 91.045 DISPLAY: LOG SWITCH: NOFEOV (S-START P-STOP X-DISPLAY) S/P/X SYSTEM G STOPPED DESCRIPTION DEVL 0/432 Development Base S SYSSTOP INVDEMO 0/440 Inventory Demonstration P INVDEVL 3/440 Inventory Development PROD 0/432 Production -------------------------------------------------------------------
In the above, SYSSTOP preceding the system name indicates that all databases in that system are stopped (deallocated). Note that the counts (0/440) do not reflect this. On the left-hand side, you have entered S for this system, and P for the INVDEVL system, because you want to start INVDEMO and stop INVDEVL. When you press <Enter>, the deallocation process will start. Deallocation of databases proceeds asynchronously, and so is not complete when the system reCOPE for IMS/DC Programmers Guide 115
sponds, even though the SYSSTOP will have disappeared from INVDEMO, and appeared against INVDEVL. To check when deallocation is complete, clear the screen, and type: COPE /DIS DB * LSYS INVDEVL This will show you a list of the databases in the INVDEVL system, with their IMS status. Repeat the /DIS DB command until you see that all the databases are stopped in INVDEVL. If there are many databases in the system (more than will fit on a screen), display some databases that are near the end of the list, e.g. /DIS DB Z* LSYS INVDEVL, if there are databases whose names begin with "Z". Note: For IMS 1.3 (only) the /DIS DB command will not give a clear indication of when deallocation is complete. You will have to test for availability of the databases in batch, e.g. by running a batch job with DISP=OLD on the databases. This is because in 1.3, the databases are deallocated by COPE, and then immediately started again, but this time pointing to a dummy dataset. This consideration does not apply to IMS release 2 or later. Starting and stopping the system on the transaction side is done in the same way, except for the use of TR instead of DB against the DB/TR on the selection screen. You can start or stop systems from the Selection screen, using S and P in the ACTION field, and blanking out the NAME field, but filling in the SYSTEM field. Command line system STA and STO commands You can start or stop systems, in either the DB or TR Side, from the command line of the COPE main screen by using the following commands: STA STA STO STO <lsys> DB <lsys> <lsys> DB <lsys>
Note: There is no slash (/), and no TRAN keyword between the STA or STO for the Tran Side. COPE provides these commands mainly so that you can issue them via PF keys or batch programs. This is described in the COPE for IMS/DC Administration Guide.
TRACE
To help solve application problems in online programs, COPE provides three debugging facilities:
1. 2. 3.
You can view the DLI and SQL calls your program is making using the Call Trace in ISPF option 7.2. To get a picture of what transactions are running in which message regions, you can view the "Transaction Activity Display" in ISPF option 7.2;T. You can quickly find the cause of problems using the module offsets and Last DLI call information that appears on the "Abend Summary Screen", displayed under IMS via the ABS command.
For batch and BMP regions, you can get the DLI and SQL call traces by adding a //COPETRAC DD SYSOUT=* statement to the JCL. Turning DLI and SQL call trace on For MPP programs, enter COPE TRACE ON from a cleared screen, or TRACE ON from the "=====>" prompt on the COPE main screen, to turn on DLI and SQL call trace. Figure 72: COPE Online - Turning Trace On
------------------------------------------------------------------COPE INVDEVL DFTI8L07 17:18 MSGIMS1 J2853 =====> TRACE ON -------------------------------------------------------------------
Press <Enter>, and *TRACE* appears in the top line, to indicate that the Trace is on for your terminal. An informational message also appears on line 3: Figure 73: COPE Online - Trace Status screen
------------------------------------------------------------------COPE INVDEVL DFTI8L07 *TRACE* 17:18 MSGIMS1 J2853 =====> TRACE ON User DFTI8L07 now has trace ON -------------------------------------------------------------------
117
For batch and BMP regions, you can get the DLI and SQL call traces by adding a //COPETRAC DD SYSOUT=* statement to the JCL. Trace display for MPP programs (ISPF option 7.2) When the Trace is on, COPE sends a copy of all DLI and SQL calls issued by MPP programs that run from your terminal, to the IMS log. After running the transactions that you want traced, switch to COPE under ISPF to view the trace, under option 7.2 ("Trace Display"). Many different terminals may have their traces on at the same time. The viewing mechanism keeps the results separate. To view the trace, in ISPF COPE option 7.2, enter your terminal's name (Lterm or Signon-id) opposite the User field as follows: Figure 74: Option 7.2 IMS Online Traces menu
------------------- IMS Online Traces - COPE System --------------Command ===> Blank - DLI Call Trace ("COPE TRACE ON" under IMS) T - Transaction Activity (Picture of trans by Region) PO - Printoff (Print last trace displayed) User ===> DFTI8L07 Lines ===> 500 Edit/Browse ===> B * - on end for generic (Maximum to display) E or B Time - 1538 Date - 910321
Optional range restriction: From Date ===> 910321 From Time To Date ===> 910321 To Time Optional filters: Trancode ===> * Display ===> D
===> 1537 (Blank, or HHMM) ===> (Blank, or HHMM)
* - on end for generic N - no calls, S - summary, D - details
-------------------------------------------------- STANDARDWARE ---
In the above example, you entered DFTI8L07 as the Lterm name (use the Sign-on id instead, if you use /SIGN in your system). You have also entered the "From Time", to say from what time you want the search for trace lines to start. Other fields have suitable defaults already filled in.
The next 500 lines of trace information after 1537 will be displayed. This is indicated by the 500 in the 'Lines' field, the 1537 in the 'From Time', and the blank 'To Time'. To see the last 500 lines, leave the 'From Time' blank, instead of filling it in. This is not recommended, however, because if no trace lines can be found, it will search the entire log, which may take a long time. To see 500 lines preceding a particular time (other than the current time), fill in the 'To Time'. To fully limit the time range, fill in both. The dates can also be changed from the "today" value provided. In the example above, the default B for Browse is taken. Change this to E for Edit, to be placed in Edit (instead of Browse), on the trace output. The optional filters are a way to limit the search by Trancode, and to control the detail in the display. The Display field may be: N - no calls Use this if you only want to see program traces (such as COBOL Ready Trace) and do not want to see the DLI and SQL call trace. Program Traces are described below, under 'COBOL Ready Trace'. The resultant trace display will show a minimum of detail for each call. The display will be easier to read, but won't contain details such as all PCB fields, or millisecond elapsed times. The display will show all details of PCB fields and timings. Displays COPE transactions (that are usually omitted) and a Counts summary of log record types and volumes. This is useful to Systems Administrators, when reviewing logging performance.
S - summary
D - details C - counts
Hit <Enter>, and the IMS disk logs are read. While they are being read, the lower part of the screen will show a moving graphical display of the disk logs, and the current search position, as follows: Figure 75: Option 7.2 Trace Search in Progress screen
Searching DFSOLP02...... Old___________________________ 1701 Tue_________________________ 0903__________________________ 1146_____________________________ 1345__________________________ 1521____*********+_______________ -------------------------------------------------------------------
In the above display, there are 6 disk logs, each represented by a horizontal bar, with the time (1701 Tue, 0903, etc) on the front. The first log is "Old", meaning the data on it is older than one week (this log is not being used). The second log started at 17:01 on Tuesday, which is yesterday, here. The other four logs are from today, and therefore show just the start time, not the day of the week. A blinking plus sign (+) moves as the log is searched, leaving a trail of asterisks (*), representing
tracks that have been searched. Here the search has proceeded over part of the last log (the one that began at 15:21). When the search is proceeding backwards (as it will initially), a trail of minus signs (-) are left instead of asterisks, which are later obliterated by the asterisks as it reads back forwards. You can use this display to view the search, and thereby estimate how long it will take, using the times as reference points. In this example, the search would be fairly fast, and a few seconds later you are placed in browse on the selected trace records: Figure 76: Trace Records screen
---------------------------------------------------------(((--------COMMAND=> LINE 00000000 COL 001 080 501 LINES DISPLAYED, 15237 LOG RECORDS SEARCHED SCROLL ===> PAGE *************************** TOP OF DATA *************************** **** 15:37 MSGIMS1 INVDEVL CIFAU101 C9000130 COPE:213mS PgmLoad: GU - DFTI8L07 Ioal:337 PCB:1 Pgm:18mS Dli:0mS Pcbmodn&c.CIFSTART ....CIFMNT02 MENU GU - LCIFACCU Ioal:32 PCB:4 Pgm:9mS Dli:2mS Popt&c.G Seg-name &c .CAACTS Ssa1&c.CACPTCFR*V Ssa2&c.CFAINSEG(AINCACTN =20000100) =WARN> GE&c.Seg not found. GNP - LCIFACCU Ioal: 0 PCB:4 Pgm:9mS Dli:8mS Popt&c.G Segname &c .CAACTS Ssa1&c.CACPTXXX =ERR=> AC&c.Ssa Segname/Lvl bad. Segname in Ssa is not in this DB ISRT -- DFTI8L07 Ioal:24 PCB:1 Pgm:10mS Dli:1mS PcbModn&c.CIFSTART .......HIT PF3 TO EXIT. Modn&c.CIFGENER **** 15:37 MSGIMS4 PRODSYS CDEDK100 C0024329 COPE:181mS PgmLoad: --------------------------------------------------------(((----------
In the above example, the beginning of each transaction is indicated by "****" in column 1. Calls have the Function code (GU, GN, etc) in column 1, and PCB information on the same line as the Function Code, and the I/O area (if present) on the next line, and SSAs (if any) following that. If the status code is bad, a "=WARN>" or "=ERR=>" line is produced, as the last of the group of lines associated with each DLI call. What to do if you get no Trace output If your Terminal, From Time/To Time, or Trancode filters give you no output to view, the terminals or transactions in the time period that were filtered out are indicated on special "=MSG=>" lines, with
transaction counts in parentheses, e.g. =MSG=> TRANCODES NOT SELECTED: ABCA1030 (3), TAS* (34) =MSG=> PF3 AND CHANGE LTERM, TIME OR TRANCODE FILTER OPTIONS. The above message tells you about transactions that matched your terminal filter, but not your trancode. It will summarize many similarly named trancodes, as in the "TAS*" example above. If no transactions match your terminal name filter, the message will tell you the terminal names that were filtered out, again with transaction counts in parentheses, e.g. =MSG=> LTERMS NOT SELECTED: DFTI4L* (33), DFTI2L81 (7) You would then correct your filters and retry, or vary the From Time and To Time to search for trace records in a different time period. Details of Trace display The following sub-sections explain each line of the Call Trace in detail. The lines explained are: ------- Example --------**** 15:37 MSGIMS1 GU -- DFTI8L07 .... CIFMNT02 Modn&c.CIFGENER Ssa1&c.CACPTCFR*V =WARN> GE: Segment not found. ==== Loading COPEd pgm C9000130.
Program Start Cobol Ready Trace Function/PCB Ioarea Modname Ssa Message Logic
121
Program start **** 15:37 CIFMNT01 DFTI8L07 MSGIMS1 INVDEVL CIFAU101 C9000130 J2347 Cope:213mS PgmLoad:93mS **** Indicates this line is a "Program Start" line 15:37 Time the program started CIFMNT01 Trancode DFTI8L07 User terminal (Lterm of Signon-id) MSGIMS1 Message Region Jobname in which MPP ran INVDEVL Logical System name CIFAU101 Real program name C9000130 COPE program name J2347 Job number of message region Cope:213mS Time from IMS scheduling to Cope Loading program PgmLoad:93mS Time taken to Load the program COBOL Ready Trace
A0100-etc
Contents of the trace line (blanks truncated off end)
You must compile your program with READY TRACE and RESET TRACE statements, or DISPLAY statements, to receive this trace. This facility works for non-COBOL traces as well. If you are using any language that writes lines to a DD in the message region, you will see the trace here, with the DDname on the front of each line. For example, if the DD is DSNTRACE: DSNTRACE ...some trace data... The special DD's SYSOUT, SYSOUU and SYSOUV get the characters , | and \ on the front of their lines. The DD's must be present in the message region JCL but you will not see any output for them using IOF or SDSF. This diversion of traces from IOF/SDSF to the IMS logs, means that you have less trouble finding your trace, because it is easily displayed using the 7.2 facility, and you don't need to locate the correct message region under IOF or SDSF, nor sift through other people's trace data. COPE always diverts program traces to the log, no matter whether you have TRACE ON or OFF. Your TRACE status only refers to whether or not you want the DLI and SQL call traces. Under COPE, you cannot view program traces in IOF or SDSF, because they are not there. Note: Abend dumps will still appear in IOF and SDSF (they are not diverted to the log, because the overhead would be too high). COPE assists you in finding the correct dump by giving you an =ERR=> line in option 7.2, that shows the abend code and module offset. You look at the preceding **** line, to see the time of the abend, and the message region jobname and job number where you
will find the dump.
Function/PCB GU -- DFTI8L07 Ioal:337 Pcb:1 Pgm:18mS Dli:0mS Pcbmodn&c.CIFSTART GU -- LCIFACCU Ioal: 32 Pcb:4 Pgm: 9mS Dli:2mS Popt&c.G Segname&c.CAACTSEG Nsens:5 Keyf:00... GU IMS Function (1st param) -Status Code from PCB 10 (2nd param), "--" for blank DFTI8L07 Lterm name from TP PCB 0 LCIFACCU Database (external) name from DB PCB 0 Ioal:337 I/O area length (from DIRCA), 0 if no segment transferred Pcb:1 PCB number, 1 always means the I/O PCB Pgm: 18mS Milliseconds elapsed between last DLI call and this one Dli: 0mS Milliseconds elapsed in DLI call Pcbmodn: MFS MOD name from TP PCB Segname&c.CAACTSEG Segment name for DB PCB Nsens:5 Number of Sensitive Segments, from DB PCB Keyf:00... Key Feedback for PCB (use HEX ON to see data value)
I/O Area ...CIFMNT02 MENU 0500CCCDDEFF4DCDE44444444444444444444444444444444444444444444444444 1102396453020455400000000000000000000000000000000000000000000000000 The I/O area hex data is viewed using HEX ON. The length of the I/O area used by COPE came from the DIRCA. If TRUNC was active when the transaction ran, I/O area's longer than 254 bytes are truncated. If NOTRUNC was active, the full I/O area is recorded on the IMS Log, but will only appear under ISPF COPE 7.2 if Browse rather than Edit is used. If Edit is used, long I/O areas will again be truncated. Whenever an I/O area is truncated, either by the IMS COPE Trace, or by the ISPF COPE Trace Edit, the eight characters "<=TRUNC=" overlay the last bytes of the 254-byte trace area, to indicate that the full I/O area is not available for viewing. Modname Modn&c.CIFGENER This is the 4th parameter of some TP ISRT and PURG calls, and specifies to IMS the MFS modname
to be used for formatting the output screen. Note: The PcbModn: is the Modname field from the PCB after the call, and should always match the Modn:, if the latter is present, because IMS sets the PCB field from the 4th parameter.
SSA Lines Ssa1&c.CACPTCFR*V Ssa2&c.CFAINSEG(AINCACTN =20000100) These are the 4th and later parameters of Database DLI calls. Hex data in SSAs can be viewed by using HEX ON. In error situations, where the SSA is overlaid, up to 254 bytes of working storage could appear. The COPE online Call Tracer does not know the actual length of SSAs. It relies on the fact that unqualified SSAs end with a blank, and that qualified SSAs end in a right parenthesis. This also means, that very occasionally, a right parenthesis will appear as part of the data in an SSA, and will be mistaken by COPE Trace as the end of the SSA. In this case the trace of the SSA is incomplete. Message =WARN> GE&c.Seg not found. =ERR=> AC&c.Ssa Segname/Lvl bad. Segname in Ssa is not in this DB. Whenever a non-blank status code is returned by DLI, a Warning or an Error message is shown as the last line of the call trace. Status codes of GE, GA, GB, II, QC and QD produce "=WARN>" messages, and other codes produce "=ERR=>" lines. The messages are defined inside module COPESXP9, and are the same messages returned by COPE to an online IMS terminal on an abend, if the last call status code was bad. The messages are intended to provide enough information for you to solve the problem without consulting the relevant IMS Manual. Logic trace ==== Loading COPEd pgm C9000130.
124
When COPE TRACE LOGIC is on, COPE records messages on the IMS log which describe the processing it is doing, as it is doing it. LOGIC trace messages are shown with "====" (four equals signs) on the front, to make them stand out. The contents of the messages are many and various. They tend to be readable, but may need to be used in conjunction with the source code for COPESXP1. The logic trace helps diagnose problems with COPE. Problems can occur, for example, when MFS is not generated (causing Lsys's to share the same MFS), and for many other minor default-related or generation problems, system JCL changes, and so on. Also, application programmers may find it useful to help solve some non-COPE problems. There is available an even more detailed trace than the LOGIC trace, called "DEBUG ON". This trace comes out on the COPERRMS DD in the message region, is very voluminous, and is system-wide (all terminals) and so must be used with caution. DEBUG trace is definitely NOT readable without the source code for the COPESXPn modules. TRACE OFF command You can turn off DLI Call Trace for your Lterm, with a <CLEAR>, then: COPE TRACE OFF You should turn DLI Call Trace off if you are logged on to IMS, and you are executing many transactions from that terminal, which do not need tracing. The overhead for the trace is typically a 25 percent increase in IMS logging. This is a low overhead, but you may want to make sure you are not incurring it unnecessarily. The trace stays off, across IMS Restarts, until you issue another "COPE TRACE" or "COPE TRACE ON" command. Tracing is always independent of other users, and it doesn't matter which Message Region your transactions run in. If you turn trace on, and then do not issue any IMS transactions from that terminal, there is no logging and thus no overhead. TRACE NOTRUNC command For the DLI Call I/O area, only the first 254 bytes (or less) are usually traced. You can stop this "truncation" of the I/O area trace by using the following commands: COPE NOTRUNC COPE ON NOTRUNC (if TRACE is already on) (when turning TRACE on)
"NOTRUNC" can be shortened to "NOT". The overhead for NOTRUNC is high, and can impact performance, especially if it is accidentally left on for an active terminal. Use the default, TRUNC, wherever possible, and NOTRUNC only when it is necessary to see the contents of segments past the 254-byte truncation point. You can turn TRUNC back on, without turning TRACE off, with a "COPE TRACE TRUNC" command.
The COPE header line shows *TRACE*N* , when NOTRUNC is in effect. TRACE LOGIC command To find out exactly what COPE is doing as your MPP runs, you may turn on a detailed internal LOGIC trace, for your terminal only, with the following command: COPE TRACE LOGIC LOGIC can be shortened to LOG. The output is viewed under ISPF COPE 7.2, as with normal DLI and SQL Call Trace. LOGIC lines come out with "====" (four equals signs) on the front, to make them stand out. Enter "COPE TRACE NOLOGIC" to turn the logic trace off. "*TRACE*L*" is an example of a header line, with "L" for LOGIC on. Logic trace has a moderate performance impact (not as large as NOTRUNC). The messages produced by Logic Trace are readable, but may need to be viewed in conjunction with the source Code of module COPESXP7, the main online COPE processor module.
Transaction Activity Display (ISPF 7.2.T)

Enter T on the 7.2 Trace menu to display a picture of all transactions that have run in a recent period of time. This is useful for finding out the Trancode or Program name used by IMS screens you are not familiar with. It also shows you some key performance indicators for individual transactions, such as the number of Database Get calls, number and volume of Update (Insert, Delete and Replace) calls by database name, elapsed execution time, and input queue time. The Transaction Activity Display is not dependent on whether Lterms have their COPE DLI and SQL Call Traces on or off. To view the Transaction Activity Display, in ISPF COPE option 7.2, enter T on the command line:
126
Figure 77: Trace Selection screen
------------------- IMS Online Traces - COPE System --------------COMMAND ===> T Blank - DLI Call Trace ("COPE TRACE ON" under IMS) T - Transaction Activity (Picture of trans by Region) PO - Printoff (Print last trace displayed) User ===> DFTI8L07 Lines ===> 500 Edit/Browse ===> B * - on end for generic (Maximum to display) E or B Time - 1538 Date - 910321
Optional range restriction: From Date ===> 910321 From Time To Date ===> 910321 To Time Optional filters:
===> 1537 (Blank, or HHMM) ===> (Blank, or HHMM)
------------------------------------------------ STANDARDWARE -----
The Transaction Activity Display does not use the User field, nor the Optional Filters at the bottom of the screen. It displays all transactions from all terminals no matter what is in these fields. The other input fields are used in the same way as for DLI Call Trace, and are filled in for you, with suitable defaults. Hit <Enter>, and the IMS disk logs are read, and then you are placed in Browse on the generated picture of the transactions that recently ran:
127
Figure 78: Transaction Activity screen
------------------------------------------------------------------COMMAND=> LINE 00000000 COL 001 080 495 LINES DISPLAYED, 7323 LOG RECORDS SEARCHED SCROLL ===> PAGE ************************ TOP OF DATA *************************** 15:37:02 -------------0.3RESHOW DFTI8L07 RESHOWP7 INVDEVL 15:37:03 R: USTDLMGR: 10K -------------0.0G: 23 R: 1 TRANCODE TERMINAL -------------2.7PSBNAME LSYS G: 7 -------------0.3MSGCOPEA MSGCOPEB -------------------------------------------------------------------
The above example shows the features of the Transaction Activity display. Each box represents a program running in a message region. The left hand column shows the time, in HH&c.MM&c.SS format. Next to this is a column in which will appear transactions that ran in the first Message Region. If you go down to the bottom of the display, you would see the jobname for this message region (shown as MSGCOPEA here). Each succeeding column is a different message region, and the columns are across the page in ascending order by message region jobname. Columns for BMPs will appear to the right of the columns for the message regions that were found to be running. In the columns, a box represents a single program scheduling: Input Queue Time .-------------0.3-. Trancode --->|RESHOW DFTI8L07|<-- Terminal PSB -------->|RESHOWP INVDEVL|<-- Logical System Update Bytes by DB --->|R: USTDLMGR: 10K| .->|G: 23 R: 1|<-- Number of Update Calls | -------------2.7- | Execution Number of Time Get Calls
In the above example, the transaction spent 0.3 seconds on the Input Queue. It had Trancode RESHOW, and was from terminal DFTI8L07. The PSB (program name) was RESHOWP, and it ran in Lsys INVDEVL. It issued 23 Database Get calls, and one Update call, which was a Replace. Database "USTDLMGR" had 10K bytes logged by the replace call. The transaction executed for 2.7 seconds. The total internal IMS response time was 3.0 seconds (0.3 plus 2.7). Most transaction boxes look like this example. For more complex transactions, the information is summarized, so there are fewer details, but the overall view is always accurate. Update bytes by DB details A summary of update bytes by DB is in the middle of the box: Update bytes by DB details .-------------0.3-. |RESHOW DFT18L07| |RESHOWP INVDEVL| Update Bytes by DB -->|R: USTDLMGR: 10K| |G: 23 R: 1| '-------------2.7-'
R:
A combination of the letters I, D and R show the types of update calls (ISRTs DELTs and REPLs) that were issued against the database. In the above example, only REPL was issued, so only an R is shown. The DBD name updated is shown. Up to 4 lines of updates will be shown. When more than 4 DBDs are updated, like-named DBDs will have their names combined in one line, with an asterisk (*) on the end of the name, e.g. TASATHDB and TASATHPR would summarize as TASATH*. This is an indicator of the bytes updated. It is actually the length of the change records logged, so in IMS 3.1 shows the compressed size.
USTDLMGR
10K
Number of Get calls and number of Update calls The last line in the box has call counts:
129
Number of Get calls and number of Update calls .-------------0.3-. |RESHOW DFTI8L07| |RESHOWP INVDEVL| |R: USTDLMGR: 10K| Number of Get calls -->|G: 23 R: 1|<-- Number of Update calls '-------------2.7-'
G: 23 R: 1
This example did 23 database get calls (may have been GU, GN, GNP, GHU, etc). If there were no database get calls, the G: will be absent. This example did 1 update call, and it was a REPL. A combination of the letters I, D and R will show the type of calls present (ISRTs, DLETs and REPLs) and the number following will show total update calls. For example "IR: 7" would indicate some mix of 7 ISRT and REPL calls.
Multiple transactions in one program scheduling A program may process more than one transaction, before ending:
Multiple transactions in one program scheduling .-------------0.3-. |RESHOW DFTI8L07| |RESHOWP INVDEVL| |R: USTDLMGR: 10K|<--- Update bytes 1st tran |=============1.3=|<--- Execution time 1st tran Second transaction |RESHOWT DFTI8L07| (trancode RESHOWT, |RESHOWP PRODSYS| and system PRODSYS |I: USTDLMGR: 5K|<--- Update bytes 2nd tran different from first)|G: 30 IR: 2|<--- Counts include both '-------------1.4-'<--- Execution time 2nd tran First transaction
This example shows the display for a program scheduling that processes two transactions. The trancode, terminal name, and Lsys could be the same or different in each transaction. The update bytes are by transaction, but the final call counts are not (they apply to the entire program scheduling). There will be a "======" separator line for each extra transaction. Note: Notice that each transaction may execute in a different COPE Lsys.
130
Abend indicator If a transaction abends, the abend code appears in the bottom left of the box. An example is an S0C7:
Abend Indicator .-------------0.3-. |RESHOW DFTI8L07| |RESHOWP INVDEVL| |R: USTDLMGR: 10K| |G: 23 R: 1| '-S0C7!-------2.7-'
An example of a user abend code would be U1004. The exclamation mark is placed after the abend code. You may enter a "FIND !" command in a long display, to find abended transactions quickly.
Abend Summary Screen

When an IMS transaction abends, press <PA1> on the DFS555I message, to clear it out, then type COPE ABS, to display the COPE Abend Summary screen. Often, you can easily solve the problem immediately from the "Abend Description" or "Status Code Description" on Line 3, the "Module Call" trace, and/or the "Last DLI Call" display. You can check your compiler listing, for the "Call Offsets" given, for Module or DLI calls, without looking at dumps or linkedit maps. If you need the dump, the message region jobname, number, and time in the header line help you locate the correct dump. The lines of the Abend Summary screen are described in detail below:
Abend Description Abend Offset Status Code Description Module Call trace Last DLI Call display Module Offsets Date Linkedited
-------------- Example ------------U0476: 2nd parm not a PCB addr, or only 1 parm CIFAU154+01A8&c.S0C7! A1: Destination in 3rd parm has to be in Imsgen CIFAU101+032E: Called CIFAU154 Last DLI Call: GNP GE ISSREFDB Ioal:0 PCB:4 CIFAU154+05F2: Last DLI Call CIFAU154 linkedited 90/06/14, dsn=
131
Abend summary - Abend description Figure 79: Abend Description screen
------------------------------------------------------------------COPE INVDEVL DFTI8L07 14:37 MSGIMS1 J1769 U0476&c.Bad PCB Addr =====> U0476: 2nd parm not a PCB addr, or only 1 parm, or Psbgen "LANG=" bad DFSECP10+0254:U476!Tran&c.CIFMNT01 Pgm&c.CIFAU101(C0029204) INVDEVL CIFAU101+03EC: Last DLI Call: GU -------------------------------------------------------------------
The messages in the top right-hand corner and on line 3 explain the meaning of the Abend code, if it is an IMS abend or system abend. In this example, you would look at your CIFAU101 compiler listing, for a bad GU call at +03EC. Figure 80: Abend S0C7 display
------------------------------------------------------------------S0C7&c.Bad Numeric =====> S0C7: Add Packed X'12345F' X'4040' (Sign '0') CIFAU154+01A8&c.S0C7!Tran&c.CIFMNT01 Pgm&c.CIFAU101 (C0029204) INVDEVL -------------------------------------------------------------------
For an S0C7, COPE shows you the instruction (Add Packed), the two fields in hexadecimal, and tells you what is wrong with one or both fields (Sign "0"). Here, at +01A8 in the CIFAU154 listing, a 2byte field for an ADD is blanks (Hex 4040).
132
Abend summary - Abend offset Figure 81: Abend Offset display
------------------------------------------------------------------S0C7&c.Bad Numeric =====> S0C7: Add Packed X'12345F' X'4040' (Sign '0') CIFAU154+01A8&c.S0C7!Tran&c.CIFMNT01 Pgm&c.CIFAU101 (C0029204) INVDEVL -------------------------------------------------------------------
The fourth line of the screen shows you the module name and offset where the abend occurred. Here, the module is CIFAU154, and the offset is 01A8. At, or near, 01A8 in CIFAU154's PMAP or Condensed Listing, you would find a statement that does a calculation, involving an addition. The offset matches the compiler listing offsets, so you do not need to consult a linkedit map. Abend summary - Status code description Figure 82: Abend Status Code display
------------------------------------------------------------------COPE INVDEVL DFTI8L07 14:58 MSGIMS1 J1771 A1&c.Dest bad =====> A1&c.Destination name in 3rd parm has to be Trancode or Lterm in Imsgen CIFAU101+0A28: U1001! Tran&c.CIFMNT01 Pgm&c.CIFAU101 (C0029204) CIFAU101+0A04: Last DLI Call: CHNG 'A1' ALT-PCB Ioal:8 PCB:3 CIFAU101+30E0: Dest: DFTI8LP2 -------------------------------------------------------------------
The messages tell you the meaning of the IMS status code returned by the last DLI call. In this example, you would look at the CHNG call at +0A04 in the CIFAU101 compiler listing, which is referring to DFTI8LP2 at +30E0. This Lterm name may be wrongly coded inside the module, or could have been entered on a user screen, or perhaps should be added to the IMSGEN.
In this case, COPE does not "know" the U1001 abend code, because it is not an IMS abend code. If COPE knows the Abend, and there is also a bad status code in the last DLI call, it puts the short abend message in the top corner, and the long status code message on line 3. Abend summary - Module call trace Figure 83: Abend Summary - Module Call Trace display
------------------------------------------------------------------COPE 14:58 MSGIMS1 J1771 IxSeg not found =====> NE:2ndy Index can be rebuilt by reorg. Caused by bad sparsing routine BADCODE+4E:U1003! Tran&c.CIFMNT01 Pgm&c.CIFAU101 (C0029204) INVDEVL CIFAU156+E4: Called BADCODE CIFAU154+0102: Linked CIFAU156 CIFAU111+032E: Called CIFAU154 CIFAU156+A2: Last DLI Call: GU 'NE' ISSREFS4 Ioal:0 PCB:7 -------------------------------------------------------------------
The messages containing "Called" show that a static call occurred from one module to another. "Linked" denotes a dynamic call. The most current module is at the top (BADCODE), followed by the module that called it (CIFAU156), and so on, in reverse order. The main module in this example is CIFAU101, because it is in the last message containing "Called" or "Linked". The "Last DLI Call" message is not a part of the Module Call trace. Modules that were previously called by other modules, and have returned, are not on the current call path, and therefore will not appear in this list.
134
Abend summary - Last DLI call display Figure 84: Abend Summary - Last DL/1Call display
------------------------------------------------------------------COPE INVDEVL DFTI8L07 =====> S0C9&c.Divide by 0, or result too big, due short dividend or long divior CIFAU101+2280&c.S0C9!Tran&c.CIFMNT01 Pgm&c.CIVAU101 (C0029204) INVDEVL CIFAU101+220C: Last DLI Call: GU "--" ABCINSCB Ioal:400 PCB:5 Lv1:01 Popt&c.GOTP Segn&c.ABIACSEG Nsens:2 Keyf:02000010 0F CIFAU101+4308: I/Oa: ......... ACCT 20000100 SHORT TITLE 20444444444444444CCCE4FFFFFFFF4ECDDE4ECEDC4 0C00000000000000013330200001000286930393350 CIFAU101+42F0: Ssa1: ABIACSEG(ABIACKEY =.....) CCCCCECC4CCCCCDCE47000105 12913257D129132580E2000FD --------------------------------------------------------------------
The Last DLI Call was a GU with blank status (shown " - - ") on Database ABCINSDB. It returned a segment of length 400. The PCB Number is 5 (5th PCB in PSB, including the I/O PCB). Other PCB fields shown are Level (01), Procopt (GOTP), Segment Name (ABIACSEG), Number of Sensitive Segments (2), and Key Feedback Area in hex. The start of the I/O area, and each SSA (only 1 in this example), are shown in character and vertical hexadecimal. Abend summary - Module offsets Figure 85: Abend Summary - Module Offsets display
------------------------------------------------------------------CIFAU154+061E: U1005! Tran&c.CIFMNT01 CIFAU101+A8: Called CIFAU154 CIFAU154+05F2: Last DLI Call: GN '--' ABCINSDB CIFAU154+18B0: I/Oa: ......... 008044: Ssal: ABIACSEG(ABIACKEY) =.....) -------------------------------------------------------------------
135
The Module Name and Module Offset are given on the front of many messages. The Module Name is the external name, not the COPE C-number name. Physically, the module can exist in a load library with a COPE C-number name. The Module Offset is in hex (for example +A8) form, omitting leading zero bytes. It is relative to the start of the module, not the load module that the module may be linked in to. COPE finds the position of all modules within the load module, to get the offset. The offset matches compiler listing addresses (PMAP in COBOL). When an area is in Getmained storage, the 4-byte storage address is given (as in 00008044 above). This has no direct relationship to offsets shown in compiler listings, but can be used to locate the area in the dump. Abend summary - Date link-edited Figure 86: Abend Summary - Date Link-edited display
------------------------------------------------------------------CIFAU154 link-edited 90/06/14, dsn=T.COPE.PGMLIB -------------------------------------------------------------------
The module that abended has its linkedit date printed, along with the library that the module was loaded from. Note: In message regions where you preload modules, you need to check whether the module was preloaded. If it was, then it will have been preloaded from the COPESTEP DD, and the date linkedited shown in this message may be inaccurate; it might be showing the date linkedited for a module in the "C00000n" Lsys-specific DD, which might be different from the module you preloaded into the message region.
Bring in new Versions of COPE tables (REFRESH)

The first time you compile a new MFS format into an Lsys, you have to issue REFRESH. This will refresh the MFS C-number translate table. This table only changes when you add an MFS format into an Lsys, the table does not change when you replace an existing format.
System administrators do IMSGENs which add new PSBs etc., and then issue REFRESH to cause the message regions to load the new versions of the COPEXRFn modules. These modules contain tables which translate PSB and DBD names to C-numbers. When you logon to an Lsys, messages appear telling you whether the system uses Tasklib Switching or not. Message No Tasklib Switching Meaning Programs are loaded using C-numbers. You must issue REFRESH after every program compile. If you do not REFRESH, the old version of the program may continue to be loaded into the message region. Your administrator may have set up the compile JCL to automatically issue the REFRESH, via a BMP step. Programs are loaded using real names. In this case, there is no importing of programs, and the latest version of the program will always be picked up, so there is NO need to REFRESH after a compile.
Tasklib Switching
Displaying Link Date/DSN of a Program (VERSION)

Displays the date link-edited, and the dataset name, for a program. Type in VERSION ABCA1040 (for example) and you will see: ----+----1----+----2----+----3----+----4----+----5----+---6-Loaded "ABCA1040", 24408 bytes 0001F0A8:..........h...h.....h....0........q........................... 9ED0034B328B008D001D81325F370E5D009ED00F0000000000000000000000 0C0C5010068D088B048B800280025F8D048C0C7E0000000000000000000000 ABCA1040 link-edited 91/05/08, dsn=TFTPROD.CTF4BASE.PGMLIB, dd=COPEL009 The program is 24408 bytes long. The first 62 bytes at the entry point to the program are shown. It was link-edited on May 8th, into the PGMLIB shown.
System Commands for COPE Administrators

System administrators need to be familiar with commands that are used to debug COPE, refresh internal tables after gens, submit batch jobs, synchronize status after problems, and other rarelyused functions. In normal operation, these commands are either issued automatically (REFRESH, for example) or are not used.
You can receive a description of the commands by hitting <PF1> from the COPE screen, then selecting option 12 on the online tutorial panel, and then selecting one of these sub-options: Option COLDS DEBUG IMS nn REFRESH SUB SYNC VERSION VERSION LLE @<storage> Used for Automatic Cold Start command (also WARMS and EMERS) Debug COPE itself Set physical IMS id number Bring in latest versions of COPE tables Submit a job from JCL library Synchronize Start/Stop, to "wake up" terminals Display the version (date/time assembled) of COPE modules Display Load List Elems (shows Preloaded/Loaded modules) Display Storage by hex-address, module name, or label
138
Setup of ViaSoft Smart-Test option

To allow operation of the ViaSoft Smart-Test package, the user must specify certain datasets in the setup of the test. COPE ViaSoft support consists of two components: 1. 2. A front end to the DFSRRC00 DLI access program A Modblks member that allows selection of PSB's and transactions that contain the original (non C-number) names.
The Lsys is identified by a token in the IMSID field of the DLI parm field. This token is the same as that specified for a BMP or batch program to identify an Lsys. It is the token specified in the 4.10.2 COPE application by the COPE Systems Administrator.
Smart-Test setup
Your existing Smart-Test installation should be accessed and the following setup steps performed: 1. 2. 3. 4. Specify the correct IMS RESLIB for COPE Specify the correct IMS modblks library and suffix for COPE Specify the correct application load libraries Specify the desired COPE Logical system in the IMSID Parm field
To operate a test correctly, you should know the following: 1. 2. 3. 4. The name of the IMS RESLIB for COPE (ZDEFAULT parameter XCOPEIRS) The name of the IMS Modblks library The Stage 1 suffix used for the ViaSoft member (ZDEFAULT parameter XVIASUFF) The tokens used to identify COPE Logical Systems (4.10.2 specifications).
To perform the library specifications, place the cursor in the 'File' field of the top line of the panel shown in the following figure and press <Enter>.
139
Figure 87: Viasoft - Initial screen
File View Test Search List Options Help --------------------------------------------------------------------VIA/SmartTest R3.0 Command ===> _________________________________________________________________ *** *** *** **** ======= ====== ================= *** *** *** ***** ========== ========= =============== *** *** *** ****** === === === === === *** *** *** *** *** ========= === === ======= === *** *** *** *** *** ========= === === ======= === ****** *** ********* === === === === === ***** *** *** *** ========== ========= === === **** *** *** *** ======= ====== === === nc. A proprietary product of VIASOFT Inc. Use restricted to authorized licensees.
Select option 1 on the resulting selection panel shown in the following figure:
140
Figure 88: Viasoft - Setup Test Option Selection screen
File View Test Search List Options Help -------------------------------------------------------------------| 1 1. Setup test environment... | rtTest R3.0 | 2. Open... |__________________________________ | 3. Close | | 4. Save | | 5. Compile/Analyze... | | 6. AKR utility... | | 7. Edit pseudo... | | 8. Execute... | | 9. Exit | --------------------------------- ===== ====== ============== *** *** *** ***** ========== ========= ============= *** *** *** ****** === === === === === *** *** *** *** *** ========= === === ======= === *** *** *** *** *** ========= === === ======= === ****** *** ********* === === === === === ***** *** *** *** ========== ========= === === **** *** *** *** ======= ====== === = Inc. A proprietary product of VIASOFT Inc. Use restricted to authorized licensees.
Select the setup of the current environment as shown below:
141
Figure 89: Viasoft Current Environment Setup Selection screen
File View Test Search List Options Help ------------------------------------------------------------File - Setup Test Environment | | Command ===> ________________________________________________ | | | | Select the desired Setup option. Then press Enter. | | | | Current environment is IMS/DC | | | | Setup Options | | 1 1. Setup current environment | | 2. Select execution environment | | 3. Specify AKR, loadlib, and/or proclib names | | 4. Select saved test session profile | | 5. Tailor test session | | 6. Specify load module intercepts | | | --------------------------------------------------------------A proprietary product of VIASOFT Inc. licensees. Use restricted to authorized
Select the 'Verify IMS/DC allocations' by entering 'V' in the panel shown below:
142
Figure 90: Initial BMC Delta/IMS Selection menu
IMS/DC Session Setup Command ===> v R - Begin IMS/DC test session (RUN) C - Convert batch JCL to CLIST D - Define Transactions/LTERM V - Verify IMS/DC allocations Execution: (optional) Options: IOPCB LTERM . . IOPCB Break on entry (Y/N) YES Initial FORMAT GEMENU Toggle PFKEY . . . . PF12 DB2 Subsystem name . ____ Data base region type: DLI/DBB/BMP/IFP BMP File allocation CLIST: Data set name . '$DBDAT.JCL.CNTL' Member . . . . CLIST Deallocate after test YES
Enter 'A' to review all IMS allocations as shown below:
143
Figure 91: Viasoft IMS Setup Selection menu
IMS/DC Session Setup -------------------------------------------------------| IMS/DC Allocation Selection | | Command ===> a | | | | 1 - FORMAT/DBRC allocation | | 2 - DFSRESLB/DFSESL/MODBLKS allocation | | 3 - PROCLIB/DFSVSAMP allocation | | 4 - PSB/DBD allocation | | 5 - ACB allocation | | 6 - IMSMON allocation | | 7 - IEFRDER allocation | | 8 - DFSSTAT allocation | | 9 - FPTRACE allocation | | | | P - IMS Region Control Execution Parameters | | | | A - ALL (Display all of the above in succession) | | | | R - Restore default values for all of the above | --------------------------------------------------------
Options '2' and 'P' are required by COPE. COPE will override any specifications of PSB or DBD libraries. All other specifications are left unmodified. Using Option 2 you must specify the correct IMS RESLIB used by COPE. In addition, the correct Modblks dataset and the modblks member suffix must be specified for correct operation of transaction selection.
144
Figure 92: Viasoft RESLIB and MODBLK Specification screen
IMS/DC Session Setup -------------------------------------------------------| IMS/DC Allocation Selection | | ------------------------------------------------| | | IMS DFSRESLB/DFSESL/MODBLKS Allocation | | | | Command ===> __________________________________ | | | | | | | | Enter IMS Load Library Data set names: | | | | 'SYS1.IMSVS.APPL.RESLIB' | | | | ______________________________________________ | | | | ______________________________________________ | | | | ______________________________________________ | | | | | | | | Enter DB2 Load Library Data set names: | | | | 'SYS1.DB2T.DSNLOAD' | | | | ______________________________________________ | | | | | | | | Enter IMS/DC MODBLKS Library Data set name: | | | | 'IMSVS.TST1.MODBLKS' | | | | | | -- | Enter IMS/DC MODBLKS member suffix: T | -------------------------------------------------
Option 'P' allows specification of the Parm fields supplied to DLI. The only one that COPE requires is the IMSID field, which must contain a name that is associated with the Lsys that you want to test against. With COPE, the IMSID field is NOT the name of the IMS control Region. (The correct name is substituted at execution time by COPE). The field is used instead to specify the particular Lsys you want to test against.
145
Figure 93: Viasoft IMSID/Lsys Specification screen
IMS/DC Session Setup -------------------------------------------------------| IMS/DC Allocation Selection | ------------------------------------------------------------------| IMS BMP Parameters | Command ===> ___________________________________________________ | | Enter IMS BMP Execution parameters: | | IN . . ________ (Input transaction code) | OUT . . ________ (Transaction code or logical terminal for output) | OPT . . N (Operator option N, W, or C) | SPIE . 0 (SPIE option 0 or 1) | TEST . 0 (Validity check call list address 0 or 1) | DIRCA . 000 (Region interregion communication area) | PRLD . __ (DFSMPLxx suffix or leave blank) | STIMER 0 (Timer to be set 0 or 1) | CKPTID _____________ (Checkpoint ID for restart or leave blank) | PARDLI 0 (Parallel DL/I option 0 or 1) | CPUTIME 0 (CPU time for IMS) | NBA . . ___ (Number Fast Path data buffers) | OBA . . ___ (Number additional page-fixed buffers) | IMSID . AI01 (Subsystem identifier) | AGN . . ________ (Application Group Name) | SSM . . ____ (DB2 subsystems member) | PREINIT __ (DFSINTxx suffix or leave blank) -------------------------------------------------------------------
With the exception of these specific requirements, the operation of SmartTest remains the same. Information about the use of the product can be obtained from the ViaSoft Smart-Test manuals.
146
Setup of HourGlass support

The COPE Year 2000 feature supports HourGlass made by Mainware and TicToc made by Isogon. Either product must be acquired separately by users of the COPE Year 2000 Feature. The COPE Year 2000 Feature allows every Logical System to have a different setting of the system date and time. Both Batch and on-line support of IMS is provided. The desired dates and times are defined inside the ISPF portion of COPE and the resulting specifications are generated into the COPEXRF4 load module for use by the execution environment. Some Logical Systems may use the system date and are excluded from the time and date manipulation, whilst other logical systems have altered dates. The COPE HourGlass support may be activated by specifying XHRGLASS=YES in the ZDEFAULT PROCS copy. When the XHRGLASS parameter is specified an additional selection option will appear on the administrators panel. Option 13 appears as follows: Figure 94: Administration menu with Hourglass option
------------------ Administration - COPE System -------------------Option ===> 1 - DEFINE - Define Libsets and Logical Systems 2 - IMSGEN - Import and Generate Stage 1 and Dynalloc 3 - DRAW - Display Picture of Libsets 4 - RELATED - Define Related Types 5 - DEFAULT - Define Default Compile Parameters 6 - CALLED - Define Called Module Entry Points 7 - PSBGEN - Generate Combined PSBs 8 - ACBGEN - Generate ACBs 9 - JCL - Convert MSG/BMP/Batch JCL 10 - DB2 - Bind DB2 Plans 11 - MDS - Modify Message Region Dataset Allocations 12 - MSC - Synchronize MFS names between MSC systems 13 - VDATE - Specify a virtual date and time for HourGlass
When Option 13 is selected the following panel is displayed:-
147
Figure 95: Virtual Date Specification screen
Edit Virtual Date for a Lsys - Table Data Panel --ROW 1 OF 7 COMMAND ===> SCROLL ===> CSR Commands: FIND/POPUP/REPORT View.: none Rcd(s): S/R/I/D/C/M/DD/RR View.: none PROJECT GROUP TIME REL"VE Rcd NAME NAME MM/DD/YYYY HH:MM ACT"L ..... FTCOPE COPEA 01/06/1996 01:27 A ..... FTCOPE COPEB __________ ______ _ ..... FTCOPE COPEC -100 -01:27 R ..... FTCOPE COPED 1246 +01:27 R ..... FTCOPE COPEF -487 -10:27 R ..... FTCOPE COPEG 09/01/1996 ______ A ..... FTCOPE COPEH 05/10/1999 11:46 A ***** ********************** BOTTOM OF DATA **********************
All defined Logical Systems are displayed. The user may specify 'Absolute' or 'Relative' dates for each system. If the date is not to be manipulated, all fields should be left blank next to the Logical System If an 'Absolute' date is specified, the date and time for every on-line and BMP and Batch job will always remain the same. The date may be either specified in the form MM/DD/YYYY or as a number prefixed by a + or - sign. If a number is specifies for an absolute date, it will be converted to a date of the form MM/DD/YYYY when the enter key is pressed. A 'Relative' Time/Date specification will cause a fixed amount to be added to the current date/time. This will allow a realistic set of dates to be obtained during testing over several days. The time specification may be left blank which will result in the use of the current system time for the Logical System.
JCL Requirements
An additional DD card should be added to all COPE controlled message regions as follows://HGIMSMSG DD DUMMY This DD is required by HourGlass. No additional DD statements are required for batch or BMP jobs since they will be added automati148 COPE for IMS/DC Programmers Guide
cally by COPE. The Logical System must be identified in the JOB card, the COPEBSYS DD statement, or in the IMSID field as is for all COPE jobs.
HourGlass Abends
COPE will check on the presence of HourGlass for logical systems that require the date to be altered and will abend with a 779 Abend code if HourGlass is not started and running. This will prevent accidental updating of the data with incorrect dates due to operational difficulties.
149
Use and Setup of the IBM Debug Tool under COPE and IMS for non Language Environment Programs
There are three IMS environments discussed. 1. Debugging a MPP program 2. Debugging a BMP program 3. Debugging a DLI/DBB program
IDebugging a MPP program

Using DEBUG Tool with COPE for a MPP non Language Environment program requires the user to use the EQASET transaction e.g. EQASET MFI=terminal_lu_name Where terminal_lu_name is the name of the DEBUG Tool Vtam terminal. Debugging may be turned on and off by the IMS transaction EQASET ON/OFF
Debugging a BMP program

Using DEBUG Tool with COPE for a BMP non Language Environment program require the user to add to the JCL that is used to run the BMP. 1. The IMSID must be DEBG or DEBA and the terminal_lu_name must be added to the PARM field 2. A COPEBSYS DD card must be added to specify the Logical System 3. A PARMFILE DD statement must be added 4. Additional DD statements as required The DFSRRC00 PARM field changes The IMSID must be DEBG. This will inform COPE that the DEBUG Tool is being used. In addition the APARM parameter must contain the DEBUG Tool terminal_lu_name e.g. //BMP EXEC PGM=DFSRRC00, // PARM='BMP,TESTDLT0,DFSSAM09,,,,CL,,,1,,,,DEBG,IVP,,,,TRMLU001' A A A A Application Program' | | | PSB Name--------' | | IMSID--------------------------' '---APARM If the application program requires an APARM parameter, The IMSID must be set to DEBA and the terminal-lu-name specified in the PARMFILE data
Add a COPEBSYS DD card COPE requires to know the environment that the application is executing within. This is done by adding a COPEBSYS DD statement with the Logical System specified as part of a temporary dataset name e.g. //COPEBSYS DD SPACE=(TRK,1),UNIT=SYSDA,DSN=&&IVP9A In the example the Logical System name is IVP9A. Your COPE administrator will provide you with the tokens that you may use. Add a PARMFILE DD statement Run time options are required to start DEBUG Tool. These are passed through a file with name PARMFILE e.g. //PARMFILE DD * /TEST(,,,MFI%TRMLU001:*),TRAP(ON) /* The example shows an in stream file but a sequential or PDS dataset may be used. The terminal_lu_name is overridden with the APARM data extracted from the DFSRRC00 PARM if DBUG is used as the IMSID else it must contain the users terminal_lu_name if DEBA is used as the IMSID. Add additional DD statements as required DEBUG Tool makes use of INSPLOG file and a batch COPE trace may be started with a COPETRAC DD card e.g. //INSPLOG DD SYSOUT=* //COPETRAC DD SYSOUT=*
151
Debugging a DLI or DBB program

The changes to the JCL are identical to those described for a BMP program. The format of the PARM field for DFSRRC00 is different. An example follows //BMP EXEC PGM=DFSRRC00, // PARM='DLI,TESTDLT0,DFSSAM09,,,,,,,,,,DEBG,,,,,,,,TRMLU001' A A A A Application Program-' | | | PSB Name-------' | | IMSID----------------------' '---APARM
152
SETUP of DEBUG TOOL for COPE

Change EQAOPTS
1. Copy the EQAOPTS member from the hlq.SEQASAMP library to a private library. 2. Make the following changes EQAXOPT GPFDSN,'TFTPROD.DEBUG.COPE' EQAXOPT SVCSCREEN,ON,CONFLICT=OVERRIDE,MERGE=COPE The GPFDSN parameter must be an installation dataset name.
Update the Global Preferences File.

The Global Preferences File specified with the GPFDSN EQAXOPT macro should contain the following statements. SET SET SET SET DISASSEMBLY ON; DISASSEMBLY OFF; AUTOMONITOR ON LOG; DYNDEBUG ON;
The first two statements are required else Language Environment will abend with a U4083. Other statements may be added or deleted. (Note: Statements must start in Column 8 and finish with a semi-colon)
153
SPOC Feature of COPE setup and use

Description of the COPE SPOC Feature
The Single Point Of Control (SPOC) feature of IMS allows type 1 and type 2 commands to be issued from an ISPF session and displays the results of the commands. Commands and their responses are stored, and the commands may be reissued at any time. The COPE SPOC Feature modifies the operation of the IMS SPOC TSO Feature, and translates Program and Database names to COPE names for all or specific Logical Systems. Responses from IMS are also translated to display the COPE names ant the real user names. In addition to the command facilities, the COPE SPOC feature also uses the Dynamic Resource Definition Feature (DRD) of IMS and updates an executing system with new definitions of transactions, databases (DBDs) and programs (PSBs) associated with all COPE Logical Systems
Accessing the COPE SPOC Command application

When the feature is installed, the primary ISPF COPE panel has the following appearance :Figure 96:Prime ISPF COPE Panel with SPOC Feature -------------------- COPE Development System -----------------------Option ===> 1 - Browse Version 4.2.10 2 - Edit Date 07/09/07 3 - Utilities Time 23:50 4 - Administration Julian 07.250 5 - Special Utilities Screen 1 6 - Dictionary z/OS 1.07.00 7 - IMS Online IMS 10.1.0 8 - COPE Wizard T - Translate Function 9 - IMS Application Menu (SPOC+KLBA) X - Exit RELEASEA TFTPROD.COPE1.PROCS
Physical IMS Procs Dataset
.-------------. .-------------. .------------. .------------. ]Enter "JOB" ] ]Enter "EDIT" ] ]Enter "BROW"] ]Enter "UTIL"] ]to review job] ]to access ] ]to access ] ]to access ] ]status ] ]ISPF Edit ] ]ISPF View ] ]ISPF Utility] ------------- ------------- ------------ ------------ Lsys Licenced 99 Expiry Date= 08/12/31 Copyright (c) 1989-2007 Standardware Inc.
Selecting Option 9 displays the following IMS Application Menu:154 COPE for IMS/DC Programmers Guide
Figure 97:IMS Application Menu Help -----------------------------------------------------------------IMS Application Menu Command ===> Select an application and press Enter.
1 2 3 4 5 6 7 8 9
Single Point of Control (SPOC) Imsplex=PLEX1 Manage resources Route SYSid=IVPA Knowledge-Based Log Analysis (KBLA) HALDB Partition Definition Utility (PDU) Syntax Checker for IMS parameters (SC) Installation Verification Program (IVP) IVP Export Utility (IVPEX) IPCS with IMS Dump Formatter (IPCS) Abend Search and Notification (ASN)
To exit the application, press F3.
Selecting option 1 displays the following Command Entry Panel :-
155
Figure 98:SPOC Command Entry Panel File Action Manage resources SPOC View Options Help -------------------------------------------------------------------PLEX1 IMS Single Point of Control Command ===> Plex . . Response for: CSLM000I (C) Copyright IBM Corp. 2000. All rights reserved. Route . . Wait . .
Before commencing operations, position the cursor on the Options word on the top line and press enter. Select Option 1 Preferences from the drop down panel. The following will be displayed :-
156
Figure 99:Options Preferences panel Help -------------------------------------------------------------------PLEX1 IMS Single Point of Control Preferences Top of data Command ===> Select your options and press the Enter key. More: Command Entry Preferences Default IMSplex . . . . PLEX1 Default routing . . . . IVPA +
Wait interval . . . . . Waiting preference . 1
1. 2. 1. 2.
Wait for command to complete. Do not wait for command response. Use command shortcuts. Do not use command shortcuts.
Command shortcuts . . 1
Shortcut processing .
1. Merge explicit and default parameters. 2. Explicit parameters override defaults. 1. SPOC command panel.
Initial view
. . . . 1
. he default IMSPLEX and Routing values must be entered and must match the XPLEX and XROUTE ZDEFAULT parameters specified for the Physical COPE System. The Default Exit Option (accessed by scrolling forward from the above panel) should be set to 2 (Keep Command Responses).
Example of inputting IMS command and the response

Any Type 1 or Type 2 commands may be entered. An example of a Type 2 command follows :-
157
Figure 100:Example of inputting a Type 2 command File Action Manage resources SPOC View Options Help ------------------------------------------------------------------PLEX1 IMS Single Point of Control Command ===> qry pgm name(d*) lsys ivpa2 show(all) Plex . . Response for: CSLM000I (C) Copyright IBM Corp. 2000. All rights reserved. Route . . Wait . .
The response from this command follows :Figure 101:Response from Type 2 command File Action Manage resources SPOC View Options Help --------------------------------------------------------------------PLEX1 IMS Single Point of Control Command ===> No clients returned return code 0. Check return code(s). Plex . . PLEX1 Route . . Wait . . Response for: QRY PGM NAME(C0000650,C0000651,C0000654, More: +> PgmName C-num Lsys TYP CC CCText RgnType BMPType FP DOPT DBFSAMP1 (C0000650 IVPA2 AP) 0 BMP Y N N DBFSAMP2 (C0000651 IVPA2 AP) 0 BMP Y N N DBFSAMP5 (C0000654 IVPA2 AP) 0 BMP Y N N DBFSAMP6 (C0000655 IVPA2 AP) 0 BMP Y N N DFHSAM04 (C0000656 IVPA2 AP) 0 BMP Y N N DFHSAM05 (C0000657 IVPA2 AP) 0 BMP Y N N DFHSAM14 (C0000658 IVPA2 AP) 0 BMP Y N N DFHSAM15 (C0000659 IVPA2 AP) 0 BMP Y N N DFHSAM24 (C0000660 IVPA2 AP) 0 BMP Y N N DFHSAM25 (C0000661 IVPA2 AP) 0 BMP Y N N DFSIVPA (C0000662 IVPA2 AP) 0 BMP Y N N DFSIVPB (C0000663 IVPA2 AP) 0 BMP Y N N DFSIVPC (C0000664 IVPA2 AP) 0 BMP Y N N DFSIVPD (C0001167 IVPA2 PS) 10 NO RESOURCES FOUND DFSIVPE (C0001173 IVPA2 PS) 10 NO RESOURCES FOUND DFSIVPF (C0001179 IVPA2 PS) 10 NO RESOURCES FOUND
Generic (ending with a asterisk) are allowed but a complete name may also be entered. The resulting display shows the real user name as well as the COPE C-number name that IMS uses. The <LSYS cope-name> parameter limits the command to objects in the defined Logical System. If the <LSYS cope-name> parameter is omitted, all objects for all COPE logical systems are displayed. The <LSYS cope-name> parameter may be placed anywhere in the command.
Using IMS DRD (Dynamic Resource Definition)

Adding DBDs, PSBs, and transactions is prohibited using DRD commands if the COPE SPOC interface is used. The modification and deletion commands are allowed. If PSBs, DBDs or transactions are to be added to a COPE system definition, the existing process of updating the Stage 1 source via COPE Option 4.2;E;S must be used. This allows COPE to assign C-numbers for the defined objects. Generation of the Stage 1 source using option 4.2;GS will access the operational COPE system and add new objects dynamically using Type 2 commands. The Stage 1 source will also be generated in the normal manner but need not be compiled. If a generation is performed but IMS is not executing, and if the MODBLDS form of definition is not used, the generation job should be repeated when IMS is active so that definitions may be added or deleted.. .
159
160

Copepga

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Copepga

Uploaded by

Copyright:

Available Formats

COPE for IMS/DC Programmers Guide

Document: COPEPGA Modified: Wednesday, September 12, 2007 9:19 am

COPE for IMS/DC Programmers Guide

154 155 156 157 158 158

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

How COPE Works

Application Programmer Responsibilities

The COPE Parsers

How to use this Manual

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

Common COPE facilities

COPE for IMS/DC Programmers Guide

: Figure 1: Job Status Display

COPE for IMS/DC Programmers Guide

Figure 2: Data Display example

COPE for IMS/DC Programmers Guide

Figure 3: Selection Mask prompt

.. -------------------------------------- Standardware Inc. --.. --------------------------------------------------- STANDARDWARE --

COPE for IMS/DC Programmers Guide

Use of the COPE External Interface

Summary of Information required for External Interface

What happens in the External COPE Interface

Importing COPYLIB members

Preparation of the External Interface

- - - - - - - - - FOR IMPORT JOB GENERATION ONLY - - - - - - - - -

IMS SYSTEM NAME

OR PROJECT NAME ===> LEVEL NAME ===>

COPE for IMS/DC Programmers Guide

Controlling the User Jobcard

Compiling Multiple Members

COPE for IMS/DC Programmers Guide

COPE for IMS/DC Programmers Guide

Figure 5: COPE Primary menu

Copyright (c) 1989-2000 Standardware Inc.

Figure 6: COPE Browse screen

COPE for IMS/DC Programmers Guide

Figure 7: Project/Group Selection menu

PROJECT . CSD . CSD . CSD . CSD

COPE for IMS/DC Programmers Guide

Figure 8: COPE List Library display

COPE for IMS/DC Programmers Guide

Figure 9: Browse Member display

COPE for IMS/DC Programmers Guide

Figure 10: Object Data screen

CREATED SIZE MOD DATE UPDATED USER LOCK FLAG

COPE for IMS/DC Programmers Guide

ABCDF100 MFSSOURC APPMM5B 04:57 APPMM5B

COPE for IMS/DC Programmers Guide

Figure 14: COPE Import screen

Import - From Library

Importing to COPE Library: FTCOPE.COPEH.DBDSRCLB

COPE for IMS/DC Programmers Guide

Figure 15: COPE Compile Option Override screen

ROW 1 OF 2 -MORE DOWN

The field definitions are as follows: