GIT ICS 80 03_Software_Tools_Subsystem_Users_Guide_2ed_Apr80 03 Software Tools Subsystem Users Guide 2ed Apr80

GIT-ICS-80-03_Software_Tools_Subsystem_Users_Guide_2ed_Apr80 GIT-ICS-80-03_Software_Tools_Subsystem_Users_Guide_2ed_Apr80

User Manual: GIT-ICS-80-03_Software_Tools_Subsystem_Users_Guide_2ed_Apr80

Open the PDF directly: View PDF .
Page Count: 197

Download
Open PDF In Browser	View PDF

GIT-ICS-80/03
SOFTWARE TOOLS SUBSYSTEM
USER'S GUIDE
2ND EDITION
APRIL,

School
Information

1980

and Computer Science

GEORGIA INSTITUTE
OF TECHNOLOGY

6IT-ICS-80/03
SOFTWARE TOOLS SUBSYSTEM
USER'S 6UIDE
2ND EDITION
APRIL,

1980

T. Allen Akin
Perry B. Flinn
Daniel H. Forsyth, Jr.

School of Information and Computer Science
Georgia Institute of Technology
Atlanta, Georgia 30332

INTRODUCTION TO THE
GEORGIA TECH SOFTWARE TOOLS SUBSYSTEM USER'S GUIDE
The documents following this Introduction comprise the most recent version of the User's
Guide for the Georgia Tech Software Tools Subsystem for Prime 350 and larger computers.
This
Guide brings together in one place all the tutorial and reference information useful to
novice and intermediate users of the Subsystem.
It deals with several important aspects of
Subsystem use: the user interface in general, unavoidable aspects of the underlying operating system, and the most-frequently used major commands.
Each topic is covered in a separate
document (available individually) and all documents are collected together with this
Introduction to form the Guide itself.
Experienced users, as well as beginning users who
wish to expand their knowledge of the Subsystem, will find the Software Tools Subsystem
Reference Manual valuable.
The development of the Georgia Tech Software Tools Subsystem was originally motivated by
the text Software Tools by Brian W. Kernighan and P. J. Plauger, Addison-Wesley, 1976. That
text is still the basic reference for the tools that it covers, particularly Ratfor, the text
editor, the macro preproces.or, and the text formatter.
SOFTWARE TOOLS SUBSYSTEM TUTORIAL

l1li

USER'S GUIDE TO THE PRIMOS FILE SYSTEM

1l1li

INTRODUCTION TO THE SOFTWARE TOOLS SUBSYSTEM TEXT EDITOR

l1li

USER'S GUIDE FOR THE SOFTWARE TOOLS SUBSySTEM COMMAND INTERPRETER

l1li

USER'S GUIDE TO THE RATFOR PREPROCESSOR

l1li

SOFTWARE TOOLS TEXT FORMATTER USER'S GUIDE

l1li

Software Tools Subsystem Tutorial

•
T. A11en Akin
Perry B. Flinn
Daniel H. Forsyth, Jr.

School of Information and Computer Science
Georgia Institute of Technology
Atlanta, Georgia 30332
April, 1980

TABLE OF CONTENTS

Introduction ••••••.••••••.••.••••••••••••••••••••••••.•••••••••••••••••••••••••••.•.•
Getting Started •••••••••••••••.•••••••••••••••••••••.•••••••••••••••••••••••••••••
Correcting Typographical Errors...................................................
Adjusting to Terminal Characteristics •••••••••••••••••••••••••••••••••••••••••••••
Finishing Up •••••.••••.••.••••••••••.•••••••••••••••••••.••••••••.••••••••••••••••

3
3
4
4
5

Online Documentation •••••.•.•••••••••••••••.••••••••••••••••••••.••••••••••••••••••••
The 'Help' Command ••••••.•••••••••••••••••••••••••.••••••••••.••••••••..••••••••••
The 'Usage' Command •••••••••••••••••.••••••••••••••••••••••••.•••.•.••••••••••••••

7
7
8

Ut iIi ty Commands ••••.•.••••••••••••••••••.•••••••••••.•••••••••••••.••••••••••••.••••
The 'Lf' Command ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Th e 'Ca t' Command •••••••••.••••••••••••.••••••••••••••••.•••••••••••••••••••..••..
Deleting Files ••••••••••••••••••.••••.••••••••••••••.••••••••••••.••.•••••••••••••
The Subsystem Postal Service......................................................
The Subsystem News Service ••••••••••••.•••••••••••••••••••••••••••••••••••.•••••••

9
9
10
11
11
11

Input/Output •••••.•••••••••••••••••.•••••.•••••••••••..•..•••••••••••.•••••••••••..••
Standard Input and Standard Output ••••.••••••••••.••••••••••••••.•••••••••••••••••
I/O Redirection...................................................................
Examples of Redirected I/O Using 'Cat' .•.•.•••••••.•.•.•.••••••••••.••••••••••••••

13
13
13
13

Using Primos from the Subsystem .......................................................
Executing Primos Commands from the Subsystem •••••.••••••.••••••••.••••••••••••••••
Using ~rtran from the Subsystem ••••••••••••••••.•••••••••••••••••••••••••••••••••
Using the Linking Loader from the Subsystem •••••••••.•••.••••.••••••.••••..•..••••
Warning ••••••••••••••••••••.••••••••.•••••••••••••••••••.•••••••••••••••••••••••••

15
15
15
16
16

Program Development ••••••.••••.••••••••••••••••••••••••••••••••••••••••••••••.•••••••
Caveats for Subsystem Programmers ••••••••.••••••••••••••••.••••••••••••.••.••.••••
The Subsystem Text Editor.............................. •.••••••••••••••••...••.••••
Creating a Program ••••.•••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••

17
17
17
18

Advanced Techniques ••••••.•••••••••••••••.•••••••••••••••••..••••••••••••••••••••••••
Command F i l e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pipes •••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••.••••••••.••••••••
Additional I/O Redirectors •.••••••••.•.••••••••••••••••••••••••.••••••••••••••••••

22
22
22
22

Background ••••••••••••••••••••••••••••••••••••••.••.•••••••••••••••••••••••••••••••••
Ancient History...................................................................
Authors and Origins •••••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••

24
24
25

1 -

Foreword
The Software Tools Subsystem is powerful collection of program development and text
processing tools developed at the Georgia Tech School of Information and Computer Science,
for use on Prime 350 and larger computer systems. The tutorial that you are now reading is
intended to serve as your first introduction to the Subsystem and its many capabilities. The
information contained herein applies to Version 7 of the Subsystem as released in April 1980.

- 2 -

Software Tools Subsystem Tutorial
Introduction
The Software Tools Subsystem is a programming system based on the book
Software Tools, by Brian W. Kernighan and P. J. Plauger, (Addison-Wesley Publishing
Company, 1976), that runs under the Primos operating system on Prime 350 and larger
computers.
It
allows
much greater flexibility in command structure and
input/output capabilities than Primos, at some small added expense in processing
time.
This tutorial is intended to provide sufficient information for a beginning
user to get sta~ted with the Subsystem, and to acquaint him with its basic
features;
it 1S by no means a comprehensive reference. Readers desiring a more
detailed exposition of the Subsystem's capabilities are referred to the Software
Tools Subsystem Reference Manual Qnd to the remainder of the Software Tools
suosystem User's GUlde, of WhlCh this Tutorial is a part.

Getting Started
Since the Subsystem 1's composed entirely of ordinary user-state programs, as opposed
being a part of the operating system, it must be called when needed.
The following example shows how a typical terminal session might begin.
the user are boldfaced.
OK, login login name
Password:
LOGIN NAME (15) LOGGED IN AT 9:22 010578
OK, swt
Password:
]

Items typed by

(1 )

(2)
(3 )
(4)
(5 )
(6)

(1 )

A terminal session is initiated when you type the Primos 'login'
command.
"Log i n name" here represents the login name that you were assigned when your
account was established.

(2)

Primos asks you to enter your login password (if you have one) and turns off the
terminal's printer. You then type your password (which is not echoed) followed by
a newline.
(Note: password checking on login is a feature of Georgia Tech Primos;
at other installations, this line will be omitted.)

(3)

Primos acknowledges a successful login by typing your login name, your process number (in parentheses), and the current time and date.

(4 )

Primos indicates it is ready to accept commands by typing "OK,".
this prompt, Primos is waiting for you to type a command.)
n.§.oft~are '!.ools") to start up the Subsystem.

(5)

'Swt'
prompts you for your Subsystem password.
This password will have been
assigned to you by your Subsystem Manager at the time he created your Subsystem
account.
(Note:
Under Georgia Tech Primos, Subsystem passwords are never issued,
nor prompted for by 'swt'.) After you receive the prompt, enter your Subsystem
password.
It will not be printed on the terminal.

(6)

The Subsystem's command interpreter prompts with "l", indicating that it is ready
to accept commands.

(Whenever you see
Type
'swt'
(for

When the Subsystem command interpreter has told you it is waiting for something to do
(by typing the "]"), you may proceed to enter commands. Each command consists of a 'commandname', followed by zero or more 'arguments', all separated from each other by blanks:
command-name

argument

The command name is necessary so that the command interpreter knows what it is you want it to
do.
On
the other hand, the arguments, with a few exceptions, are completely ignored by the
command interpreter. They consist of arbitrary sequences of characters which are made
available to the command when it is invoked.
For this reason, the things that you can type
as arguments depend on what command you are invoking.
When you have finished typing a command, you inform the command interpreter of this
hitting the "newline" key.
(On some terminals, this key is labeled "return", or ncr".
both the "newline" and "return" keys are present, you should use "return".)

- 3 -

by
If

Software Tools Subsystem Tutorial
Incidentally, if you get some strange results from including any of the characters

>
within a command name or argument, don't fret.
These are called "meta-characters" and each
has a special meaning to the command interpreter. We will explain some of them later on.
For a more complete description of their meaning, see the User's Guide for the Software Tools
Subsystem Command Interpreter.
Correcting Typographical Errors
If you are a perfect typist, you can probably skip this part. But, if you are like most
of us, you will make at least a few typos in the course of a session and will need to· know
how to correct them.
There are three special characters used in making corrections. The "erase" character
causes the last character typed on the line to be deleted.
If you want to delete the last
three characters you have typed so far, you should type the erase character three times.
If
you have messed up a line so badly that it is beyond repair, you can throwaway everything
you have typed on that line in one fell swoop by typing the "kill" character. The result
will be that two backslashes ( ) are printed, and the cursor or carriage is repositioned to
the beginning of the line. Finally, the "retype" character retypes the present line, so you
can see exactly what erasures and changes have been made.
You may then continue to edit the
line, or enter it by striking the return key.
When you log into the Subsystem for the very first time, your erase, kill and retype
characters are control-h (backspace), DEL (RUBOUT on some terminals), and control-r, respectively.
You can, however, change their values to anything you wish, and the new settings
will be remembered from session to session. The 'ek' command is used to set erase and kill
characters:
ek erase kill
"Erase" should be replaced by any single character or by an ASCII mnemonic (like "BS" or
"SUB"). The indicated character will be used as the new erase character. Similarly, "kill"
should be replaced by a character or mnemonic to be used as the new kill character. For
instance, if you want to change your erase and kill characters back to the default values of
"BS" and "DEL", you can use the following command:
ek BS DEL

(By the way, we recommend that you do not use "e" or "k" for your erase or kill character.
If you do, you will be hard pressed to-Change them ever again!)
Adjusting to Terminal Characteristics
Unfortunately, not all terminals have full upper/lower case capability.
In particular,
In the belief that
most of the older Teletype modelS can handle only the upper case letters.
the use of "good" terminals should not be restricted by the limitations of the "bad" ones,
the Subsystem preserves the distinction between upper and lower case letters.
To allow users of upper-ease-only terminals to cope with programs that expect lower case
input, the 'term' command provides case conversion facilities:
term -nolcase
This command instructs the Subsystem to force all subsequent upper case letters you type
to be converted to lower case, and all lower case letters sent to your terminal by the computer to be converted to upper case.
In short, it means "I have no lower-case."
To provide further assistance to users whose terminals have a limited character set,
this command also activates a set of "escape" conventions to allow them to enter other
special characters not on their keyboard,
and to provide for their printing. When the
"escape" character (@) precedes another, the two characters together are recognized by the
Subsystem as a single character according to the following list:
@A

@Z
@(
@)

->
->
->
->
->

(note that

A -> a in " nolcase" mode)

{
}

Software Tools Subsystem Tutorial

All other characters are mapped to themselves when escaped; thus, "@_" is recognized as H@_H.
If you must enter a l i teral escape character, you must enter two: n@@" .
If you have given a "term -nolcase" command you must use escapes to enter upper case
letters, since everything would otherwise be forced to lower case.
For example,
@A
is used to transmit an upper case 'A', while
A

is used to transmit a lower case 'A'.
All output generated when the "-nolcase" option is in effect is forced to upper case for
compatibility with upper-ease-only terminals.
However, the distinction between upper and
lower case is preserved by prefixing each letter that was originally upper case with an
escape character. The same is true for the special characters in the above list. Thus,
Software Tools Subsystem
would be printed as
@SoFTWARE @TooLS @SUBSYSTEM
under the n-nolcase" option.
Finishing Up
When you're finished using the Subsystem, you have several options for getting out. The
We
first three simply terminate the Subsystem, leaving you face to face with bare Primos.
cover them here only for the sake of completeness, and on the off chance that you will
actually want to use Primos by itself.
First, you may type
stop
OK,
which effects an orderly exit from the Subsystem's command interpreter and gives control to
Primos'
command interpreter.
You will be immediately greeted with "oK,n, indicating that
Primos is ready to heed your call.
Second, you may enter a control-c (hold the "control" key down, then type the letter
ncn)
immediately after the "] II prompt from the command interpreter. TAKE HEED that this is
the standard method of generating an end-of-file signal to a program that is trying to read
from the terminal and is widely used throughout the Subsystem. Upon seeing this end-of-file
signal, the command interpreter assumes you are finished and automatically invokes the 'stop'
command.
The third and least desirable meth01 is to type a control-p or BREAK.
This
any running program, including the command interpreter, and (with few exceptions)
Primos. This last method is definitely not the method of choice, since it is
interrupt the Subsystem at an inconvenient point, causing things to be left in
chaos. You are strongly encouraged to choose either of the first two methods over
Finally, we come to the method you will probably want to use most often.
mand simply ends your terminal session and disconnects you from the computer.
example illustrates its use.
(Once again, user input is boldfaced.)
] bye
LOGIN NAME (15) LOGGED OUT AT 10:16 010578
TIME USED= 0:25 10:39 1:33
OK,

(1)
(2)
(3 )
(4)

(1)

You type the 'bye' command to end your terminal session.

(2)

Primos acknowledges, printing the time of logout.

(3)

Primos prints a summary of times used.

- 5 -

interrupts
returns to
likely to
a state of
this one.

The 'bye' comThe following

Software Tools Subsystem Tutorial
The first time is the number of hours and minutes of connect time.
The second time is the number of minutes and seconds of CPU time.
The third time is the number of minutes and seconds spent doing disk i/o.
(4)

Primos signals it is ready for a new login.

- 6 -

Software Tools Subsystem Tutorial
Online Documentation
Users, old and new alike, often find that their memories need jogging on the
use of a particular command. It is convenient, rather than having to look something up in a book or a manual, to have the computer tell you what you want to know.
Two Subsystem commands, 'help' and 'usage,' attempt to address this need.

The 'Help' Command
The 'help' command is designed to give a comprehensive description of the command in
question. The information provided includes the following: a brief, one-line description of
what the command does; the date of the last modification to the documentation; the usage
syntax for the command (what you must type to make it do what you want it to do); a detailed
description of the command's features; a few examples; a list of files referenced by the command; a list of the possible messages issued by the command; a list of the command's known
bugs or shortcommings; and a cross reference of related commands or documentation.
'Help' is called in the following manner:
help command-l command-2 •••
If help is available for the specified commands, it is printed; otherwise, 'help'
that no information is available.

tells

you

'Help' will only print out about as many lines as will fit on most CRT screens, and then
prompt you with the message "more?". This allows you to read the information before it rolls
off the screen, and also lets you stop getting the information for a command if you find
you're not really interested. To stop the output, just type an nn" or a "q" followed by a
NEWLINE. To continue, you may type anything else, including just a NEWLINE.
Several special cases are of interest. One, the command "help" with no arguments is the
same as "help general", which gives general information on the Subsystem and explains how to
use the help command. Two, the command "help -in produces an index of all commands supported
under the Subsystem, along with a short description of each. Finally, "help bnf" gives an
explanation of the conventions used in the documentation to describe command syntax.
Examples of the use of 'help':
help
help
help
help
help

(1)
(2)

-i
rp ed term
bnf
guide

(3 )
(4 )
(5)

(1)

General information pertaining to the Subsystem, along with an explanation of the
'help' command, is listed on the terminal.

(2)

A list of currently supported commands and subprograms, each with a short
tion, is listed on the terminal.

(3)

Information on the Ratfor preprocessor, the Software Tools text editor, and the
terminal configuration program is printed on the terminal.

(4)

A description of the notational conventions used
printed.

(5)

Information on how to obtain the Subsystem USer's Guides is listed on the terminal.

describe

command

descrip-

syntax

Since beginning users frequently find printed documentation helpful, you may find the following procedure useful. Unfortunately, it involves many concepts not yet discussed, so it will
be l'ather cryptic; nevertheless, it will allow you to produce a neatly-formatted copy of output from 'help'.

1 help -p I os >/dev/lps/f
1 help -p rp se term I os >/dev/lps/f
1 help -p -i I os >/dev/lps/f

I
I
I

(1 )

(2)
(3 )

(1)

The general information entry is printed on the line printer.

(2)

Information on the Ratfor preprocessor, the screen editor, and the terminal configuration program is printed on the line printer.

- 7 -

Software Tools Subsystem Tutorial
(3)

The index of available commands and subprograms is printed on the line printer.

The 'Usage' Command
Whereas 'help' produces a fairly comprehensive description of the command in question,
the 'usage' command gives only a brief summary of the syntax of the command. The syntax is
expressed in a notation known as Backus-Naur Form (BNF for short) which is itself explained
by typing "help bnf".
The
'usage' command
examples illustrate.

used

in the same way as the 'help' command, as the following

1 usage usage

(1 )
(2)

1 usage fmt help
(1)

The syntax of the 'usage' command is printed.

(2)

Usage information on the Software Tools text formatter and the
printed.

- 8 -

'help'

command

Software Tools Subsystem Tutorial
Utility Com.ands
The Subsystem supports several utility commands of general interest. These
commands have proven to be important in daily use, and so have been given a
separate section in this tutorial. Each will be discussed in turn.

The 'Lf' Command
The
'If'
(for "list files") command is the preferred method for obtaining information
about files.
Used by itself-without any arguments, 'If' prints the names of all the files in
your current directory in a mUlti-column format. This, however, is by no means all that 'If'
can do.
In fact, used in its general form. an 'If' command looks something like this:
. If

options

files

The "files" part is simply a list of files and/or directories that you want information
about.
If the "files" part" is omitted, 'If' assumes you mean the current directory.
For
each file in the list, information about that file is printedi for each directory listed,
information about each file within that directory is printed.
The "options" part of the command controls what information is to be printed. It is
composed of a dash ("-") followed by a string of single character option specifiers. Some of
the more useful options are the following:
c

print information in a single column format.

for each directory in the list,
instead of about its contents.

print all known information about the named files.

print the size (in 16-bit words) of each named file.

information

about

the

directory

that

IO/cmdncO:secret
The directory named ncmdncO" (one of whose passwords is "secret") which resides in
the MFD on logical disk O.

Imd
The MFD on the logical disk whose packname is "md".
1*/boot
The "boot" file on the current logical disk.
Iispoolq/q.ctrl
The file named "q.ctrl" in the "spoolq" directory on the
disk that has one.

lowest

numbered

logical

ki@/da:ad@/ik
The directory residing in the current dire:::tory whose entryname is "ki/da" and one
of whose passwords is nad/ik"~
(Note the use of the n@" to turn off the special
meaning of "I".)

The current directory.
Templates
In order to provide flexibility in the organization and placement of the directories and
files used by the Subsystem, the pathname interpreter contains a primitive macro substitution
facility, a feature that is loosely referred to as "templates." Templates provide a means
for designating particular files or directories without having to know their exact location
in the file system, and for constructing file names whose exact interpretation may vary with
the context in which, or the user by whom they are used. A template simply consists of a
name
(made up of letters, digits and underscores, and beginning with a letter) enclosed in

- 4 -

File System User's Guide
equals bars (=).
Unlike entrynames, upper- and lower-case letters are different in template
names;
"name" and "NAME" are not the same.
Each defined templatehas an associated value
which is an arbitrary character string.
The effect of including a template in a pathname is
the same as if its value had appeared in3tead.
There are two types of templates:
static and dynamic.
The value of a dynamic template
varies depending upon who you are, how you are connected to the computer, or what time it is.
The following list describes all of the available dynamic templates:
"date"
The current date in the format mmddyy.
"day=
The current day of the week; ",nonday", for example.
"passwd"
The owner password of the curr~nt user's profile directory.
sword the Subsystem asked you for when you typed "swt".)

(This is the same pas-

=pid=
The current user's process-id. This is a two-digit number in the range 01-63
is unique to each logged-in us~r.

that

=time=
The current time in the format hhmmss.
=user=
The current user's login name.
These templates are particularly useful Eor constructing unique file names.
Static templates are those whos'? definitions are independent of the context in which
they are used.
These templates and theic values come from two sources.
The file whose name
is the value of the template
=template=
contains template definitions that apply globally to all Subsystem users.
In fact the
definition of =template= itself is contained in this file,
as are definitions for other
important Subsystem files and directories.
In addition to this file, you may have in your
profile directory (named by the template =varsdir=) a file named ".template" that contains
your own personal template definitions.
Any templates that you define yourself preempt
similarly-named system and dynamic templ,ltes, so you should exercise caution in choosing
names. Also note that any new templates you place in your personal template file do not take
effect until the next time you enter th.~ Subsystem via 'swt'; this is the only time that the
file is examined.
The format o'f both files is the sam·~:
a series of lines containing a name, followed by
one or more blanks, and then a value.
Blank lines are ignored, as are leading and trailing
blanks on each line.
Comments may be introduced with the sharp character (i); all characters
from the sharp to the end of the line are ignored:

i example of a template defini~ion
template_name
template_value

# comment

A quick perusal of the contents of =template= should clear up any lingering questions you may
have.
Just for convenience, all the standard templates, along with an explanation of each,
are listed in Appendix A.
If you look at the template definition file,
you will notice that some of the
definitions appear to contain templates i:hemselves.
This is perfectly legal, for after each
template
is expanded,
the result is inspected for further templates until no others are
found.
This makes possible the definition of such templates as
"=varsdir=", and generally
enhances the utility of the mechanism.
Just one further remark about templ,ates:
Remember the trouble we had with "/" in passwords and entrynames? Well, we have a Similar situation with "="; when should it be taken
literally,
and when should it indicate the beginning of a template? To solve this dilemma,
any time the template expander sees a ter'lplate with an empty name (that is,
two consecutive
equals bars),
it supplies a single "=" as the replacement value and does not consider it to
be the start of another template.
So if you ever want a literal "=", in a password for example, just type "==" and you've got it.

5 -

File System User's Guide
Device Names
Up to this point, we have been talking only about disk files, and the path names we have
described have corresponded exactly to some actual sequence of directories leading to a file.
Although this is certainly the most common use of pathnames, there is one additional feature
that significantly enhances their usefulness.
If the "starting node" of a pathname is
"/dev", the path name doesn't necessarily refer to a disk file, but may instead refer to an
arbitrary peripheral device, or to some special file that requires unusual processing.
As
with ordinary pathnames, the "directory path" provides more information about the target file
or device.
Perhaps the most
usually called) is

useful

these extended pathnames (or "device names," as they are

/dev/lps
which refers to the line printer spooler. When this pathname is opened for writing, a
special disk file is created and other processing is done so that when the file is closed,
its contents will be written to the on-site line printer by the spooler and then deleted.
Additional entrynames may be included after the "Ips" to select various processing options
specific to the spooling process. A complete list of these in included as Appendix c.
Another useful device name is
/dev/tty
which refers to your terminal device. There are also others which, when opened,
descriptors for the various standard input and output ports:
/dev/stdout
/dev/stdoutl
/dev/stdout2
/dev/stdout3
/dev/errout

yield

file

/dev/stdin
/dev/stdinl
/dev/stdin2
/dev/stdin3
/dev/errin

Finally, the device name
/dev/null
when opened yields a file descriptor which discards all data written to it and returns an
end-of-file signal every time it is read.
It is really just a fancy name for the proverbial
bit bucket.
Georgia Tech Extensions
As many of you reading this guide will eventually come to know, using the standard
Primos file system can be quite awkward, principally because, of the constant necessity of
typing passwords in pathnames.
Relief from this burden comes only at the expense of
security, which in many cases is a more important consideration than ease of use. So that we
can have our cake and eat it' too, we at Georgia Tech have made a few modifications' to the
standard protection mechanism that virtually eliminate the necessity for typing passwords in
all but the rarest of circumstances. The Subsystem requires none of these modifications to
operate properly, 'and in those cases where it behaves differently depending on the extant
version of Primos, it does so completely transparently to the user.
In Georgia Tech Primos, if a directory's owner password is a valid entryname, it is
assumed to be the login name of the user that "owns" that directory.
In this case, the
"owner password" is instead called the "owner name." When you attach to a directory whose
owner name "matches" your login name, you automatically get owner status without having to
cite a password. The word "match" is quoted in the last sentence because more is meant by it
than just character-for-character equality. The underscore
()
is treated as a "wild"
character:
whenever it appears in a given position in either-your login name or the directory's owner name, the two names are considered equal in that position.
Thus, a directory
whose owner name i s "
" can be attached with owner status by everyone. Likewise, if
your login name is "
n then you get automatic owner status
in any directory with an
owner name instead of an owner password. With judicious assignment of login names, this
feature may be used to effect very convenient sharing of files by multiple users working on
the same project.
Just as icing on the cake, anyone logged in with the name "system" gets
owner status in every directory, regardless of whether it has an owner name or an owner password.
The modifications described in the last paragrapll constitute all of
differences between the protection mechanism in Georgia Tech Primos
mechanism. In all other situations, you can expect tne standard behavior.

- 6 -

the substantive
and the standard

File System User's Guide
Appendix A - Standard Templates
The following list describes all of the templates that are provided either in the
dard Subsystem template file or by the template interpreter.

stan-

=aUx=
This Subsystem directory contains large files that are not absolutely necessary for
the operation of the Subsystem.
=bin=
The standard Subsystem command directory.
=cmdncO=
The directory to which the system console is normally attached.
=date=
The current date in the format mmddyy.
=day=
The current day of the week (e.g., "monday", "tuesday", etc.).
=dictionary=
A file containing English words, used by the spelling checker.
=doc=
The Subsystem documentation directory.
=extra=
A standard Subsystem directory containing miscellaneous files required for proper
operation of the Subsystem.
=fmac=
The Subsystem directory contai,ing all the text formatter macro definition files.
=GaTech=
This is a template having nothing to do with pathnames.
Its value is "yes" at
installations that run the Georg ia Tech version of Primos, and "no" elsewhere.
Programs that are sensitive to the operating system version use this template to
determine their environment.
=gossip=
The directory containing user-to-user message files generated by the 'to' command.
=home=
The current user's login directory. Take note that this is not the same as his
"home directory" as described in the section on "current" and "home" directories.
=incl=
The standard Subsystem directory containing
programs.

files

that

are

included

Ratfor

=installation=
A file containing the name of the installation.
=lbin=
The standard Subsystem locally-supported-command directory.
=lib=
The Pr imos directory containi:1g all library files that should be accessible to the
loader.
=mai 1=
The Subsystem directory that contains per-user mail delivery files.
=mailfile=
The current user's mail storage file. This is where the 'mail' command deposits
letter after you have asked thot it be saved.
=newbin=
The Subsystem directory into which
recompilation of the entire Suhsystem.

newly-compiled commands are placed during a

=newlbin=
The Subsystem directory into which newly-compiled locally-supported-commands
placed during a recompilation 0f the entire Subsystem.

- 7 -

are

File System User's Guide
=newlib=
The Subsystem directory into which newly-compiled object code libraries are placed
during a recompilation of the entire Subsystem.
=news=
The directory used by the Subsystem news service.
=newsfile=
The current user's news delivery file.
=passwd=
The password of the current user's profile directory.
the Subsystem asked you for when you typed "swt".)

(This is the

same

password

=pid=
The current user's process-id. This is a two-digit number in the range 01-63 that
is unique to each logged-in user.
=src=
The Subsystem source code directory.
=srcloc=
A file associating each Subsystem library subroutine and
name(s) of its source code file(s).

command

with

the

path-

=swtrtn=
The value of this template is the entryname of the 'swtrtn' program in the directory =cmdncO=.
=system=
The Primos directory that contains the core-images of
segments.

the

various

shared

memory

=temp=
The Subsystem directory in which all temporary files are created.
=template=
The system template definition file.
=termlist=
A file describing the location and type of each terminal connected to the computer.
=time=
The current time in the format hhmmss.
=user=
The current user's login name.
=userlist=
A file containing a list of all users authorized to use the computer.
=utemplate=
The current user's private template definition file.
=vars=
The Subsystem directory in which all per-user profile directories are contained.
=varsdir=
The current user's profile directory.
=varsfile=
The current user's shell variable storage file.
=vth=
The directory used by the Subsystem virtual terminal handler.

- 8 -

File System User's Guide
Appendix B - Pathname Syntax
For the grammar afficionados among you, here is a formal description of the syntax of
pathnames. The notation used is an exte,ded Backus-Naur Form (BMF) which is described in the
introduction to the Software Tools Subsystem Reference Manual.

::=

::= \{\}
/
::=

::=

::= {/}
::= [:l
::= {}
::= I
::=
I
::= a

::= 0
::= •

I b I c 1••• 1 x I y I z
I 1 I 2 1••• 1 7 I 8 I 9
I $ I & I - I * I
I /

Appendix C - Spool Options
The entrynames that may be appended to the "/dev/lps" device name to control spooling
options are summarized in the following list. These entrynames correspond exactly to the
options that are accepted by the 'sp' cOlnmand (see section one of the Subsystem reference
manual) •
a

This option selects a specific location at which the file is to be printed. The
immediately following entryname in the path is taken as the name of the destination
printer.

The file name that is printed on the banner page of the printout may be set
arbitrarily with this option. The next entryname in the path is taken as the name
to be printed.
If this option is not used, the name "/dev/lps" is printed.

This option specifies the number of copies of the file that are to be printed.
next entryname must be a decim,~l integer indicating the number of copies.

Printing of the file may be deferred until a specific time of day using this
option.
The next entryname in the path must be a time of day in any reasonable
format.

If specified, this option indicates that the print file contains
carriage control characters.

This option causes the spooler to suppress the printing of the banner page that
normally precedes each printout.

Specifying this option causes the spooler to suppress the trailing page eject
it normally supplies at the end of each printout.

This option causes the spooler to print a consecutive line number in front of each
line of the print file.

This option instructs the spooler that the print file is to be printed on a special
type of paper. The name of th,! desired form should follow as the next entryname in
the path.

"Raw" forms control mode is selected by this option. No carriage control characters are recognized, nor is any pagination done when this mode is in effect.

This option selects the stan~ard Primos forms control mode. Under this mode, the
printout is automatically paginated, and a header line is printed on each page.

9 -

standard

The

Fortran

that

Introduction to the Software Tools Text Editor

II
T. Allen Akin

Perry B. Flinn
Daniel H. Forsyth, Jr.

School of Information and Computer Science
Georgia I~stitute of Technology
Atlanta, Geo~gia 30332
April, 1980

TABLE OF CONTENTS

Tutorial •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Starting an Editing Session. ••••••••.•••••••• ••••• •••••• •••••••••••••••••• ••••• •••
Entering Text - the Append Command ••••••••••••••••••••••••••••••••••••••••••••••••
Writing text on a file - the Write command ••••••••••••••••••••••••••••••••••••••••
Finishing up - the Quit command •••••••••••••••••••••••••••••••••••••••••••••••••••
Reading files - the Enter command •••••••••••••••••••••••••••••••••••••••••••••••••
Errors - the Query command ••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Printing text - the Print command •••••••••••••••••••••••••••••••••••••••••••••••••
More Complicated Line Numbers •••••••••••••••••••••••••••••••••••••••••••••••••••••
Deleting Lines ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Text Patterns •••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Making Substitutions - the Subs~itute command •••••••••••••••••••••••••••••••••••••
Line Changes and Insertions •••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Moving Text •••••••••••••••••••••••••.••••••••••••••••••••••••••••••••••.••••••••••
Global Commands •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Marking Lines •••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Undoing Things -- the Undo Command ••.•••••••••••••••••••••••••••••••••••••••••••••
Summary...........................................................................

1
1
1
1
2
2
3
3
4
5
6
8
9
10
10
11
12
13

The Subsys tern Sc reen Ed i to r ••••••••••••.••••••••••••••••••••••••••••••••••.••••••••••
Invoking the Screen Editor ••• •••••••.•••••••••••••••••• ••••••••••••••••••••• ••••••
Using 'Se' ••• •••••• •••••••••••••• ••••••••••••••••••••• ••• ••••••••••••••••••• ••••••
Extended Line Numbers •• ~..........................................................
Case Conversion •••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Tabs ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Full-Screen Editing •••••••••••••••••.••••••••••••••••••••••••••••••••••.••••••••••
Horizontal Cursor Motion ••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Vertical Cursor Motion ••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Character Insertion •••••••••••••••••.•••••••••••••.•••••••••••••••••••••••••••••••
Character Deletion................................................................
Te rm ina t i ng a Li n e ••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Non-printing Characters •••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

14
14
14
15
15
16
16
16
17
17
17
18
18

Screen Editor Options

Screen Editor Control Characters

Ed i tor Command Summary •••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

Elements of Line Number Expressions ••••.•••••••••••••••••••••••••••••••••••••••••••••

Summary of> Paftern Elements

iii

Foreword
'Ed'
is an interactive program that can be l sed for the creation and modification o£
"text." "Text" may be any collection of character dBta, such as a report, a program, or data
to be used by a program.
This document is intended to provide the beginning user of 'ed' with a tutorial, an aid
to becoming familiar with editing.
It does not attempt to cover the editor in full; only the
most frequently used aspects are mentioned.
For details on advanced uses, a careful reading
of Software Tools and the Software Tools Subsystem Reference Manual is recommended.

How To Use This Guide
This tutorial includes a step-by-step journey through an editing session.
You should be
sitting at a terminal and running the Software Tools Subsystem, so that you can perform the
suggesteo exercises as you go.
Throughout the text of this guide are sample editing commands, which you can execute on
your terminal to get a feel for their actual effect.
If at any time your terminal session
produces results different from those shown in the text, carefully re-check what you have
typed, or consult someone in charge of your installation.

- iv -

Introduction to 'Ed'
Tutorial
Starting an Editing Session
We assume that you have successfully logged in to your computer and are running the
Software Tools Subsystem.
If you need assistance, see the Software Tools Subsystem Tutorial.
We further assume that you know how to use the character erase and line delete characters, so
that you will have no trouble correcting typographical errors, and that you have some idea of
wh a t a "f i 1 e " is.
Since you are
in the Subsystem, the command interpreter should have just printed the
prompt "]". To enter the text editor, type
ed

(followed by a newline)

(Throughout this guide, boldface is used to indicate information that you should type in.
Things typed by 'ed' are shown in the reqular font.)
You are now in the editor, ready to go.
Note that 'ed' does not print any prompting information; this quiet behavior is preferred by
experienced users.
(If you would like
a
prompt,
it can be provided; try the command
"op/prompt/".)
,
At this point,
'ed'
is waiting for instructions from you.
You can instruct 'ed' by
using "commands", which are single letters (occasionally accompanied by other information,
which you will see shortly}.
Entering Text - the Append Command
The first thing that you need is te~t to edit. Working with 'ed' is like working with a
blank sheet of paper;
you write on the paper, alter or add to what you have written, and
either file the paper away for further use or throw it away.
In 'ed's terminology, the blank
sheet of paper you start with is called 1 "buffer."
The buffer is empty when you start
editing. All editing operations take pllce in the buffer; nothing you do can affect any file
'unless you make an explicit request to transfer the contents of the buffer to a file.
So the first problem reduces to finding a way to put text into the buffer.
command is used to do this:

The "append"

a
This command appends (adds)

text lines to the buffer, as they are typed in.

To put text into the buffer, simply type it in, terminating each line with a newline:
The quick brown fox
jumps over
the lazy dog.
To stop entering text, you must enter a line containing only a period, immediately followed
by a newline, as in the last line above.
This tells 'ed' that you are finished writing on
the buffer, and are ready to do some editing.
The buffer now contains:
The quick brown fox
jumps over
the lazy dog.
Neither the append command nor the fin,l period are included in the buffer -- just the text
you typed in between them.
Writing text on a file - the Write command
Now that you have some text in the ~uffer, you need to know how to save it.
command "w" is used for this purpose.
I~ is used like this:

The

write

w file
where "file" is the name of the file use:l to store what you just typed in. The write command
copies the contents of the buffer to che named file, destroying whatever was previously in
the file.
The buffer, however, remains intact; whatever you typed in is still there.
To
indicate that the transfer of data was successful, 'ed' types out the number of lines written.
In this example, 'ed' would type:
-

Introduction to 'Ed'
3

It is advisable to write the contents of the buffer out to a file periodically, to insure
that you have an up-to-date version in case of some terrible catastrophe (like a system
crash) •
Finishing up - the Quit command
Now that you have saved your text in a file,
"quit" command "q" is provided for this:

YOLo

may wish

leave

the

editor.

The

The next thing you see should be the "]" prompt from the Subsystem command interpreter.
you did not write out the contents of the buffer, the edi tor would respond:

(not saved)
This is to remind you to write out the buffer, so that the results of your editing session
are not lost.
If you intended that the buffer be discarded, just enter "q" again and 'ed'
will throwaway the buffer and terminate.
When you receive the "]" prompt from the Subsystem command interpreter, the buffer has
been thrown away~ there is absolutely no way to recover it.
If you wrote the contents of the
buffer to a file, then this is of no concern~ if you did not, it may mean disaster.
To check if the text you typed in is really in the file you wrote it to, try the following command:
] cat file
where "file" is the name of the file given with the "w" command.
("Cat" is a Subsystem' command that can be used to print files on the terminal.
If, for example, you wished to print
your file on the line printer, you could say:
] pr file
and the contents of "file" would be queued for printing.)
Reading files - the Enter command
Of course, most of the time you will not be entering text into the buffer for the first
time.
You need a way to fill the buffer with the contents of some file that already exists,
so that you can modify it. This is the purpose of the "enter" command "e"~ it enters the
contents of a file into the buffer.
To tryout "enter," you must first get back into the
ed itor:

1 ed
"Enter" is used like this:
e file
"File" is the name of a file to be read into the buffer.
Note that you are not restricted to editing files in the current directory~ you may also
edit files belonging to other users (provided they have given you permission).
Files belonging to other users must be identified by their full "pathname" (discussed fully in User's
Guide to the Primos File System).
For example, to e(nt a file named "document" belonging to
User"l:Om--;-OO-you woulaenter the following command:
e Iitomidocument

read.

After the file's contents are copied into the buffer, 'ed' prints the number of lines it
In our example, the buffer would now contain:
The quick brown fox
jumps over
the lazy dog.

If anything
named file.

at all is present in the buffer, the "e" command destroys it before reading the

2 -

Introduction to 'Ed'
As a matter of convenience, 'ed' re'uembers the file name specified on the last" e" command, so you do not have to specify a file name on the Ow" command. With these provisions, a
common editing session looks like
] ed
e file
{editing}

w
q
The "file" command ("f")
the name, just type:

is available for finding out the remembered file name.

To print out

file
You might also want to check that
] ed file
is exactly the same as
ed
e file
That is,

'ed' performs an "e" command for you if you give it a file name on the command line.

Errors - the Query command
Occasionally, an error of some ki~d is encountered.
Usually, these are caused by mis'ed'
spelled file names, although there are other possibilities. Whenever an error .occurs,
types
?

Although this
is rather cryptic, it is usually clear what caused the problem. If you need
further explanation, just enter "?" and 'ed' responds with a one-line explanation of the
error.
For example, if the last command you typed was an "e" command, 'ed' is probably saying that it could not find the file you asked for.
You can find out for sure by entering
It?" :

e myfile
?
?
I can't open the file to read

Except for
the messages in reponse to "?", 'ed' rarely gives other, more verbose error messages; if you should see one of these, t~e best course of action is to report it to whoever
maintains the editor at your installation.
Printing text - the Print command
You are likely to need to print t:1e text you have typed to check it for accuracy.
The
"print" command "p" is available to do t:1is.
"P" is different from the commands seen thus
far; "e", "w", and "a" have been seen to work on the whole buffer at once.
For a small file,
it might be easiest to print the entire buffer just to check on some few lines, but for very
large files this is clearly impractical.
The "p" command therefore accepts "line numbers"
that indicate which lines to print.
Try the following experiment:

1 ed file
3
lp
The quick brown fox
3p
the lazy dog.
1,2p
The quick brown fox
jumps over
1,3p
The quick brown fox
jumps over
the lazy dog.

- 3 -

Introduction to 'Ed'
"lp"
tells 'ed' to print line 1 ("The quick brown fox").
"3p" says to print the third line
("the lazy dog.").
"1,2p" tells 'ed' to print the first through the second lines, and "1,3p"
says to print the first through the third lines.
is.

Suppose we want to pr int the last 1 ine in the bl'ffer, but we don't know what its
'Ed' provides an abbreviation to specify the last line in the buffer:

number

$p
the lazy dog.
The dollar sign can be used just like a number.
type:

To print everything in the buffer, we could

l,$p
The quick brown fox
jumps over
the lazy dog.
If for some reason you want to stop the printing before it is done, press the BREAK key
on your terminal.
If you receive no response from BREAK, 'ed' is waiting for you to enter a
command. Otherwise, 'ed' responds with
?

and waits for your next command.
More Complicated Line Numbers
'Ed' has several ways to specify lines other than just numbers and "$".
ing command:

Try the follow-

the lazy dog.
'Ed'
ned
line
did
'Ed'

prints the last 1 ine. Does 'ed' always print the last line when it is given an unadorThe "current"
No.
The "p" command by itself prints the "current" line.
command?
is the last line you have edited in any way.
(Ps a matter of fact, the
last thing we
was to print all the lines in the buffer, so the last line was edited by being printed. )
allows you to use the symbol " "
(read "dot") to represent the current line. Thus
lip"

•p

the lazy dog.
is the same as

• ,.p
the lazy dog.
which is the same as just
p

the lazy dog.
II

can be used in many ways.

For example,

1,2p
The quick brown fox
jumps over
1, .p
The quick brown fox
jumps over
.,$p
jumps over
the la zy dog.
This example shows how to print all the lines up to the current line (l,.p) or all the lines
from the current line to the end of the buffer (.,$p).
If for some reason you would like to
know the 'number of the current line, you can type
3

and 'ed' displays the number.

(Note that the last thing we did was to print the

- 4 -

last

line,

Introduction to 'Ed'
so the current line became line 3.)
is not particularly useful when used alone.
" "
used in "line-number expressions." Try this experiment:

It becomes much more important when

.-lp
jumps over
"._1" means "the line that is one line before the current line."
.+lp
the lazy dog.
".+1" means "the line that is one line after the current line."
.-2,.-lp
The quick brown fox
jumps over
".-2,.-lp" means "print the lines from two lines before to one line before the current line."
You can also use "$" in line-number expressions:
$-lp
jumps over
"$-lp" means "print the line that is one line before the last line in the buffer,
next to the last line."

i.e.,

the

Some abbreviations are available to help reduce the amount of typing you have to do.
Typing a newline by itself is equivalent to typing ".+lp"; typing a caret, "A", followed by a
newline is equivalent to typing ".-lp"; and typing a line-number expression followed by a
newline is equivalent to typing that line-number expression followed by "p".
Examples:
{type a newline by itself}
the la zy dog.
Jumps over
I

The quick brown fox
It might be worthwhile to note here that almost all commands expect line numbers of one
form or another.
If none are supplied, 'ed' uses default values. Thus,
w file
is equivalent to
l,$w file
and

a
is equivalent to
.a

(which means, append text after the current line.)
Deleting Lines
As yet, you have seen no way of removing lines that are no longer wanted or needed.
do this, use the "delete" command "d":

1,2d
deletes the first through the second lines.
"D" expects line numbers that work in the same
way as those specified for Up", deleting one line or any range of lines.
d

deletes only the current line.

It is the same as ".d" or ".,.d".

5 -

Introduction to 'Ed'
After a deletion, the current line pointer is left pointing to the first line after the
group of deleted lines, unless the last line in the buffer was deleted.
In this-case, the
current line is the last line before the group of deleted lines.
Text Patterns
Frequently it is desirable to be able to find a particular "pattern" in a piece of text.
For example, suppose that after proofreading a report you have typed in using 'ed' you find a
spelling error. There must be an easy way to find the misspelled word in the file so it can
be corrected.
One way to do this is to count all the lines up to the line containing the
error, so that you can give the line number of the offending line to 'ed'.
Obviously, this
way is not very fast or efficient.
'Ed' allows you to "search" for patterns of text (like
words) by enclosing the pattern in slashes:
/juBlpS/
jumps over
'Ed' looks for the pattern you specified, and moves to the first line which contains the pattern. Note that if we had typed
/jumped/
?

'ed' would inform us that it could not find the pattern we wanted.
'Ed' searches forward from the current line when it attempts to find the pattern you
specified.
If
'ed'
reaches the last line without seeing the pattern, it "wraps around" to
the first line in the file and contin~es searching until it either finds the pattern or gets
back to ·the line where it started (line "."). This procedure ensures that you get the "next"
occurrence of the pattern you. were looking for, and that you don't miss any occurrences
because of your current position in the file.
Suppose, however, that you do not wish to find the "next" occurrence of a word, b'ut the
previous one instead. Very few text editors provide this capability; however, 'ed' makes it
simple. Just surround the pattern with backslashes:
\quick\
The quick brown fox
Remember: backslashes search backward. The backward search (or backscan, as i t i s sometimes
called) wraps around the file in a manner similar to the forward search (or scan).
The
search begins at the line before the current line, proceeds until the first line of the file
is seen, then begins at the last line of the file and searches up until the current line is
encountered. Once again, this is to ensure that you do not miss any occurrences of a pattern
due to your current position in the file.
'Ed' also provides more powerful pattern matching services than simply looking for a
given string of characters.
(A note to beginning users: this section may seem fairly complicated at first, and indeed you do not really need to understand it completely for effective use of the editor. However, the results you might get from some patterns would be
mystifying if you were not provided with some explanation, so look this over once and move
on. )
The pattern that may appear within slashes (or backslashes) is called a "regular expression."
It contains characters to look for and special characters used to perform other
operations. The following characters
%

have special meaning to 'ed':
%

Beginning of. line. The "%" character appearing as the first element in a pattern
matches the beginning of a line.
It is most frequently used to locate lines with
some string at the very beginning; for example,
/%The/
finds the next line that begins with the word "The". The percent sign has its
special meaning only!f it is the first element of the pattern; otherwise, it is
treated as a literal percent sign.

Any character. The question mark "?" in a regular expression matches ~ character (except a beginning-of-line or a newline).
It can be used like this:

- 6 -

Introduction to 'Ed'
/a?b/
to find strings like
a+b
a-b
a b
arbitrary
However, n?"
$

is most often used with the "closure" operator "*" (see below).

End of line.
The dollar sign appearing as the last element of
the newline character at the end of a line. Thus,

pattern

matches

/today$/
can be used to find a line with the word ntoday" at the very end. Like the percent
sign, the dollar sign has no special meaning in positions other than the end of a
pattern.
[]

Character classes.
For example,

The square brackets are used to match "classes" of

characters.

/[A-Z 11

finds the next line containing a capital letter,
/%[abcxyz]/
finds the next line beginning with an a, b, c, x, y, or z, and
/ [-0-9] /

finds the next line which contains a non-digit.
frequently used with the "closure" operator n*"

Character classes are also

Closure. The asterisk is used to mean "any number of repetitions (including zero)
of the previous pattern element (one character or a character class in brackets).n
Thus,
/a?*b/
finds lines containing an "an followed by any number of characters and a "b".
example, the following lines are matched:

For

ab
abnormal
Recording Media, by Dr. Joseph P. Gunchy
As another example,
/%=*$/
matches only those lines containing all equal-signs (or nothing at all).
wish to ensure that only non-empty lines are matched, use

If you

/%==*$/
Always remember that "*" (closure) matches zero or more repetitions of an element.
@

Escape. The "at" sign has special meaning to 'ed'.
It is the nescape" character,
which is used to prevent interpretation of a special character which follows.
SupYou may use the folpose you wish to locate a line containing the string "a * bU.
lowing command:
/a @* b/
The "at" sign "turns off" the special meaning of the asterisk, so it can be used as
an ordinary text character.
You may have occasion to escape any of the regular
expression metacharacters (%, ?, $, [, *, @, or {) or the slash itself. For exampIe, suppose you wi shed to find the next occur renee of the str ing "1/2". The command you need is:
/1@/2/

- 7 -

Introduction to 'Ed'
{}

Pattern tags. As seen in the next section, it is sometimes useful to remember what
part of a line was actually matched by a pattern. By default, the string matched
by the entire pattern is remembered.
It is also possible to remember a string that
was matched by only a part of a pattern by enclosing that part of the pattern in
braces. Hence to find the next line that contains a quoted string and remember the
text between the quotes, we might use

I" { ?*} " I
If the line thus located looked like this
This is a line containing a "quoted string".
then the text remembered as matching the tagged part of the pattern would be
quoted string
The last important thing you need to know about patterns is the use of the "default"
pattern.
'Ed'
remembers the last pattern used in any command, to save you the trouble of
retyping it. To access the remembered pattern, simply use an "empty" string.
For example,
the following sequence of commands could be used to step through a file, looking for each
occurrence of the string "ICS":

IICSI
II

(and so on)

One last comment before leaving pattern searching.

The constructs

Ipatternl
\pattern\
are not separate commands; they are components of line number expressions.
the line after the next line containing "tape", you could say

Thus,

I tap"'e/+ lp
Or,
to print a range of lines from one before to one after a line with a given pattern, you
could use
Ipattern/-I,/pattern/+lp

Making Substitutions - the Substitute command
This is one of the most used editor commands. The "substitute" command "s" is used
make small changes within lines, without retyping them completely.
It is used like this:

starting-line,ending-line s Ipattern/new-stuffl
For instance, suppose our buffer looks like this:
l,$p
The quick brown fox
.jumps over
the lazy dog.
To change "jumps" to "jumped,"
2s/jumps/jumped/p
jumped over
Note the use of the trailing "pH to print the result.
If the "p" had been omitted, the
change would have been performed (in the buffer) but the changed line would not have been
printed out.
If the last string specified in the substitute command is empty, then the text matching
the pattern is deleted:

- 8 -

Introduction to 'Ed'
s/jumped//p
over
s/t */
jumps /p
jumps over
Recalling that a missing pattern means "use the last pattern specified," try to explain
the following commands do:

what

s///p
jumps over

s//

/p
jumps over

(Note that, like many other commands, the substitute command assumes you want to work on the
current line if you do not specify any line numbers.)
What if you want to change "over" into "over and over"?

You might use

slover/over and over/p
jumps over and over
to accomplish this. There is a shorthand notation for this kind of substitution that was
alluded to briefly in the last section.
(Recall the discussion of "tagged" paterns.)
By
default, the part of a line that was matched by the whole pattern is remembered. This string
can then be included in the replacement string by typing an ampersand ("&")
in the desired
position. So, instead of the command in the last example,
s/over/& and

could have been used to get the same result. If a portion of the pattern had been tagged,
the text matched by the tagged part in the replacement could be reused by typing "@l":
s/jump{?*}/vault@l/p
vaults over and over
It is possible to tag up to nine parts of a pattern using braces.
tagged part may then be used in a replacement string by typing

The text matched

each

@n
where n corresponds to the nth "{" in the pattern.

What does the following command do?

s/{[- ]*} {?*}/@2 @l/
Final words on substitute: the slashes are known as "delimiters" and may be replaced by
any other character except a newline, as long as the same character is used consistently
throughout the command. Thus,
s'vaults'vaulted'p
vaulted over and over
is legal. Also, note that substi~ute changes only the first occurrence of the pattern that
it finds; i f you wish to change all occurrences on a line, you may append a "g" (for
"global") to the command, like this:

sl /*/gp
****vaulted*over*and*over
Line Changes and Insertions
Two "abbreviation" commands are available to shorten common operations applying to
changes of entire lines. These are the "change" command "c" and the "insert" command nino
The change command is a combination of delete and append.

Its format is

starting-line,ending-line c
This command deletes the given range of lines, and then goes into append mode to obtain text
to replace them. Append mode works exactly the same way as it does for the "a" command;
input is terminated by a period standing alone on a line. Examine the following editing session to see how change might be used:

- 9 -

Introduction to 'Ed'
l,$c
Ed is an interactive program used for
the creation and modification of -text.

c
the creation and modification of -text. w
-Text" may be any collection of character
data.
As you can see, the current line is set to the last line entered in append mode.
The other abbreviation command is "i".
following relation holds:

"I" is very closely related to "a"; in fact, the

starting-line
is the same as
starting-line - 1
In short, "i"· inserts
specified line.

text

before the specified line, whereas "a" inserts text after the

Moving Text
Th roughout this guide, we have concentrated on what may be called "in-place"
The other type of editing commonly used is often called "cut-and-paste" editing.
command "m" is provided to facilitate this kind of editing, and works like this:

editing.
The move

starting-line,ending-line m after-this-line
If you wanted to move the last fifty lines of a file to a point after
command would be

the

third

line,

the

$-49,$m3
Any of the line numbers may, of course, be full expressions with search strings, arithmetic,
etc.
You may, if you like, append a "p" to the move command to cause it
line moved.
The current line is set to the last line moved.

the

last

Global Commands
The "global" command "g"
is
buffer that match a certain pattern.
"editor", you could type

used to perform an editing command on all lines in the
For example, to print all the lines containing the word

g/editor/p
If you wanted to correct some common spelling error, you would use
g/old-stuff/s//new-stuff/gp
which makes the change in all appropriate lines and prints the resulting lines.
example: deleting all lines that begin with an asterisk could be done this way:

Another

g/%@*/d
"G" has a companion command "x" (for "exclude") that performs an operation on all lines
in the buffer that do not match a given pattern.
For example, to delete all
lines that do
not begin with an asterISk, use
x/%@*/d
"G" and "x" are very powerful commands that are essential for advanced usage, but are
usually not necessary for beginners. Concentrate on other aspects of 'ed' before you move on
to tackle global commands.

- 10 -

Introduction to 'Ed'
Marking Lines
During some types of editing, especially when moving blocks of text, it is often necessary to refer to a line in the buffer that is far away from the current line. For instance,
say you want to move a subroutine near the beginning of a file to somewhere near the end, but
you areh't sure that you can specify patterns to properly locate the subroutine. one way to
solve this problem is to find the first line of the subroutine, then use the co.mmand 11.-":
/subroutine/
subroutine think

47
and write
thing:

down

(or remember) line 47.

Then find the end of the subroutine and do the same

/end/
end

Now you move to where you want to place the subroutine and enter the command
47,71m.
which does exactly what you want.
The problem here is that absolute line numbers are easily forgotten, easily mistyped,
and difficult to find in the first place. It is much easier to have 'ed' remember a short
"name" along with each line, and allow you to reference a line by its name. In practice, it
seems convenient to restrict names to a single character, such as "b" or "e" (for "beginning"
or "end").
It is not necessary for a given name to be uniquely associated with one line;
many lines may bear the same name. In fact, at the beginning of the editing session, all
lines are marked with the same name: a single space.
To
return to our. example, us ing the 'k' command, we can mark the beg inning and ending
lines of the subroutine quite easily:

/subroutine/
subroutine think
kb
/end/
end
ke
We have now marked the first line in the subroutine with "b" and the second line with "e".
Both
To refer to names, we need more line number expression elements:
">" and "<".
work in line number expressions just like "$" or "/pattern/". The symbol ">" followed by a
single character mark name means "the line number of the first line with this name when you
search forward".
The symbol "<" followed by a single character mark name means "the line
number of the first line with this name when you search backward".
(Just remember that ,<,
points backward and ,>, points forward.)
Now in our example, once we locate the new destination of the subroutine, we can use
"
or
se -t myfile
Again, if you are using the an ADDS Regent 100 terminal, you could type

1 se -t regent
Use of the third method depends on how your installation is set up and is usually practical only when terminals are directly connected to the computer, or are all of the same
model.
If this is the case in your installation, as it is at Georgia Tech, you can use the
'e' command to invoke 'se' with the proper terminal type. All you need do is type
e myfile
and 'se' will appear.
Using • Se'
Once 'se' knows your terminal type, it clears the screen, draws in its margins, and
begins reading your file (if you specified one).
The screen it draws looks something like
this.
(The parenthesized numerals are not part of the screen layout, but are there to aid in
the following discussion.)

- 14 -

Introduction to 'Ed'

(1)

(2)
(3 )
1
integer a
*1
c
1
-> 1
for (a = 1; a <= 12; a = a + 1)
E
call putch (NEWLINE, STDOUT)
1
F
stop
1
$
end
1
(4 )
cmd>
11: 39 myfile •••• (5) ••••••••••••••••••••••••••••••••••

A
B

The display is divided into five parts:
(1) the line number area, (2) the mark name area,
(3) the text area, (4) the command line, and (5) the status line. The current line (remember
In addition, a
" • n)
is indicated by the symbol "." in the 1 ine number area of the screen.
rocket ("->") is displayed to make the current line more obvious. The current mark name of
Other
each line is shown in the markname area just to the left of the vertical bar.
information, such as the number of lines read in, the name of the file, and the time of day,
are displayed in the status line.
The cursor is positioned at the beginning of the command line, showing you that 'se'
awaits your command.
You may now enter any of the 'ed' commands and 'se' will perform them,
while making sure that the current line is always displayed on the screen. There are only a
few other things that you need know to successfully use 'se'.
'Se' always recognizes BS (control-h) and DEL as the erase and
regardless of your Subsystem erase and kill character settings.

kill

characters,

If you make an error, 'se' displays an error message in the status line (you need
not request it).
It also leaves your command line intact so that you may change it
using in-line editing commands (we'll get to this a little later).
If you don't
want to bother with changing the command, just hit DEL and 'se' will erase it.
The "po command has a different meaning than in 'ed'. When used with line numbers,
it displays as many of the lines in the specified range as possible (always including the last line).
When used wi thout line numbers, "p" displays the previous
page.
The ":" command positions a specified line at the top of the screen
(e.g.,
"12:"
positions the screen so that line 12 is at the top).
If no line number is
specified, ":" displays the next page.
The "v" command can be use to modify an entire line rather than just add to the end
of it. Also, if you use "v" over a range of lines and find you want to terminate
the command before all lines have been considered, the control-f key is used
instead of a period.
Keeping these few differences in mind, you will see that 'se' can perform all of the funtions
of 'ed', while giving the advantage of a "window" into the edit buffer.
Extended Line Numbers
'Se' has a number of features that take advantage of the window display to minimize
keystrokes and speed editing.
In the line number area of the screen, 'se' always displays
for each line a string that may be used in a command to refer to that line.
Normally,
it
displays a capital letter for each line, but in "absolute line number" mode (controlled by
the Roan command; see the section on options for more details), it displays the ordinal number of the line in the buffer.
The line number letters displayed by 'se' may be used in any context requiring a line
number.
For instance, in the above example, a change to the first line on the screen could
be specified as
As/%/* my new program/
You could delete the line before the first line on the screen by typing
A-Id

Case Conversion
When
'se' is displaying upper-case letters for line numbers, it accepts command letters
only in lower case. For those who edit predominately upper-case text this is somewhat inconvenient; for those with upper-case only terminals this is a disaster.
For this reason,
'se'
- 15 -

Introduction to 'Ed'
offers several options to alleviate this situation.
First of all,
typing a control-z causes 'se' to invert the case of all letters (just
like the alpha-lock key on some terminals).
Upper-case letters are converted to lower-case,
lower-case letters are converted to upper-case, and all other characters are unchanged.
You
can type control-z at any time to toggle the case conversion mode. When case inversion is in
effect, 'se' displays the word "CASE" in the status line.
One drawback to this feature is that 'se' still expects line numbers in upper case and
commands in lower case, so you must shift to type the command letter -- just the reverse of
what you're used to.
A more satisfactory solution is to specify the "c" option. Just type
oc
on the command line and 'se' toggles the case conversion mode, and completely reverses its
interpretation of upper and lower case letters.
In this mode, 'se' displays the line number
letters in lower case and expects its command I-etters in upper case.
Unshifted letters from
the terminal are converted to upper case and shifted letters to lower case.
Tabs
In the absence of tabs, program indentation is very costly in keystrokes.
So 'se' gives
you the ability to set arbitrary tab stops using the not" command.
By default, 'se' places a
stop at column 1 and every third column thereafter.
Tabs corresponding to the default can be
set by enumerating the column positions for the stops:
ot 1 4 7 10 13 16 19 22 25 28 31 34
This
is almost as bad as typing the blanks on each line.
shorthand for such repetitive specifications.

For this reason, there is also a

ot +3
sets a tab stop at column 1 and at every third column thereafter.
prefer the specification

Fortran

programmers

may

ot 7 +3
to set a stop at column 7 and at every third thereafter.
Once the tab stops are set, the control-i and control-e keys can be used to move the
cursor from its current position forward or backward to the nearest stop, respectively.
Full-Screen Editing
Full screen editing with 'se' is accomplished through the use of control characters for
editing
functions.
A few,
such as control-h, control-i, and control-e have already been
mentioned.
Since 'se' supports such a large number of control functions, the mnemonic value
of control character assignments has dwindled to almost zero.
About the only thing mnemonic
is that most symmetric functions have been assigned to opposing keys on the keyboard
(e.g.,
forward
and backward tab to control-i and control-e, forward and backward space to control-g
and control-h, skip right and left to control-o and control-w, and so on). We feel pangs of
conscience about this, but can find no more satisfactory alternative.
If you feel the
control character aSSignments are terrible and you can find a better way, you may change them
by modifying the definitions in 'se' and recompiling.
If they work well, we'd like to hear
about them.
Except for a few special purpose ones, control characters can be used anywhere, even on
the command line.
(This is why erroneous commands are not erased -- you may want to edit
them.)
Most of the functions work on a single line, but in overlay mode (controlled by the
"v" command) the cursor may be positioned anywhere in the buffer.
Horizontal Cursor Motion
There are quite a few functions for moving the cursor. You've probably used at least
one
(control-h) to backspace over errors.
None of the cursor motion functions erase characters, so you may move forward and backward over a line without destroying
it.
Here are
several of the more frequently used cursor motion characters:
control-q

Move forward one column.

- 16 -

Introduction to 'Ed'
control-h

Move backward one col umn.

control-i

Move forward to the next tab stop.

control-e

Move backward to the previous tab stop.

control-o

Move to the first col umn beyond the end of the line.

control-w

Move to column 1.

Vertical Cursor Motion
'Se' provides two control keys, control-d and control-k, to move the cursor up and down,
respectively,
from line to line through the edit buffer. The exact function of each depends
on 'se's current mode:
in command mode they simply move the current line pointer without
affecting the cursor position or the contents of the command line; in overlay mode (viz. the
"vO command)
they actually move the cursor up or down one line within the same column;
finally, in append move, these keys are ignored. Regardless of the mode,· the screen is
adjusted when necessary to insure that the current line is displayed.
control-d

Move the cursor up one line.

control-k

Move the cursor down one line.

Character Insertion
Of course the next question is:
"Now that I've moved the cursor, how do I change
things?"
If you want to retype a character, just position the cursor over it, and type the
desired character; the old one is reptaced. You may also insert characters at the current
cursor position instead of merely overwriting what's already. there.
Typing a control-c
inserts a single blank before the character under the cursor and moves the remainder of the
line one column to the right; the cursor remains in the same column over the newly-inserted
blank.
Typing a control-x inserts enough blanks at the current cursor position to move the
character that was there to the next tab stop. This can be handy for . aligning items in a
table, for example. As with control-c, the cursor remains in the same column.
A more general way of handling insertions is to.type control-a. This toggles "insert
mode" -- the word "INSERT" appears on the status line, and all characters typed from this
point are inserted in the line
(and characters to the right are moved over). Typing
control-a again turns insert mode off. Here is a summary of these control characters:
control-a

Toggle insert mode.

control-c

Insert a blank to the left of the cursor.

control-x

Insert blanks to the next tab stop.

Character Deletion
There are many ways to do away with characters. The most drastic is to type DEL;
'se'
erases the current line and leaves the cursor in column 1. Typing control-t causes 'se' to
delete the character under the cursor and all those to its right. The cursor is left in the
same column which is now just beyond the new end of the line. Similarly, control-y deletes
all the characters to the left of the cursor (not including the one under it). The remainder
of the line is moved to the left, leaving the cursor over the same character, but now in
column 1.
Control-r deletes the character under the cursor and closes the gap from the
right, while control-u does the same thing after first moving the cursor one column to the
left. These last two are most commonly used to eat characters out of the middle of a line~
DEL

Erase the entire line.

control-t

Erase the characters under and to the right of the cursor.

control-y

Erase the characters to the left of the cursor.

control-r

Erase the character under

control-u

Erase the character immediately to left of the cursor.

th~

cursor.

- 17 -

Introduction to 'Ed'
Terminating a Line

After you have edited a line, there are two ways of terminating it (having it entered or
executed) •
The most commonly used is newline (or carriage-return) which deletes all characters under and to the right of the cursor and terminates the line.
To terminate a line
without deleting any characters, there is control-v.
NEWLINE

Erase characters under and to the right of the cursor and terminate.

control-v

Terminate.

Non-printing Characters

'Se' displays a non-printing character as a blank (or other user-selectable character;
see the description of noun in the section on options).
Non-printing characters
(such as
'se's control characters), or any others for that matter, may be entered by hitting the ESC
key followed immediately by the key to generate the desired character. Note, however, that
the character you type is taken literally, exactly as it is generated by your terminal, so
case conversion does not apply.
ESC

Accept the literal value of the next character, regardless of its function.

- 18 -

Introduction to 'Ed'
Screen Editor Options
Options for 'se' can be specified in two ways: with the "0" command or on the Subsystem
command line that invokes 'se'. To specify an option with the "0" command, just enter ·0"
followed immediately by the option letter and its parameters. To specify an option on the
command line, just use "-" followed by the option letter and its parameters.
With this
second method, if there are imbedded spaces in the parameter list, the entire option should
be enclosed in quotes. For example, to specify the "a" (absolute line number) option and t'ab
stops at column 8 and every fourth thereafter with the "0" command, just enter
oa
ot 8 +4
when 'se' is waiting for a command.
you might use

To enter the same options on the invoking command

line,

se -t regent myfile -a "-t 8 +4"
The following table summarizes the available 'se' options:
Option

Action

causes absolute line numbers to be displayed in the line number area of the screen.
The default behavior is to display upper-case letters with the letter "A"
corresponding to the first line in the window.

inverts the case of all letters you type (i.e., converts upper-case to lower-case
and vice versa). This option causes commands to be recognized only in upper-case
and alphabetic line numbers to be displayed and recognized only in lower-case.

d[]

selects the placement of the current line pointer following a "d" (delete) command.
must be either ">" or "<". If ">" is specified, the default behavior is
selected:
the line following the deleted lines becomes the new current line. If
"<" is specified, the line immediately preceding the deleted lines becomes the new
current line. If neither is specified, the current value of is displayed 'in
the status line.

selects Fortran oriented options.
and "t7 +3" (see below) options.

1 []

sets the line number display option.
Under control of this option, , se'
continuously displays the value of one of three symbolic line numbers.
may
be any of the following:

*
$

This is equivalent to specifying

both

the

nco

display the current line number
display the number of the top line on the screen
display the number of the last line in the buffer

If is omitted, the line number display is disabled.
t[] sets

tab

stops according to .
consists of a s,eries of numbers
columns in which tab stops are to be set. If a number is preceded by a
plus SIgn ("+"), it indicates that the number is an increment~ stops are set at
regular intervals separated by that many columns, beginning with the most recently
specified absolute column number. If no such number precedes the first increment
specification, the stops are set relative to column 1. By default, tab stops are
set in every third column starting with column 1, correspondin~ to a
specification of "+3". If is omitted, the current tab spacing IS displayed
in the status line.
indicat~ng

u[]

selects the character that 'se' displays in place of unprintable characters.
may be any printable character; it is initially set to blank. If is omitted,
'se' displays the current replacement character on the status line.

v[]

sets the default "overlay column".
This is the column at which the cursor is
initially positioned by the "v" command. must be a positive integer, or a
dollar sign ($) to indicate the end of the line. If is omitted, the current
overlay column is displayed in the status line.

- 19 -

Introduction to 'Ed'
w[]

sets the "warning threshold" to which must be a positive integer.
Whenever
the cursor is positioned at or beyond this column, the column number is displayed
in the status line and the terminal's bell is sounded.
If is omitted, the
current warning threshold is displayed in the status line. The default warning
threshold is 74, corresponding to the first column beyond the right edge of the
screen on an 80 column crt.

-[]

splits the screen at the line specified by which must be a simple line number
within the current window. All lines above remain frozen on the screen, the
line specified by is replaced by a row of dashes, and the space below this
row becomes the new window on the file.
Further editing commands do not affect the
lines displayed in the top part of the screen.
If is omitted, the screen is
restored to its full size.

- 20 -

Introduction to 'Ed'
Screen Editor Control Characters
Character Action
control-a Toggle insert mode. The status of the insertion indicator is inverted.
Insert
mode, when enabled, causes characters typed to be inserted at the current cursor
position in the line instead of overwriting the characters that were there
previously. When insert mode is in effect, ·INSERT" appears in the status line.
control-b Scan right and erase. The current line is scanned from the current cursor position
to the right marg in until an occurrence of the next character type.d is found. When
the character is found, all characters from the current cursor position up to (but
not including) the scanned character are deleted and the remainder of the line is
moved to the left to close the gap. The cursor is left in the same column which is
now occupied by the scanned character. If the line to the right of the cursor does
not contain the character being sought, the terminal's bell is sounded. 'Se'
remembers the last character that was scanned using this or any of the other scanning keys; if control-b is hit twice in a row, this remembered character is used
instead of a literal control-b.
control-c Insert blank. The charac·ters at and to the right of the current cursor position
are moved to the right one column and a blank is inserted to fill the gap.
control-d Cursor up. The effect of this key depends on 'se's current mode. When in command
mode, the current line pointer is moved to the previous line without affecting the
contents of the command line. If the current line pointer is at line 1, the last
line in the file becomes the new current line. In overlay mode (viz. the "v" command), the cursor is moved up one line while remaining in the same column.
In
append mode, this key is ignored.
control-e Tab left.
position.

The cursor is moved to the nearest tab stop to the left of its current

control-f "Funny" return. The effect of this key depends on the editor's current mode.
In
command mode, the current command line is entered as-is, but is not erased upon
completion of the command; in append mode, the current line is duplicated; in overlay mode (viz. the ·v· command), the current line is restored to its original
state and command mode is reentered (except if under control of a global prefix).
control-g Cursor. right.

The cursor is moved one column to the right.

control-h Cursor left. The cursor is moved one column to the left.
erase any characters; it simply moves the cursor.
control-i Tab right.
position.

Note that this does not

The cursor is moved to the next tab stop to the right

its

current

control-k Cursor down.
As with the control-d key, this key's effect depends on the current
editing mode. In command mode, the current line pointer is moved to the next line
without changing the contents of the command line. If the current line pointer is
at the last line in the file, line 1 becomes the new current line.
In overlay mode
(viz. the ·v" command), the cursor is moved down one line while remaining in the
same column. In append mode, control-K has no effect.
control-l Scan left.
The cursor is positioned according to the character typed immediately
after the control-I. In effect, the current line is scanned, starting from the
current cursor position and moving left, for the first occurrence of this character. If none is found before the beginning of the line is reached, the sqap
resumes with the last character in the line. If the line does not contain the
character being looked for, the message nNOT FOUND n is printed in the status line.
'Se' remembers the last character that was scanned for using this key; if the
control-l is hit twice in a row, this remembered character is searched for instead
of a literal control-I.
Apart from this, however, the character typed after
control-l is taken literally, so 'se's case conversion feature does not apply.
control-m Newline.

This key is identical to the NEWLINE key described below.

control-n Scan left and erase. The current line is scanned from the current cursor position
to the left margin until an occurrence of the next character typed is found. Then
that character and all characters to its right up to (but not including) the
character under the cursor are erased. The remainder of the line, as well as the
cursor are moved to the left to close the gap. If the line to the left of the cursor does not contain the character being sought, the terminal's bell is sounded.
As with the control-b key, iE control-n is hit twice in a row, the last character
- 21 -

Introduction to 'Ed'
scanned for is used instead of a literal control-no
control-o Skip right.
line •.

The cursor is moved to the first position beyond the

current

end

control-p Interrupt.
If executing any command except "a", "c", "i" or "v", 'se' aborts the
command and reenters command mode. The command line is not erased.
control-q Fix screen.
screen.

The screen is reconstructed from 'se's internal representation of

the

control-r Erase right.
The character at the current cursor position is erased and all
characters to its right are moved left one position.
control-s Scan right. This key is identical to the control-l key described above,
that the scan proceeds to the right from the current cursor position.
control-t Kill right.
The
right are erased.

character

except

the current cursor position and all those to its

control-u Erase left. The character to the left of the current cursor position is deleted
and all characters to its right are moved to the left to fill the gap. The cursor
is also moved left one column, leaving it over the same character.
control-v Skip right and terminate.
line is terminated.
control-w Skip left.

The cursor is moved to the current end of line

and

the

The cursor is positioned at column 1.

control-x Insert tab.
The character under the cursor is moved right to the next tab stop;
the gap is filled with blanks. The cursor is not moved.
control-y Kill left. All characters to the left of the cursor are erased; those at and to
the right of the cursor are moved to the left to fill the void.
The cursor is left
in column 1.
control-z Toggle case conversion mode.
The status of the case conversion indicator is
inverted; if case inversion was on, it is turned off, and vice versa. Case inversion, when in effect, causes all upper case letters to be converted to lower case,
and all lower case letters to be converted to upper case. Note, however, that 'se'
continues to recognize alphabetic line numbers in upper case only, in contrast to
the "case inversion" option (see the description. of options above). When case
inversion is on, "CASE" appears in the status line.
Insert newline.
A newline character is inserted before the current cursor
position, and the cursor is moved one position to the right. The newline is
displayed according to the current non-printing replacement character (see the "un
option) •

control-

control-\ Tab left and erase.
Characters are erased starting with the character at the
nearest tab stop to the left of the cursor up to but not including the character
under the cursor. The rest of the line, including the cursor, is moved to the left
to close the gap.
.
control-

Tab right and erase. Characters are erased starting with the character under the
cursor up to but not including the character at the nearest tab stop to the right
of the cursor. The rest of the line is then shifted to the left to close the gap.

NEWLINE

Kill right and terminate. The characters at and to the right of the current cursor
pOSition are deleted, and the line is terminated.

DEL

Kill all.
The entire line is erased, along with any error message that appears in
the status line.

ESC

Escape. The ESC key provides a means for entering 'se's control characters
literally as text into the file.
In fact, any character that can be generated from
the keyboard is taken literally when it immediately follows the ESC key.
If the
character is non-printing (as are all of 'se's control characters), it appears on
the screen as the current non-printing replacement character (normally a blank).

- '22 -

Introduction to 'Ed'
Bditor Command Summary
Syntax

Function

a[:text]

Append
Inserts text after the specified line. Text is inserted until a line
In 'se', if
containing only a period and a newline is encountered.
the command is followed immediately by a colon, then whatever text
follows the colon is inserted without entering "append" mode. The
current line pointer is left at the last line inserted.

·, .

c [:tex t]

Change
Deletes the lines specified and inserts text to replace them.
Text
is inserted until a line containing only a period and a newline is
encountered. In 'se', if the command is followed immediately by a
colon, then whatever text follows the colon is inserted without
entering "append" mode. The current line pointer is left at the last
line inserted.

·, .

d[p]

Delete
Deletes all lines between the specified lines, inclusive.
The
current line pointer is left a the line after the last one deleted.
If the "p" is included, the new current line is printed.

none

e [filename]

Enter
Loads the specified file into the buffer and prepares for editing.
Automatically invoked if a filename is specified as an argument on
the command line used to invoke the editor. The current line pointer
is positioned at the first line in the buffer.

none

f [filename]

File
Print or change the remembered file name. If a name is given, the
remembered file name is set to that value; otherwise, the remembered
file name is printed.

•,$

g/pat/command

Global on pattern
Performs the given command on all lines in the specified
match a certain pattern.

none

h [stuff]

Help
In
'se', provides access to online documentation on the screen
is
editor.
"Stuff" may be used to select which information
displayed.

i [: tex t]

Insert
Inserts text before the specified line. Text is inserted until a
line containing only a period and a newline is encountered.
In 'se',
if the command is immediately followed by a colon, then whatever text
follows is inserted without entering "append" mode. The current line
pointer is left at the last line inserted.

j/stuff![p]

Join
The specified lines are joined into a single line. The newlines that
previously separated the lines are replaced by "stuff".
If the .p"
option is used, the resulting line (which becomes the new current
line) is printed.

·, .

marK
The specified lines are marked with 'c'
which may be any single
character other than a newline.
If 'c' is not present, the lines are
marked with the default name of blank. The current line pointer is
never changed.

·, .

m [p]

Move
Moves the specified block of lines after . [p]

copY
Makes a copy of all the lines in the given range, and inserts the
copies after .
As with the "m" command, may not be
omitted. The current line pointer is set to the new copy of the last
line in the range; this line is printed if the "ph is present.

=[p]

Equals
The number of the specified line is printed. The line itself is also
printed if the "pH option is used. The current line pointer is not
changed.

none

Query
In 'ed' only, a verbose description of the last error encountered is
pr inted.

1,$

Iccommand

Exclude on markname
Similar to the 'x' prefix except that 'command' is performed for
lines in the range that do not have the mark name 'c'.

24 -

lines in the given range that do not

all

Introduction to 'Ed'

1,$

'ccommand

Global on markname
Similar to the 'g' prefix except that 'command' is performed for all
lines in the range that have the mark name 'c'.
Print next page
In 'ed', 23 lines beginning with the current line are printed
(equivalent to ".,.+23pn).
In 'se', the next page of the buffer is
displayed and the current line pointer is placed at the top of the
window.

- 25 -

Introduction to 'Ed'
Elements of Line Number Expressions
Form

Value

integer

value of the integer (e.g., 44).
number of the current line in the buffer.

number of the last line in the buffer.
number of the previous line in the buffer (same as .-1).

Ipatternl

number

the

next line in the buffer that matches the given pattern (e.g.,
wraps around
to the beginning and back to the current line.

IFebruary/)i the search proceeds to the end of the buffer, then
\pattern\

>name

number of the previous line in the buffer that matches the given pattern
(e.g., \JanuarY\)i search proceeds in reverse, from the current line to line
1, then from the last line back to the current line.
number

the next line having the given markname (search wraps around, like

II) •
]

Matches any single character that is a member of the set specified by .
may be composed of single characters or of character ranges of the form
-.
If character ranges are used, and must both belong to
the digits, the upper case alphabet or the lower case alphabet.
Matches
.

any

single

character

that

is not a member of the set specified by

In combination with the immediately preceeding pattern element,
or more characters that are matched by that element.

Turns off the special meaning of the immediately following character.
character has no special meaning, this is treated as a literal "@".

{}

Tags the
text actually matched by the sub-pattern specifed by for
use in the replacement part of a substitute command.

Appearing in the replacement part of a substitute command, represents the text
actually matched by the pattern part of the command.

Appearing in the replacement part of a substitute command, represents the text
actually matched by the tagged sub-pattern specified by .

- 26 -

matches

zero

If that

User's Guide for the
Software Tools Subsystem Command Interpreter
(The Shell)

II
T. Allen Ak in
Perry B. Fl inn
Daniel H. Forsyth, Jr.

School of Information and Computer Science
Georgia Institute of Technology
Atlanta, Georgia
30332
April, 1980

TABLE OF CONTENTS

Tutorial ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •.•••••
Getting· Started •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••.•
Typographical Conventions •••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . ~ • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

Special Characters and Quoting ••••••••••••••••••••••••••••••••••••••••••••••••••••
Command Fi les •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Doing Repetitive Tasks --- Iteration ••••••••••••••••••••••••••••••••••••••••••••••
Sources and Destinations of Data ••••••••••••••••••••••••••••••••••••••••••••••••••
Pipes and Networ ks ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Compound Nodes ••••••••••••••••••••••••• ,...........................................
Function Calls ••••••••••••••••••••••••••••••••• •.••••••••••••••••••••••••••••••••••
Variables •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Conel usion ........................................................... ... .. • . . . . • . . .
Summary of Syntax and Semantics •••••••••••••••••••••••••••••••••••••••••.••••••••••••
Commands

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

1
1
1
1
1
2
2
3
4
5
5
6
6
7
7

Networks. •.••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Nodes

•••..•••.••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Comments ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Variables •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Iteration •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Function Calls ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Concl usion ••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

12
12
12
13
13

Application Notes ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Basic Functions •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Shell Control Variables •••••••••••••.••••••••••• •.•••••••••••••••••••••••••••••••••
Symbiotic Commands ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Argument Fetching ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Shell Tracing .....................••....•.•••••..•••••••••.•••••...•.••.•..•..•
Shell Variable Utilities •••••••••••••••••••••••••••••••••••••••••••••••••••••••
Concl usion ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

14
14
16
17
17
18
18
18

Messages from the Shell ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

iii

Introduction
The Software Tools
Software Tools by Brian W.
on the Prime 400 computer
The present Subsystem, the
of computing resources.

Subsystem is a set
Kernighan and P. J.
in 1977 and 1978 in
seventh version, is

of program development tools based on the book
Plauger.
It was originally developed for use
the form of several cooperating user programs.
a powerful tool that aids in the effective use

The command interpreter, also referred to as the "shell," is a vital part of the Subsystem.
It is a program which accepts commands typed by the user on his terminal and converts them into more primitive directions to the computer itself.
The user's instructions
are expressed in a special medium called the "command language." The greatest part of this
document is involved with describing the command language and giving examples of how it is
used.
Three areas will be covered in the following pages.
First, there is a tutorial on the
use of the command language. New Subsystem users should read this chapter first.
Some
minimal knowledge of terminal usage is assumed; if you are unsure of yourself in this area,
see Prime's published documentation and the Software Tools Subsystem Tutorial for help.
Second,
there is a summary of the syntax and semantics of the command language. Experienced
users should find this chapter valuable as a reference.
Finally, there is a selection of
application notes.
This chapter is a good source of useful techniques and samples of
advanced usage.
Experienced users and curious beginners should find it well worthwhile.

- iv -

Command Interpreter User's Guide
Tutorial
Getting Started
After you have logged in to the computer, you must start up the Subsystem.
type the command "swt":

To do

this,

OK, swt
]

The Subsystem
bracket.

fires

up and the command interpreter prompts you for input by typing a right

Typographical Conventions
The rules for correcting typographical errors under the Subsystem may be different from
the usual ones on your system.
(You can change the rules, if you like; see the Subsystem
Tutorial for more information.)
Usually, the Subsystem expects a backspace (control-h) to be
used for deleting single characters that are in error, and a DEL (RUBOUT on some terminals)
to delete entire lines that are in error.
Throughout this chapter, references will be made to input lines that are terminated with
a "newline." You should use the "newline" key on a terminal only if it lacks a "return" key.
They do not necessarily have the same effect.
Commands
Input to the command interpreter consists of "commands." Commands, in turn, consist of
a "command name,"
usually made up of letters and digits, and additional pieces of
information, often called "parameters" or "arguments."
(Note that a command mayor may not
have arguments, depending on its function.)
The command name and any arguments are separated
from each other by spaces.
For example:
] echo Bello world!
Bello world!
]

The command name is "echo".
'Echo' is not a very involved command; it simply types back
parameters, whatever they may be.

its

Here is another command, one that is a bit more useful:

]If
adventure
shell
words

ee
shell.doc
zunde

guide
subsys

m680D

time sheet

]

'Lf'
is used to list the names of your files.
('Lf' may be used with arguments, as well as
without them; for more information, see the Software Tools Subsystem Reference Manual, or try
typing the command nhelp If".)
Special Characters and Quoting
Some characters have special meanin'J to the command interpreter.
ing this command:

For example, try

typ-

] echo Alas, poor Yorick
Alas
poor: not found
]

This strange behavior is caused by the fact that the comma is used for dark mysterious
purposes elsewhere in the command language.
(The comma actually represents a null I/O connection between nodes of a network.
See the section on pipes and networks for more
information.)
In fact, all of the following characters are potential troublemakers:

blank

The way to handle this problem is to use quotes.

You may use either single or double quotes,

Command Interpreter User's Guide
but be sure to match each with another of the same kind.

Try this command now:

echo -Alas, poor Yorick; I knew him well."
Alas, poor Yorick; I knew him well.
]

You can use quotes to enclose other quotes:
] echo 'Quoth the raven: -Nevermore!"
Quoth the raven: "Nevermore!"
]

A final word on quoting: Note
argument.
For example, the command

that

anything

enclosed

quotes

becomes

single

] echo "Can I use that in my book?"
has only one argument, but
echo Can I use that in my book?
has seven.
Command Files
Suppose you have a task which must be done often enough that it is inconvenient to
remember the necessary commands and type them in every time. For an example, let's say that
you have to print the year-end financial reports for the last five years.
If the "print"
command is used to print files, your command might look like:
] print year74 year75 year76 year77 year78 year79
If you use a text editor to make a file named "reports" that contains this command,
then print your reports by typing

you

can

reports
No special command is required to perform the operations in this "command file;" simply typing its name is sufficient.
Any number of commands may be placed in a command file.
It is possible to set up groups
of commands to be repea~ed or executed only if certain conditions occur.
See the
Applications Notes for examples.
It is one of the important features of the command interpreter that command files can be
treated exactly like ordinary commands.
As shown in later sections, they are actually
programs written in the command language; in fact, they are often called "shell programs."
Many Subsystem commands ('e', 'fos', and 'rfl', for example) are implemented in this manner.
Doing Repetitive Tasks --- Iteration
Some commands can accept only a single argument. One example of this is the 'fos' command. "Fos" stands for "format, overstrike, and spool."
It is a shorthand command for
printing "formatted" documents on the line printer.
(A "formatted" document is one prepared
with the help of a program called a "text formatter," which justifies right margins,
indents
paragraphs, etc. This document was prepared by the Software Tools text formatter 'fmt.') If
you have several documents to be prepared, it is inconvenient to have to type the 'fos' command for each one.
A special technique called "iteration" allows you to "factor out" the
repeated text.
For example,
]

fos (filel file2 file3)

is equivalent to
fos filel
fos file2
fos file3
The arguments inside the parentheses form an "iteration group."
There may be more than one
iteration group in a command, but they must all contain the same number of arguments. This
is because each new command line produced by iteration must have one argument from each
group.
As an illustration of this,

- 2 -

Command Interpreter User's Guide
(echo print fos) f1le(1 2 3)
is equivalent to
] echo filel
1 print file2
] fos file3
Iteration is performed by simple text substitution; if there is no space between an argument
and an iteration group in the original command, then there is none between the argument and
group elements in the new commands. Thus,
file(l 2 3)
is equivalent to
f ilel
fi Ie 2
file3
Iteration is most useful when combined with function calls, which will be discussed later.
Sources and Destinations of Data
Control of the sources and destinations of data is a very basic function of the command
interpreter, yet one that deserves speci31 attention. The concepts involved are not new, yet
they are rarely employed to the extent that they have been used in the SUbsystem.
The best
approach to learning these ideas is to experiment.
Get on a terminal, enter the Subsystem,
and try the examples given here until th-=y seem to make sense. Above all, experiment freely;
try anything that comes to mind.
The Subsystem has been designed with the idea that users
are intelligent human beings, and their freedom of expression is the most valuable of tools.
Use your imagination; if it needs tweaking, take a look at the Application Notes in the last
chapter.
Every program and command in the Subsystem can gather data from certain well-known
places and deliver it to other well-known places.
Data sources are known as "standard input
ports;" data des·tinations are called "standard output ports." Programs are said to "read
from standard input" and "write on standClrd output."
The key point here is that programs
need not take
into account how input data is made available or what happens to output data
when they are finished with it; the commClnd interpreter is in complete control of the standard ports.
A command we will use frequently in this section is 'copy'.
'Copy' does exactly what
its name implies; it copies data from one place to another.
In fact, it copies data from its
first standard input port to its first standard output port.
The first point to remember is that by default, standard ports reference
Try 'copy' now:

the

terminal.

copy
After you have entered this command, type some random text followed by a newline.
'Copy'
will type the same text back to you.
(When you tire of this game,
type a control-c; this
causes an end-of-file signal to be sent to
'copy', which then returns to the command
interpreter. Typing control-c to cause end-of-file is a convention observed by all Subsystem
programs.)
Since you did not say otherwise, standard input and standard output referred to
the terminal;
input data was taken from the terminal (as you typed it) and output data was
placed on the terminal (printed by 'copy').
Obviously, 'copy' would not be of much use if this was all it could do.
Fortunately,
the command interpreter can change the sources and destinations of data, thus making 'copy'
less trivial.
Standard ports may be altered so as to refer to disk files by use of a "funnel."
The
greater-than sign
(»
is used to represent a funnel.
Conventionally, the ">" points in the
direction of data flow.
For example, if you wished to copy the contents of file "ee" to file
"old_ee", you could type
] ee>

copy

>old ee

The greater-than sign must always be imm,~diately next to its associated filename;
no
intervening blanks are allowed. At least one blank must separate the '>' from any command name or
arguments.
This restriction is necessary to insure that the command language can be
interpreted unambiguously.

- 3 -

Command Interpreter User's Guide
The construct "ee>" is read "from ee"; ">old ee" is read "toward old ee."
Thus, the
command above can be read" from ee copy toward old ee," or, "copy from ee toward old ee."
The process of changing the file assignment of a standard port by use of a funnel is called
"I/O redirection," or simply "redirection."
It is not necessary to redirect both standard input and standard output; either may be
redirected independently of the other.
For example,
ee>

copy

can be used to print the contents of file nee" on the terminal.
(Remember that standard output, since it was not specifically redirected, refers to the terminal.)
Not surprisingly,
the last variation of 'copy',

1 copy

>old ee

is also useful.
This command causes input to be taken from the terminal (until an end-offile is.generated by typing a control-c) and placed on the file "old ee". This is a quick
way of creating a small file of text without using a text editor.
It is important to realize that all Subsystem programs behave uniformly with regard to
redirection.
It is as correct to redirect the output of, say, 'If'
If

>file list

as it is to redirect the output of 'copy'.
Although the discussion has been limited to one input port and one output port up to
this point, more of each type are available.
In the current implementation, there are a
total of six; three for input and three for output.
The highest-numbered output port is
generally used for error messages, and is often called "ERROUT"; you can "capture" error messages by redirecting this output port. For example, if any errors are detected by 'If' in
this command
1 If
then

th~

3>errors

resulting error messages will be placed on the file "errors".

Final words on redirection:
there are two special-purpose redirection operators left.
They are both represented by the double funnel "»~". The first operator is called "append:"

1 1f

»list

causes a list of files to be placed at the end of (appended to) the file named "list". The
second operator is called "from comman~input~ It is represented as just "»" with no file
name, and causes standard input to refer to the current source of commands.
It is useful for
running programs like the text editor from "scripts" of instructions placed in a command
file.
Pipes and Networks
The last section discussed I/O redirection, the process of making standard ports refer
to disk files, rather than just to the terminal.
This section will take that idea one step
further.
Frequently, the output of one program is placed on a file, only to be picked up
again later and used by another program. The command interpreter simplifies this process by
eliminating the intermediate file.
The connection between programs that is so formed is called a "pipe," and a linear array of programs communicating through pipes is called a
"pipeline."
.
Suppose that you maintain a large directory, containing drafts of various manuals. Each
draft is in a file with a name of the form "MANxxxx.rr", where "xxxx" is the number of the
manual and "rr" is the revision number. You are asked to produce a list of the numbers of
all manuals at the first revision stage. The following command will do the job:
If -c I find .01
"If -cor lists the names of all files in the current directory. The "pipe connection"
(vertical bar) causes this listing to be passed to the 'find' command, which selects those
lines containing the string ".01" and prints them. Thus, the pipeline above will print all
filenames matching the conventional form of a first-revision manual name.
The ability to build special purpose commands cheaply and quickly from available tools
using pipes is one of the most valuable features of the command interpreter. With practice,
surprisingly difficult problems can be solved with ease. For further examples of pipelines,
see the Applications Notes.
-

4 -

Command Interpreter User's Guide
Combinations of programs connected with pipes need not be linear. Since multiple standard ports are available, programs can be and often are connected in non-linear networks.
(Some networks cannot be executed iE the programs in the network are not executed
concurrently. The command interpreter detects such networks, and prints a warning message if
they cannot be performed.)
Further information on networks can be found in both the
reference and applications chapters of this Guide.
Compound Nodes
It is sometimes necessary to change the standard port environment of many commands at
one time, for reasons of convenience or efficiency. The "compound node" (a set of networks
surrounded by curly braces) can be used in these situations.
As an example of the first case, suppose that you wish to generate a list of manual
names (see the last example) in either the first or the second stage of revision. One way to
do this is to generate the list for the first revision stage, place it on a file using a funnel, then generate a list for the second revision stage and place it on the end of the same
file using an "append" redirector. A compound node might simplify the procedure thusly:
] { If -c I find .01;

If -c I find .02}

>list

The first network finds all manuals at the first reVISIon stage, and the second finds all
those at the second stage. The networks will execute left-to-right, with the output of each
being placed on the file "list," thus generating the desired listing. With iteration, the
command can be collapsed even farther:
] { If -c I find .0(1 2) }
This combination of iteration and

>list

compou~d

nodes is often useful.

Efficiency becomes a consideration in cases where successive long streams of data are to
be copied onto a file; if the "append" redirector is used each time, the file must be
reopened and repositioned several times.
Using a compound node, the output file need be
opened only once:
] { (filel file2 file3»

copy}

>all files

This complex exa~ple copies the contents of files "filel," "file2," and "file3" into the file
named "all files."
Function Calls
Programs in the Subsystem r'eceive information through their command-line arguments as
well as their standard ports, so it is s,)metimes useful to deliver the output of a program to
the command interpreter for further processing, rather than to a pipe. The "function call"
mechanism is available for this purpose. For example, recall the situation illustrated in
the section on pipes and networks; suppose it is necessary to actually print the manuals
whose names were found.
This is how the task could be done:
print [If -c I find .01]
The function call is composed of the pipeline "If -c I find
.01" and the square brackets
enclosing it.
The output of the pipeline within the brackets is passed to 'print' as a set
of arguments, which it accesses in the usual manner. Specifically, all the lines of output
from the pipeline are combined into one set of arguments, with spaces provided where multiple
lines have been collapsed into one line.
'Print' accepts multiple arguments; however, suppose it was necessary to use a program
like '£OSl, that accepts only one argument.
Iteration can be combined with a function call
to do the job:
] fos ([If -c I find .01])
This command
"01" •

formats

and prints all manuals in the current directory with revision numbers

Function calls are frequently us~d in command files, particularly for accessing
arguments passed to them. Since the sequence "1 f -c I find pattern" occurs very f requentl y,
it is a good candidate for replacement with a command file; it is only necessary to pass the
pattern to be matched from the argument list of the command file to the 'find' command with a
function call. The following command file, called 'files', will illustrate the process:
1 f -c I find [arg 1]

- 5 -

Co~and

Interpreter User's Guide

"arg 1" retrieves the first command file
argument to 'find' through its argument list.
network was appropriate:

argument. The function call then passes that
'Files' may then be used anywhere the original

files .01
print [files .01]
fos ([files .01])

Variables
It has been claimed that the command language is a programming language in its own
right.
One facet of this language that has not been discussed thus far is the use of its
variables. The command interpreter allows the user to create variables, with scope, and
assign values to them or reference the values stored in them.
Certain special variables
These variables have names
which is the prompt string the
object to ")" as a prompt, you

are used by the command interpreter in its everyday operation.
that begin with the underline ( ).
One of these is ' prompt',
command interpreter prints when-requesting a command.- If you
can change it with the "set" command:

1 set prompt = "OK, "
OK, set prompt = -, "
% set prompt
"] "
1

You may create and use variables of your own. To create a variable in the current scope
(level of command file execution), use the "declare" comand:
) declare i j k sum
Values are assigned to variables with the 'set' command. The command interpreter checks the
current scope and all surrounding scopes for the variable to be set; if found, it is changed,
otherwise it is declared in the current scope and assigned the specified value.
Variables behave like small programs that print their current values. Thus the value of
a variable can be obtained by simply typing its name, or it can be used in a command line by
enclosing it in brackets to form a function call.
The following command file
(which also
illustrates the use of 'if', 'eval', and 'goto') will count from 1 to the number given as its
first argument:
declare i
set i
1
: loop
if (eval i ">"
goto exit
fi

(arg 1))

set i = (eval i + 1)
goto loop
:exit
Note the use of the "eval" function, which treats its arguments as an arithmetic expression
and returns the expression's value.
This is required to i~sure that the string "i + 1" is
interpreted as an expression rather than as a character string. Also note that 'fi'
terminates the 'if' command.
Conclusion
This concludes the tutorial chapter of this document. Despite the fact that a good deal
of material has been presented, much detail has been omitted.
The next chapter is a complete
summary of the capabilities of the command interpreter.
It is written in a rather technical
style, and is recommended for reference rather than self-teaching. The last chapter is a set
of examples that may prove helpful. As always, the best approach is simply to sit down at a
terminal and tryout whatever you wish to do.
Should you have difficulty, further tutorials
are available, and the 'help' command can be consulted for quick reference.

- 6 -

Command Interpreter User's Guide
Summary of Syntax and Semantics
This section is the definitive document for the syntax and corresponding semantics of
the Software Tools Subsystem Command Interpreter. It is composed of several sub-sections,
each covering some major area of command syntax, with discussions of the semantic
consequences of employing particular constructs. It is not intended as a tutorial, nor is it
intended to supply multitudinous examples; the other sections of this document are provided
to fill those needs.
Commands
::= [

r ;

} ]

The ncommand" is the basic unit of communication between the command interpreter and the
user.
It consists of any number of networks (described below) separated by semicolons and
terminated by a newline. The networks are executed one at a time, left-to-right; should an
error occur at any point in the parse or execution of a network, the remainder of the
is ignored. The null command is legal, and causes no action.

The command interpreter reads commands for interpretation from the "command source. n
This is initially the user's terminal, although execution of a commarid file may change the
assignment. Whenever the command source is the terminal, and the command interpreter is
ready for input, it prompts the user with the string contained in the shell variable
'prompt'. Since this variable may be altered by the user, the prompt string is selectable
on a per-user basis.
Networks
::=
{ { } }
::=
::=

, I 1 'I' [ 1 [ . ]

::=
::= I $ I
A generates a block of (possibly concurrent) processes that are bound to one
an.other by channels for the flow of data. Typically, each corresponds to a single
process.
«Node>s are described in more detail below.) There is no predefined "execution
order" of the processes composing a ; the command interpreter will select any order it
sees fit in order to satisfy the required input/output relations. In particular, the user is
specifically enjoined not to assume a left-to-right serial execution, since some s cannot be executed in this manner.
Input/output relations between s are specified with the
construct.
The following discussion may be useful in visualizing the data flows in a ,
and clarifing the function of the components of the .
The entire may be represented as a directed graph with one vertex for each
(typically, equivalent to each process) in the net. Each vertex may have up to narcs
terminating at it (representing "input data streams n ), and m arcs originating from it
(representing "output data streams"). An arc between two vertices indicates a flow of data
from one to another, and is physi':ally implemented by a pipe.
Each of the n possible input points on a is assigned an identifier consisting of
a unique integer in the range 1 to n. These identifiers are referred to as the "port numbers" for the "standard input ports" ot the given . Similarly, each of the m possible
output points on a is assigned a unique integer in the range 1 to ~, referred to as
the port numbers for the nstandard output ports n of the given .
Lastly, the s themselves are numbered, starting at 1 and increasing by 1 from
left end of the to the right.
Clearly, in order to specify
s, it is sufficient to specify:

any

possible

The number of the "source" .

- 7 -

the

input/output connection between any two

Command Interpreter User's Guide
The number of the "destination" .
The port number of the standard output port on the source that is to be
source of the data.
The port number
receive the data.

the

the standard input port on the destination that is to

The syntax for includes the specifications for the last three of these
items.
The source is understood to be the node that immediately preceeds the under consideration. The special "," is used to separate s
that do not participate in data sharing; it specifies a null connection.
Thus, the provides ~ ~ of establishing any possible connection between two ~ of ~
given .
The full flexibility of the is rarely needed or desirable.
In order to
make effective use of the capabilities provided, suitable defaults have been designed into
the syntax. The semantics associated with the defaults are as follows:
If the output port number (the one to the left of the vertical bar) is omitted, the
next unassigned output port
(in increasing numerical order) is im~lied. This
default action takes place only after the entire has been examine, and all
non-defaulted output ports for the given node have been assigned. Thus, if the
first after a has a defaulted output port number, port 1
will be assigned if and only if no other attached to that
references output port 1.
It is an error for two to reference
the same output port.
(This particular behavior may be changed in the future to
allow "forking" output streams, which would be copied to more
than
one
destination.)
If the destination number is omitted, then the next node in the (scanning from left to right) is implied. Occasionally a null is generated at
the end of a because of the necessity for resolving such references.
If the destination 's input port number is omitted, then the next unassigned
input port (in increasing numerical order) is implied. As with the defaulted output port, this action takes place only after the entire has been examined.
The comments under (1) above also apply to defaulted input ports.
In addition to the defaults, specifying input/output connections between widely
separated s is aided by alternative means of giving numbers. The last in
a may be referred to by the $, and any may be referred to by an
alphanumeric .
«Node>· labelling is discussed in the section on syntax,
below.)
If the first of a is labelled, the may serve as a target for the
'goto' command; see the Applications Notes for examples.
.
As will be seen in the next section, further syntax is necessary to completely specify
the input/output environment of a ; the reader should remember that s
control only those flows of data between processes.
A few examples of the syntax presented above may help to clarify some of the semantics.
Since the syntax of has not yet been discussed, s will be represented by the
string "node" followed by a digit, for uniqueness and as a key to s.
A simple linear of three s without defaults:
nodel

112.1

node2

113.1

node3

(Data flows from output port 1 of nodel to input port 1 of node2 and output port 1 of node2
to input port 1 of node3.)
The same , with defaults:
nodel I node2 I node3
(Note that the spaces around the vertical bars are mandatory, so that the lexical analysis
routines of the command interpreter can parse the elements of the command unambiguously.)
A simple cycle:
nodel 11. 2
(Data flows from output port
unspecified at this level.)

of nodel to input port 2 of nodel.

- 8 -

Other data flows are

Command Interpreter User's Guide
A branching with overidden defaults:
nodel

1.1

node2

node3

(Data flows from output port I of nodel to input port 2(1)
node2 to input port I of node3.)

of node3 and

output

port

Nodes
::=

{:}

[ I 1

::= {

{

::= { }
'{' { } '}'
{ }
::=
[ 1
[ 1

'> '
,> '

'» '
,» '

[

[ 1

::=
::=
::=
The is the basic executable element of the command language.
It consists of zero
or more labels
(strings of letters, digits, and underscores, beginning with a letter),
optionally followed by one of two additional structures. Although, strictly speaking, the
syntax allows an empty node,
in practice there must be either a label or one of the two
additional structures present.
The first option is the .
It specifies the name of a command to be performed, any arguments that command may require, and any s that will affect
the data environment of the command.
«I/o redirectors will be discussed below.)
The execution of a simple node normally involves the creation of a single process, which performs some
function, then returns to the operating system.
The second option is the .
It specifies a which is to be executed
according to the usual rules of evaluation (see the previous subsection), and any s that should affect the environment of the .
The is
provided for two reasons.
One, it is occasionally useful to alter default port assignments
for an entire with s, rather than supplying s for each
.
Two, use of compound nodes containing more than one gives the user some
control over the order of execution of his processes. These abilities are discussed in more
detail below.
Since it is the more basic construct, consider the .
It consists of a
with s, intermixed with s.
The must
be a filename, usually specifying the name of an object code file to be loaded. The command
interpreter locates the command to be performed by use of a user-specified "search rule.The search rule resides in the shell variable" search rule", and consists of a series of
comma-separated elements.
Each element is either a-template in which ampersands
(&)
are
replaced by the or a flag instructing the command interpreter to search one of
its internal tables.
The flag N~int" indicates that the command interpreter's repertoire of
"internal" commands is to be checked.
(.1\0 internal command is implemented as a subroutine of
the command interpreter, typically for speed or because of a need to access some private data
base.) The flag "~var" causes a search of the user's "shell variables"
(see below for
further discussion of variables and functions).
The following search rule will cause the
command interpreter to search for a comm3nd among the internal commands, shell variables, and
the directory "=bin=", in that order:
n~int,·var,=bin=/&"

The purpose of the search rule is to allow optimization of command location for speed, and to
admit the possibility of restricting some users from accessing "privileged" commands.
(For
example, the search rule
n·var,//project/library/&"
would

restrict

user

accessing

his

variables
- 9 -

and

those commands in the directory

Command Interpreter User's Guide
H//project/library".
He could not alter this restriction, since he does not have
the (internal) 'set' command; the "Aint" flag is missing from his search rule.)

access

s to be passed to the program being readied for execution are gathered by the
command interpreter and placed in an area of memory accessible to the library routine
'getarg'.
They may be arbitrary strings, separated from the command name and from each other
by blanks.
Quoting may be necessary if an could be interpreted as some other
element of the command syntax.
Either single or double quotes may be used.
The appearance
of two strings adjacent to one another without blanks implies concatenation. Thus,
"quoted "string
is equivalent to
"quoted string"
or to
quoted' string'
Single quotes may appear within strings delimited by double quotes, and vice versa; this is
the only way to include quotes within a string.
Example:
"'quoted string'"
'"Alas, poor Yorick!'"
Arguments are generally unprocessed by the command
information useful to the program being invoked.

interpreter,

and

may

contain

any

In the previous section, it was shown that streams of data from "standard ports" could
be piped from program to program through the use of the syntax.
It is also
possible to redirect these data streams to files, or to use files as sources of data.
The
construct that makes this possible is the .
The is composed
of filenames, port numbers (as described in the last section), and one or two occurrences of
the" funnel" (».
The two simplest forms take input from a file to a standard port or output from a standard port to a file.
In the case of delivering output to a file, the file is automatically
created if it did not exist, and overwritten if it did.
In the case of taking input from a
file, the file is unmodified.
Example:
documentat ion> 1
causes
node;

the

data

the

file "documentation" to be passed to standard input port 1 of the

l>results
causes data written to standard output port 1 of the node to be placed on the file "results".
If no is present for a given port, then that port automatically
to the user's terminal.

refers

If port numbers are omitted, an assignment of defaults is made. The assignment rule is
identical to that given above for :
the first available port after the
entire has been scanned is used. s are evaluated left-to-right, so
leftmost defaulted redirectors are assigned to lower-numbered ports than those to their
right.
For example,
data> requests>

trans

2>summary 3>errors 1 sp

is the same as
data>l requests>2 trans 2>summary 3>errors 112.1 sp
where all defaults have been elaborated.
'Trans' might be some sort of transaction processor, accepting data input and update requests, and producing a report (here printed off-line
by being piped to a spooler program), a summary of transactions, and an error listing.
In addition to the s mentioned above, there are two lesser-used redirectors that are useful.
The first appends output to a file, rather than overwriting the file.
The syntax is identical to the other output redirector, with the exception that two funnels
, » ' are used, rather than one.
For example,
6»stuff

- 10 -

Command Interpreter User's Guide
causes the data written to output port 6 to be appended to the file "stuff".
(Note the lack
of spaces around the redirectori a redirector and its parameters are never separated from one
another, but are always separated from surrounding arguments or other text. This restriction
is necessary to insure unambiguous interpretation of the redirector.)
The second redirector
causes input to be taken from the current command source file.
It is most useful in conjunction with command files. The syntax is similar to the input redirector mentioned above, but
two funnels are used and no filename may be specified. As an example, the following segment
of a command file uses the text editor to change all occurrences of "March" to "April" in a
given file:
»ed file
g/March/s//April/

w
q

When the editor is invoked, it will take input directly from the command file,
will read the three commands placed there for it.

and

thus

The "command source" and "append" redirectors are subject to the same resolution of
defaults as the other redirectors and has been covered, just two further considerations remain.
First, the nature of an executable program must be defined.
Second, the problem of execution
order must be clarified.
In the vast majority of cases, a may also specify an internal command, a
shell variable, or a command file.
Internal commands are executed within the command
interpreter by the invocation of a subroutine. When a shell variable is used as a command,
the net effect is to print the value of the variable on the first output port, followed by a
newline.
If the filename specified i3 a text file rather than an object file, the command
interpreter "guesses" that the named file is a file of commands to be interpreted one at a
time.
In any case, command invocation is uniform, and any or given will be honored. Thus, it is allowable to redirect the output of a command
file just as if it were an object program, or copy a shell variable to the line printer by
connecting it to the spooler through a pipe.
As mentioned in the section on s, the execution order of nodes in a is
undefined. That is, they may be executed serially in any order, concurrently, or even simultaneously. The exact method is left to the implementor of the command interpreter.
In any
case, the flows of data described by s and s are guaranteed
to be present. There are times when it would be preferable to know the· order in which a
will be evaluated; to help with this situation, s may be used to effect
serialization of control flow within a network. s separated by semicolons or newlines
are guaranteed to be executed serially, left-to-right, otherwise the command interpreter
would exhibit unpredictable behavior as the user typed in his commands. Suppose it is necessary to operate four programs; three may proceed concurrently to make full use of the multiprogramming capability of the computer system, but the fourth must not be executed until
the second of the three has terminated.
For simplicity, we will assume there are no
input/output connections between the programs.
The following command line meets the
requirements stated above:
programl, {program?; program4}, program3
(Recall that the comma represents a null i/o connection.)
Suppose that we have a slightly
different problem: the fourth program must run after all of the other three had run to completion. This, too, can be expressed concisely:
programl, program2, program3; program4
Thus, the user has fairly complete control over the execution order of his s.
(The use
of commas and semicolons in the command language is analogous to their use for collateral and
serial elaboration in Algol 68.)
This completes the discussion of the core of the command language. The remainder of the
features present in the command interpreter are provided by a built-in preprocessor, which
handles function calls, iteration, and ~omments.
The next few sections deal with the
preprocessor's capabilities.
-

11 -

Command Interpreter User's Guide
Comments
Any good command language should provide some means for the user to comment his code,
particularly in command files that may be used by others. The command interpreter has a simpIe comment convention: Any text between an unquoted sharp sign (It) and the next newline is
ignored. A comment may appear at the beginning of a line, like this:

It command file to preprocess, compile, and link edit
Or after a command, like this:
file.r> rp

It Ratfor's output goes to the terminal

Or even after a label, for identification of a loop:
:loop

It beginning of daily cycle

As far as implications
equivalent to a newline.

in other areas of command syntax, the comment is functionally

Variables
::;
::; set [ ] ;

[ ]

::; declare { ] }
::; forget {
The command interpreter supports named string storage areas for m'iscellaneous user
applications. These are called variables.
Variables are identified by a name, consisting of
letters of either case, digits, and underscores, not beginning with a digit. Variables have
two attributes: value and scope. The value of a variable may be altered with the 'set' command, discussed below. The scope of a variable is fixed at the time of its creation1 simply,
variables declared during the time when the command interpreter is taking input from a command file are active as long as that file is being used as the command source. Variables
with global scope (those created when the command interpreter is reading commands from the
terminal) are saved as part of the user's profile, and so are available from terminal session
to terminal session.
Other variables disappear when the execution of the command file in
which they were declared terminates.
Variables may be created with the 'declare' command.
'Declare' creates variables with
the given names at the current lexical level (within the scope of the current command file).
The newly-created variables are assigned a null value, unless an initialization string is
provided.
Variables may be destroyed prematurely with the 'forget' command. The named variables
are removed from the command interpreter's symbol table and storage assigned to them is
released to the system. Note that variables created by operations within a command file are
automatically released when that command file ceases to execute. Also note that the only way
to destroy vari~bles at the global lexical level is to use the 'forget' command.
The value of a variable may be changed with the 'set' command. The first argument to
'set'
is the name of the variable to be changed.
If absent, the value that would have been
assigned is printed on 'set's first standard output. The last argument to 'set' is the value
to be assigned to the variable.
It is uninterpreted, that is, treated as an arbitrary string
of text.
If missing, 'set' reads one line from its first standard input, and assigns the
resulting string.
If the variable named in the first argument has not been declared at any
lexical level, 'set' declares it at the current lexical level.
Variables are accessed by name, as with any command.
(Note that the user's search rule
must contain the flag n~var" before variables will be evaluated.) The command interpreter
prints the value of the variable on the first standard output. This behavior makes variables
useful in function calls (discussed below).
In addition, the user may obtain the value of a
variable for checking simply by typing its name as a command.
Iteration
::; '(' { } ')'
Iteration is used to generate multiple command lines each differing by one or more substrings. Several iteration elements (collectively, dn "iteration group")
are placed in

- 12 -

Command Interpreter User's Guide
parentheses; the command interpreter will then generate one command line for each element,
with successive elements replacing the instance of iteration. Iteration takes place over the
scope of one ; it will not extend over a .
(If iteration is applied to a
, it will, of course, apply to the entire ; not just to the first
within that .)
Multiple iterations may be present on one command; each iteration group must have the
same number of' elements, since the command interpreter will pick one element from each group
for each generated command line.
(Cross-products over iteration groups are not implemented.)
An example of iteration:

1 fos part(l 2 3)
is equivalent to

1 fos partl; fos part2; fos part3
and

1 cp (intro body summary) part(l 2 3)
is equivalent to
] cp intro partl; cp body part2; cp summary part3

Function Calls
::= ' [ ' { } '1'
Occasionally it is useful to be able to pass the output of a program along as arguments
to another program, rather than to an input port. The "function call" makes this possible.
The output appearing on each of the first standard output ports of the s within the
function call is copied into the command line in place of the function call itself.
Line
separators
(newlines) present in the 's output are replaced by blanks. No quoting of
output is performed, thus blank-separated tokens will be passed as separate arguments.
(If quoting is desired, the filter 'quot~' can be used or the shell variable" quote opt" may
be set to the string "YES" to cause automatic quotation.)
A may of course be any '1etwork; all the syntax described in this document is
applicable.
In particular, the name of 1 variable may appear with the brackets; thus, the
value of a variable may be substituted i~to the command line.
Conclusion
This concludes the description of command syntax and semantics. The next, and final,
chapter contains actual working examples of the full command syntax, along with suggested
applications; it is highly recommended for those who wish to gain proficiency in the use of
the command language.

- 13 -

Command Interpreter User's Guide
Application Notes
This section consists mostly of examples of current usage of the command interpreter.
Extensive knowledge of some Subsystem programs may be necessary for complete understanding of
these examples, but basic principles should be clear without this knowledge.
Basic Functions
In this section, some basic applications of the command language will be discussed.
These applications are intended to give the user a "feel" for the flow of the language,
without being explicitly pedagogical.
tern.

One commonly occurring task is the location of lines in a file that match a certain patThe 'find' command performs this function:
file> find pattern >lines_found

Since the lines to be checked against the pattern are frequently a list of file names, the
following sequence occurs often:
] If -c directory 1 find pattern
Consequently, a command file named 'files' is available to abbreviate the sequence:
] cat =bin=/files
If -c [args 2] 1 find [arg 1]
('Cat' is used here only to print the contents of the command file.)
The internal command
'arg' is used to fetch the first argument on the command line that invoked 'files'.
Similarly, the internal command 'args' fetches the second through the last arguments on the
command line. The command file gives the external appearance of a program 'files' such that
]

files pattern

is equivalent to
]

I f -c 1 find pattern

]

files pattern directory

and

is equivalent to
I f -c directory 1 find pattern

Once a list of file names is obtained, it is frequently processed further, as in this command
to print Ratfor source files on the line printer:
] pr [files .r$

1 sort]

'Files'
produces a list of file names with the ".r" suffix, which is then sorted by 'sort'.
'Pr' then prints all the named files on the line printer.
One problem arises when the pattern to be matched contains command language metacharacters.
When the pattern is sUbstituted into the network within 'files', and the command
interpreter parses the command, trouble of some kind is sure to arise.
There are two
solutions:
One, the filter 'quote' can be used to supply a layer of quotes around the pattern:
I f -c [args 2]

1 find

[arg 1 1 quote]

Two, the shell variable" quote opt", which controls automatic function quotation by the command interpreter, can be set to-the string "YES":
declare. quote opt = YES
If -c [args 2]-1 find [arg 1]
This latter solution works only because 'args' prints each argument on a separate line; the
command interpreter always generates separate arguments from separate lines of function output.
In practice, the first solution is favored, since the non-intuitive quoting is made
more evident.

- 14 -

Command Interpreter User's Guide
One common non-linear command structure is the so-called "Y" structure, where two
streams of data join together to form a third (after some processing).
This situation occurs
because of the presence of dyadic operations (especially comparisons) in the tools available
under the Subsystem.
As an example, the following command compares the file names in two
directories and lists those names that are present in both:
If -c dirl I sort 1$ If -c dir2 I sort I common -3
Visualize the command in this way:
If -c dirl

I sort

I f -c dir2

I sort

/
\
\

----_/

common -3

The ~wo 'If' and 'sort' pairs produce lists of file names that are
which produces a list of those names common to both input lists.

compared

Command files tend to be used not only for oft-performed tasks but also
easier when typing long, complex command~;.
Quite often these long command lines
line continuation -- a newline preceded immediately by an underscore is ignored.
ing command file is used to create a k~yword-in-context index from the heading
Subsystem Reference Manual.
Although it is not used frequently, it does a great
and is illustrative of many of the features of the command interpreter.

'common',

to make 1i fe
make use of
The followlines of the
deal of work

It make cmd.k --- build permuted index of commands
files .d$ -f sl
I change % "find %.hd -0 I"
I sh
I change ' %.hd * { [- ] *} [ "] *{ [-Ill *}?*' '@l: @2'
I kwic -d =aux=/spelling/discard _
I sort -d I unrot -w [width] >cmd.k
First a few words on how Subsystem documentation is stored: The documentation for
Subsystem
commands resides in a subdirectory na'oed "sl". The documentation for each command is in a
separate file with the name ".d". The head'ing line in each file can be identified
by the characters ".hd" at the beginning of the line.
The entire command file consists of a single network.
The 'files' command produces a
list of the full path names (the -f option is passed on to 'If') of the files
in the subdirectory "sl" that have path names ending with the characters" .d". The next 'change' command generates a 'find' command for each documentation file to find the heading line.
These
command lines are passed back to the shell ('sh') for execution.
The outputs of all of these
'find'
commands, namely the heading liDes from all the documentation files, are passed back
on the first standard output of 'sh'.
The second 'change' command uses tagged patterns to
isolate the command name and its short description from the header line and to construct a
suitable 'entry for the kwic index generator.
Finally, 'kwic', 'sort', and
'unrot'
produce
the index on the file "cmd.k".
To
this
point,
only
serially-executed commands have been discussed, however
sophisticated or parameterized. Control structures are necessary for more generally useful
applications.
The following command file, 'ssr', shows a useful technique for parametersetting commands.
Like many APL system commands, 'ssr' without arguments prints the value it
controls (in this case, the user's command search rule), while 'ssr' with an argument sets
the search rule to the argument given, then prints the value for verification.
'Ssr' looks
like this:

It ssr --- set user's search ruLe and print it
if [nargs]
set search rule
fi

[arg 1 I quote]

search rule
The 'if' command conditionally executes 0ther commands.
It requires one argument, which is
interpreted as "true" if it is present, not null, and non-zero.
If the argument is true, all
the commands from the 'if' to the next unmatched 'else' or 'fi' command are executed.
If the
argument is false, all the commands from the next unmatched 'else' command (if one is
present) to the next unmatched 'fi' comm~nd are executed.
In 'ssr' above,
the argument to
'if' is a function call invoking 'nargs', a command that returns the number of arguments passed to the command file that is currently active.
If 'nargs' is zero, then no arguments were
specified, and 'ssr' does not set the user's search rule.
If 'nargs' is nonzero, then 'ssr'
fetches the first argument, quotes it to prevent the command interpreter from evaluating
special characters, and assigns it to the user's search rule variable' search rule'.
- 15 -

Command Interpreter User's Guide
'If' is useful for simple conditional execution, but it is often necessary to select one
among several alternative actions instead of
just one from two. The 'case' command is
available to perform this function.
One example of 'case' is the command file 'e', which is
used to invoke either the screen editor or the line editor depending on which terminal is
being used (as well as remembering the name of the file last edited):

t e --- invoke the editor best suited to a terminal
i f [nargs]
set f = [arg 1 I quote]
fi

case [line]
when 10
se -t
when 11
se -t
when 15
se -t
when 17
se ..;.t
when 18
se -t
when 25
se -t
out
ed [ fJ
esac

consul [se_params]

[ f]

b200

[se_params]

[ f]

b150

[se_params]

[ f]

gt40

[se_params]

[ f]

b200

[se_params]

[ f]

bl50

[se_params]

[f]

The first 'if' command sets the remembered file name (stored in the shell variable
'f')
in
the same fashion that 'ssr' was used to set the search rule (above).
The 'case' command then
selects from the terminals it recognizes and invokes the proper text editor.
The argument of
'case'
is compared with the arguments of successive 'when' commands until a match occurs, in
which case the group of commands after the 'when' is executed; if no match occurs, then the
commands after the 'out' command will be executed.
(If no 'out' command is present, and no
match occurs, then no action is taken as a result of the 'case'.)
The 'esac'
command marks
the end of the control structure.
In 'e', the 'case' command selects either 'se' (the screen
editor) or 'ed' (the line editor), and invokes each with the proper arguments (in the case of
'se', identifying the terminal type and specifying any user-dependent personal parameters).
The 'goto' command may be used to set up a loop within a command file.
following command file will count from 1 to 10:

For example, the

t bogus command file to show computers can count
declare i

:loop
i
set i = [eval i + 1]
if [eval i <= 10]
goto loop
fi
In actual experience, little need has been found for loops within command files; thus the
need for this contrived example.

Shell Control Variables
Several special shell variables are used to control the operation of the command
interpreter. The following table identifies these variables and gives a short explanation of
the function of each.
Variable

Function

ci name

This variable is used to select a command interpreter to be executed when the
user enters the Subsystem.
It should be set to the full pathname of the command interpreter desired. The default value is "=bin=/sh".

erase

This variable may be set to a sin'lle character or an ASCII mnemonic for a
character to be used as the "erase," or character delete, control character
for Subsystem terminal
input processing.
The change in erase character
becomes effective only after the Subsystem is re-entered and the
initialization routines read the shell variable storage file.

- 16 -

Command Interpreter User's Guide
_escape

This variable may be set to a single character or an ASCII mnemonic for a
character to be used as the "escape" control character for Subsystem terminal
input processing. The change in escape character becomes effective only after
the Subsystem IS re-entered and the initialization routines read the shell
variable storage file.

hello

This variable, if present, is used as the source of a command to be executed
whenever the user enters the Subsystem.
It is frequently used to implement
memo systems, supply system status information, and print pleasing messagesof-the-day.

kill

This variable may be set to a single character or an ASCII mnemonic for a
character to be used as t~e "kill," or line delete, control character for Subsystem terminal input pro~essing. The change in kill character becomes effective only after the Subsystem is re-entered and the initialization routines
read the shell variable storage file.

_prompt

This variable contains the prompt string printed by the command interpreter
before any command read from the user's terminal.
The default value is a
right bracket (]).
This variable, if set t:> the value "YES", causes automatic quotation of each
line of program output used in a function call.
It is mainly provided for
compatibility with an 0lder version of the command interpreter, which performed the quoting automatically.
The program 'quote' may be used to
explicitly force quotation.
This variable may be set to a single character or an ASCII mnemonic for a
character to be used as the "retype" control character for Subsystem terminal
input processing. The change in retype character becomes effective only after
the Subsystem IS re-entered and the initialization routines read the shell
variable storage file.

_retype

search rule

This variable contains a sequence of comma-separated elements that control the
procedure used by the command interpreter to locate the object code for a command. Each element is either
(1) the flag "-int", meaning the command
interpreter's table of internal commands, (2) the flag a- var ", meaning the
user's shell variables, or (3) a template containing the character ampersand
(&), meaning a particular directory or file in a directory.
In the last case,
the command name specified by the user is substituted into the template at the
point of the ampersand, hopefully providing a full pathname that locates the
object code needed.

Symbiotic Commands
There are several commands that, in effect, live symbiotically with the Shell.
In the
following sections, some of the more useful of these will be reviewed. For further
information, consult the Software Tools Subsystem Reference Manual.
Argument Fetching. Four internal commands are frequently used in shell programs to
fetch arguments given on the command line.
'Arg' fetches a single argument, 'args' fetches
several, 'argsto' fetchs a specified group, and 'nargs' returns the number of available
arguments.
arg []
'Arg' prints on its first st3ndard output the argument which appeared in the
th position in the c~mmand line invoking the shell program containing
'arg'.
Position zero refers to the command name, position one to the
first argument, etc.
If an illegal position is specified,
'arg' prints
nothing. The optional second :;rgument, , specifies the number of lexic
levels to ascend in order t.) reach the desired argument list. The entry of
any command file or function c~ll constitutes a new lexic level; thus, an
'arg' command used in a functi'm call to fetch an argument to the command file
containing the function call needs a of 1 (to escape the lexic level
in which the function is evaluQted).
In fact, this is the most common use of
'arg', so the default value Eor is 1. The following three commands,
when placed in a command file, would cause that command file's first argument
to be printed three times on standard output one:
echo [arg 1]
echo [arg 1 1]
arg 1 0

- 17 -

Command Interpreter User's Guide
args [ []]
'Args' prints on its first standard output the arguments specified on the command file lexic levels above the current level. is the position on the command line of the first argument to be printed; is the
position of the last argument to be printed.
If is omitted, the final
argument on the command line is assumed. has the same meaning as for
'arg' above.
argsto [ [ [ 1 1 1
'Argsto'
prints a group of arguments delimited by arguments consisting of
.
is an integer that controls which group of arguments is
printed.
If is 0 or omitted, arguments up to the first occuience of
are printed; if is I, arguments between the first occurrence
of and the second occurrence of are printed, and so on.
is an integer indicating the argument at which the scan is to begin;
if is omitted
(or is I), the scan begins at the first argument.
has the same meaning as for 'arg' above.
narg s [< level>]
'Nargs' prints on its first standard output the number of arguments passed to
the command file lexic levels above the current level.
has
the same meaning as for 'arg' above.
Shell Tracing. The 'shtrace' command is useful for tracing the operation of the shell.
Although primarily intended for debugging the command interpreter itself, it also finds use
in monitoring and debugging shell files.
To turn the trace on, enter
shtrace on
To turn the trace off, enter
shtrace
Many other optiqns are available.
details.

Consult the Software Tools Subsystem Reference Manual

for

Shell Variable Utilities. The following commands (in addition to 'declare', 'set', and
'forget' discussed earlier) have been found useful in dealing with shell variables.
Further
information can, as usual, be found in the Software Tools Subsystem Reference Manual.
vars
'Vars' lists the names
(and optionally the values)
of the user's shell
variables. Various options control the listing format, the number of lexic
levels scanned, and whether or not shell control variables are listed. The
most common form is probably
vars -alv
which lists all variables at all lexic levels along with their values.
save
'Save' forces the user's lexic level zero shell variables to be written to the
user's private shell variable save file.
This operation normally takes place
only when the shell exits to Primos after a 'stop' or control-c, but it is
frequently convenient (and essential from some command files)
to save
variables without leaving the shell.
Conclusion
This concludes the Application Notes section of the guide. Hopefully it has presented
some ideas that will make the use of the command interpreter more productive and enjoyable.

- 18 -

Command Interpreter User's Guide
Messages from the Shell
Listed here are messages with obscure meanings that are produced by the Shell; several
In the
indicate dire internal problems that should not occur during normal operation.
interest of saving paper, self-explanatory messages are not included.
: not found
The list of elements in the search rule was exhausted, but the command had not been
located.
: too many ci files
The nesting depth of command files nas been exceeded. This is usually caused by an
Inflni tely recursive call on a comm,md file. The maximum nesting depth
(currently
10) is a compile time option of the shell and may be increased at the expense of
additional table space.

continue?
This message occurs after each network when the "single step" shell trace option is
set. A line beginning with anythinq other than an upper or lower case letter nn"
will cause the shell to execute the next network. A response beginning with nn"
will cause the shell to return to command level.
illegal destination node spec
The destination node specifier must be a defined label or a number
the number of nodes in the network.

between

and

illegal port number
A port number must be a number between 1 and the maximum number of standard ports
defined (currently 3).
missing command name
Although an empty net is allowable, redirectors must not
command name.

specified

without

missing pathname in redirector
A greater-than sign was encountered without a pathname on either side.
net is not serially executable
Because multiple processes per user are not supported, each node of a net must be
executed serially. Therefore, nets which have pipe connections that form ,a complete cycle cannot be executed.
overflow (save state):
The nesting depth of command files ~as been exceeded. This is usually caused by an
infinitely recursive callan a command file.
The maximum nesting depth (currently
10) is a compile time option of the shell and may be increased at the expense of
additional" table space.
pipe destination not found
The destination node of a pipe is not in the range of the current net.
state save stack overflow
The nesting depth of command files :las been exceeded. This is usually caused by an
infinitely recursive calIon a co~~and file.
The maximum nesting depth (currently
10) is a compile time option of the shell and may be increased at the expense of
additional table space.
unbalanced iteration groups
Because of the semantics of iter~tion, each iteration group in the same net must
contain the same number of argument~;.
unexpected EOF on variable save file
End of file has been encountered on the shell variable save file when a value has
been expected. The shell variables have been corrupted. To recover what might be
left, exit the Subsystem with a or control-P and consult your system
administrator.
whitespace required around pipe connector
A pipe connector and its assoc'ated port numbers and destination label must be
surrounded by spaces.
whitespace required around i/o redirector
An i/o redirector and its associated i/o redirector must be surrounded by spaces.

- 19 -

User's Guide for the Ratfor Preprocessor
Second Edi tion

Daniel H. Forsyth, Jr.
To Allen Akin
p ~ r r y B. Fl inn

School of Inforlnation and Computer Science
Georgia Institute of Technology
Atlanta, Georgia 30332
Apr iI, 1980

TABLE OF CONTENTS

Ratfor Language Guide

What is Ratfor?

Differences Between Ratfor and Fortran ••••••••••••••••••••••••.••••••••••••••••••••••
Source Program Fo rmat •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Case Sensitivity •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Blank Sensi tiv i ty •••••••••••••••••••••••••••••••••••••.••••••••••••••••••••••••
Ca rd Col umns ....................................................................... .
Multiple St~tements per Line •••••••••••••••••••••••••••••••••••••••••••••••••••
Statement Labels and Continuation ••••••••••••••••••••••••••••••••••••••••••••••
Comments •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Identifiers •••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Integer Constants •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
String Constants ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Logical and Relational Operators ••••••••••••••••••••••••••••••••••••••••••••••••••
Assignment Operators ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Incompatibilities •.•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

1
1
1
1

Ratfor Text Substitution Statements ••••••••••••••••••••••••••••••••••••••••••••••••••
Define . . . . . . . . . . . . . . . . . . . . . . . . . • • • . . . . . . . • . . . . • . . . . . . . . . . . . . . . . . . . . . . . • . • . . • . . . . . .
Undefine ••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Include ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• ,••••••••••

8
8
10
10

Ratfor Declarations ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
String ••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Stringtable •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Linkage •••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Local ................................................................................................................................... ..

11
11
11
12
13

Ratfor Control Statements ••••••••••••••••••••••••••••••••••••••••..••••.•••••••••••••
Compound Statements ••••••.••••••••••••••••••••••••••••••••••••••••••••••••••••••••
If - El se •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
While •••••••••••••••••••••••••••••••.•••••••••••••••.•••••••••••••••••••••••••••••
Repeat ••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

14
14
14
14
15
15
16
16
17
17
18
19

Fo r ..................................................................................................................................................... ..
Break ..................................................................................................................................................... ..
Nex t ••••••.•..•.••••••••••••••••••••.•...•.•.•...••••••••••.••••••..••••..••...•••
Return ................................................................................................................... .

Select ••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Proced ure •••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

2
2
2
3
3
4
5
6
6

Rattor Language Reference

Differences Between Rattor and Fortran
Source Program Format •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Identifiers •••••••••••••••••••••••••.•••••••••••••••.••••••••••••••••••.••••••••••
Integer Constants •••••••••••••••••••.•••••••••••••••••••••••••••••••.•••••••••••••
String Constants ••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Logical and Relational Operators ••••.•••••••••••••••••••••••••••••••••••••••••••••
Assignment Operators ••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••
Incompatibilities •••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

21
21
21
21
21
22
22
22

Ratfor Text Substitution Statements ••••.•••••••••••••••••••••••••••••••••••••••••••••
De fine .............•..•......................•....•...•...................••......
Undefine ....•.........•.....•.•.............••...••..••...•..•..........•.••.•....
Include •••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••••••••••••••••

23
23
23
23

iii

Ratfor Declarations ••.•••••.•••••••••••••••••••.•••.•••••••••••.•••••••••••••••••••••
Linkage ••••••..•••.•••••••••••••••••••••••••.•••.•••••••••••.•••••••••••••••••••••
Lo ca 1 ••••••••••.•..••••••••••••••.••••••••••.•••.•••••••.••.••••••••••••••••••••••
String ••••.........•••••••••••.•....••••.••....•..•.••••••.......••••••.•.••••••.•
Stringtable ••...•.•.•••••••••••••.••••••••••••••.•••••..••••.•••••••••••••••.•••.•

23
23
24
24
24

Ratfor Control Statements ••••.....•••••••••••••.•••.•••••••••••..•••••••••.••••••••.•
Break ••.•••••••••••••••••••.••••••••••••••••.•...••••••••••••••••••••.••••••••••••
Do •••••••••••...•.••••••••••••••••••••.•••••••••.••••••.•••••••••.••..•••.••..••••
For

24
24
24
24
24
24
25
25
25
25
25

Nex t •••.••••••..•.••.•.••••••••••••••••••••.••••.••••.•••.•.••••••••..••••••••••••
Procedure ••••••••..•••••••••••••••••••••••••.••..••••••••..•.•••••••.• "••••••••••••
Repea t •••••••.••...••••••••••••••••••••••.••••.•.•.•••••••••••••••••••••••••••••••
Return •..••••.•.•••••.•.••••••.•.•••••••••••••••.••••••••••••••••••.•••••••••.••
Select ..•.•...••...••••.•••••.••••••••••••••••.•.•.•••.••••••.••.••••••••••••••.
While •.••••••......••...•••••••••••••••••.••......••••••••......•.•••.••.••••••.

Ratfor Programming Under the Subsystem

Requirements for Ratfor Programs ••...••••••••••••••.••.•••••.••••••••••••••..•.••..

Running Ratfor Programs Under the Subsystem ••••••••.•.••••••.••••••••••••••••••••••
Preprocessing •..•••••.••••.••••..••••••••••••.••..•••••.••.••••••..•••••••••••••
Compiling ••••••••••••••.••••••••••••••••••••••••.•••••••••••••••••••••••••••••••
Linking ••••••.•.••••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••
Executing ••••.•••••••••••••••••.••••••••••••••••.••••••••.••••••••.•..•.•••••••.
Shortcuts •.••.•.•••••••••••••••••••••••••.••••••.•••••.•••••••••••••••.•••••••••
Shell Programs •••••••••••••••••••••••••••••••.•••••.•••••••••••.•••••••••••••••
The 'Rfl' Command •••.•••••••••••••.•.••••••••..••••••••••••.•••••••...••••••.
Storing Source Programs Separately •••••••••••.•••••••••••••••••.••••••..•.•••
Compiling Programs Separately ••••.••••••.••.•.•••••••••••••••••...••••••.•••.
Debugg ing ••••••••••••••••••••••••.••.••••••••••..•••••••••••••••••••••••••••••••••
Performance Monitoring ••.••••••••••••••••••••••..••••.•••••••••••••••••.•.••••••
Conditional Compilation ..••••••••••••.••..••••••.•••.••••••••..••••••••••.•••••.

26
27
27
28
29
29
29
30
30
30
31
33
34

Source Program Format Conventions ••••.••••....•••••...•••••••..•.••••..•••....•.••.
Statement Placement •••••••••.••.••••••••••••••••.•••••••••••••••••..••••••••••••
Indentation ••.•••••••••••••••.•••••••••••.••••••.•••••••••••••••••••••••..••••••
Subsystem Definitions •••••••••••••••.•••••••••••.•••••••••••••••••••.•••••.

34
34
35

Using the Subsystem Support Routines •••.••••••••••...••••••••••••••••.••••.•..••.••••
Initialization and Termination •.•.•••••••••••••...••••••••••••••••.••••.••••••••••
In it ••.•••.•••••••••••••••.•.••••••••••..••••.••••••••••••••••••••••.•••..•••••
Swt •••••.•.••••••••••.•••.•••••••••••••••.•••.•••••••••.•••••••••••••••••••••••
Character Strings •••••••.••••••.•••••••••••••••...••••••••.•••••••.•.••..•••.•..••
Eq u a 1 •••••.•.•••••••••••...•.•.•••••••••••••...••••••••.•••••••••••••.•••••••••
Index •••.••••••••••.•.•••.•..••••••••••••••••.••••••••.••••••••.••••.•.•.••••••
Leng th ••.•.•••••••.•.••••..••••••••••••.•••••••••••.•••••••••••..••••••••.•••••
Mapdn and Mapup •••••........•••••.••...•..•••.•..•.•••••.•••••••••••.•.•••••••.
Mapstr •••••••••••••.•.••••••.••••••••••••••••.•••••••••••••••••..••••••••••••••
Sc 0 py •••••••••••..•.•.•••••••••••••••••••••••.•••••••••.•••••.••••••.•.•••••.••
Type •••••••••••••••••••••.•••••••••••••••••••.•••••••••••••••••••••••••••••••••
File Access •••.••••••••..••••••••••••••••.•••••••••••••••••••••..••••••.•.••••••••
Open and Close •.•••••••••.••••••••••.••••••••.••••••••••••••••••.•••.•.••••••••
Create .•..••..•.•.•••.•......•.•.••.••••..•••.••••.••••••••..••.••••..•...•••••
Mktemp and Rmtemp ..••.•••..•••••••••••••••••..••••.••••••••••••••••••••••••••••
Wi nd and Rewi nd .•••••.•..•...•••••••••••••....•.•••••••...••••....••••.•••...••
Trunc
Remove .•.••••••••••.•.••••••.•••••••.••••••••..••.••••••••.•••••••••.•••.•...••
Ca n t . . . . . . • • • • • . • . • . • . . . . . . • • . . • . . • . . . . • • . . • . . . • . • • • • • • . • . . . • . . . • . . • . . . . . • • • . • •
Getlin ••.•••••••••••••••••••••••.•.•.••••••••..••••••••••••••••••••••••••.•••••
Getch
Input
Read f
Pu t1 in
Putch
Pr i n t ••••••••••••.....•.•..•••••••••..•••...•.•••••..••.•••••.••••••••••.••••••
Writef •••••••••••••••••••••••.•..•.••••••••••..•••••••••••••.••••••••••••••••••
Fc 0 py •••••..•••••.•••.•••...•••••••••••••••••.••••••••••••••.•••••••.••••••••••
Markf and Seekf •...••.••••••.•.•.•.••••••••••.••••••••••.••••••••.•••••••••••••

36
36
36
36
36
37
37
37
37
38
38
38
38
39
39
39
40
40
40
40
40
40
41
42
42
42
42

43
43
43

Getto ••••••••••.•••••••••••••••••.•••••.•.••••••.••••••••.•.•.••••••••••••..•••
Type Conversion •••••••••••••.•••••••.•••••••••••••••••••••••••..••••••••••••••.••.
Decode •••••••••.••..•.••••.•.••••.•••••••••.••••.••••.••.•••••.•.•••••..••.••••
Encode •••••••••..•...•••••••••••••••••••••••••••••••••••••••...•••••.••••••••••
Argument Access •••.•••.•••••••••••••••••.••••••••••.••••••••.••••••••.•.•••••..•••
Getarg •••••••••.•••..•••••••••••..••••••••••••••.••••••••••••..••••••••••••.•••
Dynamic Storage Management........................................................
Ds i nit •••••••••••.•••••.•••.•••••..•...••.•••••••••...••••..••••.••.•••••••.•••
Dsget ••.•••.•••••.•••••••.••••••..••.•••••..•••••••••••••.•••.••••••••••.••••••
Ds f r e e •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Ds dum p •••••••••.•••••••••••••••••..••.••••••••••••••••••••••••.••••••••••••••••
Symbol Table Manipulation •••••••••••..•.•••••••.••••.••••••••.•••.•••••••••••••••.
Mktabl •••••••.•••.••••••••.•.•....••••...••••••.•.•••••.•.••••••••••.•••.•.•.•.
Enter ••.•••••.•••.••.••••••••••••.••••••••.••••••••••••...••••.•••••.••••••..•.
Lookup •••...••••••..••••••..•••••..•....•••••••...•.•••..••••••..•.••••.•••.•••
Delete ••.••..••.••••••••••••.••••.•..••••••••••••••••••••••••.••••••••••••••.••
Rmtabl ••...••••.•..••••.••••••.•••••....••••..••.•••..•..••••.•.•••••••••••..•.
Sctabl •••.•.••.•..•••..•.••••• ~ . . . • • • . • • • • • • • • • • • • • • • • • . • . • • • . . • • • • • . • • • • • . • • • •
Other Routines •....•••••.••••••••••..•••..••••••...•••••••.•••••..•••••••.•••.••.•

44
44
46
46
46
46
47
47
47
47
47
48
49
49
49

50
5,9
50
51

Appendixes

Appendix A -- Implementation of Control Statements •••.••••.......••.•..•.•.•••.••....
Break ••••••••••..•••••.••.•••••.••••.•..•••••••.•••...•.•••••••..•••••••••••••••••
Do ••••••••••..•••••••....••••.•.••.•.•••••••••••...••••••.•••••.••..•••••...••••..
Fo r •••••••••••••••••••••••••••••••••.•••••••••••••••.•••••••.•••••••••••••••••••.•
If. . • • • • • . • • • • • • • • . . • • • • . . • . . . • . • • • . . • • . • • • • • • . . • • . • . . . • . • • • . . . . • • • • • . . • • . • • • • . . • .
If - Else •••••...•••••..••.••••.••.•.••••••••••••••••••••••..••••.•••.•••••.••••••
Next .•••••••••••••..••..•.....•.•....••.•..•••••••.•.••••.•..•.••••...••••••••••••
Repeat ••.•••••••.••••••...•••••.•.••.••.••••••••.••••••.••••..•••.•.•.•••••••••••.
Return ••••••••••••.••...••......•.•.....•.•.....••.•.....•.•....••••••••••••••.••.
Select •••••••.•••.•••••...•••.••••.•.•••••••••••••.••..•••••••.••••..•.•••••••••••
Select «integer expression»
.•..•...••.••.•••••••..•••..•..•••......•••••••••••..
While ..••••••..••••••••••.••••..•••..•.••••••••••••••••.•••••.••••••••••••••••••••

55
56
57
58
59
60
61
63
66

Appendix B

Linking Programs With Initialized Common .•.•.•••.•..•••••••..•••.••••••

Appendix C

Requirements for Subsystem Programs ••••••••••.••••.••••••••••••••.••.••

Appendix D
The Subsystem Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Characters •••••...•••••.•••.•....••..••••.•...••••••.••••••••.••••••••••••••••••••
Data Types •••••••.•••••••.•.•...•••...•••.•••..•••••••••.••••.•.••••••.•••••••••••
Macro Subroutines ••••.•.•..•.•••••••.•••••.•••••••.•••••••••••.•••••••.•••••••••••
La n uag e Ex ten s ion s •••••...••••••.•••.•••...••••••.•••••••••••..••••••••••.••••••••
Limits............................................................................
Standard Ports .•••..••.••••.•..•••••...•••••.•••••••.•••.••••.•..•••..••••.•.•••••
Argument and Return Values ••••.•••••..••••••.••••••••..••••••..•••.•••.•••••••••••

69
69
69
69
69
70
70
70

Appendix E -- 'Rp' Reserved Words ..••••..•••••••.•••••••••••••••....••....••••••.•.••

- v -

53
54

Preface
Ratfor
("Rational Fortran") is an extension of Fortran-66 that serves as the basis for
the Software Tools Subsystem.
It provides a number of enhancements to Fortran that
facilitate structured design and programming, as well as enhance program readability and ease
the burden of program coding.
This guide is intended to explain and demonstrate the use of Ratfor as a programming
language within the Software Tools Subsystem.
In addition, applications notes are provided
to help users build on the experience of others.

- vi -

Ratfor User's Guide
Ratfor Language Guide

What is Ratfor?

I·

The Ratfor
("Rational Fortran") language was introduced in the book Software Tools by
Brian W. Kernighan and P. J. Plauger (Adjison-Wesley, 1976). There, the authors use~ as
the medium for the development of pr')grams that may be used as cooperating tools. Ratfor
offers many extensions to Fortran that encourage and facilitate structured design and
programmlng, enhance program readability and ease the burden of coding. Through some very
simple mechanisms, Ratforhelps the programmer to isolate machine and implementation dependent sections of his code.
Among the many programs develop"d in Software Tools is a Ratfor preprocessor -- a
program for converting Ratfor into equivalent ANSI-66 Fortran.
'Rp', the preprocessor
described in this guide, is an origin~l version based on the program presented in Software
Tools.

Differences Between Ratfor and Fortran
As we mentioned, Ratfor and Fortran are very similar.
Perhaps the best introduction
their differences is given by Kernighan"lnd Plauger in Software Tools:

"But bare Fortran is a poor languag~ ·indeed for programming or describing programs.
Ratfor provides modern co~trol flow statements like those in PL/I, Cobol,
Algol, or Pascal, so we can do stru~tured programming properly.
It is easy to
read, write and understand, and re~dily translates into Fortran. . • . Except for
a handful of new statements like if - else, while, and repeat - until,
Ratfor is
Fortran ...
Source Program Format
Case Sensi~ivity.
In mo.st cases, the format of Ratfor programs is much less restricted
than that of Fortran programs.
Since the Software Tools Subsystem encourages use of
terminals with multi-case capabilitie3,
'rp' accepts input in both upper and lower case.
'Rp' is case sensitive.
Keywords, such 3S if and select, must appear in lower case. Case is
significant in identifiers; they may app~ar in either case, but upper case letters are not
equivalent to lower case letters.
For example, the words "blank" and "Blank" do not
represent the same identifier. For circ'Jmstances in which case sensitivity is a bother, 'rp'
accepts a command line option ("-mn) that instructs it to ignore the case of all identifiers
and keywords. See the applications note3 or the 'help' command for more details.
Blank Sensitivity.
Unlike most Fortran compilers, 'rp'. is very sensitive to blanks.
'Rp' requires that all words be separated by at least one blank or special character.
Words
containing imbedded blanks are not allow,~d. The best rule of thumb is to remember that if it
is incomprehensible to you, it is pro:':>ably incomprehensible to 'rp.'
(Remember, we humans
normally leave blank spaces between word.3 and tend not to place blanks inside words.
Such
things make text difficult to understand.)
Asa
properly:

bad

example,

the following Ratfor code is incorrect and will not be interpreted

subroutineexample(a,b,c)
integera,b,c
repeatx=x+l
until(x>l)
A few well placed blanks will have to be added before 'rp' can understand it:
subroutine example(a,b,c)
integer a,b,c
repeat x=x+l
until (x>l)
You should note that extra spaces are allowed (and encouraged) everywhere except inside words
and literals.
Extra spaces make a progr~m much more readable by humans:

1 -

Ratfor User's Guide
subroutine example (a; b, c)
integer a, b, c
repeat x
x + 1
until (x > 1)
Card Columns. As should be expected of any interactive software system,
'rp'
is completely insensitive to "card" columns; statements may begin and end at any position in a
line.
Lines may be of any length, but identifiers and quoted strings may not be longer than
100 characters.
'Rp'
will output all statements beginning in column 7, and automatically
generate continuation lines for statements extending past column 72.
All of the following
are valid Ratfor statements, although such erratic in1entation is definitely frowned upon.
integer i, j
i= 1
j = 2
stop
end
Multiple Statements ~ Line.
'Rp' also allows multiple statements per line, although
indiscriminate use of this feature
is not encouraged.
Just place a semicolon between
statements and 'rp' will generate two Fortran statements from them.
You will find
integer
real a
logical 1
to be completely equivalent to
integer i i real a; logical 1
Statement Labels and Continuation. You may wonder what happens to statement labels and
continuation lines, since-'rp' pays no attention to card columns.
It turns out that
statement labels and continuation lines are not often necessary. While 'rp' minimizes the
need for statement labels (except on format statements)
and is quite
intelligent about
continuation lines, there are conventions to take care of those situations where a label is
required or the need for a continuation line is not obvious to 'rp.'
A statement may be labeled simply by placing the statement number, starting in any
column,
before the statement.
Any executable statement,
including the Ratfor control
statements, may be labeled, and 'rp' will place the label correctly in the Fortran output.
It is wise to refrain from using five-digit statement numbers; 'rp' uses these statement
labels to implement the Ratfor control statements, and consequently will complain if it
encounters them in a source program •. As examples of statement labels,
read

10) a, b, c
10 format (3elO.0)
write (1, 20) a, b, Ci 20 format
go to 2

(1,

(3f20.5)

all show statement numbers in use. You should note that with proper use of Ratfor and the
Software Tools Subsystem support subroutines, statement labels are almost never required.
As for continuation lines, 'rp' is usually able to recognize when the current line needs
to be continued. A line ending with a comma, unbalan~ed parentheses in a condition, or a
missing statement
(such as at the end of an if) are all situations in which 'rp' correctly
anticipates a continuation line:

integer a, b, c, d,
e, f, g
i f (a
g

b
h

i f (a

&
&

c == d
i == j

f &
1) call eql

c = -2
If an explicit continuation is required, such as in a long assignment statement,
'rp'
can be made to continue a line by placing a trailing ~nderscore ("_") at the end of the line.
This underscore must be preceded by a space. You should note that the underscore is placed
on the end of line to be continued, rather than on the continuation line as in Fortran.
If
-

2 -

Ratfor User's Guide
you are unsure whether Ratfor will cnrectly anticipate a continuation line, go ahead and
place an underscore on the line to be continued -- 'rp' will ignore redundant continuation
indicators.
Identifiers may not be split between lines~ continuation is allowed only between tokens.
If you have an extremely long string constant that requires continuation, you can take
advantage of the fact that 'rp' always concatenates two adjacent string constants.
Just
close the first part of the literal with a quote, space, and underscore, and begin the second
part on the next line with a quote. 'Rp' will ignore the line break (because of the trailing
underscore) and concatenate the two literals.
The following are some examples of
i

i + j + k + 1 + m+ n +
s+t+u+v

~xplicit
~

line continuations:

p + q + r +

1 format

("for inputs of .. , i5, " and ", i5/
"the expected output should be ", i5)

"_____________=________________________________

string heading

"----------------------------------------------"
Comments.
Comments, an important part of any program, can be entered on any line; a
comment begins with a sharp sign ("''') a,1d continues until the end of the line. In addition,
blank lines and lines containing only co~ments may be freely placed in the source program.
Here are some appropriate and (correct b'Jt) inappropriate uses of Ratfor comments:
i f (i

> 48)

# do this only if i is greater than 48
j = j + 1

data array / 1,
2,
3,

integer cnt,
total - errs,
last_pass

i element 1
II element 2
i element 3

i element 4
i counter for controlling the
outer loop
#
i total number of errors
encountered
i
i flag for determining the
last pass~ Init = 0
i

Identifiers
A major difference between Ratfor and Fortran is Ratfor's acceptance of arbitrarily long
identifiers.
A Ratfor identifier may be up to 100 characters long, beginning with a letter,
and may contain letters, digits, dollar signs, and underscores. However, it may not be a
Ratfor or Fortran keyword,· such as if, else, integer, real, or logical. Underscores are
allowed in identifiers only for the sake of readability, and are always ignored.
Thus,
"these_tasks" and "the_set_asks" are equivalent Ratfor identifiers.
'Rp' guarantees that an identifier longer than six characters will be transformed into a
unique Fortran identifier.
Normally, the process of transforming Ratfor identifiers into
Fortran identifiers is transparent~ you need not be concerned with how this transformation is
accomplished. The one notable exception is the effect on external symbols (i.e.
subroutine
and function names, common block names).
When the declaration of a subprogram and its
invocation are preprocessed together, in the same run, no problems will occur.
However, if
the subprogram and its invocation are ?reprocessed separately, there is no guarantee that a
given Ratfor name will be transformed into the same Fortran name in the two different runs.
This situation can be avoided in either of three ways: (1) use the linkage statement
decribed in the next section, (2) use six-character or shorter identifiers for subprogram
names, or (3) preprocess subprograms and their invocations in the same run.
Just for pedagogical reasons, here,re a few correct and incorrect Ratfor identifiers:

3 -

Ratfor User's Guide
Correct
long name 1
10ng-name-2
prwf$$
I am a very long Ratfor name that is perfectly correct
a a You should note that 'a a', 'a a', and 'aa'
a a
are all absolutely identical in-Ratfor -aa
underscores are always ignored in identifiers,
AA
but 'AA' is very different.

-**
*
*

Incorrect

***

123 part
partl
part 2
a*b

starts with a digit
starts with an underscore
contains a blank
# contains an asterisk

The following paragraph contains a description of exactly how Ratfor identifiers are
transformed into Fortran identifiers.
You need not know how this transformation is accomplished to make full use of Ratfor; hence, you probably need not read the next paragraph.
If a Ratfor identifier is longer than six characters or contains an upper case letter,
it is made unique by the following procedure:

(1)
(2)
(3)
(4)

The identifier is padded with 'a's or truncated to five characters.
Remaining characters are mapped to lower case.
The frrst character is retained to preserve implicit typing.
The sixth character is changed to a "uniquing character" (normally a zero).
If necessary, the second, thi rd, fourth, and fifth characters are altered to make sure
there is no conflict with a previously used identifier.

'Rp' also examines six-character identifiers containing the uniquing character in
position, to ensure that no conflicts arise.

the

sixth

Integer Constants
Since it is sometimes necessary to use other than decimal integer constants in a
program, 'rp' accepts integers in bases 2 through 16.
Integers consisting of only digits
are, of course, considered decimal integers. Other bases can be indicated with the following
notation;
r< numbe r>
where is the base of the number (in decimal) and is number in the desired
base (the letters 'a' through 'f' are used to represent the digits '10' through '15' in bases
greater than 10). For example, here are some Ratfor integer constants and the decimal values
they represent:
Number

Decimal Value

Br77
l6rff
-2rll
7r13

63
255
-3
10

Some care must be exercised when using this form of constant to generate bit-masks with
the high-order bit set.
For example, to set the hi'Jh-order bit in a l6-bit word, one might
be tempted to use one of the constants
16rBOOO

Br100000

Either of these would cause incorrect results, because the value that they represent, in
decimal,
is 65536. Th"is number, when encountered by Prime Fortran, is converted to a 32-bit
constant (with the high order bit in the second word set). This is probably not the desired
result. The only solutions to this problem (which oc!urs when trying to represent a negative
twos-complement number as a positive number)
ar'!
(1)
use the correct twos-complement
representation (-3276B in this case), or (2) fall bac~ to Prime Fortran's octal constants
(e.g.
:100000).

- 4 -

Ratfor User's Guide
String Constants
Under the Software Tools Subsystem, character strings come in various flavors.
Because
various internal representations are use'] for character strings, Fortran Hollerith constants
are not sufficient to easily provide all the different formats required.
All types of Ratfor string constants consist of a string body followed by a st.ring
format indicator. The body of a string ~onstant consists of strings of characters bounded by
pairs of quotes (either single or double quotes), possibly separated by blanks..
All the
character strings in the body (not in~luding the bounding quotes) are concatenated to give
the value of the string constant.
For e~ample, here are three string constant bodies that
contain the same string:
"I am a string constant body"
"I" , am ' "a" , string' "constant"
HI am a string "'constant body'

, body'

The string format indicator is an optional letter that determines the internal format to
be used when storing the string. Currently there are five different string representations
available:
omitted

Fortran Hollerith string. When the string format indicator is omitted, a standard
Fortran Hollerith constant is generated. Characters are left-justified, packed in
words (two characters per word )n the Prime), and unused positions on the right are
filled with blanks.

Single character constant. Th'c 'c' string format indicator causes a single character constant to be generated.
rhe character is right-justified and
zero-filled on
the left in a word.
Only one character is allowed in the body of the constant.
Since it is easy to manipulate and compare characters in this format,
it is the
preferred format for all single characters in the Software Tools Subsystem.

Packed
(Hollerith) period-ter'linated string. The 'pi format indicator causes the
generation of a Fortran Hollerith constant containing the characters in the string
body followed by a period.
In ,ddition, all periods in the string body are preceded
by an escape character ("@"). The advantage of a Up" format string over a Fortran
Hollerith string is that the le'1gth of the Up" format string can be determined at
run time.

PL/I character varying string.
For compatibility with Prime's PL/I and because this
data format is required by some system calls, the "v" format indicator will generate
Fortran declarations to creat2 a PLII character varying string. The first word of
the constant contains the number of characters; subsequent words contain the characters of the string body packed two per word. "V" format string constants may only
be used in executable statement,.

EOS-terminated unpacked strinJ.
The "s" string format indicator causes 'rp' to
generated declarations necessarf to construct an array of characters containing each
character in the string body in a separate word,
right-justified and zero-filled
(each character is in the same format as is generated by the "c" format indicator).
Following the characters is a w)rd containing a value different from any character
value that marks the end of the string. This ending value is defined as the symbolic constant EOS. EOS-terminated strings are the preferred format for multicharacter strings in the SubsY3tem, and are used by most Subsystem routines dealing
with character strings. usn format string constants may only be used in executable
statements.

Here are some examples of stri1gs and the result that would be generated for Prime
Fortran. On a machine with a different ~haracter set or word length, different code might be
generated.
String Constant

Resulting ':ode

'v'c
"=doc="s

the integec constant 246
an integer array of length 6 containing 189, 228,
239,
189, -2
an integer array containing 7, "a>", "b ", "c>", "d "
the constant 9h@.main@ ••
the consta:1t 9hHollerith

"a>b c>d"v
".main."p
"Hollerith"

- 5 -

227,

Ratfor User's Guide
Logical and Relational Operators
Ratfor allows the use of graphic characters to represent logical and relational
operators instead of the Fortran ".EO." and such. While use of these graphic characters is
encouraged, it is not incorrect to use the Fortran operators. The following table shows the
equivalent syntaxes:

Ratfor

Fortran

Function

>
>=
<
<=

.GT.
.GE.
• LT.
• LE.
· EO.
.NE.

Greater than
Greater or equal
Less than
Less or equal
Equal to
Not equal to

.NOT.
.AND.
.OR.

Logical negation
Logical conjunction
Log ical disjunction

Note than the digraphs shown in the table "must appear in the Ratfor program with no
spaces.

imbedded

For example, the two following if statements are equivalent in every way:
i f (a .eq. b .or • . not.
i f (a == b

(c -= d

(c .ne. d .and. f
&

.~e.

g»

f >= g»

In addition to graphics representing Fortran operators, two additional operators are
available in any logical expression parsed by 'rp'
(i .e.
anywhere but
assignment
statements).
These operators, '&&' ("and if") and 'II' ("or if") perform the same action as
the logical operators '&' and
'I', except that they guarantee that the expression is
evaluated from left to right, and that evaluation is terminated when the truth value of the
expression is known. They may appear within the scope of the ,-, operator, but they may not
grouped within the scope of '&' and' I '.
TIlese operators find use in situations in which it may be illegal or undesirable to
evaluate the right-hand side of a logical expression based on the truth value of the lefthand side. For example, in
while (i > 0
i = i - 1

str (i) == , 'c)

it is necessary that the subscript be checked before it is used. The order of evaluation of
Fortran logical expressions is not specified, so in this example, it would be- technically
illegal to use '&' in place of '&&'.
If the value of ' i ' were less than 1, the illegal subscript reference might be made regardless of the range check of the subscript.
The Ratfo-r
short-circuited logical operators prevent this problem by insuring that "i > Oil is evaluated
first, and if it is false, evaluation of the expressi~n terminates, since its value
(false)
is known.
Assignment Operators
Ratfor provides shorthand forms for the Fortran idioms of the form
=
In Ratfor, this assignment can be simplified to the

f~rm

with the use of assignment operators.

The following aSSignment operators are available:

- 6 -

Ratfor User's Guide
Operator

Result
--

Use

*=
/=
%=
&=
1=

*=
/=

mod
and
or
xor

+ «e»

«e»
* «e»
/ «e> )
«v> , , , , "uld add more code and more procedure calls. Two define statements will serve the purpose
very well:
define
define
define
define

(STANDARD INPUT, -10)
(STANDARD-OUTPUT, -11)
(getl (In), getlin (In, STANDARD INPUT»
(putl (In), putlin (In, STANDARD=OUTPUT»

while (getl (line) -= EOF)
call putl (line)
In this case, when the string "getl (line)" is replaced, all occurrences of "In" (the formal
parameter) will be replaced by "line" (the actual parameter). This example will give exactly
the same results as the first, but with a little less typing when "getl" and "putl" are called often.
The full syntax for a define statement follows:
define «identifier> [«formal params» 1, is recorded as the value of
.
At any later time, if is encountered in the text, it is replaced
by the text of . If the original define contained a formal parameter list, the
list of actual parameters following is ~ollected, and the actual parameters are
substituted for the corresponding formal parameters i . before the replacement
is made.
There is a file of "standard" definitions used by all Subsystem programs called
"=incl=/swt def.r.i". The define statements in this Eile are automatically inserted before
each source file
(unless 'rp'
is told otherwise by the "-fn command line option). For

- 8 -

Ratfor User's Guide
information on the exact contents of this file, see Appendix D.
There are also a few other facts

th~t

are helpful when using define:

The must be identifiers.
may be any string of characters not containing unbalanced
parentheses, unpaired quotes, or conmas not surrounded by quotes or parentheses.
Formal parameter replacement in occurs even inside of quoted strings.
example,

.For

define (assert (cond), {
i f (-(cond»
call error ("assertion cond not valid"p)}
assert (i < j)
would generate
i f (-(i

y superseded definitions is reclaimed.
Here are a few more examples of how defines can be used:

- 9 -

all

Ratfor User's Guide
Before Defines Have Been Processed:
define (NO, 0)
define (YES, 1)
define (STDIN, -11)
define (EOF, -2)
define (RESET (flag), flag = NO)
define (CHECK FOR ERROR (flag, msg) ,
if (flag =i" YES)
call error (msg)
)

define (FATAL ERROR MESSAGE,
"Fatal error -- run terminated"p)
define (PROCESS LINE,
count = count + 1
call check syntax (buf, count, error_flail
)
-

while (getlin (buf, STDIN) -= EOF) {
RESET (error flag)
PROCESS LINECHECK FOR ERROR (error_flag, FATAL_ERROR_MESSAGE)
}

After Defines Have Been Processed:
while (getlin (buf, -11) -= -2) {
error flag = 0
count-= count + 1
call check syntax (buf, count, error_flaJ)
if (error flag == 1)
call error ("Fatal error -- run terminated"p)

Undefine
1
I"

1
1

The Ratfor undefine statement allows termination of the range of a define statement.
The identifier named in the undefine statement is rem"wed from the define" table if i t is
present; otherwise, no action is taken. Storage used by the definition is reclaimed. For
example, the statements
define (xxx, a
xxx
undefine (xxx)
xxx

would produce the following code:

a = 1
xxx

Include
The Ratfor include statement allows you to inclurie arbitrary files in a Ratfor
(much like the COBOL copy verb).
The syntax of an include statement is as follows:

program

include ""
If the file name is six or fewer characters in lengtil and contains only alphanumeric characters, the quotes may be omitted.
For the sake of uniformity, we suggest that the quotes
always be used.
When
'rp' encounters an include statement, it begins taking input from the file
specified by . When the end of the incl ud,~d fi Ie is encountered,
'rp' resumes
reading the preempted file. Files named in include s,-atements may themselves contain include
statements; this nesting may continue to an ar")itrary depth
(which, by the way, is
arbitrarily limited to five).
For an example of include at work, assume the existence of the following files:

- 10 -

Ratfor User's Gu ide
fl:
include "f2"
i = 1
incl ude "f3"
f2:
include "f4"
m = 1
f3:
j

f4:
k = 1

If "flO were the original file, the foll)wing text is what would actually be processed:
k

1
1
1

i
j

Ratfor Declarations
There are several declarations available in Ratfor in addition to those usually supported in Fortran.
They provide a way of conveniently declaring data structures not
available in Fortran, assist in supporti1g separate compilation, allow declaration of local
variables within compound statements, and allow the declaration of internal procedures.
Declarations in Ratfor may be intermixed with executable statements.
String
The string statement is provided as a shorthand way of creating and naming
EOSterminated strings.
The structure an] use of an EOS-terminated string is described in the
section on Subsystem Conventions. Here it is sufficient to say that such a string is an
integer array containing one character p?r element, right justified and zero filled, and ending with a special value
(EOS) designating the "end of string."
Since Fortran has no
construct for specifying such a data structure, it must either be declared manually, as a
Ratfor string constant, or by the Ratfor string statement.
The string statement is a declaration that creates a named string in an integer array
using a Fortran data statement. The synt.ax of the string statement is as follows:
string
where is the Ratfor identifier to be used in naming the string and
specifies the string's contents. As yOJ might expect, either single or double quotes may be
used to delimit .
In either case, only the characters between the quotes
become part of the string; the quotes themselves are not included.

String statements are quite
names or key words.
For instance,

oft~n

used for setting up constant strings such as file

string ·file name "//mydir/myfile"
string change command "change"
string delete-command "delete"
define such character arrays.
Stringtable
The stringtable statement creates a rather specialized data structure
a marginally
indexed array of variable length strings. This data structure provides the same ease of
access as an array, but it can contain e~tries of varying sizes. A stringtable declaration
defines two data items: a marginal index and a table body.
The marginal index is an integer
array containing indices into· the table body. The ~irst element of the marginal index is the
number of entries following in the marg l1al index.
Subsequent elements of the marg inal index
are pointers to the beginning of items in the table body.
Since the beginning of the table
body is always the beginning of an item, the second entry of the marginal index is always 1.

- 11 -

Ra,tfot Use r' s Gu i de
The syntax of a stringtable declaration is as fellows:
string table , ,
[ /-] { / }
and are identifiers that will be declared as the marginal index
and table body, respectively. is a comma-separated list of single-character constants
(with a "c" string format indicator), integers, or ECS-terminated character strings (with no
string format indic.ator -- a little inconsistency here).
The values contained in an
are stored contiguously in with no separator values (save for an EOS at the end
of each EOS-terminated string). An entry is made in the marginal index containing the position of the first word of each .
For example, assume that you have a program in which you wish to obtain one of three
integer values based on an input string.
You want to allow an arbitrary number of synonyms
in the input (like "add", "insert", etc.).
string table cmdpos, cmdtext,
"add"
/ ADD,
/ ADD,
" insert"
/ CHANGE,
"change"
"update"
/ CHANGE,
"delete"
/ DELETE,
/ DELETE,
"remove"
This declaration creates a structure something like the following:
cmdtex t

cmdpos
1:

2:
3:

·6

1:
6:

14:

22:

CHANGE,

29:

DELETE,

36:

DELETE,

ADD,
ADD,
. CHANGE ,

'a'c,
' i' c,
'r'c,
'c'c,
'g' c,
I u'e,
't'c,
'd'c,
't'c,
' r' c,
'v' c,

'd'c,
'n' c,
't'c,
'h 'c,

'e' c,
'p' c,
'e'c,
'e 'c,
'e'c,
'e'c,
'etc,

'd'c,
's 'c,
EOS
'a 'c,
EeS
'd'c,
EOS
' l' c ,
EOS
'ro'e,
EOS

1;: OS

'e'c,
'n'c,
'a'c,
'e'c,
· a 'e,

There are several routines in the Subsystem library that can be used to search for
strings in one of these structures. You can find details on the use of these procedures in
the reference manual/'help' entries for 'strlsr' and 'strbsr'.

Linkage
The sole purpose of the linkage declaration is to circumvent problems with transforming
Ratfor identifiers to Fortran identifiers when compiling program modules separately. To
relax the restriction that externally visible names (subroutine, function, and common block
names) must contain no more than six characters, each separately compiled module must begin
with an identical linkage declaration containing the names of all external symbols
subroutine nameS, function names, and common block names (the identIfiers inside the slashes
-- not the variable names). Except for text substitution statements, the linkage declaration
must be the first statement in each module.
The order of names in the statement is
SIgnificant
as a general rule, you should include the same file containing the linkage
declaration in each module.
Linkage looks very much like a Fortran type declaration:
linkage identifier 1, identifier2, identifier3
Each of the identifiers is an external name (i.e.
subroutine, function, or common block
name).
If this statement appears in each source module, with the identifiers in exactly the
same order, it is guaranteed that in all cases, each of these-identifIers will De transformed
into ~ame unique Fortran identifier.
For Subsystem-specific information on the mechanics
of separate compilation, you can see the section in the applications notes devoted to this
topic.

12 -

Ratfor User's Guide
Local
With the local declaration, you can indicate that certain variables are "local" to a
particular compound statement (or block) just as in Algol.
Local declarations are most often
used inside internal procedures (which are described later), but they can appear in any compound statement.
The syntax for declaring local variables was devised primarily with ease-of-implemention
in mind.
When 'rp'
becomes more aware of Fortran syntax, declarations inside of compound
statements will be implicitly local to the block. Now, however, the type declarations for
local variables must be preceded by a local declaration containing the names of all variables
that are to be local to the block:
locali, j, a
integer i, j
real a
The local statement must precede the first appearance of a variable inside the block.
Scope rules similar to those of most block-structured languages apply to nested compound
statements: A local variable is visible to all blocks nested within the block in which it is
declared.
Declaration of a local variable obscures a variable by the same name declared in
an outer block.
There are several cautions you must observe when using local variables.
'Rp'
is
currently not well-versed in the semantics of Fortran declarations and therefore cannot
diagnose the incorrect use of local declarations. Misuse can then result in semantic errors
in the Fortran output that are often not caught by the Fortran compiler.
If the declaration
of a variable within a block appears before the variable is named in a local declaration,
'rp'
will not detect the error, and an "undeclared variable" error will be generated in the
Fortran. External names (i.e. function, subroutine, and common block names) must never be
named in a local declaration, unless you want to declare a local variable of the same name.
Finally, the formal parameters of internal procedures should never appear in a local declaration in the body of the procedure, again, unless you want to declare a local variable of the
same name.
Here is an example showing the scopes of variables appearing in a local declaration:
### level 0
subroutine test

integer i ,

j, k

### level 1
local i, mi integer i , m
# accessible: level 0 j, k; level 1 i , m
{ i i i level 2
local m, ki real m, k
i accessible: level 0 ji level I ii level 2 m, k

}
end

- 13 -

Ratfor User's Guide
Ratfor Control Statements
As was said by Kernighan and Plauger in Software Tools, except for the con.trol struc-.
tures, "Ratfor is Fortran." The additional control structures just serve to give Fortran the
capabilities that already exist in Algol, Pascal, and PL/I.
Compound Statements

Ratfor allows the specification of a compound statement by surrounding a group of Ratfor
statements with braces ("{}"), just like begin - end in Algol or Pascal, or do - end in PL/I.
A compound statement may appear anywhere a single statement may appear, and is considered to
be equivalent to a single statement when used within the scope of a Ratfor control statement.
There is normally no need for a compound statement to appear by itself -- compound
statements usually appear in the context of a control structure -- but for completeness, here
is an example of a compound statement.

# end of line -- set to beginning of next line
line = line + I
col = I
end of line
YES
}

If - Else
The Ratfor if statement is much more flexible than its Fortran counterpart. In addition
to allowing a compound statement as an alternative, the Ratfor if includes an optional else
statement to allow the specificatin of an alternative statement. Here is the complete syntax
of the Ratfor if statement:
if «condition»
[else ]
is an ordinary Fortran logical expression.
If is true,
will be executed.
If is false and the else alternative is specified,
will be executed. Otherwise, if is false and the else alternative
has not been specified, no action occurs.
Both and may be compound statements or may be further if
statements.
In the case of nested if statements where one or more else alternatives are not
specified, each else is paired with the most recently occuring if that has not already been
paired with an else.
Although deep nesting of if statements hinders understanding, one situation often occurs
when it is necessary to select one and only one of a set of alternatives based on several
conditions. This can be nicely represented with a chain of if - else if - else if • • • else
statements. For example,
if (color == RED)
call process red
else i f (color ~= BLUE I color
call process blue green
else i f (color ~= YELLOW)
call process_yellow
else
call color error

GREEN)

could be used to select a routine for processing based on color.
While

The Ratfor while statement allows the repetition of a statement (or compound statement)
as long as a specified condition is met. The Ratfor while loop is a "test at the top" loop
exactly like the Pascal while and the PL/I do while. The while statement has the following
syntax:
while «condition»

If is false, control passes beyond the loop to the next statement in the program;
if is true, is executed and is retested. As should be
- 14 -

Ratfor User's Guide
expected, if is false when the
executed zero times.
The
strings:

while

statement

while (str (i)
i = i + 1

very

while

first

entered,

will

handy for controlling such things as skipping blanks in

BLANK)

And of course, may also be a compound statement:
while (getlin (buf, STDIN)
call process (buf)
call output (buf)

EOF)

}

Repeat
The Ratfor repeat loop allows repetitive execution of a statement until a specified condition is met. But, unlike the while loop, the test is made at the bottom of the loop, so
that the controlled statement will be executed at least once. The repeat loop has syntax as
follows:
repeat

[until «condition» 1
When the repeat statement is encountered, is executed.
If
is found
to be false, is reexecuted and the is retested.
Otherwise control
passes to the statement following the repeat loop.
If the until portion of the loop is omitted, the loop is considered an "infinite repeat" and must be terminated within
(usually with a break or return statement). Pascal users should note that the scope of the
Ratfor repeat is only a single (which of course may be compound).
Repeat loops, as opposed to while loops, are used when the controlled statement must
evaluated at least once.
For example,

repeat
call get next token (token)
until (token ~= BLANK_TOKEN)
The "infinite repeat" is often useful when a loop must be terminated "in the middle:"
repeat {
call get next input (inp)
call check syntax (inp, error flag)
if (error rlag == NO)
returncall syntax error (inp)
It go back and get another
}

Do
Ratfor provides access to the Fortran do statement.
The Ratfor do statement is
identical to the Fortran do except that it does not use a statement label to delimit its
scope. The Ratfor do statement has the following syntax:
do

is the normal Fortran notation for the limits of a do, such as "i = 1, 10" or "j =
5, 20, 2". The same restrictions apply to as apply to the limits in the Fortran do.
is any Ratfor statement (which may be compound).
The Ratfor do statement is just like the standard Fortran
will be executed at least once, regardless of the limits.
do control variable is not defined on exit from the loop.

one-trip do loop
Also, the value of the

The do loop can be used for array initialization and other such things that can never
require "zero trips", since it produces slightly more efficient object code than the for
statement (which we will get to next).

- 15 -

Ratfor User's Guide
do i = 1, 10
array (i)

One slight irregularity in the Ratfor syntax occurs when appears on the same
line as the do.
Since 'rp' knows very little about Fortran, it assumes that the
continue until a statement delimiter. This means that the must be followed by a
semicolon if is to begin on the same line.
This often occurs when a compound
statement is to be used:
do i = 1, 10; {
array 1 (i)
0
array-2 (i) = 0
}

For
The Ratfor for statement is an all-purpose looping construct that takes the best
features of both the while and do statements, while allowing more flexibility.
The syntax of
the for statement is as follows:
for

«initialize>; ;

When the for is executed, the statement represented by is executed. Then, if
is true, is executed, followed by the statement represented by
.
Then,

is retested, etc.
Any or all of ,
, or may be omitted; the semicolons, however, must remain.
If
or is omitted, no action is performed in their place.
If
is omitted, an "infinite loop" is assumed.
(Both or
may be compound statements).
As you can see, the for loop with and omitted is identical
to the while loop. With the addition of and , a zero-trip do loop
can be constructed. For instance,
for

(i = 1; i <= 10; i += 1) {
array I (i)
o
array-2 (i) = o

}

is identical to the last do example, but given a certain combination of limits, the for
would execute zero times while the do loop would execute it once.

loop

The for loop can do many things not possible with a do loop, since the for loop is not
constrained to the ascending incrementation of an index. As an example, assume a list structure in which "list" contains the index of the first item in a list, and the first position
in each list item contains the index of the next.
The for statement could be used to
serially examine the list:
for

(ptr = list; ptr -= NULL; ptr = array (ptr» {
examine the item beginning at array (ptr + 1)

Break
The break statement allows the early termination of a loop.

The statement

break []
will cause the immediate termination of loops, where ,
if specified,
is an
integer in the range 1 to the depth of loop nesting at the point the break statement appears.
Where is omitted, only the innermost loop surrounding the break is terminated.
In the following example, the break statement will cause the termination of the inner
for loop if a blank is encountered in 'str':

- 16 -

Ratfor User's Guide
while (getlin (str, STDIN) -= EOF)
for (i = 1; str (i) -= EOS; i += 1)
i f (str (i) == BLANK)
break

str (i) = EOS
output just the first word
call putlin (str, STDOUT)
call putch (NEWLINE, STDOUT)
}

Replacing the break statement with "break I" would have exactly the same effect.
However,
replacing it with "break 2" would cause termination of both the inner for and outer while
loops.
Unless this fragment is nested inside other loops, a value greater than 2 would be an
error.
Next
The next statement is very similar to the break statement, except that
the form

statement

next []
causes termination of - 1 nested loops (zero when is omitted).
Execution
then resumes with the next iteration of the innermost active loop.
, if specified, is
again an integer in the-range 1 to the depth of loop nesting that specifies which loop
(from
inside out) is to begin its next iteration.
In this example,
the next statement will cause the processing to be skipped when an
array element with the value "UNUSED" is encountered.
fo r

(i = 1; i < = 10; i += 1)
for (j = 1; j <= 10; j += 1) {
i f (array (i, j) == UNUSED)
next

* process

array (i, j)

When an array element with the value "UNUSED" is encountered, execution of the next statement
causes the portion of the innermost for statement, "j += 1", to be executed
before the next iteration of the inner loop begins. You should note that when used with a
for statement, next always skips to the part of the appropriate for loop.
If the statement "next 2" had been used in place of "next", the inner for
loop would
have been terminated,
and the "i += 1" of the outer for loop would have been executed in
preparation for its next iteration.
Return
The Ratfor return statement normally behaves exactly like the Fortran return statement
in all but one case.
In this case, Ratfor allows a parenthesized expression to follow the
keyword return inside a function subprogram.
The value of this expression is then assigned
to the function name as the value of the function before the return is executed.
This is
just another shorthand and does not provide any additional functionality.
Normally in a Fortran function subprogram,
you place an assignment
assigns a value to the function name before the return statement, like this:

statement

integer function calc (x, y, z)
calc = x + y - z
return
If you like, Ra tfor allows you to express the same actions wi th one line less code:
integer function calc (x, y, z)
return (x + y - z)
This segment performs exactly the same function as the preceding segment.

17 -

that

Ratfor Use r' s Guide
Select
The Ratfor select statement allows the selection of a statement from several alternatives, based either on the value of an integer variable or on the outcome of several
logical conditions. A select statement of the form
select
when «expression list 1»

when «expression list 2»

when «expression list n»

[ifany
is a comma-separated list of logical expressions) performs almost
the same function as a chain of if - else if
else statements.
Each is evaluated in turn, and when the first true is encountered, the corresponding
statement is executed.
If any when alternative is select.ed, the statement in the ifany part
is executed.
If none of the when alternatives are selected, the statement in the else part
is executed.
Although its function is very similar to an if - else chain, a select statement has two
distinct advantages.
First, it allows the "ifany" alternative -- a way to implement a rather
frequently encountered control structure without repeated code or procedure calls. Second,
it places all the logical expressions in the same basic optimization block, so that even a
dumb Fortran compiler can optimize register loads and stores.
For example, assume that we want to check to see if the variable 'color' contains a
valid color, namely 'RED', 'YELLOW', 'BLUE', or 'GREEN'. If it does, we want to executed.one
of the three subroutines 'process red', 'process yellow', or 'process blue green' and set the
flag 'color valid' to YES.
Otherwise, we want to set the
'color valid' to NO.
A select
statement performs this trick nicely, with no repeated code:
select
when (color == RED)
call process red
when (color == YELLOW)
call process yellow
when (color == BLUE, color
call process_blue_green
ifany
YES
color valid
else
NO
color valid

GREEN)

The second variant of the select statement allows the selection of a statement based on
the value of an integer (or character) expression.
It has almost exactly the same syntax as
the logical variant:
select «integer expression»
when «expression list 1»

when «expression list 2»

when «expression list n»

[ifany
]
Using this variant, a statement is selected when one of its corresponding integer expressions
has the same value as the following the 'select'. The ifany and else
clause behave as they do in the logical variant. The most visible difference, though,
is
that the order of evaluation of the integer expressions is not specified.
If two values in
two expression lists are identical, it is d.ifficul t to say which of the statements will be
executed; it can only be said that one and only one will be executed.

- 1.8 -

Ratfor User's Guide
The
integer variant offers one further advantage.
If elements in the expression lists
are integer or single-character constants,
'rp'
will generate Fortran computed goto
statements,
rather than Fortran if statements, where possible.
This code is usually
considerably faster and more compact than the code generated by if statements.
The example given for the logical variant of select would really
done with the integer variant:

much

easily

select (color)
when (RED)
call process red
when (YELLOW)
call process yellow
when (BLUE, GREEN)
call process_blue_green
ifany
color valid
YES
else
color valid
NO
As a final example of select, the following program fragment selects an insert, update,
delete, or print routine based on the input codes "in, "un, "dO or Up":
whi Ie (getl in (buf, STDIN) -= EOF)
select (buf (I»
when ('i'c, 'I'c)
~ insert record
call insert record
when ('u'c, 'UTc) { # update record
call delete record
call insert-record

}

when ('d'c, 'D'c)
# delete record
call delete record
when ('p'c, 'pTC )
# print record
ifany
call print_record
else
call command error

# always print after command
~

i lleg al input

This example shows the use of both a compound statement within an alternative
(the "update"
action deletes the target record and
then inserts a new version), and a null statement
consisting of a single semicolon.
Procedure
Procedures are a convenient and useful structuring mechanism for programs,
but in
Fortran there often reasons
for restricting the unbridled use of procedures.
Among these
reasons are (1) the run-time expense of procedure calls, and argument and common block
addressing;
(2)
external name space congestion; and (3) difficulty in detecting errors in
parameter and common-block correspondence.
Ratfor attempts to address these problems by
allowing declaration of procedures within Fortran subprograms that are inexpensive to call
(an assignment and two gatos), are not externally visible,
and allow access to global
variables.
In addition,
when correctly declared, Ratfor internal procedures can call each
other recursively without requiring recursive procedures in the host Fortran.
Currently, Ratfor internal procedures do not provide the same level of functionality as
Fortran subroutines and functions:
internal procedure parameters must be scalars and are
passed by value, internal procedures cannot be used as functions (they cannot return values),
and no automatic storage is available with recursive integer procedures. But even with these
restrictions, internal procedures can significantly improve the readability and modularity of
Ra tfor code.
Internal procedures are declared with the Ratfor procedure statement.
Internal
procedures may be declared anywhere in a program, but a declaration must appear before any of
its calls.
Here is an example of a non-recursive procedure declaration:

- 19 -

Ratfor User's Guide
# putchar --- put a character in the output string

procedure putchar (ch) {
character ch
str (i)
i += 1

}

This procedure
procedure.

has

one parameter, "ch", which must appear in a type declaration inside the

Internal procedures always exit by falling through the end of the compound statement. A
return statement in an internal procedure will return from the Fortran subprogram in which
the internal procedure is declared.
After the above declaration, "putchar" can be subsequently called in one of two ways:
putcha'r (' =' c)
-orcall putchar ('='c)
The second form is preferable, so that a procedure can be converted to a subroutine, and
vice-versa. The number of parameters in the call must always match the number of parameters
in the declaration.
If parameter list is omitted in the declaration, then it also must be
omitted in its calls.
If "putchar" were recursive, the declaration would be
procedure putchar (ch) recursive 128
The value "128" is an integer constant that is the
Kputchar" outstanding at anyone time.

maximum

number

recursive

calls

Since internal procedures may be mutually recursive, and since they must be declared
textually before they are used, procedures may be declared "forward" by separating the
procedure declaration from its body.
Here is "putchar" declared using a "forward"
declaration:
procedure putchar (ch) forward

# putchar --- put a character in the output string
procedure putchar

character ch
str (i)
i += 1

}

·As you can see, the parameters must appear in the "forward" declaration; they may appear in
the body declaration, but are ignored.
For maximum efficiency, all internal procedures
should be presented in a "forward" declaration. The procedure bodies ~ould then be declared
after the final return or stop statement in the body of the Fortran subprogram (then the
program never has to jump around the procedure body).
In general, a procedure declaration contains five parts:
the word "procedure", the
procedure name, an optional list of formal parameters, an optional "recursive (integer>"
part, and either a compound statement or the word "forward". An internal procedure call
consists of three parts: optionally the word "call", the procedure name, and an optional
parameter Ii st.

20 -

Ratfor User's Guide
Ratfor Language Reference

This section contains a summary of the Ratfor syntax and source program format.
In
addition to serving as a reference for Ratfor, it can also be used by someone who is familiar
with Fortran and wants to quickly gain a reading knowledge of Ratfor.

Differences Between Ratfor and Fortran
Source Program Format
'Rp' is sensitive to letter case.
significant in identifiers.

Keywords must appear in

lower

ca'se.

Case

'Rp'
is blank sensitive in that words (sequences of letters, digits, dollar signs,
and underscores) must be separated by special characters or blanks.
'Rp' is not sensitive to card columns.
line.
'Rp' allows
semicolons.

multiple

statements

Statements may begin at any position

per

line

separating

the

statements with

A Ratfor statement may be labeled by placing the numeric label in front of the
statement.
The label must be separated from the statement by at least one space.
'Rp' will expect a continuation line if it encounters a line ending with a trailing
comma, a condition with unbalanced parentheses, a missing statement following a
control statement, or a line ending with a trailing underscore.
Any line may contain a comment.
Comments
continue until the end of the line.

begin

with

sharp

sign

(lilt")

and

Identifiers
Ratfor identifiers consist of letters, digits, underscores, dollar signs, and may be up
to 100 characters long.
An identifier must begin with a letter.
Underscores may be included
for readability, but are completely ignored. An identifier may not be the same as a Fortran
or Ratfor keyword.
'Rp' transforms all long Ratfor identifiers into unique Fortran
identifiers.
Integer Constants
'Rp' allows integer constants of the form "r" where is an integer
between 2 and, 16. The letters "a" - IIfll are used for digits in bases greater than 10.
String Constants

I
I
I

String constants in Ratfor consist of a string body and a string format indicator. The
string body is a group of strings, bounded by quotes, and possibily separated by blanks. The
string format indicator designates the data representation to be used foe the characters in
the string body.
It has one of the following values:
omitted

Fortran Hollerith string.
A standard Fortran Hollerith constant is generated.
Characters are left-justified, packed in words
(two characters per word on the
Prime)', and unused positions on the right are filled with blanks.

Single character constant. A single character constant is generated.
The character
is right-justified and zero-filled on the left in a word. Only one character is
allowed in the body of the constant. This is the preferred format for all single
characters in the Software Tbols Subsystem.

Packed
(Hollerith)
period-terminated string.
The' p' format indicator causes the
generation of a Fortran Hollerith constant. All periods in the string body are
preceded by an escape character ("@").

PLII

character varying string.

Fortran declarations are generated to create a PL/I
- 21 -

Ratfor User's Guide
character varying string.
executable statements.

"V"

format

string

constants

may

only

used

EOS-terminated unpacked string.
Fortran declarations are generated to construct an
array in which each element contains one character of the string body,
rightjustified and zero-filled (each characte~ is in the same format as is generated by
the "c" format indicator).
Following the characters is a word containing the value
EOS.
EOS-terminated strings are the preferred format for multi-character strings in •
the Subsystem.
"S" format string constants may only be used in executable
statements.

Logical and Relational Operators
Ratfor allows the use of graphic characters to represent logical and relational
operators
instead of the Fortran ".EQ." and such.
These characters will be replaced by
their Fortran equivalents during preprocessing. The following
table shows the equivalent
syntaxes:

. Ratfor

Fortran

Function

.GT.
.GE.
. LT.
• LE.
.NE.

Greater than
Greater or equal
Less than
.Less or equal
Equal to
Not equal to

&
I

.NOT.
.AND.
.OR.

Logical negation
Logical conjunction
Logical disjunction

&&
II

(none)
(none)

Short-circuited conjunction
Short-ciructied disjunction

>
>=

<
<=

.EQ.

Note that the digraphs shown in the table must appear in the Ratfor program with no imbedded
spaces.
The short-circuited operators may appear only in the part of Ratfor
control statements.
Assignment Operators
Assignment operators provide a shorthand for the common Fortran idiom " =
". Assignment operators may appear anywhere a Fortran assignment statement may appear.
The following assignment operators are available in Ratfor:
Use

Oeerator

+=
*=
/=
%=
&=
1=

*=
/=
%=
&=
1=

Result
= + «e»
= - «e»
= . * «e»

/ «e»

mod «v> ,
and «v> ,
or «v>,
xor «v>, [«formal params»], is recorded as the replacement for
.
If

is encountered later
in the
program,
it will be replaced by .
If was present in the
definition of , and the subsequent occurence of
is followed by a
parenthesized,
comma-separated list of strings, occurrences of the formal parameters in
will be replaced by the corresponding strings in the actual parameter
list.
must be an alphabetic Ratfor identifier, while may
contain any characters except unmatched quotes or parentheses.
must be a
comma-separated list of identifiers; corresponding actual parameters may contain any characters except unmatched quotes,
unbalanced parentheses, or
unnested
commas.
During
replacement,

is also examined for occurences of defined identifiers.
Formal parameter replacement occurs on identifiers in ,
even if the
identifiers are surrounded by quotes or parentheses. Redefinition of an causes
the new to replace the old.
undefine «identifier»
The undefine statement removes the definition of from the list of defined
identifiers.
Subsequent occurrences of
in the program will not be replaced
unless appears in a subsequent define statement.
include ''
An include statement instructs 'rp' to begin taking input from
the file
specified by
.
When the end of the file is reached, 'rp' resumes taking input from the file
containing the include statement. The path name may be surrounded by either single or double
quotes.
The file specified by may contain further include statements,
up to a
maximum depth of 5.

Ratfor Declarations
linkage { , }
The linkage declaration is used to guarantee that long external names are transformed
into the same unique Fortran name.
Names are transformed as they are presented in the linkage declaration.
The same linkage statement should appear as the first statement of each
separately compiled source module, and should contain the names of all subroutines,
functions, and common blocks in the program.

23 -

Ratfor User's Guide
local { , }
The local declaration allows the declaration of variables with names local to the scope
of a compound statement (block).
The local declaration should appear
inside a compound
statement and must precede all occurences of the identifiers to be declared local to the
block.
All identifiers appearing in a local declaration must subsequently appear in a type
declaration in the same compound statement.
string
The string statement generates declarations to produce an EOS-terminated string in the
integer array .
must be surrounded by either single or double quotes.
stringtable , ,

[ /

] { / and are variables to be declared as the index and body arrays
respectively. is a one-dimensional array in which the values generated by the s
are stored consecutively.
The first element of contains the number of remaining
elements in ; subsequent elements each contain the index in of the first position of the corresponding .
s are comma-separated lists of integers, single-character constants, and strings (with
no string format indicators).
Integers and EOS-terminated strings are generated and stored
consecutively in .
The first position of each in is stored in the
corresponding entry of .

Ratfor Control Statements
break []

The break statement allows the user to terminate the execution of a
for,
while, or
repeat loop and resume control at the first statement following the loop.
The
specifies the number of loops to terminate; if absent, 1 is assumed (only the innermost loop
is terminated).
If the
integer
is N,
then the N innermost loops currently active are
terminated.
do ;
The do statement provides a means of accessing the local Fortran do-statement.

includes whatever parameters are necessary to satisfy Fortran, minus the statement number of
the last statement to be performed, which is generated by Ratfor. The semicolon must not be
used if the statement to be iterated does not appear on the same line as the do.
for' (' ; ; ')'
The for statement is a very general looping construct. is a
statement to be
executed before loop entry; it is frequently used to initialize a counter. is a
condition to be satisfied for every iteration; the condition is tested at the top of the
loop.
becoming false
is the most often used method of terminating the loop.
is a statement to be executed at the bottom of the loop, just before a jump is made
to the top to test the .
is usually used to increment or decrement a
counter.
may be any legal Ratfor statement.
if '(' ')' [else ]
If is a generalization of the Fortran logical-if statement.
If the condition is true,
the first
is executed.
If the optional else clause is missing, control is then
passed to the statement following the if; otherwise, the following
the else is
executed before passing control.
next []
The next statement complements the break statement.
It is used to force the next iteration of a for, repeat or while loop to occur.
The parameter specifies the number
of levels of nested loops to jump out; if omitted, the innermost loop is continued; otherwise, for = 2, the next-to-innermost loop is continued, etc.
-

24 -

Ratfor User's Guide
procedure [ '(' {, } ')
[recursive ]
( forward I )

[call] [ '(' {, } ')' ]
The procedure declaration allows the declaration of internal Ratfor procedures.
is the name of the internal procedure. Formal parameters
(scalar, pass-by-value)
are declared following the . Formal parameters must appear in a type declaration in
the body of the procedure.
If the procedure is to be called recursively,
the recursive
clause must be included; is the maximum number of recursive calls in
process at any given time. Following the heading, either a compound statement or the word
forward must appear.
If the forward option is used, a procedure declaration containing
must follow at some point in the program unit.
Formal parameters
specified on the second declaration may be present, but are ignored.
A
tly as
number
actual

must be defined before it is referenced by a call. The call can appear exaca Fortran call, or the word call can be omitted. Actual parameters must correspond in
to formal parameters. If the formal parameters list is omitted in the declaration, no
parameter list may be present.

repeat [until

')']

The repeat statement is used to generate a loop with the iteration test at the bottom.
The is performed, then the checked; if false,
the is
repeated.
If true, control passes-to the statement following the until.
If the until is
omitted, the loop is repeated indefinitely, and must be terminated with a stop, break, or
goto.
return ['(I ')']
The return statement behaves exactly like its Fortran counterpart, except that if the
optional parenthesized expression is included inside a function subprogram, the value of
will be assigned to the function name as the function value before the return is
executed.
select
{when' (' {, } ')' }
[ifany ] [else ]
select I ( ' ') I
{when' (' {, } ')
[ifany ] [else ]

Select is a generalization of the if statement.
In its first alternative, the when
s are evaluated in order; the associated with the first one found to
be true is executed.
If any is found true, the assocated with ifany
is executed; if none are found true, the assocated with else is executed.
Similarly, in the second alternative, the associated with select is
evaluated. The result is then compared to the s associated with the when parts
in an unspecified order.
When an equal comparison is made, the following the
corresponding when is executed.
If an equal comparison is made, the following
ifany is executed;
if no equal comparison is made,
the following else is
executed.
while 1(' ')'
The while statement is the basic test-at-the-top loop. The is evaluated; if
true, the is executed and the loop is repeated, otherwise control passes to the
statement following the loop.

- 25 -

Ratfor Use r' s Guide
Ratfor Programming Under the Subsystem

This chapter describes the use of Ratfor in the programming environment provided by the
Software Tools Subsystem.
In addition to demonstrating use of the Ratfor preprocessor,
Fortran compiler, and linking loader, the programming conventions necessary for the use of
the Subsystem support subprograms are described.
In this chapter, a number of programming conventions are presented. Since very few of
the. conventions can be enforced by the Subsystem, adherence to these conventions must be left
to up to the programmer. Many conventions, such as those dealing with indentation and comment placement, are shown because they assist in producing readable, maintainable programs.
Violation of these conventions, while not critical, may result in unmaintainable programs and
extended debugging times.
Other conventions, such as those dealing with character string
representations and input/output, are crucial to the proper operation of the Subsystem and
its support subprograms.
Violation of these conventions can and will cause undesirable
results.
------- --- ---- -----

Requirements for Ratfor Programs
The Software Tools Subsystem is not an operating system.
Rather, it is a collection of
user programs. To run successfully under the Subsystem, a program must cooperate
it. Several things are required of Subsystem programs:

coo~erating

wit

The program must terminate with a stop statement, or a call to the routine "error". The
program must not ncall exit" or invoke any of the Primos error reporting subroutines
with the the "immediate return" key. A program's failure to terminate properly will
also cause the Subsystem command interpreter to be terminated, leaving its user face-toface with Primos.
The program should not have initialized common blocks (i.e. block data).
the common areas with executable statements.
(To
I ink a program that
initialized common, see appendix b.)

Ini tiali ze
must have

Local variables in a subprogram are placed on the stack unless they appear in a data or
save declaration.
The value of variables not appearing in one of these declarations is
not defined on entry to a subprogram.
Several.conventions apply to the file containing the Ratfor source statements:
The file name should end with the suffix n.rn.
Any number of program units (main program, functions, and subroutines) may be included
in the file, but the main program must be first.
All variables and functions must be declared in type statements (the Primos Fortran compiler enforces this restriction, except in the case of function names).
Each program unit must end with an end statement.
Since defines apply globally to all subsequent program units, a main program and all of
its associated subprograms can be contained in the same file.
Only one copy of
definitions need be included at the beginning of the source file.

Running Ratfor Programs Under the Subsystem
Three steps are required to obtain an executable program from Ratfor source statements.
The first step, preprocessing, produces ANSI Fortran statements from the Ratfor source
statements. The second step, compilation, results in a relocatable binary module, which
lacks all of the Primos, Fortran and Subsystem subroutines. The last step, linking, produces
an executable object program by linking the relocatable binary module with the Primos,
Fortran and Subsystem support routines necessary for
its execution.
The object program
produced during linking may then be executed.

26 -

Ratfor User's Guide
Preprocessing
In the preprocessing step, the Ratfor preprocessor, 'rp,' is used to tranlate Ratfor
source statements into semantically equivalent ANSI Fortran statements acceptable to the
Primos Fortran compiler. The Ratfor preprocessor is invoked with a command line of the following syntax:
rp [-0 1

*
*

• • •

If you do not want a conventionally named output file, you may specify the option "-0
", where is the name you want given to the Fortran output.
If you
do not include a "-0 " option, 'rp' will name the output file by appending ".f"
to the name of the first .
If the name of the first ends in ".r",
the ".r" will be replaced by the ".f".
Finally comes a list of the files containing Ratfor source statements to be preprocessed.
'Rp' reads the files in the order specified on the command line and treats the contents
as if they were together in one big file.
This means that defines in each input file apply
to all subsequent input files.
In spite of all this complicated stuff, the 'rp' preprocessor is quite easy to use if
you follow the recommended naming conventions for files.
For instance, if you have a Ratfor
program in a file called "prog.r", you can have it preprocessed by just typing
rp prog.r
This command will cause the program contained in "prog.r" to be preprocessed, and the Fortran
output tn be produced on the file "prog.f" (which is exactly what the Fortran compiler
expects) •
Here are some more examples to show other ways in which 'rp' can be called:

i preprocess the files "pl.r", "p2.r", and "p3.r"
i
and produce Fortran output on "pl.f"
rp pl.r p2.r p3.r

i preprocess the files "pl.r", "p2.r", and "p3.r"
i
and produce Fortran output on "ftn out"
rp pl.r p2.r p3.r

-0

ftn out

i preprocess the file "pl.r", produce the Fortran
i
on "ftn out" and include code to produce
i
subprogram level trace
rp -t pl.r

-0

ftn out

Compiling
After turning your Ratfor source code into Fortran with the preprocessor, the next step
is to compile the Fortran code.
Since the Subsystem uses the Primos Fortran compiler, the
'fc' command just produces a sequence of Primos commands to cause the compilation The following command will call the Fortran compiler for a compilation:
fc «options>]

[+b ]

[+1 ]

The Fortran source code must be in the .file .
The relocatable binary output will be
placed in the file , unless "+b " is omitted. Then, following Subsystem conventions,
the binary file name is constructed by appending the input file name with ".b"; if
the input file ends with ".f", the "f" will be replaced by the "bu. Normally no listing is
produced; however, if one is requested, it will appear on the file , or if the listing file name is omitted, the name will be constructed by appending the ".1" to the input
file name; again, if the input file name ends in ".f", the Of" will be replaced with the "1".
is a series of single letter options that specify how the compiler is to
generate the object code.
Since there are too many options to completely describe here, we
will only mention a few of the more important ones. For those who wish to make full
use of
the
Fortran compiler, or for those just curious, the Software Tools Subsystem Reference
Manual, or the 'help' command will give complete information.

27 -

Ratfor User's Guide
Here are brief descriptions of the options of interest:
+a

Generate pseudo-assembly code describing the object code produced.

Unless otherwise specified, consider all integers to be "long" (32-bit) rather
than "short" (16-bit).
(This is useful for programs ported from machines with
longer word lengths.)

Produce a listing of the Fortran program with imbedded diagnostics.

Insert code to produce a statement-level trace during execution.

-u

Do not flag undeclared variables.

Of course, more than one of these options may be specified.
Again, even though all of this looks very complicated, it is really very simple, if you
have used the Subsystem file naming conventions.
If you have your Fortran code in a file
named "prog.f" (remember where Ratfor put its output), you may compile it, using the default
options, by just entering
fc prog.f
The command will call the Fortran compiler to produce binary output in the file "prog.b".
Just for completeness, here are some other examples of 'fc' commands:

i Compile "pl.f" to produce the binary "pl.b" and
•
and a listing on "pl.l"
fc +1 pl.f
• Compile "pl.f" to produce the binary "bin" and
•
the listing on "list"

Ec +1 pl.f +b bin +1 list
• Compile "p3.f", produce a pseudo-assembly code
•
listing, do not flag undeclared variables,
•
and default to 32-bit integers
fc +1 +a +i -u p3.f
One problem you may encounter when using 'fc' is that the Primos Fortran compiler pays
no attention to i/o redirection when it is writing error messages to the terminal. This IS a
problem common to all Primos commands called from the Subsystem.
If you want to record the
terminal output of the Fortran compiler, you must use the Primos command output facility.
This facility is accessed through the Subsystem 'como' command; for details, see the Software
Tools Subsystem Reference Manual or use the 'help' command.

Linking
The last step in preparing the program for execution is linking. The linking step fixes
the memory locations of the Subsystem common areas; assigns the binary module for each subprogram to an absolute memory location; and links in the required Subsystem support routines,
Fortran run-time routines, and Primos system calls. The memory image file produced by this
step may then be executed. It should be noted here that programs linked under the Subsystem
can run only under the Subsystem; they may not run without it.
.
The 'ld'· command is used to invoke the Primos loader to to do the linking.
is as follows:

Its

syntax

ld [-ul • • • [-1 ] • • •
[-t -m] [-0 to appear on the command
line. Any number of libraries (residing in "=lib=") may then be specified with the "-I"
-

28 -

Ratfor User's Guide
option.
The "_t -m n options cause a load map to be produced on a file with the name as the
output file (or first , if an output file is not specified) with n. m" appended.
If the file name ends with ".b", the ".b" is replaced by the n.mn. The "-Oil option specifies
the name of the output file.
If the "_0" option is omitted, the output file will have the
same name as the first , with ".0" appended.
If the name of the first
ends-in ".b", the ".b" will be replaced by the ".0".
Even though linking is a mysterious process, it need not be traumatic. Most of the
time, you will be linking a single binary file with no additional libraries.
For instance,
if you had a binary file named "prog.b," you could produce an object program by just typing
the command
ld prog.bThe Primos loader would be invoked, and after a great deal of
terminal, the executable program "prog .0" would be produced.

garbage

was

printed

the

The only thing that you must do is look for the message "LOAD COMPLETE" lurking
somewhere near the end of this garbage.
If you find this message, it means that all of the
external references in your program (subroutine and function calls) have been satisfied, and
linking is complete.
If you don't find this message, there- are unsatisfied references in
your program.
You may then call 'ld' with the "-un option and the loader will print the
names of the unsatisfied references on the terminal.
You will probably then find that these
references are caused by misspelled subprogram names, missing subprograms, or undimensioned
arrays (remember, the Fortran compiler treats undimensioned arrays as functions calls, so you
may not always get an error message from the compiler).
Again, for completeness, here are some examples of 'ld' at work:

i link the binary files "pl.b", "p2.b", and "p3.b"
i
to produce "pl.o" as output
ld pl.b p2.b p3.b

i link the binary file "nprog.b",
i
include the library "vpatlb",
i
and produce the output file "nprog"
Id nprog.b -1 vpatlb

-0

nprog

i link the binary files "npl" and nnp2",
i

produce a load map,
and output "my_new_prog"

The Primos loader also pays no attention to i/o redirection. If you want to catch its
terminal output, you must use the Primos 'como' commands. For details, see the reference
manual or-use the 'help' command.
Executing
Executing a Subsystem program is the easiest step of all. All you have to do to execute
it is to type its name.
For instance, if your object program was named "prog.o", all you
need type is
prog.o
to make it go.
Because the shell also looks in your current directory for executable
programs, nprog.o" is now a full-fledged Subsystem command. You may give it arguments on its
command line, redirect its standard inputs and outputs, include it in pipelines, or use it as
a function.
Of course to be able to do all of these things properly,
it must observe the
Subsystem conventions and use the Subsystem I/O routines.
Shortcuts
There
programs.
Quite

are

several

shortcuts

that

speed

things

and save typing when developing

Shell Programs. Shell programs can be a great help when performing repetitive tasks.
often one of these tasks is preprocessing, compiling, and linking a program during its
-

29 -

Ratfor User's Guide
development. A simple shell program can save a great deal of typing in this situation.
For
instance, let's say we are writing a Ratfor program that is in the file "np.r". We are in
the process of adding new features to "np" and will probably compile and test it several
times.
We can make a very simple shell program that will keep us from having to type 'rp,'
'fc,' and 'ld' commands every time we want to make a test run. All we have to do make a file
containing these three commands with 'cat':

J cat >cnp
rp np.r
fc np.f
ld -u np.b -0 np

]

Now the file "cnp" contains the following text:
rp np. r
fc np.f
ld -u np.b

-0

All we need do now to preprocess, compile, and link our program is just type the name of
shell program as a command:

the

cnp
and the shell will execute all of the commands contained in it.
The
'Rfl' Command.
Of course,
it is so common to preprocess, compile, and link a
program, there is an already-built shell program that works nicely in most cases.
'Rfl'
contains the necessary commands to preprocess, compile and link a Ratfor program contained in
a file whose name ends with ".r". All you have to do is type
r1:l np.r
and
'rfl' will execute the necessary commands to produce an executable file named Ilnp" •
(note that the executable file is named nnp" and not "np.o"l)
'Rfl' can also do some other
handy things that you can find out about in the Subsystem reference manual.
Storing Source Programs Separately.
When you write fairly large programs or test
modules independently, it is often convenient to store the programs in separate files.
If
this is the case, creating an executable program is just a little bit more complicated. The
easiest solution is to just name all of the programs on the 'rp' command line, like this:
rp pl.r p2.r p3.r

'Rp' wi 11 preprocess all of the files together and produce output on the file "pl.f".
The
define statements in "pl.r" will still be in effect when "p2.r" is preprocessed, etc. so
"pl.r", "p2.r", and "p3.r" might just as well be together in one file.
Compiling Programs Separately. A little bit harder, but sometimes much faster,
is to
preprocess and compile the modules separately and then combine them during linking. There
are two things that you have to watch.
The first problem with separate compilation is that
define statements in one file cannot affect subprograms in the other files.
For a large
program that would benefit from separate compilation, this nastiness can be avoided by placing all of the defines together in one file and placing an include for that file at the
beginning of each of the files containing the program. The defines will then be applied
uniformly to all parts of the program.
The second thing is that since Ratfor chooses unique Fortran names in the order it is
presented with "long" Ratfor names, it cannot guarantee that a long name in one file will be
transformed into exactly the same Fortran name as the same long name in a second file
(although the probability is quite high). To avoid problems, either subprogram names that
are cross-referenced in· the separate binary files should be given six-character or shorter
names, or a linkage declaration containing the names of all subroutines, function, and common
blocks should be inserted at the beginning of each module.
It is usually easiest to handle
the linkage declaration just like the define statements: put it in a separate file, and add
an include statement for it at the beginning of each module.
Then, the program units in each file may be preprocessed and compiled separately.
The
binary files from the separate compilations are linked together by just listing the names of
all of the files on the 'ld' command:
ld pl.b p2.b p3.b
The only restriction is that the main program must appear first.
The object file from this
example would be named "pl.o", but t.his could have been overridden by incl uding the "-0
-

30 -

Ratfor User's Guide
(output file>" option.
When compiling parts of a program separately, you should be aware that incorrect use of
the linkage declaration can cause totally irrational behavior of the program with no other
indication of error.
Since no checking is done on the linkage declaration, you must be
certain that every external name appears in the statement. More importantly, when you add a
subroutine, function, or common block, you must remember to change the linkage declaration.
In addition,
if you do not add the name to the very end of the declaration, you must
immediately recompile all modules!
If you compile separately,
and are confronted with a
situation in which your program is misbehaving for no apparent reason, re-check the linkage
declaration and recompile all the modules.
Debugging
Debugging unruly programs under Primos is at best a grueling task, as currently there is
almost no run-time debugging support.
Except for a couple of machine-language level debuggers, you'll get very little help from Primos (except for some nasty error messages) while
debugging programs.
This means that such techniques as top-down design,
reading other
programmers'
code,
and
reasonably careful desk checking will payoff in the long run.
But
even with all the care in the world, some bugs will creep through
(especially on an
unfamiliar system).
The next few paragraphs will be devoted to techniques for exterminating
these stubborn bugs.
For an experienced user, a load map, the Primos DMSTK command, and VPSD (the V-mode symbolic debugger) can very quickly isolate the location, if not the cause, of a bug. With more
complicated programs that are dependent on the internal structure of the machine and operating system,
such machine level debugging cannot always be avoided.
If you find yourself in
such as position, you can begin to learn some of these things by examining the following
reference manuals:
MAN 1671

System Reference Manual, Prime 100-200-300

MAN 2798

System Reference Manual, Prime 400

FDR 3059

The PMA Programmer's Guide

FDR 3057

User Guide for the Fortran Programmer

Most often, the bug can be found by one or more of the following techniques:
(1)

Inserting 'print' calls to display the intermediate results within the program.

(2)

Using the Ratfor subroutine trace.

(3)

Using the Fortran statement number and assignment trace.

It
is usually quickest to use the Ratfor subroutine trace (by including the "-t" option on
the 'rp' command line).
Although this trace lists only subroutine nesting,
it will narrow
down where a program is blowing up to a single subprogram.
If the program is very modular
and contains mostly small subprograms, quite often, the error can be spotted.
If the Ratfor trace fails to pinpoint the problem, the Fortran statement and assignment
trace will give a great deal more information (possibly hundreds of pages).
The Fortran
trace can be produced by specifying the "+t" option on the 'fc' command.
The Fortran code
produced by 'rp' must be examined to locate the statement numbers, but given the large number
of statement labels generated by 'rp,' study of this trace can isolate the problem practically to within one statement.

The above debugging methods are quick and easy to use when the program contains a
catastrophic error that causes an error termination or an infinite loop. While this is
sometimes the case, more often a subtle error is the problem.
In finding these errors, there
is no substitute for carefully inserted debugging code (such as calls to 'print') at critical
points in the program.
The rest of this section is devoted to a brief description of many of the terminal
errors that may do away with programs (and the Subsystem).
Most terminal errors cause the
Subsystem command interpreter to be terminated along with the user's delinquent program. You
can tell that you've been booted into Primos by the appearance of the "OK," or "ER!" prompt.
All error messages that cause an exit to Primos are briefly explained in appendix A-4 of the
Prime
Fortran Programmer's Guide (FDR3057).
Some very common programming errors can cause
cryptic error messages with explanations that are close to unintelligible.
Hopefully,
most
of these messages are described below.

31 -

Ratfor User's Guide
Many Primos error messages are dead giveaways of program errors. Messages that begin
with four asterisks are from the Fortran runtime packages
they usually indicate such
things as division by zero or extraction of the square root of a negative number.
For exampIe,

****

SQRT -- ARGUMENT < 0

OK,

results from extracting the square root of a number less than zero.
Other, more mysterious, error messages can also be caused by simple program errors.
Error: condition "POINTER FAULTS" raised at
can be caused by referencing a subprogram which has not been included in the object file.
obvious indication of a missing subprogram is the failure to get the

LOAD COMPLETE
message from 'ld'.
(Note that the Fortran compiler treats references to undimensioned arrays
as function calls!)
A more insidious cause of the "POINTER FAULT" message is a reference to
an unspecified argument in a subprogram; i.e.
the calling routine specifies three arguments
and the called routine expects four.
The error occurs when the unspecified argument is
referenced in the subprogram, not during the subprogram call.
Error: condition "ACCESS VIOLATION$" raised at
Error: condition "RESTRICTED INST$" raised at
Error: condition "ILLEGAL SEGNO$" raised at
Error: condition "ARITH$"-raised at
Program halt at
all can result from a subscript exceeding its bounds. Because the program may have destroyed
parts of its code, the memory addresses sometimes given may well be meaningless.
Even so,
you may locate the routine in which the program blew up by using the Primos DMSTK command and
a load map.
For
instance, given the following scenario
(ellipsis indicate irrelevant
information) ,
Error: condition "POINTER FAULT$" raised at 3.4000.001000.
OK, dmstk
Stack Segment is 6002.
6)

001464: Condition Frame for "POINTER FAULT$";
Raised at 3.4000.017202; LB= 0.4000.017402,

•••

7) 001374: Fault Frame; fault type= 000064
Returns to 3.4000.017202; LB= 0.4000.017402,
Fault code= 100000, Fault addr~ 3.4000.017204
Registers at time of fault:
you can at least attempt to tell where the program was executing. The numbers following
"LB=" on the underlined portion of the stack dump show the address of the data area of the
procedure executing when the fault occurred.
The segment number portion of this address (the
four-digit part) tells who the routine belongs to:
Segment

Use

0000 - 0023
2030
203')
2050
4000 - 4037
6001

Operating System
Software Tools Shell
So f t wa r e To 0 1 s Li bra r y
Fortran Library
User Program
Fortran Library

If the executing routine is not part of your program, you can trace back the stack (see
below) until you find which of your subprograms made the call.
If the segment number begins
with "4", you need only look down the right-most two columns of the load map (see the 'ld'
command) for the two numbers (4000 17402 in this case).
If you get an exact match, just look
across to the name on the left -- this is the subprogram that was executing.
Otherwise,
if
none of the numbers match then either the program has clobbered itself and jumped into
nowhere, you left off an argument to a library subprogram, or one of the library routines has
caused an exception trap with no fault vector.
can

Subsequent entries in the stack dump (following the information in the last scenario)
be used to
find what procedure calls were in process when the error occurred.
The
-

32 -

Ratfor User's Guide
entries are of the following form:
Stack Segment is 4035.
8) 002222: OWner=
(LB= 0.4000.017402).
Called from 3.4000.017700: returns to 3.2035.017702.
9) 002156: OWner=
(LB= 0.4000.013026).
Called from 3.4000.013442: returns to 3.2030.013450.

Each entry on the Subsystem stack (segment 4035) represents a procedure call in process. You
can use the numbers following the "LB=n and the load map to trace back through the "stack" of
procedure calls, just with the nfault frame" mentioned above.
If you find yourself at a complete and total loss at finding why your program is blowing
up, here is a list of some of the errors that have caused us great anguish:
Subscript out of range.

This error can cause any number of strange results.

Undefined subprogram. This error can be detected by the lack of a "LOAD COMPLETE"
sage from the 'ld' command.

mes-

Too few arguments passed. This error almost always causes a "POINTER_FAULT$" when the
missing argument is referenced.
Code and initialized local data requires more that one segment (64K words).
The load
map shows how much space is allocated. No linkage or procedure frame should appear in
any segment other than 4000.
Delimiter character is missing in a packed string.
This includes periods in packed
strings passed to 'print' and 'input'. This error causes the program to run wild, writing allover the place.
Type declaration is missing for a function. This error can causes failure of routines
such as 'open' which return an integer result.
The Primos Fortran compiler does not
flag undeclared functions. This error may also cause an erratic real-to-integer conversion error or cause the program to take an exception trap.
A subprogram is changing the value of a constant. If you pass a single constant as a
function or subroutine argument, and the subprogram changes the corresponding parameter,
the values of all occurrences of that constant in the calling program will be changed.
With this error, it is quite possible for the constant 12 to have the value -37 at some
time during execution.

Performance Monitoring
In most cases, it is very difficult to determine how much processing time is required by
different parts of a program. Since it is nearly impossible to determine which parts of a
program are "inefficient", especially before the program is written, it often more effective
to write a program in the most simple and straightforward manner, and then use performance
monitoring tools to find where the program is spending its time.
It has many times been our
experience to find even though parts of a program are coded inefficiently, only a very small
amount of time is wasted.
There are two available methods for obtaining an execution time "profile" of a Ratfor
program. The first method provides statistics on the number of calls to and the amount of
time spent in each subprogram. The second method provides a count of the number of times
each statement in the program is executed.
To invoke the subroutine profile, just preprocess (in one run) all the subprograms to be
profiled. Add the "-p" option to the 'rp' command line when the programs are preprocessed.
Then compile, link and execute the program normally. When the program terminates (it must
execute a stop statement, and not call "error"), type the command
profile
'Profile' accesses the files "timer dictionary" (output by 'rp') and
your program) and prints the subroutine profile to standard output.

"_profile"

(output

To invoke the statement count profile, put all the subprograms to be profiled (you must
also include the main program) in a single file.
Then preprocess the file with 'rp' and the
"_c R option. Compile, link, and execute the program. When the program terminates normally,
type the command
- 33 -

Ratfor User's Guide
st_profile myprog.r
(Of cource, assuming your source file name is "myprog.r".)
execution count for each line will be printed.

A listing

the

program

with

When running a profile, there are several things to keep in mind. First, the program
with the profiling code can be more than twice as large as the original program. Second, the
program can run an order of magnitude more slowly. Third, there can be a considerable delay
between the execution of the stop statement and the actual end of the program. Finally, you
should remember that the main program and all subprograms to be profiled must be preprocessed
at the same time.
Conditional Compilation
Conditional compilation is a handy trick for inserting debugging code or setting
compile-time options for programs. Conditional compilation can be approximated in Ratfor by
defining an identif ier, such as "DEBUG" to a sharp sign or null
(for off and on respectively).
Lines in the Ratfor program beginning with the identifier "DEBUG" (i .e. debugging
code) are not compiled if "DEBUG" is defined to be "ft", but are compiled normally if "DEBUG"
is defined as a null string.
For instance, the following example shows how conditional compilation can be used to
"turn off" print statements at compile time:
define (DEBUG, ft)
fd
DEBUG

= open

(fn, READ)
call print (ERROUT, "fd returned:*i*n"s, fd)

len = getlin (str, fd)
DEBUG call print (ERROUT, "str read: *s"s, str)
In this example, all lines beginning with "DEBUG" are ignored, unless the define statement is
replaced wi th
define (DEBUG, )
Then, all lines beginning with "DEBUG" will be compiled normally.

Source Program Format Conventions
After considering many program formatting styles, we have concluded that the convention
used by Kernighan and Plauger in Software Tools is the most expedient in terms of clarity and
ease of modification.
As a consequence~have tried to be consistent in the use of this·
We
convention throughout the Subsystem to provide uniformly readable and modifiable code.
present the convention here in the hope that you can use it to the same advantage.
Statement Placement
The placement of statements in program units is perhaps the most important part of the
formatting convention. Through uniform placement of statements, many documents can be
produced directly directly from the source code. For instance, the skeleton for Section 2 of
the Subsystem Reference Manual was produced originally from the subprogram headers of the
Subsystem library subprograms. Then the detail was filled in using the text editor.
The order of a program unit (including a main program) should be as follows:
1.

A comment line of the following format:

fI: ---
2.

The subroutine or function statement (or nothing if it is a main program).

The declarations of all arguments passed to the subprogram, if any.

A blank line

Declarations for all local variables in the program unit.

A blank line.

- 34 -

Ratfor User's Guide
7.

Executable program statements.

The end statement.

Three blank lines.

Of course, extra blank lines should be used freely to separate different
declarations and different logical blocks of executable statements.

logical

groups

As an example, here is the source code for the subroutine "cant" taken directly from the
Subsystem library:
• cant --- print "can't open" file message
subroutine cant (str)
character str (ARB)
call putlin (str, ERROUT)
call error (n: Cannot open.")
return
end

Indentation
The indentation convention is very simple. It is based on the idea that a statement
should be indented three spaces to the right of the innermost statement controlling it.
Braces are placed as unobtrusively as possible, without affecting the ease of adding or
deleting statements.
Statements, with the exception of the program heading comment, are placed three spaces
to the right of the left margin. All statements are placed in this position, unless they are
subordinate to a control statement. In this case, they are placed three spaces to the right
of the beginning of the controlling statement.
Braces do not affect the placement of statements. An opening brace is placed on the
line with the controlling statement.
A closing brace is placed on a separate line three
spaces to the right of the beginning of the controlling statement.
Multiple statements per line are forbidden, except when a chain of if - else if
else statements is used to implement a case structure.
In this event, the else if is
considered a single statement, appearing on the same line, and subsequent lines are indented
only three spaces to the right.
If all of this seems terribly confusing, here are some examples that show the identation
convention in action (the bars are just to show you the matching of braces):
for

(i = 1; str (i) -= EOS; i += 1) {
if (str (i) == 'a' c) {
I j = ctoi (str (2), i)
I select (j)
I I when (1)
I I I call altl
I I when (2)
I I I call alt2
I
I
when (3) {
I I I call altl
I I I call alt2

I I I }
I else
I
call error ("number must be
---I

I
I else if (str (i) == 's'c)
I
repeat {
I
I j = ctoi (str (2), i)
I
I status = getnext (j)
I
---I until (status == EOF)
I else {
I I call clean_up
I I stop
I ---I
---I

- 35 -

1 and

3.")

Ratfor User's Guide
Subsystem Definitions
The
use of the define statement plays a large part in producing readable, maintainable
programs.
Hiding implementation details wi th define statements not only produces more
readable code,
but allows changes in the implementation details to be made without necessitating changes in applications programs.
The development of a large part of the
Subsystem
would have been greatly hindered if it had not been possible to redefine the constant "STDIN"
from "1" to "-II", with no more than recompilation.
The Subsystem definitions file, "=incl=/swt def.r.i" exists primarily to hide the dirty
details of the Subsystem support routines from Ratfor programmers.
We sincerely believe that
the character string "EOF" is inherently more meaningful than the string
"-I".
(Would you
believe that after three years of using the Subsystem, the author of this section had to look
up the value assigned to "EOF" in order to write the preceding sentence?)
Of course,
the
use of
the Subsystem definitions also allow the developers to change
these values when necessary.
Of course, these changes force recompilation of all
existing
programs, but we feel that this is a small price to pay for the availability of more advanced
features.
All
users of the Subsystem support routines are therefore warned that the values
of the Subsystem definitions may change between versions of the Subsystem.
(At Georgia Tech,
this may be daily.)
Programs that depend on the specific values of
the symbolic constants
may well cease to function when a new version of the Subsystem is installed.
Appendix
D contains
specific information about (but not specific specific values for)
the standard Subsystem definition file.
As a general rule, all symbolic constants mentioned
in Section 2 of the Subsystem Reference Manual can be found in "=incl=/swt def.r. i".

Using the Subsystem Support Routines
Many of the
capabilities available to a Subsystem programmer are provided through the
Subsystem support routines.
The Subsystem support routines consist of well over one hundred
Ratfor
and
PMA subprograms that either perform common tasks, insulate the user from Primos
and Fortran, or conceal the internal mechanisms of the Subsystem.
By default,
the
library
containing all of these routines ("=lib=/vswtlb") is included in the linking of all Subsystem
programs.
Therefore, no special actions need be taken to call these routines.
If you notice that there are some "holes" in the functionality of the Subsystem library,
you
are probably quite correct.
The Subsystem library has grown to its present size through
the effort of many of its users.
The instance often arises that a
routine
is required
to
fill a specific function.
In keeping with the Software Tools methodology, instead of writing
a
very specific routine, we ask that the author write-a-sTightly more general routine that
can be used in a variety of instances.
The routine can then be documented and placed in the
Subsystem library for the benefit of all users.
Many of the support routines, including the
dynamic storage management routines, have come from just such instances.
The "holes" in the
Subsystem library are just waiting for someone to fill them; if you need a routine that isn't
there, please write it for us.
Initialization and Termination
The
two most important routines are those that perform the initialization and termination of Subsystem programs.
Init.
The subprogram 'init' performs the initialization necessary when execution a Subsystem program.
The statement "call init" must be the
first executable statement
in any
program that is to run under the Subsystem. As a convenience, Ratfor automatically includes
such a call in every main program.
Swt.
The subprogram 'swt' terminates the program and causes a return to
the
Subsystem
command
interpreter.
Any Subsystem files
left open by the program are closed.
Ratfor
automatically inserts a "call swt" any time it encounters a Fortran stop statement.
All Ratfor programs should stop rather than "call exi t".
Fortran and
PMA programs should
invoke
'swt' to terminate.
Character Strings
Most of the
support
routines use characters that are unpacked, one per word (i.e.
integer variable), right-justified with zero fill,
rather
than
the
Fortran default,
two
characters per
word, left-justified, with blank fill (for an odd last character).
In addition to the simplicity of manipulating
unpacked strings,
the
unpacked
format
represents
characters as small,
positive integers.
Thus, character values can be used in comparisons
and as indexes without conversion.

- 36 -

Ratfor User's Guide
Most of the support routines that manipulate character strings expect them to be stored
in an integer arrray, one character per word, right-justified and zero-filled, and terminated
with a word containing the symbolic constant 'EOS'.
Strings of this format are usually called EOS-terminated strings.
Support for the use of unpacked characters is provided in several ways:
(1)
the Subsystem I/O routines perform conversion to and from unpacked format, (2) single-character
constants 'a'c, 'b'c, ','c, etc. are provided for use in place of single-character Hollerith
literals, and (3) the Ratfor string statement is provided to initialize EOS-terminated
strings.
In a few cases,
it is more convenient to use a Hollerith literal instead of an EOSterminated string.
Since it is impossible to tell the length of a Hollerith literal at run
time, Hollerith literals used with the Subsystem are required to contain a delimiter character (usually a period) as the last character.
Hollerith literals or integer arrays that
contain Hollerith-format characters and' end with a delimiter character are referred to as
packed strings.

Following are brief descriptions for the most generally useful character manipulation
routines.
For specific information, see the Software Tools Subsystem Reference Manual.
Equal.
'Equal'
is an integer
function that takes two EOS-terminated strings as
arguments.
If the two strings are identical, 'equal' returns YES; otherwise it returns NO.
For example,
string dash x "-x"
integer equal
if (equal (argument, dash x)
call cross ref

YES)

Index.
'Index' is used to find the position of a character in an EOS-terminated string.
If the character is in the string, its position is returned, otherwise zero is returned.
'Index' is very similar to the built-in function of the same name in PL/I.
Example:
string options "acx"
integer ndx
integer index
ndx = index (options, opt character)
select (ndx)
when (1)
ca1l list all
when (2)
call list common
when (3)
call cross reference
else
call remark ("illegal option"p)
This example selects one of a number of subroutines to be executed depending on a singlecharacter option specifier.
Of course,
this particular example could be done with just
select alone.
'Index' is also useful
in character transliteration and conversion from
character to binary integer.
Length.
'Length'
is an integer function that returns the length of an EOS-terminated
string. The length of a string is zero if and only if its first character is an EOS;
it is
the number of characters before the EOS in all other cases.
'Length' is often useful in
deciding where to start appending additional text, as in the following example:
integer len
integer length
len = length (str)
call scopy (new_str, 1, str, len + 1)
Mapdn and Mapup. These functions accept a single character as an argument and if the
character is alphabetic, force it to lower or upper case, respectively.
'Mapdn' and 'mapup'
quite often find use in mapping option letters to a single case before comparison.
Since
non-alphabetic characters are not modified, these routines may be used safely even if nonalphabetic characters appear.
In addition, these routines provide a very good place to
isolate character set dependencies.
For example,

37 -

Ratfor User's Guide
character c
character mapdn
if

(mapdn (c) == 'a' c)
• handle 'a' option

else i f ' (mapdn (c) == 'l'c)
• handle 'I' option
Mapstr.
'Mapstr'
provides case mapping for alphabetic characters in EOS-terminated
strings. As arguments 'Mapstr' takes a string and the symbolic constant 'LOWER' or
'UPPER'.
Alphabetic characters in the string are then forced to lower or upper case, depending on the
constant specified.
Scopy. The subroutine 'scopy' is used for copying EOS-terminated strings.
It requires
four arguments:
the source string, the position from which to start copying, the destination
string, and the position at which filling begins in the destination string. Since Ratfor
provides no string assignment, 'scopy' is normally used to provide the capability. The simple movement of a string from one place to another is coded as
character strl (MAXLINE), str2 (MAXLINE)
call scopy (str1, 1, str2, 1)
'Scopy' is also capable of appending one string to another, as in the following example:
character strl (MAXLINE), 'str2 (MAXLINE)
call scopy (strl, 1, str2, length (str2) + 1)
Note that 'scopy' makes no attempt to avoid writing past the end of 'str2'1
~.
'Type'
is another of the routines that is intended to isolate character dependencies. Type is a function that takes a single character as an argument.
If that character
is a letter, 'type' returns the constant 'LETTER';
if the character is a digit,
'type'
returns the constant
'DIGIT'; otherwi se, 'type' returns the character.
'Type' often find s
use in a lexical analyzer:
.

characte.r c
character type
if (type (c)
LETTER)
• collect identifier
else if (type (c) == DIGIT)
• collect integer
else
• handle special character

File Access
File access is one of the more important aspects of the Subsystem. It is through the
Subsystem i/o routines that device indepedence and i/o redirection are accomplished;
moreover, the Subsystem routines provide a much less complicated interface than comparable
Primos routines.
';11 e
basic methon of access to a Subsystem file is through the contents of an integer
variable called a file descriptor.
File descriptors can be set by one of several routines or
they can be set to one of the six standard descriptors representing the six standard ports
provided to all Subsystem programs.

Quite often,
the standard ports provide all of the file access required
Values for the standard port descriptors can be accessed from defines
"=incl=/swt def.r.i"
('Rp' automatically includes this file in each run).
table gives-the symbolic names for the three standard input and three standard
available:

- 38 -

by a program.
contained in
The following
output ports

Ratfor User's Guide
Output Ports
STDOUTI (or STDOUT)
STDOUT2
STDOUT3 (or ERROUT)

STDINI (or STDIN)
STDIN2
STDIN3 (or ERRIN)
These constants
routine.

may

used

wherever

file

descriptor is required by a Subsystem i/o

Other files may be accessed or created through the routines 'open',
'create', and
'mktemp'
that are described later.
At the moment, it is sufficient to say that these
routines are functions that return a file descriptor that may be used in other Subsystem i/o
calls.
Once a file descriptor has been obtained, the file it references may be read with the
routines 'getlin', 'getch', or 'input'; written with the routines 'putlin',
'putch', or
'print'; positioned with the routines 'wind' or 'rewind'; or closed with the routines 'close'
or 'rmtemp'.
Open and Close.
'Open'
takes an EOS-terminated path name and a mode (one of the
constants READ, WRITE, or READWRITE) as arguments and returns the value of a file descriptor
or the symbolic constant ERR as a function value.
'Open' is normally used to make a file
available for processing in the specified mode.
If the mode is READ, 'open'
will open the
file for reading;
if the file doesn't exist or cannot be read (i.e. no read permission),
'open' will return ERR.
If the mode is WRITE or READWRITE, 'open' will open an existing file
or create a new file for writing or reading and writing,
if possible; otherwise it will
return ERR.
If
'open' opens an existing file, it will never destroy the contents, even if
mode is WRITE.
To be certain that a "new" file is empty, use 'create' instead of 'open'.
'Close' takes a file descriptor as its argument;
it closes and releases the file
attached to the descriptor.
If 'close' is called with a standard port, it takes no action.
Opening and closing a file is really very easy. This example opens a file named
"=extra=/news/index" and returns the file descriptor in 'fd'. If the file can't be opened,
the program will terminate with a call to 'cant'.
file des fd
integer open
string fn "=extra=/news/index"
fd = open (fn, READ) It open "=extra=/news/index"
if (fd == ERR)
call cant (fn)

call close (fd)
stop

It release the file

If the file can't be opened, 'cant' will print the message
=extra=/news/index: can't open
and terminate the program.
Create.
'Create' takes the same arguments as 'open', but also truncates the file
it empty) to be sure that there are no remnants of its previous contents.

(makes

Mktemp and Rmtemp.
Quite often, programs need temporary files for their internal use
only.
'Mktem~and 'rmtemp' allow the
creation of unique temporaries in the directory
"=temp=".
'Mktemp'
requires only a mode
(READ, WRITE, or REAI:MRITE) as an argument and
returns a file descriptor as its function value.
'Rrntemp' takes a file descriptor as its
argument and destroys and closes the temporary file.
(One should use caution, for if a
descriptor for a permanent file is passed to 'rmtemp', that file will also be destroyed.)
Typical use of 'mktemp' and 'rmtemp' usually involves the
intermediate file:

39 -

writing

and

reading

Ratfor User's Guide
file des fd
integer mktemp
fd = mktemp (READWRITE)

create a temporary file

call rewind (fd)

reposition the temporary

call rmtemp (fd)

close and destroy the temporary

Wind and Rewind.
The subroutines 'wind' and 'rewind' allow the positioning of an open
file to its end and beginning, respectively. Both take a file descriptor as an argument.
Usually,
'rewind'
is used when a program creates a file and then wishes to read it back;
'wind' is often used when a program wants to add to the end of an existing file.
A program wishing to extend a file would make a call to 'wind' just
opening the file to be extended:

after

successfully

file des fd
integer open
string fn "myfile"
fd = open (fn, READWRITE)
i f (fd == ERR)
call cant (fn)
call wind (fd)
~ file is now positioned at the
~
end, ready for appending.
Trunc.
. 'Trunc'
truncates an open file.
Truncating a file means releasing all of its
disk space, hence making it empty, but retaining its name and attributes.
'Trunc'
takes a
file descriptor as its argument.
Remove.
'Remove' removes a file by name, deleting it from the disk directory.
It takes
an EOS-terminated string as its argument, and returns the constant OK or ERR, depending on
whether or not it could remove the file.
('Remove' will also delete a Primos segment directory without complaining.)
Cant.
'Cant'
is a handy routine for handling exceptions when opening files.
For its
argument, 'cant' takes an EOS-terminated string containing a file name.
It prints the message
: can't open
and then terminates the program.
Getlin.
All Subsystem character input is done through 'getlin'.
'Getlin' takes a
character array (at least MAXLINE long) and a file descriptor and returns a line of input in
the array as an EOS-terminated string. Although the last character in the string is normally
a NEWLINE character, if the line is longer than MAXLINE, no NEWLINE will be present and the
rest of the line will be obtained on the next call to
'getlin'.
For its function value,
'getlin'
returns the length of the line delivered, (including the NEWLINE, if any) or the
constant EOF if end-of-file was encountered.
Most line-oriented i/o is done with 'getlin'. For instance, using
'getlin'
with its
analog
'putlin', a program to select only those lines beginning with the letter nan can be
written very quickly:
character buf (MAXLINE)
integer getlin
while (get! in (buf, STDIN) -= EOF)
i f (buf (1) == 'a'c)
call putlin (buf, STDOUT)
'Getlin' is guaranteed to never return a line
(including the terminating EOS).

longer

than

the

symbolic

constant

MAXLINE

If needed, there are a number of routines that you can call to convert the character
string returned by 'get1in' into other formats, such as integer and real.
Most of these
routines are described later in the section on "Type Conversion".

- 40 -

Ratfor User's Guide
Getch.
'Getch'
returns one character at a time from a file; it requires a character
variable and a file descriptor as arguments; it returns the character obtained, or the
constant EOF, in the supplied argument and as the function value. Calls to 'getch' and 'getlin' may be interleaved; 'getlin' will pick up the rest of a line not read by 'getch'.
'Getch'
is very useful in lexical analyzers or just when counting characters.
instance, the following routine counts both characters and lines at the same time;

For

character c
integer c count, 1 count
integer getch
c count = 0
1 count = 0
While (getch (c, STDIN) -= EOF)
c count = c count + 1
if (c == NEWLINE)
1 count
1 count + 1
This example assumes that since each line ends with a NEWLINE character, lines can be counted
by counting the NEWLINEs.
Input.
'Input' is a rather general routine created to provide easy access to both
interactive and file
input.
For interactive input, 'input' will prompt at the terminal,
accept input, and call the proper conversion routines to produce the desired data formats.
In case of unexpected input
(like letters in an integer), it will ask for a line to be
retyped.
For file input, 'input' recognizes that its input is not coming from a terminal
(even if. from a standard port) by turning off all prompting.
It will then accept fixed or
variable-length fields from the file under control of the format string.
'Input' requires a variable number of arguments; a file descriptor, a format string,
and as many destination fields as required by the format string.
It returns the constant EOF
as its function value if it encountered end-of-file; otherwise it returns OK.
The file descriptor passed to 'input' describes the file to be read. ~ll prompting output
(if any) always appears on the terminal.
The format string passed to 'input' indicates
what prompting information is to be output and what data format to expect as input.
Prompts
to be output are specified as literal characters; i.e. to output "Input X;", the characters
"Input X;" would appear in the format string. Prompting characters may only appear at the
beginning of the string and immediately after "skip-newline" ("*n") format codes. Data items
to be input are described by an asterisk followed by optionally one or two numbers and a letter • . For instance the code to input a decimal integer would be "*i" and the code to input a
double precision floating point number would be "*d".
When a call to 'input' is executed, the format string is interpreted from left to right.
When leading literal characters are encountered, they are output as a prompt. When the first
format code is encountered, a line is read from the file, the corresponding item is obtained
from the input line, and the item is placed in the next item in the argument list. More
items are removed from the input line until the end of the format string is reached or a
newline appears in the input.
If the end of the format string is encountered, the rest of
the input line is discarded, and 'input' returns OK.
Otherwise, if a newline is encountered
in the input, fields deSignated by the format are filled with empty strings, blanks, or
zeroes, until the format string is exhausted, or a code ("*n") to skip the NEWLINE and read a
new line is encountered.
The format string must contain exactly as many input indicators as there are receiving
data items in the call.
In any case, the maximum number of input items per call is 10.
Before
integers;

any

further,

here

call input (STDIN, "Type i:
i, j, k)

*i*nType j:

example

of an 'input' call to obtain three

*i*nType k;

If this statement were executed the following might appear at the
boldfaced) ;
Type i:
Type j;
Type k:

*i"s,
terminal

(user

input

22
476
1

We could also type all three integers on the same line, and 'input' would omit the prompting
for the second and third numbers:

- 41 -

Ratfor User's Guide
Type i:

22 476 I

There are a number of input indicators available for use in the format string.
Since
there are a large number of them with many available options, only a few are mentioned in the
following table. For further information, see the Subsystem reference manual.
Item Data

Input Representation

skip newline

If there is a NEWLINE at the current position, skip over it and read
another line. Otherwise do nothing.
(' Input' will never read more
than one line per call, unless this format code is present.

16 bit integer

Input an integer with optional plus or minus sign, followed by a
string of digits, delimited by a blank or newline.
Leading blanks
are ignored. The input radix can be changed by preceding the number
with "r" (e.g. octal should be expressed by "8r").

32 bit integer

Same as "*i".

32 bit real

Input a real number with optional plus or minus sign, followed by a
possible empty string of digits, optionally followed by a decimal
point and a possibly empty string of digits. Scaling by a power of
10 may be indicated by an "e" followed by an optional plus or minus
sign, followed by a string of digits. The number is delimited by a
blank; leading blanks are ignored.

64 bit real

Same as "*r".

string

Input a string of characters delimited by a blank or newline. No
more than MAXLINE characters will be'delivered, regardless of input
si ze.

Fixed size input fields can be requested by placing the desired field size immediately
following the asterisk in the format code.
For instance, to read three integers requiring
five spaces each, you can use the following format string:
"*5i*5i*5i"
You can also change the delimiting character of a field from its default value of a blank.
Just place two commas followed by the new delimiter immediately after the asterisk.
For
instance, two strings delimited by slashes can be input with the following format string:
*,,/s*,,/s
Regardless of the delimiter setting, a newline is alwats treated as a delimiter.
caution: if the delimiter is not a blank, leading blanks in strings are not ignored.

One

Readf. You can use 'readf' to read binary (memory-image) files that were created with
'writef'.
'Readf'
is the fastest way to read files, since no data conversion is performed.
However, use of 'readf' and 'writef' tend to make a program dependent on machine word size,
and hence, non-po'rtable.
'Readf'
takes three arguments: a receiving data array, the maximum number of words to
be read, and a Subsystem file descriptor. When called, 'readf' attempts to read the number
of words requested; if there are not that many in the file, it returns all that are left.
If
there are no words left in the file at all, 'readf' returns EOF as its function value; otherwise, it returns the number of words actually read as its function value.
Putlin.
'Putlin' is the primary output routine of the Subsystem.
It takes an EOSterminated string and a file descriptor as arguments, and writes the characters in the string
on the file specified by the descriptor. There is no restriction on the length of the input
string;
'putlin'
will write characters until it sees an EOS.
'Putlin' does not supply a
newline character at the end of the line; if one is to be written,
it must appear in the
string.
For a simple example, see the description of 'getlin'.
Putch.
A single character can be output to a file with 'putch'; it takes a character
and a file descriptor as arguments and writes the character on the file specified by the
descriptor. Calls to 'putch' and 'putlin' can be interleaved as desired.
Print.
'Print'
is a general output routine that accepts a format string and up to ten
output data items.
Interpreting the format string, 'print' calls the appropriate type conversion routines to produce character data, and outputs the characters as directed by the
format string.
'Print' requires several arguments: a file descriptor; an EOS-terminated
format string; and zero to ten output data arguments, depending on how many are required by
the format string.

- 42 -

Ratfor User's Guide
The format string contains two kinds of items:
literal items which are output when they
are encountered, and output items, which cause the next data argument to be converted to
character format and output. Literal items are just characters in the string; i.e. to output "X =", the format string would contain "X =". Output items consist of an asterisk, followed by two optional numbers, followed by a letter. For instance an output item for an
integer is "*i" and an output item for single precision floating point is "*r".
The next
example shows the output of three integers:
call print (STDOUT, "i
. i,j,k)

*i, j

*i, k

*i*n" s,

If this call were executed, the following might be the result:
i

342, j

1, k

-3382

Some of the more useful output items are described in the following table:
Item

Data Representation

*i
*1
*r
*d
*p
*s
*c
*n

short (16 bit) integer
long (32 bit) integer
single precision (32 bit) real
double precision (64 bit) real
packed, period-terminated string
EOS-terminated string
single character
newline

It is possible to exert much more control over the format of output using 'print'; for more
information, see the Subsystem reference manual.
Writef.
'Writef' is the companion routine to 'readf'; it writes words to a binary
(memory-image)
file.
It is the fastest of the output routines, since it performs no data
conversion.
It is called with three arguments: a data array containing the words to be
written, the number of words to write, and a Subsystem file descriptor. Here is an example
fast flle-to-file copy using 'readf' and 'writef' together.
integer 1, buf (1024)
integer readf
file_des in_fd, out_fd
repeat {
1 = readf (buf, 1024, in_fd)
i f (1 == EOF)
break
call writef (buf, 1, out_fd)
}
~.
'Fcopy' is a very simple routine that copies files. You open and position the
input and output files and call 'fcopy' with the input and output file descriptors.
It then
copies lines from the input file to the output file.
'Fcopy' uses a great deal of "secret
knowledge" of the workings of the Subsyst;em input-output routines, and as a consequence, it
copies disk-file to disk-file very quickly{':(even when the descriptors are of standard ports).

Markf and Seekf.
'Markf' and 'seekf' are companion routines that implement random
access--Qn disk files.
'Markf' takes a file descriptor as argument and returns a "file mark"
(currently a 32-bit integer).
'Seekf' takes the file mark along with a file descriptor and
sets the file pointer so that the file is positioned at the same place as when the "mark" was
taken.
To be used portably, "markP and "seekf" may only be used between calls to "readf" and
"writef", or immedately after input or output of a newline character (i.e. at the ends of
lines).
In addition, a call to 'putlin' or 'putch' on a file effectively (although not
actually) destroys information following the current position of the file.
For example, if
you want to write a line in a file, go off and do other operations on the file, and then be
able to re-read the line later, you can use 'markf' and 'seekf':

- 43 -

Ratfor User's Guide
file mark fm
file-mark markf
file-des fd
character line (MAXLINE)
fm = markf (fd)
call putlin (line, fd)

i i i perform other operations on 'fd'
call seekf (fm, fd)
call getlin (line, fd)

i get 'line' back

Non-portably, you can assume that a "file mark" is a zero-relative
the file -- to get word number 12 in the file, just execute

word

number

within

call seekf (intl (12), fd)
call readf (word, 1, fd)
(Remember:
file marks are 32 bits, not 16! We use 'intI' here to make "12" into a 32 bit
integer.)
Keep in mind that this "secret knowledge"
is useful only wfth "readf" and
"writef", not with any other input or output routine. Blank compression is used in line
oriented files, so the position of a line is dependent not only on length of previous lines,
but also on their content.
This usually makes the position of a line in a file quite
unpredictable.
Getto.
'Getto' exists primarily to interface with the Primos file system calls.
'Getto'
takes a path name (in an EOS-terminated string) as its first argument.
It follows
the path and sets the current directory to that specified for the file in the path name.
It
then packs the file name into its second argument, a 16 word array (with blank padding),
ready for a call to the Primos file system. It fills its 3-word third argument with the password of the last node of the path (if there was one).
Its fourth argument, an integer, is
set to YES if 'getto' changed the attach point, and NO otherwise.
'Getto' often finds use when functions other than those supported by Subsystem routines
need to be performed, such as setting the passwords on a directory:
integer pfn (16), opw (3), npw (3), pw (3), att
integer getto
string fn "=vars=/system"
i f (getto

(fn, pfn, pw, att) == ERR)
call print (ERROUT, "can't get to *s*n.", fn)
call spas$$ (pfn, 32, opw, npw) • set passwords
i f (att == YES)
call follow (EOS, 0)
i attach back to home

'l'ype Conversion
There are a very large number of type conversion routines available to convert most data
types into character strings and back. Because keeping up with all the conversion routine
names and calling sequences can be quite a chore, two routines 'decode' and 'encode' exist to
handle conversion details in a consistent format. These two routines are described at the
end of this section.
Most of the "character-to-something" routines require at least two arguments. The first
argument is usually the character string, and the second is an integer variable indicating
the first of the characters to be converted. The result of conversion is then returned as
the function value, and the position variable is updated to indicate the first position past
the characters used in the conversion.
Fo r example,
the simplest "character-to-integer" routine,
'ctoi'
requires the two
Since it skips leading blanks, but stops at the first non-digit
arguments mentioned above.
character,
it can be called several times in succession to grab several blank-separated
integers on a line:

- 44 -

Ratfor User's Guide
character str (MAXLINE)
integ er i, k (4), pos
integer ctoi
pos = 1
do i = 1, 4
k (i) = ctoi (str, pos)
i f (str (pos) -= EOS)
call remark ("illegal character in input"p)
This routine will assume unspecified values to be zero, but
blank characters are specified.

complain

non-numeric,

non-

Here is a list of all of the currently supported "character-to-something" routines.
ctoc

Character-to-character; copies.character strings and pays attention to the
maximum length parameter.

ctod

Character-to-double precision real; handles general floating point input.

ctoi

Character-to-integer
decimal only.

ctop

Character-to-packed-string; converts to packed format
character.

ctor

Character-to-single precision real; handles general floating point input.

ctov

Character-to-PL/I-character-varying;
format.

gctoi

Generalized-character-to-integer (16 bit); handles plus and minus signs;
in addition to program-specified radix, accepts an optional user-specified
radix from 2-16.

gctol

Generalized-character-to-long-integer
(32 bit); handles plus and minus
signs; in addition to program-specified radix, accepts an optional userspecified radix from 2-16.

(16

bit);

does

not

handle

converts

plus and minus signs;
with

delimiter

PL/I character varying

In addition to the "character-to-something" routines,
there are the "something-tocharacter" routines. Most of these routines require three arguments:
the value to be converted,
the destination string, and the maximum size allowable. They return the length of
the string produced as the function value.
An EOS is always placed in the position following
the last character in the destination string, but the EOS is not included when the size of
the returned string is calculated.
Since the functions will accept a sub-array reference for the output string, you may
place several objects in the same string.
For example, using the "integer-to-character" conversion routine 'itoc', you can place the four integers in the array 'k'
into
'str'
in
character format:
character str (MAXLINE)
integer i, k(4), pos
integer itoc
pos = 1
do i = 1, 4; {
pos = pos + itoc (k (i), str (pos), MAXLINE - pos)
if (pos )= MAXLINE - 1) i there's no room for any more
break
str (pos)
BLANK
pes = pos + 1
}

str (pos)

EOS

i cover up the last blank

This code will place the four integers in 'str', separated by a single blank. Although all
conversion routines leave an EOS in the string, we have to replace it here because we clobber
it with the blank.
It's worth noting that the maximum size parameter always includes the EOS -- the conversion routine will never touch any more characters than are specified by this parameter.
Here is a list of all available "something-to-character" conversion routines:
ctoc

Character-to-character; copies character strings and pays attention to the
-

45 -

Ratfor User's Guide
maximum length parameter.
dtoc

Double-precision-real-to-character; handles general floating point conversions in Basic or Fortran formats.

gitoc

Generalized-integer-to-character (16 bit);
program-specified radix.

gltoc

Generalized-long-integer-to-character
version; program specified radix.

itoc

Integer-to-character (16 bit); handles integer conversion; decimal only.

ltoc

Long-integer-to-character
deCimal only.

ptoc

Packed-string-to-character; accepts arbitrary delimiter character; will
unpack fixed length strings if delimiter is set to EOS and maximum is set
to (length + 1).

rtoc

Single-precision-real-to-character;
Basic or Fortran formats.

vtoc

PL/I-character-varying-to-character;
format to character.

(32

bit);

handles

integer

conversions;

(32 bit); handles long integer con-

handles

handles
converts

long

general
PL/I

integer

real

conversion;

conversion in

character

varying

Decode.
'Decode' handles conversion from character strings to all other formats.
It is
written to be used in concert with 'getlin' and other such routines, and as such, has a
rather odd calling sequence. It requires a minimum of five arguments: the usual string, and
string index; a format string; a format string index and an argument string index. Following
are receiving arguments, depending on the data types specified in the format string.
In
almost all cases, you should just supply variables with a values of 1 for the format index
and the argument index. The string index behaves just as it does in all other character-tosomething routine
on successful conversion , it points to -the EOS in the string. The
specifics of the format string and receiving fields are identical to
'input'.
The only
differences are that 'decode' returns with OK in the situations in which 'input' would read
another line of input, and EOF otherwise, and that all characters in the format string that
are not format codes are ignored.
Encode.
'Encode'
is a companion routine to
'decode':
it can access all of the
something-to-character conversion routines in a consistent way.
For arguments it takes a
character string, maximum length of the string, a format string, and a varying number of
source arguments, depending on the format string.
'Encode'
behaves exactly like 'print',
except that it puts the converted characters into the string, rather than putting them onto a
fi Ie.

Argument Access
Programs often find it necessary to access arguments specified on the command _line.
These arguments can be obtained as EOS-terminated strings, ready for processfng or passing to
a routine such as 'open'.
Getarg.
'Getarg' is the only routine that retrieves arguments from the shell's argument
buffer.
It is called with three arguments:
an integer describing the position of the
argument desired, a character array to receive the argument, and an integer describing the
maximum size of the receiving array.
'Getarg' tries to retrieve the argument in the
specified position; if it can, it returns the length of the string placed in the array; if it
can't, it returns the constant EOF.
'Getarg' will never write farther in the character array
than the size specified in the third argument.
Arguments are numbered 0 through the maximum specified on the command line. Argument 0
is the name of the command, argument 1 is the first argument specified, and so on. The number of arguments present on the command line can be determined by the point at which 'getarg'
returns EOF.
As a short example, here is a program
specified as arguments on its command line:

- 46 -

fragment that attempts to delete all files

Ratfor User's Guide
character file (MAXLINE)
integer i
integer remove, getarg
i = 1

wh i Ie (getarg (i, file, MAXLINE -= EOF»
{
if (remove (file) == ERR)
call print (ERROUT, "*s: cannot remove*n"s,
file)
i = i + 1
}

Dynamic Storage Management
Dynamic storage subroutines reserve and free variable size blocks from an area of
memory.
In this implementation, the area of memory is a one-dimensional array. Each block
consists of consecutive words of that array.
The dynamic storage routines assume that you have included the following declaration
your main program and in any subprograms that reference dynamic storage:

DS DECL (mem, MEMSIZE)
where 'mem' is an array name that can be used to reference the dynamic storage area. You
must also define MEMSIZE to an integer value between 6 and 32767 inclusive. This number is
the maximum amount of space available for use by the dynamic storage routines. In estimating
for the amount of dynamic storage required, you must allow for two extra 'overhead' words for
each block allocated.
Three other overhead words are required for a pointer to the first
available block of memory and to store the value of MEMSIZE.
Dsinit.

The call

call dsinit (MEMSIZE)
initializes the storage structure's pointers and sets up the list of free blocks.
must be made before any other references to the dynamic storage area are made.

This

call

Dsget.
'Dsget' allocates a block of words in the storage area and returns a pointer
(array index) to the first useable word of the block. It takes one argument -- the size of
the block to be allocated (in words).
After a call to 'dsget', you may then fill consecutive words in the 'mem' array beginning at the pointer returned by 'dsget' (up to the number of words you requested in the
block) with whatever information called for by your application. If you should write more
words to the block than you allocated, the next block will be overwritten. Needless to say,
if this happens you may as well give up and start over.
If 'dsget' finds that there is not enough contiguous storage space to satisfy your
request, it prints an error message, and if you desire, calls 'dsdump' to give you a dump of
the contents of the dynamic storage array.
Dsfree.
A call to 'dsfree' with a pointer to a block of storage (obtained from a call
to 'dsget') deal locates the block and makes it available for later use by 'dsget'.
'Dsfree'
will warn you if it detects an attempt to free an unallocated block and give you the option
of terminating or continuing the program.
Dsdump. The dynamic storage routines cannot check for correct usage of dynamic storage.
Because block sizes and pointers are also stored in 'mem' it is very easy for a mistake in
your program to destroy this information.
'Dsdump' is a subroutine that can print the
dynamic storage area in a semi-readable format to assist in debugging.
It takes one
argument:
the constant LETTER for an alphanumeric dump, or the constant DIGIT for a numeric
dump.
The following example shows the use of the dynamic storage routines and uses 'dsdump' to
show the changes in storage that result from each call.

- 47 -

Ratfor User's Guide
define (MEMSIZE, 35)
pointer posl, pos2
• pointer is a subsystem defined type
pointer dsget
DS_DECL (mem, MEMSIZE)
call dsinit (MEMSIZE)
call dsdump (LETTER) • first call
posl = dsget (4)
call scopy ("aaa"s, 1, mem, posl)
call dsdump (LETTER) • second call
pos2 = dsget (3)
call scopy ("bb"s, 1, mem, pos2)
call dsdump (LETTER) • third call
call dsfree (pos2)
call dsdump (LETTER) • fourth call
stop
end
The first call to 'dsdump'

*
*

(after' init') produces the following dump:

DYNAMIC STORAGE DUMP *
1 . 3 words in use
4
32 words available
END DUMP *

The first three words are used for overhead, and 32 (MEMSIZE - 3) words are available
ing at word four in 'mem'.
The second call to 'dsdump'
lowing:

start-

(after the first write to dynamic storage) produces the fol-

DYNAMIC STORAGE DUMP *
1
3 words in use
4
26 words available
30
6 words in use
aaa
END DUMP *

Note that only four characters were written, three a's and an EOS (an EOS is a nonprinting
character), but two extra control words are required for each block.
That block is comprised
of words 30 - 35 in the array 'mem'.
The thi rd call to 'dsdump'

(after the second 'scopy') produces the following:

DYNAMIC STORAGE DUMP *
1
3 words in use
4
21 words available
25
5 words in use
bb
30
6 words in use
aaa
END DUMP *

The final call to 'dsdump' produces:

DYNAMIC STORAGE DUMP *
1
3 words in use
4
26 words available
30
6 words in use
aaa
END DUMP *

As you can see, the second block of storage that began at word 25 has been
list of available space.

returned

the

Symbol Table Manipulation
Symbol
table routines allow you to index tabular data with a character string rather
than an integer subscript.
For instance, in the following table, the information contained
in "fieldl",
"field2", and "field3" can obtained by specifying a certain key value (e.g.
-

itS -

Ratfor User's Guide
n

firstentry") •
---------------------------------------~

I key

I fieldl I field2

Ifirstentry
I
Isecondentry

Ifield31

10268

data

27043

moredata

All Subsystem symbol table routines use dynamic storage.
Therefore, the declarations
and initialization required for dynamic storage are also required for the symbol table
routines; namely:

I
I
I

OS OECL (mem, MEMSIZE)
call dsinit (MEMSIZE)
where 'mem' is an array name that can be used to reference the dynamic storage area, and MEMSIZE is a user-defined identifer describing how many words are to be reserved for items in
dynamic storage.
MEMSIZE must be a integer value between 6 and 32767 inclusive. For a
discussion on how to estimate the amount of dynamic storage space needed in a program, you
can refer back to the section on the dynamic storage routines.
A symbol table entry consists of two parts: an identifier and its associated data. The
identifier is a variable length character string; it is dynamically created when the symbol
is entered into a symbol table. The data associated with the symbol is treated as a fixedlength array of words to be stored or modified when the assocated symbol is entered in the
table and returned when the symbol is looked up. The size of the data is fixed for each symbol table -- each entry in a table must have associated data of the same size, but different
symbol tables may have different lengths of data.

I,
I ..
I'
I
I
I

Mktabl.
A symbol table is created by a call to the pointer function 'mktabl' with a
single integer argument giving the size of the associated data array or the -node size".
'Mktabl'returns a pointer to the symbol table in dynamic storage. This returned pointer
identifies the symbol table -- you must pass it to the other symbol table routines to
identify which table you want to reference. A symbol table is relatively small (each table
requires about 50 words, not counting the symbols stored in it), so you may create as many of
I, them as you like (as long as you have room for them).
In the table above, if "fieldl" and "field3" require one word·. each, and "field2n
requires no more than 9 words, then you can create the symbol table with the following call:
pointer extable
extable = mktabl (11)
The argument
symbol.

'mktabl'

is 11 -- the total length of the data to be associated with each

Enter. To enter a symbol in a symbol table, you must provide two items:
an EOSterminated string containing the identifier to be placed in the table, and an array containing the data to be associated with the symbol. Of course this array must be at least as
large as the nnodesize" declared when the particular symbol table was, created. A call to the
subroutine 'enter' with the identifier, the data array, and the symbol table pointer will
make an entry in the symbol table. However, if the identifier is already in'the table, its
associated data will be overwritten by that you've just supplied. It is not possible to have
th~ same identifier in the same symbol table twice.
Now, continuing our example, to enter the first row of information in the table, you can
use the following statements:
info
call
info
call

(1) = 10268
scopy ("data"s, 1, info, 2)
(11) = 'u'c
enter ("firstentry"s, info, extable)

Lookup. Once you've made an entry in the symbol table, you can retrieve it by supplying
the identifier in an EOS-terminated string, an empty data array, and the symbol table pointer
to the function 'lookup'. If 'lookup' can find the identifier in the table, it will fill in
your data array with the data it has stored with the symbol and return with YES for its function value. Otherwise, it will just return with NO as its function value.

- 49 -

Ratfor User's Guide
In our example, to access the data associated with the "firstentyO we can make the
lowing call:
foundit

fol-

lookup ("firstentry"s, info, extable)

After this call (assuming that "firstentry" was in the table), °founditO would have the value
YES,
"info (1)" would have the value for "fieldl", "info (2)" through "info (lo)n would have
the value for "field2°, and "info (11)° would have the value for "field3".
Delete.
If you should want to get rid of an entry in a symbol table, you can make a
call to the subroutine
'delete' with identifier you want to delete in an EOS-terminated
string and the symbol table pointer.
If the identifier you pass is in the table,
'delete'
will delete it and free its space for later use.
If the identifier is not in the table, then
'delete' won't do anything.
Using our example again, if you want to delete 'firstentry' from the table, you can just
make the call
call delete (Ofirstentry"s, extable)
and "firstentry" will be removed from the table.
Rmtabl. When you are through with a table and want to reclaim all of its storage space,
you pass the table .pointer to 'rmtabl'.
'Rmtabl' will delete all of the symbols in the table
and release the storage space for the table itself. Of course, after you remove a table, you
can never reference it again.
To complete our example, we can get rid of our symbol table by just calling 'rmtabl':
call rmtabl (extable)
Sctabl.
So far, the routines we've talked about have been sufficient for dealing with
symbol tables.
It turns out that there is one missing operation: getting entries from the
table without knowing the identifiers. The need for this operation arises under many circumstaces.
Perhaps the most common is when we want to print out the contents of a symbol table
for debugging.
To use 'sctabl' to return the contents of a symbol table, you first need to initialize a
pointer with the value zero. We'll call this the position pointer from now on.
Then you
call
'sctable'
repeatedly, passing it the symbol table pointer, a character array for the
name, a data array for the associated data, and the position pointer.
Each time you call it,
'sctabl' will return another entry in the table:
it will fill in the character string with
the entry's identifier, fill in your data array with the entry's data, and update position in
the position pointer.
When there are no more entries to return in the table. 'sctabl'
returns EOF as its function value.
There are two things you have to watch when using 'sctabl'. First, if you don't keep
calling 'sctabl'
until it returns EOF, you must call 'dsfree' with the position pointer to
release the s.pace. Second, you may call 'enter' to modifl the value of a symbol while scanning a table, but you cannot use 'enter' to add a new sym 01 or use 'delete' to remove a symbol.
If you do, 'sctabl' may lose its place and return garbage, or it may not return at all!
Here is a subroutine that will dump the contents of our example symbol table:
• stdump --- print the contents of a symbol table
subroutine dptabl (table)
pointer table
integer posn
integer sctabl
character symbol (MAXSTR)
untyped info (11)
call print (ERROUT, "*4xSymbol*12xInfo*n"s)
posn = 0
while (sctabl (table, symbol, info, posn) -= EOF)
call print (ERROUT, "*lSsl *6i 1 *9s 1*c*n"s,
symbol, info (1), info (2), info (9»
return
end
If make
lowing:

call

to' stdump' after made the entry for "firstentry", it would print the ·fol-

50 -

Ratfor User's Guide
Symbol
firstentry

Info
l02681data

Other Routines
There are a number of miscellaneous routines that provide often needed assistance.
The
following
table gives their names and a brief description.
For full information on their
use, see the Subsystem reference manual:
date

Obtain date, time, process id, login name

error

Print an error message and terminate

Follow a path and set the current and/or home directories

remark

Print a string followed by a newline

tquit$

Check if the break key was hit

wkday

Determine the day of the week of any date

- 51 -

Ratfor User's Guide
Appendixes

Appendix A -- Implementation of Control Statements
This appendix contains flowcharts of the code produced by the Ratfor control
along with actual examples of the code Ratfor produces.

I
I
I

I
I
I
I

statements

In different contexts, a given sequence of Ratfor control statements can generate slightly different code.
First, where possible, statement labels are not produced when they are
not referenced. For instance, a repeat loop containing no break statements will have no
-exit" label generated, since one is not needed. Second, continue statements are generated
only when two statement numbers must reference the same statement.
Finally,
internally
generated goto statements are omitted when control can never pass to them; e.g. a when
clause ending with a return statement.
These code generation techniques make no fundamental difference in the control-flow of a
program, but can make the code generated by very similar instances of a control statement
appear quite different.
Please keep in mind that the examples of Fortran code generated by
'rp' are included for completeness, and are not necessarily character-for-character descriptions of the code that would be obtained from preprocessing. Rather, they are intended to
illustrate the manner in which the Ratfor statements are implemented in Fortran.

- 52-

Ratfor User's Guide

Break

Syntax:
break []
Function:
Causes an immediate exit from the referenced loop.
Example:
for

(i = length (str); i > 0; i
if (str (i) -= , 'c)
break

*
10000
10002
10003
10001

i-I )

i=length(str)
goto 10002
i=i-l
if( (Lle.O»goto 10001
if«(str(i).eq.160»goto 10003
goto 10001
goto 10000
continue

- 53 -

Ratfor User's Guide

Syntax:
do

Function:

v
initialize do
1<---------------------------------------V

1
V

false 1
* --->1

do satisfied?

reinitialize do

1 true

Example:
do i '" 1, 10
array ( i)

1----->

do 10000 i=l, 10
10000 array(i)=O

- 54 -

Ratfor User's Guide

For

Syntax:
for

([];

[];

[])

Function:

1
V

-------------->1
1

1
1
1
1

1
1

false
*
* ------>1
1
*

true

1
1

1
1
1

1
1
1
1

1
1

1
V

1
1

1
1
1

1
1
1
1

1------------------

Example:
for (i = limit - 1; i > 0; i = i - I )
array 1 (i)
array 1 (i + 1)
array-2 (i)
array=2 (i + 1)

}

{

i=limit-l
goto 10002
10000 i=i-l
10002 if((i.le.O»goto 10001
arrayl(i)=arrayl(i+l)
array2(i)=array2(i+l)
goto 10000
10001 continue

- 55 -

Ratfor User's Guide
If

Syntax:
if «condition»

Function:

true 1
--->1
1

1
1----->1
1
1

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

1
1

1 false
1
1<-----------------------------------------

Example:
if

(a == b)
c
1
d =
}

{

if «a.ne.b) )goto 10000
c=l
d=l
10000 continue

- 56 -

Ratfor User's Guide

If - Else

Syntax:
i f «condition»

else

Function:
1

true

1<----- *

1
1

false
*
* ----->1
1
*

Example:

if (i >= MAXLINE)
i
1
else
i = i + 1

if«i.1t.102»goto 10000
i=l
goto 10001
10000
i=i+1
10001 continue

- 57 -

Ratfor User's Guide
Next

Syntax:
next «levels>]
Function:
All loops nested within the loop specified by are terminated.
resumes with the next iteration of the loop specified by .
Example:

# output only strings containing no blanks
for

(i = 1; i < = L 1M IT; i = i + 1) {
for (j = 1; str (j, i) -= EOS; j
if (str (j, i) == ' 'c)
next 2
call putlin (str (1, i), STDOUT)

+ 1)

}

10000
10002
10003
10005
10006
10004
10001

i=l
goto 10002
i=i+l
if«Lgt.50»goto 10001
j=I
goto 10005
j=j+I
if«str(j,i).eq.-2»goto 10004
if( (str(j,i) .ne.I60»goto 10006
goto 10000
goto 10003
call putlin(str (I,i) ,-11)
goto 10000
continue

58 -

Execution

Ratfor User's Guide
Repeat

Syntax:
repeat

[until «condition»]
Function:
1

1<----------------V

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

1
1
1

1
1

false
1
------>1

1 true

Example:
repeat {
i = i + 1
j = j + 1
} until (str (i) 10000

"c)

i=i+1
j=j+l
if«str(i) .eq.160»goto 10000

59 -

Ratfor User's Guide
Return

Syntax:
return [ '(' when «condition 2»
when «condition 3»
-

when «condition_n»

}

[ifany
]
[else
]

- 61 -

Ratfor User's Guide
Function:

*
1
*
* true 1
1->1
* * --->1
1
I 1
*.
*
.--------------------- 1
*
*
1
* false
*

--------------------*
1
1
** true

1->
*
* --->1
1
1
*
*
*
*
*1 false

1
1
1
1
1

true 1
--->1
1

1
1->

* false
1
V

1 fal se

1
1
1

--------------------1
*
1
1 1
** * true
--->1

1->1
*
1
1 1
*
*
--------------------1
*
*
1
* false

'I
1

V
1<------------------------------------1

Example:
select
when (i == 1)
ca 11 add reco rd
when (1 == 2)
call delete record
else
call code error
goto 10001
call addreO
goto 10000
10003
call deletO
goto 10000
10001 if«i.eq.l»goto 10002
i f ( (i .eq. 2) ) goto 10003
call codeeO
10000 continue

10002

- 62 -

Ratfor User's Guide
Select «integer expression»

select «iO»
when «il.l>, , ••• )

when «i2.l>,-, ••• )

when «i3.l>,-, ••• )

when «in.1>, , ••• )

}

[ ifany
l
[el se
l

63 -

Ratfor Use r I s Guide
Function:
V

*
*
1
1
*iLl iOor ==il.2 * * true
--->1

1->1
*
1
1 1
* or
*
--------------------- 1
*
*
1
* false
1

1
1

* iO

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

i 2.1 or i 2. 2
* or
*

true 1

* ---> 1

1 1
1-> 1

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

1
1
1
1

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

* false
1
V

iO -*
i3.1 or i3.2
or
*
*

true 1
* --->1
1

1 1
1->1
1 1

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

1 false

1 false
V

1
1
* iO == * * true
---> 1

1->
* in.l or in.2
1
1 1
* or
*
--------------------1
*
*
1
*1 false

V
1<------------------------------------1

- 64 -

Ratfor User's Guide
Example:
select (i)
when (4, 6, 3003)
call add record
when (2, 12~ 5000)
call delete record
else
call code error
integer aaaaaO,aaaabO
aaaaaO=i
goto 10001
10002
call add reO
goto 10000
10003
call deletO
goto 10000
10001 aaaabO=aaaaaO-1
goto(l0003,10004,10002,10004,10002,
*
10004,10004,10004,10004,10004,
*
10003),aaaabO
if(aaaaaO.eq.3003)goto 10002
if(aaaaaO.eq.5000)goto 10003
10004 continue
10000 continue

- 65 -

Ratfor User's Guide
While

Syntax:
while «condition»

Function:
1

------------->1
V

1 true
V
---------------------

false
------>1

I
1
1
1
1
1
1

1
1

--------------------1
V
---------------

1
1
1
1
1

1-----------------V
Example:
while (str (i) i = i + 1

EOS)

10000 if«str(i).eq.-2»goto 10001

i=i+l
goto 10000
10001 continue

- 66 -

Ratfor User's Guide
Appendix B -- Linking Programs With Initialized Common
The Subsystem link procedure makes the assumption that all common
areas
are
uninitialized to allow programs to access up to 27 64K word segments of data space. A
program which uses initialized common areas requires a slightly modified link procedure to
execute correctly.
The program is also restricted to one segment (64K words) for both code
and data space.
If this limit is exceeded, no warning will be given, and unpredictable
results will occur during execution.
If more than 64K words of space is required, the common
areas must be initialized at run time, or the program cannot be run under the Subsystem.
the option string "-S 'co ab
The modification to the link procedure is as follows:
4000'" must appear on the 'ld' command line before the first binary file.
For instance,
if
the file "prog.b" contained a program with block data statements, an 'ld' command to link it
might appear as follows:
ld -s 'co ab 4000' prog.b
The executable program would be placed in the file "prog .0".

67 -

Ratfor User's Guide
Appendix C -- Requirements for Subsystem Programs
This appendix gives the technical specifications of requirements for programs that run
under the Subsystem.
It is included to allow non-Ratfor programs to run under the Subsystem.
32S and 16S addressing modes
There is no support for the execution of these addressing modes.
64R & 32R addressing modes
The 64R mode library routines cannot access the Subsystem common areas, so 32R and 64R
mode programs cannot execute under the current version of the Subsystem. However, in
the near future, this restriction will be lifted.
64V addressing mode
Segments '4035 and '4036 may not be disturbed.
When a Subsystem program is executed, the stack is already constructed
'4035.
However, the executing program may rebuild it if desired.

segment

The program must make a call to the Subsystem routine 'init' at the beginning of
execution. A "call init" is inserted automatically at the beginning of each Ratfor
main program.
The program must terminate with a call to the Subsystem routine 'swt' at the end of
its execution or its main program must return to its caller. A stop statement in Ratfor will be transformed into a ca~l to 'swt'.
The program must not tamper with any file units already open by the Subsystem.
should always use a Subsystem or Primos call to obtain an unused file unit.
The program must be in a P300 format runfile.
'seg' SHARE command.

These runfiles may be produced by the

The program must have been loaded by the modified version of the segmented loader,
'swtseg', or the entry control block for the main program must be at location '1000 in
segment '4000.
The runfile must not expect any segment other than '4000 to be initialized before
execution. Initialization of any other segment is the responsibility of the object
program.
The default load sequence produced by 'ld' will correctly link programs requiring up
to 64K words of procedure (code) and linkage (initialized local data) frames.
Up to
27 64K word segments may be used for uninitialized common blocks. Up to 64K words of
local data may be allocated on the stack.
321 addressing mode
No support is available for 321 mode programs (unless someone gives us a machirie
supports 321 mode)

- 68 -

that

Ratfor User's Guide
Appendix D -- The Subsystem Definitions
The. file n=incl=/swt_def.r.i" contains Ratfor define statements for all the symbolic
contants required to use the routines in the Subsystem support library.
This appendix
describes the more frequently used constants and the constraints placed on them.
Characters
Ascii Mnemonics. Character definitions for the Ascii control characters NUL, SOH, STX,
••• , GS, RS, US, as well as SP and DEL.
Control characters. Character definitions for the Ascii control characters CTRL AT,
CTRL A, CTRL B, ••• , CTRL LBRACK, CTRL BACKSLASH, CTRL_RBRACK, CTRL_CARET,-and
CTRCUNDERLINE.
BACKSPACE Synonym for Ascii BS.
TAB
Synonym for Ascii HT.
Synonym for Ascii BEL.
BELL
RHT
Relative horizonal tab character (used for blank compression in Primos text
fi les) •
Synonym for Ascii DEL.
RUBOUT
Data Types
Bit strings (16 bit items).
bits
Boolean (logical) values: .true. and .false. (16 bit items).
bool
character Single right-justified zero-filled character (scalar), or a string
characters terminated by an EOS (array).
file des File descriptor returned 'open', 'create', etc.
file-mark File position returned by 'seekf'.
10ngTnt
Double precision (32 bit) integer.
longreal Double precision (64 bit) floating point.
Pointer for use with dynamic storage and symbol table routines.
pointer

these

Macro Subroutines
fpchar

«packed array>, , from at
character position and increments . The first character in the
array is position zero.
spchar «packed array>, , in at
character position and increments . The first char.acter in the
array is position zero.
getc «char» Behaves exactly like 'getch', except the character is always obtained from
STDIN.
putc «char»
Behaves exactly like 'putch', except the character is always placed on
STDOUT.
SKIPBL «character array>, until the corresponding position
in the character array is non-blank.
OS DECL «ds array name>, with size .
Lanuage Extensions
ARB

Used when dimensioning array parameters in subprograms (since their length is
determined by the calling program, not the subprogram).
FALSE
Represents the Fortran logical constant .false.
IS DIGIT «char» Logical expression yielding TRUE if is a digit.
IS-LETTER «char» Logical expression yielding TRUE if is an upper or lower case
letter.
IS UPPER «char» Logical expression yielding TRUE if is an upper case letter.
IS-LOWER «char» Logical exparession yielding TRUE if is a lower case letter.
SET OF UPPER CASE Sequence of 26 character constants representing the upper case letters
for use in the when parts of select statements.
SET OF LOWER CASE Sequence of 26 character constants representing the lower case letters
for use in when parts of select statements.
SET OF LETTERS Sequence of 52 character constants representing the upper and lower case
- letters for use in when parts of select statements.
SET OF DIGITS Sequence of 10 character constants representing the digits for use in when
- parts of select statements.
SET OF CONTROL CHAR Sequence of 32 character contants representing the first 32 Ascii
control characters for use in when parts of select statements.
TRUE
Represents the Fortran logical constant .true.

- 69 -

Ratfor User's Guide
Limits
CHARS PER WORD Maximum number of packed characters per machine word.
MAXINT
-Largest 16-bit integer.
MAXARG
Maximum length of a command line argument (EOS-terminated character string).
MAXCARD
Maximum input line length (excluding the EOS).
MAXDECODE Maximum size of string processed by 'decode'.
MAXLINE
Maximum input line length.
MAXPAT
Maximum size of a pattern array.
MAXPATH
Maximum size of a Subsystem pathname.
MAXPRINT Maximum number of character that can be output by a single call to 'print'.
MAXTREE
Maximum number of characters in a Primos tree name.
MAXFNAME Maximum number of characters in a simple file name.
Standard Ports
STDIN
STDIN 1
STDIN2
ERRIN
STDIN3
STDOUT
STDOUT1
STDOUT2
ERROUT
STDOUT3

Standard
Standard
Standard
Standard
Standard
Standard
Standard
Standard
Standard
Standard

input 1.
Input 1.
input 2.
input 3.
input 3.
output 1.
output 1.
output 2.
output 3.
output 3.

Argument and Return Values
ABS
REL
DIGI'r
LETTEH
UPPER
LOWER
READ
WRITE
REArnRITE
EOF
OK
ERR
EOS
LAMBDA
YES
NO

Request absolute positioning ('seekf').
Request relative positioning ('seekf').
Character is a digit ('type').
Char?lcter is a letter (' type').
Map to upper case ('mapstr').
Map to lower case ('mapstr').
Open file for reading.
Open file for writing.
Open file for reading and writing.
End of file (guaranteed distinct from all characters and from OK and ERR).
No error (guaranteed distinct from all characters and from EOF and ERR).
Error occurred (guaranteed distinct from all characters and from EOF and OK).
End of string (guaranteed distinct from all characters).
Null pointer (guaranteed distinct from all pointer values).
Affirmative response (guaranteed ~istinct from NO).
Negative response (guaranteed distinct from YES).

70 -

Ratfor User's Guide
Appendix E -- 'Rp' Reserved Words

The following
identifiers are reserved keywords in Ratfor and cannot be used as
identifiers.
'Rp' will not diagnose the use of reserved keywords as identifiers; results of
misuse will be unreasonable behavior such as misleading error messages and mis-ordered
Fortran code.
blockdata
break
call
case
common
complex
continue
data
define
dimension
do
doubleprecision
else
end
equivalence
external
for
forward
function
goto
if
ifany
implicit
incl ude
integer

linkage
local
logical
next
parameter
procedure
real
recursive
repeat
return
save
select
shortcall
stackheader
stmtfunc
stop
string
stringtable
subroutine
trace
undefine
until
when
while

- 71 -

Software Tools Text Formatter
User's Guide

Pe r r y B. Fl inn

School of Information and Computer Science
Georgia Institute of Technology
Atlanta, Georgia 30332
March, 1980

TABLE OF CONTENTS

Basics •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Usage .......................................................................................................... .

Commands and Text •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Filling and Margin Adjustment ••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Filled Text •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Hyphenation •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Ma rg in Ad j us tm en t •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Centering •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Sentence Punctuation ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Filling and Margin Adjustment •••••••••••••••••••••••••••••••••••••••••••

1
1
2
3
3

Spacing and Page Control •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Line Spa c i ng ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Page Division •••••••••••••••••••••••••••••••••••••.•••••••••••••••••••••••••••••••
'No-space' Mode •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Spacing and Page Control ••••••••••••••••••••••••••••••••••••••••••••••••

3
3
4
4
5

Margins and Indentation ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Margins •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Top and Bottom Marg ins ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Left and Right Marg ins ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Indentation •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Page Offset ••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••.•••••••••••
Marg in Characters •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Margins and Indentation •••••••••••••••••••••••••••••••••••••••••••••••••

5
5
5

Beadings, Footings and Titles ••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Three Pa rt Ti tIes •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Page Headings and Footings ••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Headings, Footings and Titles •••••••••••••••••••••••••••••••••••••••••••

6
6
6
6

7
7
7

Tabulation •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Ta bs ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Tabulation ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

9
9
10

Mi scellaneous Commands •••••••.•.•••••.•••••••••••••••••••••••••••••••••.•..••••••••••
Comments ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Boldfacing and Underl ining ••••••••••••••••••••••••••.••••••••••••••••••.••••••••••
Control Characters ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Prompting •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Premature Termination •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Miscellaneous Commands ••••••••••••••••••••••••••••••••••••••••••••••••••

10
10
10
11
11
12
12

Input Processing ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••
Input File Control ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Functions, Variables and Special Characters •••••••••••••••••••••••••••••••••••••••
Number Reg iste rs ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Functions .•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Variables •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Special Characters ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Summary - Input Processing ••••••••••••••••••••••••••••••••••••••.•••••••••••••••••

12
12
13
13
14
14
14
15

Mac ros •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Macro Definition ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Macro Invocation
Summary - Macros

15
15
16
16

Applications Notes ••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••
paragraphs ••••••.••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••
Sub-headings •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••
Quotations ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
Italics ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••
Boldfacing ••••••••••••••••••••••••••.••••••••••••••••••••••••••••••••••..•••••••••
Exampl es •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••.•••
Table Constr uct ion •••••••••••••••••••••••••••••••••••••••••••••••••••••.••••••••••

17
17
17
17
18
18
18
18
19

Summary of Command. Sorted Alphabetically ....•......................................•

Major Headings •••••••••••••••••...•••••••••••••••••••••••••.•.•••••••••.••••••••••

iii

Foreword

'Fmt'
is a program designed to facilitate the preparation of neatly formatted text.
It
provides many features, such as automatic margin alignment, paragraph indentation, hyphenation and pagination, that are designed to greatly ease an otherwise tedious job.
It is the intent of this guide to familiarize the user with the principles of automatic
text formatting in general and with the capabilities and usage of 'fmt' in particular.

- iv -

Text Formatter User's Guide
Basics
Usage
'Fmt' takes as input a file containing text with interspersed formatting
instructions.
It is invoked by a command with various optional parameters, discussed below.
The resultant
output is appropriately formatted text suitable for
a
printer
having
backspacing
capabilities.
The output of 'fmt' is made available on its first standard output port, and
so may be placed in a file, sent to a line printer, or changed in any of a number of ways,
simply by applying standard Software Tools Subsystem I/O redirection.
When 'fmt' is invoked from the Subsystem, there are several optional parameters that may
be specified to control its operation.
The full command line syntax is
fm t

[

-s ]

-p[-] 1 1 }

A brief explanation of the cryptic notation:
the items enclosed within square brackets
("[]") are optional -- they mayor may not be specified; items enclosed between braces ("{}")
may occur any number of times, including
zero;
items enclosed in angle brackets
("<>")
designate character strings whose significance is suggested by the text within the brackets;
everything else should be taken literally.
And now for an explanation of what these parameters mean:

-s

If this option is selected, 'fmt' will pause at the top of each page, ring the bell
or buzzer on your terminal, and wait for a
response.
This feature
is for
the
benefit of people using hard-copy terminals with paper not having pin-feed margins.
The correct response,
to be entered after the paper is mounted, is a control-c
(hold the 'control' key down and type 'c').

-p •••

This option allows selection of which pages of the formatted document will actually
be printed.
Immediately following the "_pH, without any inte.rvening spaces, should
be a number indicating the first page to be printed.
Following this, a second number may be specified, separated from the first by a single dash, which indicates
the last page to be printed.
I f this second number is omitted, all remaining pages
will be produced.

Any number of file names may be specified on the command line.
'Fmt' will open the
files
in turn, formatting the contents of each one as if they constituted one big
file.
When the last named fi Ie is processed, 'fmt' terminates.
If no file
names
are specified, standard input number one is used.
In addition, standard input may
be specified explicitly on the command line by using a dash as a file name.

Commands and Text
'Fmt', like almost every other text formatter ever written, operates on an input stream
that consists of a mixture of text and formatting commands.
Each command starts at the
beginning of a line with a 'control character', usually a period, followed by a two character
name, in turn followed by some optional 'parameters'.
There must not be anything else on the
1 ine.
For example, in
.ta 11 21 31 41
the control character is a period, the command name is ta, and there are four
parameters:
"11",
"21",
"31"
and "41".
Notice that the command name and all the parameters must be
separated from each other by one or more blanks. Anything not recognizable as a command is
treated as text.

Filling and Margin Adjustment
Filled Text
'Fmt' collects as many words as will fit on a single output line before actually writing
it out,
regardless of line boundaries in its input stream.
This is called 'filling' and is
stannard practice for 'fmt'.
It can, however, be turned off with the 'no-fill' command
.nf
and lines thenceforth will be copied from input to output unaltered.
filling back on again, you may do so with the 'fill' command

1 -

When you want

turn

Text Formatter User's Guide
.fi
and 'fmt' will resume its normal behavior.
If there is a partially filled line that has not yet been written out when an nf command
is encountered, the line is forced out before any other action is taken.
This phenomenon of
forcing out a partially filled line is known as a 'break' and occurs implicitly with many
formatting commands.
To cause one explicitly, the 'break' command
.br
is available.
Hyphenation
If, while filling an output line, it is discovered that the next word will not fit, an
attempt is made to hyphenate it. Although 'fmt' is usually quite good in its cho.ice of where
to split a word, it occasionally makes a gaffe or two, giving reason to want to turn the
feature off.
Automatic hyphenation can be disabled with the 'no-hyphenation' command
.nh
long enough
command

for a troublesome word to be processed, and then reenabled with the. 'hyphenate'

.hy
Neither command causes a break.
Margin Adjustment
After filling an output line, 'fmt' inserts extra blanks between words so that the last
word on the line is flush with the right margin, gIVIng the text a "professional" appearance.
This is one of several margin adjustment modes that can be selected with the 'adjust' command
.ad
The optional parameter may be anyone of four single characters: "b", "c", "I" or
"r".
If the parameter is "b" or missing, normal behavior will prevail -- both margins will
be made even by inserting extra blanks between words.
This is the default margin adjustment
mode.
If "c" is specified, lines will be shifted to the right so that they are centered
between the left and
right margins.
If the parameter is "1", no adjustment will be performed; the line will start at the left margin and the right margin will be ragged.
If "r"
is specified, lines will be moved to the right so that the right margin is even, leaving the
left margin ragged.
The 'no-adjustment' command
.na
has exactly the same effect as the following 'adjust' command:
.ad 1
No adjustment will be performed, leaving the left margin even and the
In no case does a change in the adjustment mode cause a break.

right

margin

ragged.

Centering
Input lines may be centered, without filling, with the help of the 'center' command
.ce N
The optional parameter N is the number of subsequent input lines to be centered between the
left and right margins.
If the parameter is omitted, only the next line of input text is
centered.
Typically, one would specify a large number, say 1000, to avoid having to count
lines; then, immediately following the lines to be centered, give a 'center' command with an
parameter of zero.
For example:

2 -

Text Formatter User's Guide
.ce 1000
more lines
than I care
to count
.ce 0
It is worth noting the difference between
.ce
and
.ad c
When the former
is used, an implicit break occurs before each line is printed, preventing
filling of the centered lines; when the latter is used, each line is filled with as many
words as possible before centering takes place.
Sentence Punctuation
By default,
'fmt' adds an extra blank after punctuation at the end of a sentence;
specifically, after periods, colons, exclamation points and question marks.
This may not be
desirable, particularly when abbreviations or a person's initials are involved. Thus, it can
be turned on and off at will. The 'single-blank' command
.sb
turns the mode off, while the 'extra-blank' command
.xb
turns it back on again.

As with hyphenation, neither command causes a break.

Summary - Filling and Margin Adjustment
Command
Syntax

Initial
Value

If no
Cause
Parameter Break

Explanation

• ad

lib"

"b"

Set margin adjustment mode •

yes

Force a break •

yes

Center N input text lines •

• br
• ce N

N=O

N=l

•f i

Turn on fill mode •

.hy

Turn on automatic hyphenation.

• na

Turn off margin adjustment •

• nf

yes

Turn off fill mode •

• nh

Turn off automatic hyphenation •

(Also inhibits adjustment.)

.sb

off

Single blank after end of sentence.

• xb

Extra blank after end of sentence •

Spacing and Page Control
Line Spacing
'Fmt'
usually produces single-spaced output, but this can be changed, without a break,
using the 'line-spacing' command
.ls N
The parameter N specifies how many lines on the page a single line of text will use; for
double spacing, N would be two.
If N is omitted, the default (single) spacing is reinstated.
-

3 -

Text Formatter User's Guide
Blank lines may be produced with the 'space' command
.sp N
The parameter N is the number of blank lines to produce; if omitted, a value of one is
assumed. The sp command first causes a break; this not only causes a partially filled line
to be output, but if the current line spacing is more than one, the break will cause the
extra blank lines to be output as well. Then the blank lines generated by sp are output.
Thus, if output is being double-spaced and the command
.sp 3
is given, four blank lines will be generated: one from the double-spacing that is in effect,
and three from the sp command.
If the value of N calls for more blank lines than there are
remaining on the current page, any extra ones are discarded. This ensures that, normally,
each page begins at the same distance from the top of the paper.
Page Division

'Fmt'
automatically divides its output into pages, leaving adequate room at the top and
bottom of each page for running headings and footings.
There are several commands that
facilitate the control of page divisions when the normal behavior is inadequate.
The 'begin-page' command
.bp +N
causes a break and a skip to the top of the next page.
If a parameter is given, it serves to
alter the page number and so it must be numeric with an optional plus or minus sign.
If the
parameter is omitted, the page number is incremented by one.
If the command occurs at the
top of a page before any text has been printed on it, the command is· ignored, except perhaps
to set the page number. This is to prevent the random occurrence of blank pages.
The optionally signed numeric parameter is a form of parameter used by many formatting
commands. When the sign is omitted, it indicates an absolute value to be used; when the sign
is present, it indicates an amount to be added to or subtracted from the current value.
The page number
number' command
.pn

may

be set independently of the 'begin-page' command with the 'page-

The next page after the current one, when and if it occurs, will be numbered +N.
caused.

No break is

The length of each page produced by 'fmt' is normally 66 lines. This is standard for
eleven inch paper printed at six lines per inch.
However, if non-standard paper is used, the
printed length of the page may easily be changed with the 'page-length' command
.pl +N
which will set the length of the page to

lines without causing a break.

Finally, if it is necessary to be sure of having enough room on a page, say for a figure
or a graph, use the 'need' command
.ne N
'Fmt'
will cause a
will do nothing more.
be adequate room.

break, check if there are N lines left on the current page and, if so,
Otherwise, it will skip to the top of the next page where there should

')Io-space' Mode
'No-space' mode is a feature that assists in preventing unwanted blank lines from
appearing,
usually at the top of a page. When in effect, certain commands that cause blank
lines to be generated, such as bp, ne and sp, are suppressed. For the most part,
'no-space'
mode is managed automatically; it is turned on automatically at the top of each page before
the first text has appeared, and turned off again automatically when a line of output is
generated.
This accounts for the suppression of bp commands at the top of a page and the
discarding of excess blank lines in sp commands.
'No-space' mode may be turned on explicitly with the 'no-space' command

- 4 -

Text Formatter User's Guide
.ns
and turned off explicitly with the 'restore-spacing' command
.rs
Neither command causes a break.
Summary - Spacing and Page Control
Command
Syntax

Initial
Value

Cause
If no
Parameter Break

.bp +N

N=l

yes

Begin a new page.

.1 s N

N=l

yes

Set line spacing.

N=l

yes

Express a need for N contiguous lines.

Turn on 'no-space' mode.

.ne N

Explanation

.ns

.pl +N

N=66

Set page length.

.pn +N

N=l

ignored

Set page number.

Turn off 'no-space' mode •

yes

Put out N blank lines.

. rs
N=l

.sp .N

Margins and Indentation
Margins
All formatting operations are performed within the framework of a page whose size is
defined by four margins: top, bottom, left and right. The top and bottom margins determine
the number of lines that are left blank at the top and bottom of each page.
Likewise, the
left and right margins determine the first and last columns across the page into which text
may be placed.
Top and Bottom Margins
Both the top and the bottom margins consist
the header and footer lines. For the sake of
the top margin will be referred to as 'margin I'
sub-margins of the bottom margin, 'margin 3' and

of two sub-margins that fix the location of
clarity, the first and second sub-margins of
and 'margin 2', and the first and second
'margin 4'.

The value of margin 1 is the number of lines to skip at the top of each page before the
header line, plus one. Thus, margin 1 includes the header line and all the blank lines
preceding i t from the top of the paper. By default, its value is three. Margin 2 is the
number of blank lines that are to appear between the header line and the first text on the
page.
Normally, it has a value of two. The two together form a standard top margin of five
lines, with the header line right in the middle.
It is easy enough to change these defaults
if they prove unsatisfactory; just use the 'margin-I' and 'margin-2' commands
.ml +N
.m2 +N
to set either or both sub-margins to

~N.

The bottom margin is completely analogous to the top margin, with margin 3 being the
number of blank lines between the last text on a page and the footer line, and margin 4 being
the number of lines from the footer to the bottom of the paper (including the footer).
They
may be set using the 'margin-3' and 'margin-4' commands
.m3 +N
.m4 +N
which work just like their counterparts in the top margin1 none cause a break.

5 -

Text Formatter User's Guide
Left and Right Margins
The left and right margins define the first and last columns into which text may be
printed. They affect such things as adjustment and centering. The left margin is normally
set at column one, though this is easily changed with the 'left-margin' command
.lm +N
The right margin, which is normally positioned in column sixty, can be set similarly with the
'right-margin' command
.rm +N
To ensure that the new margins apply only to subsequent text, each command causes a break
before changing the margin value.
Indentation
It is often desirable to change the effective value of the left margin for
indentation,
without actually changing the margin itself.
For instance, all of the examples in this guide
are indented from the left margin in order to set them apart from the rest of the text.
Indentation is easily arranged using the 'indent' command,
.in +N
whose parameter specifies the number of columns to indent from the left margin.
indentation value, and the one assumed if no parameter is given, is zero (i.e.
left margin).

The initial
start in the

For the purpose of margin adjustment, the current indentation value is added to the left
margin value to obtain the effective left margin.
In this respect, the 1m and in commands
are quite similar.
But, whereas the left margin value affects the placement of centered
lines produced by the ce command, indentation is completely ignored when lines are centered.
Paragraph indentation poses a sticky problem in that the indentation must be applied
only to the first line of the paragraph, and then normal margins must be resumed. This can't
be done conveniently with the 'indent' command, since it causes a break. Therefore, 'fmt'
has a 'temporary-indent' command
.ti +N
whose function is to cause a break, alter the current indentation value by +N until the next
line of text is produced, and then reset the indentation to its previous value.
So to begin
a new paragraph with a five column indentation, one would say
.ti +5

Page Offset
As if control over the left margin position and indentation were not enough, there is
yet a third means for controlling the position of text on the page. The concept of a page
offset involves nothing more than prepending a number of blanks to each and every line of
output.
It is primarily intended to allow output to be easily positioned on the paper
without having to adjust margins and indentation (with all their attendant side effects)
and
without having to physically move the paper. Although the page offset is initially zero,
other arrangements may be made with the 'page-offset' command
.po +N
which causes a break.
Margin Characters
It is common practice in the revision of technical literature to indicate parts of the
text that are different from previous versions of the same document. Such changes are
usually indicated by "revision bars" which are vertical lines in the left margin of lines
that are new or revised.
'Fmt' provides for this capability with two formatting commands.
The imargin-offset' command,
.mo +N
without causing a break, specifies that +N columns are to

- 6 -

reserved

between

the

'page-

Text Formatter User's Guide
offset' columns and the 'left-margin' column for revision bars or other marginal characters.
The margin offset starts out at zero, and reverts to that value if no parameter is specified.
Once a non-zero margin offset has been set, any arbitrary character may be placed in the
leftmost column of the area with the 'margin-character' command:
.mc
Initially, and when is omitted, this character has blank as its value.
For revision
bars, would be specified as "I". Whatever character is specified, it is placed next
to the left margin on every line of output as long as the margin offset is non-zero.
Summary - Margins and Indentation
Command
Syntax

Initial
Value

If no
Cause
Parameter Break

Explanation

• in +N

N=O

yes

Indent left margin.

• lm +N

N=l

yes

Set left marg in •

.ml +N

N=3

Set top margin before and including page heading.

.m2 +N

N=2

Set top margin after page heading.

• m3 +N

N=2

Set bottom margin before page footing •

.m4 +N

N=3

Set bottom margin including and after page footing.

.mc

BLANK

Set margin character.

.mo +N

N=O

Set margin offset.

.po +N

N=O

yes

Set page offset.

.rm +N

N=60

yes

Set right margin.

.ti +N

N=O

yes

Temporarily indent left margin.

Headings, Footings and Titles
Three Part Titles
A three part title is a line of output consisting of three segments.
The first segment
is left-justified,
the second is centered between the left and right margins, and the third
is right-justified. For example

left part

center part

right part

is a three part title whose first segment is "left part", whose
part", and whose third segment is "right part".
To generate
available:

title

the

current

position

second

segment

"center

the page, the 'title' command is

.tl /left part/center part/right part/
In fact, this command was used to generate the previous example.
The parameter to the title
command is made up of the text of the three parts, with each segment enclosed within a pair
of delimiter characters. Here, the delimiter is a slash, but any other character may be used
as long as it is used consistently within the same command.
If one or more segments are to
be omitted, indicate this with two adjacent delimiters at the desired position. Thus,
• t1 / / /Pag e 1/

specifies only the third segment and would produce something like this:
Page 1
It is not necessary to include the trailing delimiters.
- 7 -

Text Formatter User's Guide
To facilitate page numbering, you may include the sharp character ("i") anywhere in the
text of the title; when the command is actually performed, 'fmt' will replace all occurrences
of the "in with the current page number. To produce a literal sharp character in the title,
it should be preceded by an "@"

@i
so that it loses its special meaning.
The first segment of a title always starts at the left margin as specified by the 1m
command. While the third segment normally ends at the right margin as specified by the rm
command, this can be changed with the 'length-of-title' command:
.It +N
which changes the length of subsequent titles to +N, still beginning at the left margin.
Note that the title length is automatically set by the 1m and rm commands to coincide with
the distance between the left and right margins.
Page Headings and Footings

The most common uses for three part titles are page headings and footings.
and footer lines are initially blank.
Either one or both may be set at any time,
break, by using the 'header' command

The header
without a

.he /left/center/right/
to set the page heading, and the 'footer' command
.fo /left/center/right/
to set the page footing~ The change will become manifest the next time the top or the bottom
of a page is reached. As with the tl command, the "in may be used to access the current page
number.
It
is often desirable when producing text to be printed on both sides of a page to have
different headings and footings on odd- and even-numbered pages. Although the he and fo commands affect the headings and footings on all pages, it is possible to set up independent
headings and footings for odd- and even-numbered pages.
For odd-numbered pages, the 'oddheader' and 'odd-footer' commands are available:

.oh /left/center/right/
.of /left/center/right/
while the 'even-header' and 'even-footer' commands are provided for even-numbered pages:
.eh /left/center/right/
.ef /left/center/right/
As an illustration, the following commands were
footings for this guide:
.eh /Text Formatter User's Guide///
.oh ///Text Formatter User's Guide/
.fo //- i -II

- 8 -

used

generate

the

page

headings

and

Text Formatter User's Guide
Summary - Beadings, Footings and Titles
Command
Syntax

Initial
Value

If no
Cause
Parameter Break

Explanation

.e f

IIlclrl

blank

Set even-numbered page footing.

.eh

IIlclrl

blank

Set even-numbered page heading.

.fo

Illclrl

blank

Set running page footing.

.he

Illclrl

blank

Set running page heading.

N=60

Set length of header, footer and titles.

.1 t +N
.of

Illclrl

blank

Set odd-numbered page footing.

.oh

Illclrl

blank

Set odd-numbered page heading.

.tl

Illclrl

blank

yes

Generate a three part title.

Tabulation
Tabs
Just like any good typewriter, 'fmt' has facilities for tabulation. When it encounters
a special character in its input called the 'tab character' (analogous to the TAB key on a
typewriter),
it automatically advances to the next output column in which a 'tab stop' has
been previously set. Tab stops are always measured from the effective left margin, that is,
the left margin plus the current indentation or temporary indentation value. Whatever column
the left margin may actually be in, it is always assumed to be column one for the purpose of
tabulation.
Originally, a tab stop is set in every eighth column, starting with column
may be changed using the 'tab' command

nine.

This

.ta •••
Each parameter specified must be a number, and causes a tab stop to be set in the corresponding output column. All existing stops are cleared before setting the new ones, and a stop is
set in every column beyond the last one specified. This means that if no columns are
specified, a stop is set in every column.
By default, 'fmt' recognizes the ASCII TAB, control-i, as the
'tab character'.
But
since this is an invisible character and is guaranteed to be interpreted differently by
different terminals, it can be changed to any character with the 'tab-character' command:
.tc
While there is no restriction on what particular character is specified for
wise to choose one that doesn't occur too frequently elsewhere in the text.
parameter, the tab character reverts to the default.

If you omit the

When 'fmt' expands a tab character, it normally puts out enough blanks to get to the
next tab stop.
In other words, the default 'replacement' character is the blank. This too
may easily be changed with the 'replacement-character' command:
.rc
As with the tc command, may be any single character.

If omitted, the default is used.

A common alternate replacement character is the period, which is frequently used
tables of contents. The following example illustrates how one might be constructed:

- 9 -

Text Formatter User's Guide
.ta 52
.tc \
Section Name\Page
.rc
.sp
.nf
.ta 53
Basics\l
Filling and Margin Adjustment\2
Spacing and Page Contro1\5
.sp
.fi
The result should look about like this:
Sect ion Name

Page

Basics •••••••••••••.•••••••••••••••••••••••••••••••• 1
Filling and Margin Adjustment ••••••••••••••••••••••• 2
Spacing and Page Control .••••••••••••••••.•••••••••• 5
Since the default replacement character is a blank you might
A final word on tabs:
think that, in the process of adjusting margins (i.e., when the adjustment mode is "b"),
'fmt' might throw in extra blanks between words that were separated by the tab character.
Since this is definitely not the expected or desired behavior, 'fmt' uses what is called a
"phantom blank" as the--aefau1t replacement character.
The phantom blank prints as an
ordinary blank, but is not recognized as one during margin adjustment.
Summary - Tabulation
Command
Syntax

Initial
Value

If no
Cause
Parameter Break

Explanation

.ta N

9 17

all

Set tab stops.

.tc c

TAB

Set tab character.

.rc c

BLANK

Set tab replacement character.

Miscellaneous Commands
Comments
It is rare that a document survives its writing under the pen of just one author or
editor. More frequently, several different people are likely to put in their two cents worth
concerning its format or content.
So, if the author is particularly attached to something he
has written, he is well advised to say so. Comments are an ideal vehicle for this purpose
arid are easily introduced with the 'comment' command

The parameter , which may be any single character, becomes the new control character.
If the parameter is omitted, the familiar period is reinstated.
It has been shown that many commands automatically cause a break before they perform
their function.
When this presents a problem, it can be altered.
If instead of using the
ba.sic control character the 'no-break' control character is used to introduce a command, the
automatic break that would normally result is suppressed.
The standard no-break control
character is the grave accent ("'"), but may easily be changed with the following command:

.c2
As with the cc command, the parameter may be any single character, or may be omitted
default value is desired.

the

Prompting
Brief, one-line
'prompt' command

messages

may

written

directly

to the user's terminal using the

.er
The text that is actually written to the terminal starts with the first non-blank character
following the command name, and continues up to, but not including, the next newline character.
If a newline character should be included in the message, the escape sequence

@n
may be used.
Leading blanks may also be included in the message by preceding the message
with a quote or an apostrophe.
'Prot' will discard this character, but will then print the
rest of the message verbatim. For instance,
.er '

this is a message with 10 leading blanks

would write the following text on the terminal, leaving the cursor or carriage at the end
the message
this is a message with 10 leading blanks
For a multiple-line message, try
- 11 -

Text Formatter User's Guide
.er multiple@nline@nmessage@n
The output should look like this:
mUltiple
line
message
Prompts are particularly useful in form letter applications where there may be several
pieces of information that 'fmt' has to ask for in the course of its work.
The next section
describes how 'fmt' can dynamically obtain information from the user.
Premature Termination
If 'fmt' should ever encounter an 'exit' command
.ex
in the course of doing its job, it will cause a break and exit immediately to the Subsystem.
Summary - Miscellaneous Commands
Command
Syntax

Initial
Value

If no
Cause
Parameter Break

Explanation

Introduce a comment.

Boldface N input text lines.

.c2 c

Set no-break control character.

• cc c

Set basic control character •

Write a message to the terminal .

yes

Exit immediately to the Subsystem.

Underline N input text lines.

.bf N

N=O

• er text

N=l

ignored

.ex

N=O

.ul N

N=l

Input Processing
Input File Control
Up to this point, it has been assumed that 'fmt' reads only from its standard input file
or
from
files
specified as parameters on the command line.
It is also possible to
dynamically include the contents of any file in the midst of formatting another.
This aids
greatly in the modularization of large, otherwise unwieldy documents, or in the definition of
frequently used sequences of commands and text.
The 'source' command is available to dynamically include the contents of a file:
.so
The parameter
is mandatory; it may be an arbitrary file system pathname, or, as with
file names on the command line, a single dash ("-") to specify standard input number one.
The effect of a 'source' command is to temporarily preempt the current input source and
begin reading from the named file.
When the end of that file is reached, the original source
of
input
is resumed.
Files
included with 'source' commands may themselves contain other
'source' commands; in fact, this 'nesting' of input files may be carried out to virtually any
depth.
'Fmt' provides one additional command for manipulating input
command

files.

The

'next

file'

.nx
may

used for either one of two purposes.

If you specify a parameter, all current

- 12 -

Text Formatter User's Guide
input files are closed (including those opened with so commands), and the named file becomes
the new input source.
You can use this for repeatedly processing the same file, as, for
example, with a form letter.
If you omit the parameter, 'fmt' still closes all of its
current input files. But instead of using a file name you supply with the nx command,
it
uses the next file named on the command line that invoked 'fmt'.
If there is no next file,
then formatting terminates normally.
Neither the so command nor the nx command causes a break.
Functions, Variables and Special Characters
Whenever 'fmt' reads a line of input, no matter what the source may be, there is a
certain amount of 'pre-processing' done before any other formatting operations take place.
This pre-processing consists of the interpretation of 'functions', 'variables' and 'special
characters'.
A 'function'
is a predefined set of actions that produces a textual result,
possibly based on some user supplied textual input. For example, one hypothetical function
might be named 'time', and its result might be a textual representation of the current time
of day:
17:22:43

A 'variable' is simply one of 'fmt's internal parameters, such as the current page length or
the current line-spacing value; the name of each variable is the same as the two-character
name of the corresponding command to set the value of that parameter.
The result of a
variable is just a textual representation of that value.
A 'special character' is like a function or variable, but its result is a single character that cannot be conveniently generated from the keyboard.

From the standpoint of a user, functions, variables and special characters are all very
similar.
In fact, they are invoked identically by enclosing the appropriate name, plus any
text to be used as arguments, in square brackets:
[bf This text to be boldfaced]
[Is]
[alpha 5]
Such a construct is known as a "function call."
When 'fmt' sees a function call in an input line, it excises everything in between the
brackets, including the brackets themselves, and inserts the results in its place.
Naturally, anything not recognizable is left alone.
If by chance you want the name of a
function, variable or special character enclosed in square brackets included literally as
part of the text, you can inhibit evaluation by preceding the left bracket with the escape
character:
@[time]
It is also possible to nnest" function calls so that the
arguments to another:

results

one

may

used

[bf [ldate]]

Number Registers
The
'number registers'
are a group of 64 accumulators (numbered 1-64) on which simple
arithmetic operations may be performed. They find their greatest use in the preparation of
documents with numbered sections and paragraphs.
Number registers are accessed and
manipulated by a special set of functions.
The 'set' function
[set reg value]
assigns the integer 'value' to the register 'reg' and yields the empty string as its
The 'add' function

result.

[add reg value]
adds the integer 'value'
(which, by the way may be positive or negative) to the register
'reg'. This function too yields an empty result.
Finally, the 'num' function
[num reg]
yields the current value of the register 'reg' as its result.
- 13 -

In addition, 'reg' may

either

Text Formatter User's Guide
be prefixed or postfixed by a plus or minus sign.
If the sign appears before the register
humber, the register is incremented or decremented (according to the sign) by one before the
function's result is yielded.
If the sign follows the register number, though, the
register's current value is yielded and then the register is incremented or decremented.
Functions
The following table summarizes the available functions:
add
bf
cu
date
day
ldate
num
RN

rn
set
sub
sup
time
ul

Add constant to number register
Boldface the arguments on output
Output the arguments with a continuous underline
Current date; e.g., 04/30/80
Current day of the week; e.g., Wednesday
Current date: e.g., April 30, 1980
Output value of number register with optional pre- or post-inc.rementation
decrementation
Convert the argument to a lower-case Roman numeral
Convert the argument to an upper-case Roman numeral
Set number reg ister to value
Output the arguments as a subscript (requires post-processor)
OUtput the arguments as a superscript (requires post-processor)
Current time of day; e.g., 17:22:45
Underline the arguments on output

variables
The formatting parameters
marized in the following table:
cc
c2
in
1m
In
Is
ml
ml
m2
m3
m4
pI
pn
po
rm
tc
ti
tcpn

Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current
Current

whose

values are available through function calls are sum-·

basic control character
no-break control character
indentation value
left margin value
line number on the page
line-spacing value
macro invocation level
margin 1 value
margin 2 value
margin 3 value
margln 4 value
page length value
page number
page offset value
right margin value
tab character
temporary indentation value
page number, right justified in 4 character field

Special Characters
The following table summarizes the available special characters.
In each case, a
positive integer may be included as an argument following the name to produce multiple
instances of the character. For example, "[bl 5]" yields five contiguous phantom blanks.
NOTE:
in order for the Greek letters and mathematical symbols to be printed correctly, a
post-processor such as 'dprint' (see Section 3 of the Software Tools Subsystem Reference
Manual) and/or special printing equipment is required.
bl
bs
al pha
beta
delta
DELTA
epsilon
eta
gamma
GAMMA
inEini ty
integral
lambda
LAMBDA
mu

Phantom blank
Backspace
Lower-case Greek
Lower-case Greek
Lower-case Greek
Upper-case Greek
Lower-case Greek
Lower-case Greek
Lower-case Greek
Upper-case Greek
Infinity symbol
Integral symbol
Lower-case Greek
Upper-case Greek
Lower-case Greek

alpha
beta
delta
delta
epsilon
eta
gamma
gamma
lambda
lambda
mu

Text Formatter User's Guide
nabla
not
nu
omega
OMEGA
partial
phi
~I

psi
~I

pi
PI
rho
sigma
SIGMA
tau
theta
THETA
xi
zeta

Upside-down upper-case Greek delta (APL "DELn)
Not symbol
Lower-case Greek nu
Lower-case Greek omega
Upper-case Greek omega
Partial derivative symbol
Lower-case Greek phi
Upper-case Greek phi
Lower-case Greek psi
Upper-case Greek psi
Lower-case Greek pi
Upper-case Greek pi
Lower-case Greek rho
Lower-case Greek sigma
Upper-case Greek sigma
Lower-case Greek tau
Lower-case Greek theta
Upper-case Greek theta
Lower-case Greek xi
Lower-case Greek zeta

Summary - Input Processing
If no
Cause
Parameter Break

Explanation

• nx file

next arg

Move on to the next input file •

.so file

ignored

Temporarily alter the input source.

Command
Syntax

Initial
Value

Macros
Macro Definition
A macro is nothing more than a frequently used sequence of commands and/or text that
have been grouped together under a single name.
This name may then be used just like an
ordinary command to invoke the whole group in one fell swoop.
The definition (or redefinition) of a macro starts with a 'define' command
.de xx
whose parameter is a one or two character string that becomes the name of the macro. The
macro name may consist of any characters other than blanks, tabs or newlinesi upper and lower
letters. are distinct. The definition of the macro continues until a matching 'end' command
.en xx
is encountered. Anything may appear within a macro definition,
including other macro
definitions.
The only processing that is done during definition is the interpretation of
variables and functions (i.e. things surrounded by square brackets). Other than this, lines
are stored exactly as they are read from the input source. To include a function call in the
definition of a macro so that its interpretation will be delayed until the macro is invoked,
the opening bracket should be preceded by the escape character "@".
~r example,

.f tm --- time of day
.de tm
@[time]
.en tm
would produce the current time of day when invoked, whereas

.f tm --- time of day
.de tm
[time]
.en tm
would produce the time at which the macro definition was processed.

- 15 -

Text Formatter User's Guide
Macro Invocation
Again, a macro is invoked like an ordinary command: a control character at the beginning of the line immediately followed by the name of the macro.
So to invoke the above
'time-of-day' macro, one might say
.tm
As with ordinary commands, macros may have parameters.
In fact, anything typed on the
line after the macro name is available to the contents of the macro.
As usual, blanks and
tabs serve to separate parameters from each other and from the macro name.
If it is necessary to include a blank or a tab within a parameter, it may be enclosed in quotes.
Thus,
"parameter one"
would constitute a single parameter and would be passed to the macro as
parameter one
To include an actual quotation mark within
adjacent to each other.
For instance,

the

parameter,

type

two

quotes

immediately

"""quoted string"""
would be passed to the macro as the single parameter
"quoted string"
Within the macro, parameters are accessed in a way similar to functions and variables:
the number of the desired parameter is enclosed is square brackets.
Thus,
[l]

would retrieve the first parameter,
[2]

would fetch the second, and so on.
accessed with

As a special case,. the name of the macro

itself

may

[0]

Assume there is a macro named "mx" defined as follows:

.J mx --- macro example
.de mx
Macro named' [0] " invoked with two arguments:
'[I]' and '[2]' •
• en mx
Then, t ypi ng
.mx "param I" "param 2"
would produce the same result as typing
Macro named 'mx', invoked with two arguments:
'param I' and 'param 2'.
Macros
such ted ious
section in
notes in the

are quite handy for such common operations as starting a new paragraph, or for
tasks as the construction of tables like the ones appearing at the end of each
this guide.
For some examples of frequently used macros, see the applications
following pages.

Summary - Macros
Command
Syntax

Inl tial
Value

If no
Cause
Parameter Break

Explanation

.de xx

ignored

Begin definition or redefinition of a macro.

.en xx

ignored

End macro definition.
-

16 -

Text Formatter User's Guide
Applications Notes
This section will illustrate the capabilities of 'fmt' with some actual applications.
Most of the examples are macros that assist in common formatting operations, but attention
has also been given to table construction. All of the macros presented here are available
for general use in the file '/extra/fmacro/report', which may be named on the command line
invoking 'fmt' or may be included with a 'source' command as follows:
.so =fmac=/report

Paragraphs
One standard way of beg inning a new paragraph is to skip a "line and indent by a few
spaces, as was dOone throughout this guide.
This can be done by giving an sp command followed
by a ti command. A better way is to define a macro. This allows procrastination on deciding
the format of paragraphs and facilitates change at some later date without a major editing
effort.
Here is the paragraph macro used in this document:

.t pp
.de
.sp
.ne
.ti
.ti
.ns
.en

begin paragraph

pp
2
@[in]
+5

First a line is skipped via the 'space' command. Then, after checking that there is room on
the current page for the first two lines of the new paragraph, a temporary indentation is set
up that is five columns to the rignt of the running indentation with the two ti commands.
Finally, no-space mode is turned on to suppress unwanted blank lines.
Sub-headings
Sub-heRdings such as the ones used here may be easily produced with the following macro:

.t sh --- sub-heading
.de
.sp
.ne
.ti
.bf

sh
2
4
@[in]

[1]
.pp
.en sh
First, two blank lines are put out. Then it is determined if there are four contiguous lines
on the current page: one for the heading itself, one for the blank line after the heading,
and two for the first two lines of the next paragraph. The temporary indentation value is
then set to coincide with the current indentation value. Next, the first parameter passed to
the macro (the text of the sub-heading) is boldfaced and a new paragraph is begun. The "pp"
macro will insert the blank line after the heading.
Major Headings
Each section of this guide is introduced bya major heading that is boldfaced, underlined and centered on the page. The macro used to produce these headings is the following:
•• mh --- major heading
.de mh
.sp 3
.ne 5
.ce

.ul
.bf
[11

.sp
.pp
.en mh
- 17 -

Text Formatter User's Guide
This is similar to the sub-heading macro:
three blank lines are put out; a check for enough
room is made; the parameter is centered, underlined and boldfaced; another blank line is put
out; and a new paragraph is begun.
Quotations
Lengthy quotations are often set apart from other text by altering the left and right
to narrow the width of the quoted text.
Here is a pair of macros that may be used to
dellmit the beginning and end of a direct quotation:

mar~ins

.1 bq --- begin direct quote
.de bq
.sp
.ne 2
.in +5
.rm -5

.It +5
.en bq

.1 eq --- end direct quote
.de eq
.sp
.in -5
.rm +5
.en eq
Notice the It command in the first macro.
To avoid affecting page headings and footings, the
left margin is not adjusted; rather, an additional indentation is applied.
But to increase
the right margin width, there is no other alternative but to use the rm command.
The 'titlelength' command is thus necessary to allow headings and footings to remain unaffected by the
interim right margin.
Italics
Since most printers can't easily produce italics, they are frequently simulated by
underlining.
The following macro 'italicizes' its parameter by underlining it •

. 1 it --- italicize (by underlining)
.de it
.ul
[1]
.en it

Boldfacing
While 'fmt' has built-in facilities for boldfacing, their use may be somewhat cumbersome
if there are many sho~t phrases or single words that need boldfacing; each phrase or word
requires two input lines: one for the bf command and one for the actual text.
The following
macro cuts the overhead in half by allowing the command and the text to appear on the same
line.

.1 bo

boldface parameter

.de bo
.bf

[1]
.en bo

Examples
This guide is peppered with examples, each one set apart from other text by surrounding
blank lines and additional
indentation.
The next two macros, used like the "bqH and "eq"
macros, facilitate the production of examples.

- 18 -

Text Formatter User's Guide

.f
.de
.sp
.ne
.nf
.in
.en

bx --- begin example text
bx
2

+10
bx

.f ex --- end example text
.de ex
.sp
.fl
.in -10
.en ex
Note that the definition of the "ex" macro causes the ex command to become inaccessible.
Table Construction
One example of table construction (for a table of contents) has already been mentioned
in the section dealing with tabs. Another type of table that occurs frequently is that used
in the command summaries in this guide.
Each entry of such a table consists of a number of
'fields', followed on the right by a body of explanatory text that needs to be filled and
adjusted.
The easiest way to construct a table like this involves using a combination of tabs
indentation, as the following series of commands illustrates:

and

• in +40
.ta 14 24 34 41
.tc \
The idea is to set a tab stop in each column that begins a field, and one last one in the
column that is to be the left margin for the explanatory text. The extra indentation moves
the effective left margin to this column. To begin a new entry, temporarily undo the extra
indentation with a ti command, and then type the text of the entry, separating the fields
from one another with a tab character:
.ti -40
field l\field 2\field 3\field 4\Explanatory text
The first line of the entry will start at the old left margin.
Then all subsequent lines
will be filled and adjusted between column forty-one and the right margin (inclusive).

- 19 -

Text Formatter User's Guide
Summary of Commands Sorted Alphabetically
Command
Syntax

Ini tial
Value

If no
Cause
Parameter Break

•J

Explanation

Introduce a comment •

• ad c

both

Set margin adjustment mode •

.bf N

N=O

N=l

Boldface N input text lines.

• bp +N

N=l

yes

Begin a new page •

• br

yes

Force a break •

• c2 c

Set no-break control character •

• cc c

Set basic control character •

N=l

yes

Center N input text lines.

ignored

Begin definition or redefinition of a macro.

.ce N

N'=O

.de xx
• ef /l/e/r/

blank

Set even-numbered page footing •

• eh /l/e/r/

blank

Set even-numbered page heading •

• en xx

ignored

End macro definition •

.er tex t

ignored

Write a message to the terminal.

yes

Exit immediately to the Subsystem.

Turn on fill mode.

.ex
.fi

.fo /l/e/r/

blank

Set running page footing.

• he /l/e/r/

blank

Set running page heading •

.hy

Turn on automatic hyphenation.

• in +N

N=O

yes

Indent left margin •

.lm +N

N=l

yes

Se t

• ls N

N=l

Set line spacing •

.It +N

N=60

Set length of header, footer and titles.

.ml +N

N=3

Set top margin before and including page heading.

.m2 +N

N=2

Set top margin after page heading.

• m3 +N

N=2

Set bottom margin before page footing •

.m4 +N

N=3

Set bottom margin including and after page footing.

.mc

BLANK

Set margin character.

.inci +N

N=O

Set margin

Turn off margin adjustment •

yes

Express a need for N contiguous lines •

.nf

yes

Turn off fill mode.

.nh

Turn off automatic hyphenation.

Turn on 'no-space' mode •

Move on to the next input file.

• na
• ne N

• ns
.nx file

N=l

on
next arg

left marg in.

- 20 -

6ffset~

(Also inhibits adjustment.)

Text Formatter User's Guide
Command
Syntax

Initial
Value

Cause
If no
Parameter Break

Explanation

.of /l/c/r/

blank

Set od d-n umbe red page footing.

.oh /l/c/r/

blank

Set odd-numbered page heading.

.pl +N

N=66

Set page length.

.pn +N

N=l

ignored

Set page number.

.po +N

N=O

yes

Set page offset.

.rc c

BLANK

Set tab replacement character.

.rm +N

N=60

yes

Set right margin.

Turn off 'no-space' mode.

Single blank after end of sentence.

• rs
off

.sb
.so file

ignored

Temporarily alter the input source.

.sp N

N=l

yes

Put out N blank 1 i nes •

.ta N

9 17

all

Set tab stops.

.tc c

TAB

Set tab character.

.ti +N

N=O

yes

Temporar ily indent left margin.

blank

yes

Generate a three part title.

.ul N

N=O

N=l

Underline N input text lines.

.xb

Extra blank after end of sentence.

. tl

'1' c' r'

- 21 -

Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date : 2011:10:13 17:13:45-08:00
Modify Date : 2011:10:13 17:29:34-07:00
Metadata Date : 2011:10:13 17:29:34-07:00
Producer : Adobe Acrobat 9.46 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:001bf19a-de08-4e44-ab65-0cb1fd15dc12
Instance ID : uuid:fda4f1d7-192e-46b9-b889-ed61bbf2b039
Page Layout : SinglePage
Page Mode : UseOutlines
Page Count : 197

EXIF Metadata provided by EXIF.tools

Navigation menu

Upload a User Manual

Versions of this User Manual:

Wiki Guide
HTML
Download & Help

Views

User Manual
Discussion / Help

Navigation