<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY replstart "&lt;">
  <!ENTITY replend   "&gt;">
  <!ENTITY repeatst   "{">
  <!ENTITY repeaten   "}">
  <!ENTITY attrref SYSTEM "attr.refentry">
  <!ENTITY backupref SYSTEM "backup.refentry">
  <!ENTITY binexref SYSTEM "binex.refentry">
  <!ENTITY buildref SYSTEM "build.refentry">
  <!ENTITY chdref SYSTEM "chd.refentry">
  <!ENTITY cmpref SYSTEM "cmp.refentry">
  <!ENTITY cobblerref SYSTEM "cobbler.refentry">
  <!ENTITY copyref SYSTEM "copy.refentry">
  <!ENTITY dateref SYSTEM "date.refentry">
  <!ENTITY dcheckref SYSTEM "dcheck.refentry">
  <!ENTITY delref SYSTEM "del.refentry">
  <!ENTITY deldirref SYSTEM "deldir.refentry">
  <!ENTITY dirref SYSTEM "dir.refentry">
  <!ENTITY displayref SYSTEM "display.refentry">
  <!ENTITY dsaveref SYSTEM "dsave.refentry">
  <!ENTITY dumpref SYSTEM "dump.refentry">
  <!ENTITY echoref SYSTEM "echo.refentry">
  <!ENTITY exref SYSTEM "ex.refentry">
  <!ENTITY formatref SYSTEM "format.refentry">
  <!ENTITY freeref SYSTEM "free.refentry">
  <!ENTITY identref SYSTEM "ident.refentry">
  <!ENTITY killref SYSTEM "kill.refentry">
  <!ENTITY linkref SYSTEM "link.refentry">
  <!ENTITY listref SYSTEM "list.refentry">
  <!ENTITY loadref SYSTEM "load.refentry">
  <!ENTITY loginref SYSTEM "login.refentry">
  <!ENTITY makdirref SYSTEM "makdir.refentry">
  <!ENTITY mdirref SYSTEM "mdir.refentry">
  <!ENTITY mergeref SYSTEM "merge.refentry">
  <!ENTITY mfreeref SYSTEM "mfree.refentry">
  <!ENTITY os9genref SYSTEM "os9gen.refentry">
  <!ENTITY printerrref SYSTEM "printerr.refentry">
  <!ENTITY procsref SYSTEM "procs.refentry">
  <!ENTITY pwdref SYSTEM "pwd.refentry">
  <!ENTITY renameref SYSTEM "rename.refentry">
  <!ENTITY saveref SYSTEM "save.refentry">
  <!ENTITY setimeref SYSTEM "setime.refentry">
  <!ENTITY setprref SYSTEM "setpr.refentry">
  <!ENTITY shellref SYSTEM "shell.refentry">
  <!ENTITY sleepref SYSTEM "sleep.refentry">
  <!ENTITY teeref SYSTEM "tee.refentry">
  <!ENTITY tmoderef SYSTEM "tmode.refentry">
  <!ENTITY tsmonref SYSTEM "tsmon.refentry">
  <!ENTITY unlinkref SYSTEM "unlink.refentry">
  <!ENTITY verifyref SYSTEM "verify.refentry">
  <!ENTITY xmoderef SYSTEM "xmode.refentry">
 ]>
<book id="os9guide" lang="en">
<bookinfo>
 <title>OS-9 Operating System User's Guide</title>

 <publisher>
  <publishername>Cleglen Publishing Limited</publishername>
  <address>
   <city>Cardiff</city>
  </address>
 </publisher>

<copyright>
  <year>1983</year>
  <holder>Dragon Data Ltd., and Microware Systems Corporation.</holder>
</copyright>

 <legalnotice>
  <para>All Rights Reserved. Reproduced under license from
Microware Systems Corporation.</para>
 </legalnotice>


</bookinfo>

<preface>
<title>Welcome to OS-9!</title>
<titleabbrev>Introduction</titleabbrev>
<para>
The heart of your Dragon Computer is an amazing device: the
6809 microprocessor chip. This advanced microcomputer can run the
kind of sophisticated software normally found only on much larger
and costly computers. Because the OS-9 operating system was designed
by the same people who designed the 6809 microcomputer, together
they provide an extremely efficient and powerful combination.
</para>
<para>
The foundation of a computer's software system is its
<emphasis>Operating System</emphasis> or "OS". It is the master control
program that interfaces all other software to the system's hardware. Some
of the things it must do are performing input and output operations,
coordinating memory use, and many other "housekeeping" functions. All
other software - programming languages, applications programs, etc. -
live in your computer's memory along with the OS and depend on it to
communicate with you using the keyboard and display and to store and
retrieve data on disks, etc. Because virtually all other software relies
on the OS, your computer's performance depends on the capabilities and
efficiency of its OS.
</para>

<para>
OS-9's overall structure was based on the famous UNIX<footnote id="unixdesc">
<para>
Unix is an operating system designed by Bell Telephone
Laboratories, which is becoming widely recognized as a standard for
mini and micro operating systems because of its versatility and
elegant structure.
</para>
</footnote>
operating system, which has been widely acclaimed as the operating
system of the future because of its versatility, logical structure,
and friendly user commands. The OS-9 family of advanced software is
not only more powerful than most other microcomputer scftware - it
is also much easier to learn and use.
</para>
<para>
Some of the advanced OS-9 features you'll learn about in this
book are:
</para>
<orderedlist numeration="arabic">

<listitem><para>Friendly Unix<footnoteref linkend="unixdesc">-type
user interface and environment</para></listitem>

<listitem><para>Multiuser/Multitasking Real-Time Operating System</para></listitem>

<listitem><para>Extensive support for structured, modular programming</para></listitem>

<listitem><para>Device-independent interrupt-driven input/output system</para></listitem>

<listitem><para>Multi-level directory file system</para></listitem>

<listitem><para>Fast Random-Access File System</para></listitem>

<listitem><para>Readily Expandable and Adaptable Design</para></listitem>

</orderedlist>
<para>
If you don't know what some of these thing mean yet - don't
worry. As you explore OS-9 you'll soon learn how they enhance the
capability of your Dragon Computer and make it so much easier to use
in almost any application.
</para>
<para>
OS-9 has many commands and functions - definitely more than
you can learn in an evening! The best way to become an OS-9 expert
is to study this manual carefully, section-by-section, taking tire
to try out each command or function. Because many functions affect
others, you'll find this manual extensively cross-referenced so you
can skip ahead to help you understand a new topic. Taking the time
to study this book will certainly increase your knowledge and
enjoyment of OS-9.
</para>
<para>
But if you can't wait, at least read the rest of this chapter,
scan the command descriptions in Chapter 7, and have fun
experimenting!
</para>
</preface>

<chapter>
<title>Getting Started...</title>

<section>
<title>What You Need to Run OS-9</title>
<para>
OS-9 has been tailored to run on your standard, unmodified Dragon
Computer. To use it you'll need the following things:
</para>
<itemizedlist mark="bullet">
  <listitem><para>A 64K Memory Dragon Computer</para></listitem>
  <listitem><para>A Dragon Disk Drive With Contoller Cartridge</para></listitem>
  <listitem><para>An OS-9 Dragon System Disk</para></listitem>
</itemizedlist>
<para>
OS-9 is also ready to use the following optional equipment that you
may have now or may obtain in the future:
</para>
<itemizedlist mark="bullet">
  <listitem><para>Additional Expansion Disk Drive(s)</para></listitem>
  <listitem><para>A Parallel Printer</para></listitem>
  <listitem><para>Game Joysticks</para></listitem>
  <listitem><para>Other OS-9 Compatible Languages and Software</para></listitem>
</itemizedlist>

<section>
<title>Starting the System</title>
<para>
To start up OS-9 follow these steps:

<orderedlist numeration="arabic">
<listitem><para>Turn the Dragon Computer and disk drive(s) on. You should see
the usual Basic greeting message on the screen.</para></listitem>

<listitem><para>Insert the OS-9 System Disk in drive zero and close the door.</para></listitem>

<listitem><para>Type &quot;BOOT&quot;. After a few seconds of disk activity you should
see a screen with the words &quot;OS9BOOT&quot;.</para></listitem>

<listitem><para>OS-9 will then begin
its &quot;bootstrap&quot; loading process, which
involves ten to twenty seconds of disk activity. When the system
startup has finished, a message followed by an &quot;OS9:&quot; prompt will be
displayed.</para></listitem>
</orderedlist>
</para>
</section>

<section>
<title>In Case You Have Problems Starting OS-9</title>
<itemizedlist>
<listitem><para>If Basic gives an error message after you
type &quot;BOOT&quot;, remove the
disk, turn the computer off and on, then try again. If this
repeatedly fails your OS-9 diskette may be bad.</para></listitem>

<listitem><para>Did you remember to turn the disk drive power switch on?</para></listitem>

<listitem><para>Does your Dragon Computer have 64K RAM? This is a must!</para></listitem>

<listitem><para>If your Dragon Computer doesn't seem to understand the BOOT
command, contact your dealer.</para></listitem>

<listitem><para>If the &quot;OS9BOOT message is displayed but nothing else happens,
you may have a corrupted system disk. Hopefully you did make a
backup!</para></listitem>
</itemizedlist>
</section>

<section>
<title>A Quick Introduction to the Use of the Keyboard and Disks</title>
<para>
For now, the only special keys on the keyboard of interest are
the SHIFT key which works like a typewriter shift key; the ENTER key
which you always use after typing a command or response to OS-9; and
the &lt;- left arrow key which you can use to erase typing mistakes.
</para>
<para>
Your main disk drive is known to to OS-9 as &quot;/D0&quot; and is often
called &quot;drive zero&quot;. If you have a second disk drive (drive one),
OS-9 recognizes it as &quot;/D1&quot;. Why would anybody put a &quot;/&quot; in a name?
Because all input and output devices have names like files, and
names that start with &quot;/&quot; are always device names.
</para>
</section>

<section>
<title>Initial Explorations</title>
<para>
When OS-9 first starts up, it will display a welcoming message,
and then ask you to enter the date and time. This allows OS-9 to
keep track of the date and time of creation of new files and disks.
Enter the current date and time in the format requested like this:
<screen>
             YY/MM/DD HH:MM:SS
     TIME ?  83 7 14 1420
</screen>
In the example above, the date entered was July 14, 1983. OS-9
uses 24-hour time so the date entered was 1420 hours or 2:20 PM.
Next, OS-9 will print an &quot;OS9:&quot; prompt to let you know it is ready
for you to type in a command.
</para>
<para>
Now you're ready to try some commands. A good first command to
try is DIR (for &quot;<emphasis>dir</emphasis>ectory&quot;).
This will display a list of the files
on the System Disk. Just type:
<screen>
dir
</screen>
followed by a &quot;return&quot;. OS-9 should respond with a listing of file
names which should look something like this:
<screen>
 OS9Boot     startup     CMDS      SYS      DEFS
</screen>
The file &quot;OS9Boot&quot; contains the OS-9 program in 6809 machine
language, which was loaded into memory during the bootstrap
operation.
</para>
<para>
The file &quot;startup&quot; is a &quot;command file&quot; which is automatically run
when the system starts up, and has the commands that printed the
welcoming message and asked for the time. Later, You may want to
replace this startup file with your own customized version after you
are more familiar with OS-9. Do you want to see the contents of
this file? If so, just type
<screen>
list startup
</screen>
As you can see, the LIST command displays the contents of files
that contain text (alphabetic characters). Some files like the
&quot;OS9Boot&quot; file contain binary data such as machine language
programs. These files are called &quot;binary files&quot;, and attempts to
list them will result in a jumbled, meaningless display. On the
other hand, OS-9 will complain mightily if you try to run a text
file as a program!
</para>
<para>
As you may have surmised by now, the way you ask OS-9 to run a
program or command (they're really the same thing) is to simply type
its name. Some commands like LIST require one or more names of
files or options. If so, they are typed on the same line using
spaces to separate each item.
</para>
<para>
But where did the LIST and DIR programs come from? There are
really more files on the disk than you suspect. The DIR command
showed you what is the disk's
<emphasis>root directory</emphasis> - so named because the
OS-9 filing system resembles a tree. Growing out of the root
directory are three &quot;branches&quot; - files which are additional
directories of file names instead of programs or data. They in turn
can have even more &quot;branches&quot; - ad infinitum. If you draw a map on
paper of how this works it does look like a tree.
</para>
<para>
The directory files on your system disk are called &quot;CMDS&quot;,
&quot;SYS&quot;, and &quot;DEFS&quot;.
The file &quot;CMDS&quot; is a directory that consists of
all the system commands such as DIR, LIST, FORMAT, etc. To see the
files contained in this directory, enter:
<screen>
DIR CMDS
</screen>
which tells DIR to show files on the directory file CMDS  instead
of the root directory. After you type this you should see a long
list of file names. These are the complete set of command programs
that come with OS-9 and perform a myriad of functions. Chapter
Seven explains each one in detail. The DIR command also has a handy
option to display the CMDS  directory with less typing:
<screen>
DIR X
</screen>
Whenever you want a list of available commands you can use this so
you don't have to look it up in the book. The DIR command has
options which can give you more detailed information about each file
(see sections 3.4 and 3.8.1).
</para>
</section>
</section>
<section>
<title>Making a Backup of the System Disk</title>
<para>
Before getting too much more involved in further experimentation,
NOW is the time to make one or more exact copies of your System Disk
in case some misfortune befalls your one and only master System
Disk. Making a backup involves two steps: formatting a blank disk
and running a backup program.
</para>
<section>
<title>Formatting Blank Disks</title>
<para>
Before the actual backup procedure can be done (or any fresh
diskette is used for any purpose), the blank disk which is to become
the backup disk must be initialized by OS-9's FORMAT command.
</para>
<para>
IF YOU HAVE ONLY ONE DISK DRIVE you have to be extra careful not to
accidentally FORMAT your system disk. Type:

<screen>
FORMAT /D0
</screen>

and when you see the message

<screen>
DRAGON DISK FORMATTER 1 . 2
FORMAT DRIVE /D0
Y (YES) OR N (NO)
READY?
</screen>

immediately remove your system disk and insert a blank disk
<emphasis>before</emphasis> you type &quot;Y&quot;.

IF YOU HAVE TWO DISK DRIVES place the blank disk in drive one and
type:
</para>
<screen>
FORMAT /D1
</screen>
<para>
WHEN THE BLANK DISK IS IN THE RIGHT PLACE, type &quot;Y&quot;, then &quot;ENTER&quot;.
This initiates the formatting process. IF THE CORRECT DEVICE NAME
(/D1) IS NOT DISPLAYED: TYPE N  RIGHT NOW and start over, OR YOU
MAY ERASE your System Disk.
</para>
<para>
When you are asked for a disk name, type any letter, then ENTER.
The name you give is not important. If you have only one drive,
replace the system disk after the FORMAT program has finished. If
the FORMAT program reported any errors, try again. Disks used for
backups can't have any errors. You're now ready to run the BACKUP
program.
</para>
<para>
It takes several minutes for the FORMAT program to run. During
its second phase the hexadecimal number of each track will be
displayed as it is checked for bad sectors. If any are found an
error message for each bad sector is given.
</para>
</section>

<section>
<title>Running the Backup Program</title>
<para>
The BACKUP program makes an exact duplicate of a disk. It can be
used even if you only have one disk drive.
</para>
<para>
IF YOU HAVE ONE DRIVE type
</para>
<screen>
BACKUP /D0 #32k
</screen>
<para>
The BACKUP program will prompt you to alternately insert the source
disk (the system disk) and the destination disk (the freshly
formatted disk).
</para>
<para>
IF YOU HAVE TWO DRIVES type
</para>
<screen>
BACKUP #32K
</screen>
<para>

The BACKUP program will respond with
</para>
<screen>
Ready to BACKUP from /D0 to /D0 (or /D1) ?
</screen>
<para>
Now enter Y  for yes. It will then ask:
</para>
<screen>
X IS BEING SCRATCHED
OK ?:
</screen>
<para>
Answer &quot;Y&quot; for yes again, and the BACKUP process should begin.
</para>
<para>
The BACKUP command has two phases: the first phase copies
everything from drive zero to drive one checking for errors while
reading from the master but not for &quot;write&quot; errors. The second
phase is the &quot;verify&quot; pass which makes sure everything was copied
onto the new disk correctly.  If any errors are reported during the
first (copy) pass, there is a problem with the master disk or its
drive. If errors occur during the second (verify) pass, there is a
problem with the new disk and the BACKUP program should be run
again. If BACKUP repeatedly fails on the second pass, reformat the
disk and try to BACKUP again. If BACKUP fails again, the disk is
physically defective.
</para>
<para>
After you have made your backup disk, try turning the Dragon
Computer off and restarting the system with the copy you just made.
If it works OK, store it in a safe place in case it is needed later.
You should always have a backup copy of your system disk and all
other important disks.
</para>
</section>
</section>
</chapter>

<chapter>
<title>Basic Interactive Functions</title>

<section>
<title>Running Commands and Basic Shell Operation</title>
<para>
The &quot;shell&quot; is a the part of OS-9 that accepts commands from your
keyboard. It was designed to provide a convenient, flexible, and
easy-to-use interface between you and the powerful functions of the
operating system. The shell is automatically entered after OS-9 is
started up. You can tell when the shell is waiting for input
because it displays the &quot;OS9:&quot; prompt. This prompt indicates that
the shell is active and awaiting a command from your keyboard. It
makes no difference whether you use upper-case letters, lower-case
letters, or a combination of both because OS-9 matches letters of
either case.
</para>
<para>
The command line always begins with a name of a program which can
be:
</para>

<itemizedlist>
<listitem><para>The name of a machine language program on disk</para></listitem>
<listitem><para>The name of a machine language program already in memory</para></listitem>
<listitem><para>The name of an executable program compiled by a high-level
language such as Basic09, Pascal, Cobol, etc. (See 4.8)</para></listitem>
<listitem><para>The name of a procedure file (See 4.6)</para></listitem>
</itemizedlist>
<para>
If you're a beginner, you will almost always use the first case,
which causes the program to be automatically loaded from the CMDS
directory and run.
</para>
<para>
When processing the command line, the shell searches for a
program having the name specified in the following sequence:
</para>

<orderedlist  numeration="arabic">

<listitem><para>- If the program named is already in memory, it is run.</para></listitem>

<listitem><para>- The &quot;execution directory&quot;, usually &quot;CMDS&quot;, is searched.
If a file having the name given is found, it is loaded and
run (See 5.4.1).</para></listitem>

<listitem><para>- The user's &quot;data directory&quot; is searched. If a file having
the name given is found, it is processed as a &quot;procedure
file&quot; which means that the file is assumed to contain one
or more command lines which are processed by the shell in
the same manner as if they had manually typed in one by one.</para></listitem>

</orderedlist>
<para>
Mention is made above of the &quot;data directory&quot; and the &quot;execution
directory&quot;. At all times each user is associated with two file
directories. A more detailed explanation of directories is presented
in section 3.3. The execution directory (usually CMDS) includes
files which are executable programs.
</para>
<para>
The name given in the command line may be optionally followed by
one or more &quot;parameters&quot; which are passed to the program called by
the shell.
</para>
<para>
For example, in the command line:
</para>
<screen>
LIST FILE1
</screen>
<para>
the program name is LIST, and the parameter passed to it is FILE1.
</para>
<para>
A command line may also include one or more &quot;modifiers&quot; which are
specifications used by the shell to alter the program's standard
input/output files or memory assignments (See 4.2).


</para>
<section>
<title>Sending Output to the Printer</title>
<para>
Normally, most commands and programs display output on the Color
Computer video display. The output of these programs can
alternatively be printed by specifying output redirection on the
command line. This is done by including the following modifier to
at the end of any command line:
</para>
<screen>
&gt;/P
</screen>
<para>
The &quot;&gt;&quot; character tells the shell to redirect output (See 4.3.2) to
the printer using the Dragon's parallel port, which has the device
name &quot;/P&quot; (See 3.2). For example, to redirect the output of the
&quot;dir&quot; command to the printer, enter:
</para>
<screen>
DIR &gt;/P
</screen>
<para>
The &quot;xmode&quot; command can be used to set the printer port's
operating mode such as auto line feed, etc. For example, to examine
the printer's current settings, type:
</para>
<screen>
xmode /P
</screen>
<para>
To change any of these type XMODE  followed by the new value.
For example, to set the printer port for automatic line feeds at the
end of every line, enter:
</para>
<screen>
xmode /P lf;
</screen>
</section>
</section>

<section>
<title>Shell Command Line Parameters</title>
<para>
Parameters are generally used to either specify file name(s) or
to select options to be used by the program specified in the command
line given to the shell. Parameters are separated from the command
name and from each other by space characters (hence parameters and
options cannot themselves include spaces). Each command program
supplied with OS-9 has an individual description in the last section
of this manual which describe the correct usage of the parameters of
each command.
</para>
<para>
For example, the LIST program is used to display the contents of
a text file on your display. It is necessary to tell to the LIST
program which file it is to be displayed, therefore, the name of the
desired file is given as a parameter in the command line. For
example, to list the file called startup  (the system initialization
procedure file), you enter the command line:
</para>
<screen>
LIST STARTUP
</screen>
<para>
Some commands have two parameters. For example, the COPY command is
used to make an exact copy of a file. It requires two parameters:
The name of the file to be copied and the name of the file which is
to be the copy, for example:
</para>
<screen>
COPY STARTUP NEWSTARTUP
</screen>
<para>
Other commands have parameters which select options. For example:
</para>
<screen>
DIR
</screen>
<para>
shows the names of the files in the user's data directory. Normally
it simply lists the file names only, but if the &quot;E&quot;
(for <emphasis>e</emphasis>ntire)
option is given, it will also give complete statistics for each file
such as the date and time created, size, security codes, etc. To do
so enter:
</para>
<screen>
DIR E
</screen>
<para>
The DIR command also can accept a file name as a parameter which
specifies a directory file other than the (default) data directory.
For example, to list file names in the directory sys , type:
</para>
<screen>
DIR SYS
</screen>
<para>
It is also possible to specify both a directory name parameter and
the e  option, such as:
</para>
<screen>
DIR SYS E
</screen>
<para>
giving file names and complete statistics (See example in 3.8.1).
</para>
</section>

<section>
<title>Some Common Command Formats</title>
<para>
This section is a summary of some commands commonly used by new
or casual OS-9 users, and some common formats. Each command is
followed by an example. Refer to the individual command
descriptions in Section 8 for more detailed information and
additional examples. Parameters or options shown in brackets are
optional. Whenever a command references a directory file name, the
file <emphasis>must</emphasis> be a directory file.

<screen>
CHD filename                               chd DATA.DIR
</screen>
Changes the current <emphasis>data</emphasis> working directory to
the <emphasis>directory</emphasis> file specified.
<screen>
COPY filename1 filename2                   copy oldfile newfile
</screen>
Creates filename2  as a new file, then copies all data from
&quot;filename1&quot; to it. &quot;filename1&quot; is not affected.
<screen>
DEL filename                               del oldstuff
</screen>
Deletes (destroys) the file specified.
<screen>
DIR [filename] [e] [x]                     dir myfiles e
</screen>
List names of files contained in a directory. If the &quot;x&quot; option is
used the files in the current <emphasis>execution</emphasis>
directory are listed,
othervise, if no directory name is given, the current
<emphasis>data</emphasis> directory will be listed.
The &quot;e&quot; option selects the long format
which shows detailed information about each file.
<screen>
FREE devicename                            free /d1
</screen>
Shows how much free space remains on the disk whose name is given.
<screen>
LIST filename                              list script
</screen>
Displays the (text) contents of the file on the terminal.
<screen>
MAKDIR filename                            makdir NEWFILES
</screen>
Creates a new directory file using the name given. Often followed
by a &quot;chd&quot; command to make it the new working data directory.
<screen>
RENAME filename1 filename2                 rename zip zap
</screen>
Changes the name of filename1 to filename2.
</para>
</section>

<section>
<title>Using the Keyboard and Video Display</title>
<para>
OS-9 has many features to expand the capability of the Dragon
keyboard and video display. The video display has screen pause,
upper/lower case, and graphics functions. The keyboard can generate
all ASCII characters and has a type-ahead feature that permits you
to enter data before requested by a program (except if the disk is
running because interrupts are temporarily disabled). Appendix C of
this manual is a list of the characters and codes that can be
generated from the keyboard. The keyboard/video display can be used
as a file known by the name &quot;/TERM&quot;.
</para>

<section>
<title>Video Display Functions</title>
<para>
The Dragon uses reverse video (green letters in a black box) to
represent lower-case letters. Normally they are not used, so you
have to turn them on if you want to use them with the command:
</para>
<screen>
TMODE -UPC
</screen>
<para>
The screen pause feature stops programs after 16 lines have been
displayed. Output will continue if you hit any key. Normally this
feature is on. It can be turned on or off with the TMODE command as
follows:
</para>
<screen>
TMODE -PAUSE              turns pause mode off
TMODE PAUSE               turns pause mode on
</screen>
<para>
The display system also has a complete set of commands to emulate
commercial data terminals, plus a complete set of graphics commands.
These are described in detail in Appendix D.
</para>
</section>

<section>
<title>Keyboard Shift and Control Functions</title>
<para>
Two keys are used in combination with other keys to change their
meaning. The SHIFT KEY selects between upper case and lower case
letters or punctuation, and the CLEAR key can be used to generate
control characters .
</para>
<para>
The keyboard has a shift lock function similar to a typewriter's,
which is normally &quot;locked&quot;. The keyboard's shift lock may be
reversed by depressing the control key (CLEAR) and 0 keys
simultaneously. The shift lock only affects the letter (A-Z) keys.
When the keyboard is locked, these keys generate upper case letters,
and lower case only if the SHIFT key is depressed. When the
keyboard is unlocked, the reverse is true, e.g., lower case letters
are generated unless the SHIFT key is depressed at the same time as
a letter key.
</para>
</section>

<section>
<title>Control Key Functions</title>
<para>
There are a number of useful control functions that can be
generated from the keyboard. Many of these functions use &quot;control
keys&quot; which are generated by simultaneously depressing the CLEAR key
plus some other key. For example, to generate the character for
CONTROL D press the CLEAR and D keys at the same time.
</para>
<variablelist>
<varlistentry>
  <term>CONTROL A</term>
  <listitem>
<para>
Repeat previous input line. The last line entered will be redisplayed but
<emphasis>not</emphasis> processed, with the cursor positioned at the end of
the line. You may hit return to enter the line, or edit the line by
backspacing, typing over characters to correct them, and entering
control A again to redisplay the edited line.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>CONTROL D</term>
  <listitem>
<para>
Redisplay present input on next line.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>CONTROL W</term>
  <listitem>
<para>
Display Wait - This will temporarily halt output to the display so
the screen can be read before the data scrolls off. Output is
resumed when any other key is hit.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>CONTROL 0</term>
  <listitem>
<para>
Shift lock. Reverses present shift lock state.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>BREAK KEY (or CONTROL E)</term>
  <listitem>
<para>
Program abort - Stops the current running program
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>SHIFT BREAK KEY (or CONTROL C)</term>
  <listitem>
<para>
Interrupt - Reactivates Shell while keeping program running as
background task.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>CONTROL BREAK KEY (ESCAPE)</term>
  <listitem>
<para>
End-of-File - This key is used to send an end-of-file to programs
that read input from the terminal in place of a disk or tape file.
It must be the first character on the line in order for it to be
recognized.
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>LEFT ARROW (OR CONTROL H)</term>
  <listitem>
<para>
Backspace - erase previous character
</para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>SHIFT LEFT ARROW (or CONTROL X)</term>
  <listitem>
<para>
Line Delete - erases the entire current line.
</para>
  </listitem>
</varlistentry>
</variablelist>
</section>
</section>

</chapter>
<chapter>
<title>The OS-9 File System</title>
<section>
<title>Introduction to the Unified Input/Output System</title>
<para>
OS-9 has a unified input/output system in which data transfers to
ALL I/O devices are performed in almost exactly the same manner,
regardless of the particular hardware devices involved. It may seem
that the different operational characteristics of the I/O devices
might make this difficult. After all, line printers and disk drives
behave much differently. However, these differences can mostly be
overcome by defining a set of standardized
<emphasis>logical functions</emphasis> for
all devices and by making all I/O devices conform to these
conventions, using software routines to eliminate hardware
dependencies wherever possible. This produces a much simpler and
more versatile input/output system.
</para>
<para>
OS-9's unified I/O system is based upon logical entities called
&quot;I/O paths&quot;. Paths are analogous to &quot;software I/O channels&quot; which
can be routed from a program to a mass-storage file, any other I/O
device, or even another program. Another way to say the same thing
is that paths are files, and all I/O devices behave as files.
</para>
<para>
Data transferred through paths may be processed by OS-9 to
conform to the hardware requirements of the specific I/O device
involved. Data transfers can be either bidirectional (read/write)
or unidirectional (read only or write only), depending on the device
and/or how the path was established.
</para>
<para>
Data transferred through a path is considered to be a stream of
8-bit binary bytes that have no specific type or value: what the
data actually represents depends on how it is used by each program.
This is important because it means that OS-9 does not require data
to have any special format or meaning.
</para>
<para>
Some of the advantages of the unified I/O system are:
</para>
<itemizedlist mark="square">
<listitem><para>
Programs will operate correctly regardless of the particular I/O
devices selected and used when the program is actually executed.
</para></listitem>
<listitem><para>
Programs are highly portable from one computer to another, even
when the computers have different kinds of I/O devices.
</para></listitem>
<listitem><para>
I/O can be redirected to alternate files or devices when the
program is run, without having to alter the program.
</para></listitem>
<listitem><para>
New or special device driver routines can easily be created and
installed by the user.
</para></listitem>
</itemizedlist>
</section>

<section>
<title>Pathlists: How Paths Are Named</title>
<para>
Whenever a path is established (or &quot;opened&quot;), OS-9 must be given
a description of the &quot;routing&quot; of the path. This description is
given in the form of a character string called a &quot;pathlist&quot;. It
specifies a particular mass-storage file, directory file, or any
other I/O device. OS-9 &quot;pathlists&quot; are
similar to &quot;filenames&quot; used
by other operating systems.
</para>
<para>
The name &quot;pathlist&quot; is used instead
of &quot;pathname&quot; or &quot;filename&quot;
because in many cases it is a list consisting of more than one name
to specify a particular I/O device or file. In order to convey all
the information required, a pathlist may include a device name, one
or more directory file names and a data file name. Each name within
a pathlist is separated by slash &quot;/&quot; characters.
</para>
<para>
Names are used to describe three kinds of things:

<itemizedlist>
<listitem><para>Names of Physical I/O Devices</para></listitem>
<listitem><para>Names of Regular Files</para></listitem>
<listitem><para>Names of Directory Files</para></listitem>
</itemizedlist>


Names can have one to 29 characters, all of which are used for
matching. They must becin with an upper- or lower-case letter
followed by any combination of the following characters:
</para>

<simplelist>
<member>uppercase letters: A - Z</member>
<member>lowercase letters: a - z</member>
<member>decimal digits: 0 - 9</member>
<member>underscore: _</member>
<member>period: .</member>
</simplelist>

<para>
Here are examples of <emphasis>legal</emphasis> names:
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2.5in">
<colspec colwidth="2.5in">
<tbody>
<row>
<entry>raw.data.2</entry>
<entry>projectreview.backup</entry>
</row>
<row>
<entry>reconciliation.report</entry>
<entry>X042953</entry>
</row>
<row>
<entry>RJJones</entry>
<entry>search.bin</entry>
</row>
</tbody>
</tgroup>
</informaltable>

Here are examples of <emphasis>illegal</emphasis> names:

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="3.1in">
<colspec colwidth="2.0in">
<tbody>
<row>
<entry>22November</entry>
<entry>(does not start with a letter)</entry>
</row>
<row>
<entry>max*min</entry>
<entry>(* is not a legal character)</entry>
</row>
<row>
<entry>.data</entry>
<entry>(does not start with a letter)</entry>
</row>
<row>
<entry>open orders</entry>
<entry>(cannot contain a space)</entry>
</row>
<row>
<entry>this.name.obviously.has.more.than.29.characters</entry>
<entry>(too long)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>

<section>
<title>I/O Device Names</title>
<para>
Each physical input/output device supported by the system must
have a unique name. The actual names used are defined when the
system is set up and cannot be changed while the system is running.
The device names used for the Dragon Computer are:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.7in">
<colspec colwidth="2in">
<tbody>
<row>
<entry>TERM</entry>
<entry>Video display/keyboard</entry>
</row>
<row>
<entry>P</entry>
<entry>Printer port</entry>
</row>
<row>
<entry>D0</entry>
<entry>Disk drive unit zero</entry>
</row>
<row>
<entry>D1</entry>
<entry>Disk drive unit one</entry>
</row>
<row>
<entry>PIPE</entry>
<entry>Pipes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Device names may only be used as the first name of a pathlist,
and must be preceded by a slash &quot;/&quot; character to indicate that the
name is that of an I/O device. If the device is not a disk or
similar device the device name is the only name allowed. This is
true for devices such as terminals, printers, etc. Some examples of
of pathlists that refer to I/O devices are:
</para>

<simplelist>
<member>/TERM</member>
<member>/P</member>
<member>/D1</member>
</simplelist>

<para>
I/O device names are actually the names of the &quot;device descriptor
modules&quot; kept by OS-9 in an internal data structure called the
&quot;module directory&quot; (See the OS-9 System Programmer's manual for more
information about device driver and descriptor modules). This
directory is automatically set up during OS-9's system start up
sequence, and updated as modules are added or deleted while the
system is running.
</para>
</section>

<section>
<title>Multifile Devices And Directory Files</title>
<para>
Multifile devices are mass storage devices (usually disk systems)
that store data organized into separate logical entities called
&quot;files&quot;. Each file has a name which is entered in a directory file.
Every multifile device has a master directory (called the &quot;root
directory&quot;) that includes the names of the files and sub-directories
stored on the device. The root directory is created automatically
when the disk is initialized by the &quot;format&quot; command.
</para>
<para>
Pathlists that refer to multifile devices may have more than one
name. For example, to refer to the file &quot;mouse&quot; whose name appears
in the root directory of device &quot;D1&quot; (disk drive one) the following
pathlist is used:
</para>
<para>

/d1/mouse

</para>
<para>
When OS-9 is asked to create a path, it uses the names in the
pathlist sequentially from left to right to search various
directories to obtain the necessary routing information. These
directories are organized as a tree-structured hierarchy. The
highest-level directory is called the &quot;device directory&quot;, which
contains names and linkages to all the I/O devices on a given
system. If any of the devices are of a multifile type they each
have a root directory, which is the next-highest level.
</para>
<para>
The diagram below is a simplified file system tree of a typical
OS-9 system disk. Note that device and directory names are capitalized
and ordinary file names are not. This is a customary (but
not mandatory) practice which allows you to easily identify directory
files using the short form of the &quot;dir&quot; command.
</para>
<literallayout class="Monospaced">
                      System Device Directory
              +---------------------------------+
              !            !          !         !
              D0          TERM        P         D1
              !                                 !
              !                                 !
              !                                 !
      D0 Root Directory                 D1 Root Directory
  +----------------------+           +----------------------+
  !           !          !           !          !           !
DEFS      startup      CMDS        file1      file2        file3
  !                      !
  !                      !
  !                      !
--+--         +-----+----+-----+-----+ 
  !           !     !    !     !     !
OS9Defs     copy  list  dir   del  backup
</literallayout>
<para>
The device names in this example system are &quot;TERM&quot;,
&quot;P&quot;, &quot;D0&quot; and
&quot;D1&quot;. The root directory of device
&quot;D0&quot; includes two directory
files, DEFS and CMDS, and one ordinary file &quot;startup&quot;. Notice that
device &quot;D1&quot; has in its root directory three ordinary files. In
order to access the file &quot;file2&quot; on
device &quot;d1&quot;, a pathlist having
two names must be used:
<screen>
list /d1/file2
</screen>
To construct a pathlist to access the file &quot;dir&quot; on device
&quot;d0&quot; it is necessary to include in the pathlist the name of the
intermediate directory file &quot;CMDS&quot;. For example, to copy this file
requires a pathlist having three names to describe the &quot;from&quot; file:
<screen>
copy /d0/cmds/dir temp
</screen>
</para>
</section>

<section>
<title>Creating and Using Directories</title>
<para>
It is possible to create a virtually unlimited number of levels
of directories on a mass storage device using the &quot;makdir&quot; command.
Directories are a special type of file (see 3.8.1). They can be
processed by the same I/O functions used to access regular files
which makes directory-related processing fairly simple.
</para>
<para>
To demonstrate how directories work, assume that the disk in
drive one (&quot;d1&quot;) has been freshly formatted so that it has a root
directory only. The build command can be used to create a text file
on &quot;d1&quot;. The build command will print out &quot;?&quot; as a prompt to
indicate that it is waiting for a text line to be entered. It will
place each line into the text file until an empty line with only a
carriage return is entered, as shown below:
</para>
<screen>
OS9: build /d1/file1
? This is the first file that
? we created.
? [ENTER]
</screen>

<para>
The &quot;dir&quot; command will now indicate the existence of the new file:
</para>

<screen>
OS9: dir /d1

   Directory of /d1  15:45:29
file1
</screen>

<para>
The &quot;list&quot; command can be used to display the text stored in the
file:
</para>

<screen>
OS9: list /d1/file1

This is the first file
that we created.
</screen>

<para>
The &quot;build&quot; command again is again used to create two more text
files:
</para>

<screen>
OS9: build /d1/file2
? This is the second file
? that we created.
? [ENTER]

OS9: build /d1/file3
? This is another file.
? [ENTER]
</screen>

<para>
The dir command will now show three file names:
</para>

<screen>
OS9: dir /d1
   Directory of /D1  15:52:29
file1           file2           file3
</screen>

<para>
To make a new directory in this directory, the &quot;makdir&quot; command is
used. The new directory will be called &quot;NEWDIR&quot;. Notice that
throughout this manual directory names are always capitalized. This
is <emphasis>not</emphasis> a requirement of OS-9 (see 3.1) . Rather, it is a
practice popular with many OS-9 users because it allows easy identification
of directory files at all times (assuming all other file names use
lower-case letters).
</para>

<screen>
OS9: makdir /D1/NEWDIR
</screen>

<para>
The directory file &quot;NEWDIR&quot; is now a file listed in D1's root
directory:
</para>

<screen>
OS9: dir /D1

   Directory of /D1  16:04:31
file1           file2           file3          NEWDIR
</screen>

<para>
Now we will create a new file and put in the new directory, using
the COPY command to duplicate &quot;file1&quot;:
</para>
<screen>
OS9: COPY /D1/file1 /D1/NEWDIR/file1.copy
</screen>
<para>
Observe that the second pathlist now has three names: the name of
the root directory (&quot;D1&quot;), the name of the next lower directory
(&quot;NEWDIR&quot;), then the actual file name (&quot;file1.copy&quot;). Here's what
the directories look like now:
</para>
<screen>
          D1 Root Directory
    +---------+--------+--------+
    !         !        !        !
  NEWDIR    file1    file2    file3
    !
    !
file1.copy
</screen>
<para>
The dir command can now show the files in the new directory:
</para>
<screen>
OS9: dir /D1/NEWDIR

   Directory of /D1/NEWDIR
file1.copy
</screen>
<para>
It is possible to use &quot;makdir&quot; to create additional new directories
within &quot;NEWDIR&quot;, and so on, limited only by available disk
space.
</para>
</section>

<section>
<title>Deleting Directory Files</title>
<para>
The &quot;del&quot; command cannot be used to directly delete a directory
file. If a directory file that still contained file names were to
be deleted, OS-9 would have no way to access the files or to return
their storage to the unallocated storage pool. Therefore, the
following sequence must be performed to delete a directory file:
</para>
<para>
1 - All file names in the directory must be deleted.
</para>
<para>
2 - The &quot;attr&quot; command is used to turn off the files directory
attrribute (-d option), making it an ordinary file (see 3.8).
</para>
<para>
3 - The file may now be deleted using the &quot;del&quot; command.
</para>
<para>
A simpler alternative is to use the DELDIR command to automatically
perform all these steps for you.
</para>
</section>

<section>
<title>Additional Information About Directories</title>
<para>
The OS-9 directory system is very useful because it allows each
user to privately organize files as desired (by project, function,
etc.), without affecting other files or other user's files. Another
advantage of the hierarchical directory system is that files with
identical names can be kept on the same device as long as the names
are in different directories. For example, you can have a set of
test files to check out a program using the same file names as the
program's actual working files. You can then run the program with
test data or actual data simply by switching directories.
</para>
<para>
Here are some important characteristics relating to use of directory
files:
</para>
<itemizedlist>
<listitem><para>
Directories have the same ownership and security attributes
and rules as regular files. See Section 3.6.
</para></listitem>
<listitem><para>
The name of a given file appears in exactly one directory.
</para></listitem>
<listitem><para>
Files can only be added to directories when they are created.
</para></listitem>
<listitem><para>
A file and the directory in which its name is kept must reside on
the same device.
</para></listitem>
</itemizedlist>
</section>

<section>
<title>Using and Changing Working Directories</title>
<para>
Each program (process) has two &quot;working directories&quot; associated
with it at all times: a &quot;data directory&quot; and an &quot;execution
directory&quot;. The working directory mechanism allows the name searching
involved in pathlist processing to start at any level (subtree)
of the file system hierarchy. Any directory that the user has
permission to access (see 3.8) can be made a working directory.
</para>
<para>
The rules used to determine whether pathlists refer to the
current working directory or not are simple:
</para>
<para>
---&gt; When the first character of a pathlist IS a &quot;/&quot;,
processing of the pathlist starts at the device directory,
e.g., the first name MUST be a device name.
</para>
<para>
---&gt; When the first character of a pathlist IS NOT a &quot;/&quot;,
processing of the pathlist starts at the current working
directory.
</para>
<para>
Notice that pathlists starting with a &quot;/&quot;
<emphasis>must</emphasis> be complete, in
other words, they must have all names required to trace the pathlist
from the device directory down through all intermediate directories
(if any). For example:
</para>
<informalexample>
<para>
/d2/JOE/WORKINGFILES/testresults
</para>
</informalexample>
<para>
On the other hand, use of the current working directory allows
all names in the file hierarchy tree to be implied instead of
explicitly given. This not only makes pathlists shorter, but allows
OS-9 to locate files faster because (typically) fewer directories
need be searched. For example, if the current working directory is
&quot;/D1/PETE/GAMES&quot; and a pathlist is given such as:
</para>
<para>
baseball
</para>
<para>
the actual pathlist <emphasis>implied</emphasis> is:
</para>
<para>
/D1/PETE/GAMES/baseball
</para>
<para>
Pathlists using working directories can also specify additional
lower-level directories. Referring to the example above, the
pathlist:
</para>
<para>
ACTION/racing
</para>
<para>
implies the complete pathlist:
</para>
<para>
/D1/PETE/GAMES/ACTION/racing
</para>

<section>
<title>Automatic Selection of Working Directories</title>
<para>
Recall that two working directories are referred to as the
&quot;current execution directory&quot; and the &quot;current data directory&quot;. The
reason two working directories are maintained is so that files
containing
<emphasis>programs</emphasis> can be organized in different directories than
files containing <emphasis>data</emphasis>.
OS-9 automatically selects either working
directory, depending on the usage of the pathlist:
</para>
<para>
---&gt; OS-9 will search the execution directory when it attempts to
load files into memory assumed to be executable programs. This
means that programs to be run as commands or loaded into
memory must be in the current execution directory (See 5.4.1).
</para>
<para>
---&gt; The data directory is used for all other file references (such
as text files, etc.)
</para>
<para>
Immediately after startup, OS-9 will set the data directory to be
(the root directory of) the system disk drive (usually &quot;D0&quot;), and
the working directory to be a directory called &quot;cmds&quot; on the same
drive (&quot;/D0/cmds&quot;). On timesharing systems, the &quot;login&quot; command
selects the initial execution and data directories to the file names
specified in each user's information record stored in the system
password file(ref. 5.4.2).
</para>
<para>
Here is an example of a shell command statement using the default
working directory notation, and its equivalent expansion:
</para>
<screen>
copy file1 file2
</screen>
<para>
If the current execution directory is &quot;/D0/CMDS&quot; and the current
data directory is &quot;/D0/JONES&quot;, the same command, fully expanded to
show complete pathlists implied is:
</para>
<screen>
OS9: /D0/CMDS/copy /D0/JONES/filel /D0/JONES/file2
</screen>
<para>
Notice that the first pathlist &quot;copy&quot; expands to the current working
directory pathlist because it is assumed to be an executable program
but the two other file names expand using the data directory because
they are not assumed to be executable.
</para>
</section>

<section>
<title>Changing Current Working Directories</title>
<para>
The built-in shell commands &quot;chd&quot; and &quot;chx&quot; can be used to
independently change the current working data and execution
directories, respectively. These command names must be followed by
a pathlist that describes the new directory file. You must have
permission to access the directory according to normal file security
rules (See 3.8). Here are some examples:
</para>
<screen>
OS9: chd /D1/MY.DATAFILES

OS9: chx /D0/TESTPROGRAMS
</screen>
<para>
When using the CHD or CHX commands, pathlists work the same as they
do for regular files, except for the last name in the pathlist must
be a directory name. If the pathlist begins with a &quot;/&quot; , OS-9 will
begin searching in the device directory for the new working
directory, otherwise searching will begin with the present directory
(See 3.6). For example, the following sequence of commands set the
working directory to the same file:
</para>
<screen>
OS9: CHD /D1/SARAH
OS9: CHD PROJECT1

OS9: CHD /D1/SARAH/PROJECT1    (same effect as above)
</screen>
</section>

<section>
<title>Anonymous Directory Names</title>
<para>
Sometimes is useful to be able to refer to the current directory
or the next higher-level directory, but its name (full pathlist) may
not be known. Because of this, special &quot;name substitutes&quot; are
available. They are:
</para>
<para>
&quot;.&quot; refers to the present working directory
</para>
<para>
&quot;..&quot; refers to the directory that contains the name of the present
directory (e.g., the next highest level directory)
</para>
<para>
&quot;...&quot; refers to directory two levels up, and so on
</para>
<para>
These can be used in place of pathlists and/or the first name in a
pathlist. Here are some examples:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in">
<colspec colwidth="3in">
<tbody>
<row>
<entry>OS9: dir .</entry>
<entry>lists file names in the working data directory</entry>
</row>
<row>
<entry>OS9: dir ..</entry>
<entry>lists names in the working data directory's parent directory.</entry>
</row>
<row>
<entry>OS9: DEL ../temp</entry>
<entry>deletes the file &quot;temp&quot; from the
working data directory's parent directory.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The substitute names refer to either the execution or data
directories, depending on the context in which they are used (See
3.7.1). For example, if &quot;..&quot; is used in a pathlist of a file which
will be loaded and/or executed, it will represent the parent
directory of the execution directory. Likewise, if &quot;.&quot; is used in a
pathlist describing a program's input file, it will represent the
current data directory.
</para>
</section>
</section>

<section>
<title>The File Security System</title>
<para>
Every file (including directory files) has properties called
<emphasis>ownership</emphasis>
and <emphasis>attributes</emphasis> which determine who may access the file and
how it many be used.
</para>
<para>
OS-9 automatically stores with each file the user number
associated with the process that created it. This user is considered
to be the &quot;owner&quot; of the file.
</para>
<para>
Usage and security functions are based on &quot;attributes&quot;, which
define how and by whom the file can be accessed. There are a total
of seven attributes, each of which can be turned &quot;off&quot; or
&quot;on&quot;
independently. The &quot;d&quot; attribute is used to indicate (when on) that
the file is a directory file. The other six attributes control
whether the file can be read, written to, or executed, by either the
owner or by the &quot;public&quot; (all other users). Specifically, these six
attributes are:
</para>
<para>
WHITE PERMISSION FOR OWNER: If on, the owner may write to the file
or delete it. This permission can be used to protect important
files from accidental deletion or modification.
</para>
<para>
READ PERMISSION FOR OWNER: If on, the owner is allowed to read
from the file. This can be used to prevent &quot;binary&quot; files from
being used as &quot;text&quot; files (See 3.9)
</para>
<para>
EXECUTE PERMISSION FOR OWNER: If on, the owner can load the file into memory
and execute it. Note that the file <emphasis>must</emphasis> contain one or
more valid OS-9 format memory modules in order to actually load (See
3.9.4 and 5.4.1).
</para>
<para>
The following &quot;public permissions&quot; work the same way as
the &quot;owner permissions&quot; above but are applied to processes having
DIFFERENT user numbers than the file's owner.
</para>
<para>
WRITE PERMISSION FOR PUBLIC - If on, any other user may write to or
delete the file.
</para>
<para>
READ PERMISSION FOR PUBLIC - If on, any other user may read (and
possibly copy) the file.
</para>
<para>
EXECUTE PERMISSION FOR PUBLIC - If on, any other user may execute
the file.
</para>
<para>
For example, if a particular file had all permissions on except
&quot;write permit to public&quot; and &quot;read permit to public&quot;, the owner
would have unrestricted access to the file, but other users could
execute it, but not read, copy, delete, or alter it.
</para>

<section>
<title>Examining and Changing File Attributes</title>
<para>
The &quot;DIR&quot; command may be used to examine the security permissions
of the files in any particular directory when the &quot;e&quot; option is
used. An example using the &quot;dir e&quot; command to show the detailed
attributes of the files in the current working directory is:
</para>
<screen>
   Directory of . 10:20:44

Owner Last Modified Attributes Sector Bytecount Name
----- ------------- ---------- ------ --------- ----
   1  81/05/29 1402 --e--e-r       47        42 file1
   0  81/10/12 0215 ---wr-wr       48        43 file2
   3  81/04/29 2335 -s----wr       51        22 file3
   1  82/01/06 1619 d--wr-wr       6D       800 NEWDIR
</screen>

<para>
This display is fairly self-explanatory. The &quot;attributes&quot; column
shows which attributes are currently on by the presence or absence
of associated characters in the following format:
</para>
<para>
 dsewrewr
</para>

<para>
The character positions correspond to from left to right: directory;
sharable; public execute; public write; public read; owner execute;
owner write; owner read. The &quot;attr&quot; command is used to examine or
change a file's attributes. Typing &quot;attr&quot; followed by a file name
will result in the present attributes to be displayed, for example:
</para>

<screen>
OS9: attr file2
-s-wr-ewr
</screen>

<para>
If the command is used with a list of one or more attribute abbreviations,
the file's attributes will be changed accordingly (if
legal). For example, the command:
</para>
<screen>
OS9: attr file2 pw pr -e -pe
</screen>
<para>
enables public write and public read permissions and removes execute
permission for both the owner and the public.
</para>
<para>
The &quot;directory&quot; attribute behaves somewhat differently than the
read, write, and execute permissions. This is because it would be
quite dangerous to be able to change directory files to normal files
(See 3.5), and creation of a directory requires special initialization
(See 3.4). Therefore, the &quot;attr&quot; command
<emphasis>cannot</emphasis> be used to turn
the directory (d) attribute on (only &quot;makdir&quot; can), and can be used
to turn it off <emphasis>only</emphasis> if the directory is empty.
</para>
</section>
</section>

<section>
<title>Reading and Writing From Files</title>
<para>
A single file type and format is used for all mass storage files.
Files store an ordered sequence of 8-bit bytes. OS-9 is not usually
sensitive to the contents of files for most functions. A given file
may store a machine language program, characters of text, or almost
anything else. Data is written to and read from files exactly as
given. The file can be any size from zero up to the maximum
capacity of the storage device, and can be expanded or shortened as
desired.
</para>
<para>
When a file is created or opened a &quot;file pointer&quot; is established
for it. Bytes within the file are addressed like memory, and the
file pointer holds the &quot;address&quot; of the next byte in the file to be
written to or read from. The OS-9 &quot;read&quot; and &quot;write&quot; service
functions always update the pointer as data transfers are performed.
Therefore, successive read or write operations will perform sequential data transfers.
</para>
<para>
Any part of a file can also be read or written in non-sequential
order by using a function called &quot;seek&quot; to reposition the file
pointer to any byte address in the file. This is used when random
access of the data is desired.
</para>
<para>
To expand a file, you can simply write past the previous end of
the file. Reading up to the last byte of a file will cause the next
&quot;read&quot; request to return an end-of-file status.
</para>

<section>
<title>File Usage in OS-9</title>
<para>
Even though there is physically only one type of file, the logical
usage of files in OS-9 covers a broad spectrum. Because all
OS-9 files have the same physical type, commands such as &quot;copy&quot;,
&quot;del&quot;, etc., can be used with any file regardless of its logical
usage. Similarly, a particular file can be treated as having a
different logical usage at different times by different programs. The
main usage of files covered in this section are:
</para>
<simplelist>
<member>TEXT</member>
<member>RANDOM ACCESS DATA</member>
<member>EXECUTABLE PROGRAM MODULES</member>
<member>DIRECTORIES</member>
<member>MISCELLANEOUS</member>
</simplelist>
</section>

<section>
<title>Text Files</title>
<para>
These files contain variable-length sequences (&quot;lines&quot;) of ASCII
characters. Each line is terminated by a carriage return character.
Text files are used for program source code, procedure files,
messages, documentation, etc. The Text Editor operates on this file
format.
</para>
<para>
Text files are usually read sequentially, and are supported by
almost all high-level languages (such as BASIC09 READ and WRITE
statements). Even though is is possible to randomly access data at
any location within a text file, it is rarely done in practice
because each line is variable length and it is hard to locate the
beginning of each line without actually reading the data to locate
carriage return characters.
</para>
<para>
The content of text files may be examined using the &quot;list&quot;
command.
</para>
</section>

<section>
<title>Random Access Data Files</title>
<para>
Random-access data files are created and used primarily from
within high-level languages such as Basic09, Pascal, C, and Cobol.
In Basic09 and Pascal, &quot;GET&quot;, &quot;PUT&quot;, and &quot;SEEK&quot; functions operate on
random-access files.
</para>
<para>
The file is organized as an ordered sequence of &quot;records&quot;. Each
record has exactly the same length, so given a record's numerical
index, the record's beginning address within the file can be
computed by multiplying the record number by the number of bytes
used for each record. Thus, records can be directly accessed in any
order.
</para>
<para>
In most cases, the high-level language allows each record to be
subdivided into &quot;fields&quot;. Each field generally has a fixed length
and usage for all records within the file. For example, the first
field of a record may be defined as being 25 text characters, the
next field may be two bytes long and used to hold 16-bit binary
numbers, etc.
</para>
<para>
It is important to understand that OS-9 itself does not directly
process or deal with records other than providing the basic file
functions required by all high-level languages to create and use
random-access files.
</para>
</section>

<section>
<title>Executable Program Module Files</title>
<para>
These files are used to hold program modules generated by the
assembler or <emphasis>compiled</emphasis> by high-level languages.
Each file may
contain <emphasis>one or more</emphasis> program modules.
</para>
<para>
OS-9 program modules resident in memory have a standard module
format that, besides the object code, includes a &quot;module header&quot; and
a CRC check value. Program module(s) stored in files contain exact
binary copies of the programs as they will exist in memory, and not
one byte more (See 5.4.1). OS-9 does not require a &quot;load record&quot;
system commonly used by other operating systems because OS-9
programs are position-independent code and therefore do not have to
be loaded into specific memory addresses.
</para>
<para>
In order for OS-9 to load the program module(s) from a file, the
file itself must have execute permission (See 3.8) and each module
must have a valid module header and CRC check value. If a program
module has been altered in any way, either as a file or in memory,
its CRC check value will be incorrect And OS-9 will refuse to load
the module. The &quot;verify&quot; command can be used to check the correctness
of the check values, and update them to corrected values if
necessary.
</para>
<para>
On Level One systems, if a file has two or more modules, they are
treated as independent entities after loading and reside at different memory regions.
</para>
<para>
Like other files that contain &quot;binary&quot; data, attempts to &quot;list
program files will result in the display of random characters on the
terminal giving strange effects. The &quot;dump&quot; command can be used to
safely examine the contents of this kind of file in hexadecimal and
controlled ASCII format.
</para>
</section>

<section>
<title>Directory Files</title>
<para>
Directory files play a key role in the OS-9 file system.
Sections 3.3 through 3.7 of this chapter describe how they are used by
various OS-9 features.
</para>
<para>
Directory files can only be created by the &quot;makdir&quot; command, and
can be identified by the &quot;d&quot; attribute being set (see 3.8.1). The
file is organized into 32-byte records. Each record can be a
directory entry. The first 29 bytes of the record is a string of
characters which is the file name. The last character of the name
has its sign bit (most significant bit) set. If the record is not
in use the first character position will have the value zero. The
last three bytes of the record is a 24-bit binary number which is
the logical sector number where the file header record (see 3.10) is
located.
</para>
<para>
The &quot;makdir&quot; command initializes all records in a new directory
to be unused entries except for the first two entries. These
entries have the names &quot;.&quot; and &quot;..&quot; along with the logical sector
numbers of the directory and its parent directory, respectively (see 3.7.3).
</para>
<para>
Directories cannot be copied or listed - the &quot;dir&quot; command is
used instead. Directories also cannot be deleted directly (see 3.5).
</para>
</section>

<section>
<title>Miscellaneous File Usage</title>
<para>
OS-9's basic file functions are so versatile it is possible to
devise an almost unlimited number of special-purpose file formats
for particular applications, which do not fit into any of the three
previously discussed categories.
</para>
<para>
Examples of this category are COBOL Indexed Sequential (ISAM)
files and some special word processor file formats which allow
random access of text lines (See 3.9.2). As discussed in Sec.
3.9.1, most OS-9 utility commands work with any file format including
these special types. In general, the &quot;dump&quot; command is the preferred
method for examining the contents of unusually formatted files.
</para>
</section>
</section>

<section>
<title>Physical File Organization</title>
<para>
OS-9's file system implements a universal logical organization
for all I/O devices that effectively eliminates most hardware-related
considerations for most applications. This section gives
basic information about the physical file structure used by OS-9.
For more information, see the OS-9 System Programmer's Manual.
</para>
<para>
Each OS-9 file is comprised of one or more sectors  which are
the physical storage units of the disk systems. Each sector holds
exactly 256 data bytes, and disk is numbered sequentially starting
with sector zero, track zero. This number is called a &quot;logical
sector number&quot;, or <emphasis>LSN</emphasis>.
The mapping of logical sector numbers to
physical track/sector numbers is done by the disk driver module.
</para>
<para>
Sectors are the smallest allocatable physical unit on a disk
system, however, to increase efficiency on some larger-capacity disk.
systems, OS-9 uses uniform-sized groups of sectors, called
<emphasis>clusters</emphasis>,
as the smallest allocatable unit. Cluster sizes are always an
integral power of two (2, 4, 8, etc.). One sector of each disk is
used as a <emphasis>bitmap</emphasis> (usually LSN 1),
in which each data bit corresponds
to one cluster on the disk. The bits are set and cleared to
indicate which clusters are in use (or defective), and which are
free for allocation to files.
</para>
<para>
The Dragon Computer disk system uses the following format:
</para>
<itemizedlist mark="square">
<listitem><para>
double density recording on one side
</para></listitem>
<listitem><para>
40 tracks per disk
</para></listitem>
<listitem><para>
18 sectors per track
</para></listitem>
<listitem><para>
one sector per cluster
</para></listitem>
</itemizedlist>
<para>
Each file has a directory entry (see 3.9.5) which includes the
file name and the logical sector number of the file's &quot;file descriptor
sector&quot;, which contains a complete description of the file
including:
</para>
<itemizedlist mark="square">
<listitem><para>
attributes
</para></listitem>
<listitem><para>
owner
</para></listitem>
<listitem><para>
date and time created
</para></listitem>
<listitem><para>
size
</para></listitem>
<listitem><para>
segment list (description of data sector blocks)
</para></listitem>
</itemizedlist>
<para>
Unless the file size is zero, the file will have one or more
sectors/clusters used to store data. The data sectors are grouped
into one or more contiguous blocks called &quot;segments&quot;.
</para>
</section>
</chapter>

<chapter>
<title>Advanced Features of the Shell</title>
<para>
The basic shell functions were introduced in Section 2 in order
to provide an understanding of how basic OS-9 commands work. In
this section the more advanced capabilities of the shell are
discussed. In addition to basic command line processing, the shell
has functions that facilitate:
</para>

<itemizedlist mark="square">
<listitem><para>
I/O redirection (including filters)
</para></listitem>
<listitem><para>
Memory Allocation
</para></listitem>
<listitem><para>
Multitasking (concurrent execution)
</para></listitem>
<listitem><para>
Procedure File Execution (background processing)
</para></listitem>
<listitem><para>
Execution Control (built-in commands)
</para></listitem>
</itemizedlist>

<para>
There is a virtually unlimited combination of ways these
capabilities can be used, and it is impossible to give more than a
representative set of examples in this manual. You are therefore
encouraged to study the basic rules, use your imagination, and
explore the possibilities on your own.
</para>

<section>
<title>A More Detailed Description Command Line Processing</title>
<para>
The shell is a program that reads and processes command lines one
at a time from its input path (usually your keyboard). Each line is
first scanned (or &quot;parsed&quot;) in order to identify and process any of
the following parts which may be present:
</para>

<itemizedlist mark="square">
<listitem><para>
A program, procedure file, or built-in command name (&quot;verbs&quot;)
</para></listitem>
<listitem><para>
Parameters to be passed to the program
</para></listitem>
<listitem><para>
Execution modifiers to be processed by the shell
</para></listitem>
</itemizedlist>

<para>
Note that only the verb (the program or command name) need be
present, the other parts are optional. After the verb has been
identified, the shell processes modifiers (if any). Any other text
not yet processed is assumed to be parameters and passed to the program called.
</para>
<para>
Unless the verb is a &quot;built-in command&quot;, the shell will run the
program named as a new process (task). It then deactivates itself
until the program called eventually terminates, at which time it
gets another input line, then the process is repeated. This happens
over and over until an end-of-file condition is detected on the
shell's input path which causes the shell to terminate its own
execution.
</para>
<para>
Here is a sample shell line which calls the assembler:
</para>
<screen>
asm sourcefile l -o &gt;/p #12k
</screen>
<para>
In this example:
</para>

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in">
<colspec colwidth="3in">
<tbody>
<row>
<entry>asm</entry>
<entry>is the verb</entry>
</row>
<row>
<entry>sourcefile l -o</entry>
<entry>are parameters passed to &quot;asm</entry>
</row>
<row>
<entry>&gt;/p</entry>
<entry>is a modifier which redirects the output
(listing) to the system's printer</entry>
</row>
<row>
<entry>#12K</entry>
<entry>is a modifier which requests that the
process be assigned 12K bytes of memory
instead of its (smaller) default amount.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
The verb must be the first name in the command line. After it
has been scanned, the shell first checks if it is a &quot;built-in&quot;
command. If it is, it is immediately executed. Otherwise, the shell
assumes it is a program name and attempts to locate and execute it
as described in Sections 5.3 and 5.4.1.
</para>
</section>

<section>
<title>Execution Modifiers</title>
<para>
Execution modifiers are processed by the shell before the program
is run. If an error is detected in any of the modifiers, the run
will be aborted and the error reported. Characters which comprise
modifiers are stripped from the part(s) of the command line passed
to the program as parameters, therefore, the characters reserved for
use as modifiers ( # ; ! &lt; &gt; &amp; ) cannot be used inside parameters,
but can be used before or after the parameters.
</para>

<section>
<title>Alternate Memory Size Modifier</title>
<para>
When command programs are invoked by the shell, they are
allocated the minimum amount of working RAM memory specified in the
program's module header. A module header is part of all executable
programs and holds the program's name, size, memory requirements,
etc. (See 5.4). Sometimes it is desirable to increase this default
memory size. Memory can be assigned in 256-byte pages using the
modifier &quot;#n&quot; where n is the decimal number of pages, or in 1024
byte increments using the modifier &quot;#nK&quot;. The two examples below
behave identically:
</para>
<screen>
OS9: copy #8 file1 file2     (gives 8*256 = 2048 bytes)
OS9: copy #2K file1 file2    (gives 2*1024 = 2048 bytes)
</screen>
</section>

<section>
<title>I/O Redirection Modifiers</title>
<para>
The second kind of modifier is used to redirect the program's
&quot;standard I/O paths&quot; to alternate files or devices. Well-written
OS-9 programs use these paths for routine I/O. Because the programs
do not use specific file or device names, it is fairly simple to
&quot;redirect&quot; the I/O to any file or device without altering the
program itself. Programs which normally receive input from a
terminal or send output to a terminal use one or more of the
standard I/O paths as defined below:
</para>
<para>
STANDARD INPUT: This path normally passes data from the
terminal's keyboard to the program.
</para>
<para>
STANDARD OUTPUT PATH: This path is normally used to output
data from the program to the terminal's display.
</para>
<para>
STANDARD ERROR OUTPUT PATH: This path is used to output
routine status messages such as prompts and errors to the
terminal's display (defaults to the same device as the
standard output path). NOTE: The name &quot;error output&quot; is
sometimes misleading since many other kinds of messages besides
errors are sent on this path.
</para>
<para>
When new processes are created, they inherit their parent process'
standard I/O paths (See 5.3). Therefore, when the shell
creates new processes, they usually inherit its standard I/O paths.
When you log-on the shell's standard input is the terminal keyboard;
the standard output and error output is the terminal's display.
When a redirection modifier is used on a shell command line, the
shell will open the corresponding paths and pass them to the new
process as its standard I/O paths. There are three redirection
modifiers as given below:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.4in">
<colspec colwidth="3in">
<tbody>
<row>
<entry>&lt;</entry>
<entry>Redirect the standard input path</entry>
</row>
<row>
<entry>&gt;</entry>
<entry>Redirect the standard output path</entry>
</row>
<row>
<entry>&gt;&gt;</entry>
<entry>Redirect the standard error output path</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
When redirection modifiers are used on a command line, they must
be immediately followed by a pathlist describing the file or device
the I/O is to be redirected to or from. For example, the standard
output of &quot;list&quot; can be redirected to write to the system printer
instead of the terminal:
</para>
<screen>
OS9: LIST correspondence &gt;/p
</screen>
<para>
Files referenced by I/O redirection modifiers are automatically
opened or created, and closed (as appropriate) by the shell. Here is
another example, the output of the DIR command is redirected to the
file &quot;/D1/savelisting&quot;:
</para>
<screen>
OS9: DIR &gt;/D1/savelisting
</screen>
<para>
If the LIST command is used on the file &quot;/D1/savelisting&quot;, output
from the DIR command will be displayed as shown below:
</para>
<screen>
OS9: LIST /D1/savelisting

   Directory of .   10:15:00
myfile          savelisting       file1
</screen>
<para>
Redirection modifiers can be used before and/or after the program's
parameters, but each modifier can only be used once.
</para>
</section>
</section>

<section>
<title>Command Separators</title>
<para>
A single shell input line can request execution of more than one
program. These programs may be executed sequentially or
concurrently. Sequential execution means that one program must
complete its function and terminate before the next program is
allowed to begin execution. Concurrent execution means that several
programs are allowed to begin execution and run simultaneously.

</para>

<section>
<title>Sequential Execution</title>
<para>
Programs are executed sequentially when each is entered on a
separate line. More than one program can be specified on a single
shell command line by separating each
&replstart;program name&replend; &replstart;parameters&replend;
from the next one with a &quot;;&quot; character. For example:
</para>
<screen>
OS9: COPY myfile /D1/newfile ; DIR &gt;/p
</screen>
<para>
This command line will first execute the COPY command and then the
DIR command.
</para>
<para>
If an error is returned by any program, subsequent commands on
the same line are not executed (regardless of the state of the &quot;x&quot;
option), otherwise, &quot;;&quot; and &quot;return&quot; are identical
separators.
</para>
<para>
Here are some more examples:
</para>
<screen>
OS9: copy oldfile newfile; del oldfile; list newfile

OS9: dir &gt;/d1/myfile ; list temp &gt;/p; del temp
</screen>
<para>
All programs executed sequentially are in fact separate, child
processes of the shell (See 5.3). After initiating execution of a
program to be executed sequentially, the shell enters the &quot;wait&quot;
state (See 5.2) until execution of the called program terminates.
</para>
</section>

<section>
<title>Concurrent Execution</title>
<para>
The second kind of separator is the &quot;&amp;&quot; which implies concurrent
execution, meaning that the program is run (as a separate, child
process, see 5.3), but the shell does not wait for it to complete
before processing the next command.
</para>
<para>
The concurrent execution separator is therefore the means by
which multiprogramming (running two or more programs simultaneously)
is accomplished. The number of programs that can run at the same
time is not fixed: it depends upon the amount of free memory in the
system versus the memory requirements of the specific programs.
Here is an example:
</para>
<screen>
OS9: DIR &gt;/P&amp;
&amp;007

OS9:
</screen>
<para>
This command line will cause shell to start the DIR command
executing, print the process ID number (&amp;007), and then immediately
display the &quot;OS9:&quot; prompt and wait for another command to be
entered. Meanwhile the DIR command will be busy sending a directory
listing to the printer. You can display a &quot;status summary&quot; of all
processes you have created by using the PROCS command. Below is
another example:
</para>
<screen>
OS9: DIR &gt;/P&amp; LIST file1&amp; COPY file1 file2 ; DEL temp
</screen>
<para>

</para>
<para>
Because they were followed by &quot;&amp;&quot; separators, the DIR, LIST, and
COPY programs will run concurrently, but the DEL program will not
run until the COPY program has terminated because sequential
execution (&quot;;&quot;) was specified.
</para>
</section>

<section>
<title>Pipes and Filters</title>
<para>
The third kind of separator is the &quot;!&quot; character which is used to
construct &quot;pipelines&quot;. Pipelines consist of two or more concurrent
programs whose standard input and/or output paths connect to each
other using &quot;pipes&quot;.
</para>
<para>
Pipes are the primary means-by which data is transferred from
process to process (interprocess communications). Pipes are first-in,
first-out buffers that behave like mass-storage files.
</para>
<para>
I/O transfers using pipes are automatically buffered and
synchronized. A single pipe may have several &quot;readers&quot; and several
&quot;writers&quot;. Multiple writers send, and multiple readers accept, data
to/from the pipe on a first-come, first-serve basis. An end-of-file
will occur if an attempt is made to read from a pipe but there are
no writers available to send data. Conversely, a write error will
occur if an attempt is made to write to a pipe having no readers.
</para>
<para>
Pipelines are created by the shell when an input line having one
or more &quot;!&quot; separators is processed. For each &quot;!&quot;, the standard
output of the program named to the left of the &quot;!&quot; is redirected via
a pipe to the standard input of the program named to the right of
the &quot;!&quot;. Individual pipes are created for each &quot;!&quot; present.
For example:
</para>
<screen>
OS9: update &lt;master_file ! sort ! write_report &gt;/p
</screen>
<para>
In the example above, the program &quot;update&quot; has its input redirected
from a path called &quot;master_file&quot;. Its standard output becomes the
standard input for the program &quot;sort&quot;. Its output, in turn, becomes
the standard input for the program &quot;write_report&quot;, which has its
standard output redirected to the printer.
</para>
<para>
All programs in a pipeline are executed concurrently. The pipes
automatically synchronize the programs so the output of one never
&quot;gets ahead&quot; of the input request of the next program in the
pipeline. This implies that data cannot flow through a pipeline any
faster than the slowest program can process it. Some of the most
useful applications of pipelines are jobs like character set
conversion, print file formatting, data compression/decompression,
etc. Programs which are designed to process data as components of a
pipeline are often called &quot;filters&quot;.
The &quot;tee&quot; command, which uses
pipes to allow data to be simultaneously &quot;broadcast&quot; from a single
input path to several output paths, is a useful filter.
</para>
</section>
</section>

<section>
<title>Command Grouping</title>
<para>
Sections of shell input lines can be enclosed in parentheses
which permits modifiers and separators to be applied to an entire
set of programs. The shell processes them by calling itself
recursively (as a new process) to execute the enclosed program list.
For example:
<screen>
OS9: (dir /d0; dir /d1) &gt;/p
</screen>
gives the same result as:
<screen>
OS9: dir /d0 &gt;/p; dir /d1 &gt;/p
</screen>
except for the subtle difference that the printer is &quot;kept&quot;
continuously in the first example; in the second case another user
could &quot;steal&quot; the printer in between the &quot;dir&quot; commands.
</para>
<para>
Command grouping can be used to cause a group of programs to be
executed sequentially, but also concurrently with respect to the
shell that initiated them, such as:
</para>
<screen>
OS9: (del file1; del file2; del file3)&amp;
</screen>
<para>
A useful extension of this form is to construct pipelines consisting
of sequential and/or concurrent programs. For example:
</para>
<screen>
OS9: (dir CMDS; dir SYS) ! makeuppercase ! transmit
</screen>
<para>
Here is a very practical example of the use of pipelines. Recall
that the &quot;DSAVE&quot; command generates a procedure file to copy all the
files in a directory. The example below shows how the output of
&quot;DSAVE&quot; can be pipelined to a shell which will execute the OS-9
commands as they are generated by DSAVE. Assume that we want to
copy all files from a directory called WORKING to a directory called
ARCHIVE:
</para>
<screen>
OS9: chd /d0/WORKING; dsave ! (chd /d0/ARCHIVE)
</screen>
</section>

<section>
<title>Built-in Shell Commands and Options</title>
<para>
When processing input lines, the shell looks for several special
names of commands or option switches that are built-in the shell.
These commands are executed without loading a program and creating a
new process, and generally affect how the shell operates. They can
be used at the beginning of a line, or following any program
separator (&quot;;&quot;, &quot;&amp;&quot;, or &quot;!&quot;).
Two or more adjacent built-in
commands can be separated by spaces or commas.
</para>
<para>
The built-in commands and their functions are:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in">
<colspec colwidth="3.5in">
<tbody>
<row>
<entry>chd &replstart;pathlist&replend;</entry>
<entry>change the working data directory to the directory
specified by the pathlist (see 3.6).</entry>
</row>
<row>
<entry>chx &replstart;pathlist&replend;</entry>
<entry>change the working execution directory to the
directory specified by the pathlist (see 3.6).</entry>
</row>
<row>
<entry>ex name</entry>
<entry>directly execute the module named. This
transforms the shell process so it ceases
to exist and a new module begins execution in
its place.</entry>
</row>
<row>
<entry>w</entry>
<entry>wait for any process to terminate.</entry>
</row>
<row>
<entry>* text</entry>
<entry>comment: &quot;text&quot; is not processed.</entry>
</row>
<row>
<entry>kill &replstart;Proc ID&replend;</entry>
<entry>abort the process specified.</entry>
</row>
<row>
<entry>setpr &replstart;proc ID&replend; &replstart;priority&replend;</entry>
<entry>changes process' priority (see 5.1).</entry>
</row>
<row>
<entry>x</entry>
<entry>causes shell to abort on any error (default)</entry>
</row>
<row>
<entry>-x</entry>
<entry>causes shell not to abort on error (See 4.7)</entry>
</row>
<row>
<entry>p</entry>
<entry>turns shell prompt and messages on (default)</entry>
</row>
<row>
<entry>-p</entry>
<entry>inhibits shell prompt and messages</entry>
</row>
<row>
<entry>t</entry>
<entry>makes shell copy all input lines to output</entry>
</row>
<row>
<entry>-t</entry>
<entry>does not copy input lines to output (default)</entry>
</row>
</tbody>
</tgroup>
</informaltable>


<para>
The change directory commands switch the shell's working directory
and, by inheritance, any subsequently created child process. The
&quot;ex&quot; command is used where the shell is needed to initiate execution
of a program without the overhead of a suspended &quot;shell&quot; process.
The name used is processed according to standard shell operation,
and modifiers can be used.
</para>
</section>

<section>
<title>Shell Procedure Files</title>
<para>
The shell is a reentrant program that can be simultaneously
executed by more than one process at a time. As is the case with
most other OS-9 programs, it uses standard I/O paths for routine
input and output (see 4.2.3). specifically, it requests command
lines from the standard input path and writes its prompts and other
data to the standard error path.
</para>
<para>
The shell can start up another process also running the shell by
means of the &quot;shell&quot; command. If the standard input path is
redirected to a mass storage file, the new &quot;incarnation&quot; of the
shell can accept and execute command lines from the file instead of
a terminal keyboard. The text file (see 3.9.2) to be processed is
called a &quot;procedure file&quot;. It contains one or more command lines
that are identical to command lines that are manually entered from
the keyboard. This technique is sometimes called &quot;batch&quot; or
&quot;background&quot; processing.
</para>
<para>
If the &replstart;program name&replend; specified on a shell command line can not be
found in memory or in the execution directory, shell will search the
data directory for a file with the desired name. If one is found,
shell will automatically execute it as a procedure file (see 2.0).
</para>
<para>
Execution of procedure files have a number of valuable
applications. It can eliminate repetitive manual entry of commonly-used
sequences of commands. It can allow the computer to execute a
lengthy series of programs &quot;in the background&quot; while the computer is
unattended or while the user is running other programs &quot;in the
foreground&quot;.
</para>
<para>
In addition to redirecting the shell's standard input to a
procedure file, the standard output and standard error output can be
redirected to another file which can record output for later review
or printing. This can also eliminate the sometimes-annoying output
of shell messages to your terminal at random times.
</para>
<para>
Here are two simple ways to use the shell to create another
shell:
</para>
<screen>
OS9: shell &lt;procfile

OS9: procfile
</screen>
<para>
Both do exactly the same thing: execute the commands of the file
&quot;procfile&quot;. To run the procedure file in a &quot;background&quot; mode you
simply add the ampersand operator:
</para>
<screen>
OS9: procfile&amp;
</screen>
<para>
OS-9 does not have any constraints on the number of jobs that can be
simultaneously executed as long as there is memory available (see
5.4). Also, the procedure files can themselves cause sequential or
concurrent execution of additional procedure files. Here's a more
complex example of initiating two processing streams with
redirection of each shell's output to files:
</para>
<screen>
OS9: proc1 T &gt;&gt;stat1&amp; proc2 T &gt;&gt;stat2&amp;
</screen>
<para>
Note that the built-in command &quot;T&quot; (copy input lines to error
output) was used above. They make the output file contain a record
of all lines executed, but without useless &quot;OS9&quot; prompts intermixed.
The &quot;-x&quot; built-in command can be used if you do
<emphasis>not</emphasis> want processing
to stop if an error occurs. Note that the built-in commands only
affect the shell that executes them, and not any others that may
exist.
</para>
</section>

<section>
<title>Error Reporting</title>
<para>
Many programs (including the shell) use OS-9's standard error
reporting function, which displays an error number on the error
output path. The standard error codes are listed in the Appendix of
this manual. If desired, the &quot;printerr&quot; command can be executed,
which replaces the smaller, built-in error display routine with a
larger (and slower) routine that looks up descriptive error messages
from a text file called &quot;/d0/sys/errmsg&quot;.
Once the &quot;printerr&quot;
command has been run it cannot be turned off. Also, its effect is
system-wide.
</para>
<para>
Programs called by the shell can return an error code in the MPU
&quot;B&quot; register (otherwise B should be cleared) upon termination. This
type of error, as well as errors detected by the shell itself, will
cause an error message to be displayed and processing of the command
line or procedure file to be terminated unless the &quot;-x&quot; built-in
command has been previously executed (See 4.5).
</para>
</section>

<section>
<title>Running Compiled Intermediate Code Programs</title>
<para>
Before the shell executes a program, it checks the program
module's language type. If its type is not 6809 machine language,
shell will call the appropriate run-time system for that module.
Versions of the shell supplied for various systems are capable of
calling different run-time systems. Most versions of shell call
Basic09 when appropriate, and Level Two versions of shell can also
call the Pascal P-code interpreter (PascalN), or the CIS Cobol
runtime system (RunC).
</para>
<para>
For example, if you wanted to run a BASIC09 I-code module called
&quot;adventure&quot;, you could type the command given below:
</para>
<screen>
OS9: BASIC09 adventure
</screen>
<para>
Or you could accomplish the same thing by typing the following:
</para>
<screen>
OS9: adventure
</screen>
</section>

<section>
<title>Setting Up Timesharing System Procedure Files</title>

<para>
OS-9 systems used for timesharing usually have a procedure file
that brings the system up by means of one simple command or by using
the system &quot;startup&quot; file. A procedure file which initiates the
timesharing monitor for each terminal is executed to start up the
system. The procedure file first starts the system clock, then
initiates concurrent execution of a number of processes that have
their I/O redirected to each timesharing terminal.
</para>
<para>
Usually one TSMON command program is started up concurrently for
each terminal in the system. This is a special program which
monitors a terminal for activity. When a carriage return character
is typed on any of these terminals, the TSMON command initiates the
LOGIN command program. If a user does not enter a correct password
or user number in three tries, the LOGIN command will be aborted.
Here's a sample procedure file for a 4-terminal timesharing system
having terminals names &quot;TERM&quot;, &quot;T1&quot;,
&quot;T2&quot;, and &quot;T3&quot;.
</para>
<programlisting>
* system startup procedure file
echo Please Enter the Date and Time
setime &lt;/term
printerr
tsmon /t1&amp;
tsmon /t2&amp;
tsmon /t3&amp;
</programlisting>
<para>
NOTE: This LOGIN procedure will not work until a password file
called &quot;/D0/SYS/PASSWORD&quot; has been created. For more information,
please see the LOGIN command description.
</para>
<para>
The example above deserves special attention. Note that the
&quot;setime&quot; command has its input redirected to the system console
&quot;term&quot;, which is necessary because it would otherwise attempt to
read the time information from its current standard input path,
which is the procedure file and not the keyboard.
</para>
</section>
</chapter>


<chapter>
<title>Multiprogramming and Memory Management</title>
<para>
One of OS-9's most extraordinary abilities is multiprogramming,
which is sometimes called timesharing or multitasking. Simply
states, OS-9 lets you computer run more than one program at the same
time. This can be a tremendous advantage in many situations. For
example, you can be editing one program while another is being
printed. Or you can use your Color Computer to control household
automation and still be able to use it for routine work and
entertainment.
</para>
<para>
OS-9 uses this capability all the time for internal functions.
The simple way for you to do so is by putting a &quot;&amp;&quot; character at the
end of a command line which causes the shell to run your command as
a &quot;background task&quot;.
</para>
<para>
The information presented in this chapter is intended to give you
an insight into how OS-9 performs this amazing feat. You certainly
don't have to know every detail of how multiprogramming works in
order to use OS-9, but a basic working knowledge can help you
discover many new ways to use your Color Computer.
</para>
<para>
In order to allow several programs to run simultaneously and
without interference, OS-9 must perform many coordination and
resource allocation functions. The major system resources managed
by OS-9 are:
</para>
<simplelist>
<member>CPU Time</member>
<member>Memory</member>
<member>The input/output system</member>
</simplelist>
<para>
In order for the computer to have reasonable performance, these
resources must be managed in the most efficient manner possible.
Therefore, OS-9 uses many techniques and strategies to optimize
system throughput and capacity.
</para>

<section>
<title>Processor Time Allocation and Timeslicing</title>

<para>
CPU time is a resource that must be allocated wisely to maximize
the computer's throughput. It is characteristic of many programs to
spend much unproductive time waiting for various events, such as an
input/output operation. A good example is an interactive program
which communicates with a person at a terminal on a line-by line
basis. Every time the program has to wait for a line of characters
to be typed or displayed, it (typically) cannot do any useful
processing and would waste CPU time. An efficient multiprogramming
operating system such as OS-9 automatically assigns CPU time to only
those programs that can effectively use the, time.
</para>
<para>
OS-9 uses a technique called <emphasis>timeslicing</emphasis> which allows processes
to share CPU time with all other active processes. Timeslicing is
implemented using both hardware and software functions. The
system's CPU is interrupted by a real time clock many (60 in the
Color Computer) times each second. This basic time interval is
called a &quot;tick&quot;, hence, the interval between ticks is a time slice.
This technique is called timeslicing because each second of CPU time
is sliced up to be shared among several processes. This happens so
rapidly that to a human observer all processes appear to execute
continuously, unless the computer becomes overloaded with processing. If this
happens, a noticeable delay in response to terminal
input may occur, or &quot;batch&quot; programs may take much longer to run
than they ordinarily do. At any occurrence of a tick, OS-9 can suspend
execution of one program and begin execution of another. The
starting and stopping of programs is done in a manner that does not
affect the program's execution. How frequently a process is given
time slices depends upon its assigned priority relative to the
assigned priority of other active processes.
</para>
<para>
The percentage of CPU time assigned to any particular process
cannot be exactly computed because there are dynamic variables such
as time the process spends waiting for I/O devices. It can be
roughly approximated by dividing the process's priority by the sum
of the priority numbers of all processes:
</para>
<screen>

                     Process Priority
Process CPU Share = -------------------
                     Sum of All Active
                    Process' Priorities
</screen>
</section>

<section>
<title>Process States</title>

<para>
The CPU time allocation system automatically assigns programs one
of three &quot;states&quot; that describe their current status. Process
states are also important for coordinating process execution. A
process may be in one and only one state at any instant, although
state changes may be frequent. The states are:


</para>
<para>
<emphasis>ACTIVE:</emphasis>
processes which can currently perform useful processing.
These are the only processes assigned CPU time.
</para>
<para>
<emphasis>WAITING:</emphasis>
processes which have been suspended until another process
terminates. This state is used to coordinate execution of
sequential programs. The shell, for example, will be in the waiting
state during the time a command program it has initiated is running.

</para>
<para>
<emphasis>SLEEPING:</emphasis>
processes suspended by self-request for a specified time
interval or until receipt of a &quot;signal&quot;. Signals are internal
messages used to coordinate concurrent processes. This is the
typical state of programs which are waiting for input/output
operations.

</para>
<para>

Sleeping and waiting processes are not given CPU time until they
change to the active state.
</para>
</section>

<section>
<title>Creation of New Processes</title>

<para>
The sequence of operations required to create a new process and
initially allocate its resources (especially memory) are
automatically performed by OS-9's &quot;fork&quot; function. If for any
reason any part of the sequence cannot be performed the fork is
aborted and the prospective parent is passed an appropriate error
code. The most frequent reason for failure is unavailablity of
required resources (especially memory) or when the program specified
to be run cannot be found. A process can create many new processes,
subject only to the limitation of the amount of unassigned memory
available.
</para>
<para>
When a process creates a new process, the creator is called the
&quot;parent process&quot;, and the newly created process is called the &quot;child
process&quot;. The new child can itself become a parent by creating yet
another process. If a parent process creates more than one child
process, the children are called &quot;siblings&quot; with respect to each
other. If the parent/child relationship of all processes in the
system is examined, a hierarchical lineage becomes evident. In
fact, this hierarchy is a tree structure that resembles a family
tree. The &quot;family&quot; concept makes it easy to describe relationships
between processes, and so it is used extensively in descriptions of
OS-9's multiprogramming operations.
</para>
<para>
When the parent issues a fork request to OS-9, it must specify
the following required information:
</para>
<itemizedlist mark="square">
<listitem><para>
A PRIMARY MODULE, which is the name of the program to be
executed by the new process. The program can already be present
in memory, or OS-9 may load it from a mass storage file having
the same name (see 5.4.1).
</para></listitem>
<listitem><para>
PARAMETERS, which is data specified by the parent to be
passed to and used by the new process. This data is copied to
part of the child process' memory area. Parameters are
frequently used to pass file names, initialization values, etc.
The shell, passes command line parameters this way (see 4.1).
</para></listitem>
</itemizedlist>
<para>
The new process also &quot;inherits&quot; copies of certain of its parent's
properties. These are:
</para>
<itemizedlist mark="square">
<listitem><para>
A USER NUMBER which is used by the file security system and
is used to identify all processes belonging to a specific user
(this is not the same as the &quot;process ID&quot;, which identifies a
specific process) . This number is usually obtained from the
system password file when a user logs on. The system manager
always is user number zero (see 3.8).
</para></listitem>
<listitem><para>
STANDARD INPUT AND OUTPUT PATHS: the three paths (input,
output, and error/status) used for routine input and output.
Note that most paths (files) may be shared simultaneously by
two or more processes (see 4.2.2). The two current working
directories are also inherited.
</para></listitem>
<listitem><para>
PROCESS PRIORITY which determines what proportion of CPU
time the process receives with respect to others (see 5.1).
</para></listitem>
</itemizedlist>
<para>
As part of the fork operation, OS-9 automatically assigns:
</para>
<itemizedlist mark="square">
<listitem><para>
A PROCESS ID: a number from 1 to 255, which is used to
identify specific processes. Each process has a unique process
ID number (see 4.3.2).
</para></listitem>
<listitem><para>
MEMORY: enough memory required for the new process to run.
Level Two systems give each process a unique &quot;address space&quot;.
In Level One systems, all processes share the single address
space. A &quot;data area&quot;, used for the program's parameters,
variables, and stack is allocated for the process' exclusive
use. A second memory area may also be required to load the
program (primary module) if it is not resident in memory (see 5.4)..
</para></listitem>
</itemizedlist>
<para>
To summarize, the following items are given to or associated with
new processes:
</para>

<itemizedlist mark="square">
<listitem><para>
Primary Module (program module to be run)
</para></listitem>
<listitem><para>
Parameter(s) passed from parent to child
</para></listitem>
<listitem><para>
User Number
</para></listitem>
<listitem><para>
Standard I/O paths and working directories
</para></listitem>
<listitem><para>
Process Priority
</para></listitem>
<listitem><para>
Process ID
</para></listitem>
<listitem><para>
Memory
</para></listitem>
</itemizedlist>

</section>

<section>
<title>Basic Memory Management Functions</title>
<para>
An important OS-9 function is memory management. OS-9 automatically allocates
all system memory to itself and to processes, and
also keeps track of the logical <emphasis>contents</emphasis>
of memory (meaning which
program modules are resident in memory at any given time). The
result is that you seldom have to be bothered with the actual memory
addresses of programs or data.
</para>
<para>
Within the address space, memory is assigned from higher
addresses  downward  for  program  modules, and from lower addresses
upward for data areas, as shown below:
</para>
<screen>
                +---------------------------+  highest address
                !       program modules     !
                !         (RAM or ROM)      !
                !                           !
                ! - - - - - - - - - - - - - !
                !                           !
                !        unused space       !
                !       (RAM or empty)      !
                !                           !
                ! - - - - - - - - - - - - - !
                !                           !
                !         data areas        !
                !           (RAM)           !
                !                           !
                +---------------------------+  lowest address (0)
</screen>
<section>
<title>Loading Program Modules Into Memory</title>

<para>
When performing a fork operation, OS-9's first step is to attempt
to locate the requested program module by searching the &quot;module
directory&quot;, which has the address of every module present in memory.
The 6809 instruction set supports a type of program called
&quot;reentrant code&quot; which means the exact same &quot;copy&quot; of a program can
be shared by two or more different processes simultaneously without
affecting each other, provided that each &quot;incarnation&quot; of the
program has am independent memory area for its variables.
</para>
<para>
Almost all OS-9 family software is reentrant and can make most
efficient use of memory. For example, Basic09 requires 22K bytes of
memory to load into. If a request to run Basic09 is made, but
another user (process) had previously caused it to be loaded into
memory, both processes will share the same copy, instead of causing
another copy to be loaded (which would use an additional 22K of
memory). OS-9 automatically keeps track of how many processes are
using each program module and deletes the module (freeing its memory
for other uses) when all processes using the module have terminated.
</para>
<para>
If the requested program module is not already in memory, the
name is used as a pathlist (file name) and an attempt is made to
load the program from mass storage (see 3.9.4).
</para>
<para>
Every program module has a &quot;module header&quot; that describes the
program and its memory requirements. OS-9 uses this to determine
how much memory for variable storage should be allocated to the
process (it can be given more memory by specifying an optional
parameter on the shell command line). The module header also
includes other important descriptive information about the program,
and is an essential part of OS-9 operation at the machine language
level. A detailed description of memory modules and module headers
can be found in the &quot;OS-9 System Programmer's Manual&quot;.
</para>
<para>
Programs can also be explicitly loaded into memory using the
&quot;load&quot; command. As with fork, the program will actually be loaded
only if it is not already in memory. If the module is not in
memory, OS-9 will copy a candidate memory module from the file into
memory, verify the CRC, and then, if the module is not already in
the module directory, add the module to the directory. This process
is repeated until all the modules in the file are loaded, the 64K
memory limit is exceeded, or until a module with an invalid format
is encountered. OS-9 always links to the first module read from the
file.
</para>
<para>
If the program module <emphasis>is</emphasis> already in memory,
the load will proceed
as described above, loading the module from the specified file,
verifying the CRC, and when attempting to add the valid module to
the module directory, noticing that the module is already known, the
load merely increments the known module's link count (the number of
processes using the module.) The load command can be used to &quot;lock
a program into memory. This can be useful if the same program is to
be used frequently because the program will be kept in memory
continuously, instead of being loaded repeatedly.
</para>
<para>
The opposite of &quot;load&quot; is the &quot;unlink&quot; command, which decreases a
program module's link count by one. Recall that when this count becomes zero
(indicating the module in no longer used by any process),
the module is deleted, e.g., its memory is deallocated and its name
is removed from the module directory. The &quot;unlink&quot; command is
generally used in conjunction with the &quot;load&quot; command (programs
loaded by fork are automatically unlinked when the program
terminates).
</para>
<para>
Here is an example of the use of
&quot;load&quot; and &quot;unlink&quot; to lock a
program in memory. Suppose the &quot;copy&quot; command will be used five
times. Normally, the copy command would be loaded each time the
&quot;copy&quot; command is called. If the &quot;load&quot; command is used first,
&quot;copy&quot; will be locked into memory first, for example:
</para>
<screen>
OS9: load copy
OS9: copy file1 file1a
OS9: copy file2 file2a
OS9: copy file3 file3a
OS9: unlink copy
</screen>
<para>
It is important to use the &quot;unlink&quot; command after the program is no
longer needed, or the program will continue to occupy memory which
otherwise could be used for other purposes. Be very careful
<emphasis>not</emphasis> to
completely unlink modules in use by any process! This will cause the
memory used by the module to be deallocated and its contents
destroyed. This will certainly cause all programs using the
unlinked module to crash.
</para>
</section>

<section>
<title>Loading Multiple Programs</title>

<para>
Another important aspect of program loading is the ability to
have two or more programs resident in memory at the same time. This
is possible because all OS-9 program modules are &quot;position-independent
code&quot;, or &quot;PIC&quot;. PIC programs do not have to be loaded into
specific, predetermined memory addresses to work correctly, and can
therefore be loaded at different memory addresses at different
times. PIC programs require special types of machine language instructions
which few computers have. The ability of the 6809
microprocessor to use this type of program is one of its most
powerful features.
</para>
<para>
The &quot;load&quot; command can therefore be used two or more times (or a
single file may contain several memory modules, see 3.9.4), and each
program module will be automatically loaded at different,
non-overlapping addresses (most other operating systems write over the
previous program's memory whenever a new program is loaded). This
technique also relieves the user from having to be directly concerned with
absolute memory addresses. Any number of program modules
can be loaded until available system memory is full.
</para>
</section>

<section>
<title>Memory Fragmentation</title>

<para>
Even though PIC programs can be initially loaded at any address
where free memory is available, program modules cannot be relocated
dynamically afterwards, e.g., once a program is loaded it must
remain at the address at which it was originally loaded (however
Level Two systems can &quot;load&quot; (map) memory resident programs at
different addresses in each process' address space). This characteristic
can lead to a sometimes troublesome phenomenon called
&quot;memory fragmentation&quot;. When programs are loaded, they are assigned
the first sufficiently large block of memory at the highest address
possible in the address space. If a number of program modules are
loaded, and subsequently one or more modules which are located in
between other modules are &quot;unlinked&quot;, several fragments of free
memory space will exist. The sum of the sizes of the free memory
space may be quite large, but because they are scattered, not enough
space will exist in a single block to load a program module larger
than the largest free space.
</para>
<para>
The &quot;mfree&quot; command shows the location and size of each unused
memory area and the &quot;mdir e&quot; command shows the address, size, and
link (use) count of each module in the address space. These
commands can be used to detect fragmentation. Memory can usually be
de-fragmemted by unlinking scattered modules and reloading them.
<emphasis>Make certain</emphasis> none are in use before doing so.
</para>
</section>
</section>
</chapter>



<chapter>
<title>Use of the System Disk</title>
<para>
Disk-based OS-9 systems use a system disk to load many parts of
the operating system during the system startup and to provide files
frequently used during normal system operations. Therefore, the
system disk is generally kept in disk drive zero (&quot;/D0&quot;) when the
system is running.
</para>
<para>
Two files used during the system startup operation, &quot;OS9Boot&quot; and
&quot;startup&quot; <emphasis>must</emphasis>
reside in the system disk's root directory. Other
files are organized into three directories: CMDS (commands), DEFS
(system-wide definitions), and SYS (other system files). Other files
and directories created by the system manager and/or users may also
reside on the system disk. These frequently include each user s
initial data directory.
</para>

<section>
<title>The OS9BOOT File</title>

<para>
The file called &quot;OS9Boot&quot; loaded into RAM memory by the
&quot;bootstrap&quot; routine located in the OS-9 firmware. It includes file
managers, device drivers and descriptors, and any other modules
which are permanently resident in memory. A typical Microware OS-9
distribution disk's &quot;OS9Boot&quot; file contains the following modules:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in">
<colspec colwidth="3.5in">
<tbody>
  <row>
    <entry>IOMAN</entry>
    <entry>OS-9 Input/Output Manager</entry>
  </row>
  <row>
    <entry>RBF</entry>
    <entry>Random Block (disk) File Manager</entry>
  </row>
  <row>
    <entry>SCF</entry>
    <entry>Sequential Character (terminal) File Manager</entry>
  </row>
  <row>
    <entry>Pipeman</entry>
    <entry>Pipeline File Manager</entry>
  </row>
  <row>
    <entry>Piper</entry>
    <entry>Pipeline Driver</entry>
  </row>
  <row>
    <entry>Pipe</entry>
    <entry>Pipeline Device Descriptor</entry>
  </row>
  <row>
    <entry>KBDVID</entry>
    <entry>Keyboard/video/Graphics Device Driver</entry>
  </row>
  <row>
    <entry>PRINTER</entry>
    <entry>Printer Device Driver</entry>
  </row>
  <row>
    <entry>DDISK</entry>
    <entry>Disk Driver</entry>
  </row>
  <row>
    <entry>D0, D1</entry>
    <entry>Disk Device Descriptor</entry>
  </row>
  <row>
    <entry>TERM</entry>
    <entry>Terminal Device Descriptor</entry>
  </row>
  <row>
    <entry>P</entry>
    <entry>Printer Device Descriptor</entry>
  </row>
  <row>
    <entry>CLOCK</entry>
    <entry>Real-Time Clock Module</entry>
  </row>
  <row>
    <entry>SYSGO</entry>
    <entry>System Startup Process</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
Users may create new bootstrap files which may include additional
modules (see &quot;OS9Gen&quot; command). Any module loaded as part of the
bootstrap cannot be unlinked and is stored in memory with a minimum
of fragmentation. It may be advantageous to include in the OS9Boot
file any module used constantly during normal system operation.
This can be done with the OS9GEN command.
</para>
</section>

<section>
<title>The SYS Directory</title>

<para>
The directory &quot;/d0/SYS&quot; contains two important files:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1in">
<colspec colwidth="4in">
<tbody>
  <row>
<entry>password</entry>
<entry>the system password file (see &quot;login&quot; command)</entry>
  </row>
  <row>
<entry>errmsg</entry>
<entry>the error message file (see 4.7)</entry>
  </row>
</tbody>
</tgroup>
</informaltable>
<para>
These files (and the SYS directory itself) are not absolutely
required to boot OS-9, they are needed if &quot;login&quot;, &quot;tsmon&quot;, or
&quot;printerr&quot; will be used. Users may add other system-wide files of
similar nature if desired.
</para>
</section>

<section>
<title>The Startup File</title>

<para>
The file &quot;/d0/startup&quot; is a shell procedure file (see 4.6) which
is automatically processed immediately after system startup. The
user may include in &quot;startup&quot; any legal shell command line. Often
this will include &quot;setime&quot; to start the system clock. If this file
is not present the system will still start correctly but the user
must run the SETIME command manually.
</para>
</section>

<section>
<title>The CMDS Directory</title>

<para>
The directory &quot;/d0/CMDS&quot; is the system-wide command object code
directory, which is normally shared by all users as their working
execution directory (see 3.7). If &quot;shell&quot; is not part of the
&quot;OS9Boot&quot; file, it must be present in this directory. The system
startup process &quot;sysgo&quot; makes CMDS the initial execution directory.
</para>
</section>

<section>
<title>The DEFS Directory</title>

<para>
The directory &quot;/d0/DEFS&quot; is a directory that contains assembly
language source code files which contain common system-wide symbolic
definitions, and are normally included in assembly language programs
by means of the OS-9 Assembler &quot;use&quot; directive. The presence and
use of this directory is optional, but highly recommended for any
system used for assembly language programs. The files commonly
contained in this directory are:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1in">
<colspec colwidth="4in">
<tbody>
  <row>
<entry>OS9Defs</entry>
<entry>main system-wide definition file</entry>
  </row>
  <row>
<entry>RBFDefs</entry>
<entry>RBF file manager definition file</entry>
  </row>
  <row>
<entry>SCFDefs</entry>
<entry>SCF file manager definition file</entry>
  </row>
  <row>
<entry>Systype</entry>
<entry>System types definition file</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

</section>

<section>
<title>Changing System Disks</title>

<para>
The system disk is not usually removed while the system is running, especially
on multiuser systems. If it is, the &quot;chx&quot; and
&quot;chd&quot; (if the working data directory was on the system disk)
commands should be executed to reset the working directory pointers
because the directories may be at different addresses on the new
disk, for example:
</para>

<screen>
chx /d0/cmds
chd /d0
</screen>

<para>
In general, it is unwise to remove a disk and replace it with
another if any paths are open to files resident on the disk. It is
<emphasis>dangerous</emphasis> to exchange <emphasis>any</emphasis>
disk if any files on it are open in WRITE or UPDATE modes.
</para>


</section>

<section>
<title>Making New System Disks</title>

<para>
To make a system disk, the following steps must be performed:

<orderedlist  numeration="arabic">
<listitem><para>
The new disk must be formatted.
</para></listitem>

<listitem><para>
The &quot;OS9Boot&quot; file must be created and linked by the &quot;OS9Gen&quot; or
&quot;Cobbler&quot; commands.
</para></listitem>

<listitem><para>
The &quot;startup&quot; file must be created or copied.
</para></listitem>

<listitem><para>
The CMDS and SYS directories and the files they contain must be
copied.
</para></listitem>
</orderedlist>

Steps 2 through 4 may be performed manually, or automatically by any
of the following methods:
<orderedlist  numeration="arabic">
<listitem><para>
By a shell procedure file created by the user.
</para></listitem>

<listitem><para>
By a shell procedure file generated by the &quot;dsave&quot; command
</para></listitem>

<listitem><para>
By the &quot;backup&quot; command
</para></listitem>
</orderedlist>
</para>
</section>
</chapter>

<chapter>
<title>System Command Descriptions</title>
<para>
This section contains descriptions for each of the command
programs that are supplied with OS-9. These programs are usually
called using the shell, but can be called from most other OS-9
family programs such as BASIC09, Interactive Debugger, Macro Text
Editor, etc. Unless otherwise noted, these programs are designed to
run as individual processes.
</para>
<para>
<emphasis>WARNING</emphasis>
- ALTHOUGH MANY OS-9 COMMANDS MAY WORK ON LEVEL ONE OR LEVEL
TWO SYSTEMS, THERE ARE DIFFERENCES. TAKE CARE NOT TO MIX COMMAND
FILES FROM LEVEL ONE SYSTEMS ON LEVEL TWO, OR THE REVERSE.
</para>
<section>
<title>Formal Syntax Notation</title>
<para>
Each command description includes a syntax definition which
describes how the  command sentence can be constructed. These are
symbolic descriptions that use the following notation:
</para>

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1in">
<colspec colwidth="4in">
<tbody>
<row>
    <entry>[ ]</entry>
    <entry>= Brackets indicate that the enclosed item(s) are optional.</entry>
</row>
<row>
    <entry>&repeatst; &repeaten;</entry>
    <entry>= Braces indicate that the enclosed item(s) can be
    either omitted or repeated multiple times.</entry>
</row>
<row>
    <entry>&replstart;path&replend;</entry>
    <entry>= Represents any legal pathlist.</entry>
</row>
<row>
    <entry>&replstart;devname&replend;</entry>
    <entry>= Represents any legal device name.</entry>
</row>
<row>
    <entry>&replstart;nodname&replend;</entry>
    <entry>= Represents any legal memory module name.</entry>
</row>
<row>
    <entry>&replstart;procID&replend;</entry>
    <entry>= Represents a process number.</entry>
</row>
<row>
    <entry>&replstart;opts&replend;</entry>
    <entry>= One or more options defined in the command description.</entry>
</row>
<row>
    <entry>&replstart;arglist&replend;</entry>
    <entry>= a list of arguments (parameters).</entry>
</row>
<row>
    <entry>&replstart;text&replend;</entry>
    <entry>= a character string terminated by end-of-line.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
NOTE: The syntax of the commands given does not include the shell's
built in options such as alternate memory size, I/O redirection,
etc. This is because the shell will filter its options out of the
command line before it is passed to the program being called.
</para>
</section>

<section>
<title>Commands</title>

&attrref;
&backupref;
&binexref;
&buildref;
&chdref;
&cmpref;
&cobblerref;
&copyref;
&dateref;
&dcheckref;
&delref;
&deldirref;
&dirref;
&displayref;
&dsaveref;
&dumpref;
&echoref;
&exref;
&formatref;
&freeref;
&identref;
&killref;
&linkref;
&listref;
&loadref;
&loginref;
&makdirref;
&mdirref;
&mergeref;
&mfreeref;
&os9genref;
&printerrref;
&procsref;
&pwdref;
&renameref;
&saveref;
&setimeref;
&setprref;
&shellref;
&sleepref;
&teeref;
&tmoderef;
&tsmonref;
&unlinkref;
&verifyref;
&xmoderef;
</section>
</chapter>


<appendix>
<title>Command Summary</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colwidth="1in">
<colspec colwidth="3in">
<colspec colwidth="0.6in">
<tbody>
<row>
<entry>ATTR</entry><entry>Change File Attributes</entry><entry>7-2</entry>
</row>
<row>
<entry>BACKUP</entry><entry>Make Disk Backup</entry><entry>7-3</entry>
</row>
<row>
<entry>BINEX</entry><entry>Convert Binary to S-Record</entry><entry>7-5</entry>
</row>
<row>
<entry>BUILD</entry><entry>Build Text File</entry><entry>7-6</entry>
</row>
<row>
<entry>CHD</entry><entry>Change Working Data Directory</entry><entry>7-7</entry>
</row>
<row>
<entry>CHX</entry><entry>Change Working Execution Directory</entry><entry>7-7</entry>
</row>
<row>
<entry>CMP</entry><entry>File Comparison Utility</entry><entry>7-8</entry>
</row>
<row>
<entry>COBBLER</entry><entry>Make Bootstrap File</entry><entry>7-9</entry>
</row>
<row>
<entry>COPY</entry><entry>Copy Data</entry><entry>7-10</entry>
</row>
<row>
<entry>DATE</entry><entry>Display System Date and Time</entry><entry>7-11</entry>
</row>
<row>
<entry>DCHECK</entry><entry>Check Disk File Structure</entry><entry>7-12</entry>
</row>
<row>
<entry>DEL</entry><entry>Delete a File</entry><entry>7-16</entry>
</row>
<row>
<entry>DELDIR</entry><entry>Delete All Files in a Directory System</entry><entry>7-17</entry>
</row>
<row>
<entry>DIR</entry><entry>Display File Names in a Directory</entry><entry>7-18</entry>
</row>
<row>
<entry>DISPLAY</entry><entry>Display Converted Characters</entry><entry>7-19</entry>
</row>
<row>
<entry>DSAVE</entry><entry>Generate Procedure File to Copy Files</entry><entry>7-20</entry>
</row>
<row>
<entry>DUMP</entry><entry>Formatted File Dump</entry><entry>7-21</entry>
</row>
<row>
<entry>ECHO</entry><entry>Echo Text to Output Path</entry><entry>7-22</entry>
</row>
<row>
<entry>EX</entry><entry>Execute Program as Overlay</entry><entry>7-23</entry>
</row>
<row>
<entry>EXBIN</entry><entry>Convert S-Record To Binary</entry><entry>7-5</entry>
</row>
<row>
<entry>FORMAT</entry><entry>Initialize Disk Media</entry><entry>7-24</entry>
</row>
<row>
<entry>FREE</entry><entry>Display Free Space on Device</entry><entry>7-25</entry>
</row>
<row>
<entry>IDENT</entry><entry>Print OS-9 module identification</entry><entry>7-26</entry>
</row>
<row>
<entry>KILL</entry><entry>Abort a Process</entry><entry>7-28</entry>
</row>
<row>
<entry>LINK</entry><entry>Link Module Into Memory</entry><entry>7-29</entry>
</row>
<row>
<entry>LIST</entry><entry>List Contents of- Disk File</entry><entry>7-30</entry>
</row>
<row>
<entry>LOAD</entry><entry>Load Module(s) Into Memory</entry><entry>7-31</entry>
</row>
<row>
<entry>LOGIN</entry><entry>Timesharing System Log-In</entry><entry>7-32</entry>
</row>
<row>
<entry>MAKDIR</entry><entry>Create Directory File</entry><entry>7-34</entry>
</row>
<row>
<entry>MDIR</entry><entry>Display Module Directory</entry><entry>7-35</entry>
</row>
<row>
<entry>MERGE</entry><entry>Copy and Combine Files</entry><entry>7-36</entry>
</row>
<row>
<entry>MFREE</entry><entry>Display Free System RAM Memory</entry><entry>7-37</entry>
</row>
<row>
<entry>OS9GEN</entry><entry>Build and Link a Bootstrap File</entry><entry>7-38</entry>
</row>
<row>
<entry>PRINTERR</entry><entry>Print Full Text Error Messages</entry><entry>7-40</entry>
</row>
<row>
<entry>PROCS</entry><entry>Display Processes</entry><entry>7-41</entry>
</row>
<row>
<entry>PWD</entry><entry>Print Working Directory</entry><entry>7-42</entry>
</row>
<row>
<entry>PXD</entry><entry>Print Execution Directory</entry><entry>7-42</entry>
</row>
<row>
<entry>RENAME</entry><entry>Change File Name</entry><entry>7-43</entry>
</row>
<row>
<entry>SAVE</entry><entry>Save Memory Module(s) on a File</entry><entry>7-44</entry>
</row>
<row>
<entry>SETIME</entry><entry>Activate and Set System Clock</entry><entry>7-45</entry>
</row>
<row>
<entry>SETPR</entry><entry>Set Process Priority</entry><entry>7-46</entry>
</row>
<row>
<entry>SLEEP</entry><entry>Suspend Process for Period of Time</entry><entry>7-47</entry>
</row>
<row>
<entry>SHELL</entry><entry>OS-9 Command Interpreter</entry><entry>7-48</entry>
</row>
<row>
<entry>TEE</entry><entry>Copy Standard Input to Multiple Output Paths</entry><entry>7-50</entry>
</row>
<row>
<entry>TMODE</entry><entry>Change Terminal Operating Mode</entry><entry>7-51</entry>
</row>
<row>
<entry>TSMON</entry><entry>Timesharing Monitor</entry><entry>7-54</entry>
</row>
<row>
<entry>UNLINK</entry><entry>Unlink Memory Module</entry><entry>7-55</entry>
</row>
<row>
<entry>VERIFY</entry><entry>Verify or Update Module Header and CRC</entry><entry>7-56</entry>
</row>
<row>
<entry>XMODE</entry><entry>Examine or Change Device Initialization Mode</entry><entry>7-57</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</appendix>

<appendix>
<title>OS-9 Error Codes</title>
<para>
The error codes are shown in both hexadecimal (first column) and
decimal (second column). Error codes other than those listed are
generated by programming languages or user programs.
</para>

<informaltable frame="none">
<tgroup cols="3">
<colspec colwidth="0.6in">
<colspec colwidth="0.6in">
<colspec colwidth="3.8in">
<thead>
<row>
<entry rowsep="1">HEX</entry>
<entry rowsep="1">DEC</entry>
<entry rowsep="0"></entry>
</row>
</thead>
<tbody>
<row>
 <entry>$C8</entry>
 <entry>200</entry>
 <entry>PATH TABLE FULL - The file cannot be opened because
 the system path table is currently full.</entry></row>
<row>
 <entry>$C9</entry>
 <entry>201</entry>
 <entry>ILLEGAL PATH NUMBER - Number too large or for non-existant path.</entry></row>
<row>
 <entry>$CA</entry>
 <entry>202</entry>
 <entry>INTERRUPT POLLING TABLE FULL</entry></row>
<row>
 <entry>$CB</entry>
 <entry>203</entry>
 <entry>ILLEGAL MODE - attempt to perform I/O function of which the device or file is incapable.</entry></row>
<row>
 <entry>$CC</entry>
 <entry>204</entry>
 <entry>DEVICE TABLE FULL - Can't add another device</entry></row>
<row>
 <entry>$CD</entry>
 <entry>205</entry>
 <entry>ILLEGAL MODULE HEADER - module not loaded because its
 sync code, header parity, or CRC is incorrect.</entry></row>
<row>
 <entry>$CE</entry>
 <entry>206</entry>
 <entry>MODULE DIRECTORY FULL - Can't add another module</entry></row>
<row>
 <entry>$CF</entry>
 <entry>207</entry>
 <entry>MEMORY FULL - Level One: not enough contiquous RAM free.
 Level Two: process address space full</entry></row>
<row>
 <entry>$D0</entry>
 <entry>208</entry>
 <entry>ILLEGAL SERVICE REQUEST - System call had an illegal code number.</entry></row>
<row>
 <entry>$D1</entry>
 <entry>209</entry>
 <entry>MODULE BUSY - non-sharable module is in use by another process.</entry></row>
<row>
 <entry>$D2</entry>
 <entry>210</entry>
 <entry>BOUNDARY ERROR - Memory allocation or deallocation request not on a page boundary.</entry></row>
<row>
 <entry>$D3</entry>
 <entry>211</entry>
 <entry>END OF FILE - End of file encountered on read.</entry></row>
<row>
 <entry>$D4</entry>
 <entry>212</entry>
 <entry>RETURNING NON-ALLOCATED MEMORY - 
attempted to deallocate memory not previously assigned.</entry></row>
<row>
 <entry>$D5</entry>
 <entry>213</entry>
 <entry>NON-EXISTING SEGMENT - device has damaged file structure.</entry></row>
<row>
 <entry>$D6</entry>
 <entry>214</entry>
 <entry>NO PERMISSION - file attributes do not permit access requested.</entry></row>
<row>
 <entry>$D7</entry>
 <entry>215</entry>
 <entry>BAD PATH NAME - syntax error in pathlist (illegal character, etc.).</entry></row>
<row>
 <entry>$D8</entry>
 <entry>216</entry>
 <entry>PATH NAME NOT FOUND - can't find pathlist specified.</entry></row>
<row>
 <entry>$D9</entry>
 <entry>217</entry>
 <entry>SEGMENT LIST FULL - file is too fragmented to be expanded further.</entry></row>
<row>
 <entry>$DA</entry>
 <entry>218</entry>
 <entry>FILE ALREADY EXISTS - file name already appears in current directory.</entry></row>
<row>
 <entry>$DB</entry>
 <entry>219</entry>
 <entry>ILLEGAL BLOCK ADDRESS - device's file structure has been damaged.</entry></row>
<row>
 <entry>$DC</entry>
 <entry>220</entry>
 <entry>ILLEGAL BLOCK SIZE - device's file structure has been damaged.</entry></row>
<row>
 <entry>$DD</entry>
 <entry>221</entry>
 <entry>MODULE NOT FOUND - request for link to module not found in directory.</entry></row>
 <row>
 <entry>$DE</entry>
 <entry>222</entry>
 <entry>SECTOR OUT OF RANGE - device file structure damaged or
incorrectly formatted.</entry></row>
<row>
 <entry>$DF</entry>
 <entry>223</entry>
 <entry>SUICIDE ATTEMPT - request to return memory where your stack is located.</entry></row>
<row>
 <entry>$E0</entry>
 <entry>224</entry>
 <entry>ILLEGAL PROCESS NUMBER - no such process exists.</entry></row>
<row>
 <entry>$E2</entry>
 <entry>226</entry>
 <entry>NO CHILDREN - can't wait because process has no children.</entry></row>
<row>
 <entry>$E3</entry>
 <entry>227</entry>
 <entry>ILLEGAL SWI CODE - must be 1 to 3.</entry></row>
<row>
 <entry>$E4</entry>
 <entry>228</entry>
 <entry>PROCESS ABORTED - process aborted by signal code 2.</entry></row>
<row>
 <entry>$E5</entry>
 <entry>229</entry>
 <entry>PROCESS TABLE FULL - can't fork now.</entry></row>
<row>
 <entry>$E6</entry>
 <entry>230</entry>
 <entry>ILLEGAL PARAMETER AREA - high and low bounds passed in fork call are incorrect.</entry></row>
<row>
 <entry>$E7</entry>
 <entry>231</entry>
 <entry>KNOWN MODULE - for internal use only.</entry></row>
<row>
 <entry>$E8</entry>
 <entry>232</entry>
 <entry>INCORRECT MODULE CRC - module has bad CRC value.</entry></row>
<row>
 <entry>$E9</entry>
 <entry>233</entry>
 <entry>SIGNAL ERROR - receiving process has previous
unprocessed signal pending.</entry></row>
<row>
 <entry>$EA</entry>
 <entry>234</entry>
 <entry>NON-EXISTENT MODULE - unable to locate module.</entry></row>
<row>
 <entry>$EB</entry>
 <entry>235</entry>
 <entry>BAD NAME - illegal name syntax</entry></row>
<row>
 <entry>$EC</entry>
 <entry>236</entry>
 <entry>BAD HEADER - module header parity incorrect</entry></row>
<row>
 <entry>$ED</entry>
 <entry>237</entry>
 <entry>RAM FULL - no free system RAM available at this time</entry></row>
<row>
 <entry>$EE</entry>
 <entry>238</entry>
 <entry>UNKNOWN PROCESS ID - incorrect process ID number</entry></row>
<row>
 <entry>$EF</entry>
 <entry>239</entry>
 <entry>NO TASK NUMBER AVAILABLE - all task numbers in use</entry></row>
</tbody>
</tgroup>
</informaltable>


<section>
<title>Device Driver Errors</title>
<para>
The following error codes are generated by I/O device drivers, and
are somewhat hardware dependent. Consult manufacturer's hardware
manual for more details.
</para>

<informaltable frame="none">
<tgroup cols="3">
<colspec colwidth="0.6in">
<colspec colwidth="0.6in">
<colspec colwidth="3.8in">
<tbody>
<row>
 <entry>$F0</entry>
 <entry>240</entry>
 <entry>UNIT ERROR - device unit does not exist.</entry></row>
<row>
 <entry>$F1</entry>
 <entry>241</entry>
 <entry>SECTOR ERROR - sector number is out of range.</entry></row>
<row>
 <entry>$F2</entry>
 <entry>242</entry>
 <entry>WRITE PROTECT - device is write protected.</entry></row>
<row>
 <entry>$F3</entry>
 <entry>243</entry>
 <entry>CRC ERROR - CRC error on read or write verify.</entry></row>
<row>
 <entry>$F4</entry>
 <entry>244</entry>
 <entry>READ ERROR - Data transfer error during disk read
 operation, or SCF (terminal) input buffer overrun.</entry></row>
<row>
 <entry>$F5</entry>
 <entry>245</entry>
 <entry>WRITE ERROR - hardware error during disk write operation.</entry></row>
<row>
 <entry>$F6</entry>
 <entry>246</entry>
 <entry>NOT READY - device has "not ready" status.</entry></row>
<row>
 <entry>$F7</entry>
 <entry>247</entry>
 <entry>SEEK ERROR - physical seek to non-existant sector.</entry></row>
<row>
 <entry>$F8</entry>
 <entry>248</entry>
 <entry>MEDIA FULL - insufficient free space on media.</entry></row>
<row>
 <entry>$F9</entry>
 <entry>249</entry>
 <entry>WRONG TYPE - attempt to read incompatible media (i.e.
 attempt to read double-side disk on single-side drive)</entry></row>
<row>
 <entry>$FA</entry>
 <entry>250</entry>
 <entry>DEVICE BUSY - non-sharable device is in use</entry></row>
<row>
 <entry>$FB</entry>
 <entry>251</entry>
 <entry>DISK ID CHANGE - Media was changed with files open</entry></row>
<row>
 <entry>$FC</entry>
 <entry>252</entry>
 <entry>RECORD IS LOCKED-OUT - Another process is accessing the 
requested record.</entry></row>
<row>
 <entry>$FD</entry>
 <entry>253</entry>
 <entry>NON-SHARABLE FILE BUSY - Another process is accessing the
requested file.</entry></row>
</tbody>
</tgroup>
</informaltable>
</section>
</appendix>

<appendix>
<title>Display System Functions</title>

<section>
<title>The Video Display</title>
<para>
Dragon Data OS-9 allows  the video display to be used in
alphanumeric, semigraphic, and graphics modes. There are many
built-in functions to control the display, which are activated by
used of various ASCII control character. Thus, these functions are
available for use by software written in any language using standard
output statements (such as &quot;PRINT&quot; in BASIC). The Dragon's Basic09
language has a Graphics Interface Module that can automatically
generate these codes using Basic09 RUN statements.
</para>
<para>
The display system has two display modes: Alphanumeric
(&quot;Alpha&quot;) mode and Graphics mode. The Alphanumeric mode also
includes &quot;semigraphic&quot; box-graphics. The Dragon Computer's display
system uses a separate - memory area for each display mode so
operations on the Alpha display do not affect the Graphics display,
and visa-versa. Either display can be selected under software
control.
</para>
<para>
8-bit characters sent to the display system are interpreted
according to their numerical value, as shown in the chart below.
</para>

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in">
<colspec colwidth="3in">
<thead>
<row>
<entry>Character Range (Hex)</entry>
<entry>Mode/Used For</entry>
</row>
</thead>
<tbody>
<row>
<entry>00 - 0E</entry>
<entry>Alpha Mode - cursor and screen control</entry>
</row>
<row>
<entry>0F - 1B</entry>
<entry>Graphics Mode - drawing and screen control</entry>
</row>
<row>
<entry>1C - 20</entry>
<entry>Not used</entry>
</row>
<row>
<entry>20 - SF</entry>
<entry>Alpha Mode - upper case characters</entry>
</row>
<row>
<entry>60 - 7F</entry>
<entry>Alpha Mode - lower case characters</entry>
</row>
<row>
<entry>80 - FF</entry>
<entry>Alpha Mode - Semigraphic patterns</entry>
</row>
</tbody>
</tgroup>
</informaltable>


<para>
The graphics and alphanumeric functions are handled by the OS-9
device driver module called &quot;CCIO&quot;.
</para>
</section>
<section>
<title>Alpha Mode Display</title>
<para>
This is the &quot;standard&quot; operational mode. It is used to display
alphanumeric characters and semigraphic box graphics, and simulates
the operation of a typical computer terminal with functions for
scrolling, cursor positioning, clear screen, line delete, etc.
</para>
<para>
Each 8-bit character is assumed to be an ASCII character and is
displayed if its high order bit (sign bit) is cleared. Lower case
letters are displayed in reverse video. If the high order bit of
the character is set it is assumed to be a &quot;Semigraphic 6&quot; graphics
box. See the Dragon manual for an explanation of semigraphics
functions.
</para>

<table frame="none">
<title>Alpha Mode Command Codes</title>
<tgroup cols="2">
<colspec colwidth="0.6in">
<colspec colwidth="4in">
<thead>
<row rowsep=1>
<entry>Control Code</entry>
<entry>Name/Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>01</entry>
<entry>HOME - return cursor to upper left hand corner of screen</entry>
</row>
<row>
<entry>02</entry>
<entry>CURSOR XY - move cursor to character X of line Y. The
binary value minus 32 of the two characters following 
the control character are used as the X and Y 
coordinates. For example, to position the cursor at character 5 of line 10,
you must give X=37 and Y42</entry>
</row>
<row>
<entry>03</entry>
<entry>ERASE LINE - erases all characters on the cursor's line.</entry>
</row>
<row>
<entry>06</entry>
<entry>CURSOR RIGHT - move cursor right one character position</entry>
</row>
<row>
<entry>08</entry>
<entry>CURSOR LEFT - move cursor left one character position</entry>
</row>
<row>
<entry>09</entry>
<entry>CURSOR UP - move cursor up one line</entry>
</row>
<row>
<entry>10</entry>
<entry>CURSOR DOWN (linefeed) move cursor down one line</entry>
</row>
<row>
<entry>12</entry>
<entry>CLEAR SCREEN - erase entire screen and home cursor</entry>
</row>
<row>
<entry>13</entry>
<entry>RETURN - return cursor to leftmost character of line</entry>
</row>
<row>

<entry>14</entry>
<entry>DISPLAY ALPHA - switch screen from graphic mode to alpha
numeric mode</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
<section>
<title>Graphics Mode Display</title>
<para>
This mode is used to display high-resolution 2- or 4-color
graphics, and it includes commands to: set color; plot and erase
individual points; draw and erase lines; position the graphics
cursor; and draw circles.
</para>
<para>
The DISPLAY GRAPHICS command must be executed before any other
graphics mode command is used. It causes the graphics screen to be
displayed and sets a current display format and color. The Li.u.t
time the DISPLAY GRAPHICS command is given, a 6144 byte display
memory is allocated by OS-9, so there must be at least this much
continuous free memory available (the OS-9 &quot;MFREE&quot; command can be
used to check free memory). This memory is retained until the END
GRAPHICS command is given, even if the program that initiated
Graphics mode finishes, so it important that the END GRAPHICS
command be used to give up the display memory when Graphics mode is
no longer needed.
</para>
<para>
Graphics mode supports two basic formats: Two-Color which has
256 horizontal by 192 vertical points (G6R mode); and Four Color
which has 128 horizontal by 192 vertical points (G6C mode). Two
color sets are available in either mode. Regardless of the
resolution of the format selected, all Graphics mode commands use a
256 by 192 point coordinate system. The X and Y coordinates are
always positive numbers which assume that point 0,0 is the lower
lefthand corner of the screen.
</para>
<para>
An invisible Graphics Cursor is used by many command to reduce
the amount of output required to generate graphics. This cursor can
be explicitly set to any point using the SET GRAPHICS CURSOR
command. Also, all other commands that include X,Y coordinates
(such as SET POINT) move the graphics cursor to the specified
position.
</para>
<table frame="none">
<title>Graphics Mode Selection Codes</title>
<tgroup cols="2">
<colspec colwidth="1in">
<colspec colwidth="3in">
<thead>
<row rowsep=1>
<entry>Code</entry>
<entry>Format</entry>
</row>
</thead>
<tbody>
<row>
<entry>00</entry>
<entry>256 x 192 two-color graphics</entry>
</row>
<row>
<entry>01</entry>
<entry>128 x 192 four-color graphics</entry>
</row>
</tbody>
</tgroup>
</table>


<table frame="none">
 <title>Color Set and Current Foreground Color Selection Codes</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="0.5in">
<colspec colname="c2" colwidth="0.4in">
<colspec colname="c3" colwidth="1in">
<colspec colname="c4" colwidth="1in">
<colspec colname="c5" colwidth="1in">
<colspec colname="c6" colwidth="1in">
<thead>
<row>
<entry align="center" namest="c3" nameend="c4">Two Color Format</entry>
<entry align="center" namest="c5" nameend="c6">Four Color Format</entry>
</row>
<row>
<entry align="center" namest="c2">Char</entry>
<entry namest="c3">Background</entry>
<entry namest="c4">Foreground</entry>
<entry namest="c5">Background</entry>
<entry namest="c6">Foreground</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows=3 valign=middle>Color Set 1</entry>
<entry align="center">00</entry>
<entry align="left">Black</entry>
<entry align="left">Black</entry>
<entry align="left">Green</entry>
<entry align="left">Green</entry>
</row>
<row>
<entry align="center">01</entry>
<entry align="left">Black</entry>
<entry align="left">Green</entry>
<entry align="left">Green</entry>
<entry align="left">Yellow</entry>
</row>
<row>
<entry align="center">02</entry>
<entry namest="c5" align="left">Green</entry>
<entry align="left">Blue</entry>
</row>
<row rowsep=1>
<entry align="center">03</entry>
<entry namest="c5" align="left">Green</entry>
<entry align="left">Red</entry>
</row>
<row>
<entry morerows=3 valign=middle>Color Set 2</entry>
<entry align="center">04</entry>
<entry align="left">Black</entry>
<entry align="left">Black</entry>
<entry align="left">Buff</entry>
<entry align="left">Buff</entry>
</row>
<row>
<entry align="center" namest="c2">05</entry>
<entry align="left">Black</entry>
<entry align="left">Buff</entry>
<entry align="left">Buff</entry>
<entry align="left">Cyan</entry>
</row>
<row>
<entry align="center" namest="c2">06</entry>
<entry namest="c5" align="left">Buff</entry>
<entry align="left">Magenta</entry>
</row>
<row rowsep=1>
<entry align="center" namest="c2">07</entry>
<entry namest="c5" align="left">Buff</entry>
<entry align="left">Orange</entry>
</row>
<row>
<entry morerows=3 valign=middle>Color Set 3*</entry>
<entry align="center">08</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Black</entry>
</row>
<row>
<entry align="center" namest="c2">09</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Dark Green</entry>
</row>
<row>
<entry align="center" namest="c2">10</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Med. Green</entry>
</row>
<row rowsep=1>
<entry align="center" namest="c2">11</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Light Green</entry>
</row>
<row>
<entry morerows=3 valign=middle>Color Set 4*</entry>
<entry align="center">12</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Black</entry>
</row>
<row>
<entry align="center" namest="c2">13</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Green</entry>
</row>
<row>
<entry align="center" namest="c2">14</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Red</entry>
</row>
<row>
<entry align="center" namest="c2">15</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Buff</entry>
</row>
</tbody>
</tgroup>
</table>

<para>
* Color sets 3 and 4 not available on PAL video system (European)
models. These color sets work only with NTSC (U.S., Canada, Japan)
models.
</para>

<table frame="none">
 <title>Graphics Mode Control Commands</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="0.8in">
<colspec colname="c1" colwidth="4in">
<thead>
<row rowsep="1">
<entry>Control Code</entry>
<entry>Name/Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>15</entry>
<entry>DISPLAY GRAPHICS - switches screen to graphics mode.
This command must be given before any other
graphics commands are used. The first time this command
is given, a 6K byte display buffer is assigned. If 6K of
contiguous memory is not available an error is returned.
This command is followed by two characters which specify
the graphics mode and current color/color set, respectively.</entry>
</row>
<row>
<entry>16</entry>
<entry>PRESET SCREEN - presets entire screen to color code
passed in next character.</entry>
</row>
<row>
<entry>17</entry>
<entry>SET COLOR - selects foreground color (and color set)
passed in next character, but does not change graphics
mode.</entry>
</row>
<row>
<entry>18</entry>
<entry>QUIT GRAPHICS - disables graphics mode and returns the
6K byte graphics memory area to OS-9 for other use, and
switches to alpha mode.</entry>
</row>
<row>
<entry>19</entry>
<entry>ERASE GRAPHICS - erases all points to background color
and homes graphics cursor to the desired position.</entry>
</row>
<row>
<entry>20</entry>
<entry>HOME GRAPHICS CURSOR - moves graphics cursor to coordinates
0,0 (lower left hand corner).</entry>
</row>
<row>
<entry>21</entry>
<entry>SET GRAPHICS CURSOR - moves graphics cursor to given
coordinates X,Y. The binary value of the two characters that immediately
follow are used as the X and Y values, respectively.</entry>
</row>
<row>
<entry>22</entry>
<entry>DRAW LINE - draws a line of the current foreground
color from the current graphics cursor position to the
given X,Y coordinates. The binary value of the two
characters that immediately follow are used as the X
and Y values, respectively. The graphics cursor is
moved to the end point of the line.</entry>
</row>
<row>
<entry>23</entry>
<entry>ERASE LINE - same as DRAW LINE except the line is
&quot;drawn&quot; in the current background color, thus erasing
the line.</entry>
</row>
<row>
<entry>24</entry>
<entry>SET POINT - sets the pixel-at point X,Y to the current
foreground color. The binary value of the two
characters that immediately follow are used as the x
and Y values, respectively. The graphics cursor is
moved to the point Set.</entry>
</row>
<row>
<entry>25</entry>
<entry>ERASE POINT - same as DRAW POINT except the point is
&quot;drawn&quot; in the current background color, thus erasing
the point.</entry>
</row>
<row>
<entry>26</entry>
<entry>DRAW CIRCLE - draws a circle of the current foreground
color with its center at the current graphics cursor
position using a radius R which is obtained using the
binary value of the next character. The graphics
cursor position is not affected by this command.</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
<section>
<title>Get Status Commands</title>
<para>
The Dragon Computer I/O driver includes OS-9 Get Status
commands that return the display status and joystick values,
respectively. These are accessable via the Basic09 Graphics
Interface Module, or by the assembly language  system calls listed
below:
</para>
<para>
GET DISPLAY STATUS:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in">
<colspec colwidth="3in">
<tbody>
<row>
<entry>Calling Format</entry>
<entry><literallayout class="Monospaced">lda #1        (path number)
ldb #SS.DStat (Getstat code $12)
os9 I$GSTT     call OS-9</literallayout></entry>
</row>
<row>
<entry>Passed</entry>
<entry>nothing</entry>
</row>
<row>
<entry>Returns</entry>
<entry><literallayout>X = address of graphics display memory
Y = graphics cursor address x=MSB y =LSB
A = color code of pixel at cursor address</literallayout></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
GET JOYSTICK VALUES:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in">
<colspec colwidth="3in">
<tbody>
<row>
<entry>Calling Format</entry>
<entry><literallayout class="Monospaced">lda #1        (path number)
ldb #SS.Joy   (Getstat code $13)
os9 I$GSTT     call OS-9</literallayout></entry>
</row>
<row>
<entry>Passed</entry>
<entry>X = 0 for right joystick; 1 for left joystick</entry>
</row>
<row>
<entry>Returns</entry>
<entry><literallayout>X = selected joystick x value (0-63)
Y = selected joystick y value (0-63)
A = $FF if fire button on; $00 if off</literallayout></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<table frame="none">
<title>Display Control Codes Condensed Summary</title>
<tgroup cols="4">
<colspec colwidth="0.9in">
<colspec colwidth="0.9in">
<colspec colwidth="0.9in">
<colspec colwidth="2.5in">
<thead>
<row rowsep="1">
<entry>1st Byte</entry>
<entry>2nd Byte</entry>
<entry>3rd Byte</entry>
<entry>Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>00</entry>
<entry></entry>
<entry></entry>
<entry>Null</entry>
</row>
<row>
<entry>01</entry>
<entry></entry>
<entry></entry>
<entry>Home Alpha Cursor</entry>
</row>
<row>
<entry>02</entry>
<entry>Column+32</entry>
<entry>Row+32</entry>
<entry>Position Alpha Cursor</entry>
</row>
<row>
<entry>03</entry>
<entry></entry>
<entry></entry>
<entry>Erase Line</entry>
</row>
<row>
<entry>06</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Right</entry>
</row>
<row>
<entry>08</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Left</entry>
</row>
<row>
<entry>09</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Up</entry>
</row>
<row>
<entry>10</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Down</entry>
</row>
<row>
<entry>12</entry>
<entry></entry>
<entry></entry>
<entry>Clear Screen</entry>
</row>
<row>
<entry>13</entry>
<entry></entry>
<entry></entry>
<entry>Carriage Return</entry>
</row>
<row>
<entry>14</entry>
<entry></entry>
<entry></entry>
<entry>Select Alpha Mode</entry>
</row>
<row>
<entry>15</entry>
<entry>Mode</entry>
<entry>Color Code</entry>
<entry>Select Graphics Mode</entry>
</row>
<row>
<entry>16</entry>
<entry>Color Code</entry>
<entry></entry>
<entry>Preset Screen</entry>
</row>
<row>
<entry>17</entry>
<entry>Color Code</entry>
<entry></entry>
<entry>Select Color</entry>
</row>
<row>
<entry>18</entry>
<entry></entry>
<entry>Quit Graphics Mode</entry>
</row>
<row>
<entry>19</entry>
<entry></entry>
<entry>Erase Screen</entry>
</row>
<row>
<entry>20</entry>
<entry></entry>
<entry>Home Graphics Cursor</entry>
</row>
<row>
<entry>21</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Move Graphics Cursor</entry>
</row>
<row>
<entry>22</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Draw Line to X/Y</entry>
</row>
<row>
<entry>23</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Erase Line to X/Y</entry>
</row>
<row>
<entry>24</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Set Point at X/Y</entry>
</row>
<row>
<entry>25</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Clear Point at X/Y</entry>
</row>
<row>
<entry>26</entry>
<entry>Radius</entry>
<entry></entry>
<entry>Draw Circle</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
</appendix>


<appendix>
<title>Key Definitions With Hexadecimal Values</title>
<literallayout class="Monospaced">
NORM  SHFT   CTRL     NORM  SHFT   CTRL     NORM  SHFT   CTRL
----  ----  ------    ----  ----  ------    ----  ----  ------
0 30  0 30      --    @ 40  ' 60  NUL 00    P 50  p 70  DLE 10
1 31  1 21  |   7C    A 41  a 61  SOH 01    Q 51  q 71  DC1 11
2 32  &quot; 22      00    B 42  b 62  STX 02    R 52  r 72  DC2 12
3 33  # 23  -   7E    C 43  c 63  ETX O3    S 53  s 73  DC3 13
4 34  $ 24      00    0 44  d 64  EOT 04    T 54  t 74  DC4 14
5 35  % 25      00    E 45  e 65  END O5    U 55  u 75  NAK 15
6 36  &amp; 26      00    F 46  f 66  ACK 06    V 56  V 76  SYN 16
7 37  ' 27      5E    G 47  g 67  BEL O7    W 57  w 77  ETB 17
8 38  ( 28  [   5B    H 48  h 68  BSP 08    X 58  x 78  CAN 18
9 39  ) 29  ]   5D    I 49  i 69  HT  O9    Y 59  y 79  EM  19
: 3A  * 2A      00    J 4A  j 6A  LF  CA    Z 5A  z 7A  SUM 1A
; 3B  + 2B      00    K 4B  k 6B  VT  OB
, 2C  &lt; 3C  {   7B    L 4C  l 6C  FF  0C
- 2D  = 3D  -   5F    M 4D  m 6D  CR  00
. 2E  &gt; 3E  }   7D    N 4E  n 6E  CO  CE
/ 2F  ? 3F  \   5C    O 4F  o 6F  CI  OF


        FUNCTION KEYS

        NORM  SHFT  CTRL
        ----  ----  ----
 BREAK   05    03    1B
 ENTER   0D    0D    0D
 SPACE   20    20    20
  &lt;-     08    18    10
  -&gt;     09    19    11
  v      0A    1A    12
  ^      0C    1C    13
</literallayout>
</appendix>

<appendix>
<title>GO51...The 51 Column by 24 Line Video Display</title>
<para>
An alternative video screen device driver, which provides a 51
column by 24 line display with upper and lower case character sets,
can be incorporated into OS-9 with the command:
<screen>
GO51
</screen>
This command replaces the normal text screen driver with one that
uses high resolution graphics to &quot;draw&quot; the characters. As there
are fever pixels (dots) per character in this mode more characters
can be displayed on the screen, albeit with some loss of character
definition.
</para>
<para>
Note, however, that the use of a high resolution graphics page
means that an extra 6K bytes will be needed in this mode. This
extra memory requirement is not normally a problem but in memory-critical
applications, such as the C and Pascal compilers, the user
can simply avoid the use of GO51.
</para>
<para>
This mode of display has a set of <emphasis>escape sequences</emphasis>
(commands) to
emulate commercial data terminals. In addition to the video screen
driver, GO51 provides a new keyboard driver which features auto-repeat.
The keyboard code allocation is the same as described in
section 2.4.3 and Appendix D.
</para>
<section>
<title>The GO51 Display Functions</title>
<para>
Like the normal 32 by 16 video display functions described in
Appendix C the 51 by 24 mode provides many built in facilities to
control the display. These functions are activated by the use of
the various escape sequences and control characters described below:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in">
<colspec colwidth="3.5in">
<thead>
<row>
<entry>Escape Sequence (Hex)</entry>
<entry>Name/Function</entry>
</row>
</thead>

<tbody>
<row>
<entry>1B 41 X Y</entry>
<entry>CURSOR XY - move cursor to column X(0-50)
and Y(0-23) where X and Y are single byte values.</entry>
</row>
<row>
<entry>1B 42</entry>
<entry>CLEAR EOL - clear from cursor to the end of
line. Cursor position remains unchanged.</entry>
</row>
<row>
<entry>1B 43</entry>
<entry>CURSOR RIGHT - move cursor right by one character position.</entry>
</row>
<row>
<entry>1B 44</entry>
<entry>CURSOR UP - move cursor up by one line.</entry>
</row>
<row>
<entry>1B 45</entry>
<entry>CURSOR DOWN - move cursor down one line.</entry>
</row>
<row>
<entry>1B 46</entry>
<entry>REVERSE ON - turn reverse field on.</entry>
</row>
<row>
<entry>1B 47</entry>
<entry>REVERSE OFF - turn reverse field off.</entry>
</row>
<row>
<entry>1B 48</entry>
<entry>UNDERLINE ON - turn underline on.</entry>
</row>
<row>
<entry>1B 49</entry>
<entry>UNDERLINE OFF - turn underline off.</entry>
</row>
<row>
<entry>1B 4A</entry>
<entry>CLEAR EOS - clear from cursor to end of
screen. Cursor position remains unchanged.</entry>
</row>
</tbody>
</tgroup>
</informaltable>




<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in">
<colspec colwidth="3.5in">
<thead>
<row>
<entry>Control Character (Hex)</entry>
<entry>Name/Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>07</entry>
<entry>BELL - generates a short audible tone.</entry>
</row>
<row>
<entry>08</entry>
<entry>BACKSPACE (CURSOR LEFT) - moves cursor left one character position.</entry>
</row>
<row>
<entry>0A</entry>
<entry>LINE FEED - move cursor down by one line.</entry>
</row>
<row>
<entry>0B</entry>
<entry>CURSOR HOME - move cursor to home position 0,0 (top left).</entry>
</row>
<row>
<entry>0C</entry>
<entry>CLEAR SCREEN - clears the screen and home cursor.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</appendix>



<appendix>
<title>Using the Serial Interface</title>
<para>
For those who wish to use the serial port, the input or
output path of a program may be redirected to the serial port of
your Dragon computer.
</para>
<para>
This is done by including the following module in the OS-9 kernel:
</para>
<literallayout>
ACIA51 - Serial Device Driver
</literallayout>
<para>
To load this module into the kernel enter the following command line:
</para>
<literallayout>
LOAD /D0/CMDS/ACIA51
</literallayout>

<section>
<title>Serial Printer Implementation</title>
<para>
For those with a serial printer, you can use the serial port
in the redirection of a program's output path by including the
following modifier at the end of a command line:
</para>
<literallayout>
&gt;/P1
</literallayout>
<para>
The baud rate of the serial port may be changed as follows:
</para>
<literallayout>
XMODE /P1 BAUD=3
</literallayout>
<para>
This will change the baud rate to 1200 characters per second.
For a detailed description of the baud rate see the XMODE
command description.
</para>
</section>
<section>
<title>Serial Terminal Implementation</title>
<para>
For those who wish to connect two Dragon computers, running
OS-9, together using the serial port, redirection of the input
or output paths is possible using the following modifier at
the end of a command line:
</para>
<literallayout>
&gt;/T1 - for an output path
</literallayout>
<literallayout>
&lt;/T1 - for an input path
</literallayout>
<para>
To pass a file of data between the two computers, one must be
configured for input from the serial port and the other
configured for output:
</para>
<literallayout>
Computer 1,        BUILD TEXT &lt;/T1 - input to port
</literallayout>
<literallayout>
Computer 2,        BUILD &lt;TEXT /T1 - output to port
</literallayout>
<para>
Using the above example, the text file on computer 2 will be
transferred to a file called TEXT on computer 1.
</para>
<para>
When the command line is entered on computer 1, the system will
reply with a question mark and wait for information from the
serial port. The command line on computer 2 will send data to
the now waiting computer 1. A string of question marks will now
be seen, this is the number of lines sent and recieved by the
respective computers.
</para>
<para>
To create a log-off sequence after such a transfer, use the DISPLAY
command as follows:
</para>
<literallayout>
Computer 1,        BUILD &lt;TEXT /T1 ; DISPLAY 0A 0D &gt;/T1
</literallayout>
</section>
</appendix>
</book>