\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 } (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 } 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 } 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 }} The action taken when the user types {\tt } 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 } cancels the command string currently being typed and returns TECO to its prompt. Two consecutive {\tt } characters will cause an instant {\tt HKEKEX} exit. 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 (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 } 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 } 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 }, resulting in the loss of the edit. \section{{\tt }} \label{CTRL/Y} {\tt } is not handled at all by TECO and will result in trapping to the command interpreter. Should you accidentally type {\tt }, 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 } 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}