COPE for IMS Programmers Guide

COPE for IMS/DC Programmer’s Guide

www.standardware.com Email: [email protected] Office Locations: Standardware Incorporated 23119 Bryant Avenue Purcell, OK 73080 USA Tel: 405-288-2016 Fax: 405-288-1015 Standardware Incorporated 424 Pelham Manor Road Pelham Manor, NY 10803 USA Tel: 914-738-6382 Fax: 914-738-7136 DELTA for IMS© is a trademark of the BMC Corporation. Xpeditor© is a trademark of the Compuware corporation. SmartTest© is a trademark of the ViaSoft corporation. HourGlass© is a trademark of IBM Corporation. TicToc© is a trademark of Isogon Corporation. IBM is a registered trademark of International Business Machines Incorporated. All other trademarks and service marks are the property of their respective owners. Copyright © 1989-2010, Standardware Inc. All rights reserved. This material may not be reproduced in whole or in part by any means, without written permission from Standardware Inc.

../../../../../../../../Documents%20and%20Settings/David%20Evans/Local%20Settings/Temp/www.standardware.com

iii

Table of Figures: ......................................................................................................................................... 9 Preface ...................................................................................................................................................... 13

About this Manual....................................................................................................................................................... 13 COPE for IMS/DC Programmer's Guide ................................................................................................................... 13

Related Manuals ......................................................................................................................................................... 13 COPE Family of Products General Information Manual .......................................................................................... 13

COPE for IMS/DC Administration Guide ................................................................................................................. 13

COPE for IMS/DC Distribution Tape Information .................................................................................................... 13

COPE for IMS/DC Messages Manual ....................................................................................................................... 13

COPE for IMS/DC New Features Bulletin ................................................................................................................ 14

Distribution of Manuals .............................................................................................................................................. 14 Technical support ........................................................................................................................................................ 14

Introduction .............................................................................................................................................. 15 The COPE System ......................................................................................................................................................... 15 How COPE Works ........................................................................................................................................................ 15 Application Programmer Responsibilities ................................................................................................................... 16 The COPE Parsers ........................................................................................................................................................ 16 How to use this Manual .............................................................................................................................................. 17

Common COPE facilities .......................................................................................................................... 18 Overview ..................................................................................................................................................................... 18

ISPF Edit, View, and Utility Access .......................................................................................................................... 18

Re-submitting COPE Generated Jobs ...................................................................................................................... 18

Figure 1: Job Status Display ........................................................................................................................................ 19 Error Message explanation ..................................................................................................................................... 19

Member Selection Lists and Data Display ............................................................................................................... 19

Figure 2: Data Display example .................................................................................................................................. 20 Selection mask ........................................................................................................................................................ 21

Figure 3: Selection Mask prompt ................................................................................................................................ 22 Problem Solving........................................................................................................................................................... 22

Use of the COPE External Interface ........................................................................................................ 22 Modifying Existing Procedures .................................................................................................................................... 22 What happens in the External COPE Interface ............................................................................................................ 23 Importing COPYLIB members ...................................................................................................................................... 23 Preparation of the External Interface ......................................................................................................................... 24 Figure 4: JCL Interface screen (Option 5.7) ................................................................................................................. 24 Controlling the User Jobcard ....................................................................................................................................... 25 Compiling Multiple Members ...................................................................................................................................... 25 ACBGEN ....................................................................................................................................................................... 26 PSBGEN ....................................................................................................................................................................... 26

Contents

4

ISPF Facilities ........................................................................................................................................... 26 Accessing ISPF facilities ............................................................................................................................................... 26 Figure 5: COPE Primary menu ..................................................................................................................................... 27 COPE Browse ............................................................................................................................................................... 27 Figure 6: COPE Browse screen ..................................................................................................................................... 28 Figure 7: Project/Group Selection menu ..................................................................................................................... 29 Figure 8: COPE List Library display .............................................................................................................................. 30 Figure 9: Browse Member Display .............................................................................................................................. 31 Figure 10: Object Data screen ..................................................................................................................................... 32 Figure 11: Secondary Browse Information display ...................................................................................................... 34 COPE Edit ..................................................................................................................................................................... 35 Figure 12: COPE Edit Command screen ....................................................................................................................... 35

Edit (Default option) ............................................................................................................................................... 35

Figure 13: COPE Edit Session screen ............................................................................................................................ 36 Foreground and Background Generate/Submit (Options 1-2) ............................................................................... 36

COPE Import (Option 3) .......................................................................................................................................... 37

Figure 14: COPE Import screen .................................................................................................................................... 37 Importing load modules ...................................................................................................................................... 38

Compile options (Option 4) ..................................................................................................................................... 38

Figure 15: COPE Compile Option Override screen ....................................................................................................... 39 Figure 16: Compile Option Data Entry screen ............................................................................................................. 40

Specify program i/o data and handling of unavailable DBD’s (Option 5) ............................................................... 40

Figure 17: COPE Database Not Available Specification screen ................................................................................... 41 Figure 18: COPE Database Not Available Action Propagation screen ........................................................................ 42

Table 1: Specification of Program I/O Data ............................................................................................................ 42

Figure 19: COPE Program I/O Specification Selection screen...................................................................................... 43 Cases when Program I/O Data must be Specified Manually .............................................................................. 45

Parse all unparsed members (Option 6) ................................................................................................................. 46

Edit/Browse DL/1 calls (Option 7) ........................................................................................................................... 47

Figure 20: Edit/Browse DL/1 Calls screen ................................................................................................................... 47 Jobcard parameter specification (Option J) ............................................................................................................ 48

Figure 21: COPE Jobcard screen .................................................................................................................................. 48 COPE Utilities............................................................................................................................................................... 48 Figure 22: COPE Utility Selection screen ..................................................................................................................... 49 The LIBRARY utility ...................................................................................................................................................... 49 Figure 23: Library Management Control screen ......................................................................................................... 50 The PROMOTION utility ............................................................................................................................................... 50 Figure 24: Promotion Data Specification screen ......................................................................................................... 51

Example "P" Option Display ................................................................................................................................ 52

Figure 25: The "P" Promote Option screen ................................................................................................................. 52

v

Example of the PM and PA options. ................................................................................................................... 52

Figure 26: The PM and PA Promote screen ................................................................................................................. 53 The EXPORT utility ................................................................................................................................................... 53

Figure 27: Export Option Selection screen .................................................................................................................. 54 Export commands ............................................................................................................................................... 54

Input specification ............................................................................................................................................... 55

Output specification ............................................................................................................................................ 55

The SCAN utility ....................................................................................................................................................... 55

Figure 28: Scan Utility screen ...................................................................................................................................... 56 The REPLACE utility ................................................................................................................................................. 56

Figure 29: Replace Utility screen ................................................................................................................................. 57 The COMPARE utility ............................................................................................................................................... 57

Figure 30: Lsys Sibling Relationship Example .............................................................................................................. 58 Figure 31: Compare Utility Selection menu ................................................................................................................. 59 Figure 32: Compare two Datasets menu .................................................................................................................... 60 Figure 33: External Dataset Compare menu ............................................................................................................... 61

The PDS MAINT utility ............................................................................................................................................. 61

Figure 34: PDS Maint Option menu............................................................................................................................. 62 AMBLIST and Load Module Dates ............................................................................................................................... 63 Figure 35: Load Module Specification screen .............................................................................................................. 63 Figure 36: Load Module Attribute screen.................................................................................................................... 64 IMS Online Facilities .................................................................................................................................................... 64 Figure 37: IMS Online menu ........................................................................................................................................ 65 The IMS commands facility ......................................................................................................................................... 65

Xpediter support feature ........................................................................................................................................ 65

Xpediter Setup .................................................................................................................................................... 66

Figure 38: Xpediter Primary menu .............................................................................................................................. 66 Figure 39: Xpediter Installation Options screen .......................................................................................................... 67 Figure 40: Xpediter Exit Routine screen (1) ................................................................................................................. 67 Figure 41: Xpediter Exit Routine screen (2) ................................................................................................................. 68 Figure 42: Xpediter BTS Setup screen .......................................................................................................................... 69 Figure 43: Xpediter Test Setup menu .......................................................................................................................... 69 Figure 44: Xpediter Loadlib Specification screen......................................................................................................... 70 Figure 45: Xpediter Test Setup menu .......................................................................................................................... 71 Figure 46: Xpediter BTS Setup menu ........................................................................................................................... 71 Figure 47: Xpediter BTS DL/1 Parameter List screen ................................................................................................... 72 Figure 48: Xpediter Test Setup menu .......................................................................................................................... 72 Figure 49: Xpediter IMS Setup menu ........................................................................................................................... 73 Figure 50: Xpediter PSB/DBD Libraries screen ............................................................................................................ 74

Xpediter IMS Operation ...................................................................................................................................... 74

6

Figure 51: COPE Xpediter Interface screen.................................................................................................................. 75 Figure 52: Xpediter Initial Test screen ......................................................................................................................... 76

Problems running Xpediter ................................................................................................................................. 76

Convert JCL for an Lsys ................................................................................................................................................ 78 Execution time Unconverted JCL Option ................................................................................................................ 78

Explicit JCL conversion ............................................................................................................................................ 78

Convert JCL in one step (XJCLDSN=NO) .................................................................................................................. 79

Figure 53: Convert MSG/BMP/Batch JCL screen ......................................................................................................... 79 Convert JCL in multiple steps (XJCLDSN=YES) ......................................................................................................... 81

Figure 54: Convert MSG/BMP/Batch JCL (XJCLDSN=YES) ........................................................................................... 82 Convert JCL Options ................................................................................................................................................ 82

Running Converted JCL ........................................................................................................................................... 84

Logical System Selection ......................................................................................................................................... 85

Lsys specification ................................................................................................................................................. 85

Non-COPE switch considerations ........................................................................................................................ 86

MSC considerations............................................................................................................................................. 86

Libset Terminology ...................................................................................................................................................... 86 Figure 55: Libset Relationships .................................................................................................................................... 88 Display COPE name translations ................................................................................................................................. 89 Figure 56: Translation of a non-COPE name ............................................................................................................... 90 Figure 57: Translation of a COPE name ...................................................................................................................... 91

IMS Facilities ............................................................................................................................................. 91 Overview ..................................................................................................................................................................... 91 Figure 58: COPE Online Main screen ........................................................................................................................... 92

Commands for programmers .................................................................................................................................. 93

Commands for administrators ................................................................................................................................ 94

Using the tutorial .................................................................................................................................................... 94

Logon to an Lsys .......................................................................................................................................................... 95 Figure 59: DRAW, Libset display ................................................................................................................................. 95 Figure 60: COPE Online Main screen (Not logged on) ................................................................................................. 96 Figure 61: COPE Online Main screen (after logging on) .............................................................................................. 96 Figure 62: COPE Online - LIB command screen ........................................................................................................... 97

Suspending conversational transactions ................................................................................................................ 97

IMS / Commands (with * wild characters) .................................................................................................................. 98 Display COPE Message Explanations (nnn) ................................................................................................................. 99 Display Program Load Libraries (LIB) .......................................................................................................................... 99 Logoff from COPE (not normally necessary) ............................................................................................................. 100

vii

Figure 63: COPE Online - Not Logged On screen ....................................................................................................... 101 Send a Message to a User or all Users (MSG) ........................................................................................................... 101 Database Start/Stop ................................................................................................................................................. 102 Figure 64: COPE Online - Start/Stop Selection screen (DB side) ................................................................................ 102 Figure 65: COPE Online - Start/Stop System List screen (DB side) ............................................................................ 103 Figure 66: COPE Online - Database List screen ......................................................................................................... 103 Figure 67: COPE Online - Stopped Database screen ................................................................................................. 104

Groups of databases ............................................................................................................................................. 104

Database stopped counts ..................................................................................................................................... 105

Why /DBR, etc. commands are prohibited ........................................................................................................... 105

Command line STA and STO commands ............................................................................................................... 106

Figure 68: COPE Online - Start/Stop Selection screen (TR side) ................................................................................ 106 Figure 69: COPE Online - Start/Stop System List screen (TR side) ............................................................................. 107 Figure 70: COPE Online - Transaction List screen ...................................................................................................... 107

Why /STO TRAN, etc. commands are prohibited .................................................................................................. 108

Command line transaction STA and STO commands ............................................................................................ 109

System Start/Stop ..................................................................................................................................................... 109 Figure 71: COPE Online - System Start/Stop screen (DB side) ................................................................................... 110

Command line system STA and STO commands ................................................................................................... 111

TRACE ........................................................................................................................................................................ 111 Turning DLI and SQL call trace on ......................................................................................................................... 111

Figure 72: COPE Online - Turning Trace On ............................................................................................................... 112 Figure 73: COPE Online - Trace Status screen ........................................................................................................... 112

Trace display for MPP programs (ISPF option 7.2) ............................................................................................... 112

Figure 74: Option 7.2 IMS Online Traces menu ......................................................................................................... 113 Figure 75: Option 7.2 Trace Search in Progress screen ............................................................................................. 114 Figure 76: Trace Records screen ................................................................................................................................ 115

What to do if you get no Trace output ................................................................................................................. 115

Details of Trace display ......................................................................................................................................... 116

Program start .................................................................................................................................................... 116

COBOL Ready Trace ........................................................................................................................................... 116

Function/PCB .................................................................................................................................................... 117

I/O Area ............................................................................................................................................................. 117

Modname .......................................................................................................................................................... 117

SSA Lines ........................................................................................................................................................... 118

8

Message ............................................................................................................................................................ 118

Logic trace ......................................................................................................................................................... 118

TRACE OFF command ............................................................................................................................................ 119

TRACE NOTRUNC command ................................................................................................................................. 119

TRACE LOGIC command ........................................................................................................................................ 119

Transaction Activity Display (ISPF 7.2.T) ................................................................................................................... 119 Figure 77: Trace Selection screen .............................................................................................................................. 120 Figure 78: Transaction Activity screen ...................................................................................................................... 121

Update bytes by DB details ................................................................................................................................... 122

Number of Get calls and number of Update calls ................................................................................................. 122

Multiple transactions in one program scheduling ................................................................................................ 122

Abend indicator ..................................................................................................................................................... 123

Abend Summary Screen ............................................................................................................................................ 123 Figure 79: Abend Description screen ......................................................................................................................... 124 Figure 80: Abend S0C7 display .................................................................................................................................. 124 Figure 81: Abend Offset display ................................................................................................................................ 125

Abend summary - Status code description ........................................................................................................... 125

Figure 82: Abend Status Code display ....................................................................................................................... 125 Abend summary - Module call trace ..................................................................................................................... 126

Figure 83: Abend Summary - Module Call Trace display........................................................................................... 126 Abend summary - Last DLI call display .................................................................................................................. 126

Figure 84: Abend Summary - Last DL/1Call display .................................................................................................. 127 Abend summary - Module offsets ........................................................................................................................ 127

Figure 85: Abend Summary - Module Offsets display ............................................................................................... 127 Abend summary - Date link-edited ....................................................................................................................... 128

Figure 86: Abend Summary - Date Link-edited display ............................................................................................. 128 Bring in new Versions of COPE tables (REFRESH) ...................................................................................................... 128 Displaying Link Date/DSN of a Program (VERSION) .................................................................................................. 129 System Commands for COPE Administrators ............................................................................................................ 129

Setup of ViaSoft Smart-Test option ....................................................................................................... 130 Smart-Test setup ................................................................................................................................................... 130

Figure 87: Viasoft - Initial screen ............................................................................................................................... 131 Figure 88: Viasoft - Setup Test Option Selection screen ............................................................................................ 132 Figure 89: Viasoft Current Environment Setup Selection screen ............................................................................... 133 Figure 90: Initial BMC Delta/IMS Selection menu ..................................................................................................... 134 Figure 91: Viasoft IMS Setup Selection menu ........................................................................................................... 135 Figure 92: Viasoft RESLIB and MODBLK Specification screen ................................................................................... 136

ix

Figure 93: Viasoft IMSID/Lsys Specification screen ................................................................................................... 137 Setup of HourGlass support .................................................................................................................. 137

Figure 94: Administration menu with Hourglass option ........................................................................................... 138 Figure 95: Virtual Date Specification screen ............................................................................................................. 139 JCL Requirements ...................................................................................................................................................... 139 HourGlass Abends ..................................................................................................................................................... 140

Use and Setup of the IBM Debug Tool under COPE and IMS for non Language Environment Programs................................................................................................................................................. 140

Debugging a MPP program ....................................................................................................................................... 140 Debugging a BMP program ...................................................................................................................................... 141

The DFSRRC00 PARM field changes ...................................................................................................................... 142

Add a COPEBSYS DD card ...................................................................................................................................... 143

Add a PARMFILE DD statement ............................................................................................................................ 143

Add additional DD statements as required ........................................................................................................... 143

Debugging a DLI or DBB program ............................................................................................................................. 143 SETUP of DEBUG TOOL for COPE ........................................................................................................ 143

Change EQAOPTS ...................................................................................................................................................... 143 Update the Global Preferences File ........................................................................................................................... 143

SPOC Feature of COPE setup and use ................................................................................................. 144 Description of the COPE SPOC Feature ..................................................................................................................... 144 Accessing the COPE SPOC Command application ..................................................................................................... 144 Figure 96: Prime ISPF COPE Panel with SPOC Feature .............................................................................................. 144 Figure 97: IMS Application Menu .............................................................................................................................. 145 Figure 98: SPOC Command Entry Panel .................................................................................................................... 146 Figure 99: Options Preferences panel ....................................................................................................................... 147 Example of inputting IMS command and the response ............................................................................................ 147 Figure 100: Example of inputting a Type 2 command .............................................................................................. 148 Figure 101: Response from Type 2 command ........................................................................................................... 148 Using IMS DRD (Dynamic Resource Definition) ......................................................................................................... 149

Table of Figures:

Figure 1: Job Status Display............................................................................................................................................. 19

Figure 2: Data Display example ....................................................................................................................................... 20

Figure 3: Selection Mask prompt .................................................................................................................................... 22

Figure 4: JCL Interface screen (Option 5.7) ..................................................................................................................... 24

Figure 5: COPE Primary menu ......................................................................................................................................... 27

Figure 6: COPE Browse screen ........................................................................................................................................ 28

Figure 7: Project/Group Selection menu ........................................................................................................................ 29

Figure 8: COPE List Library display .................................................................................................................................. 30

Figure 9: Browse Member Display .................................................................................................................................. 31

Figure 10: Object Data screen ......................................................................................................................................... 32

Figure 11: Secondary Browse Information display ......................................................................................................... 34

10

Figure 12: COPE Edit Command screen .......................................................................................................................... 35

Figure 13: COPE Edit Session screen ............................................................................................................................... 36

Figure 14: COPE Import screen ....................................................................................................................................... 37

Figure 15: COPE Compile Option Override screen .......................................................................................................... 39

Figure 16: Compile Option Data Entry screen................................................................................................................. 40

Figure 17: COPE Database Not Available Specification screen ....................................................................................... 41

Figure 18: COPE Database Not Available Action Propagation screen ............................................................................ 42

Figure 19: COPE Program I/O Specification Selection screen ......................................................................................... 43

Figure 20: Edit/Browse DL/1 Calls screen ....................................................................................................................... 47

Figure 21: COPE Jobcard screen ...................................................................................................................................... 48

Figure 22: COPE Utility Selection screen ......................................................................................................................... 49

Figure 23: Library Management Control screen ............................................................................................................. 50

Figure 24: Promotion Data Specification screen............................................................................................................. 51

Figure 25: The "P" Promote Option screen ..................................................................................................................... 52

Figure 26: The PM and PA Promote screen .................................................................................................................... 53

Figure 27: Export Option Selection screen ..................................................................................................................... 54

Figure 28: Scan Utility screen .......................................................................................................................................... 56

Figure 29: Replace Utility screen .................................................................................................................................... 57

Figure 30: Lsys Sibling Relationship Example .................................................................................................................. 58

Figure 31: Compare Utility Selection menu .................................................................................................................... 59

Figure 32: Compare two Datasets menu ........................................................................................................................ 60

Figure 33: External Dataset Compare menu ................................................................................................................... 61

Figure 34: PDS Maint Option menu ................................................................................................................................ 62

Figure 35: Load Module Specification screen ................................................................................................................. 63

Figure 36: Load Module Attribute screen ....................................................................................................................... 64

Figure 37: IMS Online menu ........................................................................................................................................... 65

Figure 38: Xpediter Primary menu .................................................................................................................................. 66

Figure 39: Xpediter Installation Options screen ............................................................................................................. 67

Figure 40: Xpediter Exit Routine screen (1) .................................................................................................................... 67

Figure 41: Xpediter Exit Routine screen (2) .................................................................................................................... 68

Figure 42: Xpediter BTS Setup screen ............................................................................................................................. 69

Figure 43: Xpediter Test Setup menu ............................................................................................................................. 69

Figure 44: Xpediter Loadlib Specification screen ............................................................................................................ 70


Figure 46: Xpediter BTS Setup menu .............................................................................................................................. 71

Figure 47: Xpediter BTS DL/1 Parameter List screen ...................................................................................................... 72


Figure 49: Xpediter IMS Setup menu .............................................................................................................................. 73

Figure 50: Xpediter PSB/DBD Libraries screen ................................................................................................................ 74

Figure 51: COPE Xpediter Interface screen ..................................................................................................................... 75

Figure 52: Xpediter Initial Test screen ............................................................................................................................ 76

Figure 53: Convert MSG/BMP/Batch JCL screen............................................................................................................. 79

Figure 54: Convert MSG/BMP/Batch JCL (XJCLDSN=YES) ............................................................................................... 82

Figure 55: Libset Relationships ....................................................................................................................................... 88

xi

Figure 56: Translation of a non-COPE name ................................................................................................................... 90

Figure 57: Translation of a COPE name ........................................................................................................................... 91

Figure 58: COPE Online Main screen .............................................................................................................................. 92

Figure 59: DRAW, Libset display ..................................................................................................................................... 95

Figure 60: COPE Online Main screen (Not logged on) .................................................................................................... 96

Figure 61: COPE Online Main screen (after logging on) .................................................................................................. 96

Figure 62: COPE Online - LIB command screen ............................................................................................................... 97

Figure 63: COPE Online - Not Logged On screen .......................................................................................................... 101

Figure 64: COPE Online - Start/Stop Selection screen (DB side) ................................................................................... 102

Figure 65: COPE Online - Start/Stop System List screen (DB side) ............................................................................... 103

Figure 66: COPE Online - Database List screen ............................................................................................................. 103

Figure 67: COPE Online - Stopped Database screen ..................................................................................................... 104

Figure 68: COPE Online - Start/Stop Selection screen (TR side) ................................................................................... 106

Figure 69: COPE Online - Start/Stop System List screen (TR side) ................................................................................ 107

Figure 70: COPE Online - Transaction List screen ......................................................................................................... 107

Figure 71: COPE Online - System Start/Stop screen (DB side) ...................................................................................... 110

Figure 72: COPE Online - Turning Trace On .................................................................................................................. 112

Figure 73: COPE Online - Trace Status screen ............................................................................................................... 112

Figure 74: Option 7.2 IMS Online Traces menu ............................................................................................................ 113

Figure 75: Option 7.2 Trace Search in Progress screen ................................................................................................ 114

Figure 76: Trace Records screen ................................................................................................................................... 115

Figure 77: Trace Selection screen ................................................................................................................................. 120

Figure 78: Transaction Activity screen .......................................................................................................................... 121

Figure 79: Abend Description screen ............................................................................................................................ 124

Figure 80: Abend S0C7 display ...................................................................................................................................... 124

Figure 81: Abend Offset display .................................................................................................................................... 125

Figure 82: Abend Status Code display ........................................................................................................................... 125

Figure 83: Abend Summary - Module Call Trace display .............................................................................................. 126

Figure 84: Abend Summary - Last DL/1Call display ...................................................................................................... 127

Figure 85: Abend Summary - Module Offsets display .................................................................................................. 127

Figure 86: Abend Summary - Date Link-edited display ................................................................................................. 128

Figure 87: Viasoft - Initial screen .................................................................................................................................. 131

Figure 88: Viasoft - Setup Test Option Selection screen ............................................................................................... 132

Figure 89: Viasoft Current Environment Setup Selection screen ................................................................................. 133

Figure 90: Initial BMC Delta/IMS Selection menu......................................................................................................... 134

Figure 91: Viasoft IMS Setup Selection menu ............................................................................................................... 135

Figure 92: Viasoft RESLIB and MODBLK Specification screen ....................................................................................... 136

Figure 93: Viasoft IMSID/Lsys Specification screen ...................................................................................................... 137

Figure 94: Administration menu with Hourglass option ............................................................................................... 138

Figure 95: Virtual Date Specification screen ................................................................................................................. 139

Figure 96: Prime ISPF COPE Panel with SPOC Feature .................................................................................................. 144

Figure 97: IMS Application Menu.................................................................................................................................. 145

Figure 98: SPOC Command Entry Panel ........................................................................................................................ 146

Figure 99: Options Preferences panel ........................................................................................................................... 147

12

Figure 100: Example of inputting a Type 2 command .................................................................................................. 148

Figure 101: Response from Type 2 command .............................................................................................................. 148

List of Tables:

Table 1: Specification of Program I/O Data .................................................................................................................... 42

13

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).

COPE for IMS/DC Distribution Tape Information

Accompanies a distribution tape. It explains the contents of the tape and gives instructions for up- loading 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.

14

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:

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

15

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. The COPE ISPF Development Facility, or, 2. 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 throughthem in an orderly manner. COPE understands the source/load relationship of modules, and willpromote 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 DBD’s, Dynamic Allocation Macro specifications, IMS/VS Stage 1 source specifications and PSB’s 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 user- defined groups.

16

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").

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").

Be able to import, compile, and test programs using the COPE facilities (see "Accessing ISPFfacilities").

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").

Interface with the person administering the COPE environment to generate PSB’s, DBD’s, and ACB’s.

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 DBD’s, PSB’s, 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 DBD’s, PSB’s, 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 DBD’s, PSB’s, 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.

17

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"

"ISPF Facilities"

"IMS Facilities" If the External Interface is to be used, the following sections should be read:

"Common COPE facilities"

"Use of the COPE External Interface"

"IMS Facilities"

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 PSB’s or DBD’s, 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

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

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.

21

Many of the COPE panels display member selection lists, of which there are two types: 1. Selection for a single member 2. 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

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 con- tacting 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.

Use of the COPE External Interface

Modifying Existing Procedures

If the COPE External Interface is used, the compile procedures for PSB’s, DBD’s, and MFS must be modified by adding a step to import the source into COPE. An example of such a step follows:

23

//COPE1 EXEC COPECOPE,COPE SYSTEM //PROJECT=LSYS1,LOGICAL IMS SYSTEM //INDSN='INST.PSB’sORCE',INPUT SOURCE DATASET NAME //INMEM=PSB99,SOURCE MEMBER NAME //USER=FTIDEF1,ISPF LOGON ID FOR JOBCARD IDENTIF'N //LIBTYPE=PSB’sOURCDESTINATION 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.PSB’sORCE' 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. COPE System Name (There may be several COPE Psys's in an Installation). 2. Logical IMS system name for COPE. 3. Source dataset and member name for PSB, DBD, or MFS modules. 4. 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 PSB’s, DBD’s, 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, PSB’s, DBD’s, or MFS.

24

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)

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.

25

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 PSB’s 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 DBD’s or PSB’s). An example of the interface follows: //COPE1 EXEC COPECOPE,COPE SYSTEM //PROJECT=LSYS1,LOGICAL IMS SYSTEM //INDSN='INST.PSB’sORCE',INPUT SOURCE DATASET NAME //INMEM=PSB99,SOURCE MEMBER NAME //USER=FTIDEF1,ISPF LOGON ID FOR JOBCARD IDENTIF'N //LIBTYPE=PSB’sOURCDESTINATION 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 /*

26

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"

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=ACB’sOURCDESTINATION 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).

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 PSB’s will be generated and compiled, but online PSB’s will not. Online PSB generation may be performed using option 4.7 in the ISPF portion of COPE. It should be noted that online PSB’s should not be generated until all PSB’s of the same (external) name have been imported for all Lsys's. COPE generates maximal online PSB’s that contain PCBs from the PSB’s associated with each Lsys. Generating PSB’s before all imports are complete will produce redundant PSBGEN jobs that will be harmless, but which consume unnecessary CPU re- sources.

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:

27

Figure 5: COPE Primary menu

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:

28

Figure 6: COPE Browse screen

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:

29

Figure 7: Project/Group Selection menu

A list of valid libset "Types" may be obtained with the L command. The L command results in the following display:

30

Figure 8: COPE List Library display

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:

31

Figure 9: Browse Member Display

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:

32

Figure 10: Object Data screen

Each panel field is described below: Field Usage OBJECT NAME 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).

OBJECT TYPE 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.

CONCAT NUMB 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.

CREATED DATE The date the object was created. This field is extracted either from the PDS Directory (for PDS Objects) or from TBSTATS information (for ISPF tables).

CURRENT SIZE The current size is the number of table rows or PDS records that the ta-

33

ble or member currently contains. MOD TIME The modification time is the time at which the table or member was last

changed. PDS IND The PDS indicator field contains a Y or N depending on whether the Ob-

ject is a PDS member or a ISPF table. ALT-NAME FLG 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.

ALT NAME The "Alternate" PDS member name of the object. This name is used to

save a modified object when the "Primary Name" is locked. DELTA IND Not used in the current version of COPE DATASET NAME The name of the dataset in which the object is stored. PROMOTE TIME The time that the object was last promoted . PROMOTE DATE The date that the object was last promoted. PROMOTE USER The Userid of the user that last promoted the object. LOGGED TIME The time the object was imported LOGGED DATE The date the object was imported STATUS EXPTN 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.

CREATED SIZE The created size is the number of table rows or records when the table

or member was created. MOD DATE The date of the last modification of the object UPDATED USER The userid of the user that last changed the table or PDS member. LOCK FLAG 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.

FIRST NAME The "Actual" PDS member name of the Object. This is the name under

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

34

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

The fields on the previous screen are explained below: Field Usage LOGGED USER Userid of the user that imported the object CHANGE TIME 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.

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.

CHANGE USER 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.

35

COPE Edit

Option "2" from the primary COPE panel accesses the Edit screen shown below:

Figure 12: COPE Edit Command screen

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 using COPEUTIL.7 and the External Interface, which are described in the COPE for IMS/DC Adminis- tration Guide. In this case, importing of PSB’s, DBD’s 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:

36

Figure 13: COPE Edit Session screen

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

37

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:

Figure 14: COPE Import screen

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.

38

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 maybe specified if DBD’s, PSB’s, 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 Im- port 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 VAL- IDATE 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 Instal- lation 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

39

Name values; if you do not, selection screens will be shown. A display similar to the following will result:

Figure 15: COPE Compile Option Override screen

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:

40

Figure 16: Compile Option Data Entry screen

The field definitions are as follows: Field Usage PARAMETER Contains a short description of the parameter. The description may not be up-

dated. VALUE 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 DBD’s (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-LI- BRARY' 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.

41

Figure 17: COPE Database Not Available Specification screen

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.

42

Figure 18: COPE Database Not Available Action Propagation screen

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:

Table 1: Specification of Program I/O Data

Numb

Specification

In or Out Program

When Used

1 2 3 4 5 6 7

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/Out Out Out In In In In

Compile/Link Run Run Run Compile Run Link

43

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

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 Description 1 - SET Init. Call Issued, DB2 status. Whether a program uses DB2 or not is filled in by the COPE parser automati-

cally, 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.

44

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. 4 – LOD "Loaded", or dynamically-called program 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.

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 pre- specified, 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 Statically-called programs.

This is filled in automatically for COBOL by the COPE parser, and for Assem- bler, 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 Explanation LOOK 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 CO- BOL or Assembler parser, which extracts COPYLIB member names and

45

"Static" module names from the source. PARSE ASM Parse an Assembler program.

Typing a command of "PARSE COB" or "PARSE ASM", invokes the CO- BOL 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 MID- NAME 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. Dupli- cate 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. Dupli- cate 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. Du- plicate 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. How- ever, 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. 2. 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. 3. If your Administrator has elected to define Assembler MACLIB's in Shared Storage Datasets,

46

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 Assem- bler 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. 4. 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.

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.

47

Edit/Browse DL/1 calls (Option 7)

Figure 20: Edit/Browse DL/1 Calls screen

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)"

48

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 Utilities

The Utility selection menu is accessed via Option 3 on the Primary COPE menu. The Selection menu appears as follows:

49

Figure 22: COPE Utility Selection screen

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:

50

Figure 23: Library Management Control screen

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.

51

Figure 24: Promotion Data Specification screen

The options allowed on the Promotion panel are: Option Usage A 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

. R 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.

P 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.

. PM The PM Option displays only members that have been modified PA The PA Option displays the names of all members in a Library regardless of wheth-

er or not they have been modified.

52

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

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:

53

Figure 26: The PM and PA Promote screen

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

54

Figure 27: Export Option Selection screen

Export commands

The commands that are allowed are: Command Usage Blank Perform the Export processing. L List the Libset Types defined J Review and modify the JOB card parameters (for tape output only). E Edit and Submit the generated tape export Job. .

55

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:

56

Figure 28: Scan Utility screen

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.

57

Figure 29: Replace Utility screen

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. Appro- priate 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:

58

Figure 30: Lsys Sibling Relationship Example

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

59

Figure 31: Compare Utility Selection menu

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.

60

Figure 32: Compare two Datasets menu

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.

61

Figure 33: External Dataset Compare menu

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 re- names 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:

62

Figure 34: PDS Maint Option menu

The commands that are allowed are: Command Usage J Specify job card parameters. C(ompress) Generate JCL to compress a dataset E(xpand) Generate JCL for reallocating and copying datasets with new attributes. S 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.

63

AMBLIST and Load Module Dates

Whenever details about a load module are required, the IBM AMBLIST utility provides a decompo- sition 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

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.

64

Figure 36: Load Module Attribute screen

IMS Online Facilities

The IMS Online facilities are accessed from Option 7 on the COPE primary menu. The Selection menu appears as follows:

65

Figure 37: IMS Online menu

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)" 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.

66

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'.

Figure 38: Xpediter Primary menu

On the resulting panel, enter Option 6 as shown:

67

Figure 39: Xpediter Installation Options screen

Select Option 2 (Execution Time Exit Routines) as shown:

Figure 40: Xpediter Exit Routine screen (1)

If you have only the BTS feature of Xpediter ONLY specify the BTS exits. DO NOT specify the IMS exit.

68

Figure 41: Xpediter Exit Routine screen (2)

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.

69

Figure 42: Xpediter BTS Setup screen

The IMS RESLIB and the COPE PGMLIB must be added to the STEPLIB definitions as follows

Figure 43: Xpediter Test Setup menu

70

Figure 44: Xpediter Loadlib Specification screen

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.

71


Figure 46: Xpediter BTS Setup menu

In this example a token of 'TRAINING' identifies an Lsys. This token is placed in the position shown.

72

Figure 47: Xpediter BTS DL/1 Parameter List screen

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.


The COPE PSBLIB and DBDLIB datasets must be specified for BTS and IMS. In addition the dynamic PSBLIB dataset must be specified as shown in the following panels.

73

Figure 49: Xpediter IMS Setup menu

74

Figure 50: Xpediter PSB/DBD Libraries screen

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. Ex- ecution 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:

75

Figure 51: COPE Xpediter Interface screen

1. 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. Fill in Program (PSB) and/or Trancode(s), as in regular Xpediter. 3. 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.

76

Figure 52: Xpediter Initial Test screen

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. Check that you have all the program libraries you need in SE.1 (Loadlibs). These DO require quotes around them.

2. 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 Xpe- diter by putting EMVSP.IMSVS.PGMLIB in your SE.1 list, in this example.

77

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.

4. 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.

5. 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.

6. 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.

8. 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

User=BC0CSWE TranXtranC-Psb RCAPHDC C0008435 C0032091

Here, user BC0CSWE started their last Xpediter test at 16:33 on trancode RCAPHDC. The C- numbers 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 "Da-

78

tabase Stopped" message in COPE ISPF 2.5 (This needs a 4.7 Psbgen and 4.8 Acbgen, to take effect).

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.

2. 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.

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. In the IMSID parameter of the Job PARM statement. (the 14th parameter). 2. In the programmer's name field of the job card, (the second positional job card parameter). 3. 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

79

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. Both methods do the following:

XJCLDSN=NO Normal option. Import and re-generate occurs in one step XJCLDSN=YES 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 1. Translate PSB and DBD DD names to internal C-numbers 2. Adjust STEPLIB, IMS and IMSACB DD statements 3. 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:

Figure 53: Convert MSG/BMP/Batch JCL screen

80

To convert JCL, follow these steps: J Check job card PROJECT/GROUP The Libset identifier Enter Libset 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.

I Select I and press <Enter>. Import From dataset Specify the dataset name within quotes of the From (source) library.

Press <Enter>. Select members Use S to select from the member list. Hit <PF3> when all selections

made. Specify PROCLIB(s) Enter the PROCLIB(s) that the JCL uses (the JCL will be generated with

instream procs). Hit <PF3>. Note job number Note the job number that appears in the top right hand corner. When this

job completes, the JCL will have been converted. EG 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 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

81

again by typing the characters MD (for "Make Data") in the line command field.

ES Editing of the input to the import operation is accomplished with this op-

tion. EO 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. Import the JCL into COPE 2. Parse the imported JCL 3. Specify replacement DSNs 4. Generate the converted JCL If XJCLDSN=YES, there are additional P and D options on the option 4.9 panel:

82

Figure 54: Convert MSG/BMP/Batch JCL (XJCLDSN=YES)

Convert JCL Options

The following is an explanation of the options that are available from the option 4.9 screens: Command Explanation I 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).

P Parse JCL.

If XJCLDSN=YES all imported members must be parsed to extract the dataset names.

D 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.

83

Two columns of information are displayed: "Original dataset names" and "Re- placed 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 else- where.

G 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-

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 Ed- it. 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.

84

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. Use the JCL converter to translate input control cards, where those cards specify trancodes or

database names used in your CMD calls. 2. Change your program so that it issues AIB INQY instead of "/DIS TRAN". This call is translated

85

by COPE. 3. Change your program so that it does not issue CMD calls. If your program duplicates the func-

tion 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.

4. 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.

5. A future release of COPE will have CMD and GCMD call translation. Keep this in mind when

implementing a solution to this problem. 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. MPPs can switch transactions to BMPs, or vice versa 2. Non-COPE MPPs or BMPs can switch to COPE MPPs or BMPs, or vice versa 3. In an MSC environment, transactions can switch from one Psys to another 4. 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 TFT4 ...logs current user onto Lsys TFT4 COPE LOGON TFT4 ...same (LOGON can be omitted online) COPE LOGON TFT4 FROM USER69 ...logs USER69 onto Lsys TFT4 COPE B.TFT4 ...logs 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 UST- DLMGR; 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'

86

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.

3. 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))

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 non- COPE 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 combina- tions 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 Stan- dardware for further information in the latter case.

Libset Terminology

Libsets are a mechanism for controlling groups of datasets that contain the objects, such as PSB’s,

87

DBD’s, 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. Concate- nation 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 demon- strates some of the COPE libset capabilities and also the terms used by COPE to describe libset manipulation.

88

Figure 55: Libset Relationships

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 Meaning Entry Libset Libsets used for development. They contain modules which may be in

a state of development for uncompleted systems. Import The input of a module into a development or ENTRY level COPE libset. Export The process of removing any module from any COPE libset to another

system or dataset. Sibling Libset 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

Promotion Hierarchy The sequence of libsets that a module must pass through when it mi-

grates from development to production.

89

Parent Libset 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.

Entry Category 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. Lib- set H, however, may only receive Entry Category B. Libset F may receive the categories A, C, and D.

Logical IMS System A logical IMS COPE system may be defined wherever there is an unam-

biguous 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.

.

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. The following examples demonstrate the operation of the translate feature

90

Figure 56: Translation of a non-COPE name

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.

91

Figure 57: Translation of a COPE name

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 C- number 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.

IMS Facilities

Overview

To access the IMS facilities of COPE, you logon to IMS, then type COPE. This brings up the main COPE screen.

92

Figure 58: COPE Online Main screen

In the above example: Value Represents COPE In the top left-hand corner identifies this as the COPE screen INVDEVL 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) DFTI8L07 Your Lterm (or Signon-id, if you use the IMS /SIGN command) 15:37 The time (24 hr clock) MSGIMS1 The message region Jobname J2853 The message region Job number =====> Indicates the line where you enter commands XYZ INC Your installation's name, as known to COPE for this CPU Wed 03/21/91 The current day and date Enter a ... And the lines down to TRACE ON is text reminding you of the major commands

available AVAIL> 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 =STOP> Lists the names of the Lsys's that are Stopped (usually a person stops a system

93

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 Mes- sages 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 MY- MENU, 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-cleared- screen" support installed. Contact your COPE Administrator if you are unsure if this support is installed.

nnn Displays COPE message explanation, for message COPnnn

94

LIB Displays the program library dataset names for an Lsys MSG Sends a message to one user, or all users SS Accesses the Start/Stop Database/Transaction scrolling screens TRACE Turns DLI and SQL call traces on or off for your terminal VERSION Displays the linkedit date, and library dataset name for a program BACKUP/RESTORE Submits 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 Purpose COLDS Automatic Cold start command (also WARMS and EMERS) DEBUG Debug Cope itself IMS nn Set physical IMS system number REFRESH Bring in latest version of COPE tables SUB Submit a job from the JCL library SYNC Synchronize Start/Stop to "wake up" terminals VERSION LLE Display the Load List Elements (shows Preloaded/Loaded modules) @<storage> 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 Purpose PF1 Accesses the Tutorial PF3 Exits the Tutorial (does not go to a higher level in the panel hierarchy) PF7 Goes UP to the parent panel in the hierarchy (use this key to return after selecting a topic PF8 Goes to the NEXT panel in sequence, and is the same as pressing <Enter> PF10 Goes BACK to the previous panel that you viewed, ignoring the hierarchy

95

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:

Figure 59: DRAW, Libset display

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:

96

Figure 60: COPE Online Main screen (Not logged on)

Type INVDEVL in the "=====>" field, press <Enter>. You will see the following screen:

Figure 61: COPE Online Main screen (after logging on)

97

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

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:

98

/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

99

* 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 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).

100

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 re- solved 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

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:

101

Figure 63: COPE Online - Not Logged On screen

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. Sending messages with MSG <dest> <color> <text> 2. Deleting messages sent to you, with MSG DEL 3. Deleting messages sent from you, with MSG DEL <dest>

102

4. Deleting messages sent by others, with MSG DEL <dest> FROM <source> 5. 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)

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.

103

Figure 65: COPE Online - Start/Stop System List screen (DB side)

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:

Figure 66: COPE Online - Database List screen

104

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:

Figure 67: COPE Online - Stopped Database screen

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 com- pletely 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.

105

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" later in this section.

Database stopped counts

The STOPPED column on Start/Stop screens shows you counts of databases stopped, as a "frac- tion". For example: S/P/X DATABASE G STOPPED DESCRIPTION

ABC1G3/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 DB ...use COPE SS "P" /STO DB ...use COPE SS "P" (also takes database offline) /DBD DB ...use COPE SS "P" (does not allow read trans to run) /STA DB ...use COPE SS "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.

106

Command line STA and STO commands

You can start or stop databases from the command line of the COPE main screen by using the following commands: STA DB <name> STA DB <name> LSYS <lsys> STO DB <name> STO DB <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)

Enter TR for TRansaction, against the DB/TR, and blank out the SYSTEM name to get a scrollable list of Lsys's:

107

Figure 69: COPE Online - Start/Stop System List screen (TR side)

Select an IMS system with an X, and press <Enter>. The following screen then appears:

Figure 70: COPE Online - Transaction List screen

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

108

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 in- tervening 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 Ad- ministrator. 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." 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

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 TRAN .. use COPE SS "S" /STA PROG .. use COPE SS "S" (on the Tran) /RST .. use COPE SS "S" (no different from /STA) /STO TRAN .. use COPE SS "P" /STO PROG .. use COPE SS "P" (stops the Tran)

109

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 <tran> STA <tran> LSYS <lsys> STO <tran> STO <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.

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

110

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)

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 responds, 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 consid- eration 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

111

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 <lsys> STA DB <lsys> STO <lsys> STO 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. You can view the DLI and SQL calls your program is making using the Call Trace in ISPF option

7.2. 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. 3. You can quickly find the cause of problems using the module offsets and Last DLI call informa-

tion 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.

112

Figure 72: COPE Online - Turning 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

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:

113

Figure 74: Option 7.2 IMS Online Traces menu

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'.

114

S – summary 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.

D – details The display will show all details of PCB fields and timings. C – counts 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.

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

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 for- wards. 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:

115

Figure 76: Trace Records screen

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)

116

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: Program Start ------- Example ---------

**** 15:37 MSGIMS1 Cobol Ready Trace Function/PCB GU-- DFTI8L07 Ioarea .... CIFMNT02 Modname Modn&c.CIFGENER Ssa Ssa1&c.CACPTCFR*V Message =WARN> GE: Segment not found. Logic ==== Loading COPEd pgm C9000130.

Program start

**** 15:37 CIFMNT01 DFTI8L07 MSGIMS1 INVDEVL CIFAU101 C9000130 J2347 Cope:213mS PgmLoad:93mS ****Indicates this line is a "Program Start" line 15:37Time the program started CIFMNT01Trancode DFTI8L07User terminal (Lterm of Signon-id) MSGIMS1Message Region Jobname in which MPP ran INVDEVLLogical System name CIFAU101Real program name C9000130COPE program name J2347Job number of message region Cope:213mSTime from IMS scheduling to Cope Loading program PgmLoad:93mSTime 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

117

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... GUIMS Function (1st param) --Status Code from PCB 10 (2nd param), "--" for blank DFTI8L07Lterm name from TP PCB 0 LCIFACCUDatabase (external) name from DB PCB 0 Ioal:337I/O area length (from DIRCA), 0 if no segment transferred Pcb:1PCB number, 1 always means the I/O PCB Pgm: 18mSMilliseconds elapsed between last DLI call and this one Dli: 0mSMilliseconds elapsed in DLI call Pcbmodn:MFS MOD name from TP PCB Segname&c.CAACTSEG Segment name for DB PCB Nsens:5Number 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.

118

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 unqual- ified 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 con- sulting the relevant IMS Manual.

Logic trace

==== Loading COPEd pgm C9000130. 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.

119

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 (if TRACE is already on) COPE ON NOTRUNC (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 LOG- IC 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 Re-

120

place) 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:

Figure 77: Trace Selection screen

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:

121

Figure 78: Transaction Activity screen

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 ascend- ing 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 --------> |RESHOWPINVDEVL |<-- Logical System Update Bytes by DB ---> |R: USTDLMGR: 10K | . -> |G: 23R: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 RE- SHOW, 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. Da- tabase "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

122

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-. |RESHOWDFT18L07| |RESHOWPINVDEVL| 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.

USTDLMGR The DBD name updated is shown. Up to 4 lines of updates will be shown.

When more than 4 DBD’s are updated, like-named DBD’s will have their names combined in one line, with an asterisk (*) on the end of the name, e.g. TASATH- DB and TASATHPR would summarize as TASATH*.

10K 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.

Number of Get calls and number of Update calls

The last line in the box has call counts: 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 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. R: 1 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-.

123

First transaction |RESHOWDFTI8L07 | |RESHOWPINVDEVL | |R: USTDLMGR: 10K |<--- Update bytes 1st tran |=============1.3= |<--- Execution time 1st tran Second transaction |RESHOWT DFTI8L07| (trancode RESHOWT, |RESHOWPPRODSYS| and system PRODSYS |I: USTDLMGR: 5K |<--- Update bytes 2nd tran different from first) |G: 30IR:2 |<--- Counts include both '------------------------1.4-'<--- Execution time 2nd tran 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.

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-. |RESHOWDFTI8L07 | |RESHOWPINVDEVL | |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:

-------------- Example ------------- Abend Description U0476: 2nd parm not a PCB addr, or only 1 parm Abend Offset CIFAU154+01A8&c.S0C7! Status Code Description A1: Destination in 3rd parm has to be in Imsgen Module Call trace CIFAU101+032E: Called CIFAU154 Last DLI Call display Last DLI Call: GNP GE ISSREFDB Ioal:0 PCB:4 Module Offsets CIFAU154+05F2: Last DLI Call Date Linkedited CIFAU154 linkedited 90/06/14, dsn=

Abend summary - Abend description

124

Figure 79: Abend Description screen

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

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 2- byte field for an ADD is blanks (Hex 4040). Abend summary - Abend offset

125

Figure 81: Abend Offset display

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

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 re- ferring 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.

126

Abend summary - Module call trace

Figure 83: Abend Summary - Module Call Trace display

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.

Abend summary - Last DLI call display

127

Figure 84: Abend Summary - Last DL/1Call display

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 Sen- sitive 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

The Module Name and Module Offset are given on the front of many messages.

128

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 address- es (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

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 PSB’s 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 Switch- ing or not. Message Meaning No Tasklib Switching Programs are loaded using C-numbers. You must issue REFRESH af-

ter 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

129

the REFRESH, via a BMP step. Tasklib Switching Programs are loaded using real names. In this case, there is no import-

ing of programs, and the latest version of the program will always be picked up, so there is NO need to REFRESH after a compile.

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 rarely- used 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 Used for COLDS Automatic Cold Start command (also WARMS and EMERS) DEBUG Debug COPE itself IMS nn Set physical IMS id number REFRESH Bring in latest versions of COPE tables SUB Submit a job from JCL library SYNC Synchronize Start/Stop, to "wake up" terminals VERSION Display the version (date/time assembled) of COPE modules VERSION LLE Display Load List Elems (shows Preloaded/Loaded modules) @<storage> Display Storage by hex-address, module name, or label

130

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. A front end to the DFSRRC00 DLI access program 2. 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. Specify the correct IMS RESLIB for COPE 2. Specify the correct IMS modblks library and suffix for COPE 3. Specify the correct application load libraries 4. Specify the desired COPE Logical system in the IMSID Parm field To operate a test correctly, you should know the following: 1. The name of the IMS RESLIB for COPE (ZDEFAULT parameter XCOPEIRS) 2. The name of the IMS Modblks library 3. The Stage 1 suffix used for the ViaSoft member (ZDEFAULT parameter XVIASUFF) 4. 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>.

131

Figure 87: Viasoft - Initial screen

Select option 1 on the resulting selection panel shown in the following figure:

132

Figure 88: Viasoft - Setup Test Option Selection screen

Select the setup of the current environment as shown below:

133

Figure 89: Viasoft Current Environment Setup Selection screen

Select the 'Verify IMS/DC allocations' by entering 'V' in the panel shown below:

134

Figure 90: Initial BMC Delta/IMS Selection menu

Enter 'A' to review all IMS allocations as shown below:

135

Figure 91: Viasoft IMS Setup Selection menu

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.

136

Figure 92: Viasoft RESLIB and MODBLK Specification screen

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.

137

Figure 93: Viasoft IMSID/Lsys Specification screen

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.

Setup of HourGlass support

The COPE Year 2000 feature supports HourGlass made by IBM 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.

138

The COPE HourGlass support may be activated by specifying XHRGLASS=YES or XHRGLASS+S in the ZDEFAULT PROCS copy. The XHRGLASS=S option allows a user to specify an individual time stamp for his user ID. With this option COPE does not enforce a timestamp for a MPP or IFP executing application. COPE will enforce the COPE specified timestamp for Batch and BMP applications unless there is a HourGlass JCL override DD statement. When the XHRGLASS parameter is specified an additional selection option will appear on the administrator’s panel. Option 13 appears as follows:

Figure 94: Administration menu with Hourglass option

When Option 13 is selected the following panel is displayed:-

139

Figure 95: Virtual Date Specification screen

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 Sys- tem.

MPP JCL Requirements for XHRGLASS=YES

No additional DD card should be added to all COPE controlled message. HourGlass provides its own copy of DFSRRC00 and requires a //HGIMSMSG DD DUMMY statement to be added to the MPRs. THE HGIMS DD STATEMENT SHOULD NOT BE SPECIFIED IN THE MESSAGE REGION JCL AND THE HOURGLASS DFSRRC00 MODULE SHOULD NOT BE USED. If the Hourglass STEPLIB is defined or the HGIMSMSG DD added the COPE Y2K Feature WILL NOT WORK in the MPP environments. No additional DD statements are required for batch or BMP jobs since they will be added automatically by COPE. The Logical System must be identified in the JOB card, the COPEBSYS DD statement, or in the IMSID field as it is for all COPE jobs.

MPP JCL Requirements for XHRGLASS=S

A non HourGlass modified DFSRRC00 should be accessed via the COPESTEP DD concatenation. The HourGlass STEPLIB dataset is required and a HGIMS DD DUMMY JCL statement should be added to each message region.

140

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.

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

Debugging a MPP program

COPE contains a feature that allows a DEBUG TOOL User to have their own load library when they test an

application in a MPP. This library is concatenated in front of the default set of load libraries used in a MPP. This

isolated the modified application from other users of the system and allows different versions of the same

application program to be developed simultaneously without adverse interactions.

The DEBUG TOOL User Load library is managed with the DT command issued in the COPE screen (Enter

COPE on a blank IMS terminal screen). Multiple users may use the same dataset. A User can change the

dataset name by entering another DT<dataset-name> at any time.

There are 5 different DT commands

141

DT <dataset-name>

DT ON

DT OFF

DT

DT CLEAR

The DT <dataset-name> identified the User load library dataset. A check is made that the dataset exists and a

error message is displayed if the check fails.

The DT ON command forces the defined dataset to be concatenated in front of all other message region

‘STEPLIB’ datasets whenever a transaction is processed for the user. The user does not have to use DEBUG

TOOL for this to happen.

The DT OFF command is used to prevent the user load library to be concatenated in front of the ‘STEPLIB’

datasets.

The DT command displays whether DT is ON or OFF and also the Load Library that will be concatenated if DT

ON is specified. In case that transactions input from a client system connected to COPE need to be DEBUGed,

the User Id is different from the User Id of the developer using DEBUG TOOL.

The DT CLEAR command deletes the users dataset record.

The DT commands may be entered as follows:-

DT<dataset-name> FROM Client-Id

DT ON FROM Client-Id

DT OFF FROM Client-Id

DT FROM Client-Id

Using the 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.

142

4. Additional DD statements as needed.

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.

//BMPEXEC 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.

The DFSRRC00 PARM field changes

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.

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.

DEBUG Tool makes use of INSPLOG file and a batch COPE trace may be started with a COPETRAC DD card

e.g. //INSPLOGDD SYSOUT=*

//COPETRAC DD SYSOUT=*

143

Add a COPEBSYS DD card

Add a PARMFILE DD statement

Add additional DD statements as required

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:

//BMPEXEC PGM=DFSRRC00, // PARM='DLI,TESTDLT0,DFSSAM09,,,,,,,,,,DEBG,,,,,,,,TRMLU001' A A A A Application Program-' | | | PSB Name-------' | | IMSID---------------------- ' '---APARM

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 DISASSEMBLY ON; SET DISASSEMBLY OFF; SET AUTOMONITOR ON LOG; SET 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)

144

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

Selecting Option 9 displays the following IMS Application Menu:-

145

Figure 97: IMS Application Menu

To exit the application, press F3. Selecting option 1 displays the following Command Entry Panel :-

146

Figure 98: SPOC Command Entry Panel

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 :-

147

Figure 99: Options Preferences panel

The 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 :-

148

Figure 100: Example of inputting a Type 2 command

The response from this command follows :-

Figure 101: Response from Type 2 command

149

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 MODBLKS form of definition is not used, the generation job should be repeated when IMS is active so that definitions may be added or deleted.