 README.1ST       Directory: [307,20]

 U. S. Geological Survey
 Menlo Park, California

 USGS Submissions for the Fall 1982 RSX/IAS SIG DECUS Symposium Tape
 -------------------------------------------------------------------

     We are pleased to submit our contributions to the Fall '82 tape, and
hope you will find them useful. Some of our programs were previously
submitted to the SIG tapes, but that was several versions ago of RSX.

     All of these submissions have been tested on an 11/70 running 
RSX-11M-PLUS V2.0 and on an 11/23 running RSX-11M V4.0. With any luck,
all of the programs will run on V2.1 / V4.1 without modification. If
they don't, please write me at the address below for patches.

     To build the entire kit requires about 1700. blocks of disk space
on the device where the kit is loaded.

     Our distribution is contained in one UIC, [307,20]. The files included
in this UIC are:

       README.1ST      - The file you are reading now
       USGSF82.CMD     - Command file to generate the USGS kit
       USGSF82.ULB     - Universal library containing the kit
       USGSF82.DOC     - Documentation on generating and using the kit

     To generate the kit, copy the entire UIC to any UIC of your choosing,
and enter:

       >@USGSF82

     The command file will try to locate all necessary system files. It
will ask for help if it can't find what it needs. If your system files
are in strange places, you just might have to modify the command file.

     The command file may be invoked in "batch" mode from another command
file. The global symbol $AUTO must be set to True, and there are other
environmental symbols which may be defined to assist the command file.
(Undefined symbols will be assigned default values which normally work.) In
this mode, the command file runs without interaction. See the comments
in USGSF82.CMD describing this mode.

     I apologize for not supplying Help files for our submissions. All
of our programs (except DVCDAT) recognize a special switch, /HE, to print
out a page of information on the issuing terminal. I hope that suffices.

------------------------------------------------------------------------------

Our submissions:

     CSH (Checkpoint Space Handler)

     This program was briefly mentioned by me at the Spring '82 Atlanta
Symposium Magic Session. This program allows you to examine the size and
contents of your system checkpoint files, and will forcibly deallocate
the checkpoint file if you need to dismount the disk (ACS simply marks
the file for deallocation; you have to wait for all checkpointed tasks
to be loaded into memory, which can take forever on M-PLUS systems.)

    -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

     CWD (Change Working Directory) and PWD (Print Working Directory)

     This is the program that has been mentioned several times at the
"Best of the SIG Tape" sessions. CWD allows you to conveniently change
your default device (SY0:) and/or current UIC (much like the "cd" command
on Unix(TM)). For example,

        >Cwd DL2:104,4   is the same as:    >Asn DL2:=Sy0:
                                            >Set /Uic=[104,4]

     Cwd also prints the available space on SY0:, and checks to make
sure you have a directory in your new UIC.

     The PWD command simply prints your current working directory, along
with free space statistics on SY0:

     Caution to privileged users: before using CWD from a CLI other
than MCR, please read the release notes in USGSF82.DOC before proceeding
any further.

    -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

     DVCDAT (Device Database Display Program)

     This is a utility written by Jim Neeland of Hughes Research, and
modified by Larry Baker of USGS to run on M-PLUS. DVC takes a single
argument, a device specification, and dumps the driver database on the
user's terminal. The offsets are labelled symbolically in a most
readable format. This program is almost essential for anyone working
on a device driver.

    -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

    SNAP (Snapshot Utility Program)

    This is a catchy little program which tells PMD (the Post Mortem
Dumper) to produce a snapshot of any (well, almost any) task on the
system. With command switches, you can specify up to four pairs of
memory address limits to have PMD dump, along with other goodies.
After PMD is finished, the task that was "Shot" resumes on its merry way.
If the RMDEMO task header display doesn't give you all the information
you need, try using SNAP.

    -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

    WHO (System Activity Utility)

    How many incarnations of this program exist? We lost track, but
we went ahead and resubmitted ours. WHO prints the terminal ID's, user
names, and active tasks for each logged in terminal on your system.
Each task can have one of eight "status" codes showing what each task
is up to. When your system slows down, this command quickly spots the
guilty parties.

    WHO can also quickly scan your account file looking for a particular
user or UIC.

------------------------------------------------------------------------------

    For quirks and problems with the programs in this kit, please read
the release notes in USGSF82.DOC. If you really get stuck, please write
to me at the following address:

         Gary L. Maxwell
         U. S. Geological Survey
         345 Middlefield Road  M/S 77
         Menlo Park, California   94025

