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.
The following utilities are available in the RSX system:
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
-1-
RSX Cover Document
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
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:
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.
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.
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".
intro: displays a list of available tools on STDOUT.
ls: lists structure-level-1 directories. ls understands the
regular expressions of find,change and ed, thus permitting
such examples as
-2-
RSX Cover Document
ls %a ......... lists all files starting with the letter a
in the current working directory
ls tst ......... lists all files with the characters tst
anywhere in the file name
ls ";1$" ....... lists all files with version number 1
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.
rat4: the string declaration has been added. The rules for its
use are:
1. All string declarations in a module must be grouped
together.
2. The group of string declarations must appear after all
other declaration statements and before any data
statements.
3. The format of the string declaration is
string name "abcdefghij"
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.
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. Several commands internal to the
shell have been added:
home set current directory to home directory
xon equivalent to -x switch
xoff inverse of xon
von equivalent to -v switch
voff inverse of von
The standard search path for the shell when resolving
commands is as follows:
1. current directory
2. home directory
3. usr directory [105,2]
4. bin directory [105,1]
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
-3-
RSX Cover Document
(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.
-4-
Files and Pathnames
The following are legal file specifications to any tool requiring
one:
Valid inputs to cd are the last four above, with the
file.ext;version removed. Again note that ddnn: is not valid.
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.
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:
tool <file >file
-5-
Tools Disk Structure
On disk structure of the Tools VOS
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:
[105,1] main tools directory; all system task images as well as
script files reside here
[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])
[105,3] scratch files created by the tools go here.
[105,4] files formatted by lpr go here (not yet implemented)
[105,5] mail directory: the mail data-base is kept here.
[105,6] the directory where man entries reside.
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.
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:
subroutine main
call remark("Hello world.")
return
end
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:
1. ld generates the following lines on the file (assuming F4P)
dk0:[101,1]hello.tsk;1/fp/cp=
dk0:[101,1]hello
-6-
Tools Disk Structure
ST0:[105,1]rlib/lb:.main.
ST0:[105,1]rlib/lb
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:
/
units=8
actfil=6
//
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:
/
units=8
actfil=6
libr=fcsres:ro
//
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.
Structure of the Distribution Tape
The distribution tape, unless specifically requested otherwise,
is a 9-track, 800 bpi, DOS-format tape created with FLX. Four
UIC's are represented:
[307,30] command file to install the tools, this document, and a
working task image for FFL, the fast filex utility
[307,31] the fortran and macro sources for building the system,
along with all script files necessary for the system to
run.
[307,32] the pre-roffed manual entries for use by the man
command.
[307,33] ratfor source code for the system, as well as roff input
files for various documentation on the tools.
-7-
Run-time Requirements of Tools VOS
One global logical device name must exist - ST0:. As one might
expect, this merely points to the disk where the tools
directories reside.
For ease of use, it is suggested that the task sh.tsk on the
tools directory be installed with the name "...SHL".
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:
1. Type ^C and wait for the MCR> prompt.
2. Type FEL and wait for the termination messages from the
subtasks.
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.
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!)
-8-
Installation Guide
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:
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]*.*
-9-
Installation Procedure
1. Login under a priveleged account
2. Ready tape or disk with the distribution on it
3. Select UIC to copy kitbld.cmd to
4. if (distribution on disk)
PIP *.*=DISK:[307,30]KITBLD.CMD
else
FLX /RS=TAPE:[307,30]KITBLD.CMD/DO
5. Make sure target volume is initialized and mounted
6. @KITBLD
7. Answer all questions
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:
a. The GBL logical name assignment is essential
b. Installation of shl is suggested
c. Installation of fel is essential
d. Running of shl -c "addr | sort >st0:[105,1]address"
assures that the mail database is current with ACNT's
database.
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:
a. >SET /UIC=[1,2]
b. >PIP *.*=ST0:[GRP,MEM]TOOLS.CMD
c. >@TOOLS
d. >using your favorite editor, place the following line
somewhere in [1,2]startup.cmd before the terminals are
enabled for users to use:
@LB0:[1,2]TOOLS
10. Now you are finished
-10-
What is KITBLD doing?
1. Determines
a. Target device and unit (LB0 is suggested, if there is
room)
b. Tools group number (default is 105)
c. Member number for tools binary directory (default is 1)
d. If building from tape or disk, and input device and unit
e. If F4P will be used
f. If the OTS for the compiler is in LB:[1,1]SYSLIB.OLB
g. If not, file specification for the OTS library - eg.
LB0:[1,1]FOROTS.OLB
h. If not using F4P, should the tasks be built /FP
i. If the tasks should be linked with an FCS resident
library (see comments on page 6).
j. If so, the name of the resident library (FCSRES).
k. Should fortran and macro files be deleted after use
(saves ~1100 blocks on target disk)
l. Should object files be deleted after use (saves ~1600
blocks on target disk)
2. Copies the necessary files from the distribution
3. Assures contiguousness of . tsk files from the distribution
4. If the binary directory is not [105,1], uses chs and rt4 to
modify the site-dependent primitive functions in sitepr.r.
5. Uses lss and chs to generate an indirect command file for
the assembler to assemble all of the . mac files.
6. Fortran compiles the primitive functions written in ratfor
7. Creates the ratfor library, RLIB.OLB
8. Builds all of the tasks
9. Builds the manual directory from the distribution medium
10. Builds the mail database
11. Creates each account's mymail. file with the correct
protection.
12. Displays the site's tools.cmd file
On a non-loaded system, the system generation takes
approximately 90 minutes.
-11-
Source File Structure
(How to rebuild the damn thing if I don't like it!)
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:
1. All files included in the rat4 source file
2. The rat4 source file, tool.r
Suppose that you wish to change the subroutine "module" in
"tool". The suggested scenario is as follows:
>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
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.
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:
1. toolcbl - an archive of the included files
2. each individual source module for tool
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
% 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
-12-
Source File Structure
% cat sh.w >/105,2/sh.w
Source Differences for FOR vs. F4P
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
F4P A,A=A.F/NOTR
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
FOR A,A=A.F/NOSN/NOVA/NOLO
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.
-13-
Adding On-line Documentation
A sample scenario for modifying existing on-line documentation
follows.
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:
% 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
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.
-14-
Running tools from MCR
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:
>INS ST0:[105,1]TOOL/TASK=...TOL
If a tool is invoked by the following MCR command
>RUN ST0:[105,1]TOOL
the tool will prompt for its arguments with an asterisk