Standard TECO TEXT EDITOR AND CORRECTOR FOR THE VAX-11, PDP-11, PDP-10, and PDP-8 USER'S GUIDE AND LANGUAGE REFERENCE MANUAL May 1985 Edition TECO-11 VERSION 40 TECO-10 VERSION 3 TECO-8 VERSION 7 May, 1985 Standard TECO The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation or by DECUS. Neither Digital Equipment Corporation, DECUS, nor the authors assume any responsibility for the use or reliability of this document or the described software. Copyright (C) 1979, 1985 TECO SIG General permission to copy or modify, but not for profit, is hereby granted, provided that the above copyright notice is included and reference made to the fact that reproduction privileges were granted by the TECO SIG. Standard TECO PAGE i CONTENTS INTRODUCTION 1 PREFACE TO THE MAY 1985 EDITION 4 CHAPTER 1 BASICS OF TECO 7 1.1 USING TECO 7 1.2 DATA STRUCTURE FUNDAMENTALS 9 1.3 FILE SELECTION COMMANDS 10 1.3.1 Simplified File Selection 10 1.3.2 Input File Specification (ER command) 11 1.3.3 Output File Specification (EW command) 12 1.3.4 Closing Files (EX command) 13 1.4 INPUT AND OUTPUT COMMANDS 14 1.5 POINTER POSITIONING COMMANDS 15 1.6 TYPE OUT COMMANDS 16 1.6.1 Immediate Inspection Commands 17 1.7 TEXT MODIFICATION COMMANDS 18 1.8 SEARCH COMMANDS 19 1.9 SAMPLE EDITING JOB 20 INTERLUDE 23 CHAPTER 2 INVOKING TECO 24 2.1 RUNNING TECO 24 2.2 CREATING A NEW FILE 24 2.3 EDITING AN EXISTING FILE 24 2.4 SWITCHES ON TECO AND MAKE COMMANDS 25 2.5 INVOKING A TECO PROGRAM 26 2.6 USER INITIALIZATION 27 CHAPTER 3 CONVENTIONS AND STRUCTURES 29 3.1 TECO CHARACTER SET 29 3.2 TECO COMMAND FORMAT 30 3.2.1 Numeric Arguments 31 3.2.2 Text Arguments 32 3.2.3 Colon Modifiers 33 3.3 DATA STRUCTURES 34 3.3.1 Text Buffer 35 3.3.2 Q-registers 36 3.3.3 Q-register Push-down List 37 3.3.4 Numeric Values and Flags 37 Standard TECO PAGE ii CHAPTER 4 COMMAND STRING EDITING 38 4.1 Immediate Action Editing Characters 38 4.2 Immediate Action Commands 41 4.3 Introduction to Macros 43 4.4 Immediate ESCAPE-Sequence Commands 44 4.5 Operating System Character Filters 46 CHAPTER 5 COMMAND DESCRIPTIONS 48 5.1 FILE SPECIFICATION COMMANDS 49 5.1.1 File Opening Commands 49 5.1.2 File Specification Switches 51 5.1.3 File Close and Exit Commands 51 5.1.4 Secondary Stream Commands 54 5.1.5 Wildcard Commands 56 5.1.6 Direct I/O to Q-Registers 56 5.2 PAGE MANIPULATION COMMANDS 58 5.3 BUFFER POINTER MANIPULATION COMMANDS 61 5.4 TEXT TYPE OUT COMMANDS 63 5.5 DELETION COMMANDS 66 5.6 INSERTION COMMANDS 68 5.7 SEARCH COMMANDS 70 5.8 SEARCH ARGUMENTS 76 5.9 Q-REGISTER MANIPULATION 80 5.10 ARITHMETIC AND EXPRESSIONS 86 5.11 SPECIAL NUMERIC VALUES 89 5.12 COMMAND LOOPS 94 5.13 BRANCHING COMMANDS 95 5.14 CONDITIONAL EXECUTION COMMANDS 101 5.15 RETRIEVING ENVIRONMENT CHARACTERISTICS 103 5.16 MODE CONTROL FLAGS 105 5.17 SCOPE COMMANDS 113 5.17.1 Video Terminal Scope Commands 113 5.17.2 Refresh Scope Commands 116 5.18 PROGRAMMING AIDS 117 5.18.1 Text Formatting 117 5.18.2 Comments 117 5.18.3 Messages 118 5.18.4 Tracing 119 5.18.5 Convenience Characters 119 5.18.6 Memory Expansion 120 5.18.7 Case Control 121 5.19 MANIPULATING LARGE PAGES 122 5.20 TECHNIQUES AND EXAMPLES 123 Standard TECO PAGE iii APPENDIX A ASCII CHARACTER SET 128 APPENDIX B ERROR MESSAGES 137 APPENDIX C INCOMPATIBLE, OBSOLETE, AND SYSTEM-SPECIFIC COMMANDS 145 C.1 SPECIFIC FEATURES OF TECO-11 145 C.1.1 TECO Commands 145 C.1.2 String Build Constructs 147 C.2 SPECIFIC FEATURES OF RT-11 148 C.3 SPECIFIC FEATURES OF RSTS/E 148 C.4 SPECIFIC FEATURES OF RSX-11/M, RSX-11/D, and IAS 149 C.5 SPECIFIC FEATURES OF VAX/VMS 149 C.6 SPECIFIC FEATURES OF OS/8 149 C.7 SPECIFIC FEATURES OF TOPS-10 150 APPENDIX D RT-11 OPERATING CHARACTERISTICS 153 APPENDIX E RSTS/E OPERATING CHARACTERISTICS 157 APPENDIX F RSX-11 OPERATING CHARACTERISTICS 160 APPENDIX G VAX/VMS OPERATING CHARACTERISTICS 167 APPENDIX H OS/8 OPERATING CHARACTERISTICS 175 APPENDIX I TOPS-10 OPERATING CHARACTERISTICS 187 APPENDIX J BASIC-PLUS/BASIC-PLUS-2 HANDLING 194 GLOSSARY 197 INDEX 214 Standard TECO PAGE 1 Introduction INTRODUCTION TECO is a powerful text editing language available under most DIGITAL operating systems. TECO may be used to edit any form of ASCII text: program sources, command procedures, or manuscripts, for example. TECO is a character-oriented editor, and also offers a number of facilities for dealing with lines of text. You can use TECO interactively, issuing commands which are to be executed as soon as they are typed in. (TECO is an interpreter.) In this mode, TECO can be used for tasks ranging from very simple to quite complex. You can write sequences of commands called macros, which can be stored and then invoked by short commands or even single keystrokes. You can write sequences of commands to be run as TECO programs, and store them on disk for execution at convenience. TECO can be used as an implementation language, as it provides powerful primitive functions for text processing, screen handling, and keyboard management. (The VTEDIT program included with some TECO distributions is an example of a full keypad editor developed in the TECO language.) TECO correctly handles most sequential ASCII formats supported by the operating systems upon which it runs. It provides flexible pattern-matching constructs for text searching, file wildcarding, and special support for editing BASIC-PLUS/BASIC-PLUS-2 source programs. A split screen scrolling feature allows command dialogue to share the screen with an automatically-updated window into the editing buffer. TECO's syntax is terse; commands are designed to minimize keystrokes. Also, the versatility of TECO "in all its glory" makes it complex. However, just a few commands suffice to get real work done, and a novice TECO user can begin creating and editing text files after only a few hours of instruction. More powerful features can be learned one at a time, and at leisure. This manual presents TECO in two stages. The first part (Chapter 1) contains basic information and introduces that set of "just a few" commands. Subsequent chapters describe the full TECO command set, including a review of the those commands presented in Chapter 1. These chapters also introduce the concept of TECO as a programming language and explain how basic editing commands may be combined into "programs" sophisticated enough to handle the most complicated editing tasks. The early sections of this manual include few specific examples of commands, since all TECO commands have a consistent, logical Standard TECO PAGE 2 Introduction format which will quickly become apparent to the beginning user. There is, however, an extensive example at the end of Chapter 1 which employs most of the commands introduced up to that point. Students of TECO should experiment with each command as it is introduced, and then duplicate the examples on their computer. (If a video terminal which supports split-screen scrolling such as a member of the VT100 or VT200 families is available and the TECO being used supports it, seeing both your commands and their effects in the text buffer simultaneously can make learning easier. A command such as "5,7:W" allows 5 lines for command dialogue, while "watching" the text buffer on the remainder of the screen. The 7:W command is described in Table 5-17B.) This manual is intended to be a reference manual, and except for Chapter 1 is not a tutorial. After Chapter 1, it is assumed that the reader has a general familiarity with TECO and is referring to this manual to find detailed information. Notation The following notation is used in this manual to represent special characters: Notation ASCII code (octal) Name 0 Null 10 Backspace 11 Tab 12 Line Feed 13 Vertical Tab 14 Form Feed 15 Carriage Return or $ 33 ESCape or Altmode - Control-x 40 Space 177 Delete or Rubout or ` - See below is a character used to signify the end of text strings and TECO commands typed at the console. (TECO presumes that you may need to deal with carriage return and line feed as ordinary characters in ASCII text, so another character must be used as TECO's text-string and command-string delimiter.) When a command string is being executed, TECO looks for the ESCape character (octal 033) as its delimiter. Some newer terminals, however, no longer possess an ESCape key. Late-model TECO's are capable of recognizing a surrogate (some other, user-specified) character as signifying an ESCape when typed at the console. Such a character echos as accent grave -- you see Standard TECO PAGE 3 Introduction an ` character, and TECO receives an ESCape character. (Note that TECO programs, command files, and macros cannot use the surrogate, since it is translated to ESCape only when you type it at the console.) For details on choosing a surrogate for ESCape, see the EE flag or the 8192 ET bit (section 5.16). Throughout this manual, the term is used to mean whatever character you type as a text-string or command-string delimiter. The ` character is used throughout to mean whichever character is echoed for a keystroke which passes an ESCape to TECO; if no ESCape surrogate is active, you will see a $ instead. Control characters, , are produced by striking the CONTROL key and a character key simultaneously. Throughout this manual, upper case characters will be used to represent TECO commands. Standard TECO PAGE 4 Preface to the May 1985 edition PREFACE TO THE MAY 1985 EDITION Trading in the ESCape key In the beginning, terminals had ESCape keys. (Go back far enough and the device TT: stands for might actually have existed on the system, too.) Programs wanting to treat & Co. as data needed another character to serve as command delimiter, and ESCape looked available. Times change. Welcome to ESCape sequences, to cursor-control and function keys. Farewell to $$. See the Introduction for the notation used in this manual. Hello ``. Changes to the manual This edition of the manual incorporates new material pertinent to the enhancements to TECO-11 between Version 36 and Version 40 (see below). Although this manual is still not intended to be a tutorial, some "how to learn" suggestions (such as use of split-screen scrolling) were added, as were indications of how TECO can be used to build custom-designed editors. Numerous smaller changes were also made: clarifications, new index and glossary entries, additional explanatory material and cross referrals, correction of old typographic errors, and (no doubt) addition of new ones. Standard TECO PAGE 5 Preface to the May 1985 edition From Version 36 to Version 40 - affected section numbers Manual organization/additions -- Introduction to Macros (new section), 4.3 Split-screen scrolling, 5.17 "Immediate action commands" renamed to "immediate inspection commands", 1,6.1 "Immediate action editing characters" (new name), 4.1 VAX/VMS filespec qualifiers, format/attribute table, G.11 Eight-bit ASCII character set table, Appendix A Handling for BASIC-PLUS-x source files, Appendix J "Significant" software changes -- ESCape surrogate - EE flag, 8192 ET bit, 5.16 Reverse paging (-P, et al, VAX/VMS only), 5.2 Reverse searching (-N, et al, VAX/VMS only), 5.7 Local Q-registers, 3.3.2 Local Q-register manipulation, 5.9 Immediate ESCape-sequence commands, 4.4 :^T, read/decode a keystroke, 5.11 32 ED bit controls immediate ESC-seq commands, 5.16 Acceptance and handling of 8-bit characters, [throughout] Typeout of 8-bit data, and the 4096 ET bit, 5.16 n:^T, one-shot binary-mode character typeout, 5.4 TECO HELP facilities on VAX/VMS, G.13 "Minor" software changes -- ^W as immediate mode command (screen re-paint), 4.2 character as immediate inspection command, 1.6.1, 4.2 Null tag allowed in computed GOTO, 5.13 Standard TECO PAGE 6 Preface to the May 1985 edition nFRtext` command (replace n characters), 5.6 m,nFRtext` command (replace from m to n), 5.6 ^E (form feed flag) can now be user-set, 5.11 Setting 1:W changes width and O/S characteristic, 5.17 WRAP/NOWRAP set by 256 ET bit on VAX/VMS, 5.16 128 ED bit inhibits auto-refresh in split scrolling, 5.16 Search matching with diacritical marks, 5.16 New 0:W codes for VT102 and GIGI scope types, 5.17 VAX/VMS handling of ^T (disabled when), 4.5 Standard TECO PAGE 7 Basics of TECO CHAPTER 1 BASICS OF TECO 1.1 USING TECO TECO may be called from command level by typing the appropriate command, followed by a carriage return: For RT-11, OS/8, TOPS-10, and TOPS-20 R TECO For RSTS/E RUN TECO$:TECO -or- EDIT/TECO For RSX-11 RUN $TEC For VAX/VMS RUN SYS$SYSTEM:TECO TECO will respond by printing an asterisk at the left margin to indicate that it is ready to accept user commands. At this point, you may type one or more commands. A TECO command consists of one or two characters which cause a specific operation to be performed. Some TECO commands may be preceded or followed by arguments. Arguments may be either numeric or textual. A numeric argument is simply an integer value which can be used to indicate, for example, the number of times a command should be executed. A text argument is a string of ASCII characters which might be, for example, words of text or a file specification. If a command requires a numeric argument, the numeric argument always precedes the command. If a command requires a text argument, the text argument always follows the command. Each text argument is terminated by a special character (usually a character, which TECO hears as an ESCape - see Introduction). This indicates to TECO that the next character typed will be the first character of a new command. TECO accumulates commands as they are typed in a command string, and executes commands upon receipt of two consecutive characters. may be any character you select (if your TECO and operating system support user-selectable ESCape surrogates - see sections on ET and EE flags). When you type the character you have designated as , TECO receives an ESCape character, and an ` (accent grave) is echoed. (If you are not using an ESCape surrogate -- that is, you are actually pressing an ESCape key -- a dollar sign is echoed.) The accent grave character is used in examples throughout this manual to represent typed s. Note that the carriage return character has no special significance to TECO; only the forces execution of the command string. Standard TECO PAGE 8 Using TECO TECO executes command strings from left to right until either all commands have been executed or a command error is recognized. It then prints an asterisk to signal that additional commands may be entered. If TECO encounters an erroneous command, it prints an error message and ignores the erroneous command as well as all commands which follow it. All error messages are of the form: ?XXX Message where XXX is an error code and the message is a description of the error. Some error messages mention the specific character or string of characters in error. In these error messages, TECO represents the non-printing special characters as follows: Character Form Displayed <^x> Every error message is followed by an asterisk at the left margin, indicating that TECO is ready to accept additional commands. If you type a single question mark character after a TECO-generated error message, TECO will print the erroneous command string up to and including the character which caused the error message. This helps you to find errors in long command strings and to determine how much of a command string was executed before the error was encountered. You can correct typing errors by hitting the DELETE key, which may be labeled DEL or RUBOUT on your keyboard. Each depression of the DELETE key deletes one character and echoes it on your terminal, beginning with the last character typed. If your terminal is a CRT, TECO will actually erase the deleted character from the screen. You can delete an entire command string this way, if necessary. To delete an entire line of commands, enter the character , typed by holding down the CONTROL key while depressing the "U" key. When you are done editing, use the EX command to exit TECO, as described below in section 1.3.4. Standard TECO PAGE 9 Data Structure Fundamentals 1.2 DATA STRUCTURE FUNDAMENTALS TECO considers any string of ASCII codes to be text. Text is broken down into units of characters, lines, and pages. A character is one ASCII code. A line of text is a string of ASCII codes including one line terminator (usually a line feed) as the last character on the line. A page of text is a string of ASCII codes including one form feed character as the last character on the page. TECO maintains a text buffer in which text is stored. The buffer usually contains one page of text, but the terminating form feed character never appears in the buffer. TECO also maintains a text buffer pointer. The pointer is a movable position indicator which is never located directly on a character, but is always between characters: between two characters in the buffer, before the first character in the buffer, or after the last character in the buffer. Line feed and form feed characters are inserted automatically by TECO. A line feed is automatically appended to every carriage return typed to TECO and a form feed is appended to the contents of the buffer by certain output commands. Additional line feed and form feed characters may be entered into the buffer as text. If a form feed character is entered into the buffer, it will cause a page break upon output; text following the form feed will begin a new page. Finally, TECO maintains an input file and an output file, both of which are selected by the user through file specification commands. The input file may be on any device from which text may be accepted. The output file may be on any device on which edited text may be written. TECO functions as a "pipeline" editor. Text is read from the input file into the text buffer, and is written from the buffer onto the output file. In the VAX/VMS implementation, it is possible to "back up" as well as page forward in the file being edited. In other implementations, once text has been written to the output file, it cannot be accessed again without closing the output file and reopening it as an input file. Standard TECO PAGE 10 File Selection Commands 1.3 FILE SELECTION COMMANDS Input and output files may be specified to TECO in several ways. The following sections present first a simple method for specifying files, and then more sophisticated commands that permit flexible file selection. NOTE All of the following file selection commands are shown with a general argument of "filespec". The actual contents of this filespec argument are operating system dependent. See the operating characteristics appendices. Examples include a mixture of file specifications from various operating systems. 1.3.1 Simplified File Selection For most simple applications, you can use special operating system commands to specify the name of the file you wish to edit at the same time that you start up TECO. To create a new file: MAKE filespec This command starts up TECO and creates the specified file for output. To edit an existing file: TECO filespec This command starts up TECO and opens the specified file for editing while preserving the original file (as a backup file). It also automatically brings the first page of the file into the text buffer. These functions simulate the EB command described in Chapter 5. If any of the above commands do not seem to work on your operating system, consult the appropriate appendix for information about how to install TECO and its associated operating system commands. Standard TECO PAGE 11 File Selection Commands 1.3.2 Input File Specification (ER command) TECO will accept input text from any input device in the operating system. The input device may be specified by the text string supplied in the ER command (and which, like any text argument, is terminated by a character). The ER command causes TECO to open the specified file or print an error message if the file is not found. This command does not cause any portion of the file to be read into the text buffer, however. The following examples illustrate use of the ER command. COMMAND FUNCTION ERfilespec` General form of the ER command where "filespec" is the designation of the input file. The command is terminated by a character. ERPR:` Prepare to read an input file from the paper tape reader. ERPROG.MAC` Prepare to read input file PROG.MAC from the system's default device. ERDX1:PROG.FOR` Prepare to read input file PROG.FOR from DX1:. TECO will only keep one input and one output file open and selected at a time. The current input file may be changed by simply using the ER command to specify a new file. It is not always necessary to specify an input file. If you want to create a file without using any previously edited text as input, you may type commands to insert the necessary text directly into the text buffer from the keyboard and, at the end of each page, write the contents of the buffer onto an output file. Since all input is supplied from the keyboard, no input file is necessary. Standard TECO PAGE 12 File Selection Commands 1.3.3 Output File Specification (EW command) TECO will write output text onto any output device in the operating system. The output file may be specified by means of the text string supplied in an EW command. If the output device is a file-structured device (for example, a disk), the file name and any extension must be supplied. If a file name is specified but no device is explicitly specified, the system's default device is assumed. The following examples illustrate use of the EW command. COMMAND FUNCTION EWfilespec` General form of the EW command where "filespec" is the designation of the output file. The command is terminated by a character. EWSYS:TEXT.LST` Prepare to write output file TEXT.LST on SYS:. EWPROG` Prepare to write output file PROG on the system's default device. ERDX1:INPUT.MAC`EWOUTPUT.MAC`` Open an input file INPUT.MAC to be found on DX1: and open an output file named OUTPUT.MAC. The double (echoed as ``) terminates the command string and causes the string to be executed. Note that the which terminates the EW command may be one of the two s which terminates the command string. You do not need to specify an output file if you only want to examine an input file, without making permanent changes or corrections. In this case, the contents of the input file may be read into the text buffer page by page and examined at the terminal. Since all output is printed on the user terminal, no output file is needed. Standard TECO PAGE 13 File Selection Commands 1.3.4 Closing Files (EX command) When you are finished editing a file, use the EX command to close out the file and exit from TECO. The current contents of the text buffer and any portion of the input file that has not been read yet are copied to the output file before TECO exits. The EX command takes no arguments. COMMAND FUNCTION EX Write the text buffer to the current output file, move the remainder of the current input file to the current output file, close the output file, then return to the operating system. ERFILE.MAC`EWCOPY.MAC`EX`` Open an input file FILE.MAC and open an output file named COPY.MAC, then copy all the text in the input file to the output file, close the output file, and exit from TECO. Standard TECO PAGE 14 Input and Output Commands 1.4 INPUT AND OUTPUT COMMANDS The following commands permit pages of text to be read into the TECO text buffer from an input file or written from the buffer onto an output file. Once a page of text has been written onto the output file, it cannot be recalled into the text buffer unless the output file is closed and reopened as an input file. COMMAND FUNCTION Y Clear the text buffer, then read the next page of the input file into the buffer. Since the Y command causes the contents of the text buffer to be lost, it is not permitted if an output file is open and there is text in the buffer. P Write the contents of the text buffer onto the next page of the output file, then clear the buffer and read the next page of the input file into the buffer. nP Execute the P command n times. If n is not specified, a value of 1 is assumed. After each Y, P, or nP command, TECO positions the pointer before the first character in the buffer. Standard TECO PAGE 15 Pointer Positioning Commands 1.5 POINTER POSITIONING COMMANDS The buffer pointer provides the means of specifying the location within a block of text at which insertions, deletions or corrections are to be made. The following commands permit the buffer pointer to be moved to a position between any two adjacent characters in the buffer. COMMAND FUNCTION J Move the pointer to the beginning of the buffer. L Move the pointer forward to a position between the next line feed and the first character of the next line. That is, advance the pointer to the beginning of the next line. nL Execute the L command n times, where n is a signed integer. A positive value of n moves the pointer to the beginning of the nth line following the current pointer position. A negative value moves the pointer backward n lines and positions it at the beginnning of the nth line preceding the current position. If n is zero, the pointer is moved to the beginning of the line on which it is currently positioned. C Advance the pointer forward across one character. nC Execute the C command n times, where n is a signed integer. A positive value of n moves the pointer forward across n characters. A negative value of n moves the pointer backward across n characters. If n is zero, the pointer position is not changed. Remember that there are two characters, and , at the end of each line in the buffer. These commands may be used to move the buffer pointer across any number of lines or characters in either direction; however, they will not move the pointer across a page boundary. If a C command attempts to move the pointer backward beyond the beginning of the buffer or forward past the end of the buffer, an error message is printed and the command is ignored. If an L command attempts to exceed the page boundaries in this manner, the pointer is positioned at the boundary which would have been exceeded. Thus, in a page of 2000 lines, the command "-4000L" would position the pointer before the first character in the buffer. The command "4000L" would position the pointer after the last character in the buffer. No error message is printed in either case. Standard TECO PAGE 16 Type Out Commands 1.6 TYPE OUT COMMANDS The following commands permit sections of the text in the buffer to be printed out on your terminal for examination. These commands do not move the buffer pointer. COMMAND FUNCTION T Type the contents of the text buffer from the current position of the pointer through and including the next line feed character. nT Type n lines, where n is a signed integer. A positive value of n causes the n lines following the pointer to be typed. A negative value of n causes the n lines preceding the pointer to be typed. If n is zero, the contents of the buffer from the beginning of the line on which the pointer is located up to the pointer is typed. This is useful for verifying the location of the buffer pointer. HT Type the entire contents of the text buffer. V Type the current line. Equivalent to the sequence "0TT". Standard TECO PAGE 17 Type Out Commands 1.6.1 Immediate Inspection Commands [not in TECO-10] In addition, there are available as a convenience abbreviations of two frequently used type out commands. Each one consists of a single character, and must be the very first character typed after TECO prints its prompting asterisk. Each of these commands takes effect immediately; there is no need to follow any of these commands by any character. For this reason, these commands are known as "immediate" commands (see Chapter 4 for more information on immediate commands). COMMAND FUNCTION Immediately execute an LT command. This command is issued by typing the line feed key as the first keystroke after TECO's prompt. It causes TECO to move the pointer ahead one line and then type out the new line. On terminals without a line feed key, typing has the same effect. (See also the next command.) Immediately execute an LT command. (Action identical to that of the command above.) This command is available when an ESCape surrogate is active, and causes TECO to move the pointer ahead one line and then type out the new line when a is the first thing typed after TECO's prompting asterisk. [RSTS/E only] Immediately execute a -LT command. This command is issued by typing the backspace key as the first keystroke after TECO's prompt. It causes TECO to move the pointer back one line and then type the line just moved over on the terminal. On terminals without a backspace key, typing has the same effect. These commands are useful for "walking through" a file, examining and/or modifying lines one at a time. Standard TECO PAGE 18 Text Modification Commands 1.7 TEXT MODIFICATION COMMANDS You can insert or delete text from the buffer using the following commands: COMMAND FUNCTION Itext` Where "text" is a string of ASCII characters terminated by a character. The specified text is inserted into the buffer at the current position of the pointer. The pointer is positioned immediately after the last character of the insertion. K Delete the contents of the text buffer from the current position of the pointer up to and including the next line feed character. nK Execute the K command n times, where n is a signed integer. A positive value of n causes the n lines following the pointer to be deleted. A negative value of n causes the n lines preceding the pointer to be deleted. If n is zero, the contents of the buffer from the beginning of the line on which the pointer is located up to the pointer is deleted. HK Delete the entire contents of the text buffer. D Delete the character following the buffer pointer. nD Execute the D command n times, where n is a signed integer. A positive value of n causes the n characters following the pointer to be deleted. A negative value of n causes the n characters preceding the pointer to be deleted. If n is zero, the command is ignored. Like the L and C commands, the K and D commands may not execute across page boundaries. If a K command attempts to delete text up to and across the beginning or end of the buffer, text will be deleted only up to the buffer boundary and the pointer will be positioned at the boundary. No error message is printed. A D command attempting to delete text past the end or beginning of the text buffer will produce an error message and the command will be ignored. Standard TECO PAGE 19 Search Commands 1.8 SEARCH COMMANDS The following commands may be used to search the input file for a specified string of characters. COMMAND FUNCTION Stext` Where "text" is a string of ASCII characters terminated by a character. This command searches the text buffer for the next occurrence of the specified character string following the current pointer position. If the string is found, the pointer is positioned after the last character on the string. If it is not found, the pointer is positioned immediately before the first character in the buffer and an error message is printed. Ntext` Performs the same function as the S command except that the search is continued across page boundaries, if necessary, until the character string is found or the end of the input file is reached. If the end of the input file is reached, an error message is printed. On VAX/VMS, you can "back up" into the file and continue editing, although doing so uses TECO features beyond those introduced in this chapter. Using only basic features (or a TECO implementation other than VAX/VMS), you must close the output file and reopen it as an input file before you can edit the file further. Both the S command and the N command begin searching for the specified character string at the current position of the pointer. Therefore, neither command will locate any occurrence of the character string which precedes the current pointer position, nor will it locate any character string which is split across a page boundary. Both commands execute the search by attempting to match the command argument, character for character, with some portion of the buffer contents. If an N command reaches the end of the buffer without finding a match for its argument, it writes the contents of the buffer onto the output file, clears the buffer, reads the next page of the input file into the buffer, and continues the search. Standard TECO PAGE 20 Sample Editing Job 1.9 SAMPLE EDITING JOB The following sample editing job is included to help the new user to achieve a greater understanding of the basic TECO commands. The entire terminal output from the editing run is reproduced intact, with numbers added in the left margin referring to the explanatory paragraphs which follow. 1< *EWDT1:FILE1.TXT`` 2< *HKIMR. JOHN P. JONES ! COMPUTER ELECTRONICS CORPORATION ! BOSTON, MASAASACHUSETTS ! ! DEAR MR. JONES: ! ! I WAS PLEASED TO RECEIVE YOUR REQUEST FOR INFORMATION ! PERTAINING TO THE NEW TECO TEXT EDITING AND CORRECTING ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO USERS'S GUIDE, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! SINCERELY, ! ! ! ! ! `` 3< *-20LSETTS`I 02150`` ! *STION`2C13DIREGARDING`` 4< *SGUIDE`-5DIMANUAL`` ! *SELY`0T`` ! SINCERELY*0KIVERY TRULY YOURS`` ! *HT`` ! MR. JOHN P. JONES ! COMPUTER ELECTRONICS CORPORATION ! BOSTON, MASSACHUSETTS 02150 ! ! DEAR MR. JONES: ! ! I WAS PLEASED TO RECEIVE YOUR REQUEST FOR INFORMATION ! REGARDING THE NEW TECO TEXT EDITING AND CORRECTING ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO USER'S MANUAL, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! VERY TRULY YOURS, ! ! Standard TECO PAGE 21 Sample Editing Job ! ! ! 5< *EX`` ! (TECO is rerun, operating system dependent) ! *ERDT1:FILE1.TXT`EWLP:`` 6< *Y5KIMR. JAMES B. SMITH ! DATEK ASSOCIATES, INC. ! 122 MAIN STREET WEST ! AUSTIN, TEXAS ! ! DEAR MR. SMITH: ! `` ! *HT`` ! MR. JAMES B. SMITH ! DATEK ASSOCIATES, INC. ! 122 MAIN STREET WEST ! AUSTIN, TEXAS ! ! DEAR MR. SMITH: ! ! I WAS PLEASED TO RECEIVE YOUR REQUEST FOR INFORMATION ! REGARDING THE NEW TECO TEXT EDITING AND CORRECTING ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO USER'S MANUAL, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! VERY TRULY YOURS, ! ! ! ! ! ! *EX`` 1) At this point, the user called TECO into memory. TECO responded by printing an asterisk at the left margin. The user then entered an EW command, opening an output file called "FILE1.TXT" on DT1. There is no input file. Upon receipt of the double (echoed as ``), TECO created the designated output file, then printed another asterisk at the left margin. 2) The user entered a command string consisting of two commands. The HK command cleared the text buffer (not really necessary, since it was already empty), and the I command inserted 18 lines of text into the buffer, including 8 blank lines. TECO executed these commands upon receipt of the second double . At this point, the buffer pointer was positioned at the end of the buffer, following the last line feed character in the text. Note that the user made an error while typing the word "MASSACHUSETTS". He typed "MASA", then realized his mistake and Standard TECO PAGE 22 Sample Editing Job struck the DELETE key once to delete the second "A". TECO echoed the deleted character. The user then typed the correct character and continued the insertion. 3) The user typed -20L to move the pointer to the beginning of the buffer and SETTS` to position the pointer immediately after the character string "ETTS" (which terminates the word "MASSACHUSETTS"). He then used an I command to insert one space and a five-digit zip code. A second S command positioned the pointer after the word "INFORMATION". The 2C command moved the pointer to the beginning of the next line (carriage return and line feed count two characters), and the user deleted the words "PERTAINING TO" and replaced them with the word "REGARDING". 4) The user continued editing by positioning the pointer after the word "GUIDE". He then deleted this word, and replaced it with the word "MANUAL". Finally, he searched for the word "SINCERELY", typed 0T to determine that the pointer was correctly positioned between the Y and the comma which follows it, and typed 0K to delete everything on the line except the comma. He then inserted "VERY TRULY YOURS" in place of the word "SINCERELY". An HT command caused the edited text to be printed at the terminal. 5) The command string EX`` caused the contents of the buffer to be written onto the output file and the output file to be closed. The user then reentered TECO and reopened the file "FILE1.TXT" as an input file and specified the line printer as an output file. 6) This command string reads the first (and only) page of "FILE1.TXT" into the buffer, deleted the first 5 lines, replaced them with a different address and salutation, then printed the contents of the buffer on the terminal for verification and finally printed the new version of the letter onto the line printer. Note that the previous version of the letter still resides in file "FILE1.TXT" on DT1. Standard TECO PAGE 23 Interlude INTERLUDE The rest of this manual is a description of TECO in all its glory. TECO is a complex editor and has many features because it has been under development for a long time. (TECO is older than some of the readers of this manual!) Do not try to understand everything the first time through. If you find that what you are reading seems hopelessly obscure, or makes no sense whatsoever, skip to the next section and come back to it some time later. It will be a while before you need all of TECO's features. This manual is meant to be a reference manual and not a tutorial. Readers who are first learning TECO may wish to consult the following document (available from Digital Equipment Corporation) for more basic material: DEC-10-UTECA-A-D INTRODUCTION TO TECO. The commands described in this manual are those implemented in TECO-11 Version 40, TECO-8 Version 7, and TECO-10 Version 3. Some of the more obscure commands may not be present under some operating systems, in which case this is indicated by a note in the form [Not in TECO-x]. This manual also describes some (but not necessarily all) of the obscure commands that belong to one implementation of TECO but not to the other implementations. Such commands are flagged by a note of the form [TECO-x only]. These commands are not to be considered part of the so-called "Standard TECO" and should not be used in applications that may be run on multiple operating systems. Consult also the appendices for commands that are very operating system dependent. Standard TECO PAGE 24 Invoking TECO CHAPTER 2 INVOKING TECO 2.1 RUNNING TECO To run TECO with no special options or defaults, use the same command on your operating system that you would use to run any other program. The command is system dependent but is usually something like RUN TECO Consult the appendix that describes your operating system's characteristics for details. 2.2 CREATING A NEW FILE As described in Chapter 1, most operating systems use the same command to invoke TECO for the purpose of creating a new file: MAKE filespec The "MAKE filespec" command takes as its single argument the file specification for the file to be created. This file specification must conform to the conventions used by your operating system. If a file by that name already exists, TECO will give you a warning message telling you that you are superseding an existing file. The MAKE command invokes TECO and performs an effective EWfilespec`` command, as described in Chapter 1. 2.3 EDITING AN EXISTING FILE As Chapter 1 states, most operating systems use the same command to invoke TECO for the purpose of editing an existing file: TECO filespec The "TECO filespec" command takes as its argument the file specification for the file to be edited. The file will be opened for input and output, with back-up protection. That means that the system will save the original version of the source file (in case you 'blow' the edit). If your operating system supports file version numbers, a new version will be created. If your operating system does not support file version numbers, the original file will be preserved in a file with the same name but with a backup extension (.BAK). Standard TECO PAGE 25 Editing an Existing File The TECO command invokes TECO and performs an effective EBfilespec`Y`` command. Note that the first page of the file is brought into memory and that the text buffer pointer is positioned at the start of the file. If, at any time during the edit, you discover that the edit is invalid, slowly (so TECO can respond to them) type enough s to get you back to the operating system. You will find that your original file has been preserved. TECO remembers the filespec given in a MAKE or TECO command. If TECO is invoked with the command "TECO", with no filespec, it will open the file edited last (i.e., the remembered filespec). 2.4 SWITCHES ON TECO and MAKE COMMANDS The TECO and MAKE commands can take switches (qualifiers) of the form /SWITCH. These switches are described below. SWITCHES ON COMMAND LINES System Switch Meaning RSTS/E /SIZE:n start with nK word editing area /SIZE:+n start with nK additional words of editing area RSTS/E RSX-11 VAX/VMS /INSPECT Do not create an output file /FIND Initially position to the position marker left in the file by the VTEDIT macro and delete the marker. /NOCREATE Do not automatically create a new file if the file specified by the TECO command does not exist. /NOINI Do not use TECO.INI to perform initialization /NOMEMORY Do not remember the argument to the invocation command. /SCROLL Automatically enter split screen scrolling mode, using 1/4 of the screen's lines as the scrolling area (available on VT100 terminals only). /VTEDIT Load VTEDIT video terminal editor The /SCROLL switch may take a value of the following form: /SCROLL:n Enter split screen scrolling mode, using n lines for the scrolling area. Standard TECO PAGE 26 Switches on TECO and MAKE Commands The /VTEDIT switch may also take values (of the form :value). /VTEDIT:HOLD Start up in hold screen mode /VTEDIT:SEEALL Start up in SEEALL mode These values can be combined, viz.: /VTEDIT:HOLD:SEEALL. 2.5 INVOKING A TECO PROGRAM All operating systems except TOPS-10 and TOPS-20 use the same command to let you start up execution of a TECO program (macro). This is the MUNG command. The MUNG command has the form MUNG filespec where filespec is the name of the TECO program that is to be run. If no file extension (file type) is specified, .TEC is assumed. This command executes the TECO code that appears within the specified file. It invokes TECO and performs an effective EIfilespec`` command (consult the appendices for operating-system dependent differences). The contents of the specified file should generally end with a double ESCAPE so that execution will start immediately. Another form of this command is MUNG filespec,data where "data" is any string of ASCII characters to be passed to the TECO program. This version of the MUNG command invokes TECO and issues an effective Idata`EIfilespec`` command. Under TECO-11, a space, tab, or a slash (/) may be used instead of the comma. Standard TECO PAGE 27 Invoking a TECO Program 2.6 USER INITIALIZATION You can specify initialization commands to TECO by creating a file called TECO.INI. If, upon start-up, TECO finds a file called TECO.INI in your area, TECO executes the commands in that file. You can use TECO.INI commands to set initial values of flags and to tailor TECO to your needs. You must, however, be very careful in constructing code for your TECO.INI file: an error in this code may keep TECO from running at all! If you include unusual commands in your initialization file, you would be prudent to surround such commands with the ? command. This causes TECO to type the commands out when they are executed (see section 5.18.4). You should also print an informative message on the terminal reminding other users that this version of TECO has been customized. Example 1: ?1ED? The user initialization file sets the ED flag to 1 so that ^ characters in search strings have their traditional meaning (do not convert the next character to a control character). The file also causes the command to be typed out when it is executed. Example 2: 0,16ED ^A[Dot preserved on failing searches]^A 13^T 10^T The user initialization file causes future search string failures to preserve the pointer position. It also prints a message informing all users of this feature. Standard TECO PAGE 28 User Initialization In TECO-11, the TECO.INI commands may return a value to the command processor. Such a value, if present, is interpreted as a set of bit encoded flags that control the startup processing. The following bits may be set: Value&1 Automatically load the VTEDIT macro (as if the user had typed TECO/VTEDIT). Value&4 Inhibit use of the memory file (as if the user had typed TECO/NOMEMORY). Value&16 Automatically load VTEDIT and start it in SEEALL mode (as if the user had typed TECO/VTEDIT:SEEALL). Value&32 Automatically load VTEDIT and start it in HOLDSCREEN mode (as if the user had typed TECO/VTEDIT:HOLD). Value&128 Automatically enter split screen scrolling mode (as if the user had typed TECO/SCROLL). Value&256 Inhibit automatic creation of the output file if the input file does not exist (as if the user had typed TECO/NOCREATE). For additional information on initialization, consult the operating system specific appendices. Standard TECO PAGE 29 Conventions and Structures CHAPTER 3 CONVENTIONS AND STRUCTURES 3.1 TECO CHARACTER SET TECO accepts the full 8-bit ASCII character set. (In other than TECO-11, characters typed at the console have their 8th bit trimmed off. If your terminal does not transmit or receive all of the ASCII codes, you can still insert the full character set into your TECO buffer, using special commands (see section 5.6). For more information on TECO's handling of 8-bit characters (including on terminals capable of displaying only 7-bit data), see the description of the 4096 ET bit, in section 5.16. When TECO is maintaining a window into the text buffer, a special facility (called "SEEALL" or "View All" mode) is available to explicitly show certain characters which normally do not print, such as , , and . This mode is controlled by the 3:W flag, which is described in section 5.17. TECO command strings may be entered using upper case characters (as shown throughout this manual) or lower case characters. For example, the commands MQ, mQ, Mq, and mq are executed identically. A file containing upper and lower case text can be edited in the same way as a file containing upper case only, although this may be clumsy to do from an upper case only terminal. TECO can be set to convert lower case alphabetics to upper case as they are typed in; commands to enable or disable lower case type-in will be presented in section 5.16. Control characters are generally echoed by TECO as a caret or up-arrow followed by the character. Some control characters, such as (form feed) and (bell) echo as the function they perform. In many cases, you can type a control character as a caret (up-arrow) followed by a character, and it will be treated as if it had been entered using the control key. There are exceptions to the interchangeable use of the CONTROL key and the caret. When a control character is used as the delimiter of a text string (as explained in Section 3.2.2 below), it must be entered in its form. This form must also be used if the control character is the second character of a two-character command, or is being entered as an immmediate action command. Since certain control characters have special meaning in text arguments, some of them (such as and ), must be entered into a text string using the CONTROL key and preceded by , ^Q, , or ^R. Standard TECO PAGE 30 Conventions and Structures 3.2 TECO COMMAND FORMAT Each TECO commands consists of one or two characters. TECO commands may be strung together (concatenated) into a command string. If a command in the string returns numeric value(s), it or they will be passed to the following command. NOTE Most commands which return a value are expressly designed for that purpose. A few commands (such as n%q and m,n:W, q.v.) can be used to cause an action, and also return a value. Good programming practice suggests following such a command with or caret-[ if the returned value is not intended to affect the following command. A TECO command may be preceded by one or two numeric arguments. Some TECO commands may be followed by a text argument. Many TECO commands can be modified by "@" (see section 3.2.2) and/or by ":" (see section 3.2.3). When TECO commands are concatenated into a command string, no delimiter is necessary between commands except for one necessary to delimit a text argument or one as suggested in the note above. TECO commands are accumulated into a command string as they are typed. The command string is executed when it is terminated by typing two consecutive characters. TECO then executes the commands in the order in which they appear in the command string, until the string is exhausted or an error occurrs. (Some TECO commands cause branching or looping, so altering the order of execution.) TECO's character is (internally) the ESCape (octal 33). Because newer terminals use the ESCape character as part of control sequences (and some terminals no longer even possess an ESCape key), provision is made for you to designate a key on your terminal to cause an ESCape to be sent to TECO -- that is, to act as an ESCape surrogate. (See the EE flag and the 8192 ET bit, section 5.16.) Because the key you press to delimit text strings and TECO commands may be the ESCape key or may be the surrogate, this manual uses the indirect term to mean whichever one you are using. When an ESCape surrogate is active, the character you see is `. (When no surrogate is active, you see $.) This manual uses the ` character. Standard TECO PAGE 31 Conventions and Structures 3.2.1 Numeric Arguments Most TECO commands may be preceded by a numeric argument. Some numeric arguments must be positive; others can be negative or zero. The maximum size of any numeric argument is restricted, as summarized in the following table: Signed Unsigned System Min Max Max TECO-8 -2**12+1 +2**12-1 2**13-1 TECO-10 -2**34 +2**34-1 2**35-1 TECO-11 -2**15 +2**15-1 2**16-1 TABLE 3-1 Restrictions on numeric arguments Exceeding these ranges of values can cause unpredictable results. So can using a negative argument with a command that takes only an unsigned argument. Numeric arguments can be used in the following ways: - Character commands such as J, C, R, and D take a single numeric argument which represents the number of characters that the command is to act on. - Such commands as P, PW, and < perform an action that can be repeated. The numeric argument is the repetition count. - Some commands, such as ED, ET, ^E, ^X, ES, EU, and EV, control the setting of variables called flags. When a numeric argument is specified, the value of that argument becomes the new value of the associated flag. When no numeric argument is specified, these command return the value of the associated flag. - Line commands such as T, K, X, FB, and FC operate on lines. They take zero, one, or two numeric arguments. If one argument (n) is specified, it represents the number of lines over which the command is to have effect, beginning at the current buffer pointer position. A positive (non-zero) n affects a text running from the current pointer position to the nth following line delimiter. A negative n affects a text running from the pointer back to the beginning of the line containing the nth previous line delimiter. When n is zero, the affected text runs from the beginning of the current line to the current pointer position. When n is omitted, n = 1 is assumed. When a line command contains two numeric arguments (m,n), these represent the pointer positions between which text is affected. Unless the description of the Standard TECO PAGE 32 Conventions and Structures command says the order of these two arguments is important, they may be entered in either order. When a command that normally takes an argument is specified with no argument, TECO executes the command in the most common or most useful way, as shown in the following table: Command Default Argument Default Action C 1 Advance 1 character R 1 Back over 1 character L 1 Advance 1 line J 0 Jump to start of buffer V 1 View 1 line D 1 Delete 1 character K 1 Kill 1 line S, N, etc. 1 Search for first occurrence % 1 Increment Q-register by 1 X 1 Extract one line Table 3-2 Default Arguments These default arguments reduce the number of keystrokes needed for common TECO actions. 3.2.2 Text Arguments Many TECO commands take a text (character string) argument. The string is placed immediately after the command and consists of a sequence of ASCII characters terminated by a character (or in the case of ! and ^A commands, by the command character). The string of ASCII characters may not include a , since this would terminate the string prematurely, but may include any other character. (Some characters may be difficult to enter from a terminal because they are TECO immediate action commands or because they have been filtered out by the operating system). Examples of text arguments: Sabc` Search for the string "abc" ^UAHELLO` Insert the text "HELLO" into Q-register A OBEGIN` Branch to the tag specified by the string "BEGIN" Some TECO commands require two text arguments. Each argument must be followed by a character, as follows: FSabc`def` Replace string "abc" by "def" Standard TECO PAGE 33 Conventions and Structures You can include a character in a text string by using another format of text argument. In this alternate form, the string is delimited on both sides by any ASCII code that does not otherwise appear in the string. You signal that this format is being used by inserting an @ character before the command, as follows: @ER5TEST.FOR5 Open the file "TEST.FOR" for input. The delimiter used is "5" @^A+Hello out there!+ Type the message "Hello out there!" on the terminal. The delimiter is "+" Unpredictable results will occur if another TECO command intervenes between an @ sign and the command that it is supposed to affect. Note that a control character used as a delimiter must be entered as (that is, in its single-keystroke form). 3.2.3 Colon Modifiers The colon (:) command modifies the action of the next command. In some cases, it will cause the next command to return a value indicating whether it has failed or succeeded. A zero (0) indicates that the command has failed, while a -1 indicates that it has succeeded. The colon modifier is used this way with such commands as :ER, :EB, :EN, :S, :N, :FS, :FN, :FB, and :FC. If the next sequential command requires a positive argument, the -1 is interpreted as the largest possible positive number. In other cases, such as :Gq and :=, the colon modifier changes the meaning of the command. Unpredictable results may occur if you place a colon directly before a TECO command that does not normally accept a colon modifier. If both the : and the @ (string delimiter) are used with the same command, they may be placed in either order. Standard TECO PAGE 34 Conventions and Structures 3.3 DATA STRUCTURES A good way to begin the study of a programming language is to forget the commands, for the moment, and concentrate instead on the data structures. This section follows that approach, describing both the values on which TECO operates and the buffers and registers in which these values are stored. TECO manipulates two types of data, namely, o The character string: a sequence of zero or more ASCII characters, and o The integer: a numeric value that may be signed or unsigned. The text that TECO edits is, of course, a character string. Less obviously, the command string by which the user controls TECO is also a character string. The counters and indices for character string manipulation, and the repetition counts for loops are integers. Character strings and integers have distinct internal representation and this is reflected in the design of the TECO commands. Commands designed for character strings do not work on integers and vice versa. The data structures described in this section are frequently applied to character strings. Structure is never "built into" the data, but rather is attributed to the data by particular commands and conventions. Thus "lines" of characters are recognized by line manipulation commands, but not by character manipulation commands, which view an end-of-line character as just another ASCII code. The following are definitions for the line and the page in TECO: o Any character string can be divided into TECO lines by considering the line to be ended by either a line feed (octal 12) a form feed (octal 14) a vertical tab (octal 13) or the end of the given character string o Any character string can be divided into TECO pages by considering the page to be ended by either a form feed (octal 14) or the end of the given character string Standard TECO PAGE 35 Conventions and Structures These data structures are used to achieve two quite separate results: the formatting of type out and the logical division of data. 3.3.1 Text Buffer The main storage of TECO is the text buffer. The text buffer stores a single character string that TECO edits. A text buffer pointer is used to address text in the buffer; it is moved about by many TECO commands. The text buffer pointer never points to characters in the buffer; it is always pointing at pointer positions (between characters). The available pointer positions in the text buffer are sequentially numbered beginning with 0. Pointer position 0 is the position at the start of the buffer, just to the left of the first character. Pointer position 1 is the next position, just to the right of the first character, etc. As an example, suppose the text buffer contains the string FOOBAR. Then seven text buffer pointer positions are determined as shown by the arrows in the following figure: F O O B A R | | | | | | | 0 1 2 3 4 5 6 Note that there are 6 characters in the buffer and that the highest numbered pointer position is 6. The pointer position number is equal to the number of characters preceding that position. Useful definitions of "current" objects are made with respect to the text buffer pointer as follows: 1. The current character of the text buffer is the character just to the right of the pointer. If the pointer is at the end of the text buffer, there is no character to the right of the buffer pointer, and the current character does not exist. 2. The current line of the text buffer is the TECO line that contains the current character. In the special case that the pointer is at the end of the buffer, the current line is everything back to (but not including) the last end-of-line character. 3. The current page of the text buffer is the TECO page that contains the current character. In the special case that the pointer is at the end of the buffer, the current page is everything back to (but not including) the last form feed character (or the beginning of the buffer). Standard TECO PAGE 36 Conventions and Structures When the text buffer pointer is at the end of the text buffer and the last character of the buffer is an end-of-line character, then the current line is an empty string according to the definition just given. In this case, TECO performs the required operation on this empty string. For example, if the pointer is at the end of the buffer and TECO is commanded to kill (delete) the next 3 lines, then the empty string is killed 3 times. Similarly, if the pointer is at the end of the buffer and TECO is commanded to advance the pointer 5 lines, the pointer will remain at the end of the buffer. No error message will be given. In a like fashion, if the pointer is at the end of the first line of the buffer, and TECO is instructed to extract the previous 4 lines (into a Q-register), then only the first line is extracted since it is presumed to be preceded by 3 empty lines. 3.3.2 Q-registers TECO provides data storage registers, called Q-registers, which may be used to store single integers and/or ASCII character strings. Each Q-register is divided into two storage areas. In its numeric storage area, each Q-register can store one signed integer. In its text storage area, each Q-register can store an ASCII character string (which can be any text, including the important case of a TECO command string). There are global Q-registers and (in TECO-11) local Q-registers. In every TECO, there are 36 global Q-registers, each of which has a one-character name: A through Z and 0 through 9. The global Q-registers are available to all macro levels, including "outside" macros altogether (that is, at prompt level). In TECO-11, there are additionally 36 local Q-registers, each of which has a two-character name: .A through .Z and .0 through .9. Effectively, there is a complete and unique set of local Q-registers available to each and every macro level, including prompt level. TECO automatically saves and restores a given macro level's local Q-registers around execution of a nested (lower level) macro. When a macro is invoked via an Mq command (where the command is not colon-modified, and q is a global Q-register), the current set of local Q-registers is saved and a new set of local Q-registers created. When the macro exits, its local Q-registers are destroyed and those of the calling macro level are restored. (If a fatal error occurs and TECO goes back to prompt level, local Q-registers from all macro levels are destroyed and prompt level's set is restored.) (A new set of local Q-registers is not created when the command is colon-modified, as in :MA, or when the invoked macro itself resides in a local Q-register, as in M.A -- see Table 5-9C.) Standard TECO PAGE 37 Conventions and Structures A local Q-register name can be used in any command that takes a Q-register name. Various TECO commands allow the storing and retrieving of numeric values from the numeric storage areas of the Q-registers. Other TECO commands allow the storage and retrieval of strings from the text storage areas of the Q-registers. 3.3.3 Q-register Push-down List [not in TECO-8] The Q-register pushdown list is a stack that permits the numeric and text storage areas of Q-registers to be saved (the [ command) and restored (the ] command). The command sequence [A ]B replicates the text string and numeric value from Q-register A into Q-register B. (Note that in TECO-11, macros can be written to use local Q-registers, avoiding the need to save and restore Q-registers via the pushdown list.) 3.3.4 Numeric Values and Flags TECO has many special numeric values and flags which are accessible through TECO commands. Some of these values, such as the text buffer pointer, reflect the state of TECO. Others control TECO's behavior in various ways. Standard TECO PAGE 38 Command String Editing CHAPTER 4 COMMAND STRING EDITING 4.1 Immediate Action Editing Characters While you are typing command strings at a terminal, TECO considers certain ASCII characters to have special meaning. Most of the special characters cause TECO to perform a specified function immediately, without waiting for the double which normally be required to terminate a command string. Immediate action editing characters may be entered at any point in a command string - even in the middle of a command or text argument. Many immediate action editing characters, such as (which deletes the immediately preceding character), cannot be used as regular TECO commands. For instance, if you enter a into a command string which is to be later executed as a macro, the will not delete a character as part the execution of the macro. Some characters, like , are both regular TECO commands and immediate action commands. The command string ^Uqtext` enters the specified text into Q-register q. However, typed while entering a command string is an immediate action editing character which deletes the current line. Thus you cannot type a (or any similar sequence) directly into TECO as part of a command string. Nevertheless, is still a valid TECO command; should TECO encounter it in a macro or indirect file, it will have its regular TECO effect (^Uqtext`). Control characters used as immediate action editing characters must be entered using the CONTROL key; they will not be recognized if entered in their caret or up-arrow form. Table 4-1 lists the immediate action editing characters and explains their functions. Standard TECO PAGE 39 Command String Editing TABLE 4-1: IMMEDIATE ACTION EDITING CHARACTERS These characters take immediate effect and are used to edit a command string as it is being entered: CHARACTER EXPLANATION The double character sequence tells TECO to begin execution of the command string just typed in. It inserts two s into the command string. ( may be generated by pressing a key designated by the user as an "ESCape surrogate" or by pressing an actual ESCape key. In the former case, `` is echoed; if no ESCape surrogate has been designated, $$ is echoed. See the EE flag and the 8192 ET bit, section 5.16, for more information.) The two s must be typed successively. If any other character is typed in between the two s (even if subsequently DELETEd), then the two s might be treated simply as two s to be entered into the command string rather than as an immediate action command. If you need to enter two s into a command line, as in the case where you want to use the FSstring`` command to delete a string, you can keep TECO from recognizing `` as an immediate action command. Type and then continue entering the remainder of your command string. A single character can also be an immediate action command (when typed immediately after TECO's prompting asterisk, see section 4.2). Elsewhere, a single performs no immediate action. Typing a DELETE character (DEL or RUBOUT on some terminals) deletes the last character typed. DELETE can be typed repeatedly to erase multiple characters. TECO echoes the deleted character whenever a DELETE is typed, indicating to you that the character has been rubbed out. If you are doing your editing on a scope terminal, then the action of this key is different: the character that has been rubbed out will disappear from the screen of your editing terminal and the cursor will be moved back one position. If you delete a line feed, form feed, or vertical Standard TECO PAGE 40 Command String Editing tab, the cursor will move up the screen and position itself at the end of the text that immediately preceded the line feed, form feed, or vertical tab. echoes as ^C (Caret-C) and aborts the entering of the command string. The exact action of the key depends on the operating system being used (See appendices). causes the current line of the current command line to be deleted. TECO echoes the character as ^U followed by and an asterisk prompt. If you are using a scope terminal, the visible action of typing this key is different. The current line physically disappears from the screen and the cursor is positioned back at the beginning of the line. Typing two consecutive characters causes all commands which have been entered but not executed to be erased. (If the terminal has a bell, it will ring.) This command is used to erase an entire command string. A single character is not a special character. followed by a space causes the line currently being entered into the command string to be retyped. * followed by an asterisk causes all the lines typed by the user from the last TECO prompt (the asterisk) to be retyped. Typing a carriage return enters a carriage return followed by a line feed into the command string. To enter a carriage return without a line feed, type . RSX-11 TECO uses the triple command as an immediate action command. See the appropriate appendix for more details. The character is used as an end-of-file terminator in some contexts on some operating systems. While its presence is usually harmless in disk files, it may cause premature end of file if the file is copied to other media (e.g., paper tape). Standard TECO PAGE 41 Command String Editing 4.2 Immediate Action Commands TABLE 4-2: IMMEDIATE ACTION COMMANDS The following commands take effect if (and only if) they are typed as the very first keystroke(s) after TECO issues its asterisk prompt. The , , and commands are also described in Chapter 1, where they are introduced as "immediate inspection commands". CHARACTER EXPLANATION ? If the previous command aborted because of an error, this immediate action command causes TECO to print the erroneous command string from the beginning of the current macro level up to and including the character that caused the error. / If TECO has just printed an error message, type this immediate action command to receive a more detailed explanation of the error. (On VAX/VMS, a HELP command is also available. See section G.13.) [In TECO-11, implemented only on VAX/VMS] Typing this immediate action command, line feed, as the first keystroke after TECO's prompt causes TECO to immediately execute an LT command. This aid lets you "walk through" a file on a non-scope terminal. (If the EV flag is non-zero, then the T portion of this command is redundant and therefore is not performed.) If you are already positioned at the end of the text buffer, TECO-11 will not type out anything. [Not in TECO-10] Typing this immediate action command, , is synonymous with typing the immediate action command (described above). This command is available on TECOs offering the ESCAPE surrogate. [TECO-11 only] Typing this immediate action command, backspace, (as the first keystroke after TECO's prompt) causes TECO to immediately execute a -LT command. (If the EV flag is non-zero, then the T portion of this command is redundant and therefore is not performed.) [Not in TECO-10] ^W Typing this immediate action command, , as Standard TECO PAGE 42 Command String Editing the first keystroke after TECO's prompt when split-screen scrolling is active causes TECO to re-paint the buffer display portion of the screen. (Split-screen scrolling is active when 7:W is non-zero.) This command is useful if the display has been "confused" by characters from a broadcast message or type-ahead. It is also useful in conjunction with ED's 128 bit (which inhibits all automatic scroll display updating). [TECO-11 only] *q When an asterisk followed immediately by a Q-register name (any alphanumeric character, here represented by q) is the first keystroke after TECO's prompt, TECO places the previous command string into Q-register q. [In TECO-8, only the *Z command is permitted, and TECO will automatically type the Z.] Note that since *q is itself an immediate action command, it may not be edited with other immediate action commands. In other words, you can't use DELETE to delete an incorrectly typed *. [In TECO-10, *q must be followed by .] Standard TECO PAGE 43 Command String Editing 4.3 Introduction to Macros One of TECO's powerful features is the ability to execute ASCII text stored in a Q-register as a command string. This is called the "macro" facility, and a command string so stored and executed is called a "macro". A Q-register may be loaded with a macro by any of several means: directly from the console (via the ^Uq command), by extraction from the text buffer (via the X command), or by these or other Q-register loading commands contained in an indirect file or even in another macro. Particularly handy is the "*" immediate action command, discussed in a preceding section. When you type this command as the first character following TECO's asterisk prompt, whatever immediately preceding command you just typed at the console is saved in a Q-register. You can then use that command again (and repeatedly) by using the Mq command. You invoke a macro by using the Mq command, where "q" is the name of the Q-register in which the macro text has been stored. A related facility is that of immediate ESCAPE-sequence commands, which is discussed in the following section. Standard TECO PAGE 44 Command String Editing 4.4 Immediate ESCAPE-Sequence Commands [TECO-11 only] Certain keys on many newer terminals generate ESCape sequences. TECO provides a facility by which you can cause the pressing of one of these keys at the prompting asterisk to be interpreted as an immediate command. When this facility is enabled, a key such as one of the cursor control keys can cause TECO to immediately execute commands (previously stored as a macro). The single keystroke suffices; no is needed. The 32 bit in the ED flag enables immedate ESCape-sequence commands. When ED's 32 bit is non-zero, and the first character TECO receives after its * prompt is ESCape, TECO will automatically read further characters and attempt to decode an ESCape sequence. The decoded ESCape sequence is resolved into a pair of numeric values, which are then passed to the macro residing in global Q-register A. The two numeric values are a type code and a value code. They are passed to the macro in QA by an effective ,MA``. The macro in QA can retrieve them by code such as: UA ! Save the code in QA ! @O!T0,T1,T2,T3! ! Dispatch on code ! !T0! ! Type 0 codes come here ! QA@O!V0,V1,V2... The and codes are as follows. Type 0 - ESCape followed by a control character The code is the control character's code (0 - 31.) Type 1 - ESCape followed by a letter (e.g., ESC A), -or- ESCape followed by [ then a letter (e.g., ESC [ A), -or- CSI followed by a letter (e.g., CSI A), -or- ESCape, O, then an uppercase letter (e.g., ESC O A) The code is the letter's ASCII value, trimmed to 5 bits (that is, a value of 0 through 31) Common keys of 1 are: Up arrow 1 1 Down arrow 1 2 Left arrow 1 4 Right arrow 1 3 PF1 1 16 PF2 1 17 PF3 1 18 PF4 1 19 ENTER 1 13 Standard TECO PAGE 45 Command String Editing Type 2 - ESCape followed by ? then a letter (e.g., ESC ? p), -or- ESCape, O, then an lowercase letter (e.g., ESC O p) The code is the letter's ASCII value, trimmed to 5 bits (that is, a value of 0 through 31) Common keys of 2 are: Keypad , 2 12 Keypad - 2 13 Keypad . 2 14 Keypad 0 2 16 Keypad 1 2 17 Keypad 2 2 18 Keypad 3 2 19 Keypad 4 2 20 Keypad 5 2 21 Keypad 6 2 22 Keypad 7 2 23 Keypad 8 2 24 Keypad 9 2 25 Type 3 - ESCape followed by [ then a digit string then ~ -or- CSI followed by a digit string then ~ The code is the value of the digit string. All of the LK201 keyboard's editing and function keys generate sequences of this format. Standard TECO PAGE 46 Command String Editing 4.5 Operating System Character Filters In general, TECO accepts any ASCII character, whether encountered in a macro, read from an indirect file, or entered directly via a command string from the terminal. (Note that TECOs other than TECO-11 strip the eighth bit on command input.) In addition, some operating systems filter out certain characters typed at a terminal and do not pass them to TECO. So that you can be aware of the possible difficulty of entering these characters directly into a TECO command string, we list them below in Table 4-5. Note that these characters are still valid characters to TECO, but may have to be entered indirectly, such as by using the nI` command. ^T Note: On some operating systems, the ^T character is an immediate action command (to the operating system), and invokes a one-line status report. Where reference is made below in Table 4-5 to this note, TECO causes the operating system's recognition of ^T to be turned off if TECO ever asks the user for input. The original state of ^T handling is restored upon exit. MUNGed TECO macros that never ask the user for input do not affect the operating system's handling of ^T. Standard TECO PAGE 47 Command String Editing TABLE 4-5: OPERATING SYSTEM CHARACTER FILTERS SYSTEM CHARACTER SYSTEM's USE RT-11 ^A VT11 support [only if GT ON] ^B Background control [F/B systems only] ^E VT11 support [only if GT ON] ^F Foreground control [F/B systems only] ^O Output control ^Q Terminal Synchronization ^S Terminal Synchronization RSTS/E ^O Output control ^Q Terminal Synchronization ^S Terminal Synchronization VAX/VMS ^O Output control ^Q Terminal Synchronization ^S Terminal Synchronization ^T System status (see ^T Note above) ^X Cancel Type-ahead ^Y Process Interruption RSX-11 ^O Output control ^Q Terminal synchronization ^S Terminal synchronization ^X Task control [RSX-11D only] TOPS-10 ^C^C Job interruption ^O Output control ^Q Terminal synchronization ^S Terminal synchronization ^T System status TOPS-20 ^C^C Job interruption ^O Output control ^Q Terminal synchronization ^S Terminal synchronization ^T System status OS/8 ^B Background control [F/B systems only] ^F Foreground control [F/B systems only] ^Y Reboot indicator [F/B systems only] Standard TECO PAGE 48 Command Descriptions CHAPTER 5 COMMAND DESCRIPTIONS This chapter presents a detailed description of the full TECO command set, functionally organized. It assumes that the reader is familiar with the elementary TECO commands presented earlier. In the sections following, the letters "m" and "n" are used in command formats to represent numerical arguments. These may be either simple integers or complex expressions. The letter "q" represents any Q-register. Standard TECO PAGE 49 File Selection Commands 5.1 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 "streams" called the primary and 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 1. 5.1.1 File Opening Commands The following commands are used to open files for input and output: TABLE 5-1A: FILE SPECIFICATION COMMANDS COMMAND FUNCTION EBfilespec` 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 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). ERfilespec` Edit Read. Opens a file for input on the currently selected input stream. Standard TECO PAGE 50 File Opening Commands EWfilespec` Edit Write. Opens a file for output on the currently selected output stream. :EBfilespec` Executes the EB command, and returns a numeric value. -1 returned indicates success: the file is open for input. A 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. :ERfilespec` Executes the ER command, and returns a numeric value. See the :EB command, above. Standard TECO PAGE 51 File Specification Switches 5.1.2 File Specification Switches Various system-dependent switches (qualifiers) of the form /SWITCH can be used with the file specification in ER, EW, and 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 or & characters for program line continuation. See Appendix J for more information. TABLE 5-1B: SWITCHES ON FILE SPECIFICATIONS System Switch Meaning OS/8 /S Ignore end-of-file (s) on input. (SUPER TECO mode) RSTS/E /B Read and write with unfiltered 8-bit /n Handle BASIC-PLUS-x line continuation /B+ Handle BASIC-PLUS line continuation / Same as /B+ /B2 Handle BASIC-PLUS-x line continuation /CLUSTERSIZE:n Specifies output file cluster size /MODE:n Use non-standard open mode VAX/VMS, /B2 Handle BASIC-PLUS-x line continuation RSX-11 /CR Implied carriage control /-CR No (internal) carriage control /FT FORTRAN carriage control /FTN Same as /FT /RW Rewind magtape before opening file /SH Open the file in shared mode /SHR Same as /SH /STM Stream format /VAR Variable format TOPS-10 /APPEND Append to existing output file (EW only) /ASCII File is ASCII /GENLSN Generate line sequence numbers /NOIN Don't put user type-in into log file /NONSTD Open DECtape in non-standard mode /NOOUT Don't put TECO's type out into log file (EL only) /OCTAL Read file in octal /PROTECT:n Specify protection code /SIXBIT Read file in pure SIXBIT /SUPLSN Suppress line sequence numbers 5.1.3 File Close and Exit Commands Standard TECO PAGE 52 File Close and Exit Commands The following commands are used to close files and exit from TECO: TABLE 5-1C: FILE CLOSE AND EXIT 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. EC leaves the text buffer empty. EF Closes the current output file on the currently selected output stream. The EF command does not write the current contents of the buffer to the file before closing it. EG` Performs the same function as the EC command, but then exits from TECO and re-executes the last COMPIL class command (.COMPILE, .LINK, .EXECUTE, etc.) [Same as EX in TECO-11] EGtext` Performs the same function as the EC command, but then exits from TECO and passes "text" to the operating system as a command string to be executed (see appendices). :EGcmd args` Performs operating system function "cmd" passing that function "args" as arguments. This command always returns a value as follows: -1 Function "cmd" successfully performed. 0 Function "cmd" is unsupported. Other Function "cmd" attempted, but failed. The returned value is the failure status. There are four functions that are commonly defined: INI Locates the user's private initialization TECO macro. LIB Defines the user's private library of TECO macros. MEM Read/write TECO's last edited file memory. VTE Locates the user's private scope editing TECO macro. These four functions work as follows: :EGcmd` Loads Q-register * with the Standard TECO PAGE 53 File Close and Exit Commands requested information. If there is no information (e.g., no user private scope editing TECO macro) then Q-register * is set to the null string. :EGcmd ` Clears the information holder. Subsequent :EGcmd` commands will set Q-register * to the null string. :EGcmd text` Sets the information holder to "text". Subsequent :EGcmd` commands will set Q-register * to "text". Consult the appendices for details. 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 EK command after an EW which is superseding an existing file leaves the old file intact. The EK command also "undoes" an EB command. (See appendices for details.) ELfilespec` Open the specified file for output as a log file. Any currently open log file will be closed. If the /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 EX and TECO commands. [TECO-10 only] EX Performs the same function as the 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 HKEX. EZfilespec` 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 EW command. [TECO-10 only] The (caret/C) command terminates execution of the current command string and Standard TECO PAGE 54 File Close and Exit Commands returns control to TECO's prompt. (Under TECO-8, the command currently acts as .) The ^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 may not be entered in up-arrow mode. 5.1.4 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: TABLE 5-1D: SECONDARY STREAM COMMANDS [Not in TECO-8 or TECO-10] Input commands (do not open or close any file; do not change the text buffer): EP Switches the input to the secondary input stream. ER` Switches the input to the primary input stream. Output commands (do not open or close any file; do not change the text buffer): EA Switches the output to the secondary output stream. EW` Switches the output to the primary output stream. Indirect file commands: EIfilespec` 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 Standard TECO PAGE 55 Secondary Stream Commands 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 s. For instance, assume that FOO.TEC contains valid TECO commands, that it presets a return to your terminal with the customary EI`, but that it does not contain an pair. If you type EIFOO``, TECO will read in the contents of FOO.TEC (building a command string) and attempt to continue building the command string by reading from your terminal when end of file on FOO.TEC is encountered. Things will appear "very quiet" until it occurs to you to type 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 encountered in an indirect file will not erase the command line in which it occurs. Instead, it will be treated as the TECO ^Uqtext` command. The only exception to this rule is the command, which directs TECO to execute the preceding command string and then return to the indirect file at the point following the . (We can say explicitly here, because can be other than ESCape only in commands typed at the console.) EI` 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 which has not yet been read is discarded. This command has no effect if no indirect file is already open. Standard TECO PAGE 56 Wildcard Commands 5.1.5 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. TABLE 5-1E: WILDCARD COMMANDS [Not in TECO-8 or TECO-10] ENfilespec` This command presets the "wild card" lookup filespec. It is only a preset; it does not open, close, or try to find any file. The "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. EN` 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 G* command (see Appendix C, section C.1.1) can be used to retrieve the fully expanded filespec. When no more occurences of the wild card filespec exist, the ?FNF error is returned. :EN` Executes the EN` command, and returns a numeric value. A -1 indicates that another match of the wild card filespec exists and has been loaded into the filespec buffer. A 0 indicates no more occurences exist. No error message is generated. The filespec argument to the file selection commands in TECO-11 can use the string building characters described in Table 5-8A (see section 5.8). The Q* construct, described in Appendix C, is especially useful in TECO-11. 5.1.6 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. TABLE 5-1F: DIRECT I/O TO Q-REGISTERS [Not in TECO-8 or TECO-11] EQqfilespec` Read specified file into Q-register q. No s or s are removed from the file, except that trailing s are discarded. The only switch permitted on the filespec in this command is the /DELETE switch, which causes TECO to delete the file after reading it, providing that the file is Standard TECO PAGE 57 Direct I/O to Q-Registers less than 500 characters long. This command supports the pseudo-device TMP:, for TMPCOR. Consult the appropriate appendix for details. [TECO-10 only] E%qfilespec` Create the specified file. The contents of the file will be the contents of Q-register q with no s deleted. No switches are permitted on the filespec of this command. This command supports the pseudo-device TMP:, for TMPCOR. Consult the appropriate appendix for details. [TECO-10 only] Standard TECO PAGE 58 Page Manipulation Commands 5.2 PAGE MANIPULATION COMMANDS The following commands permit text to be read into the text buffer from an input file or written from the buffer onto an output file. All of the input commands listed in this table assume that the input file is organized into pages small enough to fit into available memory. If any page of the input file contains more characters than will fit into available memory, the input command will continue reading characters into the buffer until a line feed is encountered when the buffer is about 3/4 full. See the appendices for more details. Special techniques for handling pages larger than the buffer capacity will be presented later in this chapter. TABLE 5-2: PAGE MANIPULATION COMMANDS COMMAND FUNCTION APPEND commands: A Appends the next page of the input file to the contents of the text buffer, thus combining the two pages of text on a single page with no intervening form feed character. This command takes no argument. To perform n Appends, use the n construct. Note that nA is a completely different command. :A Equivalent to the A command except that a value is returned. -1 is returned if the append succeeded, and 0 is returned if the append failed because the end-of-the-input-file had previously been reached (^N flag is -1 at start of this command). [Not in TECO-8] n:A Appends n lines of text from the input file to the contents of the text buffer. The value of n must not be negative. A value is returned indicating whether or not there were in fact n lines remaining in the input file. -1 is returned if the command succeeded. 0 is returned if end-of-file on the input file was encountered before all n lines were read in. Note that the command can succeed and yet read in fewer than n lines in the case that the text buffer fills up. [Not in TECO-8] PAGE Commands: P Writes the contents of the buffer onto the output file, then clears the buffer and reads the next page of the input file into the buffer. A form feed is appended to Standard TECO PAGE 59 Page Manipulation Commands the output file if the last page read in (with a P, Y, or A command) was terminated with a form feed. :P Same as the P command except that a value is returned. -1 is returned if the command succeeded. 0 is returned if the command failed because the end-of-file on the input file had been reached prior to the initiation of this command. The command string <:P;> takes you to end of file. [Not in TECO-8] nP Executes the P command n times, where n must be a non-zero positive integer. In TECO-11 on VAX/VMS, n can be a negative integer (and -P means -1P). A -nP command will back up n pages. n:P Executes the :P command n times, where n must be a non-zero positive integer. In TECO-11 on VAX/VMS, n can be a negative integer (and -:P means -1:P). This command returns 0 when another page could not be backed up because beginning of file had been reached. [Not in TECO-8] PW Write the contents of the buffer onto the output file and append a form feed character. The buffer is not cleared and the pointer position remains unchanged. nPW Executes the PW command n times, where n must be a non-zero positive integer. m,nPW Writes the contents of the buffer between pointer positions m and n onto the output file. m and n must be positiv