# HG changeset patch # User roug # Date 1026035644 0 # Node ID f4e798ea65b93f0ced804998512463be78bf0e47 # Parent 740f7868679c62f29851aa91d3666bd0476898ae More splitups. diff -r 740f7868679c -r f4e798ea65b9 docs/nitros9guide/chap1.chapter --- /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 @@ + +Getting Started... + +
+What You Need to Run OS-9 + +OS-9 has been tailored to run on your standard, unmodified Dragon +Computer. To use it you'll need the following things: + + + A 64K Memory Dragon Computer + A Dragon Disk Drive With Contoller Cartridge + An OS-9 Dragon System Disk + + +OS-9 is also ready to use the following optional equipment that you +may have now or may obtain in the future: + + + Additional Expansion Disk Drive(s) + A Parallel Printer + Game Joysticks + Other OS-9 Compatible Languages and Software + + +
+Starting the System + +To start up OS-9 follow these steps: + + +Turn the Dragon Computer and disk drive(s) on. You should see +the usual Basic greeting message on the screen. + +Insert the OS-9 System Disk in drive zero and close the door. + +Type "BOOT". After a few seconds of disk activity you should +see a screen with the words "OS9BOOT". + +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. + + +
+ +
+In Case You Have Problems Starting OS-9 + +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. + +Did you remember to turn the disk drive power switch on? + +Does your Dragon Computer have 64K RAM? This is a must! + +If your Dragon Computer doesn't seem to understand the BOOT +command, contact your dealer. + +If the "OS9BOOT message is displayed but nothing else happens, +you may have a corrupted system disk. Hopefully you did make a +backup! + +
+ +
+A Quick Introduction to the Use of the Keyboard and Disks + +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. + + +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. + +
+ +
+Initial Explorations + +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: + + YY/MM/DD HH:MM:SS + TIME ? 83 7 14 1420 + +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. + + +Now you're ready to try some commands. A good first command to +try is DIR (for "directory"). +This will display a list of the files +on the System Disk. Just type: + +dir + +followed by a "return". OS-9 should respond with a listing of file +names which should look something like this: + + OS9Boot startup CMDS SYS DEFS + +The file "OS9Boot" contains the OS-9 program in 6809 machine +language, which was loaded into memory during the bootstrap +operation. + + +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 + +list startup + +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! + + +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. + + +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 +root directory - 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. + + +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: + +DIR CMDS + +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: + +DIR X + +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). + +
+
+
+Making a Backup of the System Disk + +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. + +
+Formatting Blank Disks + +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. + + +IF YOU HAVE ONLY ONE DISK DRIVE you have to be extra careful not to +accidentally FORMAT your system disk. Type: + + +FORMAT /D0 + + +and when you see the message + + +DRAGON DISK FORMATTER 1 . 2 +FORMAT DRIVE /D0 +Y (YES) OR N (NO) +READY? + + +immediately remove your system disk and insert a blank disk +before you type "Y". + +IF YOU HAVE TWO DISK DRIVES place the blank disk in drive one and +type: + + +FORMAT /D1 + + +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. + + +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. + + +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. + +
+ +
+Running the Backup Program + +The BACKUP program makes an exact duplicate of a disk. It can be +used even if you only have one disk drive. + + +IF YOU HAVE ONE DRIVE type + + +BACKUP /D0 #32k + + +The BACKUP program will prompt you to alternately insert the source +disk (the system disk) and the destination disk (the freshly +formatted disk). + + +IF YOU HAVE TWO DRIVES type + + +BACKUP #32K + + + +The BACKUP program will respond with + + +Ready to BACKUP from /D0 to /D0 (or /D1) ? + + +Now enter Y for yes. It will then ask: + + +X IS BEING SCRATCHED +OK ?: + + +Answer "Y" for yes again, and the BACKUP process should begin. + + +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. + + +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. + +
+
+ diff -r 740f7868679c -r f4e798ea65b9 docs/nitros9guide/chap2.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 @@ + +Basic Interactive Functions + +
+Running Commands and Basic Shell Operation + +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. + + +The command line always begins with a name of a program which can +be: + + + +The name of a machine language program on disk +The name of a machine language program already in memory +The name of an executable program compiled by a high-level +language such as Basic09, Pascal, Cobol, etc. (See 4.8) +The name of a procedure file (See 4.6) + + +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. + + +When processing the command line, the shell searches for a +program having the name specified in the following sequence: + + + + +- If the program named is already in memory, it is run. + +- 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). + +- 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. + + + +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. + + +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. + + +For example, in the command line: + + +LIST FILE1 + + +the program name is LIST, and the parameter passed to it is FILE1. + + +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). + + + +
+Sending Output to the Printer + +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: + + +>/P + + +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: + + +DIR >/P + + +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: + + +xmode /P + + +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: + + +xmode /P lf; + +
+
+ +
+Shell Command Line Parameters + +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. + + +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: + + +LIST STARTUP + + +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: + + +COPY STARTUP NEWSTARTUP + + +Other commands have parameters which select options. For example: + + +DIR + + +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 entire) +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: + + +DIR E + + +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: + + +DIR SYS + + +It is also possible to specify both a directory name parameter and +the e option, such as: + + +DIR SYS E + + +giving file names and complete statistics (See example in 3.8.1). + +
+ +
+Some Common Command Formats + +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 must be a directory file. + + +CHD filename chd DATA.DIR + +Changes the current data working directory to +the directory file specified. + +COPY filename1 filename2 copy oldfile newfile + +Creates filename2 as a new file, then copies all data from +"filename1" to it. "filename1" is not affected. + +DEL filename del oldstuff + +Deletes (destroys) the file specified. + +DIR [filename] [e] [x] dir myfiles e + +List names of files contained in a directory. If the "x" option is +used the files in the current execution +directory are listed, +othervise, if no directory name is given, the current +data directory will be listed. +The "e" option selects the long format +which shows detailed information about each file. + +FREE devicename free /d1 + +Shows how much free space remains on the disk whose name is given. + +LIST filename list script + +Displays the (text) contents of the file on the terminal. + +MAKDIR filename makdir NEWFILES + +Creates a new directory file using the name given. Often followed +by a "chd" command to make it the new working data directory. + +RENAME filename1 filename2 rename zip zap + +Changes the name of filename1 to filename2. + +
+ +
+Using the Keyboard and Video Display + +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". + + +
+Video Display Functions + +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: + + +TMODE -UPC + + +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: + + +TMODE -PAUSE turns pause mode off +TMODE PAUSE turns pause mode on + + +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. + +
+ +
+Keyboard Shift and Control Functions + +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 . + + +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. + +
+ +
+Control Key Functions + +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. + + + + CONTROL A + + +Repeat previous input line. The last line entered will be redisplayed but +not 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. + + + + + CONTROL D + + +Redisplay present input on next line. + + + + + CONTROL W + + +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. + + + + + CONTROL 0 + + +Shift lock. Reverses present shift lock state. + + + + + BREAK KEY (or CONTROL E) + + +Program abort - Stops the current running program + + + + + SHIFT BREAK KEY (or CONTROL C) + + +Interrupt - Reactivates Shell while keeping program running as +background task. + + + + + CONTROL BREAK KEY (ESCAPE) + + +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. + + + + + LEFT ARROW (OR CONTROL H) + + +Backspace - erase previous character + + + + + SHIFT LEFT ARROW (or CONTROL X) + + +Line Delete - erases the entire current line. + + + + +
+
+ + diff -r 740f7868679c -r f4e798ea65b9 docs/nitros9guide/chap3.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 @@ + +The OS-9 File System +
+Introduction to the Unified Input/Output System + +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 +logical functions 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. + + +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. + + +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. + + +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. + + +Some of the advantages of the unified I/O system are: + + + +Programs will operate correctly regardless of the particular I/O +devices selected and used when the program is actually executed. + + +Programs are highly portable from one computer to another, even +when the computers have different kinds of I/O devices. + + +I/O can be redirected to alternate files or devices when the +program is run, without having to alter the program. + + +New or special device driver routines can easily be created and +installed by the user. + + +
+ +
+Pathlists: How Paths Are Named + +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. + + +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. + + +Names are used to describe three kinds of things: + + +Names of Physical I/O Devices +Names of Regular Files +Names of Directory Files + + + +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: + + + +uppercase letters: A - Z +lowercase letters: a - z +decimal digits: 0 - 9 +underscore: _ +period: . + + + +Here are examples of legal names: + + + + + + +raw.data.2 +projectreview.backup + + +reconciliation.report +X042953 + + +RJJones +search.bin + + + + + +Here are examples of illegal names: + + + + + + + +22November +(does not start with a letter) + + +max*min +(* is not a legal character) + + +.data +(does not start with a letter) + + +open orders +(cannot contain a space) + + +this.name.obviously.has.more.than.29.characters +(too long) + + + + + +
+ +
+I/O Device Names + +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: + + + + + + + +TERM +Video display/keyboard + + +P +Printer port + + +D0 +Disk drive unit zero + + +D1 +Disk drive unit one + + +PIPE +Pipes + + + + + +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: + + + +/TERM +/P +/D1 + + + +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. + +
+ +
+Multifile Devices And Directory Files + +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. + + +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: + + + +/d1/mouse + + + +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. + + +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. + + + 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 + + +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: + +list /d1/file2 + +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: + +copy /d0/cmds/dir temp + + +
+ +
+Creating and Using Directories + +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. + + +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: + + +OS9: build /d1/file1 +? This is the first file that +? we created. +? [ENTER] + + + +The "dir" command will now indicate the existence of the new file: + + + +OS9: dir /d1 + + Directory of /d1 15:45:29 +file1 + + + +The "list" command can be used to display the text stored in the +file: + + + +OS9: list /d1/file1 + +This is the first file +that we created. + + + +The "build" command again is again used to create two more text +files: + + + +OS9: build /d1/file2 +? This is the second file +? that we created. +? [ENTER] + +OS9: build /d1/file3 +? This is another file. +? [ENTER] + + + +The dir command will now show three file names: + + + +OS9: dir /d1 + Directory of /D1 15:52:29 +file1 file2 file3 + + + +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 not 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). + + + +OS9: makdir /D1/NEWDIR + + + +The directory file "NEWDIR" is now a file listed in D1's root +directory: + + + +OS9: dir /D1 + + Directory of /D1 16:04:31 +file1 file2 file3 NEWDIR + + + +Now we will create a new file and put in the new directory, using +the COPY command to duplicate "file1": + + +OS9: COPY /D1/file1 /D1/NEWDIR/file1.copy + + +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: + + + D1 Root Directory + +---------+--------+--------+ + ! ! ! ! + NEWDIR file1 file2 file3 + ! + ! +file1.copy + + +The dir command can now show the files in the new directory: + + +OS9: dir /D1/NEWDIR + + Directory of /D1/NEWDIR +file1.copy + + +It is possible to use "makdir" to create additional new directories +within "NEWDIR", and so on, limited only by available disk +space. + +
+ +
+Deleting Directory Files + +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: + + +1 - All file names in the directory must be deleted. + + +2 - The "attr" command is used to turn off the files directory +attrribute (-d option), making it an ordinary file (see 3.8). + + +3 - The file may now be deleted using the "del" command. + + +A simpler alternative is to use the DELDIR command to automatically +perform all these steps for you. + +
+ +
+Additional Information About Directories + +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. + + +Here are some important characteristics relating to use of directory +files: + + + +Directories have the same ownership and security attributes +and rules as regular files. See Section 3.6. + + +The name of a given file appears in exactly one directory. + + +Files can only be added to directories when they are created. + + +A file and the directory in which its name is kept must reside on +the same device. + + +
+ +
+Using and Changing Working Directories + +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. + + +The rules used to determine whether pathlists refer to the +current working directory or not are simple: + + +---> 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. + + +---> When the first character of a pathlist IS NOT a "/", +processing of the pathlist starts at the current working +directory. + + +Notice that pathlists starting with a "/" +must 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: + + + +/d2/JOE/WORKINGFILES/testresults + + + +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: + + +baseball + + +the actual pathlist implied is: + + +/D1/PETE/GAMES/baseball + + +Pathlists using working directories can also specify additional +lower-level directories. Referring to the example above, the +pathlist: + + +ACTION/racing + + +implies the complete pathlist: + + +/D1/PETE/GAMES/ACTION/racing + + +
+Automatic Selection of Working Directories + +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 +programs can be organized in different directories than +files containing data. +OS-9 automatically selects either working +directory, depending on the usage of the pathlist: + + +---> 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). + + +---> The data directory is used for all other file references (such +as text files, etc.) + + +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). + + +Here is an example of a shell command statement using the default +working directory notation, and its equivalent expansion: + + +copy file1 file2 + + +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: + + +OS9: /D0/CMDS/copy /D0/JONES/filel /D0/JONES/file2 + + +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. + +
+ +
+Changing Current Working Directories + +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: + + +OS9: chd /D1/MY.DATAFILES + +OS9: chx /D0/TESTPROGRAMS + + +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: + + +OS9: CHD /D1/SARAH +OS9: CHD PROJECT1 + +OS9: CHD /D1/SARAH/PROJECT1 (same effect as above) + +
+ +
+Anonymous Directory Names + +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: + + +"." refers to the present working directory + + +".." refers to the directory that contains the name of the present +directory (e.g., the next highest level directory) + + +"..." refers to directory two levels up, and so on + + +These can be used in place of pathlists and/or the first name in a +pathlist. Here are some examples: + + + + + + + +OS9: dir . +lists file names in the working data directory + + +OS9: dir .. +lists names in the working data directory's parent directory. + + +OS9: DEL ../temp +deletes the file "temp" from the +working data directory's parent directory. + + + + + +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. + +
+
+ +
+The File Security System + +Every file (including directory files) has properties called +ownership +and attributes which determine who may access the file and +how it many be used. + + +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. + + +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: + + +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. + + +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) + + +EXECUTE PERMISSION FOR OWNER: If on, the owner can load the file into memory +and execute it. Note that the file must contain one or +more valid OS-9 format memory modules in order to actually load (See +3.9.4 and 5.4.1). + + +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. + + +WRITE PERMISSION FOR PUBLIC - If on, any other user may write to or +delete the file. + + +READ PERMISSION FOR PUBLIC - If on, any other user may read (and +possibly copy) the file. + + +EXECUTE PERMISSION FOR PUBLIC - If on, any other user may execute +the file. + + +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. + + +
+Examining and Changing File Attributes + +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: + + + 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 + + + +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: + + + dsewrewr + + + +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: + + + +OS9: attr file2 +-s-wr-ewr + + + +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: + + +OS9: attr file2 pw pr -e -pe + + +enables public write and public read permissions and removes execute +permission for both the owner and the public. + + +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 +cannot be used to turn +the directory (d) attribute on (only "makdir" can), and can be used +to turn it off only if the directory is empty. + +
+
+ +
+Reading and Writing From Files + +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. + + +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. + + +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. + + +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. + + +
+File Usage in OS-9 + +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: + + +TEXT +RANDOM ACCESS DATA +EXECUTABLE PROGRAM MODULES +DIRECTORIES +MISCELLANEOUS + +
+ +
+Text Files + +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. + + +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. + + +The content of text files may be examined using the "list" +command. + +
+ +
+Random Access Data Files + +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. + + +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. + + +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. + + +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. + +
+ +
+Executable Program Module Files + +These files are used to hold program modules generated by the +assembler or compiled by high-level languages. +Each file may +contain one or more program modules. + + +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. + + +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. + + +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. + + +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. + +
+ +
+Directory Files + +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. + + +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. + + +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). + + +Directories cannot be copied or listed - the "dir" command is +used instead. Directories also cannot be deleted directly (see 3.5). + +
+ +
+Miscellaneous File Usage + +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. + + +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. + +
+
+ +
+Physical File Organization + +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. + + +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 LSN. +The mapping of logical sector numbers to +physical track/sector numbers is done by the disk driver module. + + +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 +clusters, +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 bitmap (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. + + +The Dragon Computer disk system uses the following format: + + + +double density recording on one side + + +40 tracks per disk + + +18 sectors per track + + +one sector per cluster + + + +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: + + + +attributes + + +owner + + +date and time created + + +size + + +segment list (description of data sector blocks) + + + +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". + +
+ diff -r 740f7868679c -r f4e798ea65b9 docs/nitros9guide/chap4.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 @@ + +Advanced Features of the Shell + +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: + + + + +I/O redirection (including filters) + + +Memory Allocation + + +Multitasking (concurrent execution) + + +Procedure File Execution (background processing) + + +Execution Control (built-in commands) + + + + +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. + + +
+A More Detailed Description Command Line Processing + +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: + + + + +A program, procedure file, or built-in command name ("verbs") + + +Parameters to be passed to the program + + +Execution modifiers to be processed by the shell + + + + +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. + + +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. + + +Here is a sample shell line which calls the assembler: + + +asm sourcefile l -o >/p #12k + + +In this example: + + + + + + + + +asm +is the verb + + +sourcefile l -o +are parameters passed to "asm + + +>/p +is a modifier which redirects the output +(listing) to the system's printer + + +#12K +is a modifier which requests that the +process be assigned 12K bytes of memory +instead of its (smaller) default amount. + + + + + + +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. + +
+ +
+Execution Modifiers + +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. + + +
+Alternate Memory Size Modifier + +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: + + +OS9: copy #8 file1 file2 (gives 8*256 = 2048 bytes) +OS9: copy #2K file1 file2 (gives 2*1024 = 2048 bytes) + +
+ +
+I/O Redirection Modifiers + +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: + + +STANDARD INPUT: This path normally passes data from the +terminal's keyboard to the program. + + +STANDARD OUTPUT PATH: This path is normally used to output +data from the program to the terminal's display. + + +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. + + +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: + + + + + + + +< +Redirect the standard input path + + +> +Redirect the standard output path + + +>> +Redirect the standard error output path + + + + + + +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: + + +OS9: LIST correspondence >/p + + +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": + + +OS9: DIR >/D1/savelisting + + +If the LIST command is used on the file "/D1/savelisting", output +from the DIR command will be displayed as shown below: + + +OS9: LIST /D1/savelisting + + Directory of . 10:15:00 +myfile savelisting file1 + + +Redirection modifiers can be used before and/or after the program's +parameters, but each modifier can only be used once. + +
+
+ +
+Command Separators + +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. + + + +
+Sequential Execution + +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: + + +OS9: COPY myfile /D1/newfile ; DIR >/p + + +This command line will first execute the COPY command and then the +DIR command. + + +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. + + +Here are some more examples: + + +OS9: copy oldfile newfile; del oldfile; list newfile + +OS9: dir >/d1/myfile ; list temp >/p; del temp + + +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. + +
+ +
+Concurrent Execution + +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. + + +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: + + +OS9: DIR >/P& +&007 + +OS9: + + +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: + + +OS9: DIR >/P& LIST file1& COPY file1 file2 ; DEL temp + + + + + +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. + +
+ +
+Pipes and Filters + +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". + + +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. + + +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. + + +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: + + +OS9: update <master_file ! sort ! write_report >/p + + +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. + + +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. + +
+
+ +
+Command Grouping + +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: + +OS9: (dir /d0; dir /d1) >/p + +gives the same result as: + +OS9: dir /d0 >/p; dir /d1 >/p + +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. + + +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: + + +OS9: (del file1; del file2; del file3)& + + +A useful extension of this form is to construct pipelines consisting +of sequential and/or concurrent programs. For example: + + +OS9: (dir CMDS; dir SYS) ! makeuppercase ! transmit + + +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: + + +OS9: chd /d0/WORKING; dsave ! (chd /d0/ARCHIVE) + +
+ +
+Built-in Shell Commands and Options + +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. + + +The built-in commands and their functions are: + + + + + + + +chd &replstart;pathlist&replend; +change the working data directory to the directory +specified by the pathlist (see 3.6). + + +chx &replstart;pathlist&replend; +change the working execution directory to the +directory specified by the pathlist (see 3.6). + + +ex name +directly execute the module named. This +transforms the shell process so it ceases +to exist and a new module begins execution in +its place. + + +w +wait for any process to terminate. + + +* text +comment: "text" is not processed. + + +kill &replstart;Proc ID&replend; +abort the process specified. + + +setpr &replstart;proc ID&replend; &replstart;priority&replend; +changes process' priority (see 5.1). + + +x +causes shell to abort on any error (default) + + +-x +causes shell not to abort on error (See 4.7) + + +p +turns shell prompt and messages on (default) + + +-p +inhibits shell prompt and messages + + +t +makes shell copy all input lines to output + + +-t +does not copy input lines to output (default) + + + + + + + +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. + +
+ +
+Shell Procedure Files + +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. + + +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. + + +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). + + +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". + + +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. + + +Here are two simple ways to use the shell to create another +shell: + + +OS9: shell <procfile + +OS9: procfile + + +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: + + +OS9: procfile& + + +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: + + +OS9: proc1 T >>stat1& proc2 T >>stat2& + + +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 +not 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. + +
+ +
+Error Reporting + +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. + + +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). + +
+ +
+Running Compiled Intermediate Code Programs + +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). + + +For example, if you wanted to run a BASIC09 I-code module called +"adventure", you could type the command given below: + + +OS9: BASIC09 adventure + + +Or you could accomplish the same thing by typing the following: + + +OS9: adventure + +
+ +
+Setting Up Timesharing System Procedure Files + + +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. + + +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". + + +* system startup procedure file +echo Please Enter the Date and Time +setime </term +printerr +tsmon /t1& +tsmon /t2& +tsmon /t3& + + +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. + + +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. + +
+