Mercurial > hg > Members > kono > nitros9-code
changeset 144:f4e798ea65b9
More splitups.
| author | roug |
|---|---|
| date | Sun, 07 Jul 2002 09:54:04 +0000 |
| parents | 740f7868679c |
| children | 099333bc912e |
| files | docs/nitros9guide/chap1.chapter docs/nitros9guide/chap2.chapter docs/nitros9guide/chap3.chapter docs/nitros9guide/chap4.chapter |
| diffstat | 4 files changed, 2547 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/chap1.chapter Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,307 @@ +<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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/chap2.chapter Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,405 @@ +<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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/chap3.chapter Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,1118 @@ +<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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/chap4.chapter Sun Jul 07 09:54:04 2002 +0000 @@ -0,0 +1,717 @@ +<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>