For new COPE users, installation consists of two parts, product installation and system setup. Product installation is normally performed only once for each release of COPE while system setup may be performed multiple times depending upon the IMS configuration at your site.

Tasks

The tasks required to perform product installation are shown in Product Installation Checklist, which you may use as a checklist as you perform the installation.

The initial system setup/administration tasks are shown in Tasks to generate a COPE System, which you may use as a checklist as you perform these tasks:

XCOPE1 Base runtime library prefix (for example, {hlq}.COPE)

XCOPE2 User modification library prefix (for example, {hlq}.COPEUMOD):

 Product Installation Checklist

Task 4.1 Run Library Allocation Job

1. Modify member IMALUMOD in the xcope1.JCL library.

   Warning

   Note

   If you want the CLIST dataset to be a Variable Blocked dataset (VB), change the allocation of the xcope2.CLIST dataset to VB.

2. Submit modified member IMALUMOD.This job will allocate COPE user datasets.
3. After this job completes successfully, copy member IMALUMOD from the xcope1.JCL library to the xcope2.JCL library.

Task 4.2 Allocate IMS Libraries (Optional)

COPE requires APF-authorized load library dataset(s) for some of its programs and for dynamic allocation members. Either use existing APF-authorized dataset(s) or allocate a new one(s). The recommendation is to create a new PDS for these purposes and to use it for both the COPE APF load library and the library for dynamic allocation members. The DCB attributes should be the same as that for the IMS.SDFSRESL dataset.

At a later point in the installation process when customizing parameters for COPE, the corresponding parameter names are:

• XCOPEAUT (APF-authorized program library)

• XCOPEDYN (Dynamic allocation library that needs to be APF-authorized)

  Warning

  Note

  We recommend that you the same library for both XCOPEAUT and XCOPEDYN.

You can use existing IMS libraries or allocate new ones for the following datasets:

• PSBLIB
• DBDLIB
• DOPT PSBLIB (only required if using Xpediter with COPE)
• DOPT ACBLIB (only required if using Xpediter with COPE)

Task 4.3 Specify an Adequate TSO Region Size

The ISPF facilities of COPE require a minimum TSO region size of 64 megabytes. If the TSO region size is inadequate, some ISPF COPE facilities may give program fetch or other errors. Make sure that the TSO logon procedure of any user who will be accessing COPE specifies a region size of at least 64M, or that each such user is authorized to increase his or her TSO region size on the logon entry screen.

Task 4.4 Add DB2 SDSNLOAD Dataset to TSO Region (DCCTL Users only)

In a DCCTL environment, COPE option 6.1 (Commands) requires the DB2 SDSNLOAD dataset to be in the TSO STEPLIB DD. You can alternatively execute a logon CLIST that contains:

ALLOC DD(TASKLIB) DA('DB2.SDSNLOAD') SHR

Task 4.5 Allocate the COPE System Tables Dataset

1. Copy Member ALLOCTBL from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member ALLOCTBL according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member ALLOCTBL.
   This job will allocate a dataset to contain internal tables used by the ISPF component of COPE. The low-level index of the dataset name must be .TABLES. This dataset will be referred to throughout the documentation as the system tables dataset. The system tables dataset will be initialized in  Perform Initial Entry to COPE .

Task 4.6 Customize COPE System Parameters

COPE Psys

COPE allows multiple versions of application systems to run under a single IMS control region. Each of the multiple versions is called a logical system or Lsys, and the IMS control region they share is called a COPE system or a Psys. A one-to-one correspondence exists between a COPE Psys and COPE- managed IMS control regions.

One or more members of the user-modification or distribution/runtime PROCS library consists of a set of parameter specifications known as COPE system parameters. A Psys is associated with a unique parameter specification member, which is known as the parameter member for the Psys. The member name is also the name of the Psys. The PROCS distribution/runtime library member, ZDEFAULT for DB/TM and DCCTL environments or ZDEFCICS for DBCTL environments, contains a default set of parameter specifications from which the system parameter members can be customized. Create and customize one copy of ZDEFAULT or ZDEFCICS for each Psys you build.

Task 4.6.1 COPE System Parameter Customization

To create the system parameter member for a new Psys, copy the ZDEFAULT (DB/TM and DCCTL environments) or ZDEFCICS (DBCTL environment) member to the user modification PROCS library (xcope2.PROCS), if you allocated one, or to the distribution/runtime PROCS library if not, renaming the member to the chosen Psys name when copying it. 

Once you have copied the member customize the parameters in it as appropriate for your environment

A parameter member consists of )CM statements and )SET statements. You may modify the )SET statements by changing the values after the equals (=) sign, according to your installation's needs.

The )CM statements are comments and do not need modification. However, you are free to modify existing comments or to add your own. For definitions and explanations of the parameters, see COPE System Parameters and then enter the new values in the parameter member for the Psys you are building.

Task 4.6.2 The COPEVARS and COPETOOL Members (DB/TM and DCCTL only)

Copy members COPEVARS and COPETOOL from the distribution/runtime xcope1.PROCS library to the user modification xcope2.PROCS library, using ISPF option 3.3 to perform the copy. Note the following important points:

Task 4.6.3 The COPEDBCT and COPETOOL Members (DBCTL only)

Copy members COPEDBCT and COPETOOL from the distribution/runtime xcope1.PROCS library to the user modification xcope2.PROCS library, using ISPF option 3.3 to perform the copy. Note the following important points:

Task 4.7 Allocate Online and Authorized Libraries

During ISPF initialization, COPE checks for the presence of IMS datasets, whose dataset names are specified in the COPE system parameters.

1. Copy member ALLOCIMS from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member ALLOCIMS according to the comments in the job for required changes in the xcope2.JCL library.
3. Submit modified member ALLOCIMS from the xcope2.JCL library. This job will create the COPE staging (hlq.STUBXLIB) and PGMLIB (hlq.PGMLIB) datasets.

Task 4.8 Allocate the Dialog Manager Database (DB/TM and DCCTL with YED only)

1. Copy member ALLOCDLM from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member ALLOCDLM according to the comments in the job for required changes in the xcope2.JCL library.
3. Submit modified member ALLOCDLM from the xcope2.JCL library. This job will allocate the dataset that will become the Dialog Manager database.

The Dialog Manager database itself will be defined and loaded later.

Task 4.9 Establish ISPF Access to COPE System

In this step you enable users to access COPE by selecting an ISPF menu option. Alternatively, if you prefer not to modify an ISPF panel at this time, you may provide access to COPE by means of a CLIST which can be executed via the TSO EXEC command. Though easiest for product evaluation purposes, this technique is not recommended as a permanent approach because it requires that the CLIST name be remembered by each user and does not provide the descriptive information that would be available on an ISPF panel.

To use either approach, copy distribution/runtime xcope1.CLIST library member COPESELX  into a CLIST library accessible to COPE users under TSO, renaming the member to any desired name as you copy it.

COPESELX is shown in the following example. The lowercase items must be modified using the information defined below.

COPESELX CLIST

1. Set ‘<parameter-member>’, the operand of the ZDEFAULT parameter, to the Psys name. This will be the member created in Task 4.6.1 COPE System Parameter Customization.
2. Set ‘<procs-dataset>’, the operand of the PROCLIB parameter, to the dataset name of the USER PROCS library containing the parameter member you customized (xcope2.PROCS).
3. Change ‘<load-distlib>’, the operand of the INITLIB parameter, to the dataset name of the LOAD distribution/runtime library (xcope1.LOAD).
4. Change ‘<clist-distlib>’, the operand of the DATASET parameter, to the dataset name of the CLIST distribution/runtime library (xcope1.CLIST).
5. Change ‘<ispf-appl>’ the operand of the APPL parameter, to the desired profile pool name for the COPE system. When providing access to multiple COPE systems, you must make sure that each COPE system uses a different ISPF profile pool by means of the NEWAPPL parameter. We recommends that you specify a profile pool name that can easily be associated with the COPE system you are defining.

Providing Menu Access to COPE

To provide menu access to COPE, perform the following steps:

1. Locate the panel to modify.
   First, determine the member name of the panel you want to modify by entering the PANELID command when the desired panel is displayed. The member name will appear in the top left-hand corner of the screen. To remove the panel name, enter the PANELID OFF command.
   Then determine the dataset from which the panel is being retrieved by entering the following in the command field of any ISPF panel:

   TSO EX '<xcope1>.CLIST(LOOKFOR)'

   You will be prompted to enter a member name and a DDname. For the member, specify the panel name determined above; for the DDname, specify 'ISPPLIB'.

2. Support COPE fast-path processing. Next, insert the following statements to the panel processing section in front of the &ZSEL= statement that is already in the panel:

   &A=TRANS ( TRUNC(&ZCMD,'.') *,*)
   &NEXTOPU=.TRAIL
   IF (&NEXTOPU = '')
   &NEXTOPU='@'

3. Add a select option to the panel processing section. Insert the following statements after one of the selection definitions already in the panel you have chosen, replacing the lowercase items as indicated in the guidelines following:

   <opt>, 'CMD(<new-copeselx-name>)'
   Change <opt> to the menu option the user must enter to access the COPE Psys you are building.Change <new-copeselx-name> to the name you gave to COPESELX when you copied it.

4. Include the new option in the panel display.
   Include a line such as the following inserted at an appropriate place in the display section of the panel. Replace <opt> with the same value you specified in the previous step, and change <mnemonic> and <option-description> as desired.
   % <opt> +<mnemonic> - <option-description>

Example of ISPF Access to COPE

An example showing COPE menu access is provided in xcope1.MENUS library member ISPFCMOD.

Task 4.10 Perform Initial Entry to COPE

Enter COPE using the method established in the previous step. The first time you enter COPE after installation, a screen is displayed asking you to confirm system table dataset initialization. The system tables dataset must be initialized before any other COPE processing can be done, so you should press <Enter> to begin. A dynamic display indicates the progress of the initialization.

Each entry to COPE also causes the system parameters to be validated. A variety of messages may be issued by the validation routines depending upon whether you are a new or existing user, whether this is the first or a subsequent entry to COPE, and whether parameter validation was successful. Any dataset referenced in the system parameters must exist. Watch carefully for messages that seem to indicate an error condition.

When the message Press <Enter> to continue appears, scroll through the dynamic message display to determine whether any problems were encountered by COPE. Note any error messages that appear to require corrective action and fix any problems, contact Customer Solutions if you are not certain what to do. Finally, press <Enter>. If COPE now terminates and you are returned to the panel from which you entered COPE, verify that the problems indicated by the earlier messages have been corrected by reentering COPE.

Continue taking appropriate action for any initialization message issued by COPE until you can reach the COPE primary main menu without the issuing of any messages. When you have successfully done so, continue with the rest of the installation process as described below.

If you bring up this COPE ISPF menu again in this same dialog session, the error messages will be suppressed. If you log off and back on, the messages that have not been resolved will appear.

Upon successful validation of the parameters, follow the prompts as shown on the following screen. Press Enter as indicated to proceed.

Install COPE System Tables Screen

Task 4.11 Generate the COPE DBD (DB/TM and DCCTL only)

ISPF-like services in the online IMS environment are provided by the COPE Dialog Manager. In this step, you will install the components of this Dialog Manager. The Dialog Manager database itself will be loaded later as described in the BMC-COPE-Administration-Guide.

The COPE Dialog Manager uses a single database with a DBD named USTDLMGR. The source for this DBD is found in the xcope1.DBDSOURC distribution/runtime library.

1. Copy member USTLDLMGR from the xcope1.DBDSOURC library to the xcope2.DBDSOURC library.

2. Edit member USTDLMGR in the DBDSOURC distribution/runtime library and adjust the third sub-parameter of the RMNAME parameter. The value should be about four times the maximum number of terminals that will be connected to the COPE IMS control region but not less than 60.

   Warning

   Note

   1. The minimum of 60 is required because there will be control segments loaded that are not related to the number of terminals.
   2. If you have many terminals and are concerned about the size of this database, count only terminals that will actually log on to COPE. The RMNAME parameters other than the third are not critical and should be left as they are.
   3. In a DCCTL environment the information is stored in a Db2 table, but COPE requires the USTDLMGR database be set up.
3. Copy member DBDGEN from the xcope1.JCL library to the xcope2.JCL library. 
4. Modify member DBDGEN according to the comments as appropriate in the xcope2.JCL library.

5. Submit modified member DBDGEN.
   This job will assemble and link the DBD into the DBD library whose dataset name you specified as the value of the XCOPEDBD system parameter. Refer to the system parameter member (PSYS) in the xcope2.PROCS dataset.

   Warning

   Note

   This job compiles a DBD that is never used in a DCCTL environment, but its presence is required for batch initialization of COPE jobs.

Task 4.12 Generate COPE PSBs

For DB/TM:

1. Copy member PSBGEN from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member PSBGEN according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member PSBGEN.
   This job will generate the COPE supplied PSBs into the PSB library whose name you specified as the value of the XCOPEPSB system parameter (Enter EVARS on the COPE Development System menu to see what was specified). No modifications to the PSBs themselves are necessary. Refer to the system parameter member (PSYS) in the xcope2.PROCS dataset.

For DBCTL:

1. Copy member DBCTLPSB from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member DBCTLPSB according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member DBCTLPSB.
   This job will generate the COPE-supplied PSBs into the PSB library whose name you specified as the value of the XCOPEPSB system parameter (Enter EVARS on the COPE Development system menu to see what was specified). No modifications to the PSBs themselves are necessary. Refer to the system parameter member (PSYS) in the xcope2.PROCS dataset.

If using the DCCTL YED option, do the following:

1. Copy member PSBGEN from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member PSBGEN according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member PSBGEN.
   This job will generate the COPE-supplied PSBs into the PSB library whose name you specified as the value of the XCOPEPSB system parameter (Enter EVARS on the COPE Development system menu to see what was specified). No modifications to the PSBs themselves are necessary. Refer to the system parameter member (PSYS) in the xcope2.PROCS dataset.

For DCCTL:

If not using the YED option, do the following:

1. Copy member PSBDCCTL from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member PSBDCCTL according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member PSBDCCTL.
   This job will generate the COPE supplied PSBs into the PSB library whose name you specified as the value of the XCOPEPSB system parameter (Enter EVARS on the COPE Development system menu to see what was specified). No modifications to the PSBs themselves are necessary. Refer to the system parameter member (PSYS) in the xcope2.PROCS dataset.

Task 4.13 Generate COPE MFS members (DB/TM and DCCTL only)

1. Copy member MFSGEN from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member MFSGEN according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit the modified member MFSGEN.
   This job will generate the MFS for COPE. No modifications to the MFS members themselves are necessary. A return code of 4 or less is expected from this job.

Task 4.14 Set Up IMS Regions

Task 4.14.1 Review Sample JCL for COPE Regions (DB/TM and DCCTL only)

Examine the following sample members found in the xcope1.JCL distribution/runtime library: Make changes to the IMS system that COPE will use based on the examples.

JCL members for COPE Regions

Review the following considerations:

1. In the DB/TM environment, 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 your DBDs, and your PSB pool to hold at least one PSB per message region. COPE PSBs 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 and MODBLKSA/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, and MODBLKSA/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 because 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 must be an authorized library containing COPERC00. The dynamic allocation load library, DYNLOAD, is recommended. 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. Put the XCOPEPGM library (which contains COPE's STUBXs) and the xcope1.LOAD library (the COPE software) at the top of the COPESTEP DD. Next, put libraries that are common to all Lsys's on the COPESTEP. for example, the COBOL run library, RESLIB, etc.
7. The COPE ISPF option 1.5 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 z/OS; a STEPLIB is in fact a TASKLIB (of the topside task). COPE uses the z/OS TASKLIB feature in the same way as other systems, for example, ISPF and its ISPLLIB.
8. Check that you use the same RESLIB in all regions' JCL. Mismatched IMS system modules in different RESLIBs will cause IMS waits or loops.
9. Add a COPEMENU DD to the message region JCL pointing to your xcope1.MENUS and xcope2.MENUS libraries (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 as described in the BMC-COPE-Administration-Guide. It is especially useful to set up PF Keys that are meaningful for users at your installation, and this is very easy to do.
10. Add COPEJCL DD pointing to xcope1.JCL. This is used for submitting JCL, for SUB, BACKUP and RESTORE commands.
11. If you get COPEMFSX missing messages, perform COPE ISPF option 4.7 (4.MFS).
12. 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 T, and then regenerating it. For instructions on how to do this, refer to the BMC-COPE-Administration-Guide. This conversion is required because COPE changes the PSB name to an internal C-number.
13. The SSM member should be defined and appropriate PROCLIB definitions made.
14. Make sure that the supplied PSBs, DBD and MFS formats are generated. Entering ‘COPE ‘ (note the space after COPE) from a cleared IMS screen after you are connected to the physical IMS system will bring up the main COPE IMS 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.
15. 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 COPEscreen. These facilities are described in the BMC-COPE-Programmer-s-Guide.

User applications are ready at this point. The Lsys identifying tokens are in the JCL and Batch jobs executed.

Task 4.14.2 Set Up JCL for DBCTL Regions (DBCTL only)

1. Copy the sample members from the xcope1.JCL dataset to the appropriate IMS/System procedure library and modify them as appropriate:
   

   • COPECTL

     Warning

     Note

     The addition of the COPEPGM DD card specifying the library defined in the XCOPEPGM parameter of the ZDEFCICS member. For more information, see Task 4.6.1 COPE System Parameter Customization.

   • COPEDLS
   • COPEDBRC
2. Update the JCL and control cards to appropriate libraries for running the DBCTL system.

Task 4.14.3 Check Buffer Pool Specifications (DB/TM only)

Sample buffer pool specifications are given in JCL distribution/runtime library member DFSDF000. The specification for 22K buffers is required for the COPE Dialog Manager database. All other statements are subject to your site requirements.

The COPE USTDLMGR database requires a large buffer. The IMS environment parameters are specified in the DFSPBxxx member (where the 3-character suffix is in the control region JCL) In it, the DFSDF statement specifies the suffix of a DFSDFxxx PROCLIB member. This member must contain the statement

This statement ensures buffers are available for accessing the USTDLMGR database.

Task 4.14.4 Check Message Region Preload Specifications (DB/TM and DCCTL only)

A sample message region preload list is given in the xcope.JCL distribution/runtime library member DFSMPL00. The preload of DMLOGIC, COPEUTP1, COPEINP1, COPEKYP1, COPEYRP1, and COPEYRP2 are required; all other modules in the example are optional.

Task 4.14.5 Ensure Proper Class for COPE Trancodes (DB/TM and DCCTL only)

The four COPE Trancodes use class 5 as a default. Therefore, specify class 5 as one of the eligible classes in the message region parameter. Alternatively, you can change the COPE transaction class to a value other than 5 using option COPE 1.7 (Define Excluded (Not Modified by COPE) Databases and Transactions).

Task 4.14.6 Set AOIS Parameter

Set the IMS parameter correctly to allow ICMD/GCMD programs to operate. Typically, AOIS=S allows unrestricted calls. This is not the default value.

Task 4.14.7 Set BMPUSID to USERID (DCCTL only)

In your IMS DFSDCxxx member, set BMPUSID to USERID. This allows COPE-generated batch jobs to run with the RACF of the user who submitted the job instead of attempting to run under the default PSBNAME RACF, which would require the C#’s having permission entries.

Task 4.14.8 Check Online Datasets

You must check the sizes of the datasets used by the online message regions and control region. They were allocated during the COPE installation process.

The formulas given in this section are in 3380 cylinders. Adjust for other device types.

Determine the approximate values of the variables below by examining the program, PSB, DBD, and ACB libraries in your current  system(s), and allowing for replication to create new logical systems. The following table lists the variables.

Allocation Variables

Minimum sizes, a recommended placement and the DSN in terms of the ZDEFCICS variables are in the following table.

Allocations for Online Datasets

The following conventions are strongly recommended:

1. All of the above DSNs have a 2-level prefix that is the same as the XCOPEONL variable, within a given COPE Psys.
2. This prefix should have the 4-character IMSID of the physical IMS (Psys) as the second level.
3. This 2-level prefix should not correspond to any <Project>.<Group> of any libset, because these datasets are cross-libset.

Task 4.15 Copy Modules to Authorized Library

You must copy certain COPE load modules to APF-authorized libraries. Accomplish this by the following:

DB/TM and DCCTL:

1. Copy Member AUTHCOPY from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member AUTHCOPY according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member AUTHCOPY.
   This job copies the modules to APF-authorized libraries.

DBCTL:

1. Copy Member AUTHDBCT from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member AUTHDBCT according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member AUTHDBCT.
   This job copies the modules to APF-authorized libraries.

Task 4.16 Install IMS Exits

The COPE AOI exits, DFSAOUE0 and DFSAOE00, must be placed in the IMS RESLIB (SDFSRESL) by the COPEEXIT job. If MAINVIEW is present, use the COPEMAIN job JCL instead of the COPEEXIT job and follow the instructions in the comments.

1. Copy the appropriate member (COPEEXIT or COPEMAIN) from the xcope1.JCL library to the xcope2.JCL library.
2. Modify as appropriate.
3. Copy members COPEAOI and COPEBCMD from the xcope1.JCL library to the xcope2.JCL library.
4. Modify member COPEAOI and COPEBCMD in the xcope2.JCL library as appropriate.
5. Submit the job.

These jobs copy the exits to the IMS RESLIB and also Batch JCL for a AOI started job (COPEAOI) and a job that can issue commands to COPE (COPEBCMD). Examine the contents of COPEAOI and CIOPECMD and update them as appropriate for your environment.

The DFSAOE00 exit translates the database or program name to the correct internal COPE name depending for the Logical System noted in the LSYS parameter. The translated command is shipped to the COPEAOI job, which issues the command to IMS. If this facility is not needed, the COPEAOI JCL may be ignored.

If there will be multiple physical IMS COPE control regions in an LPAR, copy PROC COPEAOI changing the name to COPEimsid and add the following DD to the control region JCL which will result in starting up PROC COPEimsid:

COPE provided IMS exit modules DFSAOUE0 and DFSAOE00 both call module COPEAOUE.  COPEAOUE contains a   message suppression list. You can modify the message-suppression list, at label SUPPLIST in COPEAOUE, if you so desire.

The COPEBCMD xcope1.JCL member is an example of a BMP which can read a SYSIN file of commands and issue them to IMS after translating them to contain the correct COPE names for databases and programs.

Task 4.17 Install the Trace Archive Feature

COPE Trace records can be generated by issuing a TRACE ON or TRACE ON NOTRUNC command from the COPE transaction running under IMS.

The trace records are captured and placed on the OLDS datasets when a COPE FLUSH command is issued at the end of a test session. The records may be reviewed with an editor under ISPF by using the COPE Option 6.2, Trace Display application. This application reads the OLD datasets and extracts the trace records for a user-specified period.

The OLDS datasets are reused by IMS during normal operation. The trace records generated by a testing session are not available after reuse. The reuse period depends on factors such as the size of the OLDS datasets and the volume of work that is performed by IMS.

The Trace Archive Feature saves the COPE trace records so that they are available after the OLDS dataset they were stored in has been overwritten.

The number of days that trace records are saved is specified by an installation parameter.

The installation of the COPE Trace Archive Feature requires modifying the IMS ARCHJCL PROCLIB member. This member is tailored by the IMS GENJCL process to unload an OLDS that has filled up and extract and store recovery records and put them onto permanent storage.

Instructions on how to tailor the IMS ARCHJCL member for adding the COPE Trace Archive Feature are contained in the ARCHOLDS member of the xcope1.JCL dataset.

Task 4.18 Set up CICS (DB/TM Optional and Required for DBCTL)

If the CICS DBCTL interface will be used, perform the following tasks:

Task 4.18.1 Assemble CICS Programs

Three programs that run under CICS are supplied with COPE. These programs must be assembled and link-edited to ensure that they match the maintenance level of your CICS system. If you are running more than one level of CICS, you will need to assemble the programs for each CICS release and make the correct modules available in the DFHRPL concatenation for each CICS region.

Follow these steps to accomplish this:

1. Copy member CICSCSD from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member CICSCSD according to the comments in the job in the xcope2.JCL library.
3. Submit the modified CICSCSD job (A return CODE  of 4 in the LKED steps is expected).

Task 4.18.2 Assemble CICS CSD

The CICS CSD must be updated to define the COPE programs to be used in the CICS Region:

Follow these steps to accomplish this:

1. Copy member CICSCSD from the xcope1.JCL library to the JCL library.
2. Modify member CICSCSD according to the comments in the job in the JCL  library.
3. Submit the modified CICSCSD

Each Lsys has a separate load module for translating DBD and PSB names. The load module has the same name as the Lsys and must therefore be defined in the   CSD.

Task 4.18.3 Define or Modify the CICS PLT Startup (PLTPI) Definitions

For CICS releases prior to CICS Transaction Server for z/OS V5.5, do the following:

1. Copy member DFHPLT1 from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member DFHPLT1 according to the comments in the job in the xcope2.JCL library.
3. Submit the modified DFHPLT1 member.

Most installations will have an existing PLT defined. Add a new specification for the COPEREFR program to execute in the third phase of the PLT initialization.

For CICS Transaction Server for z/OS releases V5.5 and more current, CICS reads PLTs directly from source and no longer need to be Assembled. It must be available to CICS at run time, including any COPY members it referenced. For this, either place the source in a PARMLIB member that is part of the IPL PARMLIB concatenation, or add the following DD card DFHTABLE into the CICS startup JCL that points to the PLT source:

The following steps are needed for CICS Transaction Server for z/OS V5.5 and more current to accommodate this:

1. Ensure COPE PTF IMA098A is installed.
2. Copy member IMPLTSRC from the xcope1.JCL library to the xcope2.JCL library.
3. Modify member IMPLTSRC according to the comments in the xcope2.JCL library.
4. Rename IMPLTSRC to DFHPLTxx and point your DFHTABLE DD to it in the CICS region JCL.

Most installations will have an existing PLT defined. Add a new specification for the COPEREFR program.

Task 4.18.4 Update CICS Region JCL

Add the following to the CICS Region JCL:

1. A COPEBSYS DD card (Note 1).
2. Add the COPE Installation load library datasets (xcope1.LOAD and xcope2.LOAD) to the DFHRPL concatenation.
3. Add the dataset specified in the XCOPEPGM COPE variable to the DFHRPL concatenation.
4. For CICS Transaction Server for z/OS V5.5 and more current, be sure to add the DD described in Task 4.18.2 if appropriate.

Note 1:

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:

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.

An alternate form of specification can be used if multiple CICS regions are used.

In this case, the dataset name specifies the default Logical system as the last part of the name. The second to last part specifies the name of the PDIR table used in the local CICS system. The last two characters following DFHPSB represent the suffix of the PDIR implemented in the system. This information is required by the XDLIPRE exit that COPE supplies to determine if translation is required when function shipping is being used.

Task 4.18.5 Add Support of CICS DOR and AOR

If CICS Data Owning Regions (DOR) are used, environments may exist where some DL/1 calls are serviced in the Application Owning Region (AOR) and some are shipped to one or more DOR regions. This configuration is supported by COPE. The COPEBSYS DD card must be specified as a permanent dataset name with the following format:

In the above example, the prefix is any valid dataset name prefix that the installation chooses. The last two tokens on the dataset consist of the PDIR name in the AOI region, for example, DFHPSB01, followed by the Logical system name.

A typical specification would be:

Task 4.19 COPE SPOC Feature (Optional) and COPE DRD Feature (Optional)

Description of the COPE SPOC Feature

COPE provides an exit that allows the IMS ISPF SPOC (Single Point Of Control) application to translate Program and Database names by Logical System.

Instead of entering:

You may enter:

The program name PSBDBN is automatically translated to the COPE C-number name for Logical System DBT1. If the LSYS parameter is omitted, the command is expanded to show all the Logical Systems programs which are named PSBDSN.

In addition to translating the input, all command responses are also translated to show the COPE C-number names together with the non-COPE application names.

Tasks Required to Implement the COPE SPOC/DRD Feature

• Task 4.19.1 IMS SPOC Setup
• Task 4.19.2 Update Parameters in the ZDEFAULT Member of COPE
• Task 4.19.3 Copy COPEOM to IMS Libraries
• Task 4.19.4 Update the OMPARM
• Task 4.19.5 Update the OM JCL Procedure to the System PROCLIB
• Task 4.19.6 Update the BPECFG member
• Task 4.19.7 Add the Exit Definition Member to the PROCLIB
• Task 4.19.8 Enable DRD feature

Task 4.19.1 IMS SPOC Setup

Set up SPOC environment as required by IMS. See the appropriate IMS documentation to implementation of SPOC.

Task 4.19.2 Update Parameters in the ZDEFAULT Member of COPE

The parameters involved with the implementation of the COPE SPOC feature may be modified by entering EVARS on the prime ISPF COPE panel.

Once the EVARS variables are updated, run the jobs created by COPE ISPF option 1.6, 1.10, and 4.6.

The parameters are listed in the following table:

ZDEFAULT Parameters 

Task 4.19.3 Copy COPEOM to IMS Libraries

Copy the member COPEOM from the COPE LOAD distribution/runtime library to the IMS RESLIB. This module is required by the OM (Operations Manager) application. Update parameters in the ZDEFAULT member of COPE.

Task 4.19.4 Update the OMPARM

1. Copy member OMPARM from the xcope1.CTLCD library to the xcope2.CTLCD library.
2. Modify member OMPARM according to the comments it contains in the xcope2.CTLCD library.

In this example the COPEPARM member (OMPARM) is as follows:

As single Operations Manager (OM) may service several Plex arrangements. The PLEX name and routing names of each COPE IMS system must be specified (Note the spelling of ROUT).

For every ROUT specification, a separate DD card with the same file name must be added to reference the COPE PGMLIB (XCOPEPGM ZDEFAULT name) for that system. See Task 4.19.5 for an example of these DD statements.

Task 4.19.5 Update the OM JCL Procedure to the System PROCLIB

Update the OM procedure by adding the COPEPARM DD statement. An example of this member follows:

The standard procedure is modified by the addition of the COPEPARM statement and by the addition of files referencing COPE PGMLIB datasets. See Task 4.19.4 for description of DBT1 and DBT2 DD  statements

Task 4.19.6 Update the BPECFG member

The BPE member specified by the BPECFG parameter must be modified to include the following statement:-

An example of a complete BPE member follows:

Task 4.19.7 Add the Exit Definition Member to the PROCLIB

Create a new member name  COPEOM in  the IMS PROCLIB dataset. The contents are as follows:

Task 4.19.8 Enable DRD feature (Optional)

To enable COPE DRD feature, follow the below steps:

1. Ensure to complete tasks from  4.19.1  to 4.19.7, because COPE SPOC feature is the prerequisite for COPE DRD feature.  
2. Enable DRD in the IMS environment. For more information, see IMS documentation to implement DRD feature.
3. The parameters involved with the implementation of the COPE DRD feature is modified by entering EVARS on the prime ISPF COPE panel. 

The ZDEFAULT parameter, XDRDUPDT must be set to YES. Once the EVARS variable is updated, run the jobs created by COPE ISPF option 1.6, 1.10, and 4.6.

Task 4.20 IMS Catalog Feature (Optional)

If the IMS Catalog feature is not being used, set the ZDEFAULT (DB/TM) or ZDEFCICS (DBCTL) parameter XCOPESDF to &Z.

If the IMS Catalog Feature is desired, set the ZDEFAULT (DB/TM and DCCTL) or ZDEFCICS (DBCTL) parameter XCOPESDF as follows:

1. Set XCOPESDF to the 3 numeric digit suffix of the DFSDFxxx member referenced by the DFS3PU00 catalog update program.
2. Set XIMSCAT to YES.
3. Set XCATHLQ to the high-level qualifier for the IMS Boot Strap Dataset.

Task 4.21 LTERM Key (Optional – DB/TM and DCCTL only)

COPE has the option to use the LTERM name as the key to finding the logical system the user is set to. This is required when a user has multiple sessions connected to a COPE IMS physical system. The following are the tasks to enable this.

Task 4.21.1 XCOPELTR

Set COPE variable (EVARS) XCOPELTR to Y.

Task 4.21.2 Update ZDEFAULT

1. Go to COPE option 1.10 (Generate Environment Member after Changes to ZDEFAULT).
2. Submit and run the job created. Expected return code is 0.

Task 4.21.3 IMLTERM

1. Copy member IMLTERM from the xcope1.JCL library to the xcope2.JCL library.
2. Modify member IMLTERM according to the comments in the job as appropriate in the xcope2.JCL library.
3. Submit modified member IMLTERM.

Task 4.22 ODBM Client Support (Optional - DB/TM and DBCTL only)

IMS provides an implementation of the Distributed Relational Database Architecture (DRDA) protocol that you can use to write your own IMS Connect TCP/IP applications.

DRDA is an open architecture that enables communication between applications and database systems on disparate platforms.

To use the IMS support for DRDA, you must create the DRDA client driver (DRDA source server). No additional software needs to be installed or configured on the client system. The DRDA target server consists of IMS Connect and the Open Database Manager (ODBM) running with IMS in z/OS®.

If an ODBM is related to a COPE defined system, a mechanism must exist for the client to define which Logical System the required database is in.

The mechanism is implemented in the ACCRDB. The ACCRDB DDM command has this format:

RDBNAM is a required parameter that contains the IMS PSB name that identifies the target database. The PSB name is a character string up to 8 bytes long. RDBNAM can optionally include the alias name of the IMS data store.

The distributed data management (DDM) architecture RDBNAM parameter identifies the target database for a given interaction. A description follows:

Format:

Parameters:

LL

The 2-byte specification of the length of the RDBNAM parameter.

CP

X'2110', the 2-byte codepoint of the RDBNAM parameter.

PSBNAME

The IMS PSB name, specified as a character string up to 8 bytes long. The PSB name identifies the target database and must match a PSB name defined to IMS.

ALIAS

Optional. The alias name of the IMS data store name. ALIAS must be specified as 4 bytes. If the alias name is fewer than 4 characters, the characters must be left aligned and the remaining bytes must be padded with blank character spaces.

When ALIAS is used, the PSBNAME and the ALIAS must be separated by a period.

Task 4.22.1 COPE Support for the RDBNAM Parameter

COPE uses the CSL ODBM input user exit routine to translate the PSBNAME to a value that is based on the data store alias name before ODBM process the request. The Alias name is a 4 byte identification of a COPE Logical System. The Alias value is the same as that used by a Batch or BMP program to identify a COPE Logical System. The value is defined with COPE ISPF option 1.6 (Define Lsys Identifying Tokens (Re-Linkedit IMS Modules)). The PSB is imported into a COPE Logical System in the normal way. A unique C-number is assigned to the copy of the PSB in each Logical System. The PSBNAME value used in the RDBNAM parameter is the non-C-number PSBNAME.

If the identifying token specified with COPE ISPF option 1.6 (Define Lsys Identifying Tokens (Re-Linkedit IMS Modules)) is greater than 4 bytes, the last 4 bytes of the token should be used. Instructions on how to modify the COPE supplied input user exit will be given later.

Task 4.22.2 IMS PROCLIB Members Required for the COPE Input User Exit

A BPE exit list member and a CSLDCxxx PROCLIB member must be specified to activate the exit.

The exit list member must be referenced by a EXITMBR statement in the BPECFG BPE member.

Sample BPECFG BPE member:

Sample ODBM BPE user exit list member of the IMS PROCLIB dataset (COPEEXIT)

The sample DBRC user exit list member of the IMS PROCLIB dataset shown below defines:

• One ODBM initialization/termination exit routine
• An abend limit of 8
• One ODBM Input Exit routine for COPE
• One ODBM output exit routine

Sample DBRC user exit list PROCLIB member:

Example of the CSLDCxxx Members of the IMS PROCLIB Dataset

The Alias names are those used in the client Data Store specification and are those tokens defined with COPE ISPF option 1.6 (Define Lsys Identifying Tokens (Re-Linkedit IMS Modules)). If tokens greater than 4 characters are used, the last four characters must be specified. All tokens used by a COPE connected ODBM must be specified as aliases.

Task 4.22.3 Installing the COPE CLS ODBM Input User Exit Routine

If 4 character or fewer length tokens identifying the COPE Lsys, copy the COPEODMI load module from the COPE installation load library to the IMS RESLIB dataset.

The exit may have been already copied by the AUTHCOPY JOB as part of the COPE installation process.

If tokens greater than 4 characters identifying a COPE LSYS are used, the exit source must be recompiled and link-edited before being copied to the IMS RESLIB from the COPE installation load library.

Task 4.22.4 Modifying the Exit Source

If the identifying Lsys tokens are 4 characters or less, no recompilation of the exit is required.

The exit is written in assembler. Before making modifications edit the ASM member in the installation JCL dataset to conform with the installation dataset names. Do not change the FTIECIM or COPEXXXX tokens in the member since these will be modified dynamically when the JCL is submitted.

1. Enter COPE ISPF and type EDIT on the prime screen.
2. Access the COPE installation ASM dataset member COPEODBI.
3. Find the &PREF1 statement in column 1 and change the SETC value to the length of the token - 4 left-most characters of the Lsys identifying tokens.
   For example, if a Lsys token is defined as DEVELTX1, equate &PREF1 to DEVE. If there is another LSYS specification of PROJ3, equate &PREF2 to P.
4. Change the values of &PREF1 - &PREF9 to specify all combinations of token prefixes for all Logical Systems.
5. Compile and link the exit.
6. When a successful compile and link has been achieved, copy the load module from the COPE installation Load library to the IMS RESLIB dataset.

Task 4.23 IMS JAVA Support in COPE

COPE supports JMP or JBP type regions.

If a JMP region is required, set up JCL to execute a separate region for every Logical System with a unique transaction class. Use the SEPREGN application (4.4;SEPREGN) to define a transaction class for every Logical System and to also identify all PSBs that are to execute in a JMP region.

JAVA transactions entered by a user are switched to the appropriate JMP region by COPE that depends on the Logical System the user is connected to.

Documentation of the details of the arrangement is in the BMC-COPE-Administration-Guide.

Task 4.24 Control Access to COPE Functions

If you use a security product that interfaces with the operating system via the security access facility (SAF), such as RACF, you may utilize your security product to control access to COPE functions. To do this, specify YES as the value of the XISPFSEC system parameter. Then have a security administrator install rules to control access to the entity names described in the RACF-and-ACF2-Access-to-COPE-ISPF-Functions section as required.

You can edit the COPESEL1 (DB/TM and DCCTL) or COPECICS (DBCTL) primary panel and provide a limited set of options for people who do not require access to the administrator functions (for example). Rename the tailored panel and add the PANEL(....) parameter for the new panel to the example above. If users are prevented from updating the menus library by a security system such as RACF, access to COPE functions can be limited.