The MCP Tape Label Logger is a utility that records "tape label" information for Unisys MCP systems. It is a small program that runs continuously, capturing tape volume creation events in a KEYEDIOII (ISAM) file for later analysis and reporting.
This project is part of the UNITE Source Code Repository hosted on SourceForge.
The LOGGER works by capturing type-35 status change events using the MCPSUPPORT library's STATUS_CHANGE_REQUEST procedure. These events are generated by the MCP whenever a tape volume is closed after having been written. The data elements in the log file are formatted directly from the data elements in the event messages.
The LOGGER is written in DCAlgol, a variant of Unisys MCP Extended Algol.
The log file must be created before the LOGGER is used and must conform to the record format produced by the LOGGER. A COBOL-85 program, TAPELABEL/LOGINIT is included to create an empty file and define the indexes. See the Installation and Configuration and Log File Format sections below for more details.
Because the tape label events are written to a KEYEDIOII file, multi-user read and update operations can be performed. Therefore, reports, extracts, and updates may be run against the file while the LOGGER is actively recording tape label events.
This project does not presently provide any reporting or data extract facility for the logged data—that is something you will need to do for yourself. Over the long term, older records will need to be purged from the log file, and possibly archived elsewhere. These are also features that are currently left to the individual user. Contributions of report, extract, and maintenance software for the log file will be gratefully accepted and considered for inclusion in this project.
Download the ZIP file, which contains source for both the LOGGER and LOGINIT programs. These files are in MCP PWB (Programmers Workbench) format. The decompressed source can be uploaded to an MCP environment using the PWB editor, the MCP File Copier utility, the Windows Explorer extension for MCP Client Access Services, the MCP's SYSTEM/NXSERVICES/PCDRIVER utility program, or FTP.
Compile the LOGINIT program with COBOL-85. Compile the LOGGER program with DCAlgol. If your site has not licensed Algol (which includes DCAlgol), you can compile the LOGGER with DMAlgol instead. No special compiler options or run-time task attribute settings need be compiled into the codefile
Decide where you want to the log file to be stored. Specify a fully-qualified title for the log file (including family name and either a usercode prefix or "*" for a global file) in both programs, using one of the following techniques:
The internal name of the log file is LOG for the LOGGER program and TLF-TAPELABEL-LOG for the LOGINIT program.
Programs using the STATUS_CHANGE_REQUEST API must be marked as privileged programs using the ODT MP command. The LOGINIT program does not need this, only the LOGGER program, thus:
MP (PROD)OBJECT/UTIL/TAPELABEL/LOGGER ON LIB +PU
This marking must be done each time the codefile is recreated (i.e., after each recompile). Note that running under a privileged usercode is not the same as running it as a privileged program. The program will not be able to use the STATUS_CHANGE_REQUEST API if it is simply run under a privileged usercode.
The LOGGER program must be running in order to capture and record the tape label events. There is no automatic way to recover events that occurred while the program was not running. Tape assignment information is written to the system SUMLOG, however, and potentially could be retrieved from there if necessary. One way to assure the LOGGER runs is to make it an Automatic Initiate program, which will be executed by the MCP as soon as possible after a halt/load. Use the ODT AI command to define an Automatic Initiate, e.g.,
AI LABELLOGGER = (PROD)OBJECT/UTIL/TAPELABEL/LOGGER ON LIB
You may also wish to "lock" the program to prevent it from being DS-ed accidentally. That can be accomplished using the LOCKED option of the ODT MP command, and can be combined with the PU option above, thus:
MP (PROD)OBJECT/UTIL/TAPELABEL/LOGGER ON LIB +PU, +LOCKED
A locked program can be unlocked by using the ODT "<mix>LP-" command.
Note that while the codefile and log file each may be stored under a usercode, the task does not run under a usercode if initiated as an AI. Therefore, the fully-qualified title of the log file should be specified in the codefile, either in the source code of the file declaration, through file equation at compile time, or through a WFL MODIFY command against the codefile.
The LOGGER program should normally be left running continuously. It can be sent to a graceful end of task, however, by giving it a "<mix>HI 99" command. As it is driven from an event queue, the program does not need a high priority.
KEYEDIOII has good recovery across system restarts; even so, the LOGGER program closes the log file during periods of inactivity. The inactive timeout is determined by the WAITMAX define in the program, and by default is 600 seconds. The log file is reopened automatically when the next tape label event occurs. Errors during open and close cause the program to abort; errors during a write to the log file are displayed, but do not cause an abort.
KEYEDIOII files and their indexes can be backed up with Library/Maintenance, but there are issues if the file is currently open for update. This is one of the reasons why the LOGGER closes the log file during periods of inactivity. See the KEYEDIOII Programming Reference Manual for details and options to control how these files are backed up when open.
The TAPELABEL/LOGINIT program initializes the log file with an appropriate record structure and file attributes for use by the LOGGER and establishes a set of indexes. It must be compiled with COBOL-85, not COBOL-74.
The log file as defined by LOGINIT has three indexes:
You may modify the LOGINIT program to add or subtract indexes, as long as the prime index is guaranteed to generate unique keys. The LOGGER program is insensitive to the blocking factor, area size, and index structure of the file—it simply formats and stores records as it captures events. The index structure of the file can be changed after it has been created by using the MCP's SYSTEM/KEYEDIOII/UTILITY program.
The following shows the COBOL format of the KEYEDIOII record area:
01 TLF-REC.
05 TLF-KEY.
10 TLF-DATE PIC 9(8).
10 TLF-TIME PIC 9(6).
10 TLF-SERIALNO PIC X(6).
05 TLF-JOB-NR PIC 9(12).
05 TLF-TASK-NR PIC 9(12).
05 TLF-SAVEFACTOR PIC 9(3).
05 TLF-CYCLE PIC 9(4).
05 TLF-VERSION PIC 9(2).
05 TLF-FILESECTION PIC 9(4).
05 TLF-VOLUME-SEQ PIC 9(4).
05 TLF-UNITNO PIC 9(11).
05 TLF-UNIT-TYPE PIC 9(3).
05 TLF-DENSITY-BPI PIC 9(11).
05 TLF-DENSITY-ATTR PIC 9(3).
05 FILLER PIC X(13).
05 TLF-DENSITY-MNEM PIC X(12).
05 TLF-FILE-TITLE PIC X(40).
05 TLF-JOB-NAME PIC X(30).
05 TLF-TASK-NAME PIC X(80).
The log file as defined by LOGINIT has record-level locking and recovery (auditing) enabled. The file has 264-byte records (but since KEYEDIOII adds a word to each record, it will have 270-byte records on disk). The default blocking factor is four, which yields a 1080-byte (180-word, 6-sector) block. The file is defined with 2000-record (3000 sector) areas. It initially has 20 areas, but FLEXIBLE is set, so the number will expand as needed, up to a KEYEDIOII maximum of 1000 areas. This arrangement will store a maximum of two million log records; a larger number of records can be accommodated by increasing the area size of the file.
You must not change the format of the log file (at least, not without making corresponding changes to the LOGGER), since the logger program is written in DCAlgol and is coded to format records according to the offsets and data types of fields as represented in the LOGINIT program. The formats of the record area defined in the LOGGER and LOGINIT programs agree only by convention, so do not modify one without the other.
You can extract the SELECT clause, FD, and record area from the LOGINIT program for use in other COBOL programs. They should work as written for both COBOL-74 and COBOL-85. You may wish to turn the FD and/or record area into a COPY module if you will have multiple programs using the log file.
The way that a few fields are formatted in the log file requires some explanation:
Any fields from the event record that do not have valid values will be formatted as spaces in the log file record. Any FILLER is always formatted as spaces as well.
We welcome others to participate in this project and submit contributions to the software and documentation. As mentioned above, the project does not presently include any tools to extract or report the table label data recorded by the LOGGER program, and contributions of these will be gratefully considered for inclusion.
Please contact the Project Admin for information on joining the project.
If you wish to make changes to the LOGGER or LOGINIT programs, please try to preserve the existing sequence numbers in the source code lines as much as possible. Sequence numbers are a foreign concept in most development environments, but they are an important part of serious development for MCP software, so try to change them as little as possible.
Unisys documentation is available without cost on their support web site, http://support.unisys.com.
| Revised: 2012-07-22 | Project Web Hosted by
|