IMS Facilities

Overview

To access the IMS facilities of COPE, you logon to IMS, then type COPE. This brings up the main COPE screen (see the following figure).

COPE IMS Main Screen

The following table lists the values for the above example (COPE IMS Main Screen).

• Issue COPE commands, to logon to an Lsys (just type the Lsys name), or display an MFS format etc.
• Issue IMS commands, and translate internal C-numbers to real names in the output.
• Press <PF1>, to access the COPE tutorial, which works exactly the same as an ISPF tutorial.
• Issue SS to access the Start/Stop scrolling screens for databases and transactions, to deallocate databases (for example).
• Type in a COPE Message Number of form nnn, to get an explanation for the message. The Messages Manual is online.
• You can issue these commands from any screen that, like the main screen shown above, has COPE in the top left-hand corner.
• You can also issue any of these commands from a cleared screen, by preceding the command with the word COPE followed by a space.
• To issue multiple commands with one pressing of the Enter key, type them one command after another, separated by a semi-colon, in the same way as with commands under ISPF, for example:   COPE TEST;/FOR MYMENU

• You could issue the above to logon to the Lsys called TEST and display the MFS format called MY-MENU, in one operation. This example could be issued from a cleared screen (as shown by the COPE preceding the first command, TEST). From the COPE screen, as opposed to from a cleared screen, you omit the COPE (It will be accepted if you accidentally include it).

This section describes the main commands that are useful to programmers. There are other commands that are useful to COPE Administrators, which are described in detail in the Tutorial. You access the Tutorial by pressing <PF1>.

Commands for Programmers

The following table lists the commands for programmers

Commands that are useful for COPE Administrators, are described in the tutorial and in the COPE for IMS/DC Administration Guide. The fullest descriptions are usually in the tutorial, and in the detailed explanations for COPnnn msgs (available by typing COPnnn on the command line).

The following table lists the commands for COPE Administrators.

You view the descriptions in the tutorial, which are arranged in a panel hierarchy, using the same PF keys as in an ISPF Tutorial. The following table lists the PF keys for tutorial panels.

To use COPE, you need to know what physical IMS system (Psys), and within that system, which logical IMS (Lsys), to logon to. The logical IMS associated with a given Libset level can be easily determined in the ISPF environment by going into COPE B;4.3 (Administration Functions, DRAW option), which displays a diagram of the Libsets. For example:

DRAW Libset Display

Here, the Libset called XYZ.INVDEVL has a logical IMS associated with it called INVDEVL. Usually, your COPE administrator will set up the second part of the Libset name to correspond to the Lsys name, as in this example.

Logon (via VTAM) to the physical IMS that contains the COPE Lsys called INVDEVL. Your COPE administrator will tell you which physical IMS to logon to.

Once in IMS, from a cleared screen, enter COPE. The system responds with the "COPE Main screen" (see the following figure).

COPE Online Main Screen (Not Logged On)

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

COPE Online Main Screen (After Logging On)

Top Line Fields

The Lsys field will be blank if you are not currently logged on to a COPE Lsys.

Once you are logged on to a COPE Lsys, you proceed with entering transactions, /FOR commands, or options from menus, exactly as you would under a non-COPE IMS system.

If you run transactions without having logged on, you will get the COPE screen, with message COP204, telling you that you are not logged on. You would logon by typing in the Lsys name, then repeat the transaction (the transaction was not invoked when you weren't logged on).

When you logon to an Lsys, the "=LIB=>" arrows on the left point to the dataset names of the program load libraries. The libraries are concatenated in order from top to bottom, as in a JCL concatenation.

To check what the libraries are at any time, type LIB on the "====>" line.

COPE Online - LIB command screen

The COPE screen (COPE Online - LIB command screen) always contains the name of the Lsys you are currently logged on to, next to the word COPE in the top left-hand corner. This screen can be called up at any time by clearing the screen and typing COPE.

Suspending Conversational Transactions

If you do not use IMS conversational transactions, please skip this section.

If you use conversational transactions, you can temporarily suspend the conversation, so that you can run a COPE transaction. To do this, type:

IMS suspends the conversation, and responds with a message:

You can then run other transactions, such as the COPE transaction to check what Lsys you are on.

To resume the conversation, press <Clear>, and type:

quoting the 4-digit ID that was in the DFS999 message. The screen that was showing before you issued /HOLD will reappear.

IMS / Commands (With * Wildcard Characters)

You can enter just about any IMS command from the "=====>" prompt on the COPE screen, such as /DIS A, /DIS Q TRAN, /DIS DB xxxx, etc. /DIS DB, TRAN, PROG, NODE and LTERM commands can be entered with an asterisk (*) on the end of the name in order to display all those names which match the characters preceding the asterisk. For example:

displays all databases beginning with the characters ISSREF.

The * "wildcard" character can be used anywhere in the name, as in ISPF member-list masks. Other wild characters, +, #, etc. are also possible. + means a single non-blank character, # means a number, and all the 'pic' characters usable in the ISPF FIND P'...' command, are supported.

The output of / commands will have C-numbers on the right-hand side of the screen, to assist in debugging.

If the output is more than a single screen can display, enter the SCROLL ON command and repeat the query.

Append the LSYS keyword, followed by the name of a Lsys, to issue a command in a system you are not logged onto. For example,

This also works for "unused" systems. Use

to issue the command in all systems.

The following table lists the wildcard mask characters.

* is the only wild character that matches variable length. Wild characters other than asterisk (*) and plus sign (+) are the same as the 'pic' characters in the ISPF Edit FIND P'...' command, except that @ and # also match themselves.

In practice, only *, + and # are useful in display commands.

Display COPE Message Explanations (nnn)

You can type in a COPE message number and get an explanation of the message, together with a description of the system action, and the appropriate user response.

COPE messages always have a COPnnn message number on the front, as in this example:

You would type in COP204, or just 204, on the "=====>" line of the main COPE screen, or any tutorial screen, to get the explanation. You can list all message numbers by typing in MI (Message Index).

Display Program Load Libraries (LIB)

The following figure shows an example of the LIB display.

The LIB Display

LIB displays the program load libraries being used for an Lsys. For example:

The command lists the program libraries in their concatenation order.

You can also add a DDname parameter, to look at the datasets on any DD in the message region.

If you type LIB COPESTEP, for example, you will see the libraries on the special COPESTEP DD.

The COPESTEP libraries are important, because they are concatenated after the libraries for each Lsys. So, if a module is not found in the Lsys libraries, it will be searched for in the COPESTEP.

To assist you with detailed understanding of library concatenations and ESTAEs, the LIB screen shows you the actual DDname concatenation, and currently active Estaes.

The DDname search order is: C0000002 COPESTEP STEPLIB.

Estaes currently active: COPESXP7 DFSPCC20.

The implications of these display lines are:

1. In COPE message regions, the three DDnames C0000002, COPESTEP and STEPLIB are "concatenated", so that it is as if all the libraries on the DDs were on a single STEPLIB. The order is C0000002 first (it is C0000002 in this example, other Lsys's will have a different C000000n DDname). This means that C0000002 is the Lsys-specific DDname used for loading programs in this message region for this Lsys. If you change Lsys's, you will see a different DDname here (different Cnnnnnnn). The libraries come from the COPE ISPF 1.5 definition ("Define Msg. Region Datasets"), and are set up by your COPE Administrator.

   COPESTEP is logically concatenated after C0000002. If your program loads a module that is not in the Lsys-specific concatenation, the next DD searched by MVS is the COPESTEP. Preloaded modules are loaded from COPESTEP (followed by STEPLIB, then LNKLSTxx).

   STEPLIB is logically concatenated after COPESTEP. If your program loads a module that is not in the Lsys-specific concatenation, nor in the COPESTEP concatenation, the next DD searched by MVS is the STEPLIB. Since in a COPE message region you should only have ONE library on STEPLIB (the authorized library containing COPERC00), none of your loads should be resolved from STEPLIB.

   LINKLSTxx libraries are logically concatenated after STEPLIB, as in all MVS regions. If your program loads a module that is not in the Lsys-specific concatenation, nor in the COPESTEP concatenation, nor in the STEPLIB concatenation, the next DD searched by MVS is the STEPLIB.

   The term "Tasklib Switching" as used in the COPE manuals refers to the way COPE dynamically changes the Lsys-specific DDname (the top C000000n one) to the appropriate Lsys, for each transaction that runs in a COPE message region. This is the essence of shared (by Lsys's) message region support in COPE.

2. ESTAEs are displayed to assist with problems where your application program either leaves ESTAEs active in the message region, or cancels other module's ESTAEs. To diagnose such a problem, you would issue the LIB command (which displays the same screen as when you logon to an Lsys). The screen will show you the current ESTAEs in this message region. If all is well, you should see COPESXP7 and DFSPCC20 (only) as above. We are not implying here that ESTAEs are related to program library concatenations, these are two separate unrelated issues.

Logoff from COPE (Not Normally Necessary)

The normal IMS Logoff (/RCL) works under COPE, but does not affect your COPE logon status.

Since the name of the COPE Lsys you are logged onto is stored in a database, it is retained across IMS logons.

You can do a "quick change" of Lsys at any time, by entering COPE followed by a space, followed by the Lsys you want to change to, from a cleared screen. This is useful when you are comparing the results of running the same test transaction, under two different logical IMS systems.

It is also possible, though normally unnecessary, to remove the association between your terminal and a particular logical IMS (in other words, to "logoff COPE").

To do this, enter COPE LOGOFF from a cleared screen, or just LOGOFF from the COPE screen.

This facility is provided to assist COPE Administrators when they are testing your logon procedure under COPE.

The attempted transaction cannot run, because COPE does not know what logical IMS you wanted to run it in.

If there is a disk-drive hardware failure, or similar problem, your COPE Administrator will re-initialize the COPE USTDLMGR Database (which contains a record of the current Lsys for each user) and you will find that you are "COPE logged-off". In this case, follow normal logon procedures as described above.

If your COPE Administrator adds or deletes Lsys's, they must log all users off. This is done as follows:

Alternatively, your Administrator can re-initialize the Control Database (USTDLMGR). The effect in either case is that you will find yourself logged off, and you must logon again.

Send a Message to a User or all Users (MSG)

You can send a message to a user, or all users. The messages appear on the COPE main screen. The persons receiving the messages can read them and delete them. You can also delete messages you have sent.

You would send a message to ALL users as follows:

This would appear on every user's screen, in pink if you have color screens, on a =MSG=> line (max 4 lines):

For further details, access the tutorial, and select the MSG topic (number 7). From there you can select the following topics:

1. Sending messages with MSG <dest> <color> <text>
2. Deleting messages sent to you, with MSG DEL
3. Deleting messages sent from you, with MSG DEL <dest>
4. Deleting messages sent by others, with MSG DEL <dest> FROM <source>
5. Automatic deleting of msgs, with MSG <dest> <c> ADEL <mins> <text>

Database Start/Stop

 To take a database offline, you must "stop" it, using the COPE Database Start/Stop menus. This is equivalent to the normal IMS /DBR command, but provides an easier-to-use display.

From the COPE screen, enter SS to access the Start/Stop selection screen. From a cleared screen, you can enter COPE SS, to go to the same place.

Start and Stop functions are not distinguished from each other, at this point. SS displays a selection screen (see the following figure).

COPE Online - Start/Stop Selection Screen (DB Side)

Leave the ACTION field blank, enter DB for Database, next to DB/TR, and enter your name or initials ("EC" in this example) against USER NAME. For USER NAME, you can enter up to 30 characters of a message to send to users who try to use a Database that you are going to stop. All other fields are optional. You can leave the SYSTEM as INVDEVL (which is initialized to whatever system you are logged on to) or you can blank it out, to get a list of the Lsys'.

COPE Online - Start/Stop System List Screen (DB Side)

If there are more systems than will fit on one page, use <PF7> and <PF8> to scroll the list up or down.

You can select only one Lsys at a time, but you can later <PF3> back here for another one. Enter an X next to the Lsys in which you want to Start/Stop a database (for example, INVDEVL as shown in COPE Online - Start/Stop System List Screen (DB Side)).

A scrollable display of the databases that can be started or stopped is shown (see the following figure).

COPE Online - Database List Screen

Enter S for Start, and/or P for stoP, against the groups of databases that you wish to bring online, or take offline.

In the above example, the group called ABC1 is to be started, and the group called ABC2 is to be stopped.

The G column is a Group indicator that shows whether the line represents an individual database, or a Group of databases. In the above, all the lines are marked G, so they are all Groups.

When you stop a group or database, you will see that your name or initials (as entered in the USER NAME field of the selection screen) appears next to it, in place of the Description. This is so that other users may check with you, if they want to use the database that you brought offline.

When a user runs a transaction that needs an offline database, COPE gives them a message saying the database is stopped. That message also contains the USER NAME information, as shown in the following figure.

COPE Online - Stopped Database Screen

Note that COPE appends the "14:36 DFTI8L07 91.045" to the user name initials, to help identify the time, the user who stopped the database, and the date they stopped it. As much as will fit in the 30 characters available will be appended. You can use a message of up to 30 characters, and it will "push" these fields out of view if necessary.

The database that is started or stopped is the one in the logical IMS that you either entered on the first screen, or selected from the list of systems screen. There will be other databases of the same name, but in other Lsys's, which are not affected. The stopping and starting in one system is completely independent of other systems.

Use <PF3> to return through the previous screens, or just press <Clear>, for a quick exit from the Database Start/Stop screens.

The "SELECT FUNCTION ===>" line cannot be used for any commands (you must clear and say COPE to return to the COPE main screen).

Groups of Databases

COPE databases are always stopped in pre-defined groups. For example, a database with all its secondary indexes (and its primary index if HIDAM) is an indivisible unit, as far as COPE stopping and starting goes, and will always be together in the same group.

If databases have IMS logical relationships between them, the logically-related databases also form an indivisible Start/Stop group.

The reason for this grouping is to alleviate problems when IMS starts to process a DLI call (through a secondary index), and then finds that it cannot continue because the main database is offline. IMS issues a U85x, or a BA status code, in this situation.

Also, it is generally much more convenient to be able to start and stop related databases together, rather than individually.

The COPE Database Start/Stop Facility also provides "Groups of Groups", so that you can stop and start common application-related databases together. Your COPE Administrator defines these groups to COPE, with descriptive text for each, in COPE ISPF option 3.7

To see what databases are in a group, enter an X against the group. This will go down one level in the hierarchy. Press <PF3> to go back up the hierarchy.

The ultimate group, is the group of all databases in one Lsys, and you can start or stop these all at once. You do this by entering S and P against the logical system name in the list of systems. To receive this list, you blank out the SYSTEM on the initial selection screen, as described in the example above. Alternatively, you may enter S or P in the ACTION field of the initial selection screen, with the group name not blanked out, but with a blank NAME field. This is referred to as "Start/Stop of a System, DB Side" and is further described in "System Start/Stop<XREF>" later in this section.

Database Stopped Counts

The STOPPED column on Start/Stop screens shows you counts of databases stopped, as a "fraction". For example:

Here, ABC1 is a Group in which 3 of the total of 8 databases are stopped. These stopped counts are correct when you first display the list, but won't necessarily be correct at other times (for example when you <PF7> and <PF8> up and down the list).

Why /DBR, etc. Commands are Prohibited

Normal IMS commands for changing the Start/Stop status of databases cannot be used under a COPE system. They would bypass COPE's internal control of the status of databases. Therefore, you cannot use the following IMS DB commands in a COPE system:

You can start or stop databases from the command line of the COPE main screen by using the following commands:

COPE provides these commands mainly so that you can issue them via PF keys or batch programs.

This is described in the COPE for IMS/DC Administration Guide.

You start and stop transactions using the same set of screens as databases.

Enter COPE SS from a cleared screen, or just SS from the COPE screen, to get the selection screen (see the following figure).

COPE Online - Start/Stop Selection Screen (TR side)

Enter TR for TRansaction, against the DB/TR, and blank out the SYSTEM name to get a scrollable list of Lsys' (COPE Online - Database List Screen).

COPE Online - Start/Stop System List Screen (TR side)

Select an IMS system with an X, and press <Enter>. The following screen then appears (see the following figure).

COPE Online - Transaction List screen

Entering S or P against a Trancode starts or stops that transaction and its associated program. In the above example, transaction INVTRAN1 was previously stopped by an S0C7 abend. The S on the left-hand side is a command to start the transaction again, to make it available to all users. Note that the Description field of the stopped transaction contains the module name, PMAP offset, and abend code, for the abend which caused the transaction to stop.

COPE programs have the same status as the Trancode. When there are multiple Trancodes for one program, the program is started for started Trancodes and stopped for stopped ones.

The difference from Databases is that transactions will almost always be stopped by MPP abends, rather than by a user. Users start the transaction when they know the program has been fixed. Sometimes you will want to stop a transaction and leave an explanation. This is achieved in the same way as for databases. Use the 30-character User Name field on the first Start/Stop selection screen.

If your transaction is stopped by an MPP abend, normally the next thing you want to do (after fixing the application program) is to start the transaction. You can use SS screens to start it, or you can use the "Quick-Start" command:

This will start the transaction and program. Note there is no slash (/) and no TRAN keyword above.

Sometimes after issuing a STA Trancode, when you run the transaction, it is still stopped. This happens in situations where your abend was in a DLI call, and you are using dedicated (by Lsys) message regions. If this happens, just issue "STA Trancode" again, and after the second time you will find that the transaction is started. However, issuing STA trancode twice, without testing whether the Trancode was started between, will not protect you from this problem. The reason is that the intervening test transaction is needed by COPE to resynchronize the status. In other words, "if it is stopped, start it". If you want a more detailed explanation of this behavior, contact your COPE Administrator.

As with databases, groups of transactions may be pre-defined, for mass starting and stopping. See your COPE Administrator for details.

You can start or stop all transactions in an Lsys at once, from either the list of Lsys's, or from the initial selection screen (with the NAME field blank). This is referred to as "Start/Stop of a System, TR Side" and is further described in "System Start/Stop.<XREF>". You start or stop a system on the TR Side, if you need to either:

• Make the system unavailable, but do not want to deallocate all the databases

  or,

• Deallocate the system's program load libraries

Why /STO TRAN, etc. Commands are Prohibited

The standard IMS commands for changing the Start/Stop status of Transactions and Programs cannot be used under a COPE system, because they would have an effect across Lsys's. The following IMS commands should not be used:

The COPE equivalent commands internally generate the appropriate IMS command, and also provide a "Stopped" status at the Lsys level, which is necessary so that Lsys' do not interfere with each other.

In special test situations, you may need to PSTOP a transaction so that you can create a queue of transactions for testing program reusability (for example). In such a case, the IMS /PST command can be used, but with caution, because it PSTOPs the transaction in all Lsys'.

Command Line Transaction STA and STO Commands

You can start or stop transactions from the command line of the COPE main screen by issuing the following commands:

Note that there is no slash (/), and no TRAN keyword between the STA or STO and the trancode. COPE provides these commands so that you can "Quick-Start" the transaction and program after an abend, and so that you can issue them via PF keys or batch programs. This is described in the COPE for IMS/DC Administration Guide.

System Start/Stop

You start and stop Systems using the Start/Stop Selection screen, or the Start/Stop System List screen. You can start either Side of a system, or both Sides. The two sides, and the effects of stopping them are:

DB

Deallocates all databases in the Lsys. If there are many databases, this can take a minute or two, because many internal /DBR commands are issued. You would do this if you need to access all, or many of, the databases in the system, in batch, with DISP=OLD.

TR

Deallocates the program load libraries that are allocated to an Lsys. This also stops all transactions in the Lsys. You would do this if:

1. 
   
   1. You need to access the program load libraries in the Lsys in batch, with DISP=OLD. For example, you need to move the libraries from one disk to another.
   2. You need to stop users from using programs in the Lsys, but you do not need to deallocate the databases (and you therefore want to avoid the overhead of doing this). For example, you need to compile many programs in a system due to a global COPYLIB member change, and do not wish any of the old programs to run, because they might put fields wrongly in segments in databases that are being converted to the new COPYLIB layout.

When you stop a system on either Side, that system appears on the COPE main screen next to the =STOP> arrow.

Transactions cannot run in the system, even if only one Side is stopped.

As an example, you would deallocate all databases as follows. Enter COPE SS from a cleared screen, or just SS from the COPE screen, to get the Start/Stop Selection screen (See the following figure). Type DB opposite DB/TR, and blank out the SYSTEM field, to get the DB Side system list:

COPE Online - System Start/Stop screen (DB side)

In the above, SYSSTOP preceding the system name indicates that all databases in that system are stopped (deallocated). Note that the counts (0/440) do not reflect this. On the left-hand side, you have entered S for this system, and P for the INVDEVL system, because you want to start INVDEMO and stop INVDEVL. When you press <Enter>, the deallocation process will start.

Deallocation of databases proceeds asynchronously, and so is not complete when the system responds, even though the SYSSTOP will have disappeared from INVDEMO, and appeared against INVDEVL.

To check when deallocation is complete, clear the screen, and type:

This will show you a list of the databases in the INVDEVL system, with their IMS status.

Repeat the /DIS DB command until you see that all the databases are stopped in INVDEVL. If there are many databases in the system (more than will fit on a screen), display some databases that are near the end of the list, e.g. /DIS DB Z* LSYS INVDEVL, if there are databases whose names begin with "Z".

You can start or stop systems from the Selection screen, using S and P in the ACTION field, and blanking out the NAME field, but filling in the SYSTEM field.

Command Line System STA and STO Commands

You can start or stop systems, in either the DB or TR Side, from the command line of the COPE main screen by using the following commands:

• STA <lsys>
• STA DB <lsys>
• STO <lsys>
• STO DB <lsys>

To help solve application problems in online programs, COPE provides two debugging facilities:

1. You can view the DLI and SQL calls your program is making using the Call Trace in ISPF option 6.2.
2. You can quickly find the cause of problems using the module offsets and Last DLI call information that appears on the "Abend Summary Screen", displayed under IMS via the ABS command.

For batch and BMP regions, you can get the DLI and SQL call traces by adding a //COPETRAC DD SYSOUT=* statement to the JCL.

A condensed explanation of the COPE Trace Facility is given at The Trace Facility (Option 6.2).

Turning DLI and SQL Call Trace On

For MPP programs, enter COPE TRACE ON from a cleared screen, or TRACE ON from the "=====>" prompt on the COPE main screen, to turn on DLI and SQL call trace (see the following figure).

COPE Online - Turning Trace On

Press <Enter>, and *TRACE* appears in the top line, to indicate that the Trace is on for your terminal (see the following figure). An informational message also appears on line 3.

COPE Online - Trace Status Screen

For batch and BMP regions, you can get the DLI and SQL call traces by adding a //COPETRAC DD SYSOUT=* statement to the JCL.

Trace Display for MPP Programs (ISPF Option 6.2)

When the Trace is on, COPE sends a copy of all DLI and SQL calls issued by MPP programs that run from your terminal, to the IMS log. After running the transactions that you want traced, switch to COPE under ISPF to view the trace, under option 6.2 ("Trace Display"). Many different terminals may have their traces on at the same time. The viewing mechanism keeps the results separate.

To view the trace, in ISPF COPE ISPF Option 6.2, enter your terminal's name (Lterm or Signon-id) opposite the User field as shown in (see the following figure).

Option 6.2 IMS Online Traces menu

In the above example, you entered DFTI8L07 as the Lterm name (use the Sign-on id instead, if you use /SIGN in your system). You have also entered the "From Time", to say from what time you want the search for trace lines to start. Other fields have suitable defaults already filled in.

The next 500 lines of trace information after 1537 will be displayed. This is indicated by the 500 in the 'Lines' field, the 1537 in the 'From Time', and the blank 'To Time'. To see the last 500 lines, leave the 'From Time' blank, instead of filling it in. This is not recommended, however, because if no trace lines can be found, it will search the entire log, which may take a long time. To see 500 lines preceding a particular time (other than the current time), fill in the 'To Time'. To fully limit the time range, fill in both. The dates can also be changed from the "today" value provided.

In the example above, the default B for Browse is taken. Change this to E for Edit, to be placed in Edit (instead of Browse), on the trace output.

The optional filters are a way to limit the search by Trancode, and to control the detail in the display.

The Display field may be:

N - no calls

Use this if you only want to see program traces (such as COBOL Ready Trace) and do not want to see the DLI and SQL call trace. Program Traces are described below, under 'COBOL Ready Trace'.

S – summary

The resultant trace display will show a minimum of detail for each call. The display will be easier to read, but won't contain details such as all PCB fields, or millisecond elapsed times.

D – details

The display will show all details of PCB fields and timings.

C – counts

Displays COPE transactions (that are usually omitted) and a Counts summary of log record types and volumes. This is useful to Systems Administrators, when reviewing logging performance.

Hit <Enter>, and the IMS disk logs are read. While they are being read, the lower part of the screen will show a moving graphical display of the disk logs, and the current search position, as shown in (see the following figure).

Option 6.2 Trace Search in Progress Screen

In the above display, there are 6 disk logs, each represented by a horizontal bar, with the time (1701 Tue, 0903, etc) on the front. The first log is "Old", meaning the data on it is older than one week (this log is not being used). The second log started at 17:01 on Tuesday, which is yesterday, here. The other four logs are from today, and therefore show just the start time, not the day of the week.

A blinking plus sign (+) moves as the log is searched, leaving a trail of asterisks (*), representing tracks that have been searched. Here the search has proceeded over part of the last log (the one that began at 15:21). When the search is proceeding backwards (as it will initially), a trail of minus signs (-) are left instead of asterisks, which are later obliterated by the asterisks as it reads back forwards. You can use this display to view the search, and thereby estimate how long it will take, using the times as reference points.

In this example, the search would be fairly fast, and a few seconds later you are placed in browse on the selected trace records (see the following figure).

Trace Records Screen

In the above example (Trace Records Screen), the beginning of each transaction is indicated by "****" in column 1. Calls have the Function code (GU, GN, etc) in column 1, and PCB information on the same line as the Function Code, and the I/O area (if present) on the next line, and SSAs (if any) following that. If the status code is bad, a "=WARN>" or "=ERR=>" line is produced, as the last of the group of lines associated with each DLI call.

What To Do If You Get No Trace Output

If your Terminal, From Time/To Time, or Trancode filters give you no output to view, the terminals or transactions in the time period that were filtered out are indicated on special "=MSG=>" lines, with transaction counts in parentheses, e.g.

The above message tells you about transactions that matched your terminal filter, but not your Trancode. It will summarize many similarly named Trancodes, as in the "TAS*" example above.

If no transactions match your terminal name filter, the message will tell you the terminal names that were filtered out, again with transaction counts in parentheses, e.g.

You would then correct your filters and retry, or vary the From Time and To Time to search for trace records in a different time period.

Details of Trace Display

The following sub-sections explain each line of the Call Trace in detail. The lines explained are listed in the following table.

Program Start

Program Start

COBOL Ready Trace

A0100-etc

Contents of the trace line (blanks truncated off end).

You must compile your program with READY TRACE and RESET TRACE statements, or DISPLAY statements, to receive this trace.

This facility works for non-COBOL traces as well. If you are using any language that writes lines to a DD in the message region, you will see the trace here, with the DDname on the front of each line.

For example, if the DD is DSNTRACE:

   DSNTRACE ...some trace data...

The special DDs SYSOUT, SYSOUU and SYSOUV get the characters, | and \ on the front of their lines. The DDs must be present in the message region JCL but you will not see any output for them using IOF or SDSF.

This diversion of traces from IOF/SDSF to the IMS logs, means that you have less trouble finding your trace, because it is easily displayed using the COPE ISPF Option 6.2 facility, and you don't need to locate the correct message region under IOF or SDSF, nor sift through other people's trace data.

COPE always diverts program traces to the log, no matter whether you have TRACE ON or OFF.

Your TRACE status only refers to whether or not you want the DLI and SQL call traces. Under COPE, you cannot view program traces in IOF or SDSF, because they are not there.

Function/PCB

Function/PCB

The I/O area hex data is viewed using HEX ON. The length of the I/O area used by COPE came from the DIRCA. If TRUNC was active when the transaction ran, I/O area's longer than 254 bytes are truncated. If NOTRUNC was active, the full I/O area is recorded on the IMS Log, but will only appear under ISPF COPE 7.2 if Browse rather than Edit is used. If Edit is used, long I/O areas will again be truncated.

Whenever an I/O area is truncated, either by the IMS COPE Trace, or by the ISPF COPE Trace Edit, the eight characters "<=TRUNC=" overlay the last bytes of the 254-byte trace area, to indicate that the full I/O area is not available for viewing.

Modname

This is the 4th parameter of some TP ISRT and PURG calls, and specifies to IMS the MFS Modname to be used for formatting the output screen.

SSA Lines

These are the 4^th and later parameters of Database DLI calls. Hex data in SSAs can be viewed by using HEX ON.

In error situations, where the SSA is overlaid, up to 254 bytes of working storage could appear. The COPE online Call Tracer does not know the actual length of SSAs. It relies on the fact that unqualified SSAs end with a blank, and that qualified SSAs end in a right parenthesis.

This also means, that very occasionally, a right parenthesis will appear as part of the data in an SSA, and will be mistaken by COPE Trace as the end of the SSA. In this case the trace of the SSA is incomplete.

Message

Whenever a non-blank status code is returned by DLI, a Warning or an Error message is shown as the last line of the call trace.

Status codes of GE, GA, GB, II, QC and QD produce "=WARN>" messages, and other codes produce "=ERR=>" lines.

The messages are defined inside module COPESXP9, and are the same messages returned by COPE to an online IMS terminal on an abend, if the last call status code was bad. The messages are intended to provide enough information for you to solve the problem without consulting the relevant IMS Manual.

Logic trace

When COPE TRACE LOGIC is on, COPE records messages on the IMS log which describe the processing it is doing, as it is doing it.

LOGIC trace messages are shown with "====" (four equals signs) on the front, to make them stand out. The contents of the messages are many and various. They tend to be readable, but may need to be used in conjunction with the source code for COPESXP1.

The logic trace helps diagnose problems with COPE. Problems can occur, for example, when MFS is not generated (causing Lsys' to share the same MFS), and for many other minor default-related or generation problems, system JCL changes, and so on. Also, application programmers may find it useful to help solve some non-COPE problems. There is available an even more detailed trace than the LOGIC trace, called "DEBUG ON". This trace comes out on the COPERRMS DD in the message region, is very voluminous, and is system-wide (all terminals) and so must be used with caution. DEBUG trace is definitely NOT readable without the source code for the COPESXPn modules.

TRACE OFF Command

You can turn off DLI Call Trace for your Lterm, with a <CLEAR>, then:

You should turn DLI Call Trace off if you are logged on to IMS, and you are executing many transactions from that terminal, which do not need tracing. The overhead for the trace is typically a 25 percent increase in IMS logging. This is a low overhead, but you may want to make sure you are not incurring it unnecessarily.

The trace stays off, across IMS Restarts, until you issue another "COPE TRACE" or "COPE TRACE ON" command. Tracing is always independent of other users, and it doesn't matter which Message Region your transactions run in. If you turn trace on, and then do not issue any IMS transactions from that terminal, there is no logging and thus no overhead.

TRACE ON NOTRUNC Command

For the DLI Call I/O area, only the first 254 bytes (or less) are usually traced. You can stop this "truncation" of the I/O area trace by using the following commands:

"NOTRUNC" can be shortened to "NOT". The overhead for NOTRUNC is high, and can impact performance, especially if it is accidentally left on for an active terminal. Use the default, TRUNC, wher- ever possible, and NOTRUNC only when it is necessary to see the contents of segments past the 254-byte truncation point. You can turn TRUNC back on, without turning TRACE off, with a "COPE TRACE TRUNC" command.

The COPE header line shows *TRACE*N* , when NOTRUNC is in effect.

TRACE LOGIC Command

To find out exactly what COPE is doing as your MPP runs, you may turn on a detailed internal LOGIC trace, for your terminal only, with the following command:

LOGIC can be shortened to LOG. The output is viewed under ISPF COPE 6.2, as with normal DLI and SQL Call Trace. LOGIC lines come out with "====" (four equals signs) on the front, to make them stand out. Enter "COPE TRACE NOLOGIC" to turn the logic trace off. "*TRACE*L*" is an example of a header line, with "L" for LOGIC on.

Logic trace has a moderate performance impact (not as large as NOTRUNC). The messages produced by Logic Trace are readable, but may need to be viewed in conjunction with the source Code of module COPESXP7, the main online COPE processor module.

Abend Summary Screen

When an IMS transaction abends, press <PA1> on the DFS555I message, to clear it out, then type COPE ABS to display the COPE Abend Summary screen. Often, you can easily solve the problem immediately from the "Abend Description" or "Status Code Description" on Line 3, the "Module Call" trace, and/or the "Last DLI Call" display.

You can check your compiler listing, for the "Call Offsets" given, for Module or DLI calls, without looking at dumps or linkedit maps. If you need the dump, the message region jobname, number, and time in the header line help you locate the correct dump.

The lines of the Abend Summary screen are described in the following table.

Abend Description Screen

The messages in the top right-hand corner and on line 3 explain the meaning of the Abend code, if it is an IMS abend or system abend. In this example (Abend Description Screen), you would look at your CIFAU101 compiler listing, for a bad GU call at +03EC.

Abend S0C7 Display

For an S0C7, COPE shows you the instruction (Add Packed), the two fields in hexadecimal, and tells you what is wrong with one or both fields (Sign "0"). Here, at +01A8 in the CIFAU154 listing, a 2-byte field for an ADD is blanks (Hex 4040).

Abend Summary - Abend Offset

Abend Offset Display

The fourth line of the screen (Abend Offset Display) shows you the module name and offset where the abend occurred.

Here, the module is CIFAU154, and the offset is 01A8. At, or near, 01A8 in CIFAU154's PMAP or Condensed Listing, you would find a statement that does a calculation, involving an addition.

The offset matches the compiler listing offsets, so you do not need to consult a linkedit map.

Abend Summary - Status Code Description

Abend Status Code Display

The messages tell you the meaning of the IMS status code returned by the last DLI call. In this example (Abend Status Code Display), you would look at the CHNG call at +0A04 in the CIFAU101 compiler listing, which is referring to DFTI8LP2 at +30E0. This Lterm name may be wrongly coded inside the module, or could have been entered on a user screen, or perhaps should be added to the IMSGEN.

In this case, COPE does not "know" the U1001 abend code, because it is not an IMS abend code.

If COPE knows the Abend, and there is also a bad status code in the last DLI call, it puts the short abend message in the top corner, and the long status code message on line 3.

Abend Summary - Module Call Trace

Abend Summary - Module Call Trace Display

The messages containing "Called" show that a static call occurred from one module to another. "Linked" denotes a dynamic call. The most current module is at the top (BADCODE), followed by the module that called it (CIFAU156), and so on, in reverse order. The main module in this example is CIFAU101, because it is in the last message containing "Called" or "Linked". The "Last DLI Call" message is not a part of the Module Call trace. Modules that were previously called by other modules, and have returned, are not on the current call path, and therefore will not appear in this list.

Abend Summary - Last DLI Call Display

Abend Summary - Last DLI Call Display

The Last DLI Call (Trace Records Screen) was a GU with blank status (shown " - - ") on Database ABCINSDB. It returned a segment of length 400. The PCB Number is 5 (5th PCB in PSB, including the I/O PCB). Other PCB fields shown are Level (01), Procopt (GOTP), Segment Name (ABIACSEG), Number of Sensitive Segments (2), and Key Feedback Area in hex. The start of the I/O area, and each SSA (only 1 in this example), are shown in character and vertical hexadecimal.

Abend Summary - Module Offsets

Abend Summary - Module Offsets Display

The Module Name and Module Offset are given on the front of many messages (Abend Summary - Module Offsets Display).

The Module Name is the external name, not the COPE C-number name. Physically, the module can exist in a load library with a COPE C-number name.

The Module Offset is in hex (for example +A8) form, omitting leading zero bytes. It is relative to the start of the module, not the load module that the module may be linked in to. COPE finds the position of all modules within the load module, to get the offset. The offset matches compiler listing addresses (PMAP in COBOL).

When an area is in Getmained storage, the 4-byte storage address is given (as in 00008044 above). This has no direct relationship to offsets shown in compiler listings, but can be used to locate the area in the dump.

Abend Summary - Date Link-edited

Abend Summary - Date Link-edited Display

The module that abended has its Linkedit date printed, along with the library that the module was loaded from.

The first time you compile a new MFS format into an Lsys, you have to issue REFRESH. This will refresh the MFS C-number translate table. This table only changes when you add an MFS format into an Lsys, the table does not change when you replace an existing format.

System administrators do IMSGENs which add new PSB’s etc., and then issue REFRESH to cause the message regions to load the new versions of the COPEXRFn modules. These modules contain tables which translate PSB and DBD names to C-numbers.

Displaying Link Date/DSN of a Program (VERSION)

Displays the date link-edited, and the dataset name, for a program. Type in VERSION COPEUTP1 (for example) and you will see:

Version Display

The program is 695027 bytes long. The first 62 bytes at the entry point to the program are shown. It was link-edited on Sep 5th 2014, into the PGMLIB shown.

The CDE indication shows the program was preloaded. The display is different, since the data is from the Loaded address and not the entry point.

System Commands for COPE Administrators

System administrators need to be familiar with commands that are used to debug COPE, refresh internal tables after gens, submit batch jobs, synchronize status after problems, and other rarely used functions. In normal operation, these commands are either issued automatically (REFRESH, for example) or are not used.

You can receive a description of the commands by hitting <PF1> from the COPE screen, then selecting option 12 on the online tutorial panel, and then selecting one of these sub-options listed in the following table.

The VERSION LLE command results in this display (see the following figure).

VERSION LLE Result Display

Preloaded modules are not deleted by COPE when the Logical System changes. An additional mechanism to retain loaded modules and not delete them is provided in the COPESXUX COPE exit which can approve or reject module deletes on Lsys change.