Mercurial > hg > Members > kono > nitros9-code
changeset 103:32bd5072b3a5
Added the OS9 User's Manual for Dragon-64.
It shouldn't be too difficult to add the Coco differences, but I don't
have that manual.
| author | roug |
|---|---|
| date | Sat, 06 Jul 2002 09:46:49 +0000 |
| parents | 3c2d500eaf47 |
| children | 0859906a95a8 |
| files | docs/nitros9guide/makefile docs/nitros9guide/os9guide.docbook |
| diffstat | 2 files changed, 8067 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/makefile Sat Jul 06 09:46:49 2002 +0000 @@ -0,0 +1,22 @@ +SRC=os9guide +STYLESHEET=docbook-utils.dsl + +all: $(SRC).html + +$(SRC).pdf: $(SRC).docbook + docbook2pdf -d docbook-utils-a4.dsl#print $(SRC).docbook + +$(SRC).ps: $(SRC).docbook + docbook2ps -d docbook-utils-a4.dsl#print $(SRC).docbook +# docbook2ps -d $(STYLESHEET) $(SRC).docbook + +$(SRC).html: $(SRC).docbook + rm -f *.htm *.html +# jade -t sgml -V html-index -d /usr/share/sgml/docbook/dsssl-stylesheets-1.64/html/docbook.dsl $(SRC).docbook +# collateindex.pl -p -o index.docbook HTML.index + docbook2html -d docbook-utils-a4.dsl#html $(SRC).docbook + +clean: + rm -f *.htm *.html $(SRC).pdf $(SRC).ps +print: $(SRC).ps + psnup -2 $(SRC).ps | lpr
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/os9guide.docbook Sat Jul 06 09:46:49 2002 +0000 @@ -0,0 +1,8045 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ + <!ENTITY replstart "<"> + <!ENTITY replend ">"> + <!ENTITY repeatst "{"> + <!ENTITY repeaten "}"> + ]> +<book id="os9guide" lang="en"> +<bookinfo> + <title>OS-9 Operating System User's Guide</title> + + <publisher> + <publishername>Cleglen Publishing Limited</publishername> + <address> + <city>Cardiff</city> + </address> + </publisher> + +<copyright> + <year>1983</year> + <holder>Dragon Data Ltd., and Microware Systems Corporation.</holder> +</copyright> + + <legalnotice> + <para>All Rights Reserved. Reproduced under license from +Microware Systems Corporation.</para> + </legalnotice> + + +</bookinfo> + +<preface> +<title>Welcome to OS-9!</title> +<titleabbrev>Introduction</titleabbrev> +<para> +The heart of your Dragon Computer is an amazing device: the +6809 microprocessor chip. This advanced microcomputer can run the +kind of sophisticated software normally found only on much larger +and costly computers. Because the OS-9 operating system was designed +by the same people who designed the 6809 microcomputer, together +they provide an extremely efficient and powerful combination. +</para> +<para> +The foundation of a computer's software system is its +<emphasis>Operating System</emphasis> or "OS". It is the master control +program that interfaces all other software to the system's hardware. Some +of the things it must do are performing input and output operations, +coordinating memory use, and many other "housekeeping" functions. All +other software - programming languages, applications programs, etc. - +live in your computer's memory along with the OS and depend on it to +communicate with you using the keyboard and display and to store and +retrieve data on disks, etc. Because virtually all other software relies +on the OS, your computer's performance depends on the capabilities and +efficiency of its OS. +</para> + +<para> +OS-9's overall structure was based on the famous UNIX<footnote id="unixdesc"> +<para> +Unix is an operating system designed by Bell Telephone +Laboratories, which is becoming widely recognized as a standard for +mini and micro operating systems because of its versatility and +elegant structure. +</para> +</footnote> +operating system, which has been widely acclaimed as the operating +system of the future because of its versatility, logical structure, +and friendly user commands. The OS-9 family of advanced software is +not only more powerful than most other microcomputer scftware - it +is also much easier to learn and use. +</para> +<para> +Some of the advanced OS-9 features you'll learn about in this +book are: +</para> +<orderedlist numeration="arabic"> + +<listitem><para>Friendly Unix<footnoteref linkend="unixdesc">-type +user interface and environment</para></listitem> + +<listitem><para>Multiuser/Multitasking Real-Time Operating System</para></listitem> + +<listitem><para>Extensive support for structured, modular programming</para></listitem> + +<listitem><para>Device-independent interrupt-driven input/output system</para></listitem> + +<listitem><para>Multi-level directory file system</para></listitem> + +<listitem><para>Fast Random-Access File System</para></listitem> + +<listitem><para>Readily Expandable and Adaptable Design</para></listitem> + +</orderedlist> +<para> +If you don't know what some of these thing mean yet - don't +worry. As you explore OS-9 you'll soon learn how they enhance the +capability of your Dragon Computer and make it so much easier to use +in almost any application. +</para> +<para> +OS-9 has many commands and functions - definitely more than +you can learn in an evening! The best way to become an OS-9 expert +is to study this manual carefully, section-by-section, taking tire +to try out each command or function. Because many functions affect +others, you'll find this manual extensively cross-referenced so you +can skip ahead to help you understand a new topic. Taking the time +to study this book will certainly increase your knowledge and +enjoyment of OS-9. +</para> +<para> +But if you can't wait, at least read the rest of this chapter, +scan the command descriptions in Chapter 7, and have fun +experimenting! +</para> +</preface> + +<chapter> +<title>Getting Started...</title> + +<section> +<title>What You Need to Run OS-9</title> +<para> +OS-9 has been tailored to run on your standard, unmodified Dragon +Computer. To use it you'll need the following things: +</para> +<itemizedlist mark="bullet"> + <listitem><para>A 64K Memory Dragon Computer</para></listitem> + <listitem><para>A Dragon Disk Drive With Contoller Cartridge</para></listitem> + <listitem><para>An OS-9 Dragon System Disk</para></listitem> +</itemizedlist> +<para> +OS-9 is also ready to use the following optional equipment that you +may have now or may obtain in the future: +</para> +<itemizedlist mark="bullet"> + <listitem><para>Additional Expansion Disk Drive(s)</para></listitem> + <listitem><para>A Parallel Printer</para></listitem> + <listitem><para>Game Joysticks</para></listitem> + <listitem><para>Other OS-9 Compatible Languages and Software</para></listitem> +</itemizedlist> + +<section> +<title>Starting the System</title> +<para> +To start up OS-9 follow these steps: + +<orderedlist numeration="arabic"> +<listitem><para>Turn the Dragon Computer and disk drive(s) on. You should see +the usual Basic greeting message on the screen.</para></listitem> + +<listitem><para>Insert the OS-9 System Disk in drive zero and close the door.</para></listitem> + +<listitem><para>Type "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> + +<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> + +<refentry id="attr"> +<refnamediv> +<refname id="attrname">ATTR</refname> +<refpurpose>Change file security attributes</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>ATTR</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="opt">&repeatst; &replstart;permission abbreviations&replend; &repeaten;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> + +This command is used to examine or change the security permissions +of a file. To enter the command, type "ATTR" followed by the +pathlist for the file who's security permissions are to be changed, +followed by a list of permissions which are to be turned on or off. +A permission is turned on by giving its abbreviation, or turned off +by preceding its abbreviation with a minus sign. Permissions not +explicitly named are not affected. If no permissions are given the +current file attributes will be printed. You can not change the +attributes of a file which you do not own (except for user zero, who +can change the attributes of any file in the system). +</para> +<para> +The file permission abbreviations are: +</para> +<literallayout> + d = Directory file + s = Sharable file + r = Read permit to owner + w = Write permit to owner + e = Execute permit to owner +pr = Read permit to public +pw = Write permit to public +pe = Execute permit to public +</literallayout> + +<para> +The ATTR command may be used to change a directory file to a +non-directory file if all entries have been deleted from it. Since the +DEL command will only delete non-directory files, this is the only +way a directory may be deleted. You cannot change a non-directory +file to a directory file with this command (see MAKDIR). +</para> +<para> +For more information see: 3.8, 3.8.1 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +attr myfile -pr -pw + +attr myfile r w e pr rw pe + + +attr datalog +-s-wr-wr +</screen> +</refsect1> +</refentry> + +<refentry id="backup"> +<refnamediv> +<refname id="backupname">BACKUP</refname> +<refpurpose>Make a backup copy of a disk</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>BACKUP</command> +<arg choice="opt"> + <option>e</option> +</arg> +<arg choice="opt"> + <option>s</option> +</arg> +<arg choice="opt"> + <option>-v</option> +</arg> +<arg choice="opt">&replstart;devname&replend; + <arg choice="opt">&replstart;devname&replend;</arg></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to physically copy all data from one device to +another. A physical copy is performed sector by sector without +regard to file structures. In almost all cases the devices +specified mun.t have the exact same format (size, density, etc.) and +must not have defective sectors. +</para> +<para> +If both device name are omitted the names "/d0" and "/d1" are +assumed. If the second device name is omitted, a single unit backup +will be performed on the drive specified. +</para> +<para> +The options are: +</para> +<literallayout> + E = Exit if any read error occurs. + S = Print single drive prompt message. + -V = Do not verify. +#nK = more memory makes backup run faster +</literallayout> +</refsect1> +<refsect1><title>Examples</title> +<screen> +backup /D2 /D3 + +backup -V + + + +OS9: backup + +Ready to BACKUP from /D0 to /D1 ?: Y +MYDISK is being scratched +OK ?: Y +Number of sectors copied: $04D0 +Verify pass +Number of sectors verified: $04D0 +OS9: +</screen> +<para> +Below is an example of a single drive backup. BACKUP will read a +portion of the source disk into memory, you remove the source disk +and place the destination disk into the drive, BACKUP writes on the +destination disk, you remove the destination disk and place the +source disk into the drive. This continues until the entire disk +has been copied. Giving BACKUP as much memory as possible will cause +fewer disk exchanges to be required. +</para> +<para> +For more information see: 1.1.2 +</para> +<screen> +OS9:backup /D0 #10k + +Ready to BACKUP from /D0 to /D0 ?: Y +Ready DESTINATION, hit a key: +MYDISK is being scratched +OK ?: Y +Ready SOURCE, hit a key: +Ready DESTINATION, hit a key: +Ready SOURCE, hit a key: +Ready DESTINATION, hit a key: + +(several repetitions) + +Ready DESTINATION, hit a key: +Number of sectors copied: $4D0 +Verify pass +Number of sectors verified: $4D0 +</screen> +</refsect1> +</refentry> + +<refentry id="binex"> +<refnamediv> +<refname id="binexname">BINEX / EXBIN</refname> +<refpurpose>Convert Binary To S-Record File / Convert S-Record To Binary File</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> + <command>BINEX</command> + <arg choice="plain">&replstart;path1&replend;</arg> + <arg choice="plain">&replstart;path2&replend;</arg> +</cmdsynopsis> +<cmdsynopsis> + <command>EXBIN</command> + <arg choice="plain">&replstart;path2&replend;</arg> + <arg choice="plain">&replstart;path1&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +S-Record files are a type of text file that contains records that +represent binary data in hexadecimal character form. This +Motorola-standard format is often directly accepted by commercial PROM +programmers, emulators, logic analyzers and similar devices that are +interfaced RS-232 interfaces. It can also be useful for +transmitting files over data links that can only handle character-type +data; or to convert OS-9 assembler or compiler-generated +programs to load on non-OS-9 systems. +</para> +<para> +BINEX converts "path1", an OS-9 binary format file, to a new file +named "path2" in S-Record format. If invoked on a non-binary load +module file, a warning message is printed and the user is asked if +BINEX should proceed anyway. A "Y" response means yes; any other +answer will terminate the program. S-Records have a header record +to store the program name for informational purposes and each data +record has an absolute memory address which is not meaningful to OS-9 +since it uses position-independent-code. However, the S-Record +format requires them so BINEX will prompt the user for a program +name and starting load address. For example: +</para> +<screen> +binex /d0/cmds/scanner scanner.S1 +Enter starting address for file: <emphasis>$100</emphasis> +Enter name for header record: <emphasis>scanner</emphasis> +</screen> +<para> +To download the program to a device such as a PROM programmer +(for example using serial port T1) type: +</para> +<screen> +list scanner.S1 >/T1 +</screen> +<para> +EXBIN is the inverse operation; "path1" is assumed to be a +S-Record format text file which EXBIN converts to pure binary form on +a new file called "path2". The load addresses of each data record +must describe continguous data in ascending order. +</para> +<para> +EXBIN does not generate or check for the proper OS-9 module +headers or CRC check value required to actually load the binary +file. The IDENT or VERIFY commands can be used to check the +validity of the modules if they are to be loaded or run. +Example: +</para> +<screen> +exbin program.S1 cmds/program +</screen> +</refsect1> +</refentry> + +<refentry id="build"> +<refnamediv> +<refname id="buildname">BUILD</refname> +<refpurpose>Build a text file from standard input</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>BUILD</command> +<arg choice="plain">&replstart;path&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to build short text files by copying the +standard input path into the file specified by +&replstart;path&replend;. BUILD creates a file according to the pathlist parameter, +then displays a "?" +prompt to request an input line. Each line entered is written to +the output path (file). Entering a line consisting of a carriage +return only causes BUILD to terminate. +</para> + +</refsect1> +<refsect1><title>Example:</title> + +<screen> +build small_file +build /p (copies keyboard to printer) +</screen> +<para> +The standard input path may also be redirected to a file. Below is +an example: +</para> +<screen> +build <mytext /T2 (copies file "mytext" to terminal T2) + + +OS9: build newfile + +? The powers of the OS-9 +? operating system are truly +? fantastic. +? [RETURN] + +OS9: list newfile + +The powers of the OS-9 +operating system are truly +fantastic. +</screen> +</refsect1> +</refentry> + +<refentry id="chd"> +<refnamediv> +<refname>CHD/CHX</refname> +<refpurpose>Change working data directory / Change working execution directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>chd</command> +<arg choice="plain"> + &replstart;pathlist&replend; +</arg> +</cmdsynopsis> +<cmdsynopsis> +<command>chx</command> +<arg choice="plain"> + &replstart;pathlist&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +These are shell "built in" commands used to change OS-9's working +data directory or working execution directory. Many commands in OS-9 +work with user data such as text files, programs, etc. These +commands assume that a file is located in the working data +directory. Other OS-9 commands will assume that a file is in the +working execution directory. +</para> +<para> +NOTE: These commands do not appear in the CMDS directory as they +are built-in to the SHELL. +</para> +<para> +For more information see: 3.7, 3.7.2 + + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +chd /d1/PROGRAMS + +chx .. + +chx binary_files/test_programs + +chx /D0/CMDS; chd /D1 +</screen> +</refsect1> +</refentry> + +<refentry id="cmp"> +<refnamediv> +<refname>CMP</refname> +<refpurpose>File Comparison Utility</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>cmp</command> +<arg choice="plain"> + &replstart;file1&replend; +</arg> +<arg choice="plain"> + &replstart;file2&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Opens two files and performs a comparison of the binary values of +the corresponding data bytes of the files. If any differences are +encountered, the file offset (address) and the values of the bytes +from each file are displayed in hexadecimal. +</para> +<para> +The comparison ends when end-of-file is encountered on either +file. A summary of the number of bytes compared and the number of +differences found is then displayed. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9: cmp red blue + + Differences + +byte #1 #2 +======== == == +00000013 00 01 +00000022 B0 B1 +0000002A 9B AB +0000002B 3B 36 +0000002C 6D 65 + +Bytes compared: 0000002D +Bytes different: 00000005 + +OS9: cmp red red + + Differences + None ... + +Bytes compared: 0000002D +Bytes different: 00000000 +</screen> +</refsect1> +</refentry> + +<refentry id="cobbler"> +<refnamediv> +<refname>COBBLER</refname> +<refpurpose>Make a bootstrap file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>COBBLER</command> +<arg choice="plain"> + &replstart;device name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +COBBLER is used to create the "OS9Boot" file required on any disk +from which OS-9 is to be bootstrapped. The boot file will consist +of the <emphasis>same modules which were loaded into memory during the most +recent boostrap.</emphasis> +To add modules to the bootstrap file use the +"OS9Gen" command. COBBLER also writes the OS-9 kernel on the first +fifteen sectors of track 34, and excludes these sectors from the +disk allocation map. If any files are present on these sectors +COBBLER will display an error message. +</para> +<para> +NOTE: The boot file must fit into one contiguous block on the mass-storage +device. For this reason COBBLER is normally used on a +freshly formatted disk. If COBBLER is used on a disk and there is +not a contiguous block of storage large enough to hold the boot +file, the old boot file may have been destroyed and OS-9 will not be +able to boot from that disk until it is reformatted. +</para> +<para> +For more information see: 1.1.2, 6.1 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: cobbler /D1 +</screen> +</refsect1> +</refentry> + +<refentry id="copy"> +<refnamediv> +<refname>COPY</refname> +<refpurpose>Copy data from one path to another</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>COPY</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="opt"> + <option>-s</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command copies data from the first file or device specified to +the second. The first file or device must already exist, the +second file is automatically created if the second path is a file on +a mass storage device. Data may be of any type and is NOT modified +in any way as it is copied. +</para> +<para> +Data is transferred using large block reads and writes until end-of-file +occurs on the input path. Because block transfers are used, +normal output processing of data does not occur on character-oriented +devices such as terminals, printers, etc. Therefore, the +LIST command is preferred over COPY when a file consisting of text +is to be sent to a terminal or printer. +</para> +<para> +The "-s" option causes COPY to perform a single drive copy +operation. The second pathlist must be a full pathlist if "-s +appears. COPY will read a portion of the source disk into memory, +you remove the source disk and place the destination disk into the +drive, enter a "C" whereupon COPY writes on the destination disk, +this process continues until the entire file is copied. +</para> +<para> +Using the shell's alternate memory size modifier to give a large +memory space will increase speed and reduce the number of media +exchanges required for single drive copies. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +copy file1 file2 #15k (copies file1 to file2) + +copy /D1/joe/news /D0/peter/messages + +copy /TERM /P (copies console to printer) + +copy /d0/cat /d0/animals/cat -s #32k +Ready DESTINATION, hit C to continue: c +Ready SOURCE, hit C to continue: c +Ready DESTINATION, hit C to continue:c +</screen> +</refsect1> +</refentry> + +<refentry id="date"> +<refnamediv> +<refname>DATE</refname> +<refpurpose>Display system date and time</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DATE</command> +<arg choice="opt"> + <option>t</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command will display the current system date, and if the "t" +option is given, the current system time. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +date t + +date t >/p (Output is redirected to printer) + +OS9: setime + + YY/MM/DD HH:MM:SS +TIME ? 81/04/15 14:19:00 + +OS9:date + +April 15, 1981 + +OS9:date t + +April 15, 1981 14:20:20 +</screen> +</refsect1> +</refentry> + +<refentry id="dcheck"> +<refnamediv> +<refname>DCHECK</refname> +<refpurpose>Check Disk File Structure</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DCHECK</command> +<arg choice="opt"> + <option>-opts</option> +</arg> +<arg choice="plain"> + &replstart;devnam&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +It is possible for sectors on a disk to be marked as being allocated +but in fact are not actually associated with a file or the disk's +free space. This can happen if a disk is removed from a drive while +files are still open, or if a directory which still contains files +is deleted (see 3.5). DCHECK is a diagnostic that can be used to +detect this condition, as well as the general integrity of the directory/file linkages. +</para> +<para> +DCHECK is given as a parameter the name of the disk device to be +checked. After verifying and printing some vital file structure +parameters, DCHECK follows pointers down the disk's file system tree +to all directories and files on the disk. As it does so, it +verifies the integrity of the file descriptor sectors, reports any +discrepancies in the directory/file linkages, and builds a sector +allocation map from the segment list associated with each file. If +any file descriptor sectors (FDs) describe a segment with a cluster +not within the file structure of the disk, a message is reported +like: +</para> +<screen> +*** Bad FD segment ($xxxxxx-$yyyyyy) for file: &replstart;pathlist&replend; +</screen> +<para> +This indicates that a segment starting at sector xxxxxx and ending +at sector yyyyyy cannot really be on this disk. Because there is a +good chance the entire FD is bad if any of it's segment descriptors +are bad, the allocation map is <emphasis>not</emphasis> updated for corrupt FDs. +</para> +<para> +While building the allocation map, DCHECK also makes sure that each +disk cluster appears only once and only once in the file structure. +If this condition is detected, DCHECK will display a message like: +</para> +<screen> +Cluster $xxxxxx was previously allocated +</screen> +<para> +This message indicates that cluster xxxxxx has been found at least +once before in the file structure. The message may be printed more +than once if a cluster appears in a segment in more than one file. +</para> +<para> +The newly created allocation map is then compared to the allocation +map stored on the disk, and any differences are reported in messages +like: +</para> +<screen> +Cluster $xxxxxx in allocation map but not in file structure +Cluster $xxxxxx in file structure but not in allocation map +</screen> +<para> +The first message indicates sector number xxxxxx (hexadecimal) was +found not to be part of the file system, but was marked as allocated +in the disk's allocation map. In addition to the causes mentioned +in the first paragraph, some sectors may have been excluded from the +allocation map by the FORMAT program because they were defective or +they may be the last few sectors of the disk, the sum of which was +two small to comprise a cluster. +</para> +<para> +The second message indicates that the cluster starting at sector +xxxxxx is part of the file structure but is <emphasis>not</emphasis> +marked as allocated +in the disk's allocation map. It is possible that this cluster may +be allocated to another file later, overwriting the contents of the +cluster with data from the newly allocated file. Any clusters that +have been reported as "previously allocated" by DCHECK as described +above surely have this problem. +</para> +<para> +Available DCHECK options are: +</para> + +<informaltable frame="none"> +<tgroup cols="2"> +<colspec colwidth="1.3in"> +<colspec colwidth="3in"> +<tbody> +<row> +<entry>-w=&replstart;path&replend;</entry> +<entry>pathlist to directory for work files</entry> +</row> +<row> +<entry>-p</entry> +<entry>print pathlists for questionable clusters</entry> +</row> +<row> +<entry>-m</entry> +<entry>save allocation map work files</entry> +</row> +<row> +<entry>-b</entry> +<entry>suppress listing of unused clusters</entry> +</row> +<row> +<entry>-s</entry> +<entry>display count of files and directories only</entry> +</row> +<row> +<entry>-o</entry> +<entry>print DCHECK's valid options</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The "-s" option causes DCHECK to display a count of files and +directories only; only FDs are checked for validity. The "-b" option +suppresses listing of clusters allocated but not in file structure. +The "-p" option causes DCHECK to make a second pass through the file +structure printing the pathlists for any clusters that DCHECK finds +as "already allocated" or "in file structure but not in allocation +map". The "-w=" option tells DCHECK where to locate it's allocation +map work file(s). The pathlist specified must be a FULL pathlist to +a <emphasis>directory</emphasis>. The directory "/D0" is +used is used if "-w" is not +specified. It is recommended that this pathlist NOT be located on +the disk being DCHECKed if the disk's file structure integrity is in +doubt. +</para> +<para> +DCHECK builds its disk allocation map in a file called +&replstart;pathlist&replend;/DCHECKppO, where &replstart;pathlist&replend; +is as specified by the +"-w=" option and pp is the process number in hexadecimal. Each bit +in this bitmap file corresponds to a cluster of sectors on the disk. +If the "-p" option appears on the command line, DCHECK creates a +second bitmap file (&replstart;pathlist&replend;/DCHECKpp1) that has a bit set for +each cluster DCHECK finds as "previously allocated" or "in file +structure but not in allocation map" while building the allocation +map. DCHECK them makes another pass through the directory structure +to determine the pathlists for these questionable clusters. These +bitmap work files may be saved by specifying the "-m" option on the +command line. +</para> +</refsect1> +<refsect1><title>Restrictions</title> +<para> +For best results, DCHECK should have exclusive access to the disk +being checked. Otherwise DCHECK may be fooled if the disk allocation map +changes while it is building its bitmap file from the +changing file structure. DCHECK cannot process disks with a directory +depth greater than 39 levels. +</para> +<para> +For more information see: 3.10, 3.5, FORMAT, + 6.1 of OS-9 Systems Programmer's Manual +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: dcheck /d2 (workfile is on /D0) + +Volume - 'My system disk' on device /d2 +$009A bytes in allocation map +1 sector per cluster +$0004D0 total sectors on media +Sector $000002 is start of root directory FD +$0010 sectors used for id, allocation map and root directory +Building allocation map work file... +Checking allocation map file... + + +'My system disk' file structure is intact +1 directory +2 files + +OS9: dcheck -mpw=/d2 /d0 +Volume - 'System disk' on device /d0 +$0046 bytes in allocation map +1 sector per cluster +$00022A total sectors on media +Sector $000002 is start of root directory FD +$0010 sectors used for id, allocation map and root directory +Building allocation map work file... +Cluster $00040 was previously allocated +*** Bad FD segment ($111111-$23A6F0) for file: /d0/test/junky.file +Checking allocation map file... +Cluster $000038 in file structure but not in allocation map +Cluster $00003B in file structure but not in allocation map +Cluster $0001B9 in allocation map but not in file structure +Cluster $0001BB in allocation map but not in file structure + +Pathlists for questionable clusters: +Cluster $000038 in path: /d0/OS9boot +Cluster $00003B in path: /d0/OS9boot +Cluster $000040 in path: /d0/OS9boot +Cluster $000040 in path: /d0/test/double.file + +1 previously allocated clusters found +2 clusters in file structure but not in allocation map +2 clusters in allocation map but not in file structure +1 bad file descriptor sector + +'System disk' file structure is not intact +5 directories +25 files +</screen> +</refsect1> +</refentry> + +<refentry id="del"> +<refnamediv> +<refname>DEL</refname> +<refpurpose>Delete a file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DEL</command> +<arg choice="opt"> + <option>-x</option> +</arg> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &repeatst;&replstart;path&replend;&repeaten; +</arg> +<arg choice="opt"> + <option>-x</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to delete the file(s) specified by the +pathllst(s). The user must have write permission for the file(s). +Directory files cannot be deleted unless their type is changed to +non-directory: see the "ATTR" command description. +</para> +<para> +If the -x option appears, the current +<emphasis>execution</emphasis> directory is assumed. +</para> +<para> +For more information see: 3.5, 3.8.1 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +del test_program old_test_program + +del /D1/number_five + +OS9:dir /D1 + + Directory of /D1 14:29:46 +myfile newfile + +OS9:del /D1/newfile +OS9:dir /D1 + + Directory of /D1 14:30:37 +myfile + +OS9:del myprog -x +OS9:del -x CMDS.SUBDIR/file +</screen> +</refsect1> +</refentry> + +<refentry id="deldir"> +<refnamediv> +<refname>DELDIR</refname> +<refpurpose>Delete All Files In a Directory System</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DELDIR</command> +<arg choice="plain"> + &replstart;directory name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is a convenient alternative to manually deleting +directories and files they contain. It is only used when +<emphasis>all</emphasis> files in the directory system are to be deleted. +</para> +<para> +When DELDIR is run, it prints a prompt message like this: +</para> +<screen> +OS9: deldir OLDFILES +Deleting directory file. +List directory, delete directory, or quit ? (l/d/q) +</screen> +<para> +An "l" response will cause a "dir e" command to be run so you can +have an opportunity to see the files in the directory before they +are deleted. +</para> +<para> +A "d" response will initiate the process of deleting files. +</para> +<para> +A "q" response will abort the command before action is taken. +</para> +<para> +The directory to be deleted may include directory files, which +may themselves include directory files, etc. In this case, DELDIR +operates recursively (e.g., it calls itself) so all lower-level +directories are deleted as well. In this case the lower-level +directories are processed first. +</para> +<para> +You must have correct access permission to delete all files and +directories encountered. If not, DELDIR will abort upon +encountering the first file for which you do not have write +permission. +</para> +<para> +The DELDIR command automatically calls the DIR and ATTR +commands, so they both must reside in the current execution +directory. +</para> +</refsect1> +</refentry> + +<refentry id="dir"> +<refnamediv> +<refname>DIR</refname> +<refpurpose>Display the names of files contained in a directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DIR</command> +<arg choice="opt"> + <option>e</option> +</arg> +<arg choice="opt"> + <option>x</option> +</arg> +<arg choice="opt"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays a formatted list of files names in a directory file on. the +standard output path. If no parameters are given, the current +<emphasis>data</emphasis> +directory is shown. If the "x" option is given, the current +<emphasis>execution</emphasis> +directory is shown. If a pathlist of a directory file is +given, it is shown. + +</para> +<para> +If the "e" option is included, each file's entire description is +displayed: size, address, owner, permissions, date and time of last +modification. + +</para> +<para> +For more information see: 1.0.3, 3.4, and 3.8.1 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +dir (display data directory) + +dir x (display execution directory) + +dir x e (display entire description of execution dir) + +dir .. (display parent of working data directory) + +dir newstuff (display newstuff directory) + +dir e test_programs (display entire description of "test.programs) +</screen> +</refsect1> +</refentry> + +<refentry id="display"> +<refnamediv> +<refname>DISPLAY</refname> +<refpurpose>Display Converted Characters</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DISPLAY</command> +<arg choice="plain"> + &replstart;hex&replend; +</arg> +<arg choice="plain"> + &repeatst;&replstart;hex&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Display reads one or more hexadecimal numbers given as parameters, +converts them to ASCII characters, and writes them to the standard +output. It is commonly used to send special characters (such as +cursor and screen control codes) to terminals and other I/O devices. + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +display 0C 1F 02 7F + + +display 15 >/p (sends "form feed" to printer) + +OS9: display 41 42 43 44 45 46 +ABCDEF +</screen> +</refsect1> +</refentry> + +<refentry id="dsave"> +<refnamediv> +<refname>DSAVE</refname> +<refpurpose>Generate procedure file to copy files</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DSAVE</command> +<arg choice="opt"> + <option>-opts</option> +</arg> +<arg choice="opt"> + &replstart;devname&replend; +</arg> +<arg choice="opt"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Dsave is used to backup or copy all files in one or more +directories. It is unlike most other commands in that it does NOT +directly affect the system, rather, it generates a procedure file +which is executed later to actually do the work. +</para> +<para> +When DSAVE is executed, it writes copy commands to +<emphasis>standard output</emphasis> +to copy files from the current <emphasis>data</emphasis> directory +on &replstart;devname&replend; (the default is /D0) to the directory +specified by &replstart;path&replend;. If &replstart;path&replend; +does not appear, the copy is performed to the current data directory +<emphasis>at the time the DSAVE procedure file is executed.</emphasis> +If DSAVE +encounters a directory file, it will automatically include "makdir" +and "chd" commands in the output before generating copy commands for +files in the subdirectory. Since DSAVE is recursive in operation, +the procedure file will exactly replicate all levels of the file +system from the current data directory downward (such a section of +the file system is called a "subtree"). +</para> +<para> +If the current working directory happens to be the root directory of +the disk, DSAVE will create a procedure file that will backup the +entire disk file by file. This is useful when it is necessary to +copy many files from different format disks, or from floppy disk to +a hard disk. +</para> +<para> +Available DSAVE options are: +</para> + +<informaltable frame="none"> +<tgroup cols="2"> +<colspec colwidth="1in"> +<colspec colwidth="4in"> +<tbody> +<row> +<entry>-b</entry> +<entry>make output disk a system disk by using source disk's +"OS9Boot" file,. if present.</entry> +</row> +<row> +<entry>-b=&replstart;path&replend;</entry> +<entry>make output disk a system disk using &replstart;path&replend; as source +for the "OS9Boot" file.</entry> +</row> +<row> +<entry>-i</entry> +<entry>indent for directory levels</entry> +</row> +<row> +<entry>-L</entry> +<entry>do not process directories below the current level</entry> +</row> +<row> +<entry>-m</entry> +<entry>do not include "makdir" commands in procedure file</entry> +</row> +<row> +<entry>-s&replstart;integer&replend;</entry> +<entry>set copy size parameter to &replstart;integer&replend; K</entry> +</row> +</tbody> +</tgroup> +</informaltable> + + +<para> +For more information see: 1.1.3 +</para> +</refsect1> +<refsect1><title>Examples</title> +<para> +Example which copies all files on "d2" to "d1": +</para> +<screen> +chd /d2 (select "from" directory) +dsave /d2 >/d0/makecopy (make procedure file "makecopy") +chd /d1 (select "to" directory) +/d0/makcopy (run procedure file) + +chd /d0/MYFILES/STUFF +dsave -is32 /d0 /d1/BACKUP/STUFF >saver +/d0/MYFILES/STUFF/saver +</screen> +</refsect1> +</refentry> + +<refentry id="dump"> +<refnamediv> +<refname>DUMP</refname> +<refpurpose>Formatted File Data Dump in Hexadecimal and ASCII</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DUMP</command> +<arg choice="opt"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command produces a formatted display of the physical data +contents of the path specified which may be a mass storage file or +any other I/O device. If a pathlist is omitted, the standard input +path is used. The output is written to standard output. This command is +commonly used to examine the contents of non-text files. +</para> +<para> +The data is displayed 16 bytes per line in both hexadecimal and +ASCII character format. Data bytes that have non-displayable values +are represented by periods in the character area. +</para> +<para> +The addresses displayed on the dump are relative to the beginning of +the file. Because memory modules are position-independent and stored +on files exactly as they exist in memory, the addresses shown on the +dump correspond to the relative load addresses of memory-module +files. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +DUMP (display keyboard input in hex) +DUMP myfile >/P (dump myfile to printer) +DUMP shortfile +</screen> +</refsect1> + +<refsect1><title>Sample Output</title> +<screen> + Addr 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 2 4 6 8 A C E + ---- ---- ---- ---- ---- ---- ---- ---- ---- ---------------- + 0000 87CD 0038 002A P181 2800 2E00 3103 FFE0 .M.8.*q.(...1..' + 0010 0418 0000 0100 0101 0001 1808 180D 1B04 ................ + 0020 0117 0311 0807 1500 002A 5445 S2CD 5343 .........*TERMSC + 0030 C641 4349 C10E 529E FACIA.R. + + ^ ^ ^ + +starting data bytes in hexadecimal data bytes in +address format ASCII format +</screen> +</refsect1> +</refentry> + +<refentry id="echo"> +<refnamediv> +<refname>ECHO</refname> +<refpurpose>Echo text to output path</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>ECHO</command> +<arg choice="plain"> + &replstart;text&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command echoes its argument to the standard output path. It is +typically used to generate messages in shell procedure files or to +send an initialization character sequence to a terminal. The text +should not include any of the punctuation characters used by the +shell. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +echo >/T2 Hello John how's it going & (echo to T2) + +echo >/term ** warning ** disk about to be scratched 1 + +echo >/p Listing of Transaction File; list trans >/p + + +OS9: echo Here is an important message! +Here is an important message! +</screen> +</refsect1> +</refentry> + +<refentry id="ex"> +<refnamediv> +<refname>EX</refname> +<refpurpose>Execute program as overlay</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>EX</command> +<arg choice="plain"> + &replstart;module name&replend; +</arg> +<arg choice="opt"> + &replstart;modifiers&replend; +</arg> +<arg choice="opt"> + &replstart;parameters&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This a shell built-in command that causes the process executing the +shell to start execution of another program. It permits a transition +from the shell to another program without creating another process, +thus conserving system memory. +</para> +<para> +This command is often used when the shell is called from another +program to execute a specific program, after which the shell is not +needed. For instance, applications which only use BASIC09 need not +waste memory space on SHELL. +</para> +<para> +The "ex" command should always be the last command on a shell input +line because any command line following will never be processed. +</para> +<para> +NOTE: Since this is a built-in SHELL command, it does not appear in +the CMDS directory. +</para> +<para> +For more information see: 4.5, 4.6, 4.9 + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +ex BASIC09 + +tsmon /t1&; tsmon /t2&; ex tsmon /term +</screen> +</refsect1> +</refentry> + +<refentry id="format"> +<refnamediv> +<refname>FORMAT</refname> +<refpurpose>Initialize disk media</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>FORMAT</command> +<arg choice="plain"> + &replstart;devname&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to physically initialize, verify, and establish +an initial file structure on a disk. All disks must be formatted +before they can be used on an OS-9 system. +</para> +<para> +NOTE: If the diskette is to be used as a system disk, "OS9gen" or +"cobbler" must be run to create the bootstrap after the disk has +been formatted. +</para> +<para> + +The formatting process works as follows: +</para> + +<orderedlist numeration="arabic"> +<listitem> +<para> +The disk surface is physically initialized and sectored. +</para> +</listitem> +<listitem> +<para> +Each sector is read back and verified. If the sector fails to +verify after several attempts, the offending sector is excluded from +the initial free space on the disk. As the verification is +performed, track numbers are displayed on the standard output +device. +</para> +</listitem> +<listitem> +<para> +The disk allocation map, root directory, and identification sector are written +to the first few sectors of track zero. These +sectors <emphasis>cannot</emphasis> be defective. +</para> +</listitem> +</orderedlist> +<para> +FORMAT will prompt for a disk volume name, which can be up to 32 +characters long and may include spaces or punctuation. This name +can later be displayed using the FREE command. +</para> +<para> +For more information see: 3.10 +</para> +</refsect1> +</refentry> + +<refentry id="free"> +<refnamediv> +<refname>FREE</refname> +<refpurpose>Display free space remaining on mass-storage device</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>FREE</command> +<arg choice="plain"> + &replstart;devname&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command displays the number of unused 256-byte sectors on a +device which are available for new files or for expanding existing +files. The device name given must be that of a mass-storage +multifile device. "Free" also displays the disk's name, creation +date, and cluster size. +</para> +<para> +Data sectors are allocated in groups called "clusters". The number +of sectors per cluster depends on the storage capacity and physical +characteristics of the specific device. This means that small +amounts of free space may not be divisible into as many files. For +example, if a given disk system uses 8 sectors per cluster, and a +"free" command shows 32 sectors free, a maximum of four new files +could be created even if each has only one cluster. +</para> +<para> +For more information see: 3.10 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: free +BACKUP DATA DISK created on: 80/06/12 +Capacity: 1,232 sectors (1-sector clusters) +1,020 free sectors, largest block 935 sectors + +OS9: free /D1 +OS-9 Documentation Disk created on: 81/04/13 +Capacity: 1,232 sectors (1-sector clusters) +568 Free sectors, largest block 440 sectors +</screen> +</refsect1> +</refentry> + +<refentry id="ident"> +<refnamediv> +<refname>IDENT</refname> +<refpurpose>Print OS-9 module identification</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>IDENT</command> +<arg choice="opt"> + <option>-opts</option> +</arg> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="opt"> + <option>-opts</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to display header information from OS-9 memory +modules. IDENT displays the module size, CRC bytes (with verification), and for +program and device driver modules, the execution +offset and the permanent storage requirement bytes. IDENT will +print and interpret the type/language and attribute/revision bytes. +In addition, IDENT displays the byte immediately following the +module name since most Microware-supplied modules set this byte to +indicate the module edition. +</para> +<para> +IDENT will display all modules contained in a disk file. If the +"-m" option appears, &replstart;path&replend; is assumed to be a module in memory. +</para> +<para> +If the "-v" option is specified, the module CRC is not verified. +</para> +<para> +The "-x" option implies the pathlist begins in the execution +directory. +</para> +<para> +The "-s" option causes IDENT to display the. following module +information on a single line: +</para> +<simplelist> +<member> +Edition byte (first byte after module name) +</member> +<member> +Type/Language byte +</member> +<member> +Module CRC +</member> +<member> +A "." if the CRC verifies correctly, "?" if incorrect. +(IDENT will leave this field blank if the "-v" option appears.) +</member> +<member> +Module name +</member> +</simplelist> +</refsect1> + +<refsect1><title>Examples</title> +<screen> +OS9: ident -m ident +Header for: Ident <Module name> +Module size: $06A5 #1701 <Module size> +Module CRC: $1CE78A (Good) <Good or Bad> +Hdr parity: $8B <Header parity> +Exec. off: $0222 #546 <Execution offset> +Data size: $0CA1 #3233 <Permanent storage requirement> +Edition: $05 #5 <First byte after module name> +Ty/La At/Rv: $11 $81 <Type/Language Attribute/Revision> +Prog mod, 6809 obj, re-en <Module type, Language, Attribute> +</screen> +<screen> +OS9: ident /d0/os9boot -s + 1 $C0 $A366DC . OS9p2 + 83 $C0 $7FC336 . Init + 1 $11 $39BA94 . SysGo + 1 $C1 $402573 . IOMan + 3 $D1 $EE937A . REF + 82 $F1 $526268 . D0 + 82 $F1 $D65245 . D1 + 82 $F1 $E32FFE . D2 + 1 $D1 $F944D7 . SCF + 2 $E1 $F9FE37 . ACIA + 83 $F1 $765270 . TERM + 83 $F1 $B4396C . T1 + 83 $F1 $63B73B . T2 + 83 $F1 $0F9B78 . T3 + 83 $F1 $F83EB9 . T4 + 83 $F1 $D6DD9A . T5 + 3 $E1 $3EE015 . PIA + 83 $F1 $12A43B . P + 2 $D1 $BBC1EE . PipeMan + 2 $E1 $5B2B56 . Piper + 80 $F1 $CC06AF . Pipe + 2 $C1 $248B2C . Clock + ^ ^ ^ ^ ^ + | | | | | + | | | | Module name + | | | CRC check " " if -v, "." if OK, "?" if bad + | | CRC value + | Type/Language byte + Edition byte (first byte after name) +</screen> +</refsect1> +</refentry> + +<refentry id="kill"> +<refnamediv> +<refname>KILL</refname> +<refpurpose>Abort a process</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>KILL</command> +<arg choice="plain"> + &replstart;procID&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This shell "built in" command sends an "abort" signal to the +process having the process ID number specified. The process to be +aborted must have the same user ID as the user that executed the +command. The "procs" command can be used to obtain the process ID +numbers. +</para> +<para> +NOTE: If a process is waiting for I/O, it may not die until it +completes the current I/O operation, therefore, if you KILL a +process and the PROCS command shows it still exists, it is probably +waiting for receive a line of data from a terminal before it can +die. + +Since this is a built-in SHELL command, it does not appear in the +CMDS directory. + +For more information see: 4.5, 5.2, PROCS + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +kill 5 + +kill 22 + +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 20 2 0 active 2 Shell <TERM + 20 1 0 waiting 1 Sysgo <TERM + 20 3 0 sleeping 20 Copy <TERM + +OS9: kill 3 +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 20 2 0 active 2 Shell <TERM + 20 1 0 waiting 1 Sysgo <TERM + +OS9: +</screen> +</refsect1> +</refentry> + +<refentry id="link"> +<refnamediv> +<refname>LINK</refname> +<refpurpose>Link module into memory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LINK</command> +<arg choice="plain"> + &replstart;memory module name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to "lock" a previously loaded module into +memory. The link count of the module specified is incremented by one +each time it is "linked". The "unlink" command is +used to "unlock" +the module when it is no longer needed. +</para> +<para> +For more information see: 5.4, 5.4.1, 5.4.2, 5.4.3 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9: LINK edit + +OS9: LINK myprogram +</screen> +</refsect1> +</refentry> + +<refentry id="list"> +<refnamediv> +<refname>LIST</refname> +<refpurpose>List the contents of a text file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LIST</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &repeatst; &replstart;path&replend; &repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command copies text lines from the path(s) given as parameters +to the standard output path. The program terminates upon reaching +the end-of-file of the last input path. If more than one path is +specified, the first path will be copied to standard output, the +second path will be copied next, etc. +</para> +<para> +This command is most commonly used to examine or print text files. +</para> +<para> +For more information see: 2.3, 3.9.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +list /d0/startup >/P & (output is redirected to printer) + +list /D1/user5/document /d0/myfile /d0/Bob/text + +list /TERM >/p (copy keyboard to printer - use + "escape" key to terminate input) +</literallayout> +<screen> + +OS9: build animals +? cat +? cow +? dog +? elephant +? bird +? fish +? [RETURN] + +OS9: list animals +cat +cow +dog +elephant +bird +fish +</screen> +</refsect1> +</refentry> + +<refentry id="load"> +<refnamediv> +<refname>LOAD</refname> +<refpurpose>Load module(s) from file into memory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LOAD</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +The path specified is opened and one or more modules is read from it +and loaded into memory. The names of the modules are added to the +module directory. If a module is loaded that has the same name and +type as a module already in memory, the module having the highest +revision level is kept. +</para> +<para> +For more information see: 3.9.4, 5.4.1, 5.4.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> + load new_program +</literallayout> + +<screen> + +OS9:mdir + + Module Directory at 13:36:47 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN REF +SCF ACIA TERM T1 T2 +T3 P PIA CDS H1 +Sysgo Clock Shell Tsmon Copy +Mdir + +OS9:load edit +OS9:mdir + + Module Directory at 13:37:14 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN REF +SCF ACIA TERM T1 T2 +T3 P PIA CDS H1 +Sysgo Clock Shell Tsmon Copy +Mdir EDIT +</screen> +</refsect1> +</refentry> + +<refentry id="login"> +<refnamediv> +<refname>LOGIN</refname> +<refpurpose>Timesharing System Log-In</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LOGIN</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Login is used in timesharing systems to provide log-in security. It +is automatically called by the timesharing monitor "tsmon", or can +be used after initial log-in to change a terminal's user. +</para> +<para> +Login requests a user name and password, which is checked against a +validation file. If the information is correct, the user's system +priority, user ID, and working directories are set up according to +information stored in the file, and the initial program specified in +the password file is executed (usually SHELL). If the user cannot +supply a correct user name and password after three attempts, the +process is aborted. The validation file is called "PASSWORD" and +must be present in the directory "/d0/SYS". The file contains one or +more variable-length text records, one for each user name. Each +record has the following fields, which are delimited by commas: +</para> +<para> +1. User name (up to 32 characters, may include spaces). If this +field is empty, any name will match. +</para> +<para> +2. Password (up to 32 characters, may include spaces) If this field +is omitted, no password is required by the specific use. +</para> +<para> +3. User index (ID) number (from 0 to 65535, 0 is superuser). +This number is used by the file security system and as the system-wide +user ID to identify all processes initiated by the user. The +system manager should assign a unique ID to each potential user. +(See 3.8) +</para> +<para> +4. Initial process (CPU time) priority: 1 - 255 (see 5.2) +</para> +<para> +5. Pathlist of initial execution directory (usually /d0/CMDS) +</para> +<para> +6. Pathlist of initial data directory (specific user's directory) +</para> +<para> +7. Name of initial program to execute (usually "shell"). +NOTE: This is not a shell command line. +</para> +<para> +Here's a sample validation file: +</para> + +<screen> +superuser,secret,0,255,.,.,shell +steve,open sesame,3,128,.,/d1/STEVE,shell +sally,qwerty,10,100,/d0/BUSINESS,/d1/LETTERS,wordprocessor +bob,,4,128,.,/d1/BOB,Basic09 +</screen> + +<para> +To use the login command, enter: +</para> +<literallayout> +login +</literallayout> +<para> +This will cause prompts for the user's name and (optionally) +password to be displayed, and if answered correctly, the user is +logged into the system. Login initializes the user number, working +execution directory, working data directory, and executes the +initial program specified by the password file. The date, time and +process number (which is <emphasis>not</emphasis> the same as +the user ID, see 5.3) are also displayed. +</para> +<para> +Note: if the shell from which "login" was called will not be needed +again, it may be discarded by using the EX command to start the +LOGIN command. For example: +</para> +<literallayout> +ex login +</literallayout> +<refsect2> +<title>Logging Off the System</title> +<para> +To log off the system, the initial program specified in the password +file must be terminated. For most programs (including shell) this +may be done by typing an end of file character (escape) as the first +character on a line. +</para> +</refsect2> +<refsect2> +<title>Displaying a "Message-of-the-Day"</title> +<para> +If desired, a file named "motd" appearing in the SYS directory will +cause LOGIN to display it's contents on the user's terminal after +successful login. This file is not required for LOGIN to operate. +</para> +<para> +For more information see: tsmon, 2.5, 3.8, 5.3 +</para> +</refsect2> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: login + +OS-9 Level 1 Timesharing System Version 1.2 82/12/04 13:02:22 + +User name?: superuser +Password: secret + +Process #07 logged 81/12/04 13:03:00 + +Welcome! +</screen> +</refsect1> +</refentry> + +<refentry id="makdir"> +<refnamediv> +<refname>MAKDIR</refname> +<refpurpose>Create directory file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MAKDIR</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Creates a new directory file acdording to the pathlist given. The +pathlist must refer to a parent directory for which the user has +write permission. +</para> +<para> +The new directory is initialized and initially does not contain +files except for the "." and ".." pointers to its parent directory +and itself, respectively (see 3.7.3). All access permissions are +enabled (except sharable). +</para> +<para> +It is customary (but not mandatory) to capitalize directory names. +</para> +<para> +For more information see: 3.3, 3.4, 3.5,3.7.3, 3.9.5 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +makdir /d1/STEVE/PROJECT + +makdir DATAFILES + +makdir ../SAVEFILES +</literallayout> +</refsect1> +</refentry> + +<refentry id="mdir"> +<refnamediv> +<refname>MDIR</refname> +<refpurpose>Display Module Directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MDIR</command> +<arg choice="opt"> + <option>e</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays the present module names in the system module directory, +i.e., all modules currently resident in memory. For example: +</para> +<screen> +OS9: mdir + + Module Directory at 14:44:35 +D0 Pipe OS9 OS9P2 +Init Boot DDisk D1 +KBVDIO TERM IOMan RBF +SCF SysGo Clock Shell +PRINTER P PipeMan Piper +Mdir +</screen> +<para> +If the "e" option is given, a full listing of the physical address, +size, type, revision level, reentant attribute, user count, and name +of each module is displayed. All numbers shown are in hexadecimal. +</para> +<screen> +OS9: MDIR E + +Module Directory at 10:55:04 + +ADDR SIZE TY RV AT UC NAME +---- ---- -- -- -- -- -------- +C305 2F F1 1 R D0 +F059 7EB C1 1 R OS9 +F852 4F4 C1 1 R OS9P2 +FD46 2E CO 1 R INIT +C363 798 E1 1 R 2 KBVDIO +CAFB 38 F1 1 R 2 TERM +</screen> +<para> + +WARNING: Many of the modules listed by MDIR are OS-9 system modules +and NOT executable as programs: always check the module type code +before running a module if you are not familiar with it! +</para> +<para> +For more information see: 5.4.1 +</para> +</refsect1> +</refentry> + +<refentry id="merge"> +<refnamediv> +<refname>MERGE</refname> +<refpurpose>Copy and Combine Files to Standard Output</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MERGE</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &repeatst; &replstart;path&replend; &repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command copies multiple input files specified by the pathlists +given as parameters to the standard output path. it is commonly +used to combine several files into a single output file. Data is +copied in the order the pathlists are given. MERGE does no output +line editing (such as automatic line feed). The standard output is +generally redirected to a file or device. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: merge file1 file2 file3 file4 >combined.file + +OS9: merge compile.list asm.list >/printer +</screen> +</refsect1> +</refentry> + +<refentry id="mfree"> +<refnamediv> +<refname>MFREE</refname> +<refpurpose>Display Free System RAM</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MFREE</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays a list of which areas of memory are not presently in use +and available for assignment. The address and size of each free +memory block are displayed. The size is given as the number of 256-byte +pages. This information is useful to detect and correct memory +fragmentation (see 5.4.3). +</para> +<para> +For more information see: 5.4, 5.4.3 + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: mfree + + Address pages +--------- ----- + 700- 7FF 1 + B00-AEFF 164 +B100-B1FF 1 + +Total pages free = 166 +</screen> +</refsect1> +</refentry> + +<refentry id="os9gen"> +<refnamediv> +<refname>OS9GEN</refname> +<refpurpose>Build and Link a Bootstrap File</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>OS9GEN</command> +<arg choice="plain"> + &replstart;device name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +OS9Gen is used to create and link the "OS9Boot" file required on any +disk from which OS-9 is to be bootstrapped. OS9Gen is used to add +modules to an existing boot or to create an entirely new boot file. +If an exact copy of the existing OS9Boot file is desired, the +COBBLER command should be used instead. +</para> +<para> +The name of the device on which the "OS9Boot" file is to be +installed is passed to OS9Gen as a command line parameter. OS9Gen then +creates a working file called "TempBoot" on the device specified. +Next it reads file names (pathlists) from its standard input, one +pathlist per line. Every file named is opened and copied to +"TempBoot". This is repeated until end-of-file or a blank line is +reached on OS9Gen's standard input. All boot files must contain the +OS-9 component modules listed in section 6.1. +</para> +<para> +After all input files have been copied to "TempBoot", the old +"OS9Boot" file, if present, is deleted. "TempBoot" is then renamed +to "OS9Boot", and its starting address and size is linked in the +disk's Identification Sector (LSN 0) for use by the OS-9 bootstrap +firmware. +</para> +<para> +WARNING: Any "OS9Boot" file must be stored in physically contiguous +sectors. Therefore, OS9Gen is normally used on a freshly formatted +disk. If the "OS9Boot" file is fragmented, OS9Gen will print a +warning message indicated the disk cannot be used to bootstrap OS-9. +</para> +<para> +The list of file names given to OS9Gen can be entered from a keyboard, or +OS9Gen's standard input may be redirected to a text file +containing a list of file names (pathlists) . If names are entered +manually, no prompts are given, and the end-of-file key (usually +ESCAPE) or a blank line is entered after the line containing the +last pathlist. +</para> +<para> +For more information see: 6.0, 6.1, 6.6 +</para> +</refsect1> +<refsect1><title>Examples</title> +<para> +To manually install a boot file on device "d1" which is an exact +copy of the "OS9Boot" file on device "d0": +</para> +<screen> +OS9: os9gen /d1 (run OS9Gen) +/d0/os9boot (enter file to be installed) +[ESCAPE] (enter end-of-file) +</screen> +<para> +To manually install a boot file on device "d1" which is a copy of +the "OS9Boot" file on device "do" with the addition of +modules stored in the files "/d0/tape.driver" and "/d2/video.driver": +</para> +<screen> +OS9: os9gen /d1 (run OS9Gen) +/d0/os9boot (enter main boot file name) +/d0/tape.driver (enter name of first file to be added) +/d2/video.driver (enter name of second file to be added) +[ESCAPE] (enter end-of-file) +</screen> +<para> +As above, but automatically by redirecting OS9Gen standard input: +</para> +<screen> +OS9: build /d0/bootlist (use "build" to create file "bootlist") +? /d0/os9boot (enter first file name) +? /d0/tape.driver (enter second file name) +? /d2/video.driver (enter third file name) +? [RETURN] (terminate "build") +OS9: os9gen /d1 </d0/bootlist (run OS9gen with redirected input) +</screen> +</refsect1> +</refentry> + +<refentry id="printerr"> +<refnamediv> +<refname>PRINTERR</refname> +<refpurpose>Print Full Text Error Messages</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PRINTERR</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command replaces the basic OS-9 error printing routine (F$PERR +service request) which only prints error code numbers, with a +routine the reads and displays textual error messages from the file +"/d0/SYS/errmsg". Printerr's effect is system-wide. +</para> +<para> +A standard error message file is supplied with OS-9. This file can +be edited or replaced by the system manager. The file is a normal +text file with variable length line. Each error message line begins +with the error number code (in ASCII characters), a delimiter, and +the error message text. The error messages need not be in any +particular order. Delimiters are spaces or any character numerically lower then +$20. Any line having a delimiter as its first +character is considered a contintjation of the previous line(s) which +permits multi-line error messages. +</para> +<para> +WARNING: Once the printerr command has been used, it can not be undone. Once +installed, the PRINTERR module should not be unlinked. +PRINTERR uses the current user's stack for an I/O buffer, so users +are encouraged to reserve reasonably large stacks. +</para> +<para> +For more information see: 4.7, 6.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9: printerr + +</screen> +</refsect1> +</refentry> + +<refentry id="procs"> +<refnamediv> +<refname>PROCS</refname> +<refpurpose>Display Processes</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PROCS</command> +<arg choice="opt"> + <option>e</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays a list of processes running on the system. Normally only +processes having the user's ID are listed, but if the "e" option is +given, processes of all users are listed. The display is a +"snapshot" taken at the instant the command is executed: processes +can switch states rapidly, usually many times per second. +</para> +<para> +PROCS shows the user and process ID numbers, priority, state +(process status), memory size (in 256 byte pages), primary program +module, and standard input path. +</para> +<para> +For more information see: 5.1, 5.2, 5.3 +</para> +</refsect1> +<refsect1><title>Examples</title> +<para> +Level One Example: +</para> +<screen> +User# Id pty state Mem Primary module +---- --- --- -------- --- -------------- + 0 2 0 active 2 Shell + 0 1 0 waiting 1 SysGo + 1 3 1 waiting 2 Tsmon + 1 4 1 waiting 4 Shell + 1 5 1 active 64 Basic09 +</screen> +</refsect1> +</refentry> + +<refentry id="pwd"> +<refnamediv> +<refname>PWD/PXD</refname> +<refpurpose>Print Working Directory / Print Execution Directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PWD</command> +</cmdsynopsis> +<cmdsynopsis> +<command>PXD</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +PWD displays a pathlist that shows the path from the root +directory to the user's current data directory. It can be used by +programs to discover the actual physical location of files, or by +humans who get lost in the file system. PXD is identical except +that is shows the pathlist of the user's current execution directory. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: chd /D1/STEVE/TEXTFILES/MANUALS +OS9: pwd +/D1/STEVE/TEXTFILES/MANUALS +OS9: chd .. +OS9: pwd +/D1/STEVE/TEXTFILES +OS9: chd .. +OS9: pwd +/D1/STEVE + +OS9: pxd +/D0/CMDS +</screen> +</refsect1> +</refentry> + +<refentry id="rename"> +<refnamediv> +<refname>RENAME</refname> +<refpurpose>Change file name</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>RENAME</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &replstart;new name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Gives the mass storage file specified in the pathlist a new name. +The user must have write permission for the file to change its name. +It is not possible to change the names of devices, ".", or +".." +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +rename blue purple + +rename /D3/user9/test temp +</literallayout> + +<screen> +OS9: dir + + Directory of . 16:22:53 +myfile animals + +OS9:rename animals cars +OS9:dir + + Directory of . 16:23:22 +myfile cars +</screen> +</refsect1> +</refentry> + +<refentry id="save"> +<refnamediv> +<refname>SAVE</refname> +<refpurpose>Save memory module(s) on a file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SAVE</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &replstart;modname&replend; +</arg> +<arg choice="plain"> + &repeatst;&replstart;modname&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Creates a new file and writes a copy of the memory module(s) +specified on to the file. The module name(s) must exist in the +module directory when saved. The new file is given access +permissions for all modes except public write. +</para> +<para> +Note: SAVE's default directory is the current data directory. +Executable modules should generally be saved in the default +execution directory. +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +save wordcount wcount + +save /d1/mathpack add sub mul div +</literallayout> +</refsect1> +</refentry> + +<refentry id="setime"> +<refnamediv> +<refname>SETIME</refname> +<refpurpose>Activate and set system clock</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SETIME</command> +<arg choice="opt">y,m,d,h,m,s</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command sets the system date and time, then activates the real +time clock. The date and time can be entered as parameters, or if no +parameters are given, SETIME will issue a prompt. Numbers are one +or two decimal digits using space, colon, semicolon or slash +delimiters. OS-9 system time uses the 24 hour clock, i.e., 1520 is +3:20 PM. +</para> +<para> +IMPORTANT NOTE: This command must be executed before OS-9 can +perform multitasking operations. If the system does not have a real +time clock this command should still be used to set the date for the +file system. +</para> +<para> +SYSTEMS WITH BATTERY BACKED UP CLOCKS: Setime should still be run to +start time-slicing, but only the <emphasis>year</emphasis> need be given, +the date and time will be read from the clock. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: setime 82,12,22,1545 (Set to: Dec. 12, 1981, 3:45 PM) + +OS9: setime 821222 154500 (Same as above) + +OS9: setime 82 (For system with battery-backup clock) +</screen> +</refsect1> +</refentry> + +<refentry id="setpr"> +<refnamediv> +<refname>SETPR</refname> +<refpurpose>Set Process Priority</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SETPR</command> +<arg choice="plain"> + &replstart;procID&replend; +</arg> +<arg choice="plain"> + &replstart;number&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command changes the CPU priority of a process. It may only be +used with a process having the user's ID. The process number is a +decimal number in the range of 1 (lowest) to 255. The "procs" +command can be used to obtain process ID numbers and present priority. +</para> +<para> +NOTE: This command does not appear in the CMDS directory as it is +built-in to the SHELL. +</para> +<para> +For more information see: 5.1, PROCS +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +setpr 8 250 (change process #8 priority to 250) +</literallayout> + +<screen> +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 0 3 0 waiting 2 Shell <TERM + 0 2 0 waiting 2 Shell <TERM + 0 1 0 waiting 1 Sysgo <TERM + + +OS9: setpr 3 128 +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 0 3 128 active 2 Shell <TERM + 0 2 0 waiting 2 Shell <TERM + 0 1 0 waiting 1 Sysgo <TERM +</screen> +</refsect1> +</refentry> + +<refentry id="sleep"> +<refnamediv> +<refname>SLEEP</refname> +<refpurpose>Suspend process for period of time</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SLEEP</command> +<arg choice="plain"> + &replstart;tick count&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command puts the user's process to "sleep" for a number of +clock ticks. It is generally used to generate time delays or to +"break up" CPU-intensive jobs. The duration of a tick is 16.66 +milliseconds. +</para> +<para> +A tick count of 1 causes the process to "give up" its current time +slide. A tick count of zero causes the process to sleep +indefinitely (usually awakened by a signal) + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: sleep 25 +</screen> +</refsect1> +</refentry> + +<refentry id="shell"> +<refnamediv> +<refname>SHELL</refname> +<refpurpose>OS-9 Command Interpreter</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SHELL</command> +<arg choice="plain">&replstart;arglist&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +The Shell is OS-9's command interpreter program. It reads data from +its standard input path (the keyboard or a file), and interprets the +data as a sequence of commands. - The basic function of the shell is +to initiate and control execution of other OS-9 programs. +</para> +<para> +The shell reads and interprets one text line at a time from the +standard input path. After interpretation of each line it reads +another until an end-of-file condition occurs, at which time it +terminates itself. A special case is when the shell is called from +another program, in which case it will take the parameter area (rest +of the command line) as its first line of input. If this command +line consists of "built in" commands only, more lines will be read +and processed; otherwise control will return to the calling program +after the single command line is processed. +</para> +<para> +The rest of this description is a technical specification of the +shell syntax. Use of the Shell is described fully in Chapters 2 +and 4 of this manual. +</para> +</refsect1> +<refsect1><title>Shell Input Line Formal Syntax</title> +<synopsis> +&replstart;pgm line&replend; := &replstart;pgm&replend; {&replstart;pgm&replend;} +&replstart;pgm&replend; := [&replstart;params&replend;] [ &replstart;name&replend; [&replstart;modif&replend;] [&replstart;pgm params&replend;] [&replstart;modif&replend;] ] [&replstart;sep&replend;] + +Program Specifications + +&replstart;name&replend; := &replstart;module name&replend; + := &replstart;pathlist&replend; + := ( &replstart;pgm list&replend; ) + +Parameters + +&replstart;params&replend;:= &replstart;param&replend; { &replstart;delim&replend; &replstart;param&replend; } +&replstart;delim&replend; := space or comma characters +&replstart;param&replend; := ex &replstart;name&replend; [&replstart;modif&replend;] chain to program specified + := chd &replstart;pathlist&replend; change working directory + := kill &replstart;procID&replend; send abort signal to process + := setpr&replstart;procID&replend; &replstart;pty&replend; change process priority + := chx &replstart;pathlist&replend; change execution directory + := w wait for any process to die + := p turn "OS9:" prompting on + := -p turn prompting off + := t echo input lines to std output + := -t don't echo input lines + := -x dont abort on error + := x abort on error + := * &replstart;text&replend; comment line: not processed +&replstart;sep&replend; := ; sequential execution separator + := & concurrent execution separator + := ! pipeline separator + := &replstart;cr&replend; end-of-line (sequential execution separator) + + +Modifiers + +&replstart;modif&replend; := &replstart;mod&replend; { &replstart;delim&replend; &replstart;mod&replend; } +&replstart;mod&replend; := < &replstart;pathlist&replend; redirect standard input + := > &replstart;pathlist&replend; redirect standard output + := >> &replstart;pathlist&replend; redirect standard error output + := # &replstart;integer&replend; set process memory size in pages + := # &replstart;integer&replend; K set program memory size in 1K increments +</synopsis> +</refsect1> +</refentry> + +<refentry id="tee"> +<refnamediv> +<refname>TEE</refname> +<refpurpose>Copy standard input to multiple output paths</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>TEE</command> +<arg choice="plain"> + &repeatst;&replstart;path&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> + +<para> + +TEE + +Copy standard input to multiple output paths + +Syntax: Tee {&replstart;path&replend;} + + + +This command is a filter (see 4.3.3) that copies all text lines from +its standard input path to the standard output path +<emphasis>and</emphasis> any number +of additional output paths whose pathlists are given as parameters. +</para> +<para> +The example below uses a pipeline and TEE to simultaneously send the +output listing of the "dir" command to the terminal, printer, and a +disk file: +</para> +<screen> +dir e ! tee /printer /d0/dir.listing +</screen> +<para> +The following example sends the output of an assembler listing to a +disk file and the printer: +</para> +<screen> +asm pgm.src l ! tee pgm.list >/printer +</screen> +<para> +The example below "broadcasts" a message to four terminals: +</para> +<screen> +echo WARNING System down in 10 minutes ! tee /t1 /t2 /t3 /t4 +</screen> +</refsect1> +</refentry> + +<refentry id="tmode"> +<refnamediv> +<refname>TMODE</refname> +<refpurpose>Change terminal operating mode</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>TMODE</command> +<arg choice="opt"> + .&replstart;pathnum&replend; +</arg> +<arg choice="opt"> + &replstart;arglist&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to display or change the operating parameters +of the user's terminal. +</para> +<para> +If no arguments are given, the present values for each parameter are +displayed, otherwise, the parameter(s) given in the argument list +are processed. Any number of parameters can be. given, and are +separated by spaces or commas. A period and a number can be used to +optionally specify the path number to be affected. If none is given, +the standard input path is affected. +</para> +<para> +NOTE: If this command is used in a shell procedure file, the +option ".&replstart;path num&replend;" must be used to specify one of the standard +output paths (0, 1 or 2) to change the terminal's operating +characteristics. The change will remain in effect until the path is +closed. To effect a permanent change to a device characteristic, +the device descriptor must be changed. +</para> +<para> +This command can work only if a path to the file/device has already +been opened. You may alter the device descriptor to set a device's +initial operating parameter (see the System Programmer's Manual). +</para> + +<informaltable frame="none"> +<tgroup cols="2"> +<colspec colwidth="1in"> +<colspec colwidth="4in"> +<tbody> +<row> +<entry>upc</entry> +<entry>Upper case only. Lower case characters are automatically +converted to upper case.</entry> +</row> +<row> +<entry>-upc</entry> +<entry>Upper case and lower case characters permitted (default).</entry> +</row> +<row> +<entry>bsb</entry> +<entry>Erase on backspace: backspace characters echoed as a +backspace-space-backspace sequence (default).</entry> +</row> +<row> +<entry>-bsb</entry> +<entry>no erase on backspace: echoes single backspace only</entry> +</row> +<row> +<entry>bsl</entry> +<entry>Backspace over line: lines are "deleted" by sending +backspace-space-backspace sequences to erase the same +line (for video terminals) (default).</entry> +</row> +<row> +<entry>-bsl</entry> +<entry>No backspace over line: lines are "deleted" by printing +a new line sequence (for hard-copy terminals). +echo Input characters "echoed" back to terminal (default)</entry> +</row> +<row> +<entry>-echo</entry> +<entry>No echo</entry> +</row> +<row> +<entry>lf</entry> +<entry>Auto line feed on: line feeds automatically echoed to +terminal on input and output carriage returns (default).</entry> +</row> +<row> +<entry>-lf</entry> +<entry>Auto line feed off.</entry> +</row> +<row> +<entry>pause</entry> +<entry>Screen pause on: output suspended upon full screen. See +"pag" parameter for definition of screen size. Output +can be resumed by typing any key.</entry> +</row> +<row> +<entry>-pause</entry> +<entry>Screen pause mode off.</entry> +</row> +<row> +<entry>null=n</entry> +<entry>Set null count: number of null ($00) characters +transmitted after carriage returns for return delay. +The number is decimal, default = 0.</entry> +</row> +<row> +<entry>pag=n</entry> +<entry>Set video display page length to n (decimal) lines. +Used for "pause" mode, see above.</entry> +</row> +<row> +<entry>bsp=h</entry> +<entry>Set input backspace character. Numeric value of +character in hexadecimal. Default = 08.</entry> +</row> +<row> +<entry>bse=h</entry> +<entry>Set output backspace character. Numeric value of +character in hexadecimal. Default = 08.</entry> +</row> +<row> +<entry>del=h</entry> +<entry>Set input delete line character. Numeric value of +character in hexadecimal. Default = 18.</entry> +</row> +<row> +<entry>bell=h</entry> +<entry>Set bell (alert) output character. Numeric value of +character in hexadecimal. Default = 07</entry> +</row> +<row> +<entry>eor=h</entry> +<entry>Set end-of-record (carriage return) input character. +Numeric value of character in hexadecimal. Default = 0D</entry> +</row> +<row> +<entry>eof=h</entry> +<entry>Set end-of-file input character. Numeric value of +character in hexadecimal. Default 1B.</entry> +</row> +<row> +<entry>type=h</entry> +<entry>ACIA initialization value: sets parity, word size, etc. +Value in hexadecimal. Default 15</entry> +</row> +<row> +<entry>reprint=h</entry> +<entry>Reprint line character. Numeric value of character +in hexadecimal.</entry> +</row> +<row> +<entry>dup=h</entry> +<entry>Duplicate last input line character. Numeric value of +character in hexadecimal.</entry> +</row> +<row> +<entry>psc=h</entry> +<entry>Pause character. Numeric value of character in +hexadecimal.</entry> +</row> +<row> +<entry>abort=h</entry> +<entry>Abort character (normally control C). Numeric value +of character in hexadecimal.</entry> +</row> +<row> +<entry>quit=h</entry> +<entry>Quit character (normally control E). Numeric value +of character in hexadecimal.</entry> +</row> +<row> +<entry>baud=d</entry> +<entry>Set baud rate for software-controllable interface. Numeric +code for baud rate: 0=110 1=300 2=600 3=1200 4=2400 5=4800 +6=9600 7=19200</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</refsect1> +<refsect1><title>Examples</title> +<screen> +tmode -upc lf null=4 bselF pause + +tmode pag=24 pause bsl -echo bsp=8 bsl=C +</screen> +<para> +NOTE: If you use TMODE in a procedure file, it will be necessary to +specify one of the standard output paths (.1 or .2) since the +shell's standard input path will have been redirected to the disk +file (TMODE can be used on an SCFMAN-type devices only). + +Example: +</para> +<screen> +tmode .1 pag=24 (set lines/page on standard output) +</screen> +</refsect1> +</refentry> + +<refentry id="tsmon"> +<refnamediv> +<refname>TSMON</refname> +<refpurpose>Timesharing monitor</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>TSMON</command> +<arg choice="opt">&replstart;pathlist&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to supervise idle terminals and initiate the +login sequence in timesharing applications. If a pathlist is given, +standard I/O paths are opened for the device. When a carriage return +is typed, TSMON will automatically call the "LOGIN" command. If the +login fails because the user could not supply a valid user name or +password, it will return to TSMON. +</para> +<para> +Note: The LOGIN command and its password file must be present for +TSMON to work correctly (see the LOGIN command description). +</para> +<refsect2> +<title>Logging Off the System</title> +<para> +Most programs will terminate when an end of file character (escape) +is entered as the first character on a command line. This will log +you off of the system and return control to TSMON. +</para> +<para> +For more information see: 2.5, LOGIN +</para> +</refsect2> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9:tsmon /t1& +&005 +</screen> +</refsect1> +</refentry> + +<refentry id="unlink"> +<refnamediv> +<refname>UNLINK</refname> +<refpurpose>Unlink memory module</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>UNLINK</command> +<arg choice="plain"> + &replstart;modname&replend; +</arg> +<arg choice="plain"> +&repeatst; &replstart;modname&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Tells OS-9 that the memory module(s) named are no longer needed by +the user. The module(s) may or may not be destroyed and their +memory reassigned, depending on if in use by other processes or +user, whether resident in ROM or RAM, etc. +</para> +<para> +It is good practice to unload modules whenever possible to make most +efficient use of available memory resources. +</para> +<para> + +Warning: never unlink a module you did not load or link to. +</para> +<para> + + +For more information see: 5.4, 5.4.1, 5.4.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +unlink pgml pgm5 pgm99 + + +OS9: mdir + + Module Directory at 11:26:22 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN RBF +SCF ACIA TERM T1 T2 +T3 P PIA Sysgo Clock +Shell Tsmon Edit + +OS9: unlink edit +OS9: mdir + + Module Directory at 11:26:22 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN RBF +SCF ACIA TERM T1 T2 +T3 P PIA Sysgo Clock +Shell Tsmon +</screen> +</refsect1> +</refentry> + +<refentry id="verify"> +<refnamediv> +<refname>VERIFY</refname> +<refpurpose>Verify or update module header and CRC</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>VERIFY</command> +<arg choice="opt"> + <option>u</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> + +<para> +This command is used to verify that module header parity and CRC +value of one or more modules on a file (standard input) are correct. +Module(s) are read from standard input, and messages will be sent to +the standard error path. +</para> +<para> +If the U (update) option is specified, the module(s) will be copied +to the standard output path with the module's header parity and CRC +values replaced with the computed values. A message will be +displayed to indicate whether or not the module's values matched +those computed by VERIFY. +</para> +<para> +If the option is NOT specified, the module will not be copied to +standard output. VERIFY will only display a message to indicate +whether or not the module's header parity and CRC matched those +which were computed. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: verify <EDIT >NEWEDIT + +Module's header parity is correct. +Calculated CRC matches module's. + +OS9: verify <myprograml >myprogram2 + +Module's header parity is correct. +CRC does not match. + +OS9: verify <myprogram2 + +Module's header parity is correct. +Calculated CRC matches module's. + +OS9: verify u <module >temp +</screen> +</refsect1> +</refentry> + +<refentry id="xmode"> +<refnamediv> +<refname>XMODE</refname> +<refpurpose>Examine or Change Device Initialization Mode</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>XMODE</command> +<arg choice="plain">&replstart;devname&replend;</arg> +<arg choice="opt">&replstart;arglist&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to display or change the initialization +parameters of any SCF-type device such as the video display, +printer, RS232 port, etc. A common use is to change baud rates, +control key definitions, etc. +</para> +<para> +XMODE is very similar to the TMODE command. TMODE only operates on +open paths so its effect is temporary. XMODE actually updates the +device descriptor so the change persists as long as the computer is +running, even if paths to the device are repetitively opened and +closed. If XMODE is used to change parameter(s) and the COBBLER +program is used to make a new system disk, the changed parameter +will be permanently reflected on the new system disk. +</para> +<para> +XMODE requires a device name to be given. If no arguments are +given, the present values for each parameter are displayed, +otherwise, the parameter(s) given in the argument list are +processed. Any number of parameters can be given, and are separated +by spaces or commas. +</para> + +</refsect1> +<refsect1><title>XMODE Parameter Names</title> + +<informaltable frame="none"> +<tgroup cols="2"> +<colspec colwidth="1in"> +<colspec colwidth="4in"> +<tbody> +<row> +<entry>upc</entry> +<entry>Upper case only. Lower case characters are automatically +converted to upper case.</entry> +</row> +<row> +<entry>-upc</entry> +<entry>Upper case and lower case characters permitted (default).</entry> +</row> +<row> +<entry>bsb</entry> +<entry>Erase on backspace: backspace characters echoed as a +backspace-space-backspace sequence (default).</entry> +</row> +<row> +<entry>-bsb</entry> +<entry>no erase on backspace: echoes single backspace only</entry> +</row> +<row> +<entry>bsl</entry> +<entry>Backspace over line: lines are "deleted" by sending +backspace-space-backspace sequences to erase the same +line (for video terminals) (default).</entry> +</row> +<row> +<entry>-bsl</entry> +<entry>No backspace over line: lines are "deleted" by printing +a new line sequence (for hard-copy terminals). +echo Input characters "echoed" back to terminal (default)</entry> +</row> +<row> +<entry>-echo</entry> +<entry>No echo</entry> +</row> +<row> +<entry>lf</entry> +<entry>Auto line feed on: line feeds automatically echoed to +terminal on input and output carriage returns (default).</entry> +</row> +<row> +<entry>-lf</entry> +<entry>Auto line feed off.</entry> +</row> +<row> +<entry>pause</entry> +<entry>Screen pause on: output suspended upon full screen. See +"pag" parameter for definition of screen size. Output +can be resumed by typing any key.</entry> +</row> +<row> +<entry>-pause</entry> +<entry>Screen pause mode off.</entry> +</row> +<row> +<entry>null=n</entry> +<entry>Set null count: number of null ($00) characters +transmitted after carriage returns for return delay. +The number is decimal, default = 0.</entry> +</row> +<row> +<entry>pag=n</entry> +<entry>Set video display page length to n (decimal) lines. +Used for "pause" mode, see above.</entry> +</row> +<row> +<entry>bsp=h</entry> +<entry>Set input backspace character. Numeric value of +character in hexadecimal. Default = 08.</entry> +</row> +<row> +<entry>bse=h</entry> +<entry>Set output backspace character. Numeric value of +character in hexadecimal. Default = 08.</entry> +</row> +<row> +<entry>del=h</entry> +<entry>Set input delete line character. Numeric value of +character in hexadecimal. Default = 18.</entry> +</row> +<row> +<entry>bell=h</entry> +<entry>Set bell (alert) output character. Numeric value of +character in hexadecimal. Default = 07</entry> +</row> +<row> +<entry>eor=h</entry> +<entry>Set end-of-record (carriage return) input character. +Numeric value of character in hexadecimal. Default = 0D</entry> +</row> +<row> +<entry>eof=h</entry> +<entry>Set end-of-file input character. Numeric value of +character in hexadecimal. Default 1B.</entry> +</row> +<row> +<entry>type=h</entry> +<entry>ACIA initialization value: sets parity, word size, etc. +Value in hexadecimal. Default 15</entry> +</row> +<row> +<entry>reprint=h</entry> +<entry>Reprint line character. Numeric value of character +in hexadecimal.</entry> +</row> +<row> +<entry>dup=h</entry> +<entry>Duplicate last input line character. Numeric value of +character in hexadecimal.</entry> +</row> +<row> +<entry>psc=h</entry> +<entry>Pause character. Numeric value of character in +hexadecimal.</entry> +</row> +<row> +<entry>abort=h</entry> +<entry>Abort character (normally control C). Numeric value +of character in hexadecimal.</entry> +</row> +<row> +<entry>quit=h</entry> +<entry>Quit character (normally control E). Numeric value +of character in hexadecimal.</entry> +</row> +<row> +<entry>baud=d</entry> +<entry>Set baud rate for software-controllable interface. Numeric +code for baud rate: 0=110 1=300 2=600 3=1200 4=2400 5=4800 +6=9600 7=19200</entry> +</row> +</tbody> +</tgroup> +</informaltable> +</refsect1> +<refsect1><title>Examples</title> +<screen> +xmode /TERM -upc lf null=4 bse=1F pause + +xmode /T1 pag=24 pause bsl -echo bsp=8 bsl=C + +xmode /P baud=3 -if +</screen> +</refsect1> +</refentry> +</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>