# HG changeset patch
# User roug
# Date 1026035644 0
# Node ID 4cd37950c6058e42229ff1c1de1c41cc5f5b6ece
# Parent 21649cf64510d436dd2f50a0dc4d58604bdfc994
More splitups.
diff -r 21649cf64510 -r 4cd37950c605 docs/nitros9guide/acia51.appendix
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/nitros9guide/acia51.appendix Sun Jul 07 09:54:04 2002 +0000
@@ -0,0 +1,88 @@
+
+Using the Serial Interface
+
+For those who wish to use the serial port, the input or
+output path of a program may be redirected to the serial port of
+your Dragon computer.
+
+
+This is done by including the following module in the OS-9 kernel:
+
+
+ACIA51 - Serial Device Driver
+
+
+To load this module into the kernel enter the following command line:
+
+
+LOAD /D0/CMDS/ACIA51
+
+
+
+Serial Printer Implementation
+
+For those with a serial printer, you can use the serial port
+in the redirection of a program's output path by including the
+following modifier at the end of a command line:
+
+
+>/P1
+
+
+The baud rate of the serial port may be changed as follows:
+
+
+XMODE /P1 BAUD=3
+
+
+This will change the baud rate to 1200 characters per second.
+For a detailed description of the baud rate see the XMODE
+command description.
+
+
+
+Serial Terminal Implementation
+
+For those who wish to connect two Dragon computers, running
+OS-9, together using the serial port, redirection of the input
+or output paths is possible using the following modifier at
+the end of a command line:
+
+
+>/T1 - for an output path
+
+
+</T1 - for an input path
+
+
+To pass a file of data between the two computers, one must be
+configured for input from the serial port and the other
+configured for output:
+
+
+Computer 1, BUILD TEXT </T1 - input to port
+
+
+Computer 2, BUILD <TEXT /T1 - output to port
+
+
+Using the above example, the text file on computer 2 will be
+transferred to a file called TEXT on computer 1.
+
+
+When the command line is entered on computer 1, the system will
+reply with a question mark and wait for information from the
+serial port. The command line on computer 2 will send data to
+the now waiting computer 1. A string of question marks will now
+be seen, this is the number of lines sent and recieved by the
+respective computers.
+
+
+To create a log-off sequence after such a transfer, use the DISPLAY
+command as follows:
+
+
+Computer 1, BUILD <TEXT /T1 ; DISPLAY 0A 0D >/T1
+
+
+
diff -r 21649cf64510 -r 4cd37950c605 docs/nitros9guide/commands.appendix
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/nitros9guide/commands.appendix Sun Jul 07 09:54:04 2002 +0000
@@ -0,0 +1,159 @@
+
+Command Summary
+
+
+
+
+
+
+
+ATTRChange File Attributes7-2
+
+
+BACKUPMake Disk Backup7-3
+
+
+BINEXConvert Binary to S-Record7-5
+
+
+BUILDBuild Text File7-6
+
+
+CHDChange Working Data Directory7-7
+
+
+CHXChange Working Execution Directory7-7
+
+
+CMPFile Comparison Utility7-8
+
+
+COBBLERMake Bootstrap File7-9
+
+
+COPYCopy Data7-10
+
+
+DATEDisplay System Date and Time7-11
+
+
+DCHECKCheck Disk File Structure7-12
+
+
+DELDelete a File7-16
+
+
+DELDIRDelete All Files in a Directory System7-17
+
+
+DIRDisplay File Names in a Directory7-18
+
+
+DISPLAYDisplay Converted Characters7-19
+
+
+DSAVEGenerate Procedure File to Copy Files7-20
+
+
+DUMPFormatted File Dump7-21
+
+
+ECHOEcho Text to Output Path7-22
+
+
+EXExecute Program as Overlay7-23
+
+
+EXBINConvert S-Record To Binary7-5
+
+
+FORMATInitialize Disk Media7-24
+
+
+FREEDisplay Free Space on Device7-25
+
+
+IDENTPrint OS-9 module identification7-26
+
+
+KILLAbort a Process7-28
+
+
+LINKLink Module Into Memory7-29
+
+
+LISTList Contents of- Disk File7-30
+
+
+LOADLoad Module(s) Into Memory7-31
+
+
+LOGINTimesharing System Log-In7-32
+
+
+MAKDIRCreate Directory File7-34
+
+
+MDIRDisplay Module Directory7-35
+
+
+MERGECopy and Combine Files7-36
+
+
+MFREEDisplay Free System RAM Memory7-37
+
+
+OS9GENBuild and Link a Bootstrap File7-38
+
+
+PRINTERRPrint Full Text Error Messages7-40
+
+
+PROCSDisplay Processes7-41
+
+
+PWDPrint Working Directory7-42
+
+
+PXDPrint Execution Directory7-42
+
+
+RENAMEChange File Name7-43
+
+
+SAVESave Memory Module(s) on a File7-44
+
+
+SETIMEActivate and Set System Clock7-45
+
+
+SETPRSet Process Priority7-46
+
+
+SLEEPSuspend Process for Period of Time7-47
+
+
+SHELLOS-9 Command Interpreter7-48
+
+
+TEECopy Standard Input to Multiple Output Paths7-50
+
+
+TMODEChange Terminal Operating Mode7-51
+
+
+TSMONTimesharing Monitor7-54
+
+
+UNLINKUnlink Memory Module7-55
+
+
+VERIFYVerify or Update Module Header and CRC7-56
+
+
+XMODEExamine or Change Device Initialization Mode7-57
+
+
+
+
+
diff -r 21649cf64510 -r 4cd37950c605 docs/nitros9guide/os9guide.docbook
--- a/docs/nitros9guide/os9guide.docbook Sun Jul 07 08:58:56 2002 +0000
+++ b/docs/nitros9guide/os9guide.docbook Sun Jul 07 09:54:04 2002 +0000
@@ -3,6 +3,20 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -74,4850 +88,19 @@
-
-Welcome to OS-9!
-Introduction
-
-The heart of your Dragon Computer is an amazing device: the
-6809 microprocessor chip. This advanced microcomputer can run the
-kind of sophisticated software normally found only on much larger
-and costly computers. Because the OS-9 operating system was designed
-by the same people who designed the 6809 microcomputer, together
-they provide an extremely efficient and powerful combination.
-
-
-The foundation of a computer's software system is its
-Operating System or "OS". It is the master control
-program that interfaces all other software to the system's hardware. Some
-of the things it must do are performing input and output operations,
-coordinating memory use, and many other "housekeeping" functions. All
-other software - programming languages, applications programs, etc. -
-live in your computer's memory along with the OS and depend on it to
-communicate with you using the keyboard and display and to store and
-retrieve data on disks, etc. Because virtually all other software relies
-on the OS, your computer's performance depends on the capabilities and
-efficiency of its OS.
-
-
-
-OS-9's overall structure was based on the famous UNIX
-
-Unix is an operating system designed by Bell Telephone
-Laboratories, which is becoming widely recognized as a standard for
-mini and micro operating systems because of its versatility and
-elegant structure.
-
-
-operating system, which has been widely acclaimed as the operating
-system of the future because of its versatility, logical structure,
-and friendly user commands. The OS-9 family of advanced software is
-not only more powerful than most other microcomputer scftware - it
-is also much easier to learn and use.
-
-
-Some of the advanced OS-9 features you'll learn about in this
-book are:
-
-
-
-Friendly Unix-type
-user interface and environment
-
-Multiuser/Multitasking Real-Time Operating System
-
-Extensive support for structured, modular programming
-
-Device-independent interrupt-driven input/output system
-
-Multi-level directory file system
-
-Fast Random-Access File System
-
-Readily Expandable and Adaptable Design
-
-
-
-If you don't know what some of these thing mean yet - don't
-worry. As you explore OS-9 you'll soon learn how they enhance the
-capability of your Dragon Computer and make it so much easier to use
-in almost any application.
-
-
-OS-9 has many commands and functions - definitely more than
-you can learn in an evening! The best way to become an OS-9 expert
-is to study this manual carefully, section-by-section, taking tire
-to try out each command or function. Because many functions affect
-others, you'll find this manual extensively cross-referenced so you
-can skip ahead to help you understand a new topic. Taking the time
-to study this book will certainly increase your knowledge and
-enjoyment of OS-9.
-
-
-But if you can't wait, at least read the rest of this chapter,
-scan the command descriptions in Chapter 7, and have fun
-experimenting!
-
-
-
-
-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.
-
-
-
-
-
-
-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.
-
-
-
-
-
-
-
-
-
-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".
-
-
-
-
-
-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)
-
-
+&preface;
+&chap1;
+&chap2;
+&chap3;
+&chap4;
+&chap5;
+&chap6;
+&chap7;
+&commandsapp;
+&errorcodesapp;
+&displayapp;
+&keysapp;
+&go51app;
+&acia51app;
-
-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.
-
-
-
-
-
-
-Multiprogramming and Memory Management
-
-One of OS-9's most extraordinary abilities is multiprogramming,
-which is sometimes called timesharing or multitasking. Simply
-states, OS-9 lets you computer run more than one program at the same
-time. This can be a tremendous advantage in many situations. For
-example, you can be editing one program while another is being
-printed. Or you can use your Color Computer to control household
-automation and still be able to use it for routine work and
-entertainment.
-
-
-OS-9 uses this capability all the time for internal functions.
-The simple way for you to do so is by putting a "&" character at the
-end of a command line which causes the shell to run your command as
-a "background task".
-
-
-The information presented in this chapter is intended to give you
-an insight into how OS-9 performs this amazing feat. You certainly
-don't have to know every detail of how multiprogramming works in
-order to use OS-9, but a basic working knowledge can help you
-discover many new ways to use your Color Computer.
-
-
-In order to allow several programs to run simultaneously and
-without interference, OS-9 must perform many coordination and
-resource allocation functions. The major system resources managed
-by OS-9 are:
-
-
-CPU Time
-Memory
-The input/output system
-
-
-In order for the computer to have reasonable performance, these
-resources must be managed in the most efficient manner possible.
-Therefore, OS-9 uses many techniques and strategies to optimize
-system throughput and capacity.
-
-
-
-Processor Time Allocation and Timeslicing
-
-
-CPU time is a resource that must be allocated wisely to maximize
-the computer's throughput. It is characteristic of many programs to
-spend much unproductive time waiting for various events, such as an
-input/output operation. A good example is an interactive program
-which communicates with a person at a terminal on a line-by line
-basis. Every time the program has to wait for a line of characters
-to be typed or displayed, it (typically) cannot do any useful
-processing and would waste CPU time. An efficient multiprogramming
-operating system such as OS-9 automatically assigns CPU time to only
-those programs that can effectively use the, time.
-
-
-OS-9 uses a technique called timeslicing which allows processes
-to share CPU time with all other active processes. Timeslicing is
-implemented using both hardware and software functions. The
-system's CPU is interrupted by a real time clock many (60 in the
-Color Computer) times each second. This basic time interval is
-called a "tick", hence, the interval between ticks is a time slice.
-This technique is called timeslicing because each second of CPU time
-is sliced up to be shared among several processes. This happens so
-rapidly that to a human observer all processes appear to execute
-continuously, unless the computer becomes overloaded with processing. If this
-happens, a noticeable delay in response to terminal
-input may occur, or "batch" programs may take much longer to run
-than they ordinarily do. At any occurrence of a tick, OS-9 can suspend
-execution of one program and begin execution of another. The
-starting and stopping of programs is done in a manner that does not
-affect the program's execution. How frequently a process is given
-time slices depends upon its assigned priority relative to the
-assigned priority of other active processes.
-
-
-The percentage of CPU time assigned to any particular process
-cannot be exactly computed because there are dynamic variables such
-as time the process spends waiting for I/O devices. It can be
-roughly approximated by dividing the process's priority by the sum
-of the priority numbers of all processes:
-
-
-
- Process Priority
-Process CPU Share = -------------------
- Sum of All Active
- Process' Priorities
-
-
-
-
-Process States
-
-
-The CPU time allocation system automatically assigns programs one
-of three "states" that describe their current status. Process
-states are also important for coordinating process execution. A
-process may be in one and only one state at any instant, although
-state changes may be frequent. The states are:
-
-
-
-
-ACTIVE:
-processes which can currently perform useful processing.
-These are the only processes assigned CPU time.
-
-
-WAITING:
-processes which have been suspended until another process
-terminates. This state is used to coordinate execution of
-sequential programs. The shell, for example, will be in the waiting
-state during the time a command program it has initiated is running.
-
-
-
-SLEEPING:
-processes suspended by self-request for a specified time
-interval or until receipt of a "signal". Signals are internal
-messages used to coordinate concurrent processes. This is the
-typical state of programs which are waiting for input/output
-operations.
-
-
-
-
-Sleeping and waiting processes are not given CPU time until they
-change to the active state.
-
-
-
-
-Creation of New Processes
-
-
-The sequence of operations required to create a new process and
-initially allocate its resources (especially memory) are
-automatically performed by OS-9's "fork" function. If for any
-reason any part of the sequence cannot be performed the fork is
-aborted and the prospective parent is passed an appropriate error
-code. The most frequent reason for failure is unavailablity of
-required resources (especially memory) or when the program specified
-to be run cannot be found. A process can create many new processes,
-subject only to the limitation of the amount of unassigned memory
-available.
-
-
-When a process creates a new process, the creator is called the
-"parent process", and the newly created process is called the "child
-process". The new child can itself become a parent by creating yet
-another process. If a parent process creates more than one child
-process, the children are called "siblings" with respect to each
-other. If the parent/child relationship of all processes in the
-system is examined, a hierarchical lineage becomes evident. In
-fact, this hierarchy is a tree structure that resembles a family
-tree. The "family" concept makes it easy to describe relationships
-between processes, and so it is used extensively in descriptions of
-OS-9's multiprogramming operations.
-
-
-When the parent issues a fork request to OS-9, it must specify
-the following required information:
-
-
-
-A PRIMARY MODULE, which is the name of the program to be
-executed by the new process. The program can already be present
-in memory, or OS-9 may load it from a mass storage file having
-the same name (see 5.4.1).
-
-
-PARAMETERS, which is data specified by the parent to be
-passed to and used by the new process. This data is copied to
-part of the child process' memory area. Parameters are
-frequently used to pass file names, initialization values, etc.
-The shell, passes command line parameters this way (see 4.1).
-
-
-
-The new process also "inherits" copies of certain of its parent's
-properties. These are:
-
-
-
-A USER NUMBER which is used by the file security system and
-is used to identify all processes belonging to a specific user
-(this is not the same as the "process ID", which identifies a
-specific process) . This number is usually obtained from the
-system password file when a user logs on. The system manager
-always is user number zero (see 3.8).
-
-
-STANDARD INPUT AND OUTPUT PATHS: the three paths (input,
-output, and error/status) used for routine input and output.
-Note that most paths (files) may be shared simultaneously by
-two or more processes (see 4.2.2). The two current working
-directories are also inherited.
-
-
-PROCESS PRIORITY which determines what proportion of CPU
-time the process receives with respect to others (see 5.1).
-
-
-
-As part of the fork operation, OS-9 automatically assigns:
-
-
-
-A PROCESS ID: a number from 1 to 255, which is used to
-identify specific processes. Each process has a unique process
-ID number (see 4.3.2).
-
-
-MEMORY: enough memory required for the new process to run.
-Level Two systems give each process a unique "address space".
-In Level One systems, all processes share the single address
-space. A "data area", used for the program's parameters,
-variables, and stack is allocated for the process' exclusive
-use. A second memory area may also be required to load the
-program (primary module) if it is not resident in memory (see 5.4)..
-
-
-
-To summarize, the following items are given to or associated with
-new processes:
-
-
-
-
-Primary Module (program module to be run)
-
-
-Parameter(s) passed from parent to child
-
-
-User Number
-
-
-Standard I/O paths and working directories
-
-
-Process Priority
-
-
-Process ID
-
-
-Memory
-
-
-
-
-
-
-Basic Memory Management Functions
-
-An important OS-9 function is memory management. OS-9 automatically allocates
-all system memory to itself and to processes, and
-also keeps track of the logical contents
-of memory (meaning which
-program modules are resident in memory at any given time). The
-result is that you seldom have to be bothered with the actual memory
-addresses of programs or data.
-
-
-Within the address space, memory is assigned from higher
-addresses downward for program modules, and from lower addresses
-upward for data areas, as shown below:
-
-
- +---------------------------+ highest address
- ! program modules !
- ! (RAM or ROM) !
- ! !
- ! - - - - - - - - - - - - - !
- ! !
- ! unused space !
- ! (RAM or empty) !
- ! !
- ! - - - - - - - - - - - - - !
- ! !
- ! data areas !
- ! (RAM) !
- ! !
- +---------------------------+ lowest address (0)
-
-
-Loading Program Modules Into Memory
-
-
-When performing a fork operation, OS-9's first step is to attempt
-to locate the requested program module by searching the "module
-directory", which has the address of every module present in memory.
-The 6809 instruction set supports a type of program called
-"reentrant code" which means the exact same "copy" of a program can
-be shared by two or more different processes simultaneously without
-affecting each other, provided that each "incarnation" of the
-program has am independent memory area for its variables.
-
-
-Almost all OS-9 family software is reentrant and can make most
-efficient use of memory. For example, Basic09 requires 22K bytes of
-memory to load into. If a request to run Basic09 is made, but
-another user (process) had previously caused it to be loaded into
-memory, both processes will share the same copy, instead of causing
-another copy to be loaded (which would use an additional 22K of
-memory). OS-9 automatically keeps track of how many processes are
-using each program module and deletes the module (freeing its memory
-for other uses) when all processes using the module have terminated.
-
-
-If the requested program module is not already in memory, the
-name is used as a pathlist (file name) and an attempt is made to
-load the program from mass storage (see 3.9.4).
-
-
-Every program module has a "module header" that describes the
-program and its memory requirements. OS-9 uses this to determine
-how much memory for variable storage should be allocated to the
-process (it can be given more memory by specifying an optional
-parameter on the shell command line). The module header also
-includes other important descriptive information about the program,
-and is an essential part of OS-9 operation at the machine language
-level. A detailed description of memory modules and module headers
-can be found in the "OS-9 System Programmer's Manual".
-
-
-Programs can also be explicitly loaded into memory using the
-"load" command. As with fork, the program will actually be loaded
-only if it is not already in memory. If the module is not in
-memory, OS-9 will copy a candidate memory module from the file into
-memory, verify the CRC, and then, if the module is not already in
-the module directory, add the module to the directory. This process
-is repeated until all the modules in the file are loaded, the 64K
-memory limit is exceeded, or until a module with an invalid format
-is encountered. OS-9 always links to the first module read from the
-file.
-
-
-If the program module is already in memory,
-the load will proceed
-as described above, loading the module from the specified file,
-verifying the CRC, and when attempting to add the valid module to
-the module directory, noticing that the module is already known, the
-load merely increments the known module's link count (the number of
-processes using the module.) The load command can be used to "lock
-a program into memory. This can be useful if the same program is to
-be used frequently because the program will be kept in memory
-continuously, instead of being loaded repeatedly.
-
-
-The opposite of "load" is the "unlink" command, which decreases a
-program module's link count by one. Recall that when this count becomes zero
-(indicating the module in no longer used by any process),
-the module is deleted, e.g., its memory is deallocated and its name
-is removed from the module directory. The "unlink" command is
-generally used in conjunction with the "load" command (programs
-loaded by fork are automatically unlinked when the program
-terminates).
-
-
-Here is an example of the use of
-"load" and "unlink" to lock a
-program in memory. Suppose the "copy" command will be used five
-times. Normally, the copy command would be loaded each time the
-"copy" command is called. If the "load" command is used first,
-"copy" will be locked into memory first, for example:
-
-
-OS9: load copy
-OS9: copy file1 file1a
-OS9: copy file2 file2a
-OS9: copy file3 file3a
-OS9: unlink copy
-
-
-It is important to use the "unlink" command after the program is no
-longer needed, or the program will continue to occupy memory which
-otherwise could be used for other purposes. Be very careful
-not to
-completely unlink modules in use by any process! This will cause the
-memory used by the module to be deallocated and its contents
-destroyed. This will certainly cause all programs using the
-unlinked module to crash.
-
-
-
-
-Loading Multiple Programs
-
-
-Another important aspect of program loading is the ability to
-have two or more programs resident in memory at the same time. This
-is possible because all OS-9 program modules are "position-independent
-code", or "PIC". PIC programs do not have to be loaded into
-specific, predetermined memory addresses to work correctly, and can
-therefore be loaded at different memory addresses at different
-times. PIC programs require special types of machine language instructions
-which few computers have. The ability of the 6809
-microprocessor to use this type of program is one of its most
-powerful features.
-
-
-The "load" command can therefore be used two or more times (or a
-single file may contain several memory modules, see 3.9.4), and each
-program module will be automatically loaded at different,
-non-overlapping addresses (most other operating systems write over the
-previous program's memory whenever a new program is loaded). This
-technique also relieves the user from having to be directly concerned with
-absolute memory addresses. Any number of program modules
-can be loaded until available system memory is full.
-
-
-
-
-Memory Fragmentation
-
-
-Even though PIC programs can be initially loaded at any address
-where free memory is available, program modules cannot be relocated
-dynamically afterwards, e.g., once a program is loaded it must
-remain at the address at which it was originally loaded (however
-Level Two systems can "load" (map) memory resident programs at
-different addresses in each process' address space). This characteristic
-can lead to a sometimes troublesome phenomenon called
-"memory fragmentation". When programs are loaded, they are assigned
-the first sufficiently large block of memory at the highest address
-possible in the address space. If a number of program modules are
-loaded, and subsequently one or more modules which are located in
-between other modules are "unlinked", several fragments of free
-memory space will exist. The sum of the sizes of the free memory
-space may be quite large, but because they are scattered, not enough
-space will exist in a single block to load a program module larger
-than the largest free space.
-
-
-The "mfree" command shows the location and size of each unused
-memory area and the "mdir e" command shows the address, size, and
-link (use) count of each module in the address space. These
-commands can be used to detect fragmentation. Memory can usually be
-de-fragmemted by unlinking scattered modules and reloading them.
-Make certain none are in use before doing so.
-
-
-
-
-
-
-
-
-Use of the System Disk
-
-Disk-based OS-9 systems use a system disk to load many parts of
-the operating system during the system startup and to provide files
-frequently used during normal system operations. Therefore, the
-system disk is generally kept in disk drive zero ("/D0") when the
-system is running.
-
-
-Two files used during the system startup operation, "OS9Boot" and
-"startup" must
-reside in the system disk's root directory. Other
-files are organized into three directories: CMDS (commands), DEFS
-(system-wide definitions), and SYS (other system files). Other files
-and directories created by the system manager and/or users may also
-reside on the system disk. These frequently include each user s
-initial data directory.
-
-
-
-The OS9BOOT File
-
-
-The file called "OS9Boot" loaded into RAM memory by the
-"bootstrap" routine located in the OS-9 firmware. It includes file
-managers, device drivers and descriptors, and any other modules
-which are permanently resident in memory. A typical Microware OS-9
-distribution disk's "OS9Boot" file contains the following modules:
-
-
-
-
-
-
-
- IOMAN
- OS-9 Input/Output Manager
-
-
- RBF
- Random Block (disk) File Manager
-
-
- SCF
- Sequential Character (terminal) File Manager
-
-
- Pipeman
- Pipeline File Manager
-
-
- Piper
- Pipeline Driver
-
-
- Pipe
- Pipeline Device Descriptor
-
-
- KBDVID
- Keyboard/video/Graphics Device Driver
-
-
- PRINTER
- Printer Device Driver
-
-
- DDISK
- Disk Driver
-
-
- D0, D1
- Disk Device Descriptor
-
-
- TERM
- Terminal Device Descriptor
-
-
- P
- Printer Device Descriptor
-
-
- CLOCK
- Real-Time Clock Module
-
-
- SYSGO
- System Startup Process
-
-
-
-
-
-
-Users may create new bootstrap files which may include additional
-modules (see "OS9Gen" command). Any module loaded as part of the
-bootstrap cannot be unlinked and is stored in memory with a minimum
-of fragmentation. It may be advantageous to include in the OS9Boot
-file any module used constantly during normal system operation.
-This can be done with the OS9GEN command.
-
-
-
-
-The SYS Directory
-
-
-The directory "/d0/SYS" contains two important files:
-
-
-
-
-
-
-
-password
-the system password file (see "login" command)
-
-
-errmsg
-the error message file (see 4.7)
-
-
-
-
-
-These files (and the SYS directory itself) are not absolutely
-required to boot OS-9, they are needed if "login", "tsmon", or
-"printerr" will be used. Users may add other system-wide files of
-similar nature if desired.
-
-
-
-
-The Startup File
-
-
-The file "/d0/startup" is a shell procedure file (see 4.6) which
-is automatically processed immediately after system startup. The
-user may include in "startup" any legal shell command line. Often
-this will include "setime" to start the system clock. If this file
-is not present the system will still start correctly but the user
-must run the SETIME command manually.
-
-
-
-
-The CMDS Directory
-
-
-The directory "/d0/CMDS" is the system-wide command object code
-directory, which is normally shared by all users as their working
-execution directory (see 3.7). If "shell" is not part of the
-"OS9Boot" file, it must be present in this directory. The system
-startup process "sysgo" makes CMDS the initial execution directory.
-
-
-
-
-The DEFS Directory
-
-
-The directory "/d0/DEFS" is a directory that contains assembly
-language source code files which contain common system-wide symbolic
-definitions, and are normally included in assembly language programs
-by means of the OS-9 Assembler "use" directive. The presence and
-use of this directory is optional, but highly recommended for any
-system used for assembly language programs. The files commonly
-contained in this directory are:
-
-
-
-
-
-
-
-OS9Defs
-main system-wide definition file
-
-
-RBFDefs
-RBF file manager definition file
-
-
-SCFDefs
-SCF file manager definition file
-
-
-Systype
-System types definition file
-
-
-
-
-
-
-
-
-Changing System Disks
-
-
-The system disk is not usually removed while the system is running, especially
-on multiuser systems. If it is, the "chx" and
-"chd" (if the working data directory was on the system disk)
-commands should be executed to reset the working directory pointers
-because the directories may be at different addresses on the new
-disk, for example:
-
-
-
-chx /d0/cmds
-chd /d0
-
-
-
-In general, it is unwise to remove a disk and replace it with
-another if any paths are open to files resident on the disk. It is
-dangerous to exchange any
-disk if any files on it are open in WRITE or UPDATE modes.
-
-
-
-
-
-
-Making New System Disks
-
-
-To make a system disk, the following steps must be performed:
-
-
-
-The new disk must be formatted.
-
-
-
-The "OS9Boot" file must be created and linked by the "OS9Gen" or
-"Cobbler" commands.
-
-
-
-The "startup" file must be created or copied.
-
-
-
-The CMDS and SYS directories and the files they contain must be
-copied.
-
-
-
-Steps 2 through 4 may be performed manually, or automatically by any
-of the following methods:
-
-
-By a shell procedure file created by the user.
-
-
-
-By a shell procedure file generated by the "dsave" command
-
-
-
-By the "backup" command
-
-
-
-
-
-
-
-System Command Descriptions
-
-This section contains descriptions for each of the command
-programs that are supplied with OS-9. These programs are usually
-called using the shell, but can be called from most other OS-9
-family programs such as BASIC09, Interactive Debugger, Macro Text
-Editor, etc. Unless otherwise noted, these programs are designed to
-run as individual processes.
-
-
-WARNING
-- ALTHOUGH MANY OS-9 COMMANDS MAY WORK ON LEVEL ONE OR LEVEL
-TWO SYSTEMS, THERE ARE DIFFERENCES. TAKE CARE NOT TO MIX COMMAND
-FILES FROM LEVEL ONE SYSTEMS ON LEVEL TWO, OR THE REVERSE.
-
-
-Formal Syntax Notation
-
-Each command description includes a syntax definition which
-describes how the command sentence can be constructed. These are
-symbolic descriptions that use the following notation:
-
-
-
-
-
-
-
-
- [ ]
- = Brackets indicate that the enclosed item(s) are optional.
-
-
- &repeatst; &repeaten;
- = Braces indicate that the enclosed item(s) can be
- either omitted or repeated multiple times.
-
-
- &replstart;path&replend;
- = Represents any legal pathlist.
-
-
- &replstart;devname&replend;
- = Represents any legal device name.
-
-
- &replstart;nodname&replend;
- = Represents any legal memory module name.
-
-
- &replstart;procID&replend;
- = Represents a process number.
-
-
- &replstart;opts&replend;
- = One or more options defined in the command description.
-
-
- &replstart;arglist&replend;
- = a list of arguments (parameters).
-
-
- &replstart;text&replend;
- = a character string terminated by end-of-line.
-
-
-
-
-
-
-NOTE: The syntax of the commands given does not include the shell's
-built in options such as alternate memory size, I/O redirection,
-etc. This is because the shell will filter its options out of the
-command line before it is passed to the program being called.
-
-
-
-
-Commands
-
-&attrref;
-&backupref;
-&binexref;
-&buildref;
-&chdref;
-&cmpref;
-&cobblerref;
-©ref;
-&dateref;
-&dcheckref;
-&delref;
-&deldirref;
-&dirref;
-&displayref;
-&dsaveref;
-&dumpref;
-&echoref;
-&exref;
-&formatref;
-&freeref;
-&identref;
-&killref;
-&linkref;
-&listref;
-&loadref;
-&loginref;
-&makdirref;
-&mdirref;
-&mergeref;
-&mfreeref;
-&os9genref;
-&printerrref;
-&procsref;
-&pwdref;
-&renameref;
-&saveref;
-&setimeref;
-&setprref;
-&shellref;
-&sleepref;
-&teeref;
-&tmoderef;
-&tsmonref;
-&unlinkref;
-&verifyref;
-&xmoderef;
-
-
-
-
-
-Command Summary
-
-
-
-
-
-
-
-ATTRChange File Attributes7-2
-
-
-BACKUPMake Disk Backup7-3
-
-
-BINEXConvert Binary to S-Record7-5
-
-
-BUILDBuild Text File7-6
-
-
-CHDChange Working Data Directory7-7
-
-
-CHXChange Working Execution Directory7-7
-
-
-CMPFile Comparison Utility7-8
-
-
-COBBLERMake Bootstrap File7-9
-
-
-COPYCopy Data7-10
-
-
-DATEDisplay System Date and Time7-11
-
-
-DCHECKCheck Disk File Structure7-12
-
-
-DELDelete a File7-16
-
-
-DELDIRDelete All Files in a Directory System7-17
-
-
-DIRDisplay File Names in a Directory7-18
-
-
-DISPLAYDisplay Converted Characters7-19
-
-
-DSAVEGenerate Procedure File to Copy Files7-20
-
-
-DUMPFormatted File Dump7-21
-
-
-ECHOEcho Text to Output Path7-22
-
-
-EXExecute Program as Overlay7-23
-
-
-EXBINConvert S-Record To Binary7-5
-
-
-FORMATInitialize Disk Media7-24
-
-
-FREEDisplay Free Space on Device7-25
-
-
-IDENTPrint OS-9 module identification7-26
-
-
-KILLAbort a Process7-28
-
-
-LINKLink Module Into Memory7-29
-
-
-LISTList Contents of- Disk File7-30
-
-
-LOADLoad Module(s) Into Memory7-31
-
-
-LOGINTimesharing System Log-In7-32
-
-
-MAKDIRCreate Directory File7-34
-
-
-MDIRDisplay Module Directory7-35
-
-
-MERGECopy and Combine Files7-36
-
-
-MFREEDisplay Free System RAM Memory7-37
-
-
-OS9GENBuild and Link a Bootstrap File7-38
-
-
-PRINTERRPrint Full Text Error Messages7-40
-
-
-PROCSDisplay Processes7-41
-
-
-PWDPrint Working Directory7-42
-
-
-PXDPrint Execution Directory7-42
-
-
-RENAMEChange File Name7-43
-
-
-SAVESave Memory Module(s) on a File7-44
-
-
-SETIMEActivate and Set System Clock7-45
-
-
-SETPRSet Process Priority7-46
-
-
-SLEEPSuspend Process for Period of Time7-47
-
-
-SHELLOS-9 Command Interpreter7-48
-
-
-TEECopy Standard Input to Multiple Output Paths7-50
-
-
-TMODEChange Terminal Operating Mode7-51
-
-
-TSMONTimesharing Monitor7-54
-
-
-UNLINKUnlink Memory Module7-55
-
-
-VERIFYVerify or Update Module Header and CRC7-56
-
-
-XMODEExamine or Change Device Initialization Mode7-57
-
-
-
-
-
-
-
-OS-9 Error Codes
-
-The error codes are shown in both hexadecimal (first column) and
-decimal (second column). Error codes other than those listed are
-generated by programming languages or user programs.
-
-
-
-
-
-
-
-
-
-HEX
-DEC
-
-
-
-
-
- $C8
- 200
- PATH TABLE FULL - The file cannot be opened because
- the system path table is currently full.
-
- $C9
- 201
- ILLEGAL PATH NUMBER - Number too large or for non-existant path.
-
- $CA
- 202
- INTERRUPT POLLING TABLE FULL
-
- $CB
- 203
- ILLEGAL MODE - attempt to perform I/O function of which the device or file is incapable.
-
- $CC
- 204
- DEVICE TABLE FULL - Can't add another device
-
- $CD
- 205
- ILLEGAL MODULE HEADER - module not loaded because its
- sync code, header parity, or CRC is incorrect.
-
- $CE
- 206
- MODULE DIRECTORY FULL - Can't add another module
-
- $CF
- 207
- MEMORY FULL - Level One: not enough contiquous RAM free.
- Level Two: process address space full
-
- $D0
- 208
- ILLEGAL SERVICE REQUEST - System call had an illegal code number.
-
- $D1
- 209
- MODULE BUSY - non-sharable module is in use by another process.
-
- $D2
- 210
- BOUNDARY ERROR - Memory allocation or deallocation request not on a page boundary.
-
- $D3
- 211
- END OF FILE - End of file encountered on read.
-
- $D4
- 212
- RETURNING NON-ALLOCATED MEMORY -
-attempted to deallocate memory not previously assigned.
-
- $D5
- 213
- NON-EXISTING SEGMENT - device has damaged file structure.
-
- $D6
- 214
- NO PERMISSION - file attributes do not permit access requested.
-
- $D7
- 215
- BAD PATH NAME - syntax error in pathlist (illegal character, etc.).
-
- $D8
- 216
- PATH NAME NOT FOUND - can't find pathlist specified.
-
- $D9
- 217
- SEGMENT LIST FULL - file is too fragmented to be expanded further.
-
- $DA
- 218
- FILE ALREADY EXISTS - file name already appears in current directory.
-
- $DB
- 219
- ILLEGAL BLOCK ADDRESS - device's file structure has been damaged.
-
- $DC
- 220
- ILLEGAL BLOCK SIZE - device's file structure has been damaged.
-
- $DD
- 221
- MODULE NOT FOUND - request for link to module not found in directory.
-
- $DE
- 222
- SECTOR OUT OF RANGE - device file structure damaged or
-incorrectly formatted.
-
- $DF
- 223
- SUICIDE ATTEMPT - request to return memory where your stack is located.
-
- $E0
- 224
- ILLEGAL PROCESS NUMBER - no such process exists.
-
- $E2
- 226
- NO CHILDREN - can't wait because process has no children.
-
- $E3
- 227
- ILLEGAL SWI CODE - must be 1 to 3.
-
- $E4
- 228
- PROCESS ABORTED - process aborted by signal code 2.
-
- $E5
- 229
- PROCESS TABLE FULL - can't fork now.
-
- $E6
- 230
- ILLEGAL PARAMETER AREA - high and low bounds passed in fork call are incorrect.
-
- $E7
- 231
- KNOWN MODULE - for internal use only.
-
- $E8
- 232
- INCORRECT MODULE CRC - module has bad CRC value.
-
- $E9
- 233
- SIGNAL ERROR - receiving process has previous
-unprocessed signal pending.
-
- $EA
- 234
- NON-EXISTENT MODULE - unable to locate module.
-
- $EB
- 235
- BAD NAME - illegal name syntax
-
- $EC
- 236
- BAD HEADER - module header parity incorrect
-
- $ED
- 237
- RAM FULL - no free system RAM available at this time
-
- $EE
- 238
- UNKNOWN PROCESS ID - incorrect process ID number
-
- $EF
- 239
- NO TASK NUMBER AVAILABLE - all task numbers in use
-
-
-
-
-
-
-Device Driver Errors
-
-The following error codes are generated by I/O device drivers, and
-are somewhat hardware dependent. Consult manufacturer's hardware
-manual for more details.
-
-
-
-
-
-
-
-
-
- $F0
- 240
- UNIT ERROR - device unit does not exist.
-
- $F1
- 241
- SECTOR ERROR - sector number is out of range.
-
- $F2
- 242
- WRITE PROTECT - device is write protected.
-
- $F3
- 243
- CRC ERROR - CRC error on read or write verify.
-
- $F4
- 244
- READ ERROR - Data transfer error during disk read
- operation, or SCF (terminal) input buffer overrun.
-
- $F5
- 245
- WRITE ERROR - hardware error during disk write operation.
-
- $F6
- 246
- NOT READY - device has "not ready" status.
-
- $F7
- 247
- SEEK ERROR - physical seek to non-existant sector.
-
- $F8
- 248
- MEDIA FULL - insufficient free space on media.
-
- $F9
- 249
- WRONG TYPE - attempt to read incompatible media (i.e.
- attempt to read double-side disk on single-side drive)
-
- $FA
- 250
- DEVICE BUSY - non-sharable device is in use
-
- $FB
- 251
- DISK ID CHANGE - Media was changed with files open
-
- $FC
- 252
- RECORD IS LOCKED-OUT - Another process is accessing the
-requested record.
-
- $FD
- 253
- NON-SHARABLE FILE BUSY - Another process is accessing the
-requested file.
-
-
-
-
-
-
-
-Display System Functions
-
-
-The Video Display
-
-Dragon Data OS-9 allows the video display to be used in
-alphanumeric, semigraphic, and graphics modes. There are many
-built-in functions to control the display, which are activated by
-used of various ASCII control character. Thus, these functions are
-available for use by software written in any language using standard
-output statements (such as "PRINT" in BASIC). The Dragon's Basic09
-language has a Graphics Interface Module that can automatically
-generate these codes using Basic09 RUN statements.
-
-
-The display system has two display modes: Alphanumeric
-("Alpha") mode and Graphics mode. The Alphanumeric mode also
-includes "semigraphic" box-graphics. The Dragon Computer's display
-system uses a separate - memory area for each display mode so
-operations on the Alpha display do not affect the Graphics display,
-and visa-versa. Either display can be selected under software
-control.
-
-
-8-bit characters sent to the display system are interpreted
-according to their numerical value, as shown in the chart below.
-
-
-
-
-
-
-
-
-Character Range (Hex)
-Mode/Used For
-
-
-
-
-00 - 0E
-Alpha Mode - cursor and screen control
-
-
-0F - 1B
-Graphics Mode - drawing and screen control
-
-
-1C - 20
-Not used
-
-
-20 - SF
-Alpha Mode - upper case characters
-
-
-60 - 7F
-Alpha Mode - lower case characters
-
-
-80 - FF
-Alpha Mode - Semigraphic patterns
-
-
-
-
-
-
-
-The graphics and alphanumeric functions are handled by the OS-9
-device driver module called "CCIO".
-
-
-
-Alpha Mode Display
-
-This is the "standard" operational mode. It is used to display
-alphanumeric characters and semigraphic box graphics, and simulates
-the operation of a typical computer terminal with functions for
-scrolling, cursor positioning, clear screen, line delete, etc.
-
-
-Each 8-bit character is assumed to be an ASCII character and is
-displayed if its high order bit (sign bit) is cleared. Lower case
-letters are displayed in reverse video. If the high order bit of
-the character is set it is assumed to be a "Semigraphic 6" graphics
-box. See the Dragon manual for an explanation of semigraphics
-functions.
-
-
-
-Alpha Mode Command Codes
-
-
-
-
-
-Control Code
-Name/Function
-
-
-
-
-01
-HOME - return cursor to upper left hand corner of screen
-
-
-02
-CURSOR XY - move cursor to character X of line Y. The
-binary value minus 32 of the two characters following
-the control character are used as the X and Y
-coordinates. For example, to position the cursor at character 5 of line 10,
-you must give X=37 and Y42
-
-
-03
-ERASE LINE - erases all characters on the cursor's line.
-
-
-06
-CURSOR RIGHT - move cursor right one character position
-
-
-08
-CURSOR LEFT - move cursor left one character position
-
-
-09
-CURSOR UP - move cursor up one line
-
-
-10
-CURSOR DOWN (linefeed) move cursor down one line
-
-
-12
-CLEAR SCREEN - erase entire screen and home cursor
-
-
-13
-RETURN - return cursor to leftmost character of line
-
-
-
-14
-DISPLAY ALPHA - switch screen from graphic mode to alpha
-numeric mode
-
-
-
-
-
-
-
-Graphics Mode Display
-
-This mode is used to display high-resolution 2- or 4-color
-graphics, and it includes commands to: set color; plot and erase
-individual points; draw and erase lines; position the graphics
-cursor; and draw circles.
-
-
-The DISPLAY GRAPHICS command must be executed before any other
-graphics mode command is used. It causes the graphics screen to be
-displayed and sets a current display format and color. The Li.u.t
-time the DISPLAY GRAPHICS command is given, a 6144 byte display
-memory is allocated by OS-9, so there must be at least this much
-continuous free memory available (the OS-9 "MFREE" command can be
-used to check free memory). This memory is retained until the END
-GRAPHICS command is given, even if the program that initiated
-Graphics mode finishes, so it important that the END GRAPHICS
-command be used to give up the display memory when Graphics mode is
-no longer needed.
-
-
-Graphics mode supports two basic formats: Two-Color which has
-256 horizontal by 192 vertical points (G6R mode); and Four Color
-which has 128 horizontal by 192 vertical points (G6C mode). Two
-color sets are available in either mode. Regardless of the
-resolution of the format selected, all Graphics mode commands use a
-256 by 192 point coordinate system. The X and Y coordinates are
-always positive numbers which assume that point 0,0 is the lower
-lefthand corner of the screen.
-
-
-An invisible Graphics Cursor is used by many command to reduce
-the amount of output required to generate graphics. This cursor can
-be explicitly set to any point using the SET GRAPHICS CURSOR
-command. Also, all other commands that include X,Y coordinates
-(such as SET POINT) move the graphics cursor to the specified
-position.
-
-
-Graphics Mode Selection Codes
-
-
-
-
-
-Code
-Format
-
-
-
-
-00
-256 x 192 two-color graphics
-
-
-01
-128 x 192 four-color graphics
-
-
-
-
-
-
-
- Color Set and Current Foreground Color Selection Codes
-
-
-
-
-
-
-
-
-
-Two Color Format
-Four Color Format
-
-
-Char
-Background
-Foreground
-Background
-Foreground
-
-
-
-
-Color Set 1
-00
-Black
-Black
-Green
-Green
-
-
-01
-Black
-Green
-Green
-Yellow
-
-
-02
-Green
-Blue
-
-
-03
-Green
-Red
-
-
-Color Set 2
-04
-Black
-Black
-Buff
-Buff
-
-
-05
-Black
-Buff
-Buff
-Cyan
-
-
-06
-Buff
-Magenta
-
-
-07
-Buff
-Orange
-
-
-Color Set 3*
-08
-Black
-Black
-
-
-09
-Black
-Dark Green
-
-
-10
-Black
-Med. Green
-
-
-11
-Black
-Light Green
-
-
-Color Set 4*
-12
-Black
-Black
-
-
-13
-Black
-Green
-
-
-14
-Black
-Red
-
-
-15
-Black
-Buff
-
-
-
-
-
-
-* Color sets 3 and 4 not available on PAL video system (European)
-models. These color sets work only with NTSC (U.S., Canada, Japan)
-models.
-
-
-
- Graphics Mode Control Commands
-
-
-
-
-
-Control Code
-Name/Function
-
-
-
-
-15
-DISPLAY GRAPHICS - switches screen to graphics mode.
-This command must be given before any other
-graphics commands are used. The first time this command
-is given, a 6K byte display buffer is assigned. If 6K of
-contiguous memory is not available an error is returned.
-This command is followed by two characters which specify
-the graphics mode and current color/color set, respectively.
-
-
-16
-PRESET SCREEN - presets entire screen to color code
-passed in next character.
-
-
-17
-SET COLOR - selects foreground color (and color set)
-passed in next character, but does not change graphics
-mode.
-
-
-18
-QUIT GRAPHICS - disables graphics mode and returns the
-6K byte graphics memory area to OS-9 for other use, and
-switches to alpha mode.
-
-
-19
-ERASE GRAPHICS - erases all points to background color
-and homes graphics cursor to the desired position.
-
-
-20
-HOME GRAPHICS CURSOR - moves graphics cursor to coordinates
-0,0 (lower left hand corner).
-
-
-21
-SET GRAPHICS CURSOR - moves graphics cursor to given
-coordinates X,Y. The binary value of the two characters that immediately
-follow are used as the X and Y values, respectively.
-
-
-22
-DRAW LINE - draws a line of the current foreground
-color from the current graphics cursor position to the
-given X,Y coordinates. The binary value of the two
-characters that immediately follow are used as the X
-and Y values, respectively. The graphics cursor is
-moved to the end point of the line.
-
-
-23
-ERASE LINE - same as DRAW LINE except the line is
-"drawn" in the current background color, thus erasing
-the line.
-
-
-24
-SET POINT - sets the pixel-at point X,Y to the current
-foreground color. The binary value of the two
-characters that immediately follow are used as the x
-and Y values, respectively. The graphics cursor is
-moved to the point Set.
-
-
-25
-ERASE POINT - same as DRAW POINT except the point is
-"drawn" in the current background color, thus erasing
-the point.
-
-
-26
-DRAW CIRCLE - draws a circle of the current foreground
-color with its center at the current graphics cursor
-position using a radius R which is obtained using the
-binary value of the next character. The graphics
-cursor position is not affected by this command.
-
-
-
-
-
-
-
-Get Status Commands
-
-The Dragon Computer I/O driver includes OS-9 Get Status
-commands that return the display status and joystick values,
-respectively. These are accessable via the Basic09 Graphics
-Interface Module, or by the assembly language system calls listed
-below:
-
-
-GET DISPLAY STATUS:
-
-
-
-
-
-
-
-Calling Format
-lda #1 (path number)
-ldb #SS.DStat (Getstat code $12)
-os9 I$GSTT call OS-9
-
-
-Passed
-nothing
-
-
-Returns
-X = address of graphics display memory
-Y = graphics cursor address x=MSB y =LSB
-A = color code of pixel at cursor address
-
-
-
-
-
-GET JOYSTICK VALUES:
-
-
-
-
-
-
-
-Calling Format
-lda #1 (path number)
-ldb #SS.Joy (Getstat code $13)
-os9 I$GSTT call OS-9
-
-
-Passed
-X = 0 for right joystick; 1 for left joystick
-
-
-Returns
-X = selected joystick x value (0-63)
-Y = selected joystick y value (0-63)
-A = $FF if fire button on; $00 if off
-
-
-
-
-
-
-Display Control Codes Condensed Summary
-
-
-
-
-
-
-
-1st Byte
-2nd Byte
-3rd Byte
-Function
-
-
-
-
-00
-
-
-Null
-
-
-01
-
-
-Home Alpha Cursor
-
-
-02
-Column+32
-Row+32
-Position Alpha Cursor
-
-
-03
-
-
-Erase Line
-
-
-06
-
-
-Cursor Right
-
-
-08
-
-
-Cursor Left
-
-
-09
-
-
-Cursor Up
-
-
-10
-
-
-Cursor Down
-
-
-12
-
-
-Clear Screen
-
-
-13
-
-
-Carriage Return
-
-
-14
-
-
-Select Alpha Mode
-
-
-15
-Mode
-Color Code
-Select Graphics Mode
-
-
-16
-Color Code
-
-Preset Screen
-
-
-17
-Color Code
-
-Select Color
-
-
-18
-
-Quit Graphics Mode
-
-
-19
-
-Erase Screen
-
-
-20
-
-Home Graphics Cursor
-
-
-21
-X Coord
-Y Coord
-Move Graphics Cursor
-
-
-22
-X Coord
-Y Coord
-Draw Line to X/Y
-
-
-23
-X Coord
-Y Coord
-Erase Line to X/Y
-
-
-24
-X Coord
-Y Coord
-Set Point at X/Y
-
-
-25
-X Coord
-Y Coord
-Clear Point at X/Y
-
-
-26
-Radius
-
-Draw Circle
-
-
-
-
-
-
-
-
-
-
-Key Definitions With Hexadecimal Values
-
-NORM SHFT CTRL NORM SHFT CTRL NORM SHFT CTRL
----- ---- ------ ---- ---- ------ ---- ---- ------
-0 30 0 30 -- @ 40 ' 60 NUL 00 P 50 p 70 DLE 10
-1 31 1 21 | 7C A 41 a 61 SOH 01 Q 51 q 71 DC1 11
-2 32 " 22 00 B 42 b 62 STX 02 R 52 r 72 DC2 12
-3 33 # 23 - 7E C 43 c 63 ETX O3 S 53 s 73 DC3 13
-4 34 $ 24 00 0 44 d 64 EOT 04 T 54 t 74 DC4 14
-5 35 % 25 00 E 45 e 65 END O5 U 55 u 75 NAK 15
-6 36 & 26 00 F 46 f 66 ACK 06 V 56 V 76 SYN 16
-7 37 ' 27 5E G 47 g 67 BEL O7 W 57 w 77 ETB 17
-8 38 ( 28 [ 5B H 48 h 68 BSP 08 X 58 x 78 CAN 18
-9 39 ) 29 ] 5D I 49 i 69 HT O9 Y 59 y 79 EM 19
-: 3A * 2A 00 J 4A j 6A LF CA Z 5A z 7A SUM 1A
-; 3B + 2B 00 K 4B k 6B VT OB
-, 2C < 3C { 7B L 4C l 6C FF 0C
-- 2D = 3D - 5F M 4D m 6D CR 00
-. 2E > 3E } 7D N 4E n 6E CO CE
-/ 2F ? 3F \ 5C O 4F o 6F CI OF
-
-
- FUNCTION KEYS
-
- NORM SHFT CTRL
- ---- ---- ----
- BREAK 05 03 1B
- ENTER 0D 0D 0D
- SPACE 20 20 20
- <- 08 18 10
- -> 09 19 11
- v 0A 1A 12
- ^ 0C 1C 13
-
-
-
-
-GO51...The 51 Column by 24 Line Video Display
-
-An alternative video screen device driver, which provides a 51
-column by 24 line display with upper and lower case character sets,
-can be incorporated into OS-9 with the command:
-
-GO51
-
-This command replaces the normal text screen driver with one that
-uses high resolution graphics to "draw" the characters. As there
-are fever pixels (dots) per character in this mode more characters
-can be displayed on the screen, albeit with some loss of character
-definition.
-
-
-Note, however, that the use of a high resolution graphics page
-means that an extra 6K bytes will be needed in this mode. This
-extra memory requirement is not normally a problem but in memory-critical
-applications, such as the C and Pascal compilers, the user
-can simply avoid the use of GO51.
-
-
-This mode of display has a set of escape sequences
-(commands) to
-emulate commercial data terminals. In addition to the video screen
-driver, GO51 provides a new keyboard driver which features auto-repeat.
-The keyboard code allocation is the same as described in
-section 2.4.3 and Appendix D.
-
-
-The GO51 Display Functions
-
-Like the normal 32 by 16 video display functions described in
-Appendix C the 51 by 24 mode provides many built in facilities to
-control the display. These functions are activated by the use of
-the various escape sequences and control characters described below:
-
-
-
-
-
-
-
-Escape Sequence (Hex)
-Name/Function
-
-
-
-
-
-1B 41 X Y
-CURSOR XY - move cursor to column X(0-50)
-and Y(0-23) where X and Y are single byte values.
-
-
-1B 42
-CLEAR EOL - clear from cursor to the end of
-line. Cursor position remains unchanged.
-
-
-1B 43
-CURSOR RIGHT - move cursor right by one character position.
-
-
-1B 44
-CURSOR UP - move cursor up by one line.
-
-
-1B 45
-CURSOR DOWN - move cursor down one line.
-
-
-1B 46
-REVERSE ON - turn reverse field on.
-
-
-1B 47
-REVERSE OFF - turn reverse field off.
-
-
-1B 48
-UNDERLINE ON - turn underline on.
-
-
-1B 49
-UNDERLINE OFF - turn underline off.
-
-
-1B 4A
-CLEAR EOS - clear from cursor to end of
-screen. Cursor position remains unchanged.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Control Character (Hex)
-Name/Function
-
-
-
-
-07
-BELL - generates a short audible tone.
-
-
-08
-BACKSPACE (CURSOR LEFT) - moves cursor left one character position.
-
-
-0A
-LINE FEED - move cursor down by one line.
-
-
-0B
-CURSOR HOME - move cursor to home position 0,0 (top left).
-
-
-0C
-CLEAR SCREEN - clears the screen and home cursor.
-
-
-
-
-
-
-
-
-
-
-Using the Serial Interface
-
-For those who wish to use the serial port, the input or
-output path of a program may be redirected to the serial port of
-your Dragon computer.
-
-
-This is done by including the following module in the OS-9 kernel:
-
-
-ACIA51 - Serial Device Driver
-
-
-To load this module into the kernel enter the following command line:
-
-
-LOAD /D0/CMDS/ACIA51
-
-
-
-Serial Printer Implementation
-
-For those with a serial printer, you can use the serial port
-in the redirection of a program's output path by including the
-following modifier at the end of a command line:
-
-
->/P1
-
-
-The baud rate of the serial port may be changed as follows:
-
-
-XMODE /P1 BAUD=3
-
-
-This will change the baud rate to 1200 characters per second.
-For a detailed description of the baud rate see the XMODE
-command description.
-
-
-
-Serial Terminal Implementation
-
-For those who wish to connect two Dragon computers, running
-OS-9, together using the serial port, redirection of the input
-or output paths is possible using the following modifier at
-the end of a command line:
-
-
->/T1 - for an output path
-
-
-</T1 - for an input path
-
-
-To pass a file of data between the two computers, one must be
-configured for input from the serial port and the other
-configured for output:
-
-
-Computer 1, BUILD TEXT </T1 - input to port
-
-
-Computer 2, BUILD <TEXT /T1 - output to port
-
-
-Using the above example, the text file on computer 2 will be
-transferred to a file called TEXT on computer 1.
-
-
-When the command line is entered on computer 1, the system will
-reply with a question mark and wait for information from the
-serial port. The command line on computer 2 will send data to
-the now waiting computer 1. A string of question marks will now
-be seen, this is the number of lines sent and recieved by the
-respective computers.
-
-
-To create a log-off sequence after such a transfer, use the DISPLAY
-command as follows:
-
-
-Computer 1, BUILD <TEXT /T1 ; DISPLAY 0A 0D >/T1
-
-
-
diff -r 21649cf64510 -r 4cd37950c605 docs/nitros9guide/preface-dragon.preface
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/nitros9guide/preface-dragon.preface Sun Jul 07 09:54:04 2002 +0000
@@ -0,0 +1,84 @@
+
+Welcome to OS-9!
+Introduction
+
+The heart of your Dragon Computer is an amazing device: the
+6809 microprocessor chip. This advanced microcomputer can run the
+kind of sophisticated software normally found only on much larger
+and costly computers. Because the OS-9 operating system was designed
+by the same people who designed the 6809 microcomputer, together
+they provide an extremely efficient and powerful combination.
+
+
+The foundation of a computer's software system is its
+Operating System or "OS". It is the master control
+program that interfaces all other software to the system's hardware. Some
+of the things it must do are performing input and output operations,
+coordinating memory use, and many other "housekeeping" functions. All
+other software - programming languages, applications programs, etc. -
+live in your computer's memory along with the OS and depend on it to
+communicate with you using the keyboard and display and to store and
+retrieve data on disks, etc. Because virtually all other software relies
+on the OS, your computer's performance depends on the capabilities and
+efficiency of its OS.
+
+
+
+OS-9's overall structure was based on the famous UNIX
+
+Unix is an operating system designed by Bell Telephone
+Laboratories, which is becoming widely recognized as a standard for
+mini and micro operating systems because of its versatility and
+elegant structure.
+
+
+operating system, which has been widely acclaimed as the operating
+system of the future because of its versatility, logical structure,
+and friendly user commands. The OS-9 family of advanced software is
+not only more powerful than most other microcomputer scftware - it
+is also much easier to learn and use.
+
+
+Some of the advanced OS-9 features you'll learn about in this
+book are:
+
+
+
+Friendly Unix-type
+user interface and environment
+
+Multiuser/Multitasking Real-Time Operating System
+
+Extensive support for structured, modular programming
+
+Device-independent interrupt-driven input/output system
+
+Multi-level directory file system
+
+Fast Random-Access File System
+
+Readily Expandable and Adaptable Design
+
+
+
+If you don't know what some of these thing mean yet - don't
+worry. As you explore OS-9 you'll soon learn how they enhance the
+capability of your Dragon Computer and make it so much easier to use
+in almost any application.
+
+
+OS-9 has many commands and functions - definitely more than
+you can learn in an evening! The best way to become an OS-9 expert
+is to study this manual carefully, section-by-section, taking tire
+to try out each command or function. Because many functions affect
+others, you'll find this manual extensively cross-referenced so you
+can skip ahead to help you understand a new topic. Taking the time
+to study this book will certainly increase your knowledge and
+enjoyment of OS-9.
+
+
+But if you can't wait, at least read the rest of this chapter,
+scan the command descriptions in Chapter 7, and have fun
+experimenting!
+
+