------------------------------- Page    i -------------------------------

                            UTS for Beginners




                                                 Brian W. Kernighan



                                                 Edited for UTS

------------------------------- Page   ii -------------------------------

                            TABLE OF CONTENTS


1.    Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .   1

2.    Getting Started . . . . . . . . . . . . . . . . . . . . . . . .   1

2.1      Logging In . . . . . . . . . . . . . . . . . . . . . . . . .   2

3.    Typing Commands . . . . . . . . . . . . . . . . . . . . . . . .   2

4.    Special Characters  . . . . . . . . . . . . . . . . . . . . . .   3

5.    Tabs  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   4

6.    Readahead . . . . . . . . . . . . . . . . . . . . . . . . . . .   4

7.    Stopping a Program  . . . . . . . . . . . . . . . . . . . . . .   4

8.    Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . .   4

9.    Mail  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   5

10.   Writing to Other Users  . . . . . . . . . . . . . . . . . . . .   5

11.   On-line Manual  . . . . . . . . . . . . . . . . . . . . . . . .   6

12.   Day-to-Day Use  . . . . . . . . . . . . . . . . . . . . . . . .   7

12.1     Creating Files--The Editor . . . . . . . . . . . . . . . . .   7
12.2     What Files Are Out There?  . . . . . . . . . . . . . . . . .   8
12.3     Displaying Files . . . . . . . . . . . . . . . . . . . . . .   9
12.4     Shuffling Files About  . . . . . . . . . . . . . . . . . . .  10
12.5     File Name, What's in a . . . . . . . . . . . . . . . . . . .  11
12.6     What's in a File Name, Continued . . . . . . . . . . . . . .  13
12.7     Using Files Instead of the Terminal  . . . . . . . . . . . .  16
12.8     Pipes  . . . . . . . . . . . . . . . . . . . . . . . . . . .  17
12.9     The Shell  . . . . . . . . . . . . . . . . . . . . . . . . .  17

13.   Document Preparation  . . . . . . . . . . . . . . . . . . . . .  19

13.1     Formatting Packages  . . . . . . . . . . . . . . . . . . . .  19
13.2     Supporting Tools . . . . . . . . . . . . . . . . . . . . . .  20
13.3     Hints for Preparing Documents  . . . . . . . . . . . . . . .  21

14.   Programming . . . . . . . . . . . . . . . . . . . . . . . . . .  21

14.1     Programming the Shell  . . . . . . . . . . . . . . . . . . .  22

------------------------------- Page  iii -------------------------------

14.2     Programming in C . . . . . . . . . . . . . . . . . . . . . .  24

15.   UTS Reading List  . . . . . . . . . . . . . . . . . . . . . . .  25


                                                            Last Page  25

-------------------------------- Page  1 --------------------------------

1.    INTRODUCTION

In many ways, UTS is the state of the art in computer operating  systems.
From the user's point of view, it is easy to  learn and use, and presents
few of the usual impediments to getting the job done.

It is hard, however, for the beginner to know where to start, and how  to
make the  best use  of  the facilities  available.  The  purpose of  this
introduction is to point out  high spots for new users,  so they can  get
used to the main ideas of UTS and start making good use of it quickly.

This paper is not  an attempt  to re-write the  UTS Programmer's  Manual;
often the  discussion  of something  is  simply "read  section x  in  the
manual".  (This implies that you will need a copy of the UTS Programmer's
Manual, Volume  1 [1].)  Rather it  suggests in  what order  to read  the
manual, and it collects together  things that are stated only  indirectly
in the manual.  There are five sections:

 1.  Getting Started: How to log in to a UTS,  how to type, how to  enter
     special characters, how to log out.

 2.  Day-to-day Use: Things you  need every day  to use UTS  effectively:
     generally useful commands; the file system.

 3.  Document Preparation: Preparing manuscripts is one of the most  com-
     mon uses of UTS.   This section contains  advice, but not  extensive
     instructions on any of the formatting tools.

 4.  Writing Programs: UTS is  a vehicle for  developing programs.   This
     section talks about some of the tools, but again is not a tutorial.

 5.  A UTS Reading List.   An annotated bibliography  of documents  worth
     reading by new users.




2.    GETTING STARTED

This document is aimed at the use of 3270 terminals, however much of  the
information is also applicable to users of ASCII terminals.  The  follow-
ing actions will be  discussed in this  document.  This table  summarizes
the keys to hit to achieve the desired action.

-------------------------------- Page  2 --------------------------------

     Action          3270     Ascii

Enter Data         ENTER      RETURN
Interrupt Signal   PA1        CTRL-Q
Quit Signal        PA2        CTRL-\
EOT                TEST REQ   CTRL-D

To enter data into UTS, the ENTER or RETURN key must be hit.  Don't  for-
get this key, or nothing will happen.  If you think you're being ignored,
hit ENTER; something should happen.  We  won't show the ENTERs, but  they
have to be there.  The other actions will be discussed later.


2.1      LOGGING IN

To "get started", you must have a UTS login name.

 1.  To login from a 3270,  clear the screen until  "CP READ" appears  in
     the lower right hand corner.  To use an ASCII terminal, it will have
     printed: VM/470 ONLINE and will be awaiting input.

 2.  In either case, enter: dial uts and remember to press the ENTER key.

     UTS will type Name: at you.

 3.  When you get a login  message, type your login  name.  Follow it  by
     ENTER.  If a password is required, you will be asked for it.  A 3270
     will not display the input of your password, while an ASCII terminal
     will print  a black  splotch  for you  to type  your password  into.
     ENTER completes the request.

The culmination of your login efforts  is a "prompt character," a  single
character that indicates that the system is ready to accept commands from
you.  The prompt character is usually a dollar sign $.  (You may also get
a message of the day  just before the prompt character or a  notification
that you have mail or there is news.)




3.    TYPING COMMANDS

Once you've seen the prompt character,  you can type commands, which  are
requests that UTS do something.  Try typing

          date

followed by ENTER.  You should get back something like

-------------------------------- Page  3 --------------------------------

          Tue May  6 10:52:29 PDT 1980

Remember don't forget to hit ENTER after  typing the command.  This is  a
last reminder.  Another  command you  might try is  who, which tells  you
everyone who is currently logged in:

          who

gives something like

          bin     tty400   May  6 10:40
          root    tty402   May  6 10:48
          amdahl  tty403   May  6 09:58

The time is when the  user logged in.  If you  make a mistake typing  the
command name, UTS will tell you.  For example, if you type

          whom

you will be told

          whom: not found




4.    SPECIAL CHARACTERS

Because the 3270 keyboard has a limited character set, certain characters
must be entered using special characters or character pairs.  These char-
acters and character pairs, which would be used primarily in the develop-
ment of C programs, are:

          (<     for    left brace
          >)     for    right brace
          (|     for    left bracket
          |)     for    right bracket
          \      for    backslash
          ~      for    tilde
          \~     for    circumflex
          \<     for    grave accent
          \!     for    tab

-------------------------------- Page  4 --------------------------------

5.    TABS

To enter  tab characters  from a  3270, use  the "FIELD  MARK" key.   For
3270's which don't have a "FIELD MARK" key, tabs may also be entered with
the double character sequence \!.  Tab positions default to columns 1, 9,
17, 25, 33, etc.




6.    READAHEAD

UTS has full  readahead, which means  that you  can type as  fast as  you
want, whenever you want, even when some command is typing at you.  If you
type during output, your input characters will appear intermixed with the
output characters, but they will be stored away by UTS and interpreted in
the correct  order.  So  you  can type  two commands  one  after  another
without waiting for the first to finish or even begin.




7.    STOPPING A PROGRAM

A program can be stopped  by generating an  interrupt signal.  There  are
exceptions, like the text editor,  where an interrupt signal stops  what-
ever the program is doing but leaves you in that program.  Another way to
terminate a program is to use the quit signal.  The quit signal kills the
executing program and dumps  it to a  file with  the name of  core if  it
exists.  If you are using  an ASCII terminal and the program you want  to
stop is printing on your terminal, you need to hit the BREAK key to  stop
the output and then stop the program.




8.    LOGGING OUT

To log out, hit  EOT (end-of-transmission) and  the login message  should
appear.  Then you can type the login name of another user and let someone
else use the terminal you were on, or hit  EOT again to complete the  log
out process.

-------------------------------- Page  5 --------------------------------

9.    MAIL

When you log in, you may sometimes get the message

          You have mail.

UTS provides a postal  system so you  can send and  receive letters  from
other users of the system.  To read your mail, issue the command

          mail

Each message will be printed, most recent message first, followed by

          ?

This means mail is waiting  for you to say what  to do with the  message.
The two  basic responses  are d,  which deletes the  message, and  ENTER,
which does not (so  it will still be  there the next  time you read  your
mailbox).  Other responses are described in the manual [1].

How do you  send mail  to someone else?   Suppose it  is to  go to  "joe"
(assuming "joe" is someone's login name).  The easiest way is this:

          mail joe
          now type in the text of the letter
          on as many lines as you like ...
          after the last line of the letter
          hit EOT

And that's it.  EOT is used throughout UTS to mark the end of input  from
a terminal.  There are other ways to send mail--you can send a previously
prepared letter, and you can mail to a number of people all at once.  For
more details see mail(1).  The notation mail(1) means the command mail in
Volume 1 of the UTS Programmer's Manual.




10.   WRITING TO OTHER USERS

At some point in  your UTS career, out  of the blue  will come a  message
like

          Message from joe...

accompanied by a startling beep.  It means that Joe wants to talk to you,
but unless you take explicit  action you won't be able to talk back.   To
respond, type the command

-------------------------------- Page  6 --------------------------------

          write joe

This establishes a two-way communication path.  Now whatever Joe types on
his terminal  will appear on  yours and  vice versa.  The  path is  slow,
rather like talking to the moon.  (If you are in the middle of something,
you have to get to a state where you can type a command.  Normally, what-
ever program  you are  running has  to terminate  or be  terminated.   If
you're editing,  you can  escape  temporarily from  the editor--read  the
manual.) A protocol is needed to keep what you type from getting  garbled
up with what Joe types.  Typically it's like this:

          Joe types "write smith" and waits.

          Smith types "write joe" and waits.

          Joe now types his message (as many lines as he likes).
          When he's ready for a reply, he signals it by typing (o), which
          stands for "over".

          Now Smith types a reply, also terminated by (o).

          This cycle repeats until someone gets tired; he then
          signals his intent to quit with (o+o), for "over and out".

          To terminate the conversation, each side must hit EOT.
          When the other person hits EOT,
          you will get the message "EOF" on your terminal.

If you write to someone  who isn't logged in, or  who doesn't want to  be
disturbed, you'll be told.  If the target is logged in but doesn't answer
after a decent interval, simply hit EOT.




11.   ON-LINE MANUAL

The UTS Programmer's Manual is kept on-line.   If you get stuck on  some-
thing, and can't find  an expert to assist  you, you can view the  manual
page online that might help.  It's also  useful for getting the most  up-
to-date information  on  a command.   The  manual is  divided  into  four
volumes: commands, program  functions, system level  commands, and  docu-
ments.  The first three volumes  contain manual pages that may be  viewed
with the  man(1) command,  while the  documents may  be viewed  with  the
doc(1) command.  From 3270's, both the man and doc commands  put the for-
matted information into  the full  screen editor to  allow browsing.   To
view a  manual  page,  type  "man  -volume-number  name".   Volume-number
defaults to 1, so it  may be omitted if the  name is a Volume 1  command.

-------------------------------- Page  7 --------------------------------

Thus to read up on the who(1) command, type

          man who

or

          man -1 who

and, of course,

          man man

will explain the man command.




12.   DAY-TO-DAY USE


12.1     CREATING FILES--THE EDITOR

If you have to type a paper or a letter or a program, how do you get  the
information stored in the machine?  Most of these tasks are done with the
UTS full screen "text editor" ned.  Ned can only be used from 3270 termi-
nals.  From an ASCII  terminal the line editor  ed must be used.  See   A
Tutorial Introduction to the UTS Line Editor for a further description of
ed.

Since ned  is  thoroughly documented  in  the Ned  Reference  Manual  and
explained in the Ned Tutorial[2], we won't spend any time here describing
how to use it.  All we want it for right  now is to make some files.   (A
file is  just  a  collection of  information  stored in  the  machine,  a
simplistic but adequate definition.)  To create a  file "junk" with  some
text in it, do the following:

           n junk      (invokes ned)

A new screen will appear with a line of information across the top,  fol-
lowed by the primary command  line, indicated by ==>.  Commands that  are
typically entered on this line are called "primary commands".  These  are
commands that can affect any  part of the file being edited or  influence
the operation of ned.  Line numbers are typically displayed in columns 76
through 79 of  the screen.  These  columns are also  used to input  "line
commands"--editor commands that affect only the line on which the command
is entered or, in the case of block commands, the  lines delimited by the
command.  Several of  the more  frequently used commands  can be  invoked
with the PF keys.  Type p on the primary command  line to see the current

-------------------------------- Page  8 --------------------------------

settings of your PF keys.

To start entering text, move the cursor to the first line of empty screen
(this is called the data area).

           now type in
           whatever text you want ...

At this point you  could do various  editing operations on  the text  you
typed in, such  as correcting  spelling mistakes, rearranging  paragraphs
and the like.  Finally,  you must  write the information  you have  typed
into a file  with the editor  command w, entered  on the primary  command
line.

          w

Ned will respond by indicating the number of characters it wrote into the
file called "junk" (this is  the number in the middle of the top line  on
the screen).

Until the w command, nothing  is stored permanently, so  if you quit  ned
before doing a write, the  information is lost.  (Leaving ned by  hitting
PF3, which first does  a w if necessary,  is the best  way to avoid  this
problem.) After w the information is there permanently; you can re-access
it any time by typing

          n junk

Type a q to  leave ned.  (If you  try to quit  without writing, ned  will
print an error message  to remind you.  A  second q gets you out  regard-
less.)

Now create a second file  called "temp" in the  same manner.  You  should
now have two files, "junk" and "temp".


12.2     WHAT FILES ARE OUT THERE?

The ls (for "list") command lists the names (not contents) of any of  the
files that UTS knows about.  If you type

          ls

the response will be

          junk
          temp

which are indeed the two files just created.  They are sorted into alpha-
betical order  automatically,  but other  variations are  possible.   For

-------------------------------- Page  9 --------------------------------

example, if you add the optional argument -t,

          ls -t

lists them in  the order  in which they  were last  changed, most  recent
first.  The -l option gives a "long" listing:

          ls -l

will produce something like

          -rw-rw-rw-  1 bwk   41 Sep 22 12:56 junk
          -rw-rw-rw-  1 bwk   78 Sep 22 12:57 temp

The date and time are of the last change to the file.  The 41 and 78  are
the number of characters (you got the same thing from ned).  "bwk" is the
owner of the file--the person who created it.  The "-rw-rw-rw-" tells who
has permission  to  read  and write  the  file, in  this  case  everyone.
Options can be combined:  ls -lt would  give the same  thing, but  sorted
into time order.  You can  also name the files you're interested in,  and
ls will list the information about them only.  More details can be  found
in ls(1).  It  is generally  true of UTS  programs that "flag"  arguments
like -t precede file name arguments.


12.3     DISPLAYING FILES

Now that you've got a file of text, how do  you display it so people  can
look at it?   There are a host  of programs that  do that, probably  more
than are needed.  One simple  thing is to use ned,  since this will  also
allow you to make any necessary changes.  You can say

          ned junk

ned will reply with a new screen displaying the first 22 lines of "junk".
It will then allow  you to scroll through the  file by using the PF  keys
(normally PF 7 and 8).  See ned(1) for more details.

There are times when it's not feasible  to use ned for displaying  files.
For example, it  will only print one  file at a  time, and sometimes  you
want to print several, one after another.  So here are a couple of alter-
natives.

First is cat(1), the simplest of  all the printing programs.  cat  simply
copies all the files in a list onto the terminal.  So you can say

          cat junk

or, to print two files,

-------------------------------- Page 10 --------------------------------

          cat junk temp

The two files are simply concatenated (hence the name cat) onto the  ter-
minal.

pr(1) produces formatted printouts of files.  As with cat, pr prints  all
the files in a  list.  The difference  is that it produces headings  with
date, time, page number and file name at the top of each page, and  extra
lines to skip over the fold in the paper.  Thus,

          pr junk temp

will list "junk" neatly,  then skip to  the top  of a new  page and  list
"temp" neatly.  pr will also produce multi-column output:

          pr -3 junk

prints "junk" in 3-column format.  You  can use any reasonable number  in
place of "3" and pr will do its best.  It  should be noted that pr is not
a formatting program in the sense of shuffling lines around and  justify-
ing margins.  There is also  a program that prints files on a  high-speed
printer.  If you wanted to print "junk" and "temp", you could say

          opr junk temp

For a complete  description of  the command,  look in  your manual  under
opr(1).


12.4     SHUFFLING FILES ABOUT

Now that you have some  files in the file system  and some experience  in
printing them, you can  try bigger things.   For example, you can move  a
file from one  place to another  (which amounts  to giving a  file a  new
name), like this:

          mv junk precious

This means that what used to be "junk" is  now "precious".  If you do  an
ls command now, you will get

          precious
          temp

Beware that if you move  a file to another one  that already exists,  the
already existing contents are lost  forever.  If you want to make a  copy
of a file (that is, to have two versions  of something), you can use  the
cp(1) command:

          cp precious temp1

-------------------------------- Page 11 --------------------------------

makes a duplicate copy of "precious"  in "temp1".  Finally, when you  are
tired of creating and  moving files, there  is a command to remove  files
from the file system, called rm(1).

          rm temp temp1

will remove all of the  files named.  You will get  a warning message  if
one of the named files wasn't there.


12.5     FILE NAME, WHAT'S IN A

So far we have used file names without  ever saying what's a legal  name,
so it's time for a couple of rules.  First, file  names are limited to 14
characters, which is enough to be descriptive.  Second, although you  can
use almost any  character in a  file name, common  sense says you  should
stick to ones that are visible, and that you should probably avoid  char-
acters that might be used with other meanings.  We already saw, for exam-
ple, that in the ls  command, ls -t meant to  list in time order.  So  if
you had a file whose  name was "-t", you would have a tough time  listing
it by name.  There are  a number of other  characters which have  special
meaning either to UTS as a whole or to numerous  commands.  To avoid pit-
falls, you would probably do  well to use only  letters, numbers and  the
period.  (Don't use the period as the first character of a file name, for
reasons too complicated to go into.)

On to  some more  positive suggestions.   Suppose you're  typing a  large
document like a  book.  Logically  this divides into  many small  pieces,
like chapters and perhaps sections.   Physically it must be divided  too,
for ned will not handle extremely large files.  Thus you  should type the
document as a number of files.  You might  have a separate file for  each
chapter,

          chap3
          chap1
          chap2
          etc...

Or, if each chapter were broken into several files, you might have

          chap1.1
          chap1.2
          chap1.3
           ...
          chap2.1
          chap2.2
           ...

You can now tell at a glance where a particular file fits into the whole.
There are  advantages to  a systematic  naming convention  which are  not

-------------------------------- Page 12 --------------------------------

obvious to the novice UTS  user.  What if you wanted  to print the  whole
book? You could say

          pr chap1.1 chap1.2 chap1.3 ......

but you would get tired  pretty fast, and would  probably even make  mis-
takes.  Fortunately, there is a shortcut.  You can say

          pr chap*

The * means "anything at all", so  this translates into "print all  files
whose names  begin with  'chap' ",  listed in  alphabetical order.   This
shorthand notation is not a property of the  pr command, by the way.   It
is system-wide, a service  of the program  that interprets commands  (the
"shell" sh(1)).  Using that fact,  you can see how to  list the files  of
the book:

          ls chap*

produces

          chap1.1
          chap1.2
          chap1.3
          ...

The * is not limited to the last position in a file name--it can be  any-
where.  Thus

          rm *junk*

removes all files that contain  "junk" as any part of  their name.  As  a
special case, * by itself matches every file name, so

          pr *

prints all the files (alphabetical order), and

          rm *

removes all files.  (You  had better be  sure that's what  you wanted  to
say!) The * is not the only pattern-matching feature available.   Suppose
you want to print only chapters 1 through 4 and 9 of the book.  Then  you
can say

          pr chap[12349]*

The [...] means to match any of the characters inside the brackets.   You
can also do this with

-------------------------------- Page 13 --------------------------------

          pr chap[1-49]*

"[a-z]" matches any character in the range a through z.  There is also  a
? character, which matches any single character, so

          pr ?

will print  all  files  which  have  single-character  names.   Of  these
niceties, * is probably the  most useful, and you should get used to  it.
The others are frills,  but worth knowing.   If you should  ever have  to
turn off the special meaning  of *, ?, etc., enclose the entire  argument
in single quotes, as in

          ls '?'



12.6     WHAT'S IN A FILE NAME, CONTINUED

When you first made that file called "junk", how did UTS know that  there
wasn't another "junk" somewhere else, especially since the person in  the
next office is also reading this  tutorial? The reason is that  generally
each user of UTS has  his own "directory", which contains only the  files
that belong to him.  When you create a new file, unless you take  special
action, the new file is  made in your own directory, and is unrelated  to
any other file of the same name that might exist in someone else's direc-
tory.  The set  of all files that  UTS knows about  are organized into  a
(usually big) tree, with your files located several branches up into  the
tree.  It is possible for you to "walk" around this tree, and to find any
file in the system, by starting at the root of the tree and walking along
the right set of branches.  To begin, type

          ls /

"/" is the name of the root of the tree (a convention used by UTS).   You
will get a response something like this:

          bin
          dev
          etc
          lib
          tmp
          usr

This is a collection  of the basic  directories of files  that UTS  knows
about.  "usr" is a directory  that contains department codes for all  the
departments that use the system.  Now try

          ls  /usr

-------------------------------- Page 14 --------------------------------

This should list a series  of department codes, among  which is your  own
department.  Now try

          ls /usr/your-dept.

This should give you a  list of all the UTS  users under your  department
code, among which is your own login name.  Finally, try

          ls  /usr/your-dept/your-name

You should get what you get from a plain

          ls

Now try

          cat  /usr/your-dept/your-name/junk

(if "junk" is still around).  The name

          /usr/your-dept/your-name/junk

is called the  "path name"  of the  file that  you normally  think of  as
"junk".  "Path name" has an obvious meaning: it represents the  full name
of the path you have to follow through the tree of directories to get  to
a particular file.  It is  a universal rule in UTS that anywhere you  can
use an ordinary file name,  you can use a path  name.  Here is a  picture
which may make this clearer:

                         (root)
                          / | \
                         /  |  \
                        /   |   \
         bin      etc      usr      dev      tmp
        / | \    / | \    / | \    / | \    / | \
                         /  |  \
                        /   |   \
                    da     eus     td
                   /      / | \     \
                         /  |  \
                        /   |   \
                  adam     eve     mary
                 /        /   \       \
                        /       \      junk
                     junk       temp

Notice that Mary's "junk" is unrelated to Eve's.

This isn't too  exciting if all  the files  of interest are  in your  own
directory, but  if you  work  with someone  else or  on several  projects

-------------------------------- Page 15 --------------------------------

concurrently, it becomes  handy indeed.   For example,  your friends  can
print your book by saying

          pr  /usr/your-dept/your-name/chap*

Similarly, you can find out what files your neighbor has by saying

          ls  /usr/neighbor-dept/neighbor-name

or make your own copy of one of his files by

          cp  /usr/neighbor-dept/your-neighbor/his-file  yourfile

If your neighbor doesn't  want you poking  around in his  files, or  vice
versa, privacy can be arranged.   Each file and directory can have  read-
write-execute permissions for the owner,  a group, and everyone else,  to
control access.   See ls(1)  and chmod(1)  for details.  As  a matter  of
observed fact, most users most of the time find openness of more  benefit
than privacy.  As a final experiment with path names, try

          ls  /bin  /usr/bin

Do some of the names  look familiar?  When you run  a program, by  typing
its name after a prompt character, the system simply looks  for a file of
that name.  It looks first in your directory (where it typically  doesn't
find it), then  in "/bin"  and finally in  "/usr/bin".  There is  nothing
magic about commands like cat or ls, except that they have been collected
into two places to be easy to find and administer.

What if you work regularly with someone else on common information in his
directory?  You could just log  in as your friend each time you want  to,
but you can also say  "I want to work  on his files  instead of my  own".
This is done by changing the directory that you are currently in:

          cd /usr/friend-dept/your-friend

Now when you use a  file name in something like  cat or pr, it refers  to
the file  in  "your-friend's" directory.   Changing  directories  doesn't
affect any permissions associated with  a file--if you couldn't access  a
file from your own directory,  changing to another directory won't  alter
that fact.  If you forget what directory you're in, type

          pwd

("print working  directory") to  find  out.  It  is often  convenient  to
arrange one's files so that  all the files related to one thing are in  a
directory separate from other projects.  For example, when you write your
book, you might want to keep all the text in a directory called book.  So
make one with

-------------------------------- Page 16 --------------------------------

          mkdir book

then go to it with

          cd book

then start typing chapters.  The book is now found in (presumably)

          /usr/your-dept/your-name/book

To delete a directory, see rmdir(1).  You can go up one level in the tree
of files by saying

          cd ..

For completeness, . is an alternate name for the directory you are in.


12.7     USING FILES INSTEAD OF THE TERMINAL

Most of the commands we have seen so far produce output on the  terminal;
some, like the editor,  also take their  input from the terminal.  It  is
universal in UTS that the terminal can be  replaced by a file for  either
or both of input and output.  As one example, you could say

          ls

to get a list of files.  But you can also say

          ls >filelist

to get a list of your files in the file "filelist".  ("filelist" will  be
created if it doesn't already exist, or overwritten if it does.) The sym-
bol > is used  throughout UTS to  mean "put the  output on the  following
file, rather than on the terminal".  Nothing is produced on the terminal.
As another example, you could concatenate several files into one by  cap-
turing the output of cat in a file:

          cat  f1  f2  f3 >temp

The symbol >> operates very much like >  does, except that it means  "add
to the end of." That is,

          cat f1 f2 f3 >> temp

means to  concatenate "f1",  "f2", and  "f3" to  the end  of whatever  is
already in "temp", instead of overwriting the existing contents.  As with
>, if "temp" doesn't exist, it will be created for you.

-------------------------------- Page 17 --------------------------------

In a similar way, the symbol < means to take the input for a program from
the following file, instead  of from the  terminal.  Thus, you could  use
ned to prepare a letter in file "let", and then send it to several people
with

          mail adam eve mary joe < let



12.8     PIPES

One of the novel contributions of UTS is the idea of a "pipe".  A pipe is
simply a way to connect the output of one program to the input of another
program, so the two  run as  a sequence of  processes--a pipe-line.   For
example,

          pr  f  g  h

will print the  files "f", "g"  and "h",  beginning each on  a new  page.
Suppose you want them run together instead.  You could say

          cat  f  g  h  >temp
          pr <temp
          rm  temp

but this is more work  than necessary.  Clearly what we  want is to  take
the output of cat  and connect it  to the input of  pr.  So let us use  a
pipe:

          cat  f  g  h  |  pr

The vertical bar means to take the output from cat, which would  normally
have gone to the terminal,  and put it into pr, which formats it  neatly.
Any program that reads from  the terminal can read  from a pipe  instead;
any program that writes on  the terminal can drive a pipe.  You can  have
as many elements in a pipeline as you wish.  Many UTS programs are  writ-
ten so that they  will take their  input from one  or more files if  file
arguments are given; if no  arguments are given they  will read from  the
terminal, and thus can be used in pipelines.


12.9     THE SHELL

We have already mentioned once or twice the mysterious "shell," which  is
in fact sh(1).  The shell is the program that interprets what you type as
commands and arguments.  It  also looks after  translating *, etc.,  into
lists of file names,  and <, >,  and | into  changes of input and  output
streams.

-------------------------------- Page 18 --------------------------------

The shell has other  capabilities too.   For example, you  can start  two
programs with one command  line by separating  the commands with a  semi-
colon; the shell recognizes the  semicolon and breaks  the line into  two
commands.  Thus

          date; who

does both commands before returning with the prompt character.

You can also have  more than  one program running  simultaneously if  you
wish.  For example,  if you  are doing something  time-consuming, like  a
compile, and you don't want to wait around for the results before  start-
ing something else, you can say

          cc  file.c &

The ampersand at the end of a command line says "start this command  run-
ning, then take further commands from the terminal immediately." Thus the
compile will begin, but you can do something  else at the same time.   Of
course, to keep the output from interfering with what you're doing on the
terminal, it would be better to have said

          cc  file.c > errors &

which would save the output messages in a file called "errors".  When you
initiate a command with &,  UTS replies with a number called the  process
number, which identifies the command in case  you later want to stop  it.
If you do, you can say

          kill process-number

You might also read ps(1).  You can say

          (command-1; command-2; command-3) &

to start these commands in the background  or you can start a  background
pipeline with

          command-1 | command-2 &

Just as you can tell the editor or some similar program to take its input
from a file instead of from the terminal, you can  tell the shell to read
a file to get commands.  (Why not? The shell after all is just a program,
albeit a clever one.) For instance, suppose you want to find out the date
and who's on the system every time you log in.  Then you can put the  two
necessary commands ( date;  who) into a  file, let's call it  "xxx",  and
then run it with either

          sh xxx

-------------------------------- Page 19 --------------------------------

or

          sh <xxx

This says to run the shell with the file  "xxx" as input.  The effect  is
as if you had typed  the contents of "xxx" on the terminal.  (If this  is
to be a  regular thing,  you can  eliminate the  need to  type "sh";  see
chmod(1) and  sh(1).) The  shell has  quite a few  other capabilities  as
well, some of which we'll get to in the section on programming.




13.   DOCUMENT PREPARATION

The UTS system  is used  extensively for document  preparation.  This  is
generally done by using text formatting programs, that is, programs  that
produce text with justified right  margins, automatic page numbering  and
titling, automatic hyphenation, and  the like.  ms(1)  is used for  docu-
ments and mm(1) is  used for memos.   Both of these  are based on  nroff,
which is generally difficult  to use and  is needed only in very  unusual
circumstances.


13.1     FORMATTING PACKAGES

The basic idea of nroff is that the text to be formatted contains  within
it "formatting commands" that indicate  in detail how the formatted  text
is to look.  For  example, there may  be commands that  specify how  long
lines are, whether to  use single or  double spacing, and what titles  to
use on each page.

Because nroff is relatively hard to learn  to use effectively, ms and  mm
have been developed.  These are "packages" of canned formatting  requests
which let you specify paragraphs, footnotes, lists, and so on, with  lit-
tle effort and without having to learn nroff.

In this section, we will look briefly at ms.  For a complete  description
of this package,  see [3].   Formatting requests typically  consist of  a
period and two lower case letters, such as .pp, which is used to begin  a
new paragraph.

A document is typed so it looks something like this:

           .mt "document title"
           .au "author1" "author2"
           .hd 1 Level One Heading
           paragraph...

-------------------------------- Page 20 --------------------------------

           .pp
           paragraph...
           .hd 2 Level Two Heading
           paragraph...
           .pp
           etc.

The lines that begin with a period are the formatting requests.

To actually produce a document in standard format using ms, use the  com-
mand

          ms files...

to get output at your terminal, and

          ms -p files...

to have the output sent to the printer.


13.2     SUPPORTING TOOLS

In addition to formatters, there  is a host  of supporting programs  that
help with document preparation.  Some of these will be described  in this
section.

Spell(1) and typo(1)  detect possible  spelling mistakes  in a  document.
Spell works  by comparing  the words  in your document  to a  dictionary,
printing those that are  not in  the dictionary.  It  knows enough  about
English spelling to detect plurals and the like, so it does a pretty good
job.  Typo looks for words which are "unusual", and prints those.   Spel-
ling mistakes tend to be more unusual, and thus show up early because the
most unusual words are printed first.

Grep(1) looks through a set  of files for  lines containing a  particular
text pattern  (rather like  the editor's  context search does,  but on  a
whole series of files).  For example,

          grep 'ing$' chap*

will find all lines ending  in the letters "ing" in  the series of  files
"chap".  (It is almost always a good practice to put single quotes around
the pattern you're  searching for,  in case it  contains characters  that
have a special meaning for  the shell.) Grep is often useful for  finding
out in which of a set of files the misspelled words detected by spell are
actually located.

Diff(1) prints a list of  the differences between two  files, so you  can
compare two versions  of something  automatically (which certainly  beats

-------------------------------- Page 21 --------------------------------

proofreading by hand).

Wc(1) counts the words, lines  and characters in a  set of files.   Tr(1)
translates characters into other characters; for example it will  convert
upper to lower case and vice versa.  This translates upper to lower:

          tr A-Z a-z <input >output

Sort(1) sorts files in a variety of ways; cref(1) makes cross-references.
Sed(1) provides many of the editing features of ed(1), but can apply them
to arbitrarily long input.  Awk(1) provides  the ability to do both  pat-
tern matching  and numerical  computations, and  to conveniently  process
fields within lines.   These programs  are for more  advanced users,  and
they are not limited to document preparation.


13.3     HINTS FOR PREPARING DOCUMENTS

Most documents go through several  versions before they are finally  fin-
ished.  Accordingly, you should do  whatever possible to make the job  of
changing them easy.

When you do the purely mechanical operations of typing, type so that sub-
sequent editing will be easy.   Start each sentence on a new line.   Make
lines short, and break lines at natural places, such as after commas  and
semicolons, rather than randomly.  Since most people change documents  by
rewriting phrases and adding, deleting  and rearranging sentences,  these
precautions simplify any editing you have to do later.

Keep the individual files of a document down to modest size, perhaps  ten
to fifteen thousand characters.   Larger files edit  more slowly, and  of
course if you make a dumb mistake it's  better to have clobbered a  small
file than a large  one.  Split text  into files at natural boundaries  in
the document, for the same reasons that you start each sentence on a  new
line.




14.   PROGRAMMING

UTS is a marvelously pleasant and productive system for writing programs;
productivity seems  to be  an  order of  magnitude higher  than on  other
interactive systems.   One of  the  reasons for  this is  that  there  is
already a rich  set of  tools available, and  facilities like pipes,  I/O
redirection, and the capabilities of the shell often make it possible  to
do a job by pasting together programs that already exist instead of writ-
ing from scratch.

-------------------------------- Page 22 --------------------------------

The pipe mechanism,  for example,  lets you  fabricate quite  complicated
operations out  of spare  parts already  built.  The first  draft of  the
spell program was (roughly)

          cat ...          (collect the files)
          | tr ...         (put each word on a new line,
                         delete punctuation, etc.)
          | sort          (into dictionary order)
          | uniq          (strip out duplicates)
          | comm          (list words found in text but
                         not in dictionary)

More pipes have been  added subsequently, but  this goes a  long way  for
such a small effort.


14.1     PROGRAMMING THE SHELL

An option often overlooked  by newcomers is  that the shell  is itself  a
programming language, with variables, control-flow (if-else, while,  for,
case), subroutines, and interrupt handling.  Since UTS already has a host
of building-block  programs, you  can sometimes avoid  writing a  special
purpose program merely by  piecing together some  of the building  blocks
with shell command files.   As an unlikely  example, suppose you want  to
count the number of users on the machine every hour.  You could type

          date
          who | wc -l

every hour, and write  down the  numbers, but that  is rather  primitive.
The next step is probably to say

          (date; who | wc -l) >>users

which uses >> to append to the end of the file "users".  Now all you have
to do is to put a loop around this, and ensure that it's done every hour.
Thus, place the following commands into a file, say "count":

          while test 1
          do
          (date; who | wc -l) >>users
          sleep  3600
          done

Test(1) evaluates the  expression following  it and returns  a zero  exit
status if  its  value  is  true;  otherwise a  non-zero  exit  status  is
returned.  Since 1 is always true, test always returns 0 to while.  While
repeatedly executes the expression following it and executes the do  list
if its value is zero.  Thus the while test 1 is always true and causes an
infinite loop.  (The do and  done are part of the while syntax).  Now  if

-------------------------------- Page 23 --------------------------------

you issue the command

          sh  count  &

the users  will be  counted every  hour, and  you can  go on  with  other
things.  (You will have  to use kill(1)  to stop counting.) If you  would
like to be able to issue your "count" command like any other UTS command,
you must make the file executable.  To do this, type

          chmod +x count

If you would like  "every hour" to  be a parameter,  you can arrange  for
that too:

          while test 1
          do
          (date; who | wc - l) >>users
          sleep  $1
          done

$1 means the first argument when this procedure is invoked.  If you say

          sh count 60
          (or count 60, if you made the file executable)

it will count every minute.  A shell program can have any number of argu-
ments, $1 through $n.  The shell also allows conditional assignment.  For
example, you could arrange that the "count" procedure count every hour by
default, but  allow an  optional argument  to specify  a different  time.
Simply replace the sleep $1 line by

          x=${1 - 3600}
          sleep $x

The construction

          x=${1 - 3600}

tests whether $1, the first argument was previously defined.  If it  was,
that value  is assigned  to  x; otherwise  the value  after  the dash  is
assigned.  Another aspect of programming is conditional testing.  The  if
command tests the exit  status of commands  and executes other   commands
accordingly.  As a simple example,  suppose you wanted to further  modify
the "count" program to permit  a time parameter, provided it was an  hour
or less.  You could say

          if test $x -gt 3600
          then x=3600
          fi

-------------------------------- Page 24 --------------------------------

This says "if the value of x is greater than 3600 (an hour), change it to
an hour".  The if, then,  and fi are part of the syntax for an if  state-
ment in the shell.  More  complicated conditions can  be tested: you  can
find out the status  of an executed  command, and you can combine  condi-
tions with 'and', 'or', 'not' and parentheses.  See sh(1) for more infor-
mation on all the options available to you.


14.2     PROGRAMMING IN C

If you are  undertaking anything  substantial, C is  the only  reasonable
choice of programming language:  everything in UTS  is tuned to it.   The
system itself is written in  C, as are most of  the programs that run  on
it.  It is also a  remarkably easy language to use once you get  started.
C is introduced and fully described  in The C Programming Language,  [4].
Volume 2 of the manual describes the system interfaces, that  is, how you
do I/O and similar functions.  Read UTS Programming, for more complicated
things.

Most input and output in C is best handled with the standard I/O library,
which provides a useful set of I/O functions.  In general, it's wisest to
confine the system interactions in  a program to the facilities  provided
by this library.

There are a number of supporting programs that go with C.  Lint(1) checks
C programs for potential portability problems, and detects errors such as
mismatched argument types and uninitialized variables.

For larger programs (anything whose source is more than one file) make(1)
allows you to  specify the  dependencies among the  source files and  the
processing steps needed to make a new  version; it then checks the  times
that the pieces were last  changed and does the minimal amount of  recom-
piling to create a consistent updated version.

The debugger dcon(1) can be  used to both examine  a file's contents  and
dynamically debug a program.   The most effective  tool is still  careful
thought coupled wth judiciously placed print statements.

Mon(1) can be used to monitor the execution time of a program so you  can
find out where programs spend their time and what parts  are worth optim-
izing.  Mon's output can be  displayed with mer(1).  The command  time(1)
will give you  the run-time  statistics for a  program, reported in  mil-
liseconds.

-------------------------------- Page 25 --------------------------------

15.   UTS READING LIST

This is an annotated bibliography of documents that should be helpful  to
new users.  For a complete list of documents relating to  UTS, see "Docu-
ments for the UTS Time-Sharing System".

General:

 [1]  UTS Programmer's Manual, Volume 1
      Commands that are  entered from  the keyboard  are described  here.
      This is the primary reference manual for all UTS users.

Text Editors:

 [2]  Ned Tutorial
      A tutorial introduction to the UTS full-screen editor "ned".   Con-
      tains examples of how to use ned and highlights problems  users may
      encounter.

Text Formatting:

 [3]  Formatting Documents on UTS
      User's guide and reference  manual for  ms, a set  of commands  for
      formatting documents.

Programming:

 [4]  The C Programming Language
      by B. W. Kernighan and D. M. Ritchie
      Prentice-Hall, Inc., Englewood Cliffs, NJ, 1978.
      Complete tutorial and reference manual for C.

 [5]  An Introduction to the UTS Shell
      The shell  is the  command programming  language that  provides  an
      interface to the UTS operating system.
