\section{File Specification Commands} \label{File Specification Commands} You must specify an input file whenever you want TECO to accept text from any source other than the terminal. You must specify an output file whenever you want to make a permanent change to the input file. Input and output files are selected by means of file specification commands. File specification formats are operating system dependent and are fully described in the operating characteristics appendices at the end of this manual. Almost every editing job begins with at least one file specification command. Additional file specification commands may be executed during an editing job whenever required; however, TECO will keep only one input file and one output file selected at a time. TECO-11 recognizes two input and two output {\em streams} called the {\em primary} and {\em secondary} streams. The primary input and output streams are initially selected when TECO is invoked. Most file selection commands, and all of the other TECO commands (page manipulation, etc.), operate on the currently selected input and/or output stream. The following sections list all of the file specification commands. Unless otherwise noted, all of these commands leave the text buffer unchanged. Examples of some of these commands appear in Chapter~\ref{Basics of TECO}. \subsection{File Opening Commands} \label{File Opening Commands} The following commands are used to open files for input and output: \begin{table}[h] \caption{\bf{File Specification Commands}} \label{File Specification Commands} \end{table} \nopagebreak \begin{list}{}{\labelsep 20pt} \item [{\tt EBfilespec}\escape ] Edit Backup. This command is recommended for most editing jobs. It is used for files on file-structured devices only. It opens the specified file for input on the currently selected input stream and for output on the currently selected output stream. The {\tt EB} command also keeps the unmodified file (the latest copy of the input file) available to the user; details of this process are system dependent (See appendices). \item [{\tt ERfilespec}\escape ] Edit Read. Opens a file for input on the currently selected input stream. \item [{\tt EWfilespec}\escape ] Edit Write. Opens a file for output on the currently selected output stream. \item [{\tt :EBfilespec}\escape ] Executes the {\tt EB} command, and returns a numeric value. {\tt -1} returned indicates success: the file is open for input. A {\tt 0} indicates the specified file could not be found, and no error message is generated. Other errors (e.g., hardware errors, protection violations, etc.) generate messages and terminate command execution as usual. \item [{\tt :ERfilespec}\escape ] Executes the {\tt ER} command, and returns a numeric value. See the {\tt :EB} command, above. \end{list} \subsection{File Specification Switches} \label{File Specification Switches} Various system-dependent switches (qualifiers) of the form {\tt /SWITCH} can be used with the file specification in {\tt ER}, {\tt EW}, and {\tt EB} commands. These switches are listed below. Consult the operating system specific appendices for further details. In addition, on some systems switches are provided for convenient handling of BASIC-PLUS or BASIC-PLUS-2 source files which use {\tt } or {\tt \&} characters for program line continuation. See Appendix \ref{BASIC-PLUS/BASIC-PLUS-2 Handling} for more information. \begin{table}[h] \caption{\bf Switches on File Specifications} \label{Switches on File Specifications} \end{table} \nopagebreak \begin{tabular}{lll} System & Switch & Meaning \\ OS/8 & {\tt /S} & Ignore end-of-file ({\tt }s) on input. \\ & & (SUPER TECO mode) \\ RSTS/E & {\tt /B} & Read and write with unfiltered 8-bit \\ & {\tt /n} & Handle BASIC-PLUS-x line continuation \\ & {\tt /B+} & Handle BASIC-PLUS line continuation \\ & {\tt /} & Same as {\tt /B+} \\ & {\tt /B2} & Handle BASIC-PLUS-x line continuation \\ & {\tt /CLUSTERSIZE:n} & Specifies output file cluster size \\ & {\tt /MODE:n} & Use non-standard open mode \\ VAX/VMS, & {\tt /B2} & Handle BASIC-PLUS-x line continuation \\ RSX-11 & {\tt /CR} & Implied carriage control \\ & {\tt /-CR} & No (internal) carriage control \\ & {\tt /FT} & FORTRAN carriage control \\ & {\tt /FTN} & Same as {\tt /FT} \\ & {\tt /RW} & Rewind magtape before opening file \\ & {\tt /SH} & Open the file in shared mode \\ & {\tt /SHR} & Same as {\tt /SH} \\ & {\tt /STM} & Stream format \\ & {\tt /VAR} & Variable format \\ TOPS-10 & {\tt /APPEND} & Append to existing output file ({\tt EW} only) \\ & {\tt /ASCII} & File is ASCII \\ & {\tt /GENLSN} & Generate line sequence numbers \\ & {\tt /NOIN} & Don't put user type-in into log file \\ & {\tt /NONSTD} & Open DECtape in non-standard mode \\ & {\tt /NOOUT} & Don't put TECO's type out into log file \\ & & ({\tt EL} only) \\ & {\tt /OCTAL} & Read file in octal \\ & {\tt /PROTECT:n} & Specify protection code \\ & {\tt /SIXBIT} & Read file in pure SIXBIT \\ & {\tt /SUPLSN} & Suppress line sequence numbers \\ \end{tabular} \subsection{File Close and Exit Commands} \label{File Close and Exit Commands} The following commands are used to close files and exit from TECO: \begin{table}[h] \caption{\bf{File Close and Exit}} \label{File Close and Exit} \end{table} \nopagebreak \begin{list}{}{\labelsep 20pt} \item [{\tt EC}] Moves the contents of the text buffer, plus the remainder of the current input file on the currently selected input stream, to the current output file on the currently selected output stream; then closes those input and output files. Control remains in TECO. {\tt EC} leaves the text buffer empty. \item [{\tt EF}] Closes the current output file on the currently selected output stream. The {\tt EF} command does not write the current contents of the buffer to the file before closing it. \item [{\tt EG}\escape ] Performs the same function as the {\tt EC} command, but then exits from TECO and re-executes the last COMPIL class command ({\tt .COMPILE}, {\tt .LINK}, {\tt .EXECUTE}, etc.) {\em [Same as} {\tt EX} {\em in TECO-11]} \item [{\tt EGtext}\escape ] Performs the same function as the {\tt EC} command, but then exits from TECO and passes {\tt text} to the operating system as a command string to be executed (see appendices). \item [{\tt :EGcmd args}\escape ] Performs operating system function {\tt cmd} passing that function {\tt args} as arguments. This command always returns a value as follows: -1 Function {\tt cmd} successfully performed. 0 Function {\tt cmd} is unsupported. Other Function {\tt cmd} attempted, but failed. The returned value is the failure status. There are four functions that are commonly defined: \begin{list}{}{\labelsep 10pt} \item [{\tt INI}] Locates the user's private initialization TECO macro. \item [{\tt LIB}] Defines the user's private library of TECO macros. \item [{\tt MEM}] Read/write TECO's last edited file memory. \item [{\tt VTE}] Locates the user's private scope editing TECO macro. \medskip These four functions work as follows: \item [{\tt :EGcmd }\escape ] Loads Q-register {\tt *} with the requested information. If there is no information (e.g., no user private scope editing TECO macro) then Q-register {\tt *} is set to the null string. \item [\tt :EGcmd \escape ] Clears the information holder. Subsequent {\tt :EGcmd}\escape commands will set Q-register {\tt *} to the null string. \item [{\tt :EGcmd text \escape }] Sets the information holder to {\tt text}. Subsequent {\tt :EGcmd}\escape commands will set Q-register * to {\tt text}. Consult the appendices for details. \end{list} \item [{\tt EK}] Kill the current output file on the currently selected output stream. This command, which purges the output file without closing it, is useful to abort an undesired edit. Executing the {\tt EK} command after an {\tt EW} which is superseding an existing file leaves the old file intact. The {\tt EK} command also ``undoes'' an {\tt EB} command. (See appendices for details.) \iftecotenonly \item [{\tt ELfilespec}\escape ] Open the specified file for output as a log file. Any currently open log file will be closed. If the {\tt /APPEND} switch is given, future logs will append to the file (if it already exists). The default is to supersede. All type-in to TECO and all type out from TECO goes into the log file. The log file is automatically closed by the {\tt EX} and {\tt } TECO commands. {\em [TECO-10 only]} \fi \item [{\tt EX}] Performs the same function as the {\tt EC} command, but then exits from TECO. For safety reasons, this command is aborted if there is text in the text buffer but no output file is open. To exit TECO after just looking at a file, use the command string {\tt HKEX}. \iftecotenonly \item [{\tt EZfilespec}\escape ] This command is useful for outputting to magtapes and DECtapes, on which it initializes (zeros) the specified output device before switching the ouput to the primary output stream. In the case of a magtape, this command rewinds the magtape to load point. If the output device is a disk, this command works exactly like the {\tt EW} command. {\em [TECO-10 only]} \fi \item [{\tt }] The {\tt } \caret {\tt C}) command terminates execution of the current command string and returns control to TECO's prompt. (Under TECO-8, the {\tt } command currently acts as {\tt }.) \item [{\tt }] The \caret C ({\tt }) command causes an immediate abort and exit from TECO. Currently open files are not necessarily closed. See the appendices for more details. Note that the second {\tt } may not be entered in up-arrow mode. \end{list} \subsection{Secondary Stream Commands} \label{Secondary Stream Commands} TECO-11 provides secondary input and output streams. These permit the user to have two input and two output files open at the same time, and to switch processing back and forth between them. Each stream maintains its file position independently, so that one can read from one stream (for example), switch to the other, and then switch back to the first and resume from where one left off. In addition, a separate command stream allows one to execute TECO commands from a file without disturbing either input stream. The following commands manipulate the secondary input and output streams: \medskip Input commands (do not open or close any file; do not change the text buffer): \begin{table}[h] \caption{\bf{Secondary Stream Commands}} \label{Secondary Stream Commands} \end{table} \nopagebreak \begin{list}{}{\labelsep 20pt} \item [{\tt EP}] Switches the input to the secondary input stream. \item [{\tt ER} \escape ] Switches the input to the primary input stream. Output commands (do not open or close any file; do not change the text buffer): \item [{\tt EA}] Switches the output to the secondary output stream. \item [{\tt EW}\escape ] Switches the output to the primary output stream. \subsection*{Indirect file commands} \item [{\tt EIfilespec}\escape ] Opens a file as an indirect command file, so that any further TECO requests for terminal input will come from this file. At end-of-file, or upon TECO's receipt of any error message, the indirect command file will be closed and terminal input will be switched back to the terminal. Note that this command only presets where input will come from; it does not ``splice'' the file's data into the current command string. While end-of-file closes the indirect command file, it does not automatically start execution of commands. Execution will begin only upon TECO's receipt of two adjacent {\tt }s. For instance, assume that {\tt FOO.TEC} contains valid TECO commands, that it presets a return to your terminal with the customary {\tt EI}\escape, but that it does not contain an {\tt } pair. If you type {\tt EIFOO}\escape\escape, TECO will read in the contents of {\tt FOO.TEC} (building a command string) and attempt to continue building the command string by reading from your terminal when end of file on {\tt FOO.TEC} is encountered. Things will appear {\em very quiet} until it occurs to you to type {\tt } and so begin execution of the (composite) command string. All commands encountered in the indirect file will have their normal TECO meaning (as opposed to any immediate action meaning). For example, a {\tt} encountered in an indirect file will not erase the command line in which it occurs. Instead, it will be treated as the TECO \caret {\tt Uqtext}\escape command. The only exception to this rule is the {\tt } command, which directs TECO to execute the preceding command string and then return to the indirect file at the point following the {\tt }. (We can say {\tt } explicitly here, because {\tt } can be other than ESCape only in commands typed at the console.) \item [{\tt EI\escape}] If an indirect command file is active, this command will close it and resume terminal input from the terminal. Any portion of the file after a double {\tt } which has not yet been read is discarded. This command has no effect if no indirect file is already open. \end{list} \subsection{Wildcard Commands} \label{Wildcard Commands} TECO-11 supports wild card file processing with a set of special commands, to allow TECO programs to operate on a set of files. \begin{table}[h] \caption{\bf{Wildcard Commands}} \label{Wildcard Commands} \end{table} \nopagebreak \begin{list}{}{\labelsep 20pt} \item [{\tt ENfilespec}\escape ] This command presets the {\em wild card} lookup filespec. It is only a preset; it does not open, close, or try to find any file. The {\em wild card} lookup is the only filespec that can contain any wild card notations. See the appendices for the allowed wild fields in each operating system. \item [{\tt EN}\escape ] Once the wild card lookup filespec has been preset, executing this command will find the next file that matches the preset wild card lookup filespec and will load the filespec buffer with that file's name. The {\tt G*} command (see \ref{TECO Commands} can be used to retrieve the fully expanded filespec. When no more occurences of the wild card filespec exist, the {\tt ?FNF} error is returned. \item [{\tt :EN}\escape ] Executes the {\tt EN}\escape command, and returns a numeric value. A {\em -1} indicates that another match of the wild card filespec exists and has been loaded into the filespec buffer. A {\em 0} indicates no more occurences exist. No error message is generated. \end{list} The filespec argument to the file selection commands in TECO-11 can use the string building characters described in Table~\ref{String Building Characters} (see section~\ref{Search Arguments}). The {\tt Q*} construct, described in Appendix C, is especially useful in TECO-11. \subsection{Direct I/O to Q-Registers} \label{Direct I/O to Q-Registers} TECO-10 provides commands to do I/O directly to and from the Q-registers, allowing I/O to bypass the text buffer. \begin{table}[h] \caption{\bf{Direct I/O to Q-registers}} \label{Direct I/O to Q-registers} \end{table} \nopagebreak \begin{list}{}{\labelsep 20pt} \iftecotenonly \item [{\tt EQqfilespec}\escape ] Read specified file into Q-register q. No {\tt }s or {\tt }s are removed from the file, except that trailing {\tt }s are discarded. The only switch permitted on the filespec in this command is the {\tt /DELETE} switch, which causes TECO to delete the file after reading it, providing that the file is less than 500 characters long. This command supports the pseudo-device {\tt TMP:}, for {\tt TMPCOR}. Consult the appropriate appendix for details. {\em [TECO-10 only]} \item [{\tt E\% qfilespec}\escape ] Create the specified file. The contents of the file will be the contents of Q-register q with no {\tt }s deleted. No switches are permitted on the filespec of this command. This command supports the pseudo-device {\tt TMP:}, for {\tt TMPCOR}. Consult the appropriate appendix for details. {\em [TECO-10 only]} \fi \end{list}