\chapter{VAX/VMS Operating Characteristics}
\label{VAX/VMS Operating Characteristics}

     TECO   is   implemented   in   VAX/VMS    as    a    half-native,
     half-compatibility  mode  program.   The  command  processor  and
     editor proper is the same as TECO-11 and  runs  in  compatibility
     mode.   Operating  system interface and file service logic run in
     native mode.


\section{Startup}


     VAX/VMS supports all of the standard  TECO  invocation  commands,
     namely
\begin{verbatim}
               TECO
               TECO filespec
               TECO filespec=filespec
               MAKE filespec
               MUNG filespec
               MUNG filespec,text
\end{verbatim}

     If any of these commands are not recognized by  the  system,  see
     the installation instructions (\ref{Help}) in this appendix.

     TECO macros may also be invoked with the command
\begin{verbatim}
               TECO @filespec
\end{verbatim}

     It is exactly equivalent to

\begin{verbatim}
               MUNG filespec
\end{verbatim}

\section{Initialization}


     TECO performs  initialization  by  attempting  to  translate  the
     logical  name  {\tt TEC\$INIT}.   If  this  name  does not translate, no
     special initialization is done.  If it translates to a string  of
     the  form  {\tt \$filespec}  (where {\tt \$} is a dollar sign), TECO executes
     the   TECO   commands   in   the   specified   filespec    during
     initialization.  If {\tt TEC\$INIT} translates to any other string, TECO
     executes that string as TECO commands during initialization.  The
     original  command  line  is available in the text buffer when the
     user initialization commands execute.  Generally, you  would  set
     user  private  modes and/or flags at this time.  This is also the
     normal place to detect, strip off, and do  something  appropriate
     with user private qualifiers.

     TECO's memory is controlled by the logical name  {\tt TEC\$MEMORY}.   If
     this name translates to a string of the form {\tt \$filespec}, TECO uses
     the specified file for its  memory.   Otherwise,  TECO  uses  the
     logical name itself as the memory.

     If TECO is requested to load  VTEDIT  at  startup  (e.g.,  via  a
     {\tt TECO /VTEDIT}  command), it attempts to translate the logical name
     {\tt TEC\$VTEDIT}.  If the name is defined, the  resulting  filespec  is
     used  as  the  file  from  which  to  load  the scope editor.  If
     {\tt TEC\$VTEDIT} is not defined, TECO attempts to translate the logical
     name  {\tt TEC\$LIBRARY}.  If that logical is defined, it is used as the
     (device  and)  directory  name  of  where  to  find   {\tt VTEDIT.TEC}.
     Elsewise, TECO defaults to {\tt SYS\$LIBRARY:VTEDIT.TEC}.

     These four logical names ({\tt TEC\$INIT}, {\tt TEC\$MEMORY},  
	{\tt TEC\$VTEDIT},  and
     {\tt TEC\$LIBRARY})  are  the  information  holders corresponding to the
     four standard {\tt :EG} commands {\tt INI}, {\tt MEM}, {\tt VTE},  and  
{\tt LIB}  respectively
     (see section \ref{File Close and Exit Commands}).


\section{File Specification}


     All file specifiers are subject to  the  VAX/VMS  file  specifier
     rules;   logical  names  and multi-level directories are properly
     handled, including transparent network file access.  The filename
     field  must  be  specified  whenever the device name references a
     file structured device.  The type field must be explicitly  given
     if  used.   There is no default type except for {\tt EI} commands which
     default the type field to {\tt .TEC}.

     Qualifiers may be  applied  to  file  specifications  to  control
     format and attributes;  see \ref{File Record Format}.

     The qualifier {\tt /RW} may be applied to any file specification in  an
     {\tt ER},  {\tt EW},  and {\tt EI} command.  If the file specification 
	references a
     magtape, the tape is rewound before the  file  is  opened.   Note
     that  for  output files, this has the effect of zeroing the tape.
     The /RW qualifier is ignored for all other device types.

     The  presence  of  version  numbers  in  Files-11   causes   file
     processing  to  behave  slightly  differently  under VAX/VMS than
     under other operating systems.  For example, no  {\tt .BAK}  files  are
     used;   each  execution  of  an  {\tt EB} command simply produces a new
     version of the file.  Thus a user may retain any level of  backup
     he  feels  to  be  comfortable.   It  also  means  that  one must
     occasionally delete obsolete files to avoid cluttering the  disk.
     Thus the command

\begin{verbatim}
               EBname.typ;version\escape
\end{verbatim}

     is equivalent to the commands

\begin{verbatim}
               ERname.typ;version\escapeEWname.typ;0\escape
\end{verbatim}

     The {\tt EW} command also creates a new version (one  higher  than  the
     current  highest)  if no version number is given.  If an explicit
     version number is given, then that number is used, and if another
     file  of  the same name, type, and version previously existed, it
     is superseded without  warning.   (See  use  of  the  {\tt EK}  command
     below.)

     In reading files, version numbers behave the  same  as  in  other
     VAX/VMS  utilities:   the  default  is the highest version.  This
     leads to a problem in re-opening the input file while a  file  is
     being  edited  with {\tt EB}.  Since the output file is already created
     and in the directory, the input file is  no  longer  the  highest
     version.   One may deduce the version number of the input file by
     doing a {\tt ER}\escape{\tt :G*}\escape\escape which types  the  
	file  string  of  the  current
     (primary) input file.

     In symmetry with the {\tt EB} command,  the  {\tt EK}  command  
	functions  by
     simply  deleting  the current output file.  Note, however, that a
     supersede ({\tt EW} of same name, type, and version) is  not  undone  -
     the file is already deleted!

     When  files  are  processed  concurrently  on  the  primary   and
     secondary  channels,  all files are kept open.  Thus the problems
     that occur under RSX-11 do not exist under VAX/VMS.


\section{Wild Card Lookup}


     Wild card file name processing supports all of the  wild  carding
     facilities  of  RMS.   For  VAX/VMS  V2  and  later  systems this
     includes embedded * and % and multi-level directory wildcarding.


\section{Symbol Constituents}
\label{Symbol Constituents}

     The match control character \caret{\tt EC} and the  conditional  
	{\tt n"C}  accept
     the  VAX/VMS  symbol constituent character set, which consists of
     upper and lower case alphabetics, numerics, {\tt .}, {\tt \$}, and 
	{\tt \_}.


\section{Exiting From Teco}


     The normal method of exiting from TECO is with  the  {\tt EX}  command.
     This  copies  the remaining input file to the output file, closes
     all files and exits.

     The {\tt <CTRL/C>} (or Caret-C) command is the ``give up  and  get  out''
     command.  Executed from main command level, it will cause TECO to
     exit regardless of the state of the buffer.  If there is an  open
     output  file,  it  is  deleted.   The {\tt <CTRL/C>} command is roughly
     equivalent to {\tt EKHKEX}.

     TECO's normal exit status code (as reflected by the  DCL  symbols

     \${\tt STATUS} and \escape {\tt SEVERITY}) is 1 (success).  An exit 
	caused by an {\tt EG}\escape
     command sets the exit status code to 9 (also success).  An  error
     exit  caused  by  an error or {\tt <CTRL/C>} with the 128 bit set in 
	{\tt ET}
     sets the exit  status  code  to  hexidecimal  {\tt 1000002C}  which  is
     {\tt SS\$\_ABORT}  with the inhibit message bit set.  All other exits are
     from fatal internal errors and the exit status code is the  fatal
     error status code.


\section{{\tt <CTRL/C>}}


     The action taken when the user types  {\tt <CTRL/C>}  depends  on  what
     TECO is doing.

     If TECO is executing commands, or is awaiting type-in for the  
	\caret{\tt T}
     command, the {\tt ?XAB} error occurs.

     If TECO is at command level, typing {\tt <CTRL/C>} cancels the  command
     string currently being typed and returns TECO to its prompt.  Two
     consecutive {\tt <CTRL/C>} characters  will  cause  an  instant  
	{\tt HKEKEX}
     exit.

     Sometimes it is desireable for a TECO  macro  to  detect  when  a
     {\tt <CTRL/C>}  was  typed.   By  detecting the {\tt <CTRL/C>}, 
	the macro can
     exit cleanly  back  to  command  level  (pop  saved  Q-registers,
     restore  any  flag values, etc.).  To do this, the macro sets Bit
     15 (Octal 100000,  Decimal  -32768)  of  the  {\tt ET}  flag.   When  a
     {\tt <CTRL/C>}  is  typed, TECO will automatically turn off Bit 15, but
     will continue execution of the  macro.   The  macro  periodically
     checks  Bit  15  and  exits  cleanly  if  it  ever goes off.  For
     example:

\begin{verbatim}
              [0 [1 -32768#ETET < ... ET; > 32767&ETET ]1 ]0
\end{verbatim}

     Setting the {\tt <CTRL/C>} intercept bit in the {\tt ET} flag  
	must  be  done
     with  some  care;   if the bit is set inside a command loop which
     does not check it, it will be impossible for the  user  to  abort
     the  loop.   The  only remedy for this situation is to abort TECO
     with {\tt <CTRL/Y>}, resulting in the loss of the edit.


\section{{\tt <CTRL/Y>}}
\label{CTRL/Y}

     {\tt <CTRL/Y>} is not handled  at  all  by  TECO  and  will  result  in
     trapping  to  the  command  interpreter.  Should you accidentally
     type {\tt <CTRL/Y>}, immediately type {\tt CONTINUE} in response to  
	the  DCL
     prompt to resume editing.


\section{Exit And Go}


     If TECO is exited with  the  {\tt EGstring}\escape  command,  the  
	string  is
     passed  to the command interpreter as the next command to execute
     after TECO has closed its files and exited.  This  feature  works
     only on VAX/VMS V2 and later systems.


\section{{\tt ET} Flag Handling}
\label{ET Flag Handling}


     TECO will automatically turn off the following  bits  in  the  {\tt ET}
     flag  on  every  error:   Bit 0 (image output), Bit 3 (no echo on
     \caret T), Bit 4 (cancel \caret O), Bit 5 (no stall on \caret T), 
and  Bit  15  (\caret{\tt C} trap).

     In addition, TECO always turns off Bit 7 (exit  on  error,  etc.)
     every time is reaches prompt ({\tt *}) level.

     Bit 6 (the detach flag) has no meaning in VAX/VMS.


\section{File Record Format}
\label{File Record Format}

     Files-11 files are record structured, while TECO'S text buffer is
     ASCII  stream.   Thus  TECO  must  make  format  conversions when
     reading and writing files.  The conversion depends on the  record
     attributes  of  the  file.  While reading a file, the records are
     packed into the buffer.  If the file is implied carriage  control
     (the standard VAX/VMS source format) or FORTRAN carriage control,
     TECO inserts a carriage return and line feed after each record to
     make  each  record appear as a line of text in the buffer, unless
     the record ends with ESCAPE, carriage return, line feed, vertical
     tab,   or  form  feed.   A  record  containing  a  form  feed  is
     interpreted as an end of page mark;  it stops the read  operation
     and  the  form feed is not entered in the buffer.  The portion of
     the record after the form feed, if any, is  saved  for  the  next
     input command.  If the file has print file carriage control, TECO
     interprets the carriage control bytes and inserts  the  resulting
     carriage  return  and  line feed characters about the record.  If
     the input file has no  carriage  control  (also  called  internal
     carriage  control), TECO simply packs the records together in the
     text buffer.

     On output, TECO scans the text buffer for carriage  return,  line
     feed,   vertical  tab,  and  form  feed  characters.   Each  such
     character delimits the end of an output record.   If  the  output
     file  is implied or FORTRAN carriage control, and the record ends
     with exactly carriage return / line feed, the carriage return and
     line  feed are not output with the record;  Otherwise, the record
     is output in its entirety.  The carriage return and line feed are
     also  output  with  the  record  if the record ends with ESCAPE /
     carriage return / line feed.

     Qualifiers  may  be  applied  to  the  input  and   output   file
     specifications.   When a carriage control qualifier is applied to
     an input file, the file is read as  if  it  had  that  attribute;
     when  the  qualifier  is  applied  to an output file, the file is
     written with that attribute.  Applying a qualifier to an {\tt EB}  file
     specification  causes  the  qualifier  to apply to both input and
     output files.

     The following qualifiers may be used to control input processing:

\begin{list}{}{\labelsep 30pt}

          \item[{\tt /-CR}]                Force "none" file record attributes
          \item[{\tt /CR}]                 Force "Implied" file record attributes
          \item[{\tt /FT}]                 Force "FORTRAN" file record attributes
          \item[{\tt /FTN}]                Same as /FT
          \item[{\tt /B2}]                 BASIC-PLUS-x handling (see \ref{BASIC-PLUS/BASIC-PLUS-2 Handling})
\end{list}

     The  following  qualifiers  may  be  used   to   control   output
     processing:

\begin{list}{}{\labelsep 20pt}

          \item[{\tt /VAR}]                Create file record format "Var"
          \item[{\tt /STM}]                Create file record format "Stm"
          \item[{\tt /-CR}]                Create file record format "None"
          \item[{\tt /CR}]                 Create file record format "Implied"
          \item[{\tt /FT}]                 Create file record format "FORTRAN"
          \item[{\tt /FTN}]                Same as {\tt /FT}
          \item[{\tt /B2}]                 BASIC-PLUS-x handling (see \ref{BASIC-PLUS/BASIC-PLUS-2 Handling})
\end{list}

     The   following   qualifiers   may    be    used    to    control
     open/create/access options:

\begin{list}{}{\labelsep 20pt}
          \item[{\tt /RW}]                 Rewind before open/create
          \item[{\tt /SH}]                 Enable file sharing
          \item[{\tt /SHR}]                Same as {\tt /SH}
\end{list}

     Below is  a  complete  list  of  valid  TECO  input  file  record
     format/attribute    combinations    and    the   resulting   file
     format/attribute combinations for {\tt EB} commands:

\begin{tabular}{llll}

%           \multicolumn{2}{c}{Input} &
%		\multicolumn{2}{c}{Output} \\
%           \multicolumn{2}{c}{Format Attribute} &
%		\multicolumn{2}{c}{Format Attribute} \\

        Fix     & none              & Var     & Implied \\
        Fix     & Implied           & Var     & Implied \\
        Fix     & FORTRAN           & Var     & FORTRAN \\
        Var     & none              & Var     & Implied \\
        Var     & Implied           & Var     & Implied \\
        Var     & FORTRAN           & Var     & FORTRAN \\
        VFC     & Print             & Var     & Implied \\
        Stm     & none              & Stm     & Implied \\
        Stm     & Implied           & Stm     & Implied \\

\end{tabular}

     Files read with the  {\tt EI}  command  have  their  record  attributes
     interpreted in the same manner.  This leads to an unexpected side
     effect with {\tt EI} files containing  an  entire  command.   The  last
     record of the file presumably contains as its last characters the
     two alt modes which initiate execution of the macro.  If the file
     is  implied  carriage  control, however, there are also the final
     carriage return / line feed belonging to the last  record,  which
     remain  in  the  type in buffer while the macro executes.  If the
     macro attempts to receive input with the  {\tt <CTRL/T>}  command,  the
     carriage  return  /  line  feed  will be the first two characters
     read.  Alternatively, if the macro does no type in, the  carriage
     return  /  line  feed  will  be  read  by  TECO  as the first two
     characters of the next command.  Then no asterisk ({\tt *}) will appear
     as the prompt for the next command.  The remedy for both cases is
     for the macro to execute an {\tt EI}\escape command early  on.   
	This  causes
     the  remainder  of  the indirect file to be discarded and further
     input to be read from the terminal as soon as the double alt mode
     is encountered.


\section{Command Line Processing}


     The mechanism used to process the command line in VAX/VMS TECO is
     designed   to   allow   sophisticated  TECO  users  the  greatest
     flexibility in customizing TECO for their own use.  It  functions
     as follows:

     The initialization routine places  a  built-in  command  decoding
     TECO  macro  into  Q-register  Y  and  the  original command line
     (including the keyword {\tt TECO}, {\tt MAKE}, or {\tt MUNG}) into 
	Q-register Z.

     It then looks for a user private command decoding TECO  macro  by
     attempting

\begin{enumerate}

          \item  an {\tt EITECO}\escape\escape if the logical name {\tt TECO} 
		exists, elsewise

          \item  an {\tt EISYS\$LOGIN:TECO}\escape\escape if the  logical  
	name  {\tt SYS\$LOGIN} exists, elsewise

          \item  an {\tt EITECO}\escape\escape

\end{enumerate}

     If the {\tt EI} succeeds, the found file is executed.  The file may, or
     course,  do  anything  it  pleases.   Generally,  you would use a
     private command decoder to automate some sort of system  specific
     editing  package.   For  example, to implement an editing package
     called {\tt FOOBAR}, you would define the logical TECO with

\begin{verbatim}
               \$ DEFINE/SYSTEM TECO dev:[dir]FOOBAR
\end{verbatim}

     define a DCL foreign command symbol with

\begin{verbatim}
               \$ FOOBAR :== \$SYS\$SYSTEM:TECO FOOBAR
\end{verbatim}

     and place the TECO macro the  implements  the  {\tt FOOBAR}  editor  in
     {\tt dev:[dir]FOOBAR.TEC}.  Now, whenever a {\tt TECO}, {\tt MAKE}, 
	{\tt MUNG}, or {\tt FOOBAR}
     command is issued, the your macro will gain control.   It  should
     fetch Q-register Z (the original command line), check the command
     type, if it's {\tt FOOBAR}  then  go  do  its  thing,  else  it  should
     terminate and execute TECO's built-in command decoder.

\begin{verbatim}
               GZ               ! Put command into text buffer !
               J ::@S/FOOBAR/"U ! Is the command for us? !
                 @EI//          ! Not for us, turn us off !
                 HK             ! Clear out text buffer !
                 MY             ! Let the real TECO takeover !
               '                ! It's for us, just flow on... !
               \$\$               ! Double ESCAPE; 1st command's end !
               ...              ! Do your own thing here... !
\end{verbatim}

     This mechanism should not be used for simple initialization;  the
     standard   {\tt TEC\$INIT}  facility  should  suffice  for  that.   This
     facility is provided for the sophisticated user who wants his own
     command processing and thus wishes to usurp control.


\section{Help}
\label{Help}

     On VAX/VMS, TECO can provide {\tt HELP} in any of three ways.

     You can issue a {\tt HELP} command at  TECO's  asterisk  prompt.   This
     {\tt HELP}  command  obeys  the  standard  VAX/VMS  {\tt HELP} command 
	syntax
     rules.  The {\tt HELP} command may be terminated by  either  RETURN  or
     \escape\escape.

     You can type the / command  immediately  after  an  error.   (See
     section  \ref{Immediate Action Commands}.) TECO will respond with a one-paragraph description
     of the error.

     You can set EH to 3.  (See section \ref{Mode Control Flags}.) This will cause TECO to
     automatically  respond  with  a  one-paragraph description of any
     error which occurs.


\section{Installing TECO}
\label{Installing TECO}

     TECO is distributed with  VAX/VMS;   the  files  are  already  in
     place.   If  TECO  will receive heavy use, it should be installed
     {\tt /OPEN} and {\tt /HEADER\_RESIDENT}.

     The following commands, if used in a {\tt LOGIN.COM} file, would define
     the three normal TECO invocation commands:

\begin{verbatim}
		$ TE*CO :== \$SYS\$SYSTEM:TECO TECO
		$ MAK*E :== \$SYS\$SYSTEM:TECO MAKE
		$ MU*NG :== \$SYS\$SYSTEM:TECO MUNG
\end{verbatim}

     The asterisk allows for  abbreviation  of  these  commands.   For
     example, the {\tt TE*CO} definition permits {\tt TE}, {\tt TEC}, or 
	{\tt TECO}.

     One may include command qualifiers in  the  command  definitions.
     For  example, one can define a command to invoke TECO with {\tt VTEDIT}
     as follows:

\begin{verbatim}               
		$ VTECO :== \$ SYS\$S YSTEM:TECO TECO /VTEDIT
\end{verbatim}

