--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/nitros9guide/chap2.chapter	Sun Jul 07 09:54:04 2002 +0000
@@ -0,0 +1,405 @@
+<chapter>
+<title>Basic Interactive Functions</title>
+
+<section>
+<title>Running Commands and Basic Shell Operation</title>
+<para>
+The &quot;shell&quot; 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 &quot;OS9:&quot; prompt. This prompt indicates that
+the shell is active and awaiting a command from your keyboard. It
+makes no difference whether you use upper-case letters, lower-case
+letters, or a combination of both because OS-9 matches letters of
+either case.
+</para>
+<para>
+The command line always begins with a name of a program which can
+be:
+</para>
+
+<itemizedlist>
+<listitem><para>The name of a machine language program on disk</para></listitem>
+<listitem><para>The name of a machine language program already in memory</para></listitem>
+<listitem><para>The name of an executable program compiled by a high-level
+language such as Basic09, Pascal, Cobol, etc. (See 4.8)</para></listitem>
+<listitem><para>The name of a procedure file (See 4.6)</para></listitem>
+</itemizedlist>
+<para>
+If you're a beginner, you will almost always use the first case,
+which causes the program to be automatically loaded from the CMDS
+directory and run.
+</para>
+<para>
+When processing the command line, the shell searches for a
+program having the name specified in the following sequence:
+</para>
+
+<orderedlist  numeration="arabic">
+
+<listitem><para>- If the program named is already in memory, it is run.</para></listitem>
+
+<listitem><para>- The &quot;execution directory&quot;, usually &quot;CMDS&quot;, is searched.
+If a file having the name given is found, it is loaded and
+run (See 5.4.1).</para></listitem>
+
+<listitem><para>- The user's &quot;data directory&quot; is searched. If a file having
+the name given is found, it is processed as a &quot;procedure
+file&quot; which means that the file is assumed to contain one
+or more command lines which are processed by the shell in
+the same manner as if they had manually typed in one by one.</para></listitem>
+
+</orderedlist>
+<para>
+Mention is made above of the &quot;data directory&quot; and the &quot;execution
+directory&quot;. At all times each user is associated with two file
+directories. A more detailed explanation of directories is presented
+in section 3.3. The execution directory (usually CMDS) includes
+files which are executable programs.
+</para>
+<para>
+The name given in the command line may be optionally followed by
+one or more &quot;parameters&quot; which are passed to the program called by
+the shell.
+</para>
+<para>
+For example, in the command line:
+</para>
+<screen>
+LIST FILE1
+</screen>
+<para>
+the program name is LIST, and the parameter passed to it is FILE1.
+</para>
+<para>
+A command line may also include one or more &quot;modifiers&quot; which are
+specifications used by the shell to alter the program's standard
+input/output files or memory assignments (See 4.2).
+
+
+</para>
+<section>
+<title>Sending Output to the Printer</title>
+<para>
+Normally, most commands and programs display output on the Color
+Computer video display. The output of these programs can
+alternatively be printed by specifying output redirection on the
+command line. This is done by including the following modifier to
+at the end of any command line:
+</para>
+<screen>
+&gt;/P
+</screen>
+<para>
+The &quot;&gt;&quot; 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 &quot;/P&quot; (See 3.2). For example, to redirect the output of the
+&quot;dir&quot; command to the printer, enter:
+</para>
+<screen>
+DIR &gt;/P
+</screen>
+<para>
+The &quot;xmode&quot; command can be used to set the printer port's
+operating mode such as auto line feed, etc. For example, to examine
+the printer's current settings, type:
+</para>
+<screen>
+xmode /P
+</screen>
+<para>
+To change any of these type XMODE  followed by the new value.
+For example, to set the printer port for automatic line feeds at the
+end of every line, enter:
+</para>
+<screen>
+xmode /P lf;
+</screen>
+</section>
+</section>
+
+<section>
+<title>Shell Command Line Parameters</title>
+<para>
+Parameters are generally used to either specify file name(s) or
+to select options to be used by the program specified in the command
+line given to the shell. Parameters are separated from the command
+name and from each other by space characters (hence parameters and
+options cannot themselves include spaces). Each command program
+supplied with OS-9 has an individual description in the last section
+of this manual which describe the correct usage of the parameters of
+each command.
+</para>
+<para>
+For example, the LIST program is used to display the contents of
+a text file on your display. It is necessary to tell to the LIST
+program which file it is to be displayed, therefore, the name of the
+desired file is given as a parameter in the command line. For
+example, to list the file called startup  (the system initialization
+procedure file), you enter the command line:
+</para>
+<screen>
+LIST STARTUP
+</screen>
+<para>
+Some commands have two parameters. For example, the COPY command is
+used to make an exact copy of a file. It requires two parameters:
+The name of the file to be copied and the name of the file which is
+to be the copy, for example:
+</para>
+<screen>
+COPY STARTUP NEWSTARTUP
+</screen>
+<para>
+Other commands have parameters which select options. For example:
+</para>
+<screen>
+DIR
+</screen>
+<para>
+shows the names of the files in the user's data directory. Normally
+it simply lists the file names only, but if the &quot;E&quot;
+(for <emphasis>e</emphasis>ntire)
+option is given, it will also give complete statistics for each file
+such as the date and time created, size, security codes, etc. To do
+so enter:
+</para>
+<screen>
+DIR E
+</screen>
+<para>
+The DIR command also can accept a file name as a parameter which
+specifies a directory file other than the (default) data directory.
+For example, to list file names in the directory sys , type:
+</para>
+<screen>
+DIR SYS
+</screen>
+<para>
+It is also possible to specify both a directory name parameter and
+the e  option, such as:
+</para>
+<screen>
+DIR SYS E
+</screen>
+<para>
+giving file names and complete statistics (See example in 3.8.1).
+</para>
+</section>
+
+<section>
+<title>Some Common Command Formats</title>
+<para>
+This section is a summary of some commands commonly used by new
+or casual OS-9 users, and some common formats. Each command is
+followed by an example. Refer to the individual command
+descriptions in Section 8 for more detailed information and
+additional examples. Parameters or options shown in brackets are
+optional. Whenever a command references a directory file name, the
+file <emphasis>must</emphasis> be a directory file.
+
+<screen>
+CHD filename                               chd DATA.DIR
+</screen>
+Changes the current <emphasis>data</emphasis> working directory to
+the <emphasis>directory</emphasis> file specified.
+<screen>
+COPY filename1 filename2                   copy oldfile newfile
+</screen>
+Creates filename2  as a new file, then copies all data from
+&quot;filename1&quot; to it. &quot;filename1&quot; is not affected.
+<screen>
+DEL filename                               del oldstuff
+</screen>
+Deletes (destroys) the file specified.
+<screen>
+DIR [filename] [e] [x]                     dir myfiles e
+</screen>
+List names of files contained in a directory. If the &quot;x&quot; option is
+used the files in the current <emphasis>execution</emphasis>
+directory are listed,
+othervise, if no directory name is given, the current
+<emphasis>data</emphasis> directory will be listed.
+The &quot;e&quot; option selects the long format
+which shows detailed information about each file.
+<screen>
+FREE devicename                            free /d1
+</screen>
+Shows how much free space remains on the disk whose name is given.
+<screen>
+LIST filename                              list script
+</screen>
+Displays the (text) contents of the file on the terminal.
+<screen>
+MAKDIR filename                            makdir NEWFILES
+</screen>
+Creates a new directory file using the name given. Often followed
+by a &quot;chd&quot; command to make it the new working data directory.
+<screen>
+RENAME filename1 filename2                 rename zip zap
+</screen>
+Changes the name of filename1 to filename2.
+</para>
+</section>
+
+<section>
+<title>Using the Keyboard and Video Display</title>
+<para>
+OS-9 has many features to expand the capability of the Dragon
+keyboard and video display. The video display has screen pause,
+upper/lower case, and graphics functions. The keyboard can generate
+all ASCII characters and has a type-ahead feature that permits you
+to enter data before requested by a program (except if the disk is
+running because interrupts are temporarily disabled). Appendix C of
+this manual is a list of the characters and codes that can be
+generated from the keyboard. The keyboard/video display can be used
+as a file known by the name &quot;/TERM&quot;.
+</para>
+
+<section>
+<title>Video Display Functions</title>
+<para>
+The Dragon uses reverse video (green letters in a black box) to
+represent lower-case letters. Normally they are not used, so you
+have to turn them on if you want to use them with the command:
+</para>
+<screen>
+TMODE -UPC
+</screen>
+<para>
+The screen pause feature stops programs after 16 lines have been
+displayed. Output will continue if you hit any key. Normally this
+feature is on. It can be turned on or off with the TMODE command as
+follows:
+</para>
+<screen>
+TMODE -PAUSE              turns pause mode off
+TMODE PAUSE               turns pause mode on
+</screen>
+<para>
+The display system also has a complete set of commands to emulate
+commercial data terminals, plus a complete set of graphics commands.
+These are described in detail in Appendix D.
+</para>
+</section>
+
+<section>
+<title>Keyboard Shift and Control Functions</title>
+<para>
+Two keys are used in combination with other keys to change their
+meaning. The SHIFT KEY selects between upper case and lower case
+letters or punctuation, and the CLEAR key can be used to generate
+control characters .
+</para>
+<para>
+The keyboard has a shift lock function similar to a typewriter's,
+which is normally &quot;locked&quot;. The keyboard's shift lock may be
+reversed by depressing the control key (CLEAR) and 0 keys
+simultaneously. The shift lock only affects the letter (A-Z) keys.
+When the keyboard is locked, these keys generate upper case letters,
+and lower case only if the SHIFT key is depressed. When the
+keyboard is unlocked, the reverse is true, e.g., lower case letters
+are generated unless the SHIFT key is depressed at the same time as
+a letter key.
+</para>
+</section>
+
+<section>
+<title>Control Key Functions</title>
+<para>
+There are a number of useful control functions that can be
+generated from the keyboard. Many of these functions use &quot;control
+keys&quot; which are generated by simultaneously depressing the CLEAR key
+plus some other key. For example, to generate the character for
+CONTROL D press the CLEAR and D keys at the same time.
+</para>
+<variablelist>
+<varlistentry>
+  <term>CONTROL A</term>
+  <listitem>
+<para>
+Repeat previous input line. The last line entered will be redisplayed but
+<emphasis>not</emphasis> processed, with the cursor positioned at the end of
+the line. You may hit return to enter the line, or edit the line by
+backspacing, typing over characters to correct them, and entering
+control A again to redisplay the edited line.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>CONTROL D</term>
+  <listitem>
+<para>
+Redisplay present input on next line.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>CONTROL W</term>
+  <listitem>
+<para>
+Display Wait - This will temporarily halt output to the display so
+the screen can be read before the data scrolls off. Output is
+resumed when any other key is hit.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>CONTROL 0</term>
+  <listitem>
+<para>
+Shift lock. Reverses present shift lock state.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>BREAK KEY (or CONTROL E)</term>
+  <listitem>
+<para>
+Program abort - Stops the current running program
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>SHIFT BREAK KEY (or CONTROL C)</term>
+  <listitem>
+<para>
+Interrupt - Reactivates Shell while keeping program running as
+background task.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>CONTROL BREAK KEY (ESCAPE)</term>
+  <listitem>
+<para>
+End-of-File - This key is used to send an end-of-file to programs
+that read input from the terminal in place of a disk or tape file.
+It must be the first character on the line in order for it to be
+recognized.
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>LEFT ARROW (OR CONTROL H)</term>
+  <listitem>
+<para>
+Backspace - erase previous character
+</para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term>SHIFT LEFT ARROW (or CONTROL X)</term>
+  <listitem>
+<para>
+Line Delete - erases the entire current line.
+</para>
+  </listitem>
+</varlistentry>
+</variablelist>
+</section>
+</section>
+
+</chapter>