\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 <LF>} 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 <CTRL/Z>}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 <CTRL/C><CTRL/C>} 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 <CTRL/C>}]       The   {\tt <CTRL/C>}   \caret {\tt C})   command    terminates
                    execution   of  the  current  command  string  and
                    returns control to TECO's prompt.  (Under  TECO-8,
                    the    {\tt <CTRL/C>}    command   currently   acts   as
                    {\tt <CTRL/C><CTRL/C>}.)

     \item [{\tt <CTRL/C><CTRL/C>}]
                    The \caret C ({\tt <CTRL/C>}) 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 <CTRL/C>} 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 <ESC>}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 <ESC><ESC>}  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 <DELIM><DELIM>} 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<CTRL/U>}  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 <ESC><ESC>}  command, which directs TECO to execute
                    the preceding command string and  then  return  to
                    the  indirect  file  at  the  point  following the
                    {\tt <ESC><ESC>}.  (We can say  {\tt <ESC>}  explicitly  here,
                    because  {\tt <DELIM>}  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 <DELIM>}  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 <CTRL/E>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 <NULL>}s
                    or  {\tt <FF>}s  are  removed from the file, except that
                    trailing {\tt <NULL>}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 <NULL>}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}

