Mercurial > hg > Members > kono > nitros9-code
view docs/nitros9guide/os9guide.docbook @ 109:7a281e28b851
Fixed the problematic labels
| author | roug |
|---|---|
| date | Sat, 06 Jul 2002 15:44:46 +0000 |
| parents | 32bd5072b3a5 |
| children | 40f5c43c8c03 |
line wrap: on
line source
<!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>