COPE for IMS/DC Administration Guide

Transcription

1 COPE for IMS/DC Administration Guide 1

2 Please direct questions about COPE or comments on this document to: Compuware Customer Solutions Compuware Headquarters: 1 Campus Martius Detroit, MI USA 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 Mainware 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 , Compuware Corp. All rights reserved. This material may not be reproduced in whole or in part by any means, without written permission from Compuware Corp. COPE for IMS Administration Guide 2

3 TABLE OF CONTENTS: TABLE OF CONTENTS 3 Table of Figures 8 Preface 10 About This Manual 10 COPE for IMS/DC Administration Guide 10 Related Manuals 10 COPE Family of Products General Information Manual 10 COPE for IMS/DC Installation Guide 10 COPE for IMS/DC Distribution Tape Information 10 COPE for IMS/DC Programmer's Guide 10 COPE for IMS/DC Messages Manual 10 COPE for IMS/DC New Features Bulletin 11 Enhanced User Interface 11 Distribution of Manuals 11 Technical support 11 Introduction 12 Overview of the COPE architecture 12 COPE Administrative Tasks 15 Installation 15 Machine Resources 15 The ZDEFAULT member 16 ISPF Facilities 16 The COPE Primary Menus 16 The Primary Menu 17 The COPE Legacy Primary Menu 18 Legacy Primary Menu options: 19 Fast-path processing 19 Jobcard Specification 20 Split-screen facilities 20 Understanding Libset Concepts 21 Introduction to LIBSETS 21 Libset terminology 22 COPE Datasets 25 Libset Hierarchy Example 26 Building the Online IMS/DB/DC system 28 Step 1B Define Batch and BMP Identifying Tokens 29 Step 7 Perform ACB Generatio 29 Step 1. Define Libset configuration 29 Step 1A Define Scheme for generating Plan names and rebind DBRMs 30 Step 1B Define Batch and BMP Identifying Tokens. (Option 1.6) 31 Step 2 Define excluded Databases/Applications and Transactions (Option 1.7) 33 Step 3 Import Stage 1 Source 34 Step 4 Import Dynalloc (DFSMDA) Definitions 35 COPE for IMS Administration Guide 3

4 Step 5 Import DBD/PSB/MFS copy members 36 Step 6 Import and compile DBDs and PSBs 36 Step 7 Perform ACB Generation 36 Step 8 Generate Dynalloc (DFSMDA) 37 Step 9 Generate Stage 1 37 Step 10 Generate Stage 2 38 Step 11 Compile Stage 2 38 Step 12 Define and load Database and Transaction definitions 38 Step 13 Checkout System Definitions 38 Step 14 Define Message Region Lsys Steplibs 41 Step 15 Bring up IMS and check it out 41 Import Objects into COPE 43 Considerations for the initial import of Stage 1 specifications 43 Import ADS Statements (Option B;4.2.I;A) 44 Dataset Compare for Import 45 Compare members of COPE and/or non-cope libraries (Option B;3;7) 46 Compare PSB or DBD Source and Load (Option B;3;12) 47 Import Dynalloc, PSB's and DBD's from non-cope libraries (Option B;3;10) 49 Import DBD Exits(Option 2.3 or 5.7) 49 Import MFS considerations 50 Editing and Generating entities within COPE (Option 3) 51 Recompiling PSB s, DBD's or MFS (DBDGEN PSBGEN or MFSGEN) (Option 3.DBD/PSB/MFS) 51 Generating Dynalloc members Individually (Option 3.3) 51 Refreshing Start/Stop Application (Option 3.SS or 3.7) 51 COPE Data Transformations from COPE ISPF to IMS (Option 4) 53 IMS Data Transformations 54 Perform a Stage1 Generation and Update Executing System (Option 4.1) 54 Edit (and submit) a Stage 1 member (Option 4.1) 54 Edit (and submit) a Stage 2 member (Option 4.2) 54 Perform a Dynalloc Generation for all Databases (Option 4.3) 55 Manage a PSBGEN for all Logical Systems (Option 4;PSB) 55 Perform an ACBGEN (Option 4.5) 57 Create/Generate DBRC definitions (Optional) (Option 4.DBRC) 59 COPE to IMS Execution Environment Transformations 60 Refresh COPE Name Translation Members (COPEXRF1/2/3) (option 4.6) 60 Generate MFS Name Translation Table (COPEMFSX) (Option 4.7) 60 Recreate Dictionary of PSB Definitions (Option 4.8) 60 Recreate COPE Transaction and Database Start/Stop Definitions (Option 4.9) 60 The DBSTOP option (Option B;4;2;DBSTOP) 61 Define Lterm/Transaction Translate (Option B;4.2.TR) 65 COPE Dictionary 67 Internal COPE Dictionary Tables (Option 4.10) 67 Viewing Table Contents in Edit 69 List Excluded Databases (Option B;4.2.LDX) 71 Initial installation considerations 72 Installing the COPE DFSAOE00 exit 72 Sharing a DB2 subsystem between multiple COPE Psys's 73 COPE for IMS Administration Guide 4

5 Convert TRANSACT MODE=MULT parameters 73 Configure CICS tables and resource definitions (COPE CICS feature) 73 Copy load modules to the CICS environment if CICS feature present 73 Changing Message Region Datasets (Option 1.5) 74 Separate Region/Lsys (Option 4.2.SEPREGN) 76 Select PSB's for separate Message Region Execution 78 Define Message Region Class by Lsys 78 Java JMP and JBP Regions 79 Use the B;4;2;SEPREGN application to define the PSB as a SEPREGN type PSB 79 Add the additional PSB C-number names to the DFSJVMAP PROCLIB member 80 Do a Stage 1 generation with Option 4.1 to generate the additional SEPREGN transactions 80 Add a JMP region with the class specified in the SEPREGN application 80 The External Interface 82 Generation of External Interface JCL Procedure (Option 1.2) 83 DLI Call trace from Batch and BMP jobs 83 Accessing COPE tables from external systems 83 Batch Update for External System 84 COPECHEK program 84 XBACKGEN support 84 Install MSG Region Security Exit COPESXSX 85 Install Online Exit COPESXUX 87 Parameters at Return to COPE 88 Description of operation 88 Implementing Cleanup-Delete Freemains 89 Support of LU6 or SLUP devices 89 Versioning of Preloaded Tables 90 GETMAIN and LOAD restriction 90 Change DB2 Plan Name in Exit 91 Translate PSB/DBD names in an application program 92 Return the Logical System name to an Application Program 93 Install BMP/DL1 Security Exit COPEBMPX 93 Archive Exit 93 Logical System Selection 94 Lsys specification 94 Optional Features and Third-Party Product Support 95 COMPUWARE Xpediter Support 95 How to fix COPE Xpediter problems 99 How Xpediter works with COPE 101 The DB2 Schema Removal Feature 101 Description of Feature 102 The ISPF Foreground application 102 BATCH DBRM Processing 106 Administration of ISPF Development Environment 106 Introduction 106 COPE for IMS Administration Guide 5

6 Draw Libset Hierarchy 109 SWAP Select members from a member list (Option 4.14) 109 Define Default Compile Parameters (Option B;4.5) 110 Special Utilities 110 JCL Update of Compile Parameters (Option 5.2) 110 Table Unload Utility (Option B;5.2) 111 Table Reload Utility (Option 5.3) 112 XREF C-numbers (Option 5.4) 113 Orphan Delete (Option B;5.5) 114 Remove Orphans from System Tables Library (Option B;5.6) 115 JCL Interface for Imports and Compiles (Option B;5.7) 115 Repair COPE Index (Option B;5.8) 115 Regenerate a MFS X-Ref Table (Option B;5.9) 116 TFORMAT/PSB/DBD/ACBLIB Member Delete Utility (Option B;5.10/11/12/13) 116 Remove bad entries from PDS directory (Option B;5.14) 117 Copy DBD Exit Load Modules to COPE (Option B;5.15) 118 Dump/Restore COPE Datasets (Option B;5.16) 118 Convert MSDB Databases (Option B;5.17) 119 Perform COPE system table installation (Option B;5;99) 120 AMBLIST to get Load Module Dates 120 Remove duplicate and obsolete DBD entries (Option 4.10;12) 120 Convert external names to COPE internal names (Option B.4;9) 121 MSC considerations 123 Remote Logon Support 123 Step 1 - Definition 123 Step 2 - IMS Security 124 Step 3 - IMSGEN 124 Step 4 - REFRESH or SYNC 124 Step 5 - Verify 124 Step 6 - Customize COPEO 125 Step 7 - Check for MSNAME conflicts 128 Step 8 - Implement security 129 MSC Support limitations 130 MSC Supported Features 130 MFS Synchronization with MSC 130 Virtual Date Facility (Option 1.12) 131 DB/Lsys Synchronization Facility (Option ) 132 Introduction 132 Row commands 135 Expansion of Database Tables 136 Exiting the Edit Session and Performing Updates 136 Impact of Changes to Lsys Organization 137 Summary of Commands 137 Administration of IMS Execution Environment 137 Introduction 137 Customizing the COPE screen 138 Custom Commands 140 The IMS SUB Command 141 COPE for IMS Administration Guide 6

7 JCL Tailoring and Variable Substitution 142 Control Statements 143 )SEL and )ENDSEL statements 144 )SET statement 145 )CM statement 146 BACKUP/RESTORE Commands 146 Different Backup/Restore members for each Lsys 146 One Backup member and one Restore member, with tailoring 147 Disable BACKUP/RESTORE commands 148 BMP-initiated Command and Message capability 149 Standardized Data Entry 153 Table Edit 153 Entering Table Data 156 Member Selection Screen 156 Setup of the BMC DELTA/IMS interface 157 INDEX 159 COPE for IMS Administration Guide 7

8 Table of Figures FIGURE 1 IMS ARCHITECTURE FIGURE 2 COPE EXTENSION OF THE IMS ENVIRONMENT FIGURE 3 DATA TRANSFER FROM ISPF TO IMS FIGURE 4 COPE PRIMARY MENU FIGURE 5 COPE LEGACY PRIMARY MENU FIGURE 6 LIBSET EXAMPLE FIGURE 7 PROMOTION PATH EXAMPLE FIGURE 8 SYSTEMS WITHOUT COMMON CODE. LIBSET EXAMPLE FIGURE 9 STEPS TO GENERATE A COPE SYSTEM FIGURE 10 LOGICAL SYSTEM DEFINITION PANEL FIGURE 11 COPETOOL CONTENT FIGURE 12 SPECIFY COPE SYSTEMS FIGURE 13 LSYS IDENTIFYING TOKEN SPECIFICATION FIGURE 14 DEFINE EXCLUDED DATABASES AND APPLICATIONS FIGURE 15 THE LDX DISPLAY OF EXCLUDED DBDS FIGURE 16 COPE ISPF OPTION 2 MENU FIGURE 17 COPE ACBGEN PANEL FIGURE 18 COPE CHECK APPLICATION FIGURE 19 OVERALL CONSISTENCY CHECK REPORT FIGURE 20 INDIVIDUAL CONSISTENCY CHECK REPORT FIGURE 21 MESSAGE REGION DATASET DEFINITION FIGURE 22COMPARE EXTERNAL DATASETS AND COPY SELECTED DIFFERENCES FIGURE 23 COMPARE COPE CONTENTS WITH EXTERNAL DATASETS FIGURE 24 COMPARE PSB OR DBD SOURCE OR LOAD WITH SOURCE OR LOAD FIGURE 25 PSB/DBD COMPARE OUTPUT DETAILING DIFFERENCES FIGURE 26 COMPARE SUMMARY REPORT FIGURE 27IMPORT ALL DEFINITIONS INTO A LOGICAL SYSTEM FIGURE 28 START STOP (SS) DATA DEFINITION SELECTION MENU FIGURE 29 START STOP DATABASE DISPLAY FIGURE 30 START STOP GROUP DEFINITION EDIT SESSION FIGURE 31 DATA TRANSFORM MENU FIGURE 32 THE 4;PSB RECOMPILE OPTION MENU FIGURE 33 ALL PSB REGENERATION MENU FIGURE 34 INLIBS PSB GENERATE DISPLAY FIGURE 35 ACB GENERATION OPTION MENU FIGURE 36 THE COPE DBRC MANAGEMENT PANEL FIGURE 37DBSTOP SELECTION MENU FIGURE 38 DBSTOP LOGICAL SYSTEM STOP MENU FIGURE 39 DBSTOP GROUP MENU FIGURE 40 DBSTOP STOPALL MENU FIGURE 41 PRINTER NAME TRANSLATION MENU FIGURE 42 DICTIONARY TABLE SELECTION MENU FIGURE 43 TABLE DUMP SPECIFICATION MENU FIGURE 44 TABLE DUMP EXAMPLE FIGURE 45 DEPENDENT STEPLIB ON CLASS AND PCB FIGURE 46 STEPLIB SELECTION CRITERIA MENU FIGURE 47 STEPLIB CLASS SET DEFINITION FIGURE 48 STEPLIB SET DATASET DEFINITION FIGURE 49 SEPREGN SELECTION MENU FIGURE 50 SEPREGN PSB SELECTION MENU FIGURE 51SEPREGN MESSAGE REGION CLASS DEFINITION MENU FIGURE 52 EXTERNAL INTERFACE EXAMPLES FIGURE 53 GENERATION OF EXTERNAL INTERFACE PROCEDURE MENU FIGURE 66 XPEDITER EXIT DEFINITION FIGURE 67XPEDITOR BTS EXIT SPECIFICATION COPE for IMS Administration Guide 8

9 FIGURE 68DBRM SCHEMA REMOVAL MENU FIGURE 69 EXTRACTED SCHEMA AND TABLE NAMES FROM DBTM MODULES FIGURE 70 SCHEMA SUFFIX SPECIFICATION MENU FIGURE 71SCHEMA SUBSTITUTION PREFIX TOKEN DEFINITION MENU FIGURE 72 REVIEW DELETED/SUBSTITUTED SCHEMA FIGURE 54 LIBSET HIERARCHY DIAGRAM FIGURE 55 SWAP COMMAND EDIT SESSION EXAMPLE FIGURE 56ISPF TABLE UNLOAD MENU FIGURE 57 ISPF TABLE RELOAD UTILITY FIGURE 58 X-REFERENCE SELECTION MENU FIGURE 59 X-REFERENCE PSB MENU FIGURE 60 ORPHAN REMOVAL MENU FIGURE 61 INDEX REPAIR UTILITY FIGURE 62 PDS DIRECTORY CLEANUP MENU FIGURE 63 DBD EXIT LOAD MODULE COPY UTILITY MENU FIGURE 64 DUMP COPE DATASETS UTILITY FIGURE 65 MSDB SUPPORT FOR COPE FIGURE 73 MFS SYNCHRONIZATION MENU FIGURE 74 SYNCHRONIZATION LSYS SELECT MENU FIGURE 75 VIRTUAL TIME SPECIFICATION MENU FIGURE 76 DATABASE SYNC. MENU FIGURE 77 LSYS SYNC FACILITY EDIT SCREEN (EMPTY TABLE) FIGURE 78 DB/LSYS SYNC FACILITY POPULATE WINDOW FIGURE 79 DB/LSYS SYNC FACILITY (AFTER POPULATE) FIGURE 80 MEMBER SELECTION SCREEN FIGURE 81 SELECTION MASK DEFINITION COPE for IMS Administration Guide 9

10 Preface About This Manual COPE for IMS/DC Administration Guide Explains how to create, administer, 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). Related Manuals COPE Family of Products General Information Manual Gives an overview of the system and explains the benefits to be gained by its use. This manual is for individuals who wish to evaluate the use of COPE for IMS/DC, or other 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 Distribution Tape Information Accompanies a distribution tape. It explains the contents of the tape and gives instructions for uploading the data to your libraries. This manual should be read in conjunction with the COPE for IMS/ DC Installation Guide. This manual is for individuals who will receive and process a COPE for IMS/DC distribution tape. This person should be familiar MVS JCL. COPE for IMS/DC 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. 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. COPE for IMS Administration Guide 10

11 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, 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. Enhanced User Interface The manual describes a new, simpler, grouping of COPE tools using the ISPF interface. Tools are arranged under six categories of - Setup, Import, Change, Data Transform, Utilities, Other Distribution of Manuals Manuals can be provided on diskette or can be viewed and/or downloaded from Compuware's web site ( 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 Compuware by phone, fax, or . 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. COPE for IMS Administration Guide 11

12 Introduction Using COPE for IMS/DC an installation can operate separate and distinct versions of IMS/DC systems under one IMS control region. Without COPE, separate IMS environments are typically required for: Unit Testing System Testing Customized Versions Demonstration Systems Executing the same application for separate divisions, companies, clients, etc. Overview of the COPE architecture Figure 1 IMS Architecture Figure 1 documents the IMS architecture. Environment and application meta data is encoded in Assembler macros which are compiled and converted to load modules that are saved in datasets available to the executing control region. COPE for IMS Administration Guide 12

13 Figure 2 COPE extension of the IMS Environment COPE extents the IMS environment by adding a set of ISPF based applications between the Meta definition macros and the compilers. The definitions from an existing ( non COPE) system are copied into the COPE ISPF application which saves them in various datasets and then regenerated them with changed names. Each COPE environment has a different execution name for an object (such as a DBD) even though the object source is identical. The names that are change and made unique are DBD PSB DD DB2 PLAN The COPE ISPF applications ensure that all references to an object are correct in all generated modules. Thus a DBD is correctly referenced with the same COPE name in the Stage 1, PSB and DFSMDA definitions. The name of an execution modules generated by COPE is called a C-number (COPE number). Because the C- number is unique, operation of multiple versions of an application system in one IMS control region becomes possible. The COPE environment preparation is accomplished with multiple ISPF based applications. A COPE repository of information is maintained in ISPF tables. The IMS portion of COPE requires an extract of repository information in order to translate names and to maintain the status of databases and applications COPE for IMS Administration Guide 13

14 Figure 3 Data transfer from ISPF to IMS Meta data about the COPE environment is transferred either in the form of generated load modules or as data which is loaded into a COPE database,. Whenever a PSB is generated a module called a STUBX is generated that contains a description of the PSB and the Logical Systems it services. This is copied to COPE datasets called STUBXLIB and PGMLIB. Information for converting COPE names to installation defined names is maintained in load modules named COPEXRF1 and COPEXRF2, Dataset information for MPP STEPLIBS is maintained in a load module named COPEXRF5. Information about the installation environment is maintained in modules named COPEXRF5 and COPEPSYS. The COPE database data is used to manage the COPE SS (Start/Stop) application accessible from the COPE transaction menu under IMS. Throughout the COPE documentation, you will encounter the terms Psys or Physical system, and Lsys or Logical system. A Psys is a real, executing, IMS control region. An Lsys is a version of an application system that executes in the COPE-generated physical IMS control region. There are many Lsys's running at once in one Psys. The maximum number of Lsys's systems that can run in one Psys is 255, and a typical number for sizable systems is ten-twenty. Without COPE, each Lsys would require a separate IMS control region. COPE also supports multiple COPE Psys's. The end-user of a COPE-based IMS/DC application has the additional responsibility of "connecting" to (or "logging on" to) a COPE Lsys, but will not perceive any differences in the operation of the application, after the connection is made. If appropriate, you can log end-users on en masse to their Lsys's, in which case they need not know about the Lsys's at all. COPE for IMS Administration Guide 14

15 A COPE Administrator should be appointed to setup and monitor the system, and to coordinate projects sharing the system. COPE Administrative Tasks The major tasks that a COPE administrator must perform are as follows :- Coordinate the installation of the COPE software from the distribution tape. Define the Libset scheme. Allocate datasets to Libsets. Import existing IMS system definitions. The import process consists of specifying the location of Dynamic allocation and Stage 1 source members. Define transactions to be excluded from COPE control. Import DBD's, PSB's, MFS, and application program load modules. Use COPE to generate DBD's for the online operation of the system. Use COPE to generate PSB's. Use COPE to generate ACB's, from the DBD's and PSB's. Generate the physical IMS system (Psys) Train users and operators in database and transaction start/stop procedures. Installation The COPE for IMS/DC Installation Guide describes how to: Load the COPE software from the distribution tape. Specify COPE parameters in the ZDEFAULT member of the PROCS library. Set up ISPF logon libraries. Add a 'COPE' option to the ISPF Primary Option Menu. Initialize COPE tables. Generate the six supplied PSB's, the one supplied DBD, and the three supplied MFS formats. Machine Resources Machine resources that are needed are: DASD space for the application libraries. Enough space for all PSB and DBD source and load, must be provided. Initially, no space for application program source code or program load is required. IMS system definition source for all IMS systems to be controlled by COPE must be available. CPU and initiator resources to run the COPE definition jobs. A COPE administrator TSO Userid with a 4096K (4M) region size. COPE for IMS Administration Guide 15

16 The ZDEFAULT member You will see references to parameters in the ZDEFAULT (or EVARS) member throughout this guide. Such references always refer to the member of the PROCS distribution or user modification library having the same name as the COPE for IMS/DC system that you are in. This member specifies control parameter values that collectively define the environment of the system. For information on any ZDEFAULT parameter mentioned in this manual, refer to COPE for IMS/DC Installation Guide. If you have more than one COPE for IMS/DC physical system, you will need to be sure, whenever you enter COPE facilities, that you are referencing the correct ZDEFAULT member. ISPF Facilities Note: This guide assumes that you are using the standard PF key assignments such as <PF1> for HELP and <PF3> for END. If your PF keys are set in some other way, be sure to press the correct key when following the instructions presented. The COPE Primary Menus Many of the procedures described in this manual specify that you begin by accessing the COPE Primary Menu. The correct method of reaching this panel depends upon which COPE system you want to work with. For each COPE system, this method was established when the system was defined. Refer to the step 'Establish ISPF Access To The COPE System' in the COPE for IMS/DC Installation Guide, for details. Note: Whenever you follow a procedure that requires accessing the COPE Primary Menu, be sure you reach that menu for the correct COPE system. COPE for IMS Administration Guide 16

17 The Primary Menu The Primary Menu is as follows Figure 4 COPE Primary Menu The COPE system in which you are working under ISPF will often be referred to as the current COPE system or as the current environment. The Prime Menu has replaced a Legacy Prime Menu. Which existed in previous versions of the COPE product. The Legacy Prime Menu may be accessed by entering B on the prime menu COPE for IMS Administration Guide 17

18 The COPE Legacy Primary Menu The Legacy Primary Menu is as follows: Figure 5 COPE Legacy Primary Menu The following information is provided at the top right of the COPE Primary and Legacy Menus: Version Date Time Julian Screen z/os IMS The version, release and modification number of the COPE product you are running for the current COP The date, in Gregorian format, that the COPE Legacy Primary Menu was last displayed. The time that the COPE Legacy Primary Menu was last displayed. The date, in Julian format, that the COPE Legacy Primary Menu was last displayed The ISPF Task (Split Screen) Number The release of the operating system The release of IMS The following information is in the middle portion of the COPE Primary and Legacy Menus: Physical IMS The name of the current COPE system (and its ZDEFAULT member). The name of the PROCS distribution or user modification library containing the ZDEFAULT member for the current COPE system. Procs Dataset The maximum number of logical systems that are allowed under the licensing agreement governing use of the distribution libraries in use by the current COPE for IMS/DC system Master Lsys The Lsys that contains the Terminal and Control region definitions in its Stage 1 definition Lsys Licensed Licensed If you contact Compuware about any problem or technical concern, you will probably be asked for this information COPE for IMS Administration Guide 18

19 Legacy Primary Menu options: Option Browse Edit Utilities Purpose Allows you to list various types of COPE-managed objects, and to browse those whose type allows the browse operation. Allows you to list various types of COPE-managed objects, and to edit those whose type allows the edit operation. Provides access to a variety of utility functions. These are described under Administration of ISPF Development Environment" Administration Provides access to the vast majority of COPE for IMS/DC functions and procedures you will normally use. They are described under "Building the Online IMS/DB/DC system." Special Utilities Dictionary IMS Online (T)ranslate Exit Provides access to less frequently used functions that support administrative tasks. These functions are described under "Special Utilities" Allows you to view, and in some case alter, the internal information maintained by COPE. The Dictionary is described under "Error! Reference source not found.." Provides allows you to interact with a running COPE IMS region. Translate COPE name to real name or vice versa. See COPE for IMS/DC Programmer's Guide for further details. Exits to the COPE Legacy Primary Menu from the Legacy Primary Menu. The following extra commands that access normal ISPF functions without leaving COPE for IMS/DC are available from all COPE menus, though they are shown explicitly only on the COPE Primary and Legacy Primary Menus. Command JOB EDIT BROW VIEW UTIL Purpose Allows you to view a list of previously submitted jobs. The list is sorted so that the most recently submitted jobs appear first. You can edit, resubmit, or delete the JCL for listed jobs. Only jobs created and run with COPE activities are shown. Allows you to enter ISPF edit without leaving the COPE environment Allows you to enter ISPF view without leaving the COPE environment Allows you to enter ISPF view without leaving the COPE environment Allows you to enter ISPF utilities without leaving the COPE environment Fast-path processing Both the COPE Primary and Legacy Primary Menu are primary option menu. You may therefore use ISPF fastpath techniques to move from one function to another by prefixing your options with '=', provided you are permitted to do so by the function you are attempting to leave. For example, entering '=4' on any COPE screen, when permitted, will display the COPE Administration Menu. In addition, you may exit from the COPE environment by entering '=x' on any COPE screen, provided the current function may be interrupted. COPE for IMS Administration Guide 19

20 Jobcard Specification Entering J on the command line for any screen that generates a background job will display the Job Card Specification panel shown below: Figure 6 JOBCARD specification Menu Appropriate Job card data need only be entered once. It is saved in the ISPF profile pool and remains valid across sessions. Enter a valid job card on the indicated lines. A JCLLIB statement is required. NOTE: If you use less than the four lines available, fill in the remaining lines with slash, slash, asterisk (//*). All four lines must have an entry. Split-screen facilities A limited split-screen capability is available with COPE for IMS/DC: a second screen may be used with COPE for IMS/DC only if the same COPE system is accessed on a second screen. Except for this restriction, the splitscreen capability is fully functional. The Primary Menu Options The multiple ISPF based applications that COPE supports have been divided into the following categories 1. Setup 2. Import and Generate 3. Update/Copy/Move/Generate 4. Data Transform (IMS and COPE) 5. Utilities 6. View Trace 7. Translate Function COPE for IMS Administration Guide 20

21 8. Base Selection Menu 9. IMS Type 2 Commands (SPOC) These panels are fully described in The Enhanced User Interface Manual available in the COPE library. The Legacy Prime Menu collected applications into the following categories 1. Browse 2. Edit 3. Utilities 4. Administration 5. Special Utilities 6. Dictionary 7. IMS Online 8. COPE Wizard 9. Translate Function 10. IMS Type 2 Commands (SPOC) Most of the sub-options are available from the Primary Menu however; the Legacy Menu is maintained for compatibility with existing customers Understanding Libset Concepts Introduction to LIBSETS COPE supports multiple development environments in a single Physical System. An environment is called a Logical System or Lsys. All environments contain a set of related entities that are used together to achieve a result. Application programs must be used with specific PSB, DBD and MFS definitions. PSB definitions must match PSB COPYLIB definitions. Load modules must match source definitions etc. Each of the different entities exist in different dataset or library definitions. The set of datasets that contain related entities is called a LIBSET.(set of libraries) Developers are familiar with the concept of concatenation. Multiple datasets may be specified for a file and the system will scan all of them in sequence when looking for a specific module. COPE allows all datasets in a LIBSET to be concatenated. with similar datasets in other LIBSETS. The order that the datasets are scanned depends on the sibling relationship of the LIBSETS. When COPE logical systems are defined, a sibling relationship may be specified. If a Logical System has a sibling it is deemed to be the junior sibling and the sibling that is referenced is deemed to be the senior sibling. A junior sibling may be a senior sibling to another LIBSET. A senior sibling can have several junior siblings referencing its contents. The following example is given to aid understanding COPE for IMS Administration Guide 21

22 Figure 7 Libset Example The example COPE system has three Logical Systems A,B and C. A is a senior sibling to B and C who are junior siblings When an entity is put into A a virtual copy is made in systems B and C. UNLESS THERE IS AN EQUIVALENTLY NAMED MEMBER IN B OR C. If, for instance, a DBD in A is compiled, the virtual members are also compiled and additional members are put into the DBDLIB. If there is an equivalently named member in system C there is no virtual copy and a DBD will not be generated from the source in system A. An explicit compile will have to be performed on the member in C to transfer it to the DBDLIB. The arrangement is useful for setting up similar systems. A development environment typically has only 10 percent differences from the production environment. Instead of having a copy of all modules in every LSYS, only the differences are required to be present in a development LSYS as long as it is specified as the junior sibling to the production LSYS senior sibling Each Lsys defined is related to a Libset definition. The specification of the relationships between Libsets allows the definition of common source and load libraries shared between Lsys's. Concatenation sequences can be defined as well as 'promotion' paths for module migration. This section first describes COPE Libsets, datasets and hierarchies. There are several types of data that need to be entered to define all Libsets, and the screens for each are described. Following these are descriptions of special commands that help with the definition process. Refer to "Error! Reference source not found.," before undertaking any data entry. Libset terminology COPE for IMS Administration Guide 22

23 A Libset is a set of datasets that contain source and load modules which are related in some manner. For example, COBOL source modules, and their associated IMS PSB and DBD source members, form an application system, but the COBOL source is usually kept in a different dataset from the PSB source, which is in a different dataset from the DBD source. The three datasets form a Libset. If several versions of these associated modules are required, several sets of datasets are created. Each related set is called a Libset. Normally there are many more than three datasets in a Libset. In COPE, Libsets are uniquely identified by the first two qualifiers in the three-part library name. Thus the libraries named CSD.DEVL.COBOL CSD.DEVL.PSB CSD.DEVL.DBD would all belong to the Libset identified as the "CSD.DEVL" Libset, while the libraries named CSD.PROD.COBOL CSD.PROD.PSB CSD.PROD.DBD would all belong to the "CSD.PROD" Libset. The most common practice is to use one Libset for development, one for production, and one for each intermediate system-integration test phase. In addition, there is often a number of sub-system Libsets at the development level, which are "merged" into fewer Libsets at the production level. Thus, there is a hierarchy of Libsets, which is used for migration of applications from test to production. The term Promotion is used to denote the process of migration between Libsets. Unless special software is present, the promotion is usually done by a simple move utility and is subject to error caused by moving the wrong module, or by missing related modules such as COPYLIB members. Libsets frequently do not contain complete copies of application systems. Maintenance usually takes place on some subset of existing applications, and concatenated Libsets are used. Concatenation is defined as the specification of a sequence of Libsets to be scanned for a particular module. This technique eliminates redundant unmodified versions of modules but again introduces the possibility of errors due to the incorrect specification of a concatenated sequence, or the invalid modification of a version of a module that has been copied and changed in another Libset. The following diagram demonstrates some of the COPE Libset capabilities and also some of the terms used to describe Libset manipulation: Figure 10: Libset Relationships diagram COPE for IMS Administration Guide 23

24 Figure 8 Promotion path example Each square in the above diagram represents a Libset (a collection of libraries that has the first two name qualifiers the same). Libset 'G' represents the "production" Libset, and Libsets 'A', 'B', 'C' and 'D' represent Entry or developmentlevel Libsets. Modules flow from right to left, never vertically. Libsets along the bottom of the diagram contain baseline versions. Libsets above are "deltas" on those below, and are concatenated before those below. The following terminology is used within COPE: Term Explanation Entry Libset Import Export Libsets used for development. These contain modules in a state of development (for incomplete systems), or maintenance (for existing systems). Entry Libsets are shown on the right side of COPE Libset diagrams and do not have any rightto-left arrows pointing to them. In this example, A, B, C and D are Entry Libsets. H is probably not an Entry Libset (the diagram does not necessarily show all right-to-left arrows that could be shown). Input of a module into a development or Entry level Libset The process of copying any module from any COPE Libset to an external system or dataset. Concatenation Hierarchy The collection of Libsets at a particular level, such as the development or Entry level. Libsets A, B, C and D form a concatenation hierarchy. Libsets H and F form another COPE for IMS Administration Guide 24

25 Sibling Libset concatenation hierarchy. Modules of the same name in higher Libsets in the concatenation (for example, Libset H) override modules in lower (Libset F), from the higher Libset's point of view. From the lower Libset's point of view, modules in the higher Libset have no effect. A library 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 due to it not being immediately lower in the search hierarchy. Siblings are indicated by downward pointing arrows (V) on COPE Libset diagrams. A right-to-left arrow, such as the one between C and E, does not represent a sibling relationship. Promotion Hierarchy The sequence of Libsets a module must pass through when it migrates from development to production. In COPE Libset diagrams, promotion proceeds from right to left (never from top to bottom between sibling Libsets). Promotion is a copy operation, not a move. When a module is promoted, it is copied over the version in the higher Libset, but is not deleted from the current Libset. Parent Libset Entry Category The Libset that is "higher" in the promotion hierarchy (not in the concatenation hierarchy). It is a "closer-to-production" Libset. For example E is a parent of C. E is also a parent of D, B and A. In COPE Libset diagrams, the parent Libsets are to the left of the "child" Libsets, and promotion proceeds in a right-to-left direction, as indicated by right-to-left arrows (<). A handle that defines the Entry Libset that a module comes from. The category name is usually set to be the same as the Entry Libset name. You define for each Libset higher than Entry in the promotion hierarchy, the Entry Categories that Libset can receive. In the above example, Libset E can receive Entry categories A, B, C and D. Libset H, however, must be defined to receive only one or some of these categories. Although it is not explicitly shown on the diagram, Libset H may have been defined to receive category B. This would mean that Libset F must have been defined to receive A, B and C. Categories are a way of "merging" and then "splitting out" sub-system modules, as they are promoted. You can define receiving categories in a simple one- to-one relationship, if this is not desired. Logical IMS (Lsys) A Libset can have zero or one logical IMSs (Lsys's) defined on it. Where an Lsys is defined, the online system will access the modules in that Libset (and its concatenated Libsets) when the IMS user is connected to that Lsys. There is a separate set of databases for each Lsys. An Lsys can be defined wherever there is one Entry category defined. In the above example, Lsys's can be defined for Libsets A, B, C, D and H (assuming only a single Entry category is put in H). Lsys's cannot be defined for Libsets E, F and G, since they have been defined as having multiple entry categories. The above example shows only one Libset hierarchy. Other Libset hierarchies can be defined in a single COPE Psys, but the Libsets in different hierarchies are separate and distinct. All of the Libsets in a Psys are defined and accessed in one ISPF application. All of the Lsys's in a Psys belong to one IMS control region. Also, multiple COPE Psys's can be defined. Each Psys is accessed in a separate ISPF application (menu option), and belongs to a separate IMS control region. COPE Datasets A COPE Dataset is identified via a three-part name which has the form: COPE for IMS Administration Guide 25

26 <Project>.<Group>.<Type> For example: CSD.DEVL.COBOL As stated previously, the combination of <Project> and <Group> uniquely specifies a Libset. Other than this, there is no restriction on the naming of either the Project or the Group. Note: The term 'level' is sometimes used interchangeably with the term 'group'. Similarly, the <Type> is defined by you according to your own naming conventions. COPE uses specific types of datasets to contain certain modules. Examples are DBDSRCLB PSBSRCLB MFSSRCLN DBDCOPY PSBCOPY MFSCOPY ASM COBOL These datasets are automatically allocated when the Lsys is defined (Using Option 1.1) Libset Hierarchy Example Recall that a Libset is uniquely identified by the Project and Group in the 3-part dataset name, <Project>.<Group>.<Type>; for example the dataset CSD.DEVL.COBOL is in the Libset CSD.DEVL. When defining a Libset structure, several considerations must be addressed. The first consideration is the number of IMS systems to be combined to form a COPE Psys. The second is the amount of code that is shared between applications. For example, suppose that there are two systems that share no code or databases between the applications. For each application, at least two Libsets need to be defined (one for development and one for production). COPE for IMS Administration Guide 26

27 The following arrangement could be used: Figure 9 Systems without Common Code. Libset Example In the above example, there are two test IMS systems defined, named PAYSYS and INVSYS (COPE IMS system names can be up to 8 characters long). One system is associated with a Libset whose Project and Group name is PAY.DEVL and the other is associated with Libset INV.DEVL. Notice that the above is an example of two unconnected COPE hierarchies. Modules flow (are promoted) along the right-to-left arrows. Promotion copies modules (rather than moves them). There are no vertical arrows, and therefore no concatenations. COPE for IMS Administration Guide 27

28 Building the Online IMS/DB/DC system Before reading this section, you should be familiar with the concept of COPE Libsets. Please refer to Understanding Libset Concepts " Figure 10 Steps to generate a COPE System Most of the steps, detailed in Figure 3 have an ISPF based application that implement them. To give an idea of the magnitude of each of the steps they are detailed here with an estimate (for comparison purposes only) of the time it takes to perform them. Step ISPF Option Task Description Estimated Reference time Define Libset configuration 5 minutes Step 1. Define Libset configuration 1A NA Define Scheme for generating Plan names and rebind DBRMs 1-2 Days Step 1A Define Scheme for generating Plan names and rebind DBRMs COPE for IMS Administration Guide 28

29 1B 1.6 Define Batch and BMP identifying tokens Define excluded Databases/Applications and Transactions COPE for IMS Administration Guide minutes Step 1B Define Batch and BMP Identifying Tokens. (Option 1.6) 5-minutes Step 2 Define excluded Databases/Applications and Transactions (Option 1.7) Import Stage 1 Source 1-hour Step 3 Import Stage 1 Source Import Dynalloc (DFSMDA) Definitions 30 minutes Step 4 Import Dynalloc (DFSMDA) Definitions 5 2.(DBD/PSB/MFS)COPY Import DBD/PSB/MFS copy members 1-10 minutes Step 5 Import DBD/PSB/MFS copy members 6 2.(DBD/PSB) Import and compile DBDs and PSBs 1-4 Days Step 6 Import and compile DBDs and PSBs 7 4.ACB;PAR Perform ACB Generation 2 hours Step 7 Perform ACB Generation Generate Dynalloc (DFSMDA) 30 minutes Step 8 Generate Dynalloc (DFSMDA) Generate Stage 1 30 minutes Step 9 Generate Stage Generate Stage 2 30 minutes Step 10 Generate Stage Compile Stage 2 5 minutes Step 11 Compile Stage Define and load Database and Transaction definitions 13 B.3.11 Checkout System Definitions Define Message Region Lsys Steplibs 15 NA Bring up IMS and check it out Each process will now be described in detail Step 1. Define Libset configuration 5-60 minutes Step 12 Define and load Database and Transaction definitions 1 hour Step 13 Checkout System Definitions 10 minutes Step 14 Define Message Region Lsys Steplibs 1 hour Step 15 Bring up IMS and check it out Prerequisites Before commencing the Libset definition process, the XDSNFORM ZDEFAULT parameter should be defined to define the high level qualifiers for all of the datasets in each LIBSET. Each logical IMS system (or Lsys) is associated with a Libset definition. Libsets can be concatenated with one or more other Libsets. Thus programs, PSB's, DBD's, or MFS members stored in a Libset can be shared between several Lsys's. if the Libsets that the Lsys's are associated with, do not contain duplicate members. The Libset definition facilities are accessed via option 1.1 from the COPE ISPF Main Menu. Careful analysis of Libset requirements should be performed before any Libset definition is attempted. Libset definitions cannot be changed without exporting and re-importing all existing objects. A limited capability exists

30 to add new Libsets. The section entitled "Understanding Libset Concepts," should be read to understand Libsets and their relation to each other. The following image shows several interrelated Logical Systems being defined Figure 11 Logical System Definition Panel The display indicates that Logical Systems IVPE2 and IVPE3 are junior siblings to IVPE1. IVPE4 has no siblings. Application load libraries may be defined for each Logical System by entering an L as a row command. This is not a requirement during initial definition since Option 1.5 can allow definition at any time. On exit from the definition panel, the administrator will have to define one of the Logical Systems as the Master Logical System. This is the system that contains all the Stage 1 macro definitions. The remaining Logical Systems only save the APPLCTN, DATABASE and TRANSACT definitions for that system. When the Master Logical System has been defined, panels will be displayed that allow entry of Volume Serial Names for datasets that make up the LIBSET for the Logical System. The names of the datasets is controlled by the XDSNFORM definition in the ZDEFAULT (EVARS) environment PROCS definition. XDSNFORM allows definition of the high order part of the dataset name. The last qualifier is standard and set to names such as PSBSRCLB or DBDSRCLB. Step 1A Define Scheme for generating Plan names and rebind DBRMs In a non-cope IMS system, the plan name used, when an application program is scheduled, is either the same name as the PSB or an alternate name supplied by a RTT table. Since COPE uses a single PSB to support multiple Logical System (environments) a different mechanism must be used. COPE for IMS Administration Guide 30

31 COPE uses an Assembler exit named COPESXUX to generate a plan name on the first SQL call from an application program. The exit has access to the real (unmodified by COPE) PSB name and the Logical System name that the application program is executing in. With these tokens it can generate a unique plan name for the application. The simplest approach is to generate a plan that is the same name as the Logical System. All DBRMs for all applications in the Logical System may be bound to one or more collections that are referenced in the PLAN. If the COPESXUX exit is not used, COPE substitutes a C-number COPE name that is different for each Logical System. This C-number name can be found in Option 4;D;5. In addition, the COPESXUX exit may associate different DB2 sub-systems with different Logical Systems. This is a supported facility for IMS but application programs must be link edited with different DB2 interface modules containing unique SSID tokens that relate to a specific DB2 subsystem. If the COPESXUX module is used, all versions of application programs may contain the default language interface module and the exit will substitute different SSIDs automatically. Once the PLAN name protocol is defined, appropriate DB2 collections must be populated, and the defined plans created. Step 1B Define Batch and BMP Identifying Tokens. (Option 1.6) Whenever an IMS based batch JOB is executed, the Logical System it is to be executed in must be identified. This identification is achieved in one of three ways 1. Put Lsys identifying token in the second positional JOB card parameter 2. Put an Lsys identifying token in place of the IMSID in the PARM field of the DFSRRC00 program 3. Add a COPEBSYS DD statement where the Lsys Identifying token is a temporary dataset name. For example :- //COPEBSYS DD UNIT=SYSDA,SPACE=(TRK,1),DSN=&&Lsys-token The tokens that identify a Logical System are defined with Option 1.6. This ISPF based application puts the Lsys identifying tokens into a load module named COPEPSYS and link-edits it into the IMS RESLIB. It also transfers some COPE modules into the IMS RESLIB and re-linkedits DFSRRC00 and other utility modules into various datasets. Before the application is executed, the COPETOOL PROCS member must be reviewed to specify what utility modules are present in an installation. The member may be accessed by specifying EVARS;EDIT COPETOOL on the COPE primary ISPF menu. An example of the result follows :- COPE for IMS Administration Guide 31

32 Figure 12 COPETOOL content The load module datasets present for various utilities in an installation are identified and an alternate dataset is specified for each. The COPE Option 1.6 application generates Linkedit statements that relink edit the utility load modules and puts them in the alternate datasets. The alternate datasets are specified in the JCL whenever the utility is executed in a COPE environment. Selecting COPE ISPF Option 1.6 and then specifying G in the command field results in the following display Figure 13 Specify COPE Systems COPE for IMS Administration Guide 32

33 If a IMS RESLIB is shared between multiple COPE systems, the ZDEFAULT dataset and member name of all the systems must be specified. The dataset name and member name can be found on the primary COPE ISPF panel. Entering the END key (PFKey 3) results in the following display Figure 14 Lsys Identifying Token Specification Different tokens may be specified for the JOB Card and the PARM field IMSID. Generally identical tokens are specified. The IMSID token may be 8 characters even though the field is limited to 4 characters in normal usage. When definition is completed, the END (PFKey 3) is entered and the resulting generated job submitted after the SYSLMOD statements of the generated job should be checked to ensure the target datasets are correct. Step 2 Define excluded Databases/Applications and Transactions (Option 1.7) System orientated transactions and databases may be excluded from COPE. COPE does not change the names of the DBDs or PSBs that they reference. Option 1.7 allows definition of the Stage 1 statements that define the excluded objects. The following shows a typical edit session for a system. Manu of the items are defined automatically by COPE for its own usage COPE for IMS Administration Guide 33

34 Figure 15 Define Excluded Databases and Applications. PSBs or DBDs that are defined as being excluded may be imported into the COPE master Logical System. (The name of the master Logical system is displayed on the initial COPE ISPF panel.) There is another mechanism for excluding PSBs and their related databases. It is accessed by Option B;4;2;XPSB). This differs from the Option 1.7 application, in that the PSBs referenced must be already in the Master Lsys and all referenced DBDs are automatically excluded. This option should be used for AOI programs, or other programs, that perform functions also be excluded (automatically) from COPE control. To exclude system PSB's: Select option XPSB on the B;4.2 command line and press <Enter>. The dataset name and IMS system fields at the bottom of the screen are not relevant for the XPSB option. A list of all PSB's from all Stage 1's that were parsed will be presented. Place S characters next to the PSB's in the list that are to be excluded. Use the find command (F xxx) to position in the list, if the list is very long. Use find with "prev" (F xxx prev) to position backwards. If this is the second or successive time that you have entered the XPSB function, some of the PSB's displayed may have an S next to them indicating that they have been excluded before. If a previously excluded PSB is to be included, blank out the S. Press <PF3> to save the excluded list. Step 3 Import Stage 1 Source Prerequisite Step COPE for IMS Administration Guide 34

35 Review the section Considerations for the initial import of Stage 1 specifications before importing a Stage 1 source member COPE obtains its dictionary information concerning Databases, Transactions and PSBs from Stage 1 source macros. If an installation does not have a Stage 1 source member because DRD is used, a member may be generated by using the DRDEXTR JCL member from the COPE installation JCL library. Figure 16 COPE ISPF Option 2 Menu Before the Stage 1 is imported, a decision must be made as to whether some or all Logical Systems have identical Stage 1 definitions. If the XCMNSTG1 ZDEFAULT parameter is set to YES all Logical Systems share the same Stage 1 definition. If it is not set to yes COPE ISPF Option 1.8 must be accessed to define the set of Logical Systems that are common. The entire Stage 1 source must be imported into the master Logical System. The name of the master Lsys can be found on the COPE prime ISPF menu. It has been defined as part of the Lsys setup (Option 1.1). The Stage 1 is imported with Option 2.1 from a PDS. The menu is shown A JOB is generated that should be submitted. Step 4 Import Dynalloc (DFSMDA) Definitions Option 2.2 is used to import Dynalloc (DFSMDA) macros. Each Logical System should have a separate set of macros imported into it. The import dataset may be a Load library with compiled DFSMDA members in it. The system will generate source from them and copy the source into the Logical System definition. Some naming convention should be defined for the database datasets. The names may be entered with the 3.3 ISPF COPE option. COPE for IMS Administration Guide 35

36 Step 5 Import DBD/PSB/MFS copy members Some installations use COPY members as part of their DBD, PSB or MFS definitions. These members may be imported with Options 2./4C/5C/6C respectively. The copy members should be imported before the definitions are imported. The sibling arrangement is maintained for COPY members. A junior sibling will concatenate its COPYLIB in front of the senior sibling COPYLIB. COPY members that are identical between Logical Systems need not be imported to all of them if they exist in the Senior Logical System. Step 6 Import and compile DBDs and PSBs When an import of a DBD or PSB is made to a COPE Logical System, the source is copied to the COPE source dataset from an external dataset and the source is then regenerated for the Logical System and all Junior Logical Systems that are related to it. Thus if a Logical System has 10 junior siblings, eleven DBDs will be generated if a DBD is imported into the Senior Lsys. If a Junior Sibling contains a duplicate member, a Load module will not be generated for that system. Imports may be performed with Option 2.4/5 for DBDs and PSBs respectively. The input dataset may be a source or load type dataset. The advantage of using DBDLIB and PSBLIB datasets as the input is that the definitions match a running system. The disadvantage is that comments are not present. ALL DBDs must be imported into ALL Logical Systems before PSBs are imported. If a DBD is not present when a PSB is generated, COPE will generate a Dummy PSB to allow other Logical Systems to execute using the shared Message Region PSB definition. Installations may have 5,000 PSBs (or more) defined which results in an extended period of processing to generate them all. The treatment of MFS (Message Format Services) is a little different from that of the PSBs and DBDs. The COPE system can access a copy of the production system Format Libraries. Whenever a change is made to a format definition or a new format introduced, it has to be imported into the Logical System that uses it. If a format is not imported into a Logical System, COPE will use the production version of the format. Typically, on a new COPE installation, no formats are imported. Step 7 Perform ACB Generation Before the ACBGEN is performed, the COPEXRF1 X-reference load module must be generated. This is required for the successful translation of the PSB and DBD names from COPE assigned C-number names to user names. The X-reference module is generated by first performing a Stage 1 generation with Option 4.1 followed by Option 4.6 Refresh COPE Name Translation Members (COPEXRF1/2/3) (Option 4.6 requires a Stage 1 generation to have been performed) Option 4.ACB displays the following panel COPE for IMS Administration Guide 36

37 Figure 17 COPE ACBGEN Panel A new installation requires an ACBGEN ALL which can take a considerable amount of time. The COPE application supports this type of generation but it also supplies a quicker method that generates up to 9 jobs that can run simultaneously. An additional job is generated that is placed on the hold queue that when released combines the partial ACBGENs into the target ACBLIBs. The expedited method may be invoked by specifying PAR in the command field. The FIX option should be run after the ACBGEN is complete. This generates additional PSBs for use by the Xpeditor product. It also generates dummy ACBs and STUBX modules for missing ACBs. These allow transactions to execute and give warning messages. Step 8 Generate Dynalloc (DFSMDA) Option 4.3 generates DFSMDA definitions for all databases in all Logical Systems. In addition it generates a DYNJCL member and submits it to compile all generated definitions. Changes and generation of individual definitions can be accomplished with Option 3.3. Step 9 Generate Stage 1 Option 4.1 generates a job that when submitted generates a COPE Stage 1 definition and outputs it as a STAGE1 member in the IMSGEN dataset. A compilation is then made and the output saved as a member named STAGE2 in the IMSGEN dataset. (This dataset is accessible any time using Option 4.11). If DRD is active, Type 2 commands will be generated to update the executing system and no Stage 2 is required to be compiled. COPE for IMS Administration Guide 37

38 Step 10 Generate Stage 2 If the Stage 1 generation is successful, the Stage 2 member is automatically generated. If, however, changes are required to correct problems, the STAGE1 member may be edited and compiled by using Option 4.1E (or 4.S1E). Step 11 Compile Stage 2 This step is not required if DRD is active and the COPE SPOC feature installed. The Generated Stage2 member may be edited and submitted for compile with Option 4.2 (or 4.S2). When the Stage 2 has completed, the MODBLKS should be copied to MODBLKSA and MODBLKSB datasets. Step 12 Define and load Database and Transaction definitions The COPE IMS application allows SS to be entered on the COPE transaction menu. This results in a Key Select menu that allows definition of Database or PSB names together with a Logical System name. The following menu shows groups of databases or PSBs together with a description of them. The data for the Database and PSB definitions is stored in a COPE database. Data for populating the COPE database is generated from a COPE ISPF application..\ The database is loaded from a Job initiated from a COPE ISPF application. For a new installation, the COPE ISPF information must be generated from an application initiated from Option 4.9 Recreate COPE Transaction and Database Start/Stop Definitions. This extracts from internal COPE definitions and automatically creates groups of related databases and Batch message switch transactions.. When the SS information has been extracted and saved (by Option 4.9) modifications and additions may be made using Option 3.7 Update COPE Start/Stop Definitions and Submit Load JOB. If data modifications are required, section Error! Reference source not found.error! Reference source not found. should be referenced. Initially, PFKey 3 should be pressed and the resulting JOB submitted. The generated JOB will generate a ZDLD member in the IMSGEN dataset (accessible with Option 4.11). In a new installation the steps that update the COPE database will fail (If they are DL1) since the database has not been initialized. Option 5.7 should be used to generate a New Database Load job. When this has been executed, future executions will run correctly. Step 13 Checkout System Definitions An IMS system consists of thousands of interrelated definitions. If there are errors, they can only be discovered when a transaction or application is executed. Finding and fixing the incorrect definitions is time consuming and requires the experience of a DBA or Systems Programmer. COPE supplies an application that checks 15 different relationships and reports on any detected inconsistencies. COPE for IMS Administration Guide 38

39 The CHECK application is accessible via Option B;3;11. The following panel is displayed Figure 18 COPE Check application Option 2 generates the report. When the Report Job is completed, Option 1 views the results. An example of the result panel is shown as follows: Figure 19 Overall Consistency Check Report COPE for IMS Administration Guide 39

40 The panel shows the detected relationships. If the specifics of a Logical System report are required to be viewed JUMP should be entered in the command field and the cursor positioned on the intersection of the Logical System row and the report column. A typical report is shown here:- Figure 20 Individual Consistency Check Report JUMPE may be entered instead of JUMP. If the alternate ISPF screen is displayed in Edit member select mode and the cursor is placed on the top left character of a column, S <member-name> commands will be issued for all names in the column. This automated the tedious job of selecting multiple non-contiguous members. COPE for IMS Administration Guide 40

41 Step 14 Define Message Region Lsys Steplibs Option 1.5 results in the following display Figure 21 Message Region Dataset definition Evert Logical System may have multiple STEPLIB definitions defined for it. These are dynamically allocated whenever a transaction is executed in a message region. If the DD name is TASKLIB the datasets may be thought of as Message Region STEPLIB Datasets. If the DD name is not TASKLIB, COPE assigns the dataset to a file of that name whenever it is opened in the Message Region. This facility can be useful for supporting architectures that use data files in message regions and access them from on-line transactions. When the definition application is exited, an option panel is displayed that allows TASKLIBS to be defined based on Transaction Class of PSB name. This is useful if multiple versions of Language environment exist in the same COPE environment as well as if IFP applications are present that use different common modules. Press PFKey 3 (END key) until a JOB JCL is displayed. This JOB should be submitted to generate the COPEXRF4 load module that contains the dataset definitions. Step 15 Bring up IMS and check it out The following example members are provided in.jcl, to help you setup the online IMS system: COPECTL Control region COPEDLS DLS region COPEDBRC DBRC region COPEMSG1 Message region COPEMSG2 Message region COPE for IMS Administration Guide 41

42 DF SVSM00 VSAM/OSAM buffer pools member Note: IOBF=(22K,16,N,Y) for OSAM USTDLMGR with block size The following considerations should be reviewed 1. COPE needs to run LSO=S. This control region parameter causes the DLS (DLI Separate address space) region to run. COPE needs LSO=S so that the PSB and DBD pools can be large, without impacting CSA. You must specify the PSB pool and DMB pool to be your current size times the number of Lsys's. Typical values are 1.5M each, for large systems. As with a non-cope system, you want your DMB pool to be large enough to hold all of your DBD's, and your PSB pool to hold at least one PSB per message region. COPE PSB's are large. This PSB pool size refers to the DLIPSB JCL parameter. The CSAPSB parameter should be about 10% (one tenth) of DLIPSB. 2. COPE needs "online change" ACBLIBA/B, MODBLKSA/B. MATRIXA/B. This is so that you can easily do ACBGENs, and MODBLKS IMSGENs. The ACBLIBs you specify in the control region JCL must match exactly those you specify in the DLS region JCL. 3. All libraries on the control region STEPLIB, DFSESL, MODBLKSA/B and MATRIXA/B DDs must be authorized. 4. A COPEPGM DD must be added to the Control Region which points to the unauthorized XCOPEPGM (STUBX library). This is used to read in translation X-ref tables, for /FOR commands and messages to MTO. It must be unauthorized. This is not a security exposure, be cause no executable code is loaded from this DD. It is just like the unauthorized ACBLIB and FORMAT libraries that you already have in your Control Region JCL. 5. The COPE message regions execute a special authorized program, COPERC00, instead of DFSRRC00. This is so that COPE can use PC/AUTH to switch the Tasklib, and to vary the DB2 plan names. The message region STEPLIB has to be an authorized library containing COPERC00 (the dynamic allocation load library, DYNLOAD, is recommended). You put libraries you would usually put on your message region STEPLIB (including RESLIB) onto a special COPESTEP DD. 6. The COPESTEP DD is not authorized. You put the XCOPEPGM library (which contains COPE's STUBXs) and the XCOPE1.LOAD library (the COPE software) on top of the COPESTEP. Next, you put libraries that are common to all Lsys's on the COPESTEP (for example, the COBOL run library, RESLIB, etc.). If you are importing programs into COPE, they will go into the XCOPEPGM library, with C-number names. If you are not importing programs, the libraries for each Lsys are not specified in the JCL; instead COPE will dynamically allocate them. This is so that they can be de-allocated without stopping and starting message regions. These Lsys libraries (which are defined in option 4.1.5) will be "concatenated" ahead of the COPESTEP libraries, so you can put common libraries on the COPESTEP, and leave these common libraries out of the option specifications. 7. The option Tasklib libraries, and the COPESTEP libraries together behave exactly like a STEPLIB in a non-cope system. The reason for this is in the architecture of MVS; a STEPLIB is in fact a Tasklib (of the topside task). COPE uses the MVS Tasklib feature in the same way as other systems, for example, ISPF and its ISPLLIB. 8. The message region DFSESL has to be authorized. 9. Check that you use the same RESLIB in all regions' JCL. Mismatched IMS system modules in different RESLIBs will cause IMS waits or loops. You must provide buffers for your databases in the Control Region //PROCLIB DFSVSMnn member. In particular, if you use OSAM USTDLMGR, with block size (as we recommend), check that you have IOBF=(22K,16,N,Y) If you don't do this, IMS will give you a DFS0730I message with code A,10, but no further explanation of what is wrong. You must COLD start, after fixing DFSVSMnn (AUTO=N, /NRE CHKPT 0). COPE for IMS Administration Guide 42

43 10. You must either specify 001 (class 1) as one of the classes on your message region parameter, or have changed the delivered COPE system transaction class, in option 5.5. To do this, go into option 5.5, change the (TP,1) parameters that you will see there, then run option 4.2.GS, then submit IMSGJCL. 11. Add a COPEMENU DD to the message region JCL pointing to your XCOPE1.MENUS library (note the S on the end). COPE will simulate ISPF panel processing for its main screen (member COPEO) and its help screens (COPETOxx). You can customize what appears on these screens in much the same way as you would customize ISPF panels (described in "Customizing the COPE screen"). It is especially useful to set up PF Keys that are meaningful for users at your installation, and this is very easy to do. 12. Add COPEJCL DD pointing to XCOPE1.JCL. This is used for submitting JCL, for SUB, BACK UP and RESTORE commands. 13. If you get "COPEMFSX missing" messages, perform option 4,7 (4.MFS). 14. If you run Fast Path Expedited Message Handling (IFP regions) you must convert the JCL for those regions by importing it into a Libset using option B;4.9, and then regenerating it. For instructions on how to do this, see "Convert external names to COPE internal names (Option B.4;9)." This conversion is required because COPE changes the PSB name to an internal C-number. The SSM member should be defined and appropriate PROCLIB definitions made. Make sure that the supplied PSB's, DBD and MFS formats are generated, as described in the COPE for IMS/DC Installation Guide. Entering COPE from a cleared screen after you are connected to the physical IMS system will bring up the main COPE screen, which lists the Lsys's that are available. You then "Connect", or "Logon", to an Lsys by typing in its name. After clearing the screen, from this point on, operation is the same as in a non- COPE system. You should view the online tutorial (by pressing <PF1> from the COPE screen) and then press <Enter>, the same way as in an ISPF tutorial. You can exercise Start/Stop Database/Transaction, which is accessed by typing SS from the COPE screen. These facilities are described in the COPE for IMS/DC Programmers Guide User applications are at this point. The Lsys identifying tokens are in the JCL and Batch jobs executed. Import Objects into COPE Import means copy modules into COPE and (optionally) compile them. Several applications that do this are explained below. Considerations for the initial import of Stage 1 specifications The initial Import of a Stage 1 definition is performed via Option 2;1. Before the operation is performed, the following considerations should be reviewed. Locate the Stage 1 input for each Lsys. The Stage 1 must be parsed into COPE from a PDS file. Usually Stage 1 is kept on a PDS, as one or more members. Some Lsys's will often need to be exact copies of other Lsys's, in which case you can use the "Common Definition" facility implemented as Option 1;8, or you can import the same definition multiple times. If you have more than one group of Lsys's that are exact copies of each other, but each group is different, you can use Common for the largest group, but you will have to import multiple times for the other groups. COPE for IMS Administration Guide 43

44 Ensure that at least one Lsys's Stage 1 contains all the IMSCTRL through IMSGEN macros, including LINE, TERMINAL, NAME, NODE, DATABASE, APPLCTN and TRANSACT macros. This is referred to as the "Lsys that contains the terminal network definition" and it must be imported into the Master Lsys that was defined via Option 1;1 when the Logical Systems were defined. The Master Lsys name can be found on the COPE Primary ISPF panel. An existing system definition can normally be used without change. You should adjust the CPLOG= on the IMSCTF upwards (for example to , or more) to take account of the increased usage of the COPE system. Other than this, all volume-related parameters are easily modified at IMS run time. SUFFIX= needs to be correct. Check that the IMSID= value matches the XIMSID parameter in the "ZDE FAULT" member. Ensure that all Stage 1's are valid assembler macro statements, without any JCL surrounding them, and without any imbedded END statements. Ensure that all Stage 1's would assemble correctly. The system macros in the Network Definition Stage 1 have to be in the correct order. In each Stage 1, no duplicate names should be present. The parser does not check the order of the macros. Errors here will only be detected when the generated Stage 1 is assembled, much later. However, the parser does check for duplicates, and will output messages in the batch import job. These messages can be reviewed by selection the COPEBATC. If the Stage 1 is kept in multiple members of a PDS, set up a new member containing just assembler "COPY " statements, one statement for each of the other members. COPE does not translate or modify in any way the terminal network macros (TYPE, LINEGRP, LINE, TERMINAL, LTERM, etc.) but these are needed by IMS for a CTLBLKS or higher gen. If you have a large terminal network (thousands of terminals), you can save considerable COPE table space and processing time using a statement. Take a set of terminal network macros and move them to some external PDS member and replace then with <member-name> statement.. When the Import job is generated, a dataset named <XPREF>.<Psys-Name>.IMSGEN will be created. Copy members to this dataset. When COPE parses the Stage 1, it will expand any COPY <member-name> statement, but it will leave alone <member-name>. When COPE generates the translated Stage1, it will to a regular COPY. When you then assemble this generated Stage1, the assembler will expand the COPY from the member in the IMSGEN dataset. In a large system, this will speed up COPE's processing can also be used to add other non-translated statements to the Stage 1. The statements could be special macros that you use to generate IMS statements, or could be DATABASE and APPLCTN statements for objects outside COPE control. Import ADS Statements (Option B;4.2.I;A) Area Datasets only apply to DEDB databases. If you do not use DEDB databases, skip the rest of this section. DS0 DS1 Data Entry Databases can have up to 7 datasets for every area. The definitions exist in three places and must all relate correctly to each other. The definitions are contained in DBD source, Dynalloc source, and DBRC source. To provide a clearer understanding, an example from the IMS install is shown below. The DEDB database has this DBD defined: DBD NAME=IVPDB3,ACCESS=DEDB,RMNAME=DBFHDC40 AREA DD1=DFSIVD3A,DEVICE=3380,SIZE=512, ROOT=(30,5),UOW=(20,5) AREA DD1=DFSIVD3B,DEVICE=3380,SIZE=512, ROOT=(30,5),UOW=(20,5) SEGM NAME=A ,PARENT=0,BYTES=(42,42) FIELD NAME=(A ,SEQ,U),BYTES=010,START=00003,TYPE=C COPE for IMS Administration Guide 44

45 DBDGEN FINISH END The Dynalloc allocation statements are as follows: DFSMDA TYPE=INITIAL DFSMDA TYPE=FPDEDB,DBNAME=IVPDB3 DFSMDA TYPE=DATASET,DISP=SHR,DDNAME=DFSIVD31, DSNAME=IMS410.DFSIVD31 DFSMDA TYPE=FPDEDB,DBNAME=IVPDB3 DFSMDA TYPE=DATASET,DISP=SHR,DDNAME=DFSIVD32, DSNAME=IMS410.DFSIVD32 DFSMDA TYPE=FPDEDB,DBNAME=IVPDB3 DFSMDA TYPE=DATASET,DISP=SHR,DDNAME=DFSIVD33, DSNAME=IMS410.DFSIVD33 DFSMDA TYPE=FPDEDB,DBNAME=IVPDB3 DFSMDA TYPE=DATASET,DISP=SHR,DDNAME=DFSIVD34, DSNAME=IMS410.DFSIVD34 DFSMDA TYPE=FINAL END The ADS statements provide the link between the information in the DBD and the Dynalloc as follows: INIT.ADS DBD(IVPDB3) AREA(DFSIVD3A)ADDN(DFSIVD31) - ADSN(IMS410.DFSIVD31) INIT.ADS DBD(IVPDB3) AREA(DFSIVD3A)ADDN(DFSIVD32) - ADSN(IMS410.DFSIVD32) INIT.ADS DBD(IVPDB3) AREA(DFSIVD3B)ADDN(DFSIVD33) - ADSN(IMS410.DFSIVD33) INIT.ADS DBD(IVPDB3) AREA(DFSIVD3B)ADDN(DFSIVD34) - ADSN(IMS410.DFSIVD34) In this example, two area datasets have been defined for the two areas defined in the DBD. The A option on the parse panel allows entry of information from existing DBRC statements. The statements can be intermixed with JCL or other DBRC statements on input. Only the INIT.ADS and CHANGE.ADS information will be extracted. If you do not use Area statements, you can omit using option A, because the DD name on the area defaults to the area name. Dataset Compare for Import When populating a COPE Logical System with DBD, PSB or MFS source, it is sometimes necessary to compare modules in different datasets and import (Copy and generate) differences into the Logical System so that its definitions match some specific version. There are 5 different utilities available to do this. 1. Compare the contents of two non-cope datasets and manually select differences to be Imported. (Option B;3;7;1) 2. Compare the definitions in a COPE Logical System with an external dataset and Import differences. (Option B;3;7;2) COPE for IMS Administration Guide 45

46 3. Compare COPE managed or non-cope managed DBD source or load modules with COPE managed or non-cope managed DBD source or load modules and generate a list of different members and the actual differences in the members (Option B;3;12;1) 4. Compare COPE managed or non-cope managed PSB source or load modules with COPE managed or non-cope managed PSB source or load modules and generate a list of different members and the actual differences in the members (Option B;3;12;2) 5. Compare COPE managed or non-cope managed PSB source or load modules with COPE managed or non-cope managed PSB source or load modules and then compare all referenced databases and generate a list of different members and the actual differences in the members (Option B;3;12;3) Utilities 1 and 2 support a simple compare utility that ignores comments and generates a job that updates the COPE definitions. It may be used for any source definitions (e.g. PSB MFS, DBDCOPY etc.) Utilities 3,4, and 5 parses the contents of PSB and DBD source or load modules and then compares each token. Account is taken of parameter defaults and the order of macro parameters is irrelevant. Source or load modules may be compared with source or load modules and the differences documented. Compare members of COPE and/or non-cope libraries (Option B;3;7) Option B;3;7;1 allows the display of the following menu to allow the compare of the contents of external datasets.. Figure 22Compare external datasets and copy selected differences The target logical system is defined and one of the datasets to be compared is specified. The second set of datasets (up to 4 concatenated) is specified on a following menu. If the compare is done in the foreground, a selection list is displayed of the differences. If the compare is done in the background, all members are automatically imported. Option B;3;7;2 allows the display of the following menu to allow the contents of a COPE Logical System to be compared with a set of external datasets.. COPE for IMS Administration Guide 46

47 Figure 23 Compare COPE contents with external datasets Up to 4 external datasets may be specified on a following menu and the actions defined in the 3 Processing Options taken. Compare PSB or DBD Source and Load (Option B;3;12) The Options support an advanced compare utility that parses the contents of source or load modules and compares the parsed results. The output is a listing of the different members and the specific differences in them. Source modules may be compared with load modules. Only PSBs and DBDs are supported. A typical specification screen is shown here. COPE for IMS Administration Guide 47

48 Figure 24 Compare PSB or DBD Source or Load with Source or Load The specification of the members to be compared may be entered on this panel. The RAW compare option is used to only compare items such as randomizers or physical block sizes. A batch job is generated and an example of the output follows. Figure 25 PSB/DBD compare output detailing differences In addition to detailed differences, a summary of the compare process is displayed at the end of the report Figure 26 Compare summary report COPE for IMS Administration Guide 48

49 Import Dynalloc, PSB's and DBD's from non-cope libraries (Option B;3;10) This facility is useful for importing to new COPE environments from existing non-cope environments because it imports Dynalloc, DBD's and PSB's as a unit. It Is a simple way to clone a non COPE system. The screen accepts an Lsys name to import to, and three library dataset names to import from. The Dynalloc library specified may be either a source or a load library; the PSB and DBD libraries must be load libraries. Figure 27Import all definitions into a Logical System The utility first displays a selection list of PSB's in the Stage 1. The Stage 1 to be used is determined by the 'Get from' option. If this is set to 'L', the Stage 1 currently defined for the Lsys will be used. If this is set to 'D', a screen will be presented for specification of an external Stage 1 member. After the selection list of PSB's is presented, one or more (or, ALL) PSB's may be selected for processing by the utility. After the PSB's have been selected, the utility analyses the selected PSB members and finds all DBD references within them. The utility also finds all extra DBD's referred to by the DBD's themselves. After the analysis phase, batch jobs are generated and submitted to import all relevant Dynalloc, DBD's and PSB's and to do the required DBDGEN, PSBGEN and ACBGEN operations. The output of the batch jobs should be examined to ensure that all processing was performed without errors. To determine and examine the jobs submitted, the JOB command may be used from the COPE main menu. Import DBD Exits(Option 2.3 or 5.7) This applies when DBD's have RMNAME=, EXTRTN= or COMPRTN= parameters in them, which specify randomizer routines, index sparseing exits, and segment compression exits, respectively. These exit routines can COPE for IMS Administration Guide 49

50 have the same name but have different code for separate Lsys's. COPE assigns a C-number to each exit in each Lsys. When the DBD is generated for operation under COPE, the exit name will be the C-number. You can either import the exit source and compile it under COPE, or you can just import the exit load module. You must import exits that are different across Lsys's. Any exits that are in the DBD's, and are not imported, must be in an authorized library on the STEPLIB of the IMS Control region and DLS region. Non-imported exits will be shared across Lsys's. COPE does not do anything with non-imported exits. For example, the randomizer DFSHDC40 can be non-imported, and should be accessible in the Control and DLS regions, just as in a non-cope system, and the COPE DBD will refer to the name DFSHDC40. Alternatively, you could import DFSHDC40 into some or all Lsys's, in which case the COPE DBD will use the C- number for each system to refer to the exit. If exits vary across Lsys's, you must import them. It may be easier to import all exits even if some are the same; there is no performance penalty for this, but it requires more importing work. If you do not import all exits, when resolving problems with exits, you will need to check whether the exit is imported or not (using COPE option 1, Browse). When importing exits that were formerly non-imported, you must DBDGEN all DBD's in the Lsys, in order to pick up the imported exit. Following this you must ACBGEN the DBD's. Consequently, when you first install COPE, it is desirable that you import DBD Exits before you import DBD's. Then you will not have to regen the DBD's. To import exits, follow this procedure: 1. Check the DBD Exit libraries have been correctly specified to COPE: "ZDEFAULT" parameter XEXITDSN must be the full dataset name of a physical load library that is authorized and on the STEPLIB of the IMS control region and the DLS region. The exits from all Libsets will be placed in this library, as well as in the Libset library. XCOPEONL.IMSLOAD is the recommended DSN. 2. If importing source, specify a destination source type of EXITSOUR (instead of, for example PSBSRCLB or DBDSRCLB) 3. If importing load, specify a destination type of IMSLOAD. Importing exits is very similar to the process for importing any other source or load module. There is no option in the Enhanced User Interface dialogue so Option B;5;7;GB may be used Import MFS considerations At execution time under IMS, COPE changes the MFS Modname in DLI calls to a C-number, using a crossreference table of Modnames within a Lsys. If a MFS member has not been imported, the name will not appear in the table, and the DLI call will remain unaltered and can be satisfied from a default format library concatenated below the format library that COPE uses. Eliminating the unnecessary importation of MFS modules will result in savings of CPU time required to parse, regenerate and recompile the formats. Some installations use COPY statements in the MFS source. If you use COPY statements, MFSCOPY should be specified with Option 2. The copy members used should be imported to the COPYLIB before the MFS source is COPE for IMS Administration Guide 50

51 imported. If you import COPYLIB members after MFS, the you will have to reparse and regenerate all members that have been imported. The members may be reimported (the easiest option) or by using Option 3;MFS and entering an E next to the affected members and making a change to a comment (or entering a garbage character anywhere), pressing the end key (PFKey 3) and then entering a G next to the member in the member list. This process will cause the MID and MODNAMES to be extracted and the X-reference table to be updated. Editing and Generating entities within COPE (Option 3) Everything that has been Imported into COPE may be reviewed, changed. and re-generated. Option 3 from the Prime Menu accesses applications to do this Recompiling PSB s, DBD's or MFS (DBDGEN PSBGEN or MFSGEN) (Option 3.DBD/PSB/MFS) Option 3 allows access to the PSB, DBD and MFS management applications. Members may be selected by entering a G next to the name of commands such as G * (to compile all members) or G A* (to compile all members beginning with A). detailed descriptions of these applications are given in the Enhanced User Interface manual. Generating Dynalloc members Individually (Option 3.3) Use option 3.3 (or 3;DYN) to modify Dynalloc (DFSMDA) definitions for a Lsys. On exit, a selection screen will be presented to allow selection of DBDs for which Dynalloc can be regenerated. If all Dynalloc (DFSMDA) generation is required, Option 4.3 (4;DY) may be selected and the resultant job submitted. This will generate multiple DYNALLOC definitions and submit the generated member DYNJCL to compile them all.. Refreshing Start/Stop Application (Option 3.SS or 3.7) The online COPE IMS environment contains a database and transaction Start/Stop application. The application is driven from data stored in the COPE control database USTDLMGR. The data may be regenerated at any time by using the 3.7 which generates JCL that refreshes the Control Database. The 4.REF option regenerates the tables that contain information extracted from the Stage 1 source as well as other COPE definitions. It allows a complete regeneration of all information defined in ISPF to be passed to the IMS environment. Jobs are automatically submitted that recompile the tables. When the jobs have ended, REFRESH may be entered on the IMS COPE terminal to accept the definitions into a running system. Under online IMS, users start and stop Lsys's, databases and transactions using COPE's Start/Stop application. This application shows scrolling lists of the databases and transactions, together with descriptions of each. You enter or change the descriptions in ISPF option 3.7. This option also allows definition of groups or transactions that can be STARTED or STOPPED with a single selection. Option 3.7 displays the following: COPE for IMS Administration Guide 51

52 Figure 28 Start Stop (SS) data definition Selection menu Options 1 and 2 are filled in automatically when the table is created automatically or with Option 4.9. Selecting option 3 shows data collected when DBDs are imported. Logical and Data Entry DBDs together with their Areas are identified below the Logical DBD column. Figure 29 Start Stop Database display The groups are defined using the Physical and Logical definitions in the DBDs. COPE for IMS Administration Guide 52

53 Groups of databases may be defined if Option 4 is selected. If a command of SPECIFYD is entered in the command field an edit session is entered that allows groups of databases to be defined. Figure 30 Start Stop Group Definition edit session, Edit commands may be used to add data under the section USE TO DEFINE NEW GROUPS. The same GROUP NAME can be entered to the databases that are required to be processed together and a GROUP DESCRIPTION can be entered to define the database description appearing next to the database or area name on the IMS SS panel. Pressing the END (PFKey 3) key will caused the specified data to be parsed and the results put into the ISPF table holding the definitions. Option 5 displays the transactions extracted from Stage 1 definitions and Option 6 allows groups of transactions together with their descriptions to be defined. The EXPND command propagates groups and descriptions over transaction codes in other Lsys's that have not been affected by a previous EXPND. In other words, if you later need to change the members of a group, or the descriptions, you must manually change all rows affected, as EXPND works one-time only, for each row. Entering CANcel on any screen flushes all changes. COPE Data Transformations from COPE ISPF to IMS (Option 4) Meta Information maintained in the ISPF portion of COPE has to be transferred to the IMS system. This is accomplished by generating and compiling source that produces load modules for cross-reference usage. Additional facilities exist for generating IMS components such as Stage 1, PSBs, and ACBs. The Option 4 panel follows COPE for IMS Administration Guide 53

54 Figure 31 Data transform Menu As may be seen, there are three categories of transformation, and one category that allows review of the Meta Data IMS Data Transformations COPE to IMS Execution Environment Transformations COPE Internal Transformations COPE Dictionary IMS Data Transformations Perform a Stage1 Generation and Update Executing System (Option 4.1) This option allows a Modblks, Ctlblks, or Nucleus generation to be performed The generated Stage 1 is saved in a dataset and compiled to produce a Stage2 member which is saved in the same dataset. If the SPOC feature is installed, a comparison is made with the executing IMS system and additions and deletions are made for databases applications and transactions. This is different from the 3.2 application which allows additions and changes to the COPE Stage 1 and allows changes to be made to existing definitions as well as additions and deletions. Edit (and submit) a Stage 1 member (Option 4.1) The generated Stage 1 may be reviewed with this option and (optionally) submitted for compile. The recompile is only required if there was some error in the 4.1 generation process. Edit (and submit) a Stage 2 member (Option 4.2) COPE for IMS Administration Guide 54

55 This is not required if the SPOC feature is installed Perform a Dynalloc Generation for all Databases (Option 4.3) If all Dynalloc (DFSMDA) generation is required, Option 4.3 (4;DY) may be selected and the resultant job submitted. This will generate multiple DYNALLOC definitions and submit the generated member DYNJCL to compile them all.. Manage a PSBGEN for all Logical Systems (Option 4;PSB) If the usage of a PSB is unclear (e.g. MPP, Batch, BMP, Added etc.), this option allows a view of it as well as providing many additional functions for recompiling PSBs. The prime panel is shown here :- Figure 32 The 4;PSB recompile option menu Whenever PSBs are imported, an option is given to specify generation. Option 3.PSB provides an application to edit, Copy and Generate PSBs that have been imported (See The Enhanced User Interface Manual for a complete description). Situations arise that require regeneration of multiple PSBs belonging to several Logical Systems. This application allows:- Regeneration of multiple PSBs (GB) Generation of PSBs that have source imported but have no matching load module in the PSBLIB (GB;NOTCOMP) Addition of Batch PSBs that have been imported and not generated (4;GB;ADDB) Generation of PSBs that have source imported but which are not present in the ACBLIB (GB;NOTINACB) Creation of a table that contains STUBX modules which do not refer to all Logical Systems (DNC) COPE for IMS Administration Guide 55

56 Regeneration of PSBs that have incomplete STUBX modules (GNC) Recreation of the dictionary table that refers to all PSBs (REMAKE) THE GB option results in the following display Figure 33 All PSB regeneration Menu Members may be selected by entering a S next to the member name. If a selected member needs to be unselected, another S may be entered to unselect it. If all selected members need to be unselected, RESET may be entered in the command field. A command of S BA* can be entered that will select all members beginning with the letters BA. PSBs that are not defined in the Stage 1 source (Batch PSBs) are only added to the table when they are compiled. If PSBs are imported and not compiled the ADDB command can be used to add them. INLIBS, NOTCOMP and NOTINACBLIB generates a display as follows COPE for IMS Administration Guide 56

57 Figure 34 INLIBS PSB Generate display The existence of a module in various datasets is displayed and automatic selection is made depending on the command issued The SEP REGN field is used to indicate those PSB's that have been defined as operating in separate message regions for each Lsys. You set PSB's to use separate regions in B;4.2.SEPREGN;1. This is only applicable if you have unusual preload requirements. Perform an ACBGEN (Option 4.5) Introduction After DBDGEN's and PSBGENs have been done, an ACBGEN must be run. Either an ACBGEN 'ALL' can be done, or individual DBD and PSB ACBGEN's. When installing COPE for the first time, you would do all DBDGEN's and option 4.7 PSBGENs, before doing an ACBGEN ALL. IMS and COPE support concatenated ACBLIBs to overcome the problem of a PSD not being able to exceed one volume. If this feature is used XCOPEACE/F/J ZDEFAULT parameters must be specified. ACBGEN can run before or after an IMSGEN. If you want the listing from ACBGEN to have translated C- numbers or if the ACBGEN is for new DBD's or PSB's, it is recommended that you perform option 4.7 Refresh COPE Name Translation Members (COPEXRF1/2/3) before the ACBGEN. If the ACBGEN is for existing DBD's or PSB's, there is no need to do this. The following menu is displayed COPE for IMS Administration Guide 57

58 Figure 35 ACB Generation Option Menu The options on the above panel are as follows: G Use this normally. It assumes that you are reasonably sure your importing of DBDGEN's and PSBGENs was complete, as no cross-checking is performed. If no name is supplied, a selection list will be displayed. J Job card set up option. An ACBGEN "ALL" may run for many hours (depends upon the size of the system). Ensure that CPU time checking is very large or turned off (TIME=1440). COPE ACBGENs run in less than one third the time of standard IMS ACBGENs, because the program COPEXLAT reads the DBDLIB and PSBLIB directories into storage. However, COPE systems are much larger than typical individual systems. CHK Performs a completeness check, comparing ACBLIB to the Stage 1. Recommended for use when first installing COPE. FIX After you have run an ACBGEN, but you either got a condition code 8 due to a small subset of missing blocks, or you got a condition code 4 and the completeness check shows some still missing, you should run FIX before bringing the online system up. FIX finds all PSB's that would come up "NOT INIT" and replaces them with a dummy PSB (in the ACBLIB only). This prevents users from hanging, if they happen on a missing PSB. Instead of hanging, the dummy PSB causes COPE to send the user a message screen, explaining that the particular PSB is not available due to it being missing, or a DBD it references being missing. This Option must be executed after an ACBGEN if the Xpeditor product is installed. PAR An ACBGEN ALL can take a long time (sometimes days). The PAR option generates up to 9 jobs that can run in parallel. An additional job is generated and placed on the hold queue to combine the parallel jobs output to the IMS ACBLIB when the other jobs are completed. The fields on the panel are as follows ACB TYPE Select PSB or DBD type of block. For DBD's, All PSB's that reference the DBD's will be regenned. For PSB with member name * (ALL) all DBD's will also be ACBGEN'ed. If a database is COPE for IMS Administration Guide 58

59 used in a large proportion of the total PSB's, it is often quicker to do a PSB "ALL", rather than do a small number of DBD's. ACB NAME Either blank for a selection list, or name for an individual ACBGEN, or asterisk (*) for a PSB "ALL" ACBGEN. Do not use an asterisk for DBD's. IMS SYSTEM This parameter is used with DBD's and can be used as a "filter" for specification of PSB's. If the field is left blank, a selection list of defined IMS systems will be displayed. If no filtering of DBD or PSB specifications is required, an asterisk (*) can be entered in the field to allow all defined PSB and DBD specifications to be shown. IMS RUNNING Normally YES, even if the online system is not running. YES copies to the inactive A/B library. You then must issue /MOD to activate the ACB's. NO uses JCL with DISP=OLD on both A and B libraries, and copies to both of them. The DISP=OLD ensures that the online is not running (the job will wait if it is running). The copying to both A and B means that when the online does come up (after the ACBGEN is finished) you do not have to remember to do the /MOD to activate the inactive A/B library. If you submit an ACBGEN with the NO option, and later try to bring up the online before the ACBGEN has finished, the online won't come up, because of the DISP=OLD. Use NO only if you are sure it fits scheduling requirements. The other useful commands are /DIS MODIFY ALL and /MOD ABORT Create/Generate DBRC definitions (Optional) (Option 4.DBRC) RECON If DBRC is to be used, the databases and groups must be defined to the DBRC RECON. This operation is automated by COPE option 4;DBRC. Figure 36 The COPE DBRC management panel You may specify statement generation for a single Lsys or for all Lsys's (by entering an asterisk (*)). COPE for IMS Administration Guide 59

60 The statement on the panel concerning the requirement for DBD generations is intended as a reminder that DBRC will not register a database until it has been compiled into the DBD library. COPE will check the DBD library and not generate statements for databases that are not in it. This allows all generated statements to execute when submitted to DBRC instead of a continual succession of flushed jobs due to a failure to find a DBD. As an aid, VSAM IDCAMS statements are generated for defining the RECONs. If the RECONs are defined already you can remove the IDCAMS statements, before submitting the job. The generated job must be submitted by using the E option and the SUB command. Option G should only be used when all DFSMDA definitions have been imported into COPE and the dataset names modified for each Logical System. The information for generating DBRC input is extracted from the COPE dictionary, and all COPE name substitutions are included The application generates RECON allocation statements and INIT RECON statements together with INIT.DBDS and INIT.DBDSGRP for all databases. The RECON allocation and INIT.RECON statements may be removed if a RECON is already present.. If new databases are added after initial installation, option U supports a RECON extract and compare application that generates update DBRC INIT.DBD, INIT.DBDS, and INIT.DBDSGRP statements. For missing definitions COPE to IMS Execution Environment Transformations Refresh COPE Name Translation Members (COPEXRF1/2/3) (option 4.6) Selection of this option will cause a Job to be generated that will extract and generate and compile the information contained in the load modules required by the COPE IMS system. After the job completes, a COPE REFRESH transaction should be entered on an IMS terminal to refresh the copies of the load modules. Generate MFS Name Translation Table (COPEMFSX) (Option 4.7) He option is only used when some problem has occurred with a MFS generation. It regenerates the MID/MOD COPE name translation table used by the DFSAOE00 exit and the COPE processes in the message regions. Recreate Dictionary of PSB Definitions (Option 4.8) This option recreates the information displayed in the 4.PSB and 4.ACB applications. It extracts data from the Lsys source datasets and the Stage 1 definitions and recreates the tables. It must be used when a new COPE system is being generated after the Stage 1 has been imported. The only other occasion is removing problems caused by failures in normal processes. Recreate COPE Transaction and Database Start/Stop Definitions (Option 4.9) The database group table used by the 3.7 Update COPE Start/Stop Definitions and Submit Load JOB application is automatically recreated when a Stage 1 is changed by adding a new database. Occasionally a COPE for IMS Administration Guide 60

61 database definition is changed without changing a Stage 1 definition. For example a DBD is changed to reference a different database as a secondary index or a logical DBD is constructed to connect existing databases. When this happens, the database group table must be recreated to allow definition of the new base groups (groups which have related databases) as well as allowing the attributes of a database to be modified if necessary. Entering Option 4.9 allows all tables to be scanned and extracted to create the database group table. If the option 4.9 operation is omitted the application running under IMS will still operate correctly, however the information accessed from the Start/Stop application will contain errors. In general the omission will not be in any way serious. The DBSTOP option (Option B;4;2;DBSTOP) Option B;4.2.DBSTOP is provided to avoid two potential problems: Repeated database allocation failures on databases that don't exist on the disk IMS system hangs while archived databases are being restored The reasons allocation failures are a problem are: When IMS cold starts, it sets all databases to a STARTED (but not allocated) status. IMS does not test to see whether the databases are on disk or not. When a transaction runs, IMS attempts allocation for all databases in the PSB. The PSB is a COPE "Combined" PSB, and therefore contains PCB's for more than one Lsys. IMS gets allocation failures on PCB's for Lsys's that don't have databases on disk. When there are many such databases, these allocation failures take a long time to process. When the next transaction runs, IMS attempts the allocation again, repeating the allocation failures. An allocation failure does not cause IMS to stop the database. databases are a severe problem because: 1. If you have set up your archive software (FDR, DMS, etc.) to automatically restore databases, then the entire IMS system will hang for several minutes, typically, waiting for the restore 2. Archive software typically defaults to automatically restore if you don't tell it otherwise, giving the hangs 3. It is likely that you will have some "spare" Lsys's that you are not using, for which you want the databases to be archived, to save disk space You might have defined many "spare" Lsys's that aren't used, and don't have databases on disk. In that case, the allocation failure processing will cause a severe slow-down in the system, and archive restores will halt the system completely. COPE provides two mechanisms to overcome allocation failures and archive problems: The AOI exit sees an allocation failure, and generates a special COPE transaction, called a DFS2503W transaction, which will stop the database (by issuing a /STO command). Unfortunately, IMS is too slow at processing these commands, so many allocation failures will still occur, before the /STO command completes. The AOI exit sees a cold start, and generates a different special COPE transaction, called a SYNC transaction, which will issue a /STO command for all databases that are "STOPPED to COPE". A database's COPE-STOPPED status is kept on USTDLMGR (the dialog manager control database), and is changed by the SS (Start/Stop) application, under online IMS. COPE for IMS Administration Guide 61

62 The SYNC transaction's processing will normally fix the problem satisfactorily. However, there is a further problem with the COPE-STOPPED status kept on USTDLMGR. When you run an option 4.2.GS (IMSGEN) and submit DLDLJCL, which reloads the STOPPED status into USTDLMGR, it loads the status that you set up in 4.2.DBSTOP. If you don't set up the right status in DBSTOP; e.g. you have an Lsys whose databases are not on disk, and you fail to tell DBSTOP that system should be STOPPED, the load job will load a STARTED COPE-status, and SYNC will leave the database STARTED, which will lead to the allocation failures slowdown problem. The default status for databases is STARTED. To avoid the problem described above, the default status may be set to STOPPED by using the DBSTOP function accessible from the option B;4.2 selection panel. From the option B;4.2 panel, DBSTOP displays the following selection menu: Figure 37DBSTOP Selection Menu Option 1 stops all databases within an Lsys, and Option 2 stops databases within a database group. If Option 1 is selected the, following panel is displayed: COPE for IMS Administration Guide 62

63 Figure 38 DBSTOP Logical System Stop Menu The columns displayed have the following meanings: LOGICAL IMS The COPE Lsys name DESCRIPTION The COPE Lsys description ALL DB STOPPED If this field is changed to a Y, all databases associated with an Lsys will be put into a stopped status after a SYNC command. If Option 2 is selected, the following panel is displayed: COPE for IMS Administration Guide 63

64 Figure 39 DBSTOP Group Menu The columns displayed have the following meanings: IMS NAME The COPE Lsys name GROUP STO PD If this field is changed to a Y, all databases associated with the group will be put into a stopped status after a SYNC command GROUP NAME The 8 character name of the group defined with DG.4 application GRP DESCRIPN The COPE Lsys description The DBD command will display all groups that contain references to a database (there may be several). The format of the DBD command is: DBD <Lsys> <Database>. The Lsys value must be a defined Lsys name and can be an asterisk (*) to indicate all Lsys's. The Database value must be a DBD name or a character string ending with an asterisk to indicate a partial name. If you do not provide the Lsys name and/or the database name, you will get a prompt box. When you press the enter key, the COPE tables are scanned and the following screen is displayed COPE for IMS Administration Guide 64

65 Figure 40 DBSTOP STOPALL Menu The commands STOPALL and STARTALL will set the status of all displayed database groups to stopped or STARTED. Define Lterm/Transaction Translate (Option B;4.2.TR) COPE intercepts ISRTs to teleprocessing (TP) PCB's, and can translate the destination from one Lterm or Transaction to another. This works for all alternate PCB's, whether modifiable (by CHNG calls) or fixeddestination, express or non-express. This facility is useful for the following purposes: Printers IMS application programs can use a set of printer Lterms that in a non-cope system are often assigned to one physical printer. Different non-cope systems use the same Lterm names, but different printers. Under COPE, you use TR to specify the translation of the Lterms in one Lsys to a "dummy" Lterm which is then assigned to the physical printer. In another Lsys, the same Lterm names can be translated to a different "dummy" Lterm which is then assigned to a different printer. BMPs The default mechanism inside COPE for distributing messages to Transaction codes that belong to message driven BMPs uses an internal "transaction switcher" MPP. The overhead of an extra transaction switch can be avoided by using the MSGDRIVE command in option TR, to automatically fill in transaction translation for these BMPs. MSC If MSC programs insert to a destination that needs to be translated, you can use TR to specify the new destination. This is a limited, though not comprehensive, support mechanism for MSC. The definition menu is shown:- COPE for IMS Administration Guide 65

66 Figure 41 Printer Name Translation Menu To implement Lterm and/or transaction code translation, do the followingenter option B;4.2.TR. Insert rows in the table (shown below) specifying Lsys name, FROM Lterm/transaction code, and TO Lterm/transaction code. The TO Lterm for printer support should be a dummy name, such as COPEnnnn, where nnnn is a number starting at Usually, COPEnnnn will be the same for all rows that have the same Lsys name. Issue the MSGDRIVE command to fill in the rows describing transaction-driven BMPs. Delete rows in which translation is not required <PF3> to save the translation table. Enter option 3.1 with the IMS System Name specified to be your single Network Defn Y Lsys. Target Logical System name set to the Master Lsys Name (this may be found on the prime COPE ISPF panel). Add NAME statements for your dummy (COPEnnnn) Lterms, under the TERMINALs for the physical printers you want each Lterm to be assigned to. <PF3> to save the changes Dummy Lterms may need to be added to your external Stage 1 definitions, if you want to avoid "dropping" them when re-parsing Stage 1. Any MSC-related translations are entered in the same way as other translations. The following is an example of the TR Table Edit panel: The fields are: IMS NAME IMS Lsys name FROM NAME The destination name specified by programs in CHNG calls, or named on the alternate PCB on the DEST= parameter. COPE for IMS Administration Guide 66

67 TO NAME The "dummy" printer Lterm name, such as "COPEnnnn", or other transaction code or Lterm name that COPE is to translate the destination to. MSG DRIVEN Is either blank or YES. This field cannot be altered. The field is inserted to indicate that the transaction specified in the FROM field is a BMP message switch transaction. The MSGDRIVE command implements an optional performance enhancement. If a transaction is not defined in the table, and if the transaction is ISRT'd by an MPP or BMP and is destined for a BMP, an intermediate "message-switcher" MPP will route the transaction to the C-number transaction code that is assigned to the BMP for the particular Lsys. This intermediate switching process can be eliminated by translating the transaction code when it is ISRT'd rather than by the COPE supplied message switcher. You must not alter any rows created by the MSGDRIVE command. COPE Dictionary Internal COPE Dictionary Tables (Option 4.10) Introduction COPE maintains several ISPF tables that contain information about the environment. The tables are used to rename objects and to coordinate various activities during the generation process. Before describing the display facilities, a brief description of the way information is maintained in the tables will be given. COPE uses ISPF tables to store many types of records. The type of record is maintained in a variable named Rowtype. If a table only has a single type of record, there is no row type field defined in the table. All fields for a particular Rowtype are normally stored as extension variables (see the IBM ISPF Programmers Guide for an explanation of extension variables). COPE uses a convention for storing hierarchical information. The convention is top to bottom left to right. E.g. If segment types B and C are children of type A then the rows are stored as: AB B C C A B etc. If this convention is not followed when segments are changed, COPE facilities will not operate correctly. Multi segment tables always have a single "root" row followed by a hierarchy of rows as described above. For problem analysis, there may be a requirement to display the contents of the control tables. For example, you may want to translate "real" names to C-numbers or vice versa. Warning: C-numbers are often reserved for objects but never used, so do not take the presence of a C-number as an indicator that a corresponding member must exist. It may not. COPE for IMS Administration Guide 67

68 The contents of tables and their fieldnames may be dumped into a dataset for editing see Viewing Table Contents in Edit, however tables may also be displayed in a more structured edit application (For a description of the details of the Table Editor see Viewing Table Contents in Edit). Some of the tables may be displayed by entering 4.10 (Dictionary) on the primary panel. The following menu will be shown: Figure 42 Dictionary Table Selection Menu Additional tables mat be view by entering 11 on the primary table Selection Menu. The Table contents are :- Option Description Table of all PSBs, their COPE C-numbers and their usage (Same display as 4;PSB;GB) 4.10;2 Imported DBDs and their assigned C-numbers for DBD and DD names Imported DFSMDA (Dynalloc) definitions Stage 1 definitions Table of PSB name and default C-number Plan names Imported MFS names and their COPE assigned MID and MOD names DBDs and their assigned COPE C-number (subset of table) Table of DBD,FILE,AREA names for DEDB definitions Table of DBD,FILE,AREA,C-number names DB2 collection names used in COPE plan conversion Explicitly related DBDs for all systems Cross reference of PSBs and the DBDs they reference together with the C-numbers of each (This table must be generated by a batch job) BMP and Batch PSB and their COPE C-numbers PSBs excluded with B;4;2;XPSB application Excluded definitions from Option On-line (MPP IFP) PSBs and their C-numbers COPE for IMS Administration Guide 68

69 BMP PSBs and their C-numbers Excluded DBDs for PSBs defined with the B;4;2;XPSB application Table of all DBDs and their COPE C-numbers for all systems Table of related program names (not-used) Disabled Table of areas and COPE assigned C-numbers for DEDBs Viewing Table Contents in Edit The COPE dictionary contains many tables and many fields. The best way to understand the contents of the tables is to dump the contents so that the data is displayed together with the field name it is contained in. COPE tables are addressed by a 4 part name PROJECT.GROUP.TYPE.NAME. There are Project related tables and System related tables. System tables have a $ value for PROJECT and LEVEL. Project tables use the PROJECT and GROUP values associated with an Lsys. Option 5.8 allows COPE dictionary tables to be dumped. The following menu is displayed. Figure 43 Table Dump Specification Menu If P is entered in the command field and the PROJECT, GROUP,TYPE and NAME fields are completed a table will be retrieved and dumped to a dataset. The dump may be reviewed by entering E. There follows an example. COPE for IMS Administration Guide 69

70 Figure 44 Table Dump Example The number of rows in the table is displayed. The field names associated with the data is displayed in a box. The number to the left of the field names is the value of the ROWTYPE field. The data values are aligned under the field names. The ROWTYPE of the row that the data was extracted from is displayed on the left. There follows a table of PROJECT,GROUP,TYPE,NAME table access values and a description of the table that is accessed. PROJECT GROUP TYPE NAME TABLE DESCRIPTION $ $ $ $ System Index. This table contains the C-number table name of all System tables $ $ ACTIVE ACTIVE Table of active systems $ $ ADDPSB ADDPSB Table of C-numbers by Lsys for BMP applications $ $ HALDB ALL Table of C-numbers for HALDB Databases and Partitions $ $ ALLACB ALLACB Table of all PSB together with their usage and C- numbers $ $ ALLSTAG ALLSTAG Table of combined SDELTA Stage 1 attributes $ $ BMP BMP Table of all BMP applications and their C-numbers $ $ COPEIMS COPEIMS Table of Logical Systems and Dynalloc and Stage 1 sharing attributes $ $ COPEPR COPEPR Project/Group definition table $ $ MASS DBD All DBD from all Logical Systems with their DBD and DD C-numbers $ $ DESCDBD DESCDBD Able of information used by the COPE IMS SS application $ $ DISPLAY DBD Index table used by 3;DBD application $ $ DISPLAY PSB Index table used by 3;PSB application $ $ DISPLAY MFS Index table used by 3;MFS application COPE for IMS Administration Guide 70

71 $ $ EXCLUDE EXCLUDE PSBs excluded with B;4;2;XPSB application $ $ INCLUDE EXCLUDE Excluded databases and transactions and applications from 1;7 application $ $ TRANPSB TRANPSB Table used by B;5;4 X-Ref application containing all defined transactions and databases $ $ Lsys-name DBD DBD names and their associated DBD C-numbers and DD C-numbers $ $ Lsys-name DDELTA Deleted Stage 1 statements $ $ Lsys-name DYNALLOC DFSMDA (Dynalloc) definitions $ $ PGM Lsys-name PSBs and their assigned C-numbers $ $ SDELTA Lsys-name Stage 1 deleted statements $ $ STAGE1 Lsys-name Stage 1 source $ $ S1DELTA Lsys-name Stage 1 statement attributes $ $ MFS Lsys-name MFS NID and MOD names and their COPE names $ $ LEVSTRUC LEVSTRUC Hierarchical information for defined Logical Systems $ $ LOGICDBD LOGICDBD Table of explicit logical relations between databases for all Logical Systems $ $ PGMREN PHYSYSXX (The XX is the XCOPEINU ZDEFAULT value) Table of Logical Systems the PSBs are defined in $ $ STG1 TERMINAL Non APPLCTN,DATABASE,TRANSAVT Stage 1 statements $ $ XCMNSTG1 STAGE1 Stage 1 source for XCMNSTG1=YES ZDEFAULT definition $ $ XREF2TAB XREF2TAB Entities and their C-number generated by the Stage 1 generation process and used for the REFRESH processes PROJECT GROUP DBD $ or NAME (Index if $ specified) Parsed DBD information PROJECT GROUP DBDCOPY $ or NAME (Index if $ specified)dbdcopy definitions member list PROJECT GROUP DBDSRCLB $ or NAME (Index if $ specified) DBD source definitions member list PROJECT GROUP MFS $ or NAME (Index if $ specified) Parsed MFS information PROJECT GROUP MFSCOPY $ or NAME (Index if $ specified) MFSCOPY definitions member list PROJECT GROUP MFSSRCLB $ or NAME (Index if $ specified) MFS source definitions member list PROJECT GROUP PSB $ or NAME (Index if $ specified) Parsed PSB information PROJECT GROUP PSBCOPY $ or NAME (Index if $ specified) PSBCOPY definitions member list PROJECT GROUP PSBSRCLB $ or NAME (Index if $ specified) PSB source definitions member list List Excluded Databases (Option B;4.2.LDX) When PSB's are excluded, all databases that the PSB's refer to are also excluded together with all those databases' indexes or logically-related databases. COPE for IMS Administration Guide 71

72 The LDX command displays excluded DBD names as follows: Figure 45 The LDX Display of excluded DBDs Initial installation considerations Certain considerations must be given to installation features and design options. Installing the COPE DFSAOE00 exit There are two supported environments with different JCL install procedures supplied in the installation JCL dataset. IMS without the BMC MAINVIEW facility Use COPEEXIT procedure IMS with the BMC MAINVIEW facility Use COPEMAIN procedure The control region JCL should be modified with a //COPEPGM DD DISP=SHR,DSN=XCOPEPGM-Dataset Translation tables are loaded from this dataset by the COPE DFSAOE00 exit. The DFSAOUE0 exit uses the cross reference module COPEXRF1 to translate the C-number names in messages to the MTO. This greatly assists with debugging. You can modify the message-suppression list, at label SUPPLIST in COPEAOUE, if you so desire. You are not permitted by your licensing agreement with Compuware to modify the COPE AOI modules (or any other COPE modules) in any way, except for this suppression list. COPE for IMS Administration Guide 72

73 Sharing a DB2 subsystem between multiple COPE Psys's To avoid name contention if a DB2 subsystem is shared between more than one COPE system, the first character of the COPE assigned C-number is made unique depending on the physical subsystem. The character used is specified in the ZDEFAULT variable XSQLUNIQ. Convert TRANSACT MODE=MULT parameters The COPE support of DB2 uses the IMS facility of a U777 abend whenever a transaction is obtained that is destined to operate in a different Lsys from a previous transaction obtained in the same application program scheduling. Artificially introducing a U777 abend causes the second transaction to be re-queued, and the thread to DB2 terminated so that a new plan name may be specified when the transaction is reprocessed. The technique requires that MODE=SNGL be specified for all transactions that invoke applications that access DB2 in the Stage 1 TRANSACT macro. The default is MODE=MULT. Configure CICS tables and resource definitions (COPE CICS feature) The following must be performed: If you are using RDO, you may modify source member DFHCSDUP in the COPE installation JCL library and run the job to install the definitions required for COPE-DBCTL/CICS. Otherwise, incorporate the updates in DFHPPT and DFHPCT members located in the COPE installation ASM library into your PPT and PCT. If you plan to start COPE-DBCTL/CICS automatically, incorporate the DFHPLT1 source member, located in the COPE installation ASM library, into your current startup PLT, or use the DFHPLT2 member, located in the COPE installation CTLCD library, as a new startup PLT. In corporate the DFHSIT member, located in the COPE installation CTLCD library, into your SIT. Copy load modules to the CICS environment if CICS feature present If the CICS feature is present, the following must be performed: If you will be using the COPE-DBCTL/CICS installation load library in your CICS JCL, include it in your DFHRPL concatenation; otherwise, link or copy COPEREFR, COPEPRE and COPEPOST into an appropriate library. Include the dataset defined by the XCOPEPGM ZDEFAULT variable into the DFHRPL concatenation. This step allows access to the COPEXRF1 and COPEXRF2 cross-reference modules used in translating database names. Add COPEBSYS DD card to CICS region JCL All CICS transactions access a set of databases assigned to the same Logical System (Lsys). The Lsys is identified by a JCL DD card added to the CICS region JCL as follows: //COPEBSYS DD DSN=&&LSYS,SPACE=(TRK(1)),UNIT=SYSDA The Lsys is defined by a one to eight character name following the two ampersands (&&) defining a temporary dataset. A CICS region may access a different Lsys if it is shutdown and the COPEBSYS DD card is changed. COPE for IMS Administration Guide 73

74 Changing Message Region Datasets (Option 1.5) Sometimes users require a change to the Steplib concatenation of load libraries used for each Lsys. These are dynamically allocated by COPE in each message region (they are not in the message region JCL, and cannot be put in the message region JCL). You can change these dynamic allocations at any time, without bringing down the message regions. The option for modifying Message Region datasets is 1.5 As well as Steplib load library concatenations, you might have other library concatenations, VSAM files, or sequential files which you want to vary across Lsys's. You specify these in the same MDS table. To change Message Region Datasets: Go into option Insert, delete or change the TASKLIB DD rows, for Steplib concatenations. Note that the "concatenation number" specifies the order of the DSNs in each concatenation. "TASKLIB" refers to the internal mechanism used by COPE to make the libraries behave exactly like a Steplib. You should put libraries that are common to all Lsys's in the message region JCL on the COPESTEP DD, not in the MDS table. 2. Insert, delete or change other DDname rows, for non-steplib datasets. 3. Press <PF3>, and you will see the following menu Figure 46 Dependent STEPLIB on Class and PCB If you press PF3 you will be put into EDIT on generated JCL which you should submit (SUB) to recreate the COPEXRF4 load module with the TASKLIB definitions in them. Check the submitted job runs correctly with zero condition codes If you press ENTER you will see the following COPE for IMS Administration Guide 74

75 Figure 47 STEPLIB selection Criteria Menu This facility allows a different TASKLIB to be specified for message regions that have a specific scheduling class (for a MPP region) or PSB name (For an IFP region). These Tasklibs are different from the default Tasklibs specified in the previous dialog. Option 1 specifies either the job class or the IFP region PSB name to scan for if Tasklib specifications different from the default are required. Option 2 specifies the Tasklib datasets for each selection. If you select Option 1, the following panel is displayed COPE for IMS Administration Guide 75

76 Figure 48 STEPLIB Class set definition This allows specification of selections. Each selection has a name or ID shown in the second column In the example Selection 01 is applied to message regions that have scheduling classes 77.. Selection 03 applies to an IFP region that has PSB DFSIVP4 specified in the JCL MPP regions may have up to 4 classes specified. Only one of them need be specified in the selection. If you want to SAVE the specifications before they are completed enter SAVE in the command field. If you want to leave the specification so that you can return at a later time, enter CAN to CANCEL the specification process. Use of the CAN command will lose all specifications entered after the previous SAVE command. Press PF3 and selection Option 2 on the selection panel will display the following panel Figure 49 STEPLIB set dataset definition For every selection id specified in the previous dialog you have to specify Tasklibs FOR EVERY LOGICAL SYSTEM. If there are more than one dataset, a concatenation number must be specified in the rightmost column. Pressing PF3 twice will put you into edit on generated JCL that contains the specifications for all Tasklib members. The JCL should be (SUB)mitted and the return codes checked. Go to IMS, clear the screen, and type COPE REFRESH. This causes all message regions to refresh their MDS allocations on the next transaction through each region. Separate Region/Lsys (Option 4.2.SEPREGN) COPE is designed to allow all transactions from all Lsys's to execute in a common set of message regions. Occasionally, however, it is necessary to separate execution of applications and cause them to execute in separate message regions dependent upon the Lsys in which they are operating. This is required, for example, COPE for IMS Administration Guide 76

77 when Lsys-specific versions of preloaded modules are required and the region is not large enough to contain them all. Another example might be when the application architecture is such that information from an Lsys is transferred in preloaded modules between successive transactions. Note: It is not necessary to use the separate region option if files are opened in the message region or if the COPE preload capabilities are satisfactory. The SEPREGN option causes a modification to the Stage 1 generated source, and introduces a Message Switcher that reads all transactions associated with a PSB and switches them to synthetic transactions with separate classes based on the Lsys they are operating in. Whenever a SEPREGN PSB is generated, a separate PSB and STUBX is generated for each Lsys. together with a PSB for the Message Switcher. The operation of the option is controlled by information maintained in three places: The ZDEFAULT XMBMP parameter The separate region PSB definition B;4.2.SEPREGN;1 option The Lsys message region class defined with B;4.2.SEPREGN;2 option Set the ZDEFAULT XMBMP parameter to the class you want to run BMP message switcher transactions in (the default is class 1). Message switcher transactions run quickly, so they do not hold up the regions in which they run. Assign a class that is eligible to run in many regions so that message switcher transactions are not held up by longrunning transactions. The following panel is displayed when B;4.2.SEPREGN option is entered. Figure 50 SEPREGN Selection Menu COPE for IMS Administration Guide 77

78 Select PSB's for separate Message Region Execution Option 1 causes the following menu to be displayed Figure 51 SEPREGN PSB Selection Menu All fields on this screen except for the SEP REGN field are protected. In this field, a Y should be put next to any PSB whose transactions are to operate in separate message regions. The following commands may be entered in the COMMAND field: The L command positions the table so that a specified PSB is displayed. The RESET command resets all selected PSB's. If an error is made in the selection, a CANCEL command may be entered to prevent the reset definitions from being put into effect. The S command selects one or more PSB's based on a mask. A prompt for the S mask parameters may be obtained by entering S only with no mask. Define Message Region Class by Lsys The transaction classes that each Lsys transaction is to operate in may be defined with options B;4.2.SEPREGN;2. The data displayed is shown in the following figure. COPE for IMS Administration Guide 78

79 Figure 52SEPREGN Message Region Class Definition Menu The Tran Class defined for each Lsys must be unique. The APARM field is used for the message region parameter list option. Java JMP and JBP Regions When a PSB has LANG=JAVA on the PSBGEN statement, it is destined to execute in a JAVA JMP online region or a JAVA JBP batch region There are additional setup steps required to correctly schedule JMP regions. 1. Use the B;4;2;SEPREGN application to define the PSB as a SEPREGN type PSB 2. Add the additional PSB C-number names to the DFSJVMAP PROCLIB member 3. Do a Stage 1 generation with Option 4.1 to generate the additional SEPREGN transactions 4. Add a JMP region with the class specified in the SEPREGN application Use the B;4;2;SEPREGN application to define the PSB as a SEPREGN type PSB Using the dialogue defined previously, every Logical system has a unique transaction class assigned to it. Using Option 1 Select PSB's for separate Message Region Execution all JAVA PSBs should be defined as running in separate regions. On exit from the definition process, a job will be generated to recompile the PSBs. COPE for IMS Administration Guide 79

80 Add the additional PSB C-number names to the DFSJVMAP PROCLIB member The DFSJVMAP member of the IMS PROCLIB data set can be used with a DFSJMP procedure. DFSJVMAP maps all the 8-byte or less uppercase Java application names (specified to IMS) to the true OMVS path name for the ".class" file associated with that Java application. The DFSJVMAP member must be updated with the COPE C-number names assigned in the SEPREGN process. These names may be obtained by using the 4;PSB;GB application. An example of the DSJVMAP member with COPE names follows ********************************************************************** * This is a mapping of PSB names to Java samples. * The Java samples are delivered in the samples.jar file. * The location of this samples.jar file must be specified separately * by the DFSJVMMS member in the shareable application classpath. * PSB Regions Java programs * * DFSIVP37 JMP IMSIVP.class * DFSIVP67 JBP IMSIVPJBP.class ********************************************************************** DFSIVP37=samples/ivp/ims/IMSIVP C =samples/ivp/ims/IMSIVP C =samples/ivp/ims/IMSIVP C =samples/ivp/ims/IMSIVP C =samples/ivp/ims/IMSIVP * ********************************************************************** * The exec parms in the JBP region proc are set as: * MBR=DFSJBP and PSB=DFSIVP67 ********************************************************************** DFSJBP=samples/ivp/ims/IMSIVPJBP * DFSCATS2=samples/ivp/opendb/OpenDBCatalogSQLType2 DFSCATD2=samples/ivp/opendb/OpenDBCatalogDLIType2 * Do a Stage 1 generation with Option 4.1 to generate the additional SEPREGN transactions The SEPREGN application associates a message switcher application with the original JAVA application transaction(s). COPE will generate a separate transaction/psb pair for each Logical system. The message switcher reads the incoming transaction and extracts the Logical System the user is connected to. It then selects one of the generated COPE transactions and inserts the message to it. The generated COPE transaction is associated with a transaction class that is serviced by a JMP region. The 4.1 generation process generates the message switcher and the additional transactions with their unique associated classes Add a JMP region with the class specified in the SEPREGN application The JCL should be defined for a normal IMS JMP region. There should be a separate region for every COPE Logical system. The class parameter (CL1) should match the class specification specified in the SEPREGN application. An example of the JMP region follows Note COPERC00 is not specified in place of DFSRRC00 COPE for IMS Administration Guide 80

81 //IVP14J11 JOB COPE, // 'RICKJON', // CLASS=A, // MSGCLASS=A,MSGLEVEL=(1,1), // NOTIFY=RICKJON, // TIME=(1439), // REGION=0M //* /*JOBPARM PROCLIB=PROC00 //* //PROCLIB JCLLIB ORDER=(TFTPROD.RELEASEE.PROCLIB) //* //DFSJMP PROC SOUT=A,RGN=512K,SYS2=, // CL1=000,CL2=002,CL3=000,CL4=000, // OPT=N,OVLA=0,SPIE=0,VALCK=0,TLIM=00, // PCB=000,STIMER=,SOD=, // NBA=,OBA=,IMSID=,AGN=, // PREINIT=,ALTID=,PWFI=N,APARM=, // LOCKMAX=,ENVIRON=, // JVMOPMAS=,PRLD=,SSM=,PARDLI=, // MINTHRD=000,MAXTHRD=256 //* //JMPRGN EXEC PGM=DFSRRC00,REGION=&RGN, // TIME=1440,DPRTY=(12,0), // PARM=(JMP,&CL1&CL2&CL3&CL4, // &OPT&OVLA&SPIE&VALCK&TLIM&PCB, // &STIMER,&SOD,&NBA, // &OBA,&IMSID,&AGN,&PREINIT, // &ALTID,&PWFI,'&APARM',&LOCKMAX, // &ENVIRON,,&JVMOPMAS,&PRLD, // &SSM,&PARDLI, // &MINTHRD,&MAXTHRD) //* //* //STEPLIB DD DSN=TFTPROD.RELEASEE.&SYS2.SDFSJLIB,DISP=SHR // DD DSN=TFTPROD.RELEASEE.&SYS2.SDFSRESL,DISP=SHR // DD DSN=CEE.SCEERUN,DISP=SHR // DD DSN=SYS1.CSSLIB,DISP=SHR //PROCLIB DD DSN=TFTPROD.RELEASEE.&SYS2.PROCLIB,DISP=SHR //SYSUDUMP DD SYSOUT=&SOUT, // DCB=(LRECL=121,BLKSIZE=3129,RECFM=VBA), // SPACE=(125,(2500,100),RLSE,,ROUND) //* COPE SPECIFIC DATASETS //COPESTEP DD DSN=TFTPROD.RELEASED.PGMLIBCO,DISP=SHR // DD DSN=TFTPROD.COPE.LOAD,DISP=SHR // DD DSN=TFTPROD.COPE1.LOAD,DISP=SHR //COPEMENU DD DISP=SHR,DSN=TFTPROD.COPE.MENUS // DD DISP=SHR,DSN=TFTPROD.COPE1.MENUS //COPEJCL DD DISP=SHR,DSN=TFTPROD.COPE.JCL //DFSESL DD DISP=SHR,DSN=DSN910.SDSNLOAD COPE //DFSSTAT for IMS Administration DD SYSOUT=* Guide 81 // PEND //* //IVP14J11 EXEC PROC=DFSJMP,

82 The External Interface Examples of JCL that performs batch Import and generate functions for COPE can be accessed via Option 1.4 Edit External Interface (Batch Input) Sample JCL. The resultant display is shown Figure 53 External Interface Examples The External Interface is used as an interface to change management systems. Batch jobs may be initiated to perform the same functions as All jobs consist of a single step that provide parameters to a JCL procedure. COPE for IMS Administration Guide 82

83 Generation of External Interface JCL Procedure (Option 1.2) Figure 54 Generation of External Interface Procedure Menu Option 1.2 generates the JCL procedure used in the external interface and copies it to the dataset specified on the JCLLIB ORDER parameter specified in the JOB card statements on the panel. DLI Call trace from Batch and BMP jobs To get a trace of all DLI and SQL calls in batch or BMP, add this card to the JCL: //COPETRAC DD SYSOUT=* Accessing COPE tables from external systems Cope maintains extensive information about an IMS environment in ISPF tables. Sometimes, users require to enhance their environment by building ISPF based applications that can access the COPE information. A sample CLIST 'SAMPTGET' is provided that shows how a COPE table may be accessed for processing by an external application. There are four variables required to access most of the COPE ISPF tables. They are: PROJECT (Usually '$') LEVEL (Usually '$') TYPE NAME The values for TYPE and NAME parameters may be found in "Error! Reference source not found.." COPE for IMS Administration Guide 83

84 Most of the tables contain their information as extension variables. If this is the case, there is always a named field called Rowtype that contains a number that identifies the type of row. The PROJECT and LEVEL values of '$' (dollar sign) indicate a system table. Tables that do not have a value of '$' are associated with a specific Lsys. Batch Update for External System Introduction Sometimes, users of COPE require speedy access to the COPE dictionary information. Change management systems frequently require access to the COPE C-numbers to allow them to perform their functions. Using the ISPF based access method described in the previous section can be burdensome if applications invoke it hundreds of times a day. Invoking ISPF under TSO can take minutes on a busy CPU. COPE supplies a program named COPECHEK that can be invoked in batch processes to check on the definition of a PSB in the COPE Stage 1. COPE also supplies a ZDEFAULT parameter (XBACKGEN) that will generate a job and submit it to batch whenever a PSB, DBD, or MFS member is generated. This job will have the object name, the Lsys and the COPE C-number information put out on records. The intent is that the user write programs to take the information and update external (probably DB2) subsystems so that the information is available in a more convenient form. The alternative method is to unload the dictionary tables on a routine schedule. This method will not capture new object names in a timely fashion, and may prove to be expensive in processing time. COPECHEK program The following JCL will invoke the COPECHEK program: //JOBNAME JOB JOB-PARMS // ******************************************************************* // * This job is an example of using the COPECHEK program which // * validates the presence of a PSB specification in the Lsys // * Stage 1. // * The PARM field contains PSB-NAME, LSYS-NAME, INTENDED-USAGE // * (either DLI, MPP, BMP) separated by spaces. // * The return codes are // * 0 - The PSB has been defined to COPE and matches the intended // * usage // * // * 4 - The PSB has been defined to COPE but the usage is // * inconsistent with that specified in the PARM field // * 8 - The PSB has not been defined to COPE // * 12 - Unknown Lsys specification // * 16 - Internal error. The JOBLOG will contain messages that // * describe the error // * // ******************************************************************* // COPECHEK EXEC PGM=COPECHEK,PARM='PSBNAME LSYS-NAME DLI' // STEPLIB DD DISP=SHR,DSN=COPE-DISTRIBUTION-LOAD-LIB // COPESTEP DD DISP=SHR,DSN=COPE-PGMLIB (XCOPEPGM library) XBACKGEN support COPE for IMS Administration Guide 84

85 The ZDEFAULT parameter XBACKGEN has three positional parameters that allow jobs to be generated whenever PSB's, DBD's, and MFS members are imported or compiled. Each position may be set to Y or N to control the respective process. There are three ISPF skeleton Procs provided named COPEUPSB, COPEUDBD, and COPEUMFS. These skeletons must be modified by the customer, to allow invocation of a user program that will process the records punched out by COPE, and update an external system table or file. Every time a PSB is imported or compiled, the following information is created: PSB-NAME,LSYS-NAME,PSB C-NUMBER,PLAN C-NUMBER Every time a DBD or MFS member is imported or compiled, the following information is created: DBD/MFS NAME,LSYS-NAME,DBD/MFS C-NUMBER Column 33 contains the characters PSB, MFS, or DBD to identify the type of information being provided. Install MSG Region Security Exit COPESXSX COPE delivers two example modules for implementing control of functions under IMS. If RACF is used, the module COPESXSX provides an example of checking a users authority to access logical systems or issue commands from the COPE panel. If ACF2 is used, the module ACF2SXSX provides an example of using the Extended ACF2 call to validate transaction access within a logical system or access to a logical system or command authority. This example program may be renamed to COPESXSX and modified by the user. The RACF based module COPESXSX (STUBX's Security exit) implements AUTH-call security based on the XIMSSEC parameter. You can modify or replace this exit, to implement variations on the scheme provided. If you require that access restrictions vary across Lsys's, you should review this section. If you do not require this variation, then you should use regular IMS AGN-type security restriction by transaction code, and set XIMSSEC=N. If you do not use /SIGN-type security, then you must code XIMSSEC=N. If you want security variation across Lsys's, set XIMSSEC (in your copy of ZDEFAULT in PROCS) to either: Y Restricts access to an Lsys at the time the user tries to logon to the Lsys. The RACF/ACF2/ etc class is COPELSYS, resource type is Lsys (8-character logical system name). T Restricts Lsys access (same as with Y) plus checks each transaction the user runs. The class is OTHER, and the resource type is 8-byte Lsys, and the Key is 8-byte transaction code. This security is in addition to, and does not replace, any IMS AGN-type transaction code security you might have implemented. This means that you have to code sets of rules at all 3 levels: 1. Regular IMS transaction code AGN-type checking 2. COPELSYS class 3. OTHER class, Lsys Resource Type (if you code XIMSSEC=T) COPE for IMS Administration Guide 85

86 Note: Y and T also turn on checking of commands from the COPE screen. The delivered scheme allows everybody to issue /STA TRAN, etc commands, but restricts /DBR DB, /STA DB, /STO DB, etc, via an AUTH call with Class=COPECMD, Resource Type=Lsys. For further details see the documentation in ASM(COPESXSX). To change this scheme change COPESXSX. If you use XIMSSEC=T and you are using an SXSX scheme from prior to release 3.9.8, you should ensure that you name your Lsys's so that the last two non-blank characters are unique, otherwise the security for one Lsys will apply also to another that has the last 2 non-blank characters the same. The delivered COPESXSX implements the above security scheme via IMS AUTH calls. This exit is not authorized, and therefore you cannot use ACEE= or USERID= parameters on any RACROUTE macros. This exit also runs in 31-bit mode, and therefore you cannot use RACHECK macros (use RACROUTE instead). We recommend that you do not attempt to use RACROUTE; the Userid of the message region would be used if you did, and this is not normally appropriate. Use AUTH calls instead of RACROUTE, AUTH will check the /SIGN Userid against the 8-character resource name you pass. The parameter list COPE passes to COPESXSX is described in the delivered COPESXSX source. The seventh parameter is the XIMSSEC value (up to 24 bytes), and you could use this to control your security processing, if need be. If you do write or modify COPESXSX, you must fulfill these requirements: Write it in Assembler Link it to a library on the COPESTEP DD in the message region Write it RENT and REFR Do not GETMAIN areas Do not LOAD other modules A 512 byte work area is provided for exclusive use by this exit. The supplied exit contains notes and examples to assist you in modifying it. Parameters at Entry R0 = 40 COPE command security = 44 Before Program Load R1 -> -> Fake PCB list -> Logical System, Transaction code, Program name, etc fields -> First seg of msg from GU to I/O Pcb -> Line 3 error message return area -> -> 1K work area (use only first 512 bytes for SXSX) -> If R0=40, 24*12-byte tokens of COPE command If R0=44, 8-byte value "TRANSACT" -> 1-24 byte XIMSSEC value (is -not- blank padded) Parameters at Return to COPE R15 = 0 OK, Continue =8 Security restriction, send user message When a COPE command is about to be processed, SXSX is entered with R0=40. R1 points to the same parameter list as for R0=44, except that the sixth parameter is a token array, instead of "TRANSACT". The token array consists of byte entries, with each entry consisting of 8-character token followed by 4-byte COPE for IMS Administration Guide 86

87 pointer to the token in the command string. When the user logs onto an Lsys, the first token is LOGON, and the second is the Lsys name The 8-byte tokens are always upper case and padded on the right with blanks. The 4-byte pointers are not useful and should be ignored (they are only used internally for locating un-tokenized strings such as in the MSG command). The command LOGON appears always for a logon, even though the user does not need to explicitly type LOGON. If you determine that this user should not be able to logon to this Lsys, place a 72-byte message in the 4th parameter, and return with R15=8, else return R15=0. All other COPE commands can be treated similarly to the LOGON command, if desired. The delivered scheme in SXSX will check all commands against CMDTAB (a table coded inside SXSX) and if that table specifies that the command is restricted, it will issue an AUTH call, with Class=COPECMD, Resource Type=Lsys. If you use this scheme, you should code ACF2/RACF/ etc exits and/or rules to allow DBA-type users to issue commands. For further details see the documentation in the delivered ASM(COPESXSX). Install Online Exit COPESXUX The module COPESXUX (Stub User Exit) is a dummy user exit, which you can replace with your own exit, in order to implement facilities such as: Freemaining storage during COPE delete-type cleanup Support of LU6 or SLUP devices Versioning preloaded tables Changing the DB2 plan name Changing MQM message queue names It is not normally necessary to code any exit, unless you have special requirements in one of the above areas. If you do write an exit, you must fulfill these requirements: Write it in Assembler language Link it to a library on the COPESTEP DD in the message region Use the RENT and REFR options Do not GETMAIN areas Do not LOAD other modules A 512 byte work area is provided for exclusive use by the exit. The supplied exit does nothing by setting R15=0 and returning. It contains notes and examples to assist you in writing an exit. Parameters at Entry Parameters on Entry - R0 = 0 After GU I/O PCB COPE for IMS Administration Guide 87

88 = 4 Before load program = 5 After TASKLIB allocation (Set UXES2 to UXE05) = 6 Before TASKLIB allocation (Set UXES3 to UXE06) = 8 DL/I Call, Appln- >COPE = 12 DL/I Call, COPE- >IMS = 16 DL/I Call, IMS- >COPE = 20 DL/I Call, COPE- >Appln = 22 User not connected to Lsys = 24 Program terminated normally = 28 In abend ESTAE = 32 Cleanup delete module = 36 Command issued = 48 Before SQL call = 52 Before MQM call = 99 Supress COPE messages to terminals R1 -> -> Fake PCB list -> LSYS1,TRANC,PROGR,LTERM,LTSIG,SIGNO,CTRAN,... -> 1st seg of msg from GU I/O PCB -> 72-byte area for line 3 msg back to user -> UXAWK,UXLWK,UXESW,UXWRK,UXESL,... -> module name/command/db2 plan, or MQM Output Descriptor or "" -> " " Parameters at Return to COPE R15 = 0 OK, Continue = 4 Do not continue, this exit took care of = 8 Do not continue, send user message Description of operation The exit may be invoked at many points in the IMS environment. The exit is always invoked before a GU in the message region with R0 set to 0. The remaining exit points are controlled by setting a bit in a control block field. These bits are set on the initial entry by the following instructions. Enabling Instruction R 0 Value Exit Description OI UXESW,UXE00 0 Before GU DL1 call OI UXESW,UXE04 4 Before application program load OI UXES3,UXE06 6 Before Tasklib switch OI UXESW,UXE08 8 DL1 call from application to COPE OI UXESW,UXE12 12 DL1 call from COPE to DL1 OI UXESW,UXE16 16 DL1 call from IMS to COPE OI UXESW,UXE20 20 DL1 call from COPE to application OI UXESW,UXE24 24 Normal application termination OI UXESW,UXE28 28 Abnormal termination ESTAE OI UXES2,UXE32 32 Cleanup delete module OI UXES2,UXE36 36 Command COPE for IMS Administration Guide 88

89 OI UXES2,UXE48 48 Before DL2 call OI UXES2,UXE52 52 Before MQM call OI UXES2,UXE52 53 After MQM call The details of control block fields are available from compilation listings of the example exit. Implementing Cleanup-Delete Freemains COPE by default runs all Lsys's in all message regions. It "cleans up" on an Lsys change by deleting modules that have been loaded and not deleted when a transaction is scheduled in another Logical System. If your message region storage usage is high, you must run using dedicated message regions (SEPREGN see Separate Region/Lsys (Option 4.2.SEPREGN)), You turn on cleanup-delete using DEBUG MODE 9 (e.g. in your COPEO COLDS/WARMS definitions). If modules that remain is storage contain pointers to getmained areas, you need to freemain those getmains, at the time that COPE cleanup deletes the modules. To do this, on entry code R0=4, set the cleanup-delete entry code R0=32 active: OI 2 UXES2,UXE3 Then exit with R15=0. When COPE cleanup is about to delete a module, it will enter your user exit with R0=32, and the sixth parameter pointing to an 8-character module name, followed by a 4-byte pointer to the CDE. You should examine the module name, and if you know that this module contains pointers to getmained areas, you should freemain those areas, then return R15=0. If your storage is assigned in subpools, it is very easy to just freemain the subpool, e.g.: FREEMAIN RC,SP=42 If you need to locate the entry point of the module, follow the CDE pointer; the entry point address is at +16 in the CDE. Support of LU6 or SLUP devices Some remote programmable work-stations might be configured so that the Lterm name and Sign on fields in the I/O PCB are not meaningful enough to distinguish one terminal from another, for the purposes of determining which Lsys the terminal is logged onto. You can decode routing information in the message segment, to assist COPE with this. Test for R0=0 on entry (return with R15=0 for any other R0 entry value). The R0=0 entry is immediately after the GU to I/O PCB, and before COPE has attempted to determine what the Lsys is. Examine the first segment of the input message, passed in the 3rd parameter, plus the Lterm name, plus any other fields that you need to examine. Place an eight-character identifier for the terminal in the Lterm name/sign-on field at +32 dec in the second parameter, and return with R15=0. COPE will use the 8-character name you supply to look up the current logged-on Lsys in the terminal database. If you detect some unresolvable condition, you can return a message and R15=8. Do not return with R15=4 for this COPE for IMS Administration Guide 89

90 type of processing. Versioning of Preloaded Tables If you load tables into the message region in the form of load modules, and you wish different Lsys's to see different versions of those tables, you cannot preload the tables. Generally, everything will then work, but you will find that COPE is flushing the tables out of the message region (it issues DELETE's to cleanup the region) every time a transaction arrives that is for a different Lsys system from the previous Lsys. This frequent flushing and loading of the tables may be unacceptable for performance, particularly in a production environment. To fix this problem, you can code a user exit that interfaces to your table manager, to allow versioning of preloaded tables. This will work if: 1. You have some master table which points to the other tables, and this master table is the only module that application programs issue LOAD for 2. You do not mind preloading the tables under different names The idea is to change the pointers in the master table to point to the appropriate table for the current Lsys. To implement this type of versioning of preloaded tables, test for R0=4 on entry, and return immediately with R15=0 for any other entry code. Test the Lsys name at +0 in the second parameter. Traverse the pointers in your master table, changing them to point to the appropriate tables for this Lsys. Return with R15=0. GETMAIN and LOAD restriction If you GETMAIN, or LOAD, and save the pointer to the area or module in your work area, and expect that pointer to be valid on the next transaction, you will abend with an 0C4 if the current transaction abends. The reason is that the message region cleans out your GETMAIN's and LOAD'ed modules on abends. Clearly it is OK to GETMAIN or LOAD, as long as you do not save the pointer to the area or module, and expect it to be valid across transactions. In other words, there would be no point not FREEMAINing and DELETEing. In contrast to this, the COPESXUX/SX modules (your exits) are not cleaned out by abend, nor is the 1K area freed by abend. The reason for this is that COPE loads/getmains these exits in the message region mother task. This facility is provided so you can retain information across abends, if this is desired. The problem is that you have to be careful what information you retain. If you need a bigger area than 1K, you can have COPE getmain it in the mother task, by issuing a "COPEF GETMAIN,AUXWK" macro (see the prolog to COPEF for more details). If you use COPEF GETMAIN, you must reassemble your user exit on a new COPE release, and conversely, if you can avoid using COPEF GETMAIN, no reassembly is required. If you need to load other modules, it is recommended that you preload them, and always issue a LOAD at the beginning of each transaction, to locate the address of the module (because that address might have changed). COPE for IMS Administration Guide 90

91 It is probably preferable to statically link any modules you need in with COPESXUX. A COPE REFRESH command will reload a new version of COPESXUX (though it will leave your 1K work area unchanged). Change DB2 Plan Name in Exit This is ONLY appropriate if all your PSB's within an Lsys can use one DB2 plan (or similar simple requirement). In that case you set R0=48 "active" in R0=4 entry, using: OI 48 UXES2,UXE Then, on the entry code R0=48, you look at the LSYS1 field and PSBNM field, and generate the plan name you want, and MVC it over the 8-chars passed on the 6th parameter. A suggestion is to take the first 4-chars of the plan name from the Lsys name, and set a suffix such as "0001" onto this. You MUST set the same plan name for the same Lsys.PSB combination. However, different PSB's could have different plan names from each other, but it is important that the relationship be very simple, for maintainability. You MUST provide your own bind JCL and control cards to bind the correct plan name whenever you recompile DB2 modules (COPE does NOT provide suitable Bind JCL if you use the SXUX plan name selection mechanism). To see the action of your exit: In IMS COPE, say TRACE ON Run your transaction (one that issues SQL calls) In IMS COPE, say FLUSH In ISPF COPE 6.2, put From Time, Transaction code ===> * (for all), and Display ===> D (for detail) Press Enter to extract and edit the trace records Find SQL in col 1 Just before the first SQL call in the tran, you should see msgs like: =WARN> DB2 Plan name changed from C to LS by SXUX =MSG=> DB2 Plan set to LS SQL OPEN rc=0 If you don't have a DB2 tran you can run easily, from IMS COPE say DB2. This will issue some SQL calls (which will probably get -922's, which is fine for purposes of checking the exit). Then in ISPF COPE 6.2 put Display ===> C (not D) to see the COPE transaction, and you should see msgs like: =WARN> DB2 Plan name changed from COPEUTP1 to LS by SXUX =MSG=> DB2 Plan set to LS SQL OPEN rc=-922 Whenever you change and reassemble COPESXUX, you must stop and start the message regions (e.g. use COPE BOUNCE command). COPE for IMS Administration Guide 91

92 The same exit is active for MPP, BMP, DLI and DBB regions. Take care to preserve your exit across a COPE delivery. Translate PSB/DBD names in an application program and DB2 Plan A program named COPETRA is provided with COPE for IMS/DC which can be called from a user written program to perform a COPE name translation. A DD file of the name COPESTEP must point to a dataset with the COPEXRF1 and COPEXRF2 load modules in them before the program is called. Register 1 points to a contiguous work area that has the format described below. Note: On the initial call, the ANCHOR field should be 4 bytes of hex zeros. After the initial call, the ANCHOR field should be left unchanged. The same work area should be used for all calls. When the calling program wishes to terminate, it should use the END function call to cause clean up operations to be performed. Register 1 points to a contiguous work area that has the following.format... FUNC INPUT NAME INPUT LSYS OUTPUT NAME OUTPUT LSYS ANCHOR RETCODE TYPE NUM CNUM LSYS TYPE <-- Repeated 30 times The functions are: Function PSBS PSBC DBDS DBDC DDDC DDDS TRAC END Description Gets a user PSB and Lsys from a C-number (The input Lsys is ignored). Gets a C-number from a user PSB and Lsys name (The output Lsys is the same as the input Lsys). Gets a user DBD and Lsys from a C-number (The input Lsys is ignored) Gets a C-number for a user DD and Lsys name (The output Lsys is the same as the input Lsys). Gets a C-number for a user DD and Lsys name (The output Lsys is the same as the input Lsys). Gets a user DD and Lsys name from C-number. (The input Lsys is ignored) TRAN Returns a list of matching transaction codes. This command fills in the number, C-number, Lsys and type fields at the end of the input record. Up to twenty entries may be present. Returns list of matching transaction codes when a C-number PSBNAME is passed. This command fills in the NUM, CNUM, TYPE and LSYS fields at the end of the input record. Up to 20 entries may be present. This function returns the C-number followed by a TRANSACTION CODE followed by 2 characters of blanks in the array. For overflow or message switched transactions, there may be several entries. In this instance, many of the entries may have C-numbers for TRANSACTION CODES (These are internally assigned by COPE). Should be issued by the calling program when it requires that translation program to delete any loaded modules and free internal work areas. The program issues the following return codes: 0 Successful completion 8 No match for input request COPE for IMS Administration Guide 92

93 Return the Logical System name to an Application Program A program is provided with COPE for IMS/DC that may be called to determine which Lsys an application program is executing under. The program to call is named COPEGLSY. It needs to be passed the address of an eight-byte area, into which the program places the Lsys name. Install BMP/DL1 Security Exit COPEBMPX COPE delivers an example module for implementing control of applications executing under a DL/1 or BMP region. The module is named COPEBMPX. Your installation is responsible for customizing this module, and for designing and implementing the security scheme for controlling the execution of BMP and batch jobs. The COPEBMPX exit is passed the values of the region type, the program name and the PSB name coded in the parm field of the DFSRRC00 program. The exit may issue a RACROUTE macro to check the authority of the user to execute the application program. If the exit issues a non-zero return code, the application is terminated. Archive Exit The Capture Archive Exit In the DBRC skeleton JCLLIB, there is member ARCHJCL, which is submitted by IMS automatically, every time an Online Log Data Set (OLDS) switches. The first (or only) step runs the log archive utility, DFSUARC0. You must add a card to SYSIN, and a COPEARCX DD statement to the step, and a STEPLIB for the COPE system load library. to support the "Program Information Online Capture" facility of COPE. An example of the JCL follows: //ARC5SSID JOB... //ARCHIVE EXEC PGM=DFSUARCO,PARM='%SSID',REGION=4M,TIME=30 //STEPLIB DD DSN=XYZ.COPE.LOAD,DISP=SHR<=ADD= // DD DSN=IMSVS.RESLIB,DISP=SHR //SYSPRINT DD SYSOUT=* //%POLDSDD DD DSN=%POLDSDS,DISP=SHR,DCB=BUFNO=20 //%SOLDSDD DD DSN=%SOLDSDS,DISP=SHR,DCB=BUFNO=20 //DFSSLOGP DD DSN=IMS130.SLDSP.%SSID.D%ARDATE.T%ARTIME, // V%ARVERS,DISP=(,CATLG),LABEL=RETPD=7, // UNIT=CART,VOL=(,,,99), // DCB=(BLKSIZE=32600,LRECL=32596,RECFM=VB,BUFNO=20) //COPEARCX DD DSN=TFTPROD.COPE.COPEARCX,DISP=MOD <=ADD= //COPECAPT DD DSN=TFTPROD.COPE.COPECAPT,DISP=MOD <=ADD= //SYSIN DD * SLDS FEOV(06642) EXIT NAME (ARCEXIT1) EXIT NAME (COPEARCX) <=ADD= /* Instead of adding the COPE load library on the STEPLIB, you could copy module COPEARCX into a STEPLIB library. If you are running Tasklib Switching, there is no performance benefit from program information capture (it saves loads for non-tasklib Switching). If you do not use /SIGN ON, the accounting information will not be so useful. You may want to write your own accounting archive exit, based on the COPEARCX module, in this case. COPE for IMS Administration Guide 93

94 You must point the DD(s) DISP=MOD to FB 80 sequential datasets (recommended BLKSIZE 23440). You must add the "EXIT NAME(COPEARCX)" to your current list of zero or more EXIT statements, which follow your SLDS statement, on SYSIN. You can point the DD(s) to temporary FB 80 datasets, that are then IEBGENER'ed DISP=MOD onto permanent datasets in subsequent steps. The advantage of doing this is that space abends will not eventually halt IMS (due to archive failure), because the archive step will always work. The Online IMS part of COPE creates record-type X'C0' log records, on the IMS Log. Type X'C001' are DLI trace records processed by the Call Trace Browse module, COPECTB1, and only the sub record type 'COPEPGM' will be used for accounting (for finding the Lsys name). Record types X'C002' are Program Information Online Capture records, which are processed by the archive exit to accumulate onto the COPECAPT sequential file, from where they will be read by Option 5.8 ("CAPTLOAD - Load Online CAPTURE FILE OF PROGRAM INFORMATION"). THIS CAPTURE load function updates the Modname and Dynamic Program Call information in the ISPF COPE tables. New STUBX's will then be generated, which will be picked up by Online IMS, and then the capture records will no longer be produced for those instances. The Capture Load ISPF function also "clears" the COPECAPT file, on successful completion, to release the space used by processed records. 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: Logon to Lsys 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 COPE LOGON TFT4 COPE LOGON TFT4 FROM USER69 COPE B.TFT4 Logs current user onto Lsys TFT4...same (LOGON can be omitted online) Logs USER69 onto Lsys TFT4 Logs user onto Lsys TFT4 in Psys B These commands can be issued from SYSIN statements to BMP COPEIMS3, see Option 5;LOGON for an example job. The logon command is the only processing that changes a user's logical system in USTDLMGR; no other COPE processing ever changes this value, except that the LOADJCL job from option 4.2.GS will reinitialize USTDLMGR, with all users logged off. COPE for IMS Administration Guide 94

95 To display a user's logon segment, use command from the COPE screen under IMS, as in this 'DFTI9S02' The quotes are necessary. The user's current Lsys is at +10 hex (+16 dec) in the resulting display. GE status means the user has never been logged onto an Lsys. Transmitted Lsys on Switch When an MPP or BMP "switches" a transaction to another MPP or BMP, the Lsys is passed on the end of the first segment by COPE. Applications will not see this Lsys name, because COPE strips it off at the time the application does a GU (Get Unique) for the switched message. Lsys transmission overrides Logon, except in the case of an MSC switch, where the destination Psys does not have the same Lsys name defined that the source Psys had. In that case, the user must be logged on (via a Psys.Lsys "remote logon" command) in the destination Psys to whatever Lsys the user wants to use. COPEBSYS DD Statement 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 nonmessage-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. Optional Features and Third-Party Product Support COMPUWARE Xpediter Support This section describes the steps necessary to set up the optional Xpediter support available in COPE. It is applicable only if the COPE Xpediter feature is present on your installation tape. Xpediter is an interactive COPE for IMS Administration Guide 95

96 debugger from Compuware corporation. It allows developers to set break points and examine variables for a program running in an MPP or BMP test region. Step 1. ZDEFAULT variables Set the following parameters in the ZDEFAULT member of the PROCS library. Refer to the COPE for IMS/DC Installation Guide for an explanation of ZDEFAULT parameters. Set XCOPEEXP to YES. Set XEXPUSER to the maximum number of simultaneous Xpediter users for a COPE Psys. Make this a reasonable value (extra transaction codes are generated later dependent on this value). Set XCOPEACD to the dataset name of the dynamic ACB library (DOPT library). Make sure that this library is in your Control Region, and DLI region, ACBLIBA and ACBLIBB concatenations. The DSN should end in ACBLIBD (recommended). It must have the same blksize as other ACBLIBs. Set XCOPEPSD to the dataset name of the dynamic PSB library (DOPT library). The DSN should end in PSBLIBD (recommended). It must have the same blksize as the non-dopt PSBLIB. Set XPLOAD to the Xpediter load library dataset name Set XPMENU to the Xpediter panels library dataset name Set XPSKEL to the Xpediter skeleton library dataset name Set XPMSG to the Xpediter messages library dataset name Step 2. IMSGEN Perform option B.4.2.XPSB and make sure that PSB ADSIM001 is excluded from COPE control. Perform option B.4.2.LDX and make sure that DBD XPIMSDBT is excluded. Edit your IMS security definitions, making sure that COPEXPT1 (and all other COPE transactions) have TCOMMAND * (can issue commands). If you have RACF or ACF2 (etc.) IMS security exits, or rules, make sure that they allow COPEXPT1 (and all other COPE-prefixed transactions) to issue commands. If you have RACF or ACF2 IMS security exits or rules, also make sure that your TSO users will be able to run all Cnnnnnnn transaction codes from their TSO regions. Run option B.4.2.GS and submit IMSGJCL and XREFJCL. This generates additional C-number DOPT PSB's and transaction codes, which are switched-to by COPE, for running the test transactions in the TSO regions. Step 3. Generate Dummy ACB's Run option B.4.8.FIX. This generates "dummy" ACB's for the Xpediter transaction codes, that are necessary so that these transaction codes will come up initialized to IMS. When the user runs an Xpediter test, their ACB will be copied over one of these (in the DOPT ACBLIB). Option B.4.8.FIX should be run after doing the PSB=ALL gen. for a new COPE Psys, or any time that an existing Psys has many transaction codes added to it. The latter case is necessary because in that situation additional Xpediter transactions might need to be available (the number of these is dependent on the total number of transactions). COPE for IMS Administration Guide 96

97 If a release change requires an ACBGEN, e.g. changing from release 3.1 to 4.1, the members in the Dynamic ACBLIB (ZDEFAULT parameter XACBLIBD) must be deleted and the B.4.8.FIX option run. This step is required, since the FIX option will not replace any ACBLIB member that already exists. Step 4. Xpediter Exits Enter 'DEF' on the primary Xpediter panel to access the Exit Routine definition panels. Fill in the "Exit Routines (2)" screen during Installation of Xpediter as follows if the TSO and IMS Xpediter features are installed. Figure 55 Xpediter Exit definition Fill in the "Exit Routines (2)" screen during Installation of Xpediter as follows if only the TSO (BTS) feature is installed. COPE for IMS Administration Guide 97

98 Figure 56Xpeditor BTS Exit Specification If the TSO feature only is installed, the IMS RESLIB name used by COPE must be included in the XPEDITER JOBLIB definitions. You can "piggyback" your own exit, panel or command onto the COPE exit, by putting its PGM, PANEL or CMD keyword, and its PARM keyword (or any other keywords), in the COPEXPP1 PARM, past the digit (01 to 12) and a blank, as in this example: ===> PGM(COPEXPP1) PARM(01 PGM(yourexit) PARM(yourparm)) Note that COPEXPP1 can be installed as a system-wide Xpediter exit, since it detects whether it is running under COPE, and does nothing if it is not. If this Xpediter system can be invoked outside COPE, you should either copy COPEXPP1 from COPE.LOAD to Xpediter LOAD, or copy and rename IEFBR14 to Xpediter LOAD, as member COPEXPP1. This is necessary because the COPE.LOAD library is not normally installed in your TSO or ISPF startup allocations. Step 5. XPX Clist Set up the invocation of Xpediter for your users, by editing CLIST member XPX, modifying it to name your Xpediter clist, tables, xoptions and xmessages datasets. This clist is invoked from COPE option B.7.4. XPX is the same as the Compuware-delivered Clist except that we removed ISPLLIB, ISPPLIB, ISPSLIB and ISPMLIB allocations (these are done at COPE initialization, using the ZDEFAULT variables). The reason for COPE for IMS Administration Guide 98

99 this is that if these allocations were done in the clist, some maintenance levels of LIBDEF give "bounce out" and "ISPF subtask abend" behavior. Step 6. Verify Install Go into IMS 1. Issue /DIS DB XPIMSDB command. If it is invalid, stopped or NOTINIT, correct the Xpediter install of this DBD, its exit, or database dataset 2. Issue /DIS PROG ADSIM001 command. If it is invalid, stopped or NOTINIT, correct the Xpediter install of this PSB 3. Go into TSO, in ISPF, and in COPE 4. Set your Sign on id or Lterm name on the option B.7 screen 5. Set your Lsys name on the option B.7 screen 6. Select 4 (i.e. option 7.4) to enter Xpediter 7. In Xpediter SE (Setup) put XCOPEPGM (STUBX Library) as one of your Loadlibs 8..In Xpediter SE (Setup) set XCOPEPSD (dopt PSBLIB) and XCOPEDBD (DBDLIB) in PSBLIB/DBDLIB concatenation. This is used for BMP tests that use Gsam. 9. In Xpediter SE (Setup) check the PARMs has the right IMSID 10. Run a test transaction in 2.8, using breakpoints, GO, etc. 11. Issue TSO UNLOCK command, if your transaction ends without replying to the IMS terminal (to unhang the terminal) 12. Go into COPE 6.2 to see your call Trace Note: Make sure your Xpediter users have a copy of the Xpediter section in the COPE for IMS/DC Programmers Guide. How to fix COPE Xpediter problems Problems occur if Xpediter is not installed correctly, IMS or RACF-type security is wrong, COPE Stubx's or Xrefs are not correctly generated, the user has not SEtup correctly, or the user has not entered the IMS transaction after the intercepts are set. The following are actions you should take when problems occur: IMS terminal hung, TSO not hung TSO UNLOCK from the Xpediter command line COPE for IMS Administration Guide 99

100 TSO terminal hung, IMS not hung In IMS, /DIS A, then /STO REG n Both IMS and TSO hung Either terminate the IMS session, or /RST NODE from another terminal, then /DIS A and /STO REGn. TSO waiting for Transaction The user probably did not enter the transaction. Proceed as follows: 1. Issue XP ALL command, note the Lsys and Transaction code for the user 2. COPE, note the Lsys in top line. If the Lsys is different, the user should logon to the correct Lsys by typing it in and hitting Enter. Then the user can run the transaction. Note that the user might have put the wrong Lsys in the ISPF COPE option 7 screen, before going into Xpediter, exit, correct and re-enter in this case. 3. TRACE LOGIC. Get the user to run the transaction. FLUSH. Go into option 7;2 to view the user's trace. Check the Transaction code. from the user's terminal. If this half word is zero, the user's intercept is not active (never set, or user QUITed). /DIS A, /STO REG n, and get the user to go into Xpediter again. You can display another user's XPOID 'signon'; then look at the halfword at +28 (hex). TSO gets bad Transaction The user has probably queued multiple transactions, and has lost track of which is what. Proceed as follows: 1. XP ALL and note all Xtran C-numbers 2. /DIS Q TRAN 3. /DIS TRAN xxxx (all the C-number Xtran transaction codes queued) 4. /ASS TRAN xxxx CLASS 1 (or whatever) to make these transactions run 5. /STA TRAN ALL 6. /STA PROG ALL 7. /DIS Q TRAN to check that there are now no queues, repeat above if any C-number Xtran tran codes queued. 8. /DIS A 9. /STO REG n for any TSO users running 10. The user can now go back into Xpediter. Make sure that they wait for "THE IMS TRANSAC- TION CAN NOW BE ENTERED", before entering the IMS transaction. Any transactions entered before the intercepts are set will not be intercepted and sent to the Xtran. TSO gets abends The user has probably not done a SEtup correctly. 1. STUBXs library (XCOPEPGM) must be in the user's Loadlibs 2. Use the correct Reslib (XCOPEIRS) 3. Use the correct IMSid (as in Ctl/Msg region parms) COPE for IMS Administration Guide 100

101 4. Use the correct user libraries TSO gets wrong program versions The user has probably not put the correct program libraries in SEtup Loadlibs. To see what version of a program, and the DSN of the library it is in, in IMS message regions, do a VERSION pgmname, from the COPE screen under IMS. If this is the version of the program you want under Xpediter, put its DSN in SEtup Loadlibs. IMS intercept still active The TSO user probably exited in some manner without going through Xpediter QUIT processing. On IMS: 1. XP ALL 2. XP QUIT n, where n is the intercept you want to quit. Other problems/messages Check the following: 1. Transaction code COPEDXPT1 has TCOMMAND*, and RACF or ACF2 security defined to enable it to issue /STA, /STO, /DIS and /ASS commands 2. The Xpediter PSB and DBD were excluded from COPE control, and IMSGENed, and ACB- GENed; do /DIS DB XPIMSDB, /DIS PROG ADSIM001; and the Xpediter compress routine is installed in the control region and DLI region steplibs 3. You did an option B.4.8.FIX to generate the Xpediter STUBX s 4. You installed COPEXPP1 as the Xpediter exit 5. rite down or screen print all messages, including any on the message region job logs, and call Compuware for support (phone number is on the first page of this manual). How Xpediter works with COPE The run-time support consists of the Clist, XPX, used to invoke Xpediter with COPE libraries present, and the program, COPEXPP1, which is called from the Xpediter exit points. The Clist gets control from COPE option 7.4, and invokes Xpediter in the normal way. When the user starts and ends each test, Xpediter gives COPEXPP1 control, at the exits. COPEXPP1 invokes a BMP, program name COPEUTP1, PSB name COPEXPP1 and transaction code COPEXPT1, passing the program/transaction codes the user entered on the panel. The BMP allocates special COPE Xpediter C-number Programs and Transaction codes (called "Xtrans"), for use by this user, and copies and renames the ACB from the current active ACBLIB to the Dopt ACBLIB. If this is a BMP test, it also copies and renames the PSB from PSBLIB to the Dopt PSBLIB (IMS needs this for Gsam). It also updates segments of USTDLMGR, that control the switching of the IMS transaction to the allocated transaction code, for this user (without affecting other users). The DB2 Schema Removal Feature COPE for IMS Administration Guide 101

102 Description of Feature When an application has a Table Schema (Schema name) coded in addition to the Table name, it is not possible for the application to access multiple versions of the table in a single DB2 subsystem. A COPE environment may use different DB2 subsystems for each Logical System but the arrangement is costly in terms of machine resources. Modifying application programs to remove Schemas (Schema names) is costly and prone to errors and would require retesting of many programs if DB2 is heavily used. The DB2 Schema Removal Feature scans DBRMs and removes or changes Schemas (Schema names) without changing the application programs. When an application is recompiled, the DBRM generated by the compiler can be processed by the a batch job step and Schemas removed before the BIND process is performed. The feature allows Schemas to be specified in application programs table names but implements a methodology that allows different versions of the application to access different DB2 tables in a single DB2 subsystem. The ISPF Foreground application Access to the DB2 Schema Removal Feature may be achieved by entering CONDBRM on the prime COPE panel. This menu will be displayed. Figure 57 DBRM Schema removal Menu Enter the name of the DBRM dataset to convert in the appropriate line. Also, enter a Logical System name. Introduction to the DB2 Schema Removal feature COPE for IMS Administration Guide 102

103 The feature consists of a ISPF application in which Schema tokens and their alternate values may be specified. DBRMs may be processed by the ISPF foreground application or in a Batch Job. The following steps implement the schema change/removal process. The first step (Command F ) translates the DBRMs to EBDIC and saves the results in a dataset. This step also identifies encoded Schemas and saves the results in a table for subsequent review. The encoded schemas may be reviewed with Command TR. Schemas are to be changed to a new value instead of removing them, The new value consists of a prefix token and a suffix token concatenated to it. Thus the schema name ABC may be changed to WXYLSYS1 where WXY is the schema prefix and LSYS1 is the schema suffix. i. The suffix token is defined with Command S. Each Lsys may have a single suffix token defined See S Define Substitute Schema Suffix by Lsys Command. ii. The prefix token for the substitute schema is defined with Command D. See D Define Substitute Schema Prefixes Command Schemas may be removed or changed (depending on whether substitute schemas have been defined) with Command A Command R allows a review of the operations performed by Command A (Strip Schemas). Additional commands are available Command ES allows editing of the DBRMs in the dataset specified on the panel. Command EC allows editing of the converted (striped) DBRM in the Converted Unicode dataset Command X deletes the Deleted/Substituted information Command TRX deletes the Extracted Table names and their Schemas. The F From UNICODE DBRM members to EBCDIC Command This option presents a selection list of members in the dataset defined on the panel and slows selection of them. If S * is specified all members will be selected. The application changes the DBRM contents to EBCDIC and extracts the Schema and their associated Table Names and saves them for review. The E Edit EBCDIC members Command Allows editing of the EBCDIC DBRM conversion. No Schema names have been changed TR Review Extracted Table Names and their Schemas Command COPE for IMS Administration Guide 103

104 An example of the review menu follows Figure 58 Extracted Schema and Table names from DBTM modules The member names, schema names and table names are shown. The data is generated by the F application. S Define Substitute Schema Suffix by Lsys Command An example of the S menu follows Figure 59 Schema suffix specification Menu The schema suffix substitution value may be changed from the default Lsys name value. COPE for IMS Administration Guide 104

105 D Define Substitute Schema Prefixes Command An example of the D menu follows Figure 60Schema substitution Prefix Token definition Menu On initial entry, the display will be blank. IMPORT should be specified in the command field to copy the extracted data from the F Option to the display. Schema names may be up to 128 characters. The display will only display the first 10 characters. To make a change in the ALTERNATE field UW (Unformatted Wide) or FW (Formatted Wide) should be entered in the Rcd column. An edit session will be entered in which data may be entered. A Strip Schemas from multiple members Command This Command displays the member list for the EBDIC converted DBRMs generated by the ;F option. S * may be entered to select all or individual members may be selected for their schemas to be removed or substituted. R Review Deleted/Substituted Schemas for members Command COPE for IMS Administration Guide 105

106 An example of the review menu follows. Figure 61 Review Deleted/Substituted Schema The example shows substituted and deleted schemas with their member names. BATCH DBRM Processing Option 1;4;9 generates an example job that will remove or change the Schemas in a DBRM. The step defined in the example job can be inserted. Before the conversion step is used, the CONDBRM COPE option must be used to extract the Schema and (optionally) define alternative names. Administration of ISPF Development Environment Introduction The COPE ISPF development environment consists of a set of utilities that allow various specialized operations to be performed. The utilities are mainly accessible from option B;5 Special Utilities and B;3 Utilities but also include options B;4.4 and B;4.6. A summary of the utilities follows: A brief overview of each of the Utilities is provided below, and a more comprehensive description of each utility follows: COPE for IMS Administration Guide 106

107 Utility DRAW SWAP Utility Description Presents diagram of Libset interrelations hips Allows selection of members from a member list Draw Libset Hierarchy Draw Libset Hierarchy Reference Option B;4;3 invokes the DRAW function which results in a display of Libset relationships and associated IMS systems. This can be useful for new users to understand the naming conventions used. Figure 62 LIBSET Hierarchy Diagram DEFAULT Allows definition of default parameters used in program JCL generation SWAP Select members from a member list (Option 4.14) Define Default Compile Parameters (Option B;4.5) COPE for IMS Administration Guide 107

108 JCLUPDA TE TBLUNLO AD TBRELOA D X-REF ORPHAN Used to modify any existing JCL specification s for compiling DBD's, PSB's or programs, with new parameters specified in the default JCL. A utility that unloads COPE ISPF tables to a sequential file. A utility that accepts unloaded table information and reloads it into the COPE system. Provides a cross reference listing of COPE internal names and the "user" module names that they reference. Scans all datasets for a COPE developmen t environment, and lists members that are not JCL Update of Compile Parameters (Option 5.2) Table Unload Utility (Option B;5.2) Table Reload Utility (Option 5.3)Table Reload Utility (Option 5.3) XREF C-numbers (Option 5.4) Orphan Delete (Option B;5.5) COPE for IMS Administration Guide 108

109 TABLES COMPILE FIXINDEX GENMFS X TFORMA T referenced by any COPE index. Optionally, the members may be deleted. Removes Orphans from the COPE system ISPF tables library. Generates JCL to allow DBD's, MFS, PSB's and application programs to be developed outside the COPE environment May be used to recover a destroyed COPE library index by copying from another related index Will regenerate the MFS translation table for the online IMS system. This table is normally automaticall y generated Removes obsolete entries from Remove Orphans from System Tables Library (Option B;5.6) JCL Interface for Imports and Compiles (Option B;5.7) Repair COPE Index (Option B;5.8) Regenerate a MFS X-Ref Table (Option B;5.9) TFORMAT/PSB/DBD/ACBLIB Member Delete Utility (Option B;5.10/11/12/13) COPE for IMS Administration Guide 109

110 PSBLIB DBDLIB ACBLIB PDSDIR DBD EXITS DUMP test format MFS datasets Removes obsolete entries from online PSBLIB datasets Removes obsolete entries from online DBDLIB datasets Removes obsolete ACBLIB members Removes incorrect PDS dataset member entries with TTR set to zero. This condition can occur as a result of system failure during update of the directory. Copy DBD Exit load module to a library (may also be done with import facilities) Dump COPE datasets to allow restoration TFORMAT/PSB/DBD/ACBLIB Member Delete Utility (Option B;5.10/11/12/13) TFORMAT/PSB/DBD/ACBLIB Member Delete Utility (Option B;5.10/11/12/13) TFORMAT/PSB/DBD/ACBLIB Member Delete Utility (Option B;5.10/11/12/13) Remove bad entries from PDS directory (Option B;5.14) Copy DBD Exit Load Modules to COPE (Option B;5.15) Dump/Restore COPE Datasets (Option B;5.16) COPE for IMS Administration Guide 110

111 MSDB/CO NV WIZARD AMBLIST DBDPUR GE CONVER T on another system Allows conversion of MSDB databases to use COPE DBDs. Initializes Wizard tables Invokes IBM Utility to display load module contents and structure Removes DBD definitions from the COPE Dictionary Convert external names to COPE internal names (Option B.4;9) Convert MSDB Databases (Option B;5.17) Perform COPE system table installation (Option B;5;99) AMBLIST to get Load Module Dates Remove duplicate and obsolete DBD entries (Option 4.10;12) Convert external names to COPE internal names (Option B.4;9) The last part of this section describes the "External Authorization Interface". If you are using this, you need to write your interface modules, install them in the COPE system load library, and set the "YNYNY" switches as appropriate in the ZDEFAULT member of the PROCS library. COPE for IMS Administration Guide 111

112 Draw Libset Hierarchy Option B;4;3 invokes the DRAW function which results in a display of Libset relationships and associated IMS systems. This can be useful for new users to understand the naming conventions used. Figure 62 LIBSET Hierarchy Diagram SWAP Select members from a member list (Option 4.14) Some COPE utilities (Such as the CHECK Utility (Option 4.11)) generate error lists of missing members. If imports have to be performed, the members must be selected from a member list. The process is very time consuming and error prone. The SWAP application allows a dataset containing a column of member names to be pointed to and commands issued on an alternate ISPF session (Initiated by the SPLIT command) An example of the SWAP application name list edit session follows COPE for IMS Administration Guide 112

113 Figure 63 SWAP command edit session example If a SPLIT session is initiated and a member selection list from a COPE application, (such as the import application) is displayed, the cursor may be positioned on the top left character of the column of names (in this example DBFSAMD4) and if SWAPSALL is entered in the Edit command field a set of SELECT commands will be issued for the application in the alternate session. This will result in all members in the above list to be selected. In addition to the SWAPSALL command a REMDUP command can be issued to remove duplicate entry names, and also SWAPDALL and SWAPFALL commands can be used to perform D(elete) or F(ind) commands on the alternate session. Define Default Compile Parameters (Option B;4.5) Compile parameters only apply to COBOL;ASSEMBLER;PL/1;DBD;PSB and MFS source. When a COPE system is installed, a set of default parameters are automatically defined. These parameters may be modified with Option B;4;6. Most installations will use this option to modify the DEVCHAR value for the MFS compile default A specific source member may require a different compile parameter from the global default. If this is required, Option B;2;4 may be used to override it Special Utilities Refer to "The COPE Special Utilities Menu" on page 30 for details on how to access the Special Utilities Menu. The following sections describe each option on this screen. JCL Update of Compile Parameters (Option 5.2) COPE for IMS Administration Guide 113

114 This utility is intended to automatically transfer default parameters specified with option B;4.6 to JCL that is associated with modules that can be compiled that have been already imported into the system. The situation should not arise if a careful review of the default JCL is made prior to importing and compiling application programs, DBD's, PSB's etc. However, instances may occur, (for example, when a new compiler is introduced) whereby the ISPF JCL generation skeleton requires a new parameter to operate in an environment. In this case, the parameter is entered with option B;4.6, and this utility is used to update all the copies of JCL that exist at any development level. (Copies are required since each application program may have specific overrides of the default parameters). Table Unload Utility (Option B;5.2) This utility is mainly used for preparing the installation distribution tape. The function of the utility is to access an ISPF table and transfer the contents to an unloaded format suitable for input to the Table Reload Utility (described below). In addition to the data contained in the table, the utility also outputs information as to the COPE index values that are required to access the table. If a user wants to define an entirely new environment for COPE, and does not wish to re-enter existing definitions, this utility could be useful. Figure 64ISPF Table Unload Menu There are two functions available in the utility: Specify the set of index values that COPE uses to access the table and name the unload specification set. Unload the tables that are named in an unload specification set. If the specification function is selected and the specification set name is left blank, a selection menu of existing specification sets will be displayed. If a specification set name is entered, a table edit application will be entered that will request four index variables to be specified for every table to be unloaded. COPE for IMS Administration Guide 114

115 The index values are: 1. Project name 2. Group name 3. Table type 4. Table name The Project/Group combination references a Libset. The value of '$' (currency sign) has a special meaning in the Project Group, and Table Name fields. In the Project and Group, a $ indicates a 'System' table (those tables that are not associated with a particular Libset). A '$' in the table name field denotes that the Index table controls the objects associated with the Libset Project/Group/Type values. The naming convention is similar to that used by ISPF to access a dataset. If the Unload function is requested, a previously defined Unload Specification Set name must be supplied or selected from a list of known names. The output dataset must be a sequential dataset of fixed block RECFM and LRECL of 80 bytes. Table Reload Utility (Option 5.3) This simple utility requires the specification of a partitioned or sequential dataset that contains data prepared by the unload utility. The controlling menu appears as follows, and is self explanatory: Figure 65 ISPF Table Reload Utility After entering option 'R' and specifying the dataset name, a list of unloaded members will be presented. One or more of the listed members may be selected for reloading to the ISPF tables library. COPE for IMS Administration Guide 115

116 XREF C-numbers (Option 5.4) In order to avoid synonyms and homonyms, COPE assigns unique names DBD's, PSB's, application programs and MFS members. For convenience in debugging, a cross reference table is maintained of all renamed information. If no table has been generated a JOB will be displayed for submission on entry for the first time. If a XREF table exists the initial selection menu that is presented is as follows: Figure 66 X-Reference Selection Menu COPE for IMS Administration Guide 116

117 The panel that is displayed when the X-Reference for PSB's Option is selected is as follows: Figure 67 X-reference PSB Menu Orphan Delete (Option B;5.5) Figure 68 Orphan removal menu The COPE system keeps track of all datasets in all Libsets and has internal indexes to all members and alias names. An orphan is a member that is not referenced by any COPE index. An orphan can be valid if the dataset is being used to store modules that are not associated with COPE. Certain failure conditions, however, can cause COPE for IMS Administration Guide 117