\chapter{OS/8 Operating Characteristics} \label{OS/8 Operating Characteristics} \section{Startup} TECO is started with the \begin{verbatim} .R TECO \end{verbatim} command. TECO is now immediately ready to accept commands. The text buffer and Q-register areas are empty. The TECO command \begin{verbatim} .TECO filespec \end{verbatim} is used to edit an already existing file. It is equivalent to \begin{verbatim} .R TECO *EBfilespec`Y`` \end{verbatim} OS/8 "remembers" the filespec as the name of the last file that has been edited. The {\tt MAKE} command \begin{verbatim} .MAKE filespec \end{verbatim} is used to create a new file. It is equivalent to \begin{verbatim} .R TECO *EWfilespec`` \end{verbatim} OS/8 "remembers" the filespec as the name of the last file that was edited. The command \begin{verbatim} .TECO filespec1=filespec2 \end{verbatim} is used to edit {\tt filespec2} into {\tt filespec1}. That is, {\tt filespec2} is opened as the input file, and {\tt filespec1} is created as the output file. It is equivalent to \begin{verbatim} .R TECO *ERfilespec2`EWfilespec1`Y`` \end{verbatim} OS/8 "remembers" the {\tt filespec1} as the name of the last file that was edited. The command \begin{verbatim} .TECO \end{verbatim} with no arguments, causes CCL to execute the command \begin{verbatim} .TECO filespec \end{verbatim} where {\tt filespec} was the file that was previously remembered as the last file to be edited. The system purposely does not remember filenames from one day to the next, but it will remember names across bootstraps. The command \begin{verbatim} .MUNG filespec \end{verbatim} executes the specified TECO program. The default extension is {\tt .TEC} . This is equivalent to the sequence: \begin{verbatim} .R TECO *ERfilespec`YHXYHKMY`` \end{verbatim} Another format of this command is \begin{verbatim} .MUNG filespec,argument \end{verbatim} which is used to pass an argument to the TECO program to control its action. This is equivalent to the sequence: \begin{verbatim} .R TECO *ERfilespec`YHXYHKIargument`MY`` \end{verbatim} The argument may be the name of a file that the TECO program is to mung, or it may be a command to the program to specify what action to take, or whatever. It is up to the TECO program to decode this argument (which is left in the text buffer) and take appropriate action. A TECO program executed via the {\tt MUNG} command must never destroy the text storage area of Q-register Y and expect to ever see the light of day again. Note the input file remains open and can provide more input to the macro. \section{Startup Conditions} \label{Startup Conditions} The initial value of the {\tt EU} flag is 0 if the CCL command {\tt SET TTY NO SCOPE} had been previously issued, and is -1 if the CCL command {\tt SET TTY SCOPE} had previously been issued. The initial value of the {\tt ET} flag is as follows: \begin{tabular}{ll} % \multicolumn{1}{Incompatible, Obsolete and System-specific Commands}{\em Bit value} & % \multicolumn{1}{Incompatible, Obsolete and System-specific Commands}{\em Initial value} \\ 1 & 0 \\ 2 & 0 (1 if terminal is a scope) \\ 4 & 0 \\ 8 & 0 \\ 16 & 0 \\ 32 & 0 \\ 64 & 0 \\ 128 & 1 (TECO's prompt sets this to 0) \\ 256 & 0 \\ 512 & 0 (1 if VT support is present) \\ 1024 & 0 (1 if VR12 support is present) \\ 2048 & 0 \\ \end{tabular} The initial value of the {\tt ED} flag is 1. \section{File Specification} The file access commands {\tt ER}, {\tt EB}, and {\tt EW} accept a file specification in the standard OS/8 format: \begin{verbatim} dev:filename.type \end{verbatim} in which {\tt dev:} is a physical device name or a user assigned logical name; if {\tt dev:} is not specified,h the default {\tt DSK:} is assumed. The filename field must be specified in the commands {\tt ER}, {\tt EB}, and {\tt EW} and be a legal OS/8 filename. The type field is a file extension and must be explicitly given if used (there is no default). Any characters after the second will be ignored, thus the filespecs {\tt FOO.TEC} and {\tt FOO.TE} are equivalent. The {\tt EB} and {\tt EW} commands do not accept the extended notation for an output file size \begin{verbatim} dev:filename.type[n] \end{verbatim} specifying an output size allocation. \section{Backup Files} The {\tt EB} command maintains one level of file backup on OS/8. The pre-edited input file name is changed to \begin{verbatim} filename.BK \end{verbatim} before the new output file is closed with the original name. Only normal file closing commands ({\tt EC}, {\tt EF}, {\tt EG}, and {\tt EX}) cause this renaming to happen. If TECO is aborted or the output file is purged by the {\tt EK} command, the input filename remains unchanged. Note only one {\tt .BK} file for a given name is kept; earlier {\tt .BK} backup files are deleted each time a new backup file is created. A good policy to follow when editing is to close the edited file frequently enough so that an unexpected incident would not cause a substantial loss of work. Files should be backed up regularly. TECO has the power to let an unsuspecting user alter a good file into a completely useless state. The {\tt SRCCOM} program can be used to verify an editing session. \section{Exit And Go} If TECO is exited via the {\tt EGstring}\escape command, the string is passed to the system as the next command to execute. This string may be any valid command or an indirect command file specification. The command may be either a {\tt KBM} or a {\tt CCL} command. This command is especially useful while running under BATCH. If TECO is exited via the {\tt EG}\escape command, then OS/8 will re-execute the last explicit compile-class command that was executed that day. The commands that are considered to be compile-class commands are: \begin{verbatim} COMPILE file LOAD file EXECUTE file LINK file MACRO file. \end{verbatim} This feature, combined with OS/8's other remembering features, minimizes the number of keystrokes necessary to do normal program development. The programmer does not have to constantly type in the name of the file he is working with. A typical debugging session would look like this: \begin{verbatim} .MAKE FOO.MAC *!type in assembly language file to be executed! *EX`` .EXECUTE FOO (get error messages) .TECO *!fix bugs! *EG`` !re-compile and execute program! (watch program work or repeat process) \end{verbatim} \section{CTRL/C} The action taken when the user types {\tt } depends on what TECO is doing. At command level {\tt } is an immediate action command. If typed as the very first character in a command string (not necessarily the first keystroke) it aborts TECO and returns to the keyboard monitor. If this was done accidentally, TECO may be restarted (at your own risk) by using ODT to branch to location 207 in your program's image. If {\tt } is typed in the middle of entering a command string, then the ?XAB error message is given and TECO reprompts with its asterisk. Note that if TECO executes {\tt } as a command from command level, TECO is aborted. If TECO executes a {\tt } command from within a macro, TECO is also aborted. If a {\tt } is typed while TECO is running, or while TECO is typing on the terminal, or while an error message is printing, then the {\tt ?XAB} error message is given and TECO reprompts with its asterisk. TECO will abort similarly, if {\tt } is typed while TECO is waiting for input because of a \caret {\tt T} command. Note that if TECO is performing I/O using non-system handlers, the non-system handler may intercept the {\tt } and abort back to the keyboard monitor. In such a case, you may attempt to re-enter TECO. However, part of your file has been lost; good luck in attempting to issue an {\tt EF} command. Manually resetting the value of {\tt Z} might recover your data. If TECO is executing commands or doing I/O, a {\tt } will stop the operation and generate the {\tt ?XAB} error message. Sometimes it is desireable for a TECO macro to detect when a {\tt } was typed. By detecting the {\tt }, the macro can exit cleanly back to command level (restore any flag values, etc.). To do this, the macro sets Bit 0 (Octal 4000, Decimal 2048) of the {\tt ET} flag. When a {\tt } is typed, TECO will automatically turn off Bit 0, but will continue execution of the macro. The macro periodically checks Bit 0 and exits cleanly if it ever goes off. If the {\tt } trap bit is on, then the \caret {\tt T} can read a {\tt } typed at the terminal. It has an ASCII value of 3. \section{File Recovery} TECO can be a useful tool in recovering ASCII files lost on a block replaceable device. TECO allows non-file-structured devices to be opened in a non-file structured mode. This gives the user the capability to open a disk and access ASCII data anywhere on it, independent of file boundaries. To do this, you must issue a command of the form \begin{verbatim} .SET dev: NOFILES \end{verbatim} to the monitor to make it think that your disk is non-file-structured. The command \begin{verbatim} ERdev:` \end{verbatim} is used to open the device at which point \_ (underscore or backarrow) searches may be used to locate specific ASCII data and transfer it to new output files. Note that files tend to get reproduced, in whole or part, many places on a block replaceable device; be sure to verify that any given text is indeed complete and the correct version. If the disk's directory has not been clobbered (or if you are willing to create a new one), then it is not necessary to turn the disk into a non-file-structured device. Merely open up a file early on the disk for input and read through end-of-files until you locate the lost file. To read through end-of-files, you must use the {\tt /S} switch on an {\tt ER}, {\tt EB}, or {\tt EW} command. For example, the command \begin{verbatim} ERFOO.MAC/S` \end{verbatim} will open the file {\tt FOO.MA} for input and put TECO into {\em SUPERTECO} mode. In this mode, TECO will not treat a {\tt } found in a file as an end-of-file character. Instead, {\tt } will be treated like any other character. It is not a line terminator or a page terminator. This mode continues until an {\tt ER}, {\tt EW}, or {\tt EB} command is issued without a {\tt /S} switch. \section{VR12 Graphics Support} \label{VR12 Graphics Support} If TECO is run on a PDP-12, TECO will automatically start up in display mode, adjusting to both the size of the display screen and to the presence or absence of the scroller. On a PDP-12, TECO only permits one-page input and output handlers. See Section \ref{Scope Commands} for a description of the available commands to interact with the display. Various aspects of the display screen become immediately obvious upon seeing them; the text pointer, its position and shape and its position between lines; wrap around of more than 72 characters per line, and so on. Experiment with a scratch file for more familiarity. \section{Exceptions} TECO-8 does not support the following commands which are described in this manual: \begin{enumerate} \item Secondary streams ({\tt EP}, {\tt EA}, {\tt ER}\escape, {\tt EW}\escape) \item Auxiliary command streams ({\tt EI}) \item Wildcards ({\tt EN}) \item Zeroing of directories ({\tt EZ}) \item Magtape commands ({\tt EM}) \item View command ({\tt nV}) \item Bounded searches \item Anchored searches \item Search verification ({\tt ES}) \item Command verification ({\tt EV}) \item Backward searches \item Extended string build or match constructs (\caret {\tt Ex}) \end{enumerate} The following incompatibilities exist between TECO-8 and Standard TECO: \begin{enumerate} \item In octal mode, the digits 8 and 9 are not treated as errors when occurring in a numeric string. \item The {\tt *q} immediate action command is not implemented. Instead, the immediate action command * has the same effect as {\tt *Z} of the standard. (The immediate mode command \caret {\tt S} is still accepted for compatibility with OS/8 TECO V5.) \end{enumerate} \section{Chaining To TECO} \label{Chaining To TECO} A user program may chain to TECO passing it a command to be executed. There are two formats that such a command may take. \begin{list}{}{} \item [Format 1] (the TECO command format) passes TECO a valid TECO command to be executed. This TECO command is placed in a buffer starting at location 17600, one 7-bit ASCII character per word. A negative word represents a pointer to a continuation buffer in field 1. There may be any number of continuation buffers, but they must all begin above location 4000 in field 1. Since TECO clobbers most of field 1, these buffers must in fact start above location 7400. TECO will never load into page 7400 of field 1. The buffer ends with a fullword 0. \item [Format 2] (the CCL command format) passes TECO a CCL command to be parsed and executed. Such a command usually begins with the words {\tt TECO}, {\tt MAKE}, or {\tt MUNG}, but is not limited to these words. Such a CCL command is placed in a buffer starting at location 17601, one 7-bit ASCII character per word. Location 17600 must be a fullword 0 to specify that this format is being used. A negative word in the buffer represents a pointer to a continuation buffer in field 1 as described above. The buffer ends with a fullword 0. If this format is used, the passed CCL command will be parsed and executed by {\tt TECO.TEC} as described below. A user may write his own {\tt TECO.TEC}, thus implementing his own CCL commands. There is no limit to the possiblities, other than the user's imagination. \end{list} \section{User Initialization} If a user has a file called {\tt TECO.INI} on {\tt SYS:}, then when TECO starts up (via a CCL command, it will execute the contents of this file (as a TECO macro). This file must contain a valid TECO program (which will execute out of Q-register W). God help you if you have any errors in this program. This start-up file must not modify itself (Q-register W) and must not modify the contents of Q-register V. It should not indiscriminately modify the contents of Q-register Z or the text buffer. {\tt TECO.INI} will be executed before TECO opens any files. That is, if TECO was invoked via a MAKE command, {\tt TECO.INI} will be executed before the {\tt EW} command (for the MAKE) is executed. At this point, the text buffer will contain a copy of the CCL command that invoked TECO (assuming your monitor has {\tt TECO.TEC} support). However, TECO has not as yet parsed this line. The user may examine this line for himself, and modify it, but you had better know what you are doing (and do it right!). {\tt TECO.TEC} will parse the contents of the text buffer at the conclusion of execution of {\tt TECO.INI}. If your monitor does not have {\tt TECO.TEC} support, or if a user program chained to TECO passing it a TECO command (rather than a CCL command), then the initial TECO command will be in Q-register Z when {\tt TECO.INI} gets control. That command has not as yet been executed. The initialization file may examine the contents of Q-register Z to determine what TECO command will be executed and proceed accordingly. It may also modify the contents of Q-register Z (but you better know what you are doing). In this case, {\tt TECO.INI} is started up via the sequence \begin{verbatim} @:ER/SYS:TECO.INI/"SYHXWHK @\caret UZ\caret @teco command\caret @ MW+0ES.,.XWMZES"N0ESMX'`` \end{verbatim} which loads {\tt TECO.INI} into Q-register W, loads the chain argument consisting of an appropriate teco command into Q-register Z, and temporarily stores the value returned by {\tt TECO.INI} in the search verification flag (this feature may change in a subsequent release). Q-register W and ES are cleared before the post-processing command in Q-register X is executed. Note that the chain argument may not contain any embedded nulls. \section{Returned Values From TECO.INI} \label{Returned Values From TECO.INI} {\tt TECO.INI} may also return a value. If your monitor does not support {\tt TECO.TEC,} then only two values are permitted. Returning a 0 (or not returning anything) is the normal sequence of events. Returning a 1 means that TECO should execute the contents of Q-register X (via an MX command) after it executes the initial TECO command (in Q-register Z). {\tt TECO.INI} may set up Q-register X with the appropriate post-processing commands. A typical use of this feature would be to have {\tt TECO.INI} load up Q-register I with an editing macro and then put an {\tt MI} command in Q-register X for subsequent execution. If your monitor does have {\tt TECO.TEC} support, then {\tt TECO.TEC} can support additional returned values. It is recommended that {\tt TECO.TEC} support the returned values of 0 and 1 as above, but in addition, it may support additional values determined by the user. Note that {\tt TECO.INI} is not invoked if TECO is started with a {\tt RUN} or {\tt R} command. \section{TECO.TEC Support} \label{TECO.TEC Support} If the version of CCL you are using to invoke TECO supports {\tt TECO.TEC}, then it will chain to TECO with a 0 at location 17600 and will pass TECO the invoking CCL command (beginning at location 17601). If TECO is invoked in this manner, it will parse this CCL command by executing the TECO command line parser macro stored in {\tt SYS:TECO.TEC}. This macro can be modified by the user to parse switches or do any special processing that is desired. {\tt TECO.TEC} is started up via the command \begin{verbatim} @I^ @ccl command^ @:ER/SYS:TECO.TEC/"F^ ACan't find SYS:TECO.TEC ^ A^ C^ CA.,ZXV.,ZKMV.,.XV`` \end{verbatim} which puts your CCL command in the text buffer and then loads (the first page of) {\tt TECO.TEC} into Q-register V. {\tt TECO.TEC} is then executed with the {\tt MV} command and then Q-register V is cleared. It is the responsibility of {\tt TECO.TEC} to parse the command line in the text buffer and do the appropriate processing and clean-up. It is also the responsibility of {\tt TECO.TEC} to execute a user's start-up file ({\tt TECO.INI}) if one is present. Note that {\tt TECO.TEC} is not invoked if TECO is started via a RUN or R command. Also note, that the CCL command may not contain any embedded nulls. \section{Overlays} \label{Overlays} The key to writing fast TECO programs lies in understanding TECO-8's overlay structure. If TECO-8 is run in 16K or more (20K or more if VT support is present), then the overlays will be memory-resident rather than disk-resident. Although this is much faster than swapping from the disk, swapping from memory still involves some overhead, so it would be wise to structure your TECO program to minimize the number of swaps necessary. The overlay structure is designed so that the minimal number of swaps will be required unless obscure TECO features are used. There are five overlays to TECO: \begin{enumerate} \item The I/O-overlay. This overlay handles file opening and is initially resident. Thus no swapping is necessary to do an initial {\tt ER}, {\tt EW}, or {\tt EB}. \item The Q-overlay. This overlay contains most of the frequently used conditional commands and branching commands. It is intended that this overlay swap in once and remain in memory until TECO is exited. \item The X-overlay. This is the exit overlay and handles commands needed only when TECO is exiting, such as {\tt EX}, {\tt EF}, {\tt EC}, and {\tt EG}. It is intended that this overlay will swap in only once when you are ready to leave TECO. \item The F-overlay. This overlay contains the flag commands and other little-used commands. It is intended that this overlay be not used at all, or if it is used, it will be used so infrequently that it will not slow down system performance. \item The E-overlay. This is the error overlay. It is swapped in only when an error occurs. It is intended that this overlay never be swapped in. \end{enumerate} To write efficient TECO code, the user must know exactly which commands are handled by which overlay. This information is summarized below. \begin{tabular}{ll} Overlay & Commands \\ I-overlay & {\tt ERfile}\escape, {\tt EWfile}\escape, {\tt EBfile}\escape, {\tt :ERfile}\escape, {\tt :EBfile}\escape \\ Q-overlay & {\tt Otag}\escape, {\tt n"Xthen|else'}, {\tt n;}, search;, {\tt n<...>}, {\tt <...>} \\ X-overlay & {\tt EC}, {\tt EG}\escape, {\tt EGcmd}\escape, {\tt EF}, {\tt EK}, {\tt EX}, \\ & {\tt *q}, {\tt ?}, {\tt nEJ}, {\tt n}\caret {\tt \_}, {\tt V}, \caret {\tt B}, \caret {\tt E}, \caret {\tt F} , \caret {\tt L}, \caret {\tt N}, \caret {\tt Uqtext}\escape \\ F-overlay & {\tt ED}, {\tt EH}, {\tt EO}, {\tt ES}, {\tt ET}, {\tt EU}, \caret {\tt D}, \caret {\tt O}, \\ & \bs , {\tt n}\bs, {\tt n=}, {\tt n==}, {\tt n:=}, {\tt n:==}, {\tt |} \\ \end{tabular} Several things are immediately obvious. The command {\tt 0TT} should always be preferred to the {\tt V} command. ELSE clauses should be avoided. (In future releases, we will try to move the processing of the {\tt |} command into overlay Q.) The commands \bs and {\tt =} should be used as infrequently as possible from within long-running macros. {\tt Xq} is preferred to \caret{\tt Uq} to load up a Q-register. {\tt -n-1} is preferred to {\tt n}\caret{tt \_} to take a one's complement. Radix changes should be avoided. Flags, such as {\tt ET} and {\tt ED}, should be set once at the beginning of a macro, and then not fiddled with if at all possible. \section{Installation Instructions} The source of TECO consists of the following modules: \begin{tabular}{ll} {\tt TECO.MAC} & Main module \\ {\tt TECINI.MAC} & Initialization module \\ {\tt TECTBL.MAC} & Tables \\ {\tt TECDEF.MAC} & Global definitions \\ {\tt TECO12.MAC} & VR12 support \\ {\tt TECOVT.MAC} & VT support \\ {\tt TECOVI.MAC} & I/O-overlay \\ {\tt TECOVQ.MAC} & Q-overlay \\ {\tt TECOVX.MAC} & X-overlay \\ {\tt TECOVF.MAC} & F-overlay \\ {\tt TECERR.MAC} & E-overlay and error processor \\ {\tt TECSRH.MAC} & Search processor \\ {\tt TECNUM.MAC} & Arithmetic processor \\ \end{tabular} Each of these modules should be assembled (using {\em MACREL V2} or later). This can be accomplished via the command \begin{verbatim} .MAC TEC???.MAC \end{verbatim} if your monitor supports wildcards in compile-class commands. The resulting relocatable modules are then linked together (using {\em LINK V2} or later) to produce the executable TECO.SV image which should be put on {\tt SYS:} (but it may reside on any device). If your monitor supports {\tt TECO.TEC}, then {\tt TECO.TEC} must be placed on {\tt SYS:}. \section{Arithmetic Precision} \label{Arithmetic Precision} TECO-8 performs 13-bit arithmetic except that multiplication and division by negative numbers gives unpredictable results. All numbers stored in Q-registers are 13 bits long. Numbers stored in flags (such as {\tt ET}, {\tt EU}, etc.) are only 12-bits long. When storing a number into a flag, the high order (sign bit) is lost. When using the value of a flag in an arithmetic expression, the 12-bit value is sign extended first. \section{Alternate Starting Address} \label{Alternate Starting Address} The normal starting address of TECO is location {\tt 00200}. In this (normal) mode, TECO will simulate tabs by spaces on type out and will simulate vertical tabs and form feeds by line feeds. If your terminal has hardware tabs and vertical tabs (such as a KSR-35), then TECO can take advantage of these features. To enable this ability, you should change TECO's starting address to be 05200. This can be done by the monitor commands: \begin{verbatim} .GET SYS:TECO .SAVE SYS:TECO;5200 \end{verbatim} \section{VT05 Support} \label{VT05 Support} TECO will automatically handle command string scope editing correctly on a VT05. The VT support (obtained via use of the {\tt -1W} command) will handle VT05's correctly. The VTEDIT macro does not currently support the VT05 keypad.