The UW Tools Software Package Overview

Copyright © 1997, Thinkage Ltd.

Introduction
The B Programming Language
    The Tools Run-Time Library
The BOFF Debugger
The EXPLAIN Subsystem
The FRED Text Editor
The TF Text Formatter
The Secure Command Loader
    Security Features
    Other Features
Modified ACCESS Command
Site Administration Tools

Introduction

The UW Tools package contains a number of utility programs designed to increase productivity at every stage of software preparation: coding, debugging, testing, and documentation.

This manual contains a brief description of all the pieces of software in the UW Tools package. The actual documentation of the package goes far beyond what is presented here, but this should be a suitable introduction for those who have never used the package before.

Most of the material is obtained directly from the explain files.

************************************************************
*                                                          *
*      The EXPLAIN files should always be regarded as      *
*      the "official" explanations for UW Tools soft-      *
*      ware.  This overview is only a supplement.          *
*                                                          *
************************************************************

The reason is that the on-line EXPLAIN files are always going to be more comprehensive, up-to-date, and easy to use than any hardcopy manual. Therefore we suggest that you get to know the EXPLAIN system rather than depending on this manual.

Note that the UW Tools package contains all the software that was formerly in the "Compiler B" package, plus the TF text formatter, the FRED text editor, and several new utility functions.

The B Programming Language

The B programming language was used to write almost all of the software in the UW Tools package. It has proved itself time and again as one of the most versatile languages for writing system software under GCOS-8.

B is a simple language to learn. It supports all modern program logic structures: IF-THEN-ELSE, WHILE loops, SWITCH statements, and so on. Its operators allow programmers to perform all the normal integer, floating point, and character operations, as well as low-level actions like bit shifting, ANDing, and ORing. Because B is a stack-oriented language, recursion is permitted.

B is a "typeless" language. This means that the programmer does not have to declare variables to have a particular type (integer, floating point, etc.). Thus, B gives the programmer more direct control over the low-level operations of the program: how each machine word will actually be used.

B source code is clean and easy to read, without being wordy. The machine code generated by the B compiler is very tight.

B comes complete with a reference manual, a tutorial guide, and online descriptions of all library functions. The B compiler and B programs can be prepared to run under either batch or TSS.

The Tools Run-Time Library

This is an extensive library of utility routines. It naturally includes the basic support required to run a B program, but it also has a large number of utility functions to simplify programs written in B, C or Pascal. There are routines for:

To give an idea of the functionality supported by the UW_TOOLS library, "expl b lib index" gives the index of functions currently in the library. Note that some functions in the library only work under TSS or under batch.

The BOFF Debugger

BOFF is a symbolic debugger designed to help debug any program running under GCOS8. It is particularly useful with programs written in B, since the B compiler produces debug tables that BOFF can use to obtain information about the program and its variables (source line numbers, local variable names, etc.). The C and Pascal compilers also produce tables for BOFF.

BOFF can be used in several modes.

  1. To examine post-mortem dumps of aborted programs.
  2. To "babysit" a program as it runs.
  3. To patch locations in load modules (or any other kind of file).
  4. To profile a program's execution.
  5. To act as an expression evaluator, printing out the results of expressions in a variety of formats (octal, decimal, hex, BCD, ASCII, etc.).

BOFF allows you to perform the following actions for debugging:

Of course, some of these commands are not appropriate in some modes (e.g., you cannot obtain a traceback when you are simply patching a file, since nothing is or was executing). BOFF operates in TSS.

The EXPLAIN Subsystem

The EXPLAIN subsystem is a facility for providing on-line documentation on a variety of topics. The documentation for the Tools package is all available through EXPLAIN. As part of the standard installation procedure, this material is stored under the catalog LIBRARY/EXPL where the EXPLAIN command may locate it at a user's request. Sites may add their own material to LIBRARY/EXPL or modify the standard explanations to suit individual needs.

The FRED Text Editor

FRED is a line editor descended from the QED editor. It allows all the usual interactive editing operations: creating, deleting, modifying and saving text, global substitutions, and the like. In addition, it can be used to write sophisticated text manipulation programs. Our current library of stored FRED programs includes programs to play tic-tac-toe, to convert RUNOFF source into source for our TF text formatter, to generate and run an EXEC file to copy a catalog, and so on.

Some of the features that distinguish FRED from other editors are:

FRED comes complete with a reference manual, a tutorial for beginners, and a more advanced guide to writing FRED programs. FRED operates under TSS.

The TF Text Formatter

TF is a sophisticated text formatter supporting macro facilities that allow programmers to design their own formatting instructions. In this way, simple packages can be created so that even those who know nothing about TF can create well-formatted documents that conform with company standards.

TF source looks much like RUNOFF source, but TF offers a much larger choice of directives. For example, TF lets you eliminate widows and orphans, those annoying single lines at the tops of bottoms of pages, cut off from everything else. It also supports input and output diversions, the ability to call and obtain output from system commands, limited arithmetic capabilities, the creation of proportionally-spaced output for devices that have proportional spacing, and a variety of other features.

TF comes with a reference manual, tutorial guide, and a library of ready-made macro packages. It runs in both batch and TSS.

The Secure Command Loader

The Software Tools package brings with it a new command loader designed to be more secure than the stock command loader.

Security Features

The stock command loader associates privileges with individual users. A program inherits the privileges of the user who invokes it. While this seems straightforward at first sight, it has a number of drawbacks.

The most important of these is that it frequently places system administrators in an "all or nothing" position when allocating privileges. There are only a few command permissions that the GCOS8 system recognizes. Thus, each permission class gives a user fairly wide reaching privileges in a particular area. If a user has a legitimate reason for running a task that needs a particular privilege type, the administration usually has to give that user permission to run any task that needs that particular permission, even though most such tasks will have no relevance to the work that is being done. The alternative is to refuse all privileges to the user, thereby preventing him from using the few privileged actions which are pertinent to his work.

In addition to this "all or nothing" problem, there is always the possibility of "Trojan Horse" programs. This kind of security violation first turned up in Dartmouth University, on a system where permissions were associated with individual users. A Trojan Horse seems to be a simple program written by an individual user to perform any useful function. If the program is useful enough, it will eventually be tried by a privileged user who wants to avoid writing his own program to do the same thing.

This is when the Trojan Horse is finally activated. The program checks the permissions of the person who called it, finds out that it is suddenly heir to all the user's permissions, and thus has access to all the associated privileges. The opportunities for security violations are obvious.

The UW Tools command loader has a different attitude towards command privileges. Privileges are associated with programs instead of users. A program need not receive any privileges until the system administrators decide that the privilege is valid. At this point, they know what the program does. Instead of giving carte blanche to a particular user, the administration simply gives enough privileges to a program for the program to do what it has to do. The program does not receive special permissions until the administration is satisfied that it can be "trusted".

Once a program has been granted whatever privileges are pertinent, access to the program can be restricted using the standard file system permissions. Only those people with a need to perform the associated operations will be granted EXECUTE permissions on the file that contains the program. Some users may still need to be given personal privileges, but the number of privileged users is sure to be smaller.

Beyond the advantages of increased security, the UW Tools command loader offers the opportunity for increased flexibility of the GCOS system. For example, on a stock GCOS8 system, a normal user cannot get a list of all the batch jobs he is running. Checking up on your own jobs doesn't seem to be a security problem...and yet, the system does not keep a list of the jobs you have submitted, and therefore the only way to obtain such a list is to check all the jobs that are in the system and extract those that are running under your account. Unless you are given permissions to check up on everyone, you can't even check up on yourself.

With the UW Tools secure command loader, this sort of absurdity is avoided. The Tools package includes a command that can check the jobs in the system and make a list of those jobs that are running under the account of the user who invoked the command. The administration gives the necessary privileges to the command itself, not the user; there is no security problem because the administrators don't grant the privileges until they are sure that the command does what it's supposed to and nothing else. In this way, the command has the privileges needed to tell a user about his own jobs but it does not tell about anyone else's. The administration gives users the right to use this command by putting general EXECUTE permissions on the file that contains the command. The user is better off, and security is not compromised.

There are several other similar kinds of actions which are not unreasonable but which must be restricted because of privilege problems. With the UW Tools package, one can avoid such restrictions because of the security of our command loader.

As an example, the BAFT command allows you to determine the full pathnames of the permanent files currently accessed in your AFT. (AFT stands for "Available File Table", files that you have legitimately accessed and are holding ready for use. Such files are often given alternate names for one reason or another when placed in the AFT; thus it is easy to forget the real file names.) Since you have already accessed the files legitimately, there is clearly no security violation in reminding you of the file's real name; but on a stock system, the ability to determine these real names requires privileges that most users do not have. Again, the stock system forces the administration to grant programmers "the keys to the kingdom" or else to refuse programmers the ability to perform an operation that frequently comes in handy.

Other Features

The secure command loader has more extensive search rules than the stock command loader. When the loader is attempting to find a file to execute, it looks at your quick access files and the files in your AFT, as well as those under "cmdlib".

If you make a mistake entering a command name, there is some chance that you may accidentally match the name of some file under your current directory. To avoid the accidental execution of files that do not really contain programs, the command loader will not execute a sequential file as a command file unless it has been given one of the file characteristics

use/crun/
  or
use/exec/
  or
use/fred/

This is done with the command

access mf filename,use/crun/
           or
access mf filename,use/exec/
           or
access mf filename,use/fred/

The USE characteristic tells the command loader that the sequential file is a command file and should be executed with CRUN or with the UW Tools commands EXEC or FRED. If this characteristic is not present, the command loader will not execute a sequential file.

Some users may be inconvenienced by this when the release is first put up, since they will be used to executing command files simply by typing the name. The tools package makes it very easy to add the USE characteristic to existing command files. For example, the following pair of commands put USE/CRUN/ on every sequential file that is found immediately under "cmdlib".

files cmdlib mode=seq l=1 >xx
eo f=xx "access mf #1,use/crun/"

Site administrators should do this as soon as they install the UW Tools package.

With the secure command loader, LODX permission is not required to run a user hstar. This does not represent a breach of security, since an unprivileged user could get around the LODX restriction (by using the FRN command, for example). The change in the command loader just makes it more convenient to do something the user could do anyway. It also frees the LODX permission bit for any other site-defined use.

Modified ACCESS Command

A modified version of ACCESS is distributed with the package in order to support some of the features of the Secure Command Loader. This ACCESS has other important enhancements:

The Utilities

Below we summarize the arsenal of utilities that come with the UW Tools package. After the summary comes a fuller description of each utility. For the most part, the descriptions are drawn directly from the online documentation that comes as part of the package.

ACS
A command to print a user's resources and limits. This is basically an improved SMCL command that prints change dates and handles UMC's on removeables or volume sets.
ASM
A program for submitting GMAP assembly jobs from TSS.
BAFT
A better AFT command that can list the contents of the AFT, including full names of permanent files.
BCMP
A block mode file compare utility.
BPP
A simple macro preprocessor for B programs.
BSORT
A versatile utility for sorting files according to multiple keys.
BST
A disassembler for object decks.
BTEMP
A better TEMP command that can be easily used by command files and other programs.
BTOG
A program for converting B source code into GMAP assembly code.
BUCK
A TSS command that tells what FMS bucket contains a given userid.
BW
A TSS command that will return the current of all batch jobs submitted by a specified user.
CLIS
A command that lists the "characteristics" of one or more files or catalogs: general permissions, specific permissions, current size, maximum size, creation date, change date and time, number of accesses, disk location, label on tape of most recent back-up, and whether a file is random or sequential.
CLONE
A command to copy a file or entire catalog along with permissions and other FMS attributes.
COPY
A utility for copying any kind of file.
CSUS
A program that temporarily suspends a CRUN session and runs another command.
DIFF
A program that determines the differences between two text files.
DSTA
A program for examining the status of DRUNs.
ECHO
A utility that echoes its arguments to the terminal or an output file.
EO
A way of repeatedly executing commands while obtaining parameters for the commands from an input file.
EVAL
A command that evaluates arithmetic, logical, and string expressions.
EXEC
A facility similar to CRUN for conditionally executing a file of TSS commands.
EXPL
A command that is capable of obtaining on-line documentation and listing it in a convenient readable form.
F77
A TSS command for invoking the Fortran 77 compiler.
FDP
A program for dumping the contents of files in readable formats.
FILE
A utility for listing the names of all the files under a given catalog; the command can also list just the files that have a certain characteristic, e.g. all files that have been changed since a particular date.
FSTT
A program that returns fuller explanations of derail status codes.
FTN
A program for invoking the Fortran 66 compiler.
GO
A program loader for programs in B, C, or Pascal.
GROW
A command to grow a file.
IF
A command that executes a list of TSS commands, depending on the result of a logical expression.
KLIS
A program for columnating input and optionally writing the result to the line printer.
KWIC
A program to produce a "key word in context" list.
L
A command for listing the contents of almost any kind of file (e.g. text files, freeze files, qstar files, mailboxes, and others).
LC
A command that gives a concise listing of the contents of a catalog.
LEN
A utility to determine the length and type of a file. This is similar to the stock LENGTH command, but recognizes many more file formats.
LINK
A command to invoke GELOAD as a DRL TASK job.
LOCA
A utility that scans one or more text files and prints out windows around lines that contain a particular string of characters.
LODL
An editor for libraries of load modules.
LOWE
A command for putting all the alphabetic characters of an ASCII file into lower case.
OMINFO
A command for obtaining information about OM object module libraries.
OMLED
A command for editing OM object module libraries.
P
A utility for printing the contents of text files in a fully-readable format.
RANE
A command for editing a random object (GELOAD) library. RANE works in both batch and TSS.
RENAME
A command to change the AFT name of a file.
RUED
A command for editing RU (run-unit) libraries.
SETC
A command to set the working catalog with checks for common errors such as missing passwords and non-existent pathnames.
SHRINK
A command to shrink the physical size of a file down to the file size that is actually being used.
SLIS
A command that will print the contents of temporary or permanent files on the line printer.
SRCL
A command for editing source libraries (COBOL74 copy libraries).
STRP
A program for stripping trailing blanks and sequence number fields from text files.
SWAP
A utility for switching the position of programs on the CALLSS stack.
SWIT
A utility to set and display both program switch words.
TAIL
A command to display the last few lines of a file.
TIME
A command that prints the current date and time of day. It can also be used to time the execution of other commands.
TSYST
A batch utility to write system insert/edit tapes from Q* files.
TZDATA
A command to process time zone definitions that can then be incorporated into B programs.
UNCL
A command that will examine an object library to determine which of the routines in the library reference a particular SYMDEF.
UNIQ
A command to remove duplicate lines from a file.
UPPE
A command that converts a text file into upper case.
WC
A utility to count characters, words and lines in a file.
WHER
A command that can be used to determine the name of someone who has currently busied a particular file.
WMI
A command to display the current userid, system name, and working catalog.
WS
A command that will execute a set of one or more TSS commands upon each file in a given catalog.
YAY
A program that generates language parsers -- a simple source format allows users to specify a language and what actions should be taken when language constructs are recognized. The output of YAY is either B or C source code that can then be compiled to obtain the actual parser.

Site Administration Tools

The UW_PRIV userid contains supplementary commands to perform site administration. Such operations should be restricted to site adminstration personnel. Privilege bits (e.g. LODS) are not required to run programs which are found under UW_PRIV; all you need are FMS permissions to execute the appropriate file. For this reason, permissions on the userid and its files must be strictly controlled.

The sections that follow describe the programs currently distributed under UW_PRIV. Explain files for these programs can be obtained from "expl uw_priv index".