Mercurial > hg > Members > kono > nitros9-code
changeset 142:4cd37950c605
More splitups.
| author | roug |
|---|---|
| date | Sun, 07 Jul 2002 09:54:04 +0000 |
| parents | 21649cf64510 |
| children | 740f7868679c |
| files | docs/nitros9guide/acia51.appendix docs/nitros9guide/commands.appendix docs/nitros9guide/os9guide.docbook docs/nitros9guide/preface-dragon.preface |
| diffstat | 4 files changed, 359 insertions(+), 4845 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/acia51.appendix Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,88 @@ +<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> +>/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> +>/T1 - for an output path +</literallayout> +<literallayout> +</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 </T1 - input to port +</literallayout> +<literallayout> +Computer 2, BUILD <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 <TEXT /T1 ; DISPLAY 0A 0D >/T1 +</literallayout> +</section> +</appendix>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/commands.appendix Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,159 @@ +<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>
--- a/docs/nitros9guide/os9guide.docbook Sun Jul 07 08:58:56 2002 +0000 +++ b/docs/nitros9guide/os9guide.docbook Sun Jul 07 09:54:04 2002 +0000 @@ -3,6 +3,20 @@ <!ENTITY replend ">"> <!ENTITY repeatst "{"> <!ENTITY repeaten "}"> + <!ENTITY preface SYSTEM "preface-dragon.preface"> + <!ENTITY chap1 SYSTEM "chap1.chapter"> + <!ENTITY chap2 SYSTEM "chap2.chapter"> + <!ENTITY chap3 SYSTEM "chap3.chapter"> + <!ENTITY chap4 SYSTEM "chap4.chapter"> + <!ENTITY chap5 SYSTEM "chap5.chapter"> + <!ENTITY chap6 SYSTEM "chap6.chapter"> + <!ENTITY chap7 SYSTEM "chap7.chapter"> + <!ENTITY commandsapp SYSTEM "commands.appendix"> + <!ENTITY errorcodesapp SYSTEM "errorcodes.appendix"> + <!ENTITY displayapp SYSTEM "display.appendix"> + <!ENTITY keysapp SYSTEM "keys.appendix"> + <!ENTITY go51app SYSTEM "go51.appendix"> + <!ENTITY acia51app SYSTEM "acia51.appendix"> <!ENTITY attrref SYSTEM "attr.refentry"> <!ENTITY backupref SYSTEM "backup.refentry"> <!ENTITY binexref SYSTEM "binex.refentry"> @@ -74,4850 +88,19 @@ </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 "BOOT". After a few seconds of disk activity you should -see a screen with the words "OS9BOOT".</para></listitem> - -<listitem><para>OS-9 will then begin -its "bootstrap" loading process, which -involves ten to twenty seconds of disk activity. When the system -startup has finished, a message followed by an "OS9:" 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 "BOOT", 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 "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 <- left arrow key which you can use to erase typing mistakes. -</para> -<para> -Your main disk drive is known to to OS-9 as "/D0" and is often -called "drive zero". If you have a second disk drive (drive one), -OS-9 recognizes it as "/D1". Why would anybody put a "/" in a name? -Because all input and output devices have names like files, and -names that start with "/" 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 "OS9:" 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 "<emphasis>dir</emphasis>ectory"). -This will display a list of the files -on the System Disk. Just type: -<screen> -dir -</screen> -followed by a "return". 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 "OS9Boot" contains the OS-9 program in 6809 machine -language, which was loaded into memory during the bootstrap -operation. -</para> -<para> -The file "startup" is a "command file" 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 -"OS9Boot" file contain binary data such as machine language -programs. These files are called "binary files", 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 "branches" - files which are additional -directories of file names instead of programs or data. They in turn -can have even more "branches" - 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 "CMDS", -"SYS", and "DEFS". -The file "CMDS" 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 "Y". - -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 "Y", then "ENTER". -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 "Y" 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 "write" errors. The second -phase is the "verify" 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 "shell" 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 "OS9:" 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 "execution directory", usually "CMDS", 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 "data directory" is searched. If a file having -the name given is found, it is processed as a "procedure -file" 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 "data directory" and the "execution -directory". 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 "parameters" 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 "modifiers" 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> ->/P -</screen> -<para> -The ">" 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 "/P" (See 3.2). For example, to redirect the output of the -"dir" command to the printer, enter: -</para> -<screen> -DIR >/P -</screen> -<para> -The "xmode" 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 "E" -(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 -"filename1" to it. "filename1" 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 "x" 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 "e" 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 "chd" 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 "/TERM". -</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 "locked". 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 "control -keys" 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 -"I/O paths". Paths are analogous to "software I/O channels" 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 "opened"), OS-9 must be given -a description of the "routing" of the path. This description is -given in the form of a character string called a "pathlist". It -specifies a particular mass-storage file, directory file, or any -other I/O device. OS-9 "pathlists" are -similar to "filenames" used -by other operating systems. -</para> -<para> -The name "pathlist" is used instead -of "pathname" or "filename" -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 "/" 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 "/" 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 "device descriptor -modules" kept by OS-9 in an internal data structure called the -"module directory" (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 -"files". Each file has a name which is entered in a directory file. -Every multifile device has a master directory (called the "root -directory") 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 "format" command. -</para> -<para> -Pathlists that refer to multifile devices may have more than one -name. For example, to refer to the file "mouse" whose name appears -in the root directory of device "D1" (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 "device directory", 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 "dir" 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 "TERM", -"P", "D0" and -"D1". The root directory of device -"D0" includes two directory -files, DEFS and CMDS, and one ordinary file "startup". Notice that -device "D1" has in its root directory three ordinary files. In -order to access the file "file2" on -device "d1", a pathlist having -two names must be used: -<screen> -list /d1/file2 -</screen> -To construct a pathlist to access the file "dir" on device -"d0" it is necessary to include in the pathlist the name of the -intermediate directory file "CMDS". For example, to copy this file -requires a pathlist having three names to describe the "from" 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 "makdir" 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 ("d1") has been freshly formatted so that it has a root -directory only. The build command can be used to create a text file -on "d1". The build command will print out "?" 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 "dir" 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 "list" 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 "build" 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 "makdir" command is -used. The new directory will be called "NEWDIR". 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 "NEWDIR" 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 "file1": -</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 ("D1"), the name of the next lower directory -("NEWDIR"), then the actual file name ("file1.copy"). 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 "makdir" to create additional new directories -within "NEWDIR", and so on, limited only by available disk -space. -</para> -</section> - -<section> -<title>Deleting Directory Files</title> -<para> -The "del" 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 "attr" 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 "del" 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 "working directories" associated -with it at all times: a "data directory" and an "execution -directory". 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> ----> When the first character of a pathlist IS a "/", -processing of the pathlist starts at the device directory, -e.g., the first name MUST be a device name. -</para> -<para> ----> When the first character of a pathlist IS NOT a "/", -processing of the pathlist starts at the current working -directory. -</para> -<para> -Notice that pathlists starting with a "/" -<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 -"/D1/PETE/GAMES" 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 -"current execution directory" and the "current data directory". 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> ----> 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> ----> 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 "D0"), and -the working directory to be a directory called "cmds" on the same -drive ("/D0/cmds"). On timesharing systems, the "login" 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 "/D0/CMDS" and the current -data directory is "/D0/JONES", 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 "copy" 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 "chd" and "chx" 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 "/" , 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 "name substitutes" are -available. They are: -</para> -<para> -"." refers to the present working directory -</para> -<para> -".." refers to the directory that contains the name of the present -directory (e.g., the next highest level directory) -</para> -<para> -"..." 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 "temp" 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 ".." 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 "." 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 "owner" of the file. -</para> -<para> -Usage and security functions are based on "attributes", which -define how and by whom the file can be accessed. There are a total -of seven attributes, each of which can be turned "off" or -"on" -independently. The "d" 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 "public" (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 "binary" files from -being used as "text" 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 "public permissions" work the same way as -the "owner permissions" 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 -"write permit to public" and "read permit to public", 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 "DIR" command may be used to examine the security permissions -of the files in any particular directory when the "e" option is -used. An example using the "dir e" 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 "attributes" 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 "attr" command is used to examine or -change a file's attributes. Typing "attr" 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 "directory" 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 "attr" command -<emphasis>cannot</emphasis> be used to turn -the directory (d) attribute on (only "makdir" 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 "file pointer" is established -for it. Bytes within the file are addressed like memory, and the -file pointer holds the "address" of the next byte in the file to be -written to or read from. The OS-9 "read" and "write" 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 "seek" 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 -"read" 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 "copy", -"del", 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 ("lines") 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 "list" -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, "GET", "PUT", and "SEEK" functions operate on -random-access files. -</para> -<para> -The file is organized as an ordered sequence of "records". 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 "fields". 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 "module header" 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 "load record" -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 "verify" 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 "binary" data, attempts to "list -program files will result in the display of random characters on the -terminal giving strange effects. The "dump" 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 "makdir" command, and -can be identified by the "d" 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 "makdir" command initializes all records in a new directory -to be unused entries except for the first two entries. These -entries have the names "." and ".." 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 "dir" 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 "dump" 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 "logical -sector number", 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 "file descriptor -sector", 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 "segments". -</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 "parsed") 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 ("verbs") -</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 "built-in command", 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 >/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 "asm</entry> -</row> -<row> -<entry>>/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 "built-in" -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 ( # ; ! < > & ) 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 "#n" where n is the decimal number of pages, or in 1024 -byte increments using the modifier "#nK". 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 -"standard I/O paths" 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 -"redirect" 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 "error output" 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><</entry> -<entry>Redirect the standard input path</entry> -</row> -<row> -<entry>></entry> -<entry>Redirect the standard output path</entry> -</row> -<row> -<entry>>></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 "list" can be redirected to write to the system printer -instead of the terminal: -</para> -<screen> -OS9: LIST correspondence >/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 "/D1/savelisting": -</para> -<screen> -OS9: DIR >/D1/savelisting -</screen> -<para> -If the LIST command is used on the file "/D1/savelisting", 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 ";" character. For example: -</para> -<screen> -OS9: COPY myfile /D1/newfile ; DIR >/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 "x" -option), otherwise, ";" and "return" are identical -separators. -</para> -<para> -Here are some more examples: -</para> -<screen> -OS9: copy oldfile newfile; del oldfile; list newfile - -OS9: dir >/d1/myfile ; list temp >/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 "wait" -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 "&" 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 >/P& -&007 - -OS9: -</screen> -<para> -This command line will cause shell to start the DIR command -executing, print the process ID number (&007), and then immediately -display the "OS9:" 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 "status summary" of all -processes you have created by using the PROCS command. Below is -another example: -</para> -<screen> -OS9: DIR >/P& LIST file1& COPY file1 file2 ; DEL temp -</screen> -<para> - -</para> -<para> -Because they were followed by "&" 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 (";") was specified. -</para> -</section> - -<section> -<title>Pipes and Filters</title> -<para> -The third kind of separator is the "!" character which is used to -construct "pipelines". Pipelines consist of two or more concurrent -programs whose standard input and/or output paths connect to each -other using "pipes". -</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 "readers" and several -"writers". 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 "!" separators is processed. For each "!", the standard -output of the program named to the left of the "!" is redirected via -a pipe to the standard input of the program named to the right of -the "!". Individual pipes are created for each "!" present. -For example: -</para> -<screen> -OS9: update <master_file ! sort ! write_report >/p -</screen> -<para> -In the example above, the program "update" has its input redirected -from a path called "master_file". Its standard output becomes the -standard input for the program "sort". Its output, in turn, becomes -the standard input for the program "write_report", 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 -"gets ahead" 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 "filters". -The "tee" command, which uses -pipes to allow data to be simultaneously "broadcast" 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) >/p -</screen> -gives the same result as: -<screen> -OS9: dir /d0 >/p; dir /d1 >/p -</screen> -except for the subtle difference that the printer is "kept" -continuously in the first example; in the second case another user -could "steal" the printer in between the "dir" 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)& -</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 "DSAVE" command generates a procedure file to copy all the -files in a directory. The example below shows how the output of -"DSAVE" 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> +&preface; +&chap1; +&chap2; +&chap3; +&chap4; +&chap5; +&chap6; +&chap7; +&commandsapp; +&errorcodesapp; +&displayapp; +&keysapp; +&go51app; +&acia51app; -<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 (";", "&", or "!"). -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: "text" 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 -"ex" command is used where the shell is needed to initiate execution -of a program without the overhead of a suspended "shell" 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 "shell" command. If the standard input path is -redirected to a mass storage file, the new "incarnation" 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 "procedure file". 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 "batch" or -"background" 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 "in the background" while the computer is -unattended or while the user is running other programs "in the -foreground". -</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 <procfile - -OS9: procfile -</screen> -<para> -Both do exactly the same thing: execute the commands of the file -"procfile". To run the procedure file in a "background" mode you -simply add the ampersand operator: -</para> -<screen> -OS9: procfile& -</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 >>stat1& proc2 T >>stat2& -</screen> -<para> -Note that the built-in command "T" (copy input lines to error -output) was used above. They make the output file contain a record -of all lines executed, but without useless "OS9" prompts intermixed. -The "-x" 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 "printerr" 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 "/d0/sys/errmsg". -Once the "printerr" -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 -"B" 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 "-x" 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 -"adventure", 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 "startup" 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 "TERM", "T1", -"T2", and "T3". -</para> -<programlisting> -* system startup procedure file -echo Please Enter the Date and Time -setime </term -printerr -tsmon /t1& -tsmon /t2& -tsmon /t3& -</programlisting> -<para> -NOTE: This LOGIN procedure will not work until a password file -called "/D0/SYS/PASSWORD" has been created. For more information, -please see the LOGIN command description. -</para> -<para> -The example above deserves special attention. Note that the -"setime" command has its input redirected to the system console -"term", 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 "&" character at the -end of a command line which causes the shell to run your command as -a "background task". -</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 "tick", 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 "batch" 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 "states" 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 "signal". 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 "fork" 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 -"parent process", and the newly created process is called the "child -process". 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 "siblings" 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 "family" 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 "inherits" 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 "process ID", 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 "address space". -In Level One systems, all processes share the single address -space. A "data area", 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 "module -directory", which has the address of every module present in memory. -The 6809 instruction set supports a type of program called -"reentrant code" which means the exact same "copy" of a program can -be shared by two or more different processes simultaneously without -affecting each other, provided that each "incarnation" 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 "module header" 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 "OS-9 System Programmer's Manual". -</para> -<para> -Programs can also be explicitly loaded into memory using the -"load" 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 "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 "load" is the "unlink" 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 "unlink" command is -generally used in conjunction with the "load" command (programs -loaded by fork are automatically unlinked when the program -terminates). -</para> -<para> -Here is an example of the use of -"load" and "unlink" to lock a -program in memory. Suppose the "copy" command will be used five -times. Normally, the copy command would be loaded each time the -"copy" command is called. If the "load" command is used first, -"copy" 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 "unlink" 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 "position-independent -code", or "PIC". 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 "load" 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 "load" (map) memory resident programs at -different addresses in each process' address space). This characteristic -can lead to a sometimes troublesome phenomenon called -"memory fragmentation". 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 "unlinked", 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 "mfree" command shows the location and size of each unused -memory area and the "mdir e" 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 ("/D0") when the -system is running. -</para> -<para> -Two files used during the system startup operation, "OS9Boot" and -"startup" <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 "OS9Boot" loaded into RAM memory by the -"bootstrap" 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 "OS9Boot" 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 "OS9Gen" 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 "/d0/SYS" 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 "login" 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 "login", "tsmon", or -"printerr" 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 "/d0/startup" is a shell procedure file (see 4.6) which -is automatically processed immediately after system startup. The -user may include in "startup" any legal shell command line. Often -this will include "setime" 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 "/d0/CMDS" is the system-wide command object code -directory, which is normally shared by all users as their working -execution directory (see 3.7). If "shell" is not part of the -"OS9Boot" file, it must be present in this directory. The system -startup process "sysgo" makes CMDS the initial execution directory. -</para> -</section> - -<section> -<title>The DEFS Directory</title> - -<para> -The directory "/d0/DEFS" 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 "use" 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 "chx" and -"chd" (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 "OS9Boot" file must be created and linked by the "OS9Gen" or -"Cobbler" commands. -</para></listitem> - -<listitem><para> -The "startup" 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 "dsave" command -</para></listitem> - -<listitem><para> -By the "backup" 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; -©ref; -&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 "PRINT" 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 -("Alpha") mode and Graphics mode. The Alphanumeric mode also -includes "semigraphic" 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 "CCIO". -</para> -</section> -<section> -<title>Alpha Mode Display</title> -<para> -This is the "standard" 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 "Semigraphic 6" 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 "MFREE" 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 -"drawn" 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 -"drawn" 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 " 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 & 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 < 3C { 7B L 4C l 6C FF 0C -- 2D = 3D - 5F M 4D m 6D CR 00 -. 2E > 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 - <- 08 18 10 - -> 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 "draw" 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> ->/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> ->/T1 - for an output path -</literallayout> -<literallayout> -</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 </T1 - input to port -</literallayout> -<literallayout> -Computer 2, BUILD <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 <TEXT /T1 ; DISPLAY 0A 0D >/T1 -</literallayout> -</section> -</appendix> </book>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/preface-dragon.preface Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,84 @@ +<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>