The Paradigm Futilities


by Paradigm Corporation
Contents:

The Paradigm Futilities is a collection of miscellaneous utility programs, server libraries, and sample source code for Unisys MCP systems.

This project is part of the UNITE Source Code Repository hosted on SourceForge.

Description

This project hosts a collection of utility programs, libraries, and sample source code for Unisys MCP systems. Some of the elements of this collection are standalone utilities that serve a particular purpose, some are libraries of routines that can be called from other programs, some are supporting files such as copy/include modules, and some of the elements are simply sample code that you may find useful for studying to extract a particular function or technique.

The collection has been accumulated over a period of 40 years of my working with the Unisys (formerly Burroughs) MCP platform. Most of this code I have written myself. Where I have included someone else's work, or derived code from someone else's, I have tried to give appropriate credit.

There were a number of Burroughs/Unisys systems that used an operating system named "MCP," including the "Medium Systems" (B2x00/B3x00/B4x00/V Series) and "Small Systems" (B1000 Series). These platforms were discontinued years ago and are now obsolete.

This collection is targeted for the platforms formerly known as "Large Systems" (B5x00/B6x00/B7x00) and "A Series," which were originally derived from the Burroughs B5500, and more recently marketed by Unisys under the ClearPath NX, LX, and Libra names. Since this is the last of the Burroughs architectures still viable, these platforms are now simply referred to as MCP systems.

All of the source code and other data provided by this project, whether marked as such in individual files or not, is protected under the terms of the Simple Public License (SimPL) 2.0. This is a very liberal license, similar to the GPL, and allows you much freedom in the use of the source code and data from the project. Use of these materials in a manner that violates the terms of the SimPL, however, is not permitted. A copy of the license text is included in the download. You may also view the license at the Open Source Initiative web site, http://www.opensource.org/licenses/simpl-2.0.html.

Much of the code in this collection is written in Unisys MCP Extended Algol or one of its variants, DCAlgol and DMAlgol. MCP systems have never had an assembler, and thus Extended Algol is often used as a systems language. It has a large number of extensions that relate directly to the hardware and operating system architecture, particularly in the areas of character manipulation and I/O.

DCAlgol ("Datacom Algol") was originally intended as a language in which to write a Message Control System (MCS), a certain type of communications handler. It supports access to a number of MCP APIs that standard Algol does not, and these days is used primarily to invoke those APIs rather than to write MCSes. DMAlgol was originally designed to support the generative code environment used by the DMSII database management system, and that is still its prime function. It is a superset of DCAlgol, which in turn is a superset of standard Algol.

There are two utilities that properly belong to this collection, but were previously set up under SourceForge as separate projects for the UNITE Source Code Repository, and therefore are not included here. You may find these utilities useful as well:

Installation and Configuration

Download the ZIP file, which contains the source code for the collection arranged in a directory tree. The first node in the tree indicates the type of file (SOURCE, COPY, WFL [batch job streams], etc.). You can extract as much or little of the download ZIP file as you find necessary.

The source files are ordinary text files delimited by carriage-return and line-feed character pairs, but are in what is commonly known as "PWB format" after the Programmers Workbench editor that uses that format. The format is essentially that of the source records as they are stored in the MCP file system, with the CR/LF delimiters inserted between records. Source code files generally have sequence numbers and are padded with spaces to their full length (80, 84, or 90 characters, depending on the programming language).

You can view these files with a standard text editor, but modifying the files with a standard editor generally renders them unusable with PWB. PWB does have an import tool that will accept most text file formats and convert them to the format that it requires, however.

The internal layout of source code records is determined by the FILEKIND attribute of the MCP's file system. See the PWB editor on-line help file for the correspondence between its file name extensions and MCP FILEKIND values, and the discussion of the FILEKIND attribute in the File Attributes Programming Reference Manual for the columnar layout of various types of source files.

As mentioned above, much of the collection is written in MCP Algol or one of its variants. Due to a really strange marketing quirk, Algol and DCAlgol must be separately licensed, but DMAlgol is considered part of DMSII and is bundled with all MCP systems. If you do not have access to an Algol or DCAlgol compiler, you can compile either type of source with DMAlgol instead.

Most of the programs and libraries in this collection can be compiled without special attributes or other environmental considerations. Where the programs reference external files (copy/include modules, server library code files, etc.) you may need to modify the source code to match the disk families and file naming conventions at your site. No particular convention is used or required by the collection itself. See the documentation on the individual elements of the collection for any special compilation or installation considerations.

Index of the Collection

Please note that the collection is still being prepared and the current contents represent just a preliminary set of files. This index is also preliminary and may change form in the future.

Name Class Language Description / Files
BLOCKCHAR Include Algol A procedure to generate 12x12 block letters, as for a printer banner page. The routine generates a line of text using these block letters one row at a time. You must provide a call-back procedure to output the individual rows. An embedded comment describes the routine's parameters and use.
COPY/UTIL/BLOCKCHAR.alg_m
COBOL DATE Include COBOL Working-Storage and Procedure Division COPY modules for manipulating dates, based on the KDAY and KDATE routines of Algorithm 199.
COPY/UTIL/DATE/WORKAREA.c85_m
COPY/UTIL/DATE/PROCEDURE.c85_m
WFL DATE Include WFL A WFL (WorkFlow Language) $INCLUDE module for manipulating dates, based on the KDAY and KDATE routines of Algorithm 199. See http://www.digm.com/Resources/Gregory/Date-Manipulations-in-WFL.pdf for a detailed description of these routines.
WFL/UTIL/DATE/MODULE.wfl_m
DMSHASH Include Algol A procedure, extracted from the Unisys DMSII Accessroutines, to generate the hash value used by the DMSII RANDOM data set. This can be useful for determining the bucket distribution for a set of keys, or for sorting data into bucket sequence before loading a large number of records to a RANDOM data set. The parameters should be self-explanatory.
COPY/UTIL/DMSHASH.alg_m
HEXDUMP Include Algol A procedure that will format data addressed by an eight-bit pointer in the classic side-by-side hex/EBCDIC format. You must provide a call-back procedure to output the formatted lines of the dump. An embedded comment describes the parameters.
COPY/UTIL/HEXDUMP.alg_m
DIR/Nodesort Utility COBOL-74 A program that generates what is essentially a KWIC index across a set of disk directories. Each file in the directories is listed once for each node in its file name. The output is sorted by these node names, so that all file names containing the same node name are listed together. This program was originally written to help find duplicate copies of files across several disk families so that the duplicates could be eliminated and a central copy maintained. A comment in the front of the source describes the format of the input file that drives the program. The program uses Paradigm/Library to search the directory.
SOURCE/UTIL/DIR/NODESORT.c74_m
WFL/UTIL/DIR/NODESORT.wfl_m
LIST/UTIL/DIR/NODESORT.txt
Paradigm/Compare Utility Algol A program that compares two source files and lists their differences to a printer file. The nice thing about this program is that it compares the files while ignoring the sequence numbers and patchmark fields, so it's useful for comparing two versions of a source where at least one of them has been resequenced. The program understands the standard source file formats used with CANDE (based on the file's FILEKIND attribute), and where in those formats the sequence and patchmark files exist, but it can be used with unsequenced data files as well. A comment in the front of the source describes how to run the program and configure its options.
SOURCE/UTIL/PARADIGM/COMPARE.alg_m
Paradigm/GREP Algol Utility A simple utility program that demonstrates use of the PCRE Regular Expression API in the WEBAPPSUPPORT library to search a directory of files looking for records containing a specified pattern. Matching lines are written to a printer file. Detailed documentation is contained in a comment at the front of the source code. Uses the Directory Search Module of Paradigm/Library, below, to enumerate the files in the specified directory.
SOURCE/UTIL/PARADIGM/GREP.alg_m
Paradigm/Library Library DCAlgol An MCP server library containing several modules of utility routines. Most of the routines can be called easily from COBOL-74 and -85 (the date module is an exception to this; those routines can be called from COBOL but require BY CONTENT parameters). Comments embedded in the source describe the routines and their calling sequences. The source must be compiled with DCAlgol or DMAlgol because it uses the MCP GETSTATUS API for directory search. The routines are arranged in the following modules:
Debugging Module
The same HEXDUMP routine included in the COPY/UTIL/= files, but callable as a library routine. This cannot be called from COBOL, as it requires a callback procedure parameter. A default callback routine is provided, WRITETASKFILE, which will dump data to MYSELF.TASKFILE. The HEXSNAP routine is a wrapper around HEXDUMP and can be called from a COBOL program. It dumps to MYSELF.TASKFILE as well.
Character Translation Module
A set of routines, callable from COBOL, which perform character translation. UPCASE translates EBCDIC to its upper-case equivalent. ASCII_TO_EBCDIC and EBCDIC_TO_ASCII perform their eponymous functions. ASCII_TO_EBCDIC_UPPER and EBCDIC_TO_ASCII_UPPER simultaneously translate between characters sets and produce all-upper case output. BUILDXLATE will construct an arbitrary E-mode character translate table. XLATE will use the table created by BUILDXLATE to perform the actual translation.
Date Manipulation Module
A set of date manipulation routines based on the KDAY and KDATE functions of Algorithm 199.
Directory Search Module
DIR_FILELIST will search the disk directory and return all files under a specified directory node, along with a number of attributes for those files. The directory entries are returned in a data structure that can be conveniently accessed by COBOL programs. That data structure has a fixed size, so continuation calls can be made to handle directories that contain many files. A detailed comment describes how to call this routine and the format of the output data structure. DIR_CHANGEFILE is a simple wrapper around the GeneralSupport CHANGELFILE intrinsic function; DIR_REMOVEFILE is a similar wrapper around the GeneralSupport REMOVELFILE intrinsic. See the SOURCE/UTIL/PURGE/FILES program for an example of the use of these routines.
Backup Printer File Module
A set of routines to search for and read MCP printer backup (spool) files. These routines are specifically designed to be called from COBOL programs. BD_FILELIST is somewhat similar to DIR_FILELIST, and can be used to search directories for printer backup files. BD_OPENFILE, BD_CLOSEFILE, and BD_READLINE can be used to access a printer backup file and return the text and carriage control information from each line in the file.
SOURCE/UTIL/PARADIGM/LIBRARY.dca_m
Purge/Files Utility COBOL A program that searches directories for files that have not been accessed in a specified number of days, removing any such files it finds. I typically use this as a system administration tool to clean up old SUMLOG files, printer backup files, and the like. It uses Paradigm/Library to perform the directory search and file remove operations. It can be compiled using either COBOL-74 or -85. It uses an input file to specify the directory names to be searched and the file ages in days. Each directory can have a different threshold age.
SOURCE/UTIL/PURGE/FILES.c85_m
WFL/UTIL/PURGE/FILES
KEYIN Utility DCAlgol My version of the ubiquitous DCKEYIN utility. DCKEYIN is an MCP API procedure available in DCAlgol and DMAlgol that will submit ODT (operator console) commands to the MCP and receive the textual response. The effect is the same as if you had submitted the command on the system console. This version takes a string parameter that contains one or more ODT commands separated by semicolons (";"). If the first character of the string parameter is an asterisk ("*"), the program reads the ODT commands from the file CARD (a READER file by default), one per line. When reading commands from this file, the commands are limited to a maximum of 80 characters. Responses from the MCP are listed on the printer file LINE, preceded by a line with the current date and time.
SOURCE/UTIL/KEYIN.dca_m
COMS/KEYIN Utility Algol A program analogous to the KEYIN utility above, but which submits commands to COMS rather than the operator command interface. This is useful in batch jobs to control COMS entities on a scheduled basis, e.g., enabling and disabling windows or programs at the start or end of prime time. COMS/KEYIN operates by means of the COMS Program Agent Facility (PAF) API. This program takes a string parameter of the same form as DCKEYIN – it contains one or more COMS commands separated by semicolons (";"). If the first character of the string parameter is an asterisk ("*"), the program reads the COMS commands from the file CARD (a READER file by default), one per line. When reading commands from this file, the commands are limited to a maximum of 80 characters. Responses from COMS are listed on the printer file LINE, preceded by a line with the current date and time.
SOURCE/UTIL/COMS/KEYIN.alg_m
LISTER Utility Algol This is a simple program that implements the API for the CANDE Utility (U) command. If compiled as OBJECT/LISTER, you can run it two basic ways:
  • U LISTER by itself will simply list your current workfile to a printer file.
  • U LISTER filename will list the named file.
The CANDE WRITE command will do the same thing, of course, but LISTER will paginate the printer file, adding a page header with the file name, date, time, and page number.

You may wish to change the default page size (see the DEFAULTPAGESZ define) and the attributes of the PRINT file in the source to route the file to your local printer with the appropriate page composition attributes.

SOURCE/UTIL/LISTER.alg_m
UNPATCH Utility Algol This program compares two source files and creates a patch file containing the differences. The files are compared based on their text and sequence number fields. The program is effectively a batch version of the CANDE MATCH filename:F patchfile,R command.

The program reads two source files, the base (original) source file SOURCE and the new (updated) source file NEWSOURCE. The files should be of compatible formats, e.g., Algol/Algol, Algol/Fortran, COBOL74/COBOL85, etc. The differences are written to the file PATCH in a format that is compatible with the MCP SYSTEM/PATCH utility. The TASKFILE attribute determines what type of output is produced:

  • 1 = only the PATCH file is produced.
  • 2 = only a comparison listing is generated to the printer file LINE.
  • Any other value = both patch and printer file are produced (the default).
SOURCE/UTIL/UNPATCH.dca_m WFL/UTIL/UNPATCH.wfl_m
SNTP/Server Utility Algol This program is a very simple SNTP server for MCP systems, based on RFC 4330. It is designed to serve time on small- to medium-size networks, but is probably not suitable for serving time over the general Internet.

Instructions for compiling and running the program are in a large comment at the beginning of the source code. Note that if you are also running the MCP Time Client (NA TIME), the way it binds to port 123 conflicts with this server (at least as of MCP 13.1). Instructions for modifying the Time Client to resolve this conflict are also in that large comment.

SOURCE/SNTP/SERVER.alg_m
TAPUT/MakeTape Utility Algol This program takes a disk byte-stream file that represents a magnetic tape image in ".tap" format, and writes it to a physical tape.

Instructions for compiling and running the program are in a large comment at the beginning of the source code. Note that this program is not capable of creating QIC tapes, due to restrictions in the MCP implementation of those drives.

SOURCE/TAPUT/MAKETAPE.alg_m
TAPUT/Utility Utility Algol This program is a more generalized version of TAPUT/MakeTape. It can read most forms of magnetic tapes and create a ".tap" file from them. It can read a ".tap" file and create a physical magnetic tape.

Instructions for compiling and running the program are in a large comment at the beginning of the source code. Note that this program is not capable of creating QIC tapes, due to restrictions in the MCP implementation of those drives. It can read QIC tapes and create .tap files from them, however.

SOURCE/TAPUT/MAKETAPE.alg_m

Project Participation

We welcome others to participate in this project and to submit corrections, suggestions for new features, and other contributions to the software and documentation. Please contact the Project Admin for information on joining the project.

If you wish to make changes to the source code, 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.

Paul Kimpel

References

Unisys documentation is available without cost on their support web site, http://support.unisys.com.


Revised: 2017-09-03 Project Web Hosted by Get the Paradigm Futilities at SourceForge.net. Fast, secure and Free Open Source software downloads