.in 5
.rm 70
.pl 62
.he //RSX Cover Document/
.fo //-#-/
.bp
.ce
FINALLY
.sp 3
The long-awaited (I hope you think it was worth it!)
RSX-11M version of the LBL software tools virtual
operating system is ready.  This note describes the system,
and in particular, the new features added during RSX
developement.  A companion note describes the mass storage
requirements, run-time requirements and the installation
procedure.
.sp
The following utilities are available in the RSX system:
.sp
.nf
.in +5
ar ....... archive file maintainer 
args ..... concatenate standard input to arguments for command
asplit ... salvage garbaged archive files
cat ...... concatenate and print text files 
ccnt ..... character count
cd ....... change working directory
ch ....... make changes in text files 
cmp ...... compare two files 
comm ..... print lines common to two files
convrt ... convert pip listing files to LIST carriage control
cpress ... compress input files
crt ...... copy files to terminal
crypt .... crypt and decrypt standard input
date ..... print the date
dc ....... desk calculator
detab .... convert tabs to spaces
dspc ..... display all characters in a file
echo ..... echo command line arguments 
ed ....... text editor 
entab .... convert spaces to tabs and spaces
expand ... uncompress input files
fb ....... search blocks of lines for text pattern
fc ....... fortran compile and task-build image
fel ...... task to destroy process tree and return to shell
field .... manipulate fields of data
find ..... search a file for a pattern 
form ..... generate form letter
incl ..... expand included files 
intro .... list on-line documentation
kwic ..... make keyword in context index
lam ...... laminate files
lcnt ..... line count
ld ....... task-build image
ll ....... print line lengths
ls ....... list contents of directory
macro .... process macro definitions 
mail ..... send/receive mail
man ...... run off section of users manual
mcol ..... multicolumn formatting
msg ...... manipulate message files
msplit ... salvage lost message files
mv ....... move (or rename) a file
os ....... overstrike - convert backspaces into multiple lines
pl ....... print specified lines/pages in a file
postmn ... see if user has mail
pr ....... paginate files to standard output
pwd ...... print working directory
rat4 ..... ratfor preprocessor
rc ....... ratfor compile - preprocess, compile and task-build
resolve .. resolve mail users
rev ...... reverse lines
rm ....... remove files
roff ..... format text 
sedit .... stream editor
sh ....... shell (command line interpreter)
shl ...... installed version of shell for easy MCR invocation
sort ..... sort and/or merge text files 
spell .... find spelling errors
split .... split a file into pieces
tail ..... print last lines of a file
tee ...... copy input to standard output and named files
tr ....... character transliteration 
tsort .... topologically sort symbols
uniq ..... strip adjacent repeated lines from a file
unrot .... unrotate lines rotated by kwic
users .... list valid mail users
wc ....... count lines, words and characters in files
wcnt ..... (character) word count
xref ..... make a cross reference of symbols
.in -5
.fi
.sp
Writeups on each of these utilities may be had by executing the
man command in the shell.  The following comments describe new
features not reflected in the man entries:
.sp
.in +5
.ti -4
cd: change working directory is supported.  See companion document
on pathnames for legal input to cd.  Note that the synonyms cwd and
chdir are
not
supported.
.sp
.ti -4
ed: ed can handle files up to 750 lines only, due to the 32 kW task-image
limit.  Note that ed prompts for input commands, with a switch to change
this prompt.
.sp
.ti -10
fc,ld,rc: are available in RSX-11M.  The manual entries are essentially
up-to-date.
More information on fc and ld may be found farther on in the section
entitled "Tools Disk Structure".
.sp
.ti -7
intro: displays a list of available tools on STDOUT.
.sp
.ti -4
ls: lists structure-level-1 directories.  ls understands the regular
expressions of find,change and ed, thus permitting such examples as
.sp
ls %a ......... lists all files starting with the letter a in the
current working directory
.br
ls tst ......... lists all files with the characters tst anywhere in
the file name
.br
ls ";1$" ....... lists all files with version number 1
.sp
.ti -5
man: is a real utility now, as opposed to being a script file.  If no
arguments are present, man displays the writeups for all of the utilities
(those listed in intro).  If arguments are specified, then the writeups
for those utilities are displayed.
.sp
.ti -6
rat4: the string declaration has been added.  The rules for its use are:
.sp
.in +5
.ti -3
1. All string declarations in a module must be grouped together.
.ti -3
2. The group of string declarations must appear after all other declaration
statements and before any data statements.
.ti -3
3. The format of the string declaration is
.sp
string name "abcdefghij"
.sp
name is the name of the character array declared.  The value of name
may be delimited by single(') or double(") quotes.  name may be used
anywhere a character variable array can be used.
.sp
.in -5
.ti -4
sh: A bare input line of ? directs the user to help in using the system.
Command lines starting with # indicate a comment, thus allowing
scripts to be commented.
^BACKGROUND PROCESSES ARE ONLY IMPLEMENTED ON RSX11M V3.2
Several commands internal to the shell have been added:
.sp
.in +6
.ti -5
home set current directory to home directory
.ti -4
xon equivalent to -x switch
.ti -5
xoff inverse of xon
.ti -4
von equivalent to -v switch
.ti -5
voff inverse of von
.sp
.in -6
The standard search path for the shell when resolving commands is as
follows:
.sp
.in +5
.ti -3
1. current directory
.ti -3
2. home directory
.ti -3
3. usr directory [105,2]
.ti -3
4. bin directory [105,1]
.sp
.in -5
In each directory, the routine loccom (the source code is on osprim.w/osprim.r)
attempts to find a file with a null extension (shell script files) and a file
with a .tsk extension.  If a file is found in this search path, its type
(character or binary) is determined and the appropriate action is taken;
otherwise, the command is handed to MCR for execution as is.  A command may
be explicitly given to MCR through the use of the "x" command as

% x help

for example.  The auto-dropthrough feature may be turned off by specifying
the -d switch when invoking the shell.
.in -5
.sp
.he //Files and Pathnames/
.bp
The following are legal file specifications to any tool requiring
one:
.sp
.in +10
.nf
file.ext;version
[ggg,mmm]file.ext;version
ddnn:[ggg,mmm]file.ext;version
/ggg,mmm/file.ext;version
/ddnn/ggg,mmm/file.ext;version
.fi
.in -10
.sp
Note that ddnn:file.ext;version is not legal.
.sp
Valid inputs to cd are the last four above, with the file.ext;version
removed.  Again note that ddnn: is not valid.
.sp
None of the utilities assume a default extension, so a filename typed
without a period is assumed to have a null extension.  The semicolon is
a special character to the shell, so it must be escaped with an @ when
a file version number is explicitly specified in a command line typed to
the shell.
.sp
When a file is opened at WRITE access, the most recent version of the file
is overwritten.  In particular, the following command is to be eschewed,
since it may garbage up your file:
.sp
.ti +10
tool <file >file
.sp
.he //Tools Disk Structure/
.bp
.ce
On disk structure of the Tools VOS
.sp 2
As currently implemented, the Tools VOS uses six consecutive members
of one group on the
disk where it resides (ST0:).  The system built at LBL uses group
105 - i.e. [105,*], but this is something that can be tailored during
installation.  Assuming the group used is 105, the current assignment
of UIC's is as follows:
.sp
.in +8
.ti -8
[105,1] main tools directory; all system task images as well as script
files reside here
.ti -8
[105,2] site-dependent tools and scripts go here.  This directory is
part of the normal search path for the shell (current working directory;
ST0:[105,1]; ST0:[105,2])
.ti -8
[105,3] scratch files created by the tools go here.
.ti -8
[105,4] files formatted by lpr go here (not yet implemented)
.ti -8
[105,5] mail directory: the mail data-base is kept here.
.ti -8
[105,6] the directory where man entries reside.
.sp
.in -8
The bare minimum on [105,1] for a working tools system is *.tsk, dict., intro.,
mymail., mymail.bld, summary., rlib.olb, spell., msgprim., msgtest., msgprm.
and symbols.  This set of
files occupy ~6100 disk blocks.  [105,6] is also essential for the man
command.
.sp
The tools do their own I/O with FCS calls, with the only reliance
upon Fortran being the use of the $FCHNL entry point to retrieve
the FDB address for a lun.  (Note:  if you are running F4P v.3.0 with
the RMS library, you will have to edit gtfdb.mac before doing the
system generation.)
The runtime system provides for 6 concurrent open files, using
luns 1-6.  Lun 7 is a scratch lun used by the runtime system, and lun 8 is
always assigned to TI:.  Each tool attaches TI:, so that ^O works correctly.

The ld tool generates an indirect command file for TKB and spawns TKB to
build the resulting task image.  Given that the current working directory is
dk0:[101,1] and the following ratfor source file called hello.r:
.sp
.in +5
.nf
subroutine main

call remark("Hello world.")

return
end
.in -5
.fi

An rc command line of "rc -c hello.r" will generate hello.obj, and an
ld command line of "ld hello" will generate a TKB command file
in the following sequence:

.in +5
.ti -3
1. ld generates the following lines on the file (assuming F4P)
.nf
dk0:[101,1]hello.tsk;1/fp/cp=
dk0:[101,1]hello
ST0:[105,1]rlib/lb:.main.
ST0:[105,1]rlib/lb
.fi
.ti -3
2. ld then appends the file st0:[105,1]tools.tkb to the command file.  The
version of this file delivered on the tape consists of:
.nf
/
units=8
actfil=6
//
.fi
.in -5

If the site supports an FCS resident library, or wishes to link to a modified
Fortran library for the tools, the appropriate changes may be made to the
tools.tkb file.  In particular, the following one is used by the author:

.in +5
.nf
/
units=8
actfil=6
libr=fcsres:ro
//
.fi
.in -5

In order to assure correct linkage with the
FCSRES, lb:[1,1]fcsres.stb was patched so that word 26(octal) is the
characters ESK in rad50 instead of ESL. (FCSRES was built as it comes on
the distribution.)  One of the tools (ls) needs the ".XQIO" entry point from
the resident library, and this patch assures that any globals not in the
resident library will be linked in correctly.
.sp
.ce
Structure of the Distribution Tape
.sp 2
The distribution tape, unless specifically requested otherwise, is a 9-track,
800 bpi, DOS-format tape created with FLX.  Four UIC's are represented:
.sp
.in +9
.ti -9
[307,30] command file to install the tools, this document, and a working
task image for FFL, the fast filex utility
.ti -9
[307,31] the fortran and macro sources for building the system, along with
all script files necessary for the system to run.
.ti -9
[307,32] the pre-roffed manual entries for use by the man command.
.ti -9
[307,33] ratfor source code for the system,
as well as roff input files for various documentation on the tools.
.in -9
.he //Run-time Requirements of Tools VOS/
.bp
One global logical device name must exist - ST0:.  As one might
expect, this merely points to the disk where the tools directories
reside.
.sp
For ease of use, it is suggested that the task sh.tsk on the tools
directory be installed with the name "...SHL".
.sp
The task fel.tsk on the tools directory must be installed with the
taskname "...FEL".  FEL allows the user to kill all subtasks created by the
shell invoked
from MCR.  The way to do this is:
.sp
.in +5
.ti -3
1. Type ^C and wait for the MCR> prompt.
.ti -3
2. Type FEL and wait for the termination messages from the subtasks.
.sp
.in -5
If your terminal is currently operating in half-duplex, and the bottom task
in the tree is reading your terminal, you may have to type a carriage return
in order to get the termination messages onto your screen.  You should see
a shell prompt (%) when all is done.  If you do not wish to see an extra
MCR prompt (>), then terminate the FEL line with an ESCAPE.
(The name fel[l] is to depict the felling of the process tree hanging
from the login shell.)
Fell acts by sending a message to the task named $Tnn.1, which is the name
given to the login shell's child.  This task propagates the chain of messages,
and each task in the tree will die, printing a message on the user's terminal.
.sp
Due to the large task images of the tools, and the way that shell scripts
are performed (a copy of the shell is spawned reading the file as its
standard input), the checkpoint file[s] is heavily used.  In particular,
it must be quite large.  A reasonably safe assumption is 500 blocks per
simultaneously active tools user.  I realize that this may be a hardship
for some installations, but little can be done to alleviate the
problem. (Moral: one pays for portable code and functionality!)
.he //Installation Guide/
.bp
The installation command file ([307,30]kitbld.cmd) normally uses FLX
on the distribution tape.  If your system does not have a 9-track
tape drive, it will be necessary to copy the necessary UIC's from the
tape onto some compatible disk medium (RK05 or larger) at another
site.  To do so, perform the following steps:
.sp
.nf
1. Login under a priveleged account
2. Mount your disk pack to copy onto
3. Allocate the drive, initialize pack (if necessary), and mount it
4. Ready distribution tape on tape unit (following assumes MM0:)
5. Set /uic=[?,?] for copying FFL (fast filex)
6. FLX /RS/BL:35.=MM0:[307,30]FFL.TSK/DO
7. INS FFL
8. If the target disk(DDn:) is larger than an RK05
8a. FFL DDn:/UF/FO=MM0:[307,*]*.*
9. If the target disk(DKn:) is an RK05
9a. FFL DKn:/UF/FO=MM0:[307,30]*.*,[307,31]*.*,[307,32]*.*
9b. PIP DKn:[307,*]*.*;*/TR
9c. FFL DKn:/UF/FO=MM0:[307,33]*.*
.fi
.he //Installation Procedure/
.bp
.in +5
.ti -3
1. Login under a priveleged account
.ti -3
2. Ready tape or disk with the distribution on it
.ti -3
3. Select UIC to copy kitbld.cmd to
.ti -3
4. if (distribution on disk)
.ti +5
PIP *.*=DISK:[307,30]KITBLD.CMD
.br
else
.ti +5
FLX /RS=TAPE:[307,30]KITBLD.CMD/DO
.ti -3
5. Make sure target volume is initialized and mounted
.ti -3
6. @KITBLD
.ti -3
7. Answer all questions
.ti -3
8. Peruse the ST0:[GRP,MEM]TOOLS.CMD file which has been displayed on
the console.  This is the suggested tools-specific startup file.  The
following comments are in order:
.sp
.in +3
.ti -3
a. The GBL logical name assignment is essential
.ti -3
b. Installation of shl is suggested
.ti -3
c. Installation of fel is essential
.ti -3
d. Running of shl -c "addr | sort >st0:[105,1]address" assures that
the mail database is current with ACNT's database.
.sp
.in -3
.ti -3
9. If you are satisfied with the tools.cmd file as is, or after removing
offending, non-essential parts, the following four steps are necessary:
.sp
.in +3
.ti -3
a. >SET /UIC=[1,2]
.ti -3
b. >PIP *.*=ST0:[GRP,MEM]TOOLS.CMD
.ti -3
c. >@TOOLS
.ti -3
d. >using your favorite editor, place the following line somewhere in
[1,2]startup.cmd before the terminals are enabled for users to use:
.sp
@LB0:[1,2]TOOLS
.sp
.in -3
.ti -4
10. Now you are finished
.sp
.in -4
.he //What is KITBLD doing?/
.bp
.in +4
.ti -3
1. Determines
.in +3
.ti -3
a. Target device and unit (LB0 is suggested, if there is room)
.ti -3
b. Tools group number (default is 105)
.ti -3
c. Member number for tools binary directory (default is 1)
.ti -3
d. If building from tape or disk, and input device and unit
.ti -3
e. If F4P will be used
.ti -3
f. If the OTS for the compiler is in LB:[1,1]SYSLIB.OLB
.ti -3
g. If not, file specification for the OTS library - eg.
LB0:[1,1]FOROTS.OLB
.ti -3
h. If not using F4P, should the tasks be built /FP
.ti -3
i. If the tasks should be linked with an FCS resident library
(see comments on page 6).
.ti -3
j. If so, the name of the resident library (FCSRES).
.ti -3
k. Should fortran and macro files be deleted after use (saves ~1100
blocks on target disk)
.ti -3
l. Should object files be deleted after use (saves ~1600 blocks
on target disk)
.in -3
.ti -3
2. Copies the necessary files from the distribution
.ti -3
3. Assures contiguousness of .tsk files from the distribution
.ti -3
4. If the binary directory is not [105,1], uses chs and rt4 to modify
the site-dependent primitive functions in sitepr.r.
.ti -3
5. Uses lss and chs to generate an indirect command file for the assembler
to assemble all of the .mac files.
.ti -3
6. Fortran compiles the primitive functions written in ratfor
.ti -3
7. Creates the ratfor library, RLIB.OLB
.ti -3
8. Builds all of the tasks
.ti -3
9. Builds the manual directory from the distribution medium
.ti -4
10. Builds the mail database
.ti -4
11. Creates each account's mymail. file with the correct protection.
.ti -4
12. Displays the site's tools.cmd file
.in -4
.sp
On a non-loaded system, the system generation takes approximately
90 minutes.
.he //Source File Structure/
.bp
.ce 1
(How to rebuild the damn thing if I don't like it!)
.sp 2
The source code for each tool is contained on the tape under [307,33]tool.w.
This file is all the environment
necessary to rebuild the tool, provided that the tools VOS is running, of
course.  The tool.w file (except for ed, msg, rat4 and sh - see below)
is an archive containing:
.sp
.in +5
.ti -3
1. All files included in the rat4 source file
.ti -3
2. The rat4 source file, tool.r
.sp
.in -5
Suppose that you wish to change the subroutine "module" in "tool".  The
suggested scenario is as follows:
.sp
.nf
>shl
% flx /rs=mm0:[307,33]tool.w/do
% ar xv tool.w
% ar xv tool.r module
% ed module
(make changes and write file)
% ar uv tool.r module
% rc -v tool.r
% test out new version of tool.  Repeat the last three steps
until satisfied
% ar uv tool.w
% pip [105,2]tool.tsk=tool.tsk
% cat tool.w >/105,2/tool.w
.fi
.sp
Placing the tool in [105,2] means that the shell will now find your
version of the tool in  [105,2], the site-dependent tool directory.  It is
a good idea to keep the modified source in [105,2] also, since you may
need it to track down a bug found by your local bugfinder person.
.sp
Rat4, msg, sh and ed are a little trickier, since the source code is so large as
to cause the archiver to overflow if the previous tool.w structure is
attempted.  For these tools, the ".w" archive contains:
.sp
.in +5
.ti -3
1. toolcbl - an archive of the included files
.ti -3
2. each individual source module for tool
.sp
.in -5
In the main tools directory [105,1], a file bigbld is available to
automatically build the tool from this type of archive.  Suppose you wish
to modify the shell. Then
.sp
.nf
% flx /rs=mm0:[307,33]sh.w/do
% ar xv sh.w module
% ed module
% ar uv sh.w module
% bigbld sh
% pip [105,2]sh.tsk=sh.tsk
% cat sh.w >/105,2/sh.w
.fi
.sp 2
.ce
Source Differences for FOR vs. F4P
.sp
The source code for the system is identical for both compilers with two
exceptions - fc and ld.  The fc utility, which spawns the compiler as
a subtask, comes in two flavors on the source uic [307,33]: fcfor.w and
fcf4p.w

FCF4P generates the following command line for
F4P
.sp
F4P A,A=A.F/NOTR
.sp
All of the tools primitives and utility source code will be compiled
with the NOTR option.  If a different default is desired, modify the
source code for the routine fortrn in fc.w, after copying fcf4p.w into
fc.w.

FCFOR generates the following command line for FOR
.sp
FOR A,A=A.F/NOSN/NOVA/NOLO
.sp
If this is undesirable, then follow the same procedure as for F4P except
copying fcfor.w to fc.w

The ld utility, which builds a tool task image, also comes in two varieties
on the source uic: ldfp.w and ldnofp.w.

LDFP places a /fp switch after the task image name in the TKB
indirect command file.

LDNOFP places a /-fp switch
after the task image name.  If you are building a FOR system,
but using the FPP or FIS libraries, simply answer the kitbld question
"DO YOU WANT THE TASKS BUILT /FP?"
in the affirmative when building the system.

The task images on [307,31] have been compiled with FOR generating threaded
code and linked with the EIS library, since it was felt that these images
would then run on all systems building the tools.
.he //Adding On-line Documentation/
.bp
A sample scenario for modifying existing on-line documentation follows.
.sp
The archive /st0/105,1/docu contains the roff input for the manual
entry for each tool.  If you are preparing new documentation, one of these
archive entries can be used as a template.  The subsets are given the name
of the utility.  Suppose you wish to modify the writeup for ar.  The steps to
take are:
.sp
.in +3
.nf
% ar xv /105,1/docu ar
% ed ar
% cat /105,1/pagel >pagel
% roff pagel ar
% do this until you are satisfied with the writeup
% /105,1/ar uv /105,1/docu ar
% roff pagel ar >/105,6/ar
% rm ar
.sp
.fi
.in -3
The first invocation of ar is to extract the roff source from the
documentation archive.  The editor is used to modify the writeup.  The file
pagel is used merely to set the page length to 62.  The modified writeup
source is then roffed to see if it is OK.  Once it is ok, it is placed back
in the archive.  The reason that /105,1/ar is explicitly specified, is due to
the fact that just typing ar will cause the shell to find the file name ar.
in your current working directory, and will try to execute it as a script
file.  
The roffed writeup is then
placed in the directory for manual entries, /105,6.  The file ar is then removed
from the current working directory.
.he //Running tools from MCR/
.bp
Each tool is built to retrieve its arguments from MCR if it was
installed with a "...XXX" name.  To make "tool" available as
"...TOL" from MCR, simply type the following MCR command:
.sp
>INS ST0:[105,1]TOOL/TASK=...TOL
.sp
If a tool is invoked by the following MCR command
.sp
>RUN ST0:[105,1]TOOL
.sp
the tool will prompt for its arguments with an asterisk
.sp
*
.sp
before continuing.
