Building the Online IMS/DB/DC System

Before reading this section, you should be familiar with the concept of COPE Libsets. For more information, see Understanding Libset Concepts.

The following are the steps to generate a COPE System:

Most of the steps have an ISPF based application that implement them. To following table provides the magnitude of each of the steps with an estimate (for comparison purposes only) of the time it takes to perform them.

Step 0. Define Stage 1 Processing Technique

If a COPE system uses identical definitions of DATABASE, APPLCTN and TRANSACT Stage 1 macros, the XCMNSTG1 ZDEFAULT variable should be set to YES.

This setting allows COPE to store only 1 copy of the Stage 1 definition, and uses enhanced processing techniques to generate COPE Stage 1 definitions and SS information. The definition must be set before any Stage 1 source is imported.

Step 1. Define Libset Configuration

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 to add new Libsets. For more information, see Understanding Libset Concepts.

The following is a Logical System Definition Panel. It displays several interrelated Logical Systems being defined.

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 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 Lsys Identifying Tokens (Re-Linkedit IMS Modules) (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 linkedits 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.

The following is an example of the result.

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:

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 (PF3) results in the following display. It displays the 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, enter END (PF3). Check the resulting generated job, submitted after the SYSLMOD statements of the generated job, 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. Many of the items are defined automatically by COPE for its own usage.

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

1. 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 PSBs from all Stage 1’s that were parsed will be presented.
2. Place S characters next to the PSBs 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.
3. If this is the second or successive time that you have entered the XPSB function, some of the PSBs 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.
4. Press <PF3> to save the excluded list.

Step 3. Import Stage 1 Source

Prerequisite Step

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.

The Option 2 Menu is as follows:

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 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./3C/4C/5C 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 5. 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.

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:

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

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, refer to Refreshing Start/Stop Application (Option 3.SS or 3.7). Initially, PF Key 3 should be pressed and the resulting JOB submitted.

The generated JOB from Option 3.7 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.

The CHECK application is accessible via Option B;3;11. The following panel is displayed:

Option 2 generates the report. When the Report Job is completed, Option 1 views the results.

The following is an example of the result panel. It displays the Overall Consistency Check Report. 

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.

The following is a typical report. It displays an 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.

Step 14. Define Message Region Lsys Steplibs

Option 1.5 results in the following display. It shows Message Region Dataset definition.

Every 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 the hlq.JCL library, to help you setup the online IMS system:

• COPECTL Control region
• COPEDLS DLS region
• COPEDBRC DBRC region
• COPEMSG1 Message region
• COPEMSG2 Message region
• DF SVSM00 VSAM/OSAM buffer pools member

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 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, 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 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 1.5 specifications.
7. The 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 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 22528 (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).
10.  You must either specify 005 (class 5) as one of the classes on your message region parameter, or have changed the delivered COPE system transaction class, in option 1.7. To do this, go into option 1.7, change the (TP,1) parameters that you will see there, then run option 4.1, 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, BACKUP 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 T, and then regenerating it. For instructions on how to do this, see "Convert external names to COPE internal names (Option T)” in the 

    COPE

     for IMS/DC Administration Guide. 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 PSBs, DBD and MFS formats are generated, as described in the COPE for IMS/DC Installation section. 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.