Standard TECO TEXT EDITOR AND CORRECTOR FOR THE VAX-11, PDP-11, PDP-10, and PDP-8 USER'S GUIDE AND LANGUAGE REFERENCE MANUAL April 1980 Edition TECO-11 VERSION 36 TECO-10 VERSION 3 TECO-8 VERSION 7 April, 1980 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, 1980 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 CHAPTER 1 BASICS OF TECO 3 1.1 USING TECO 3 1.2 DATA STRUCTURE FUNDAMENTALS 5 1.3 FILE SELECTION COMMANDS 6 1.3.1 Simplified File Selection 6 1.3.2 Input File Specification (ER command) 7 1.3.3 Output File Specification (EW command) 8 1.3.4 Closing Files (EX command) 9 1.4 INPUT AND OUTPUT COMMANDS 10 1.5 POINTER POSITIONING COMMANDS 11 1.6 TYPE OUT COMMANDS 12 1.6.1 Immediate Action Commands 12 1.7 TEXT MODIFICATION COMMANDS 14 1.8 SEARCH COMMANDS 15 1.9 SAMPLE EDITING JOB 16 INTERLUDE 19 CHAPTER 2 INVOKING TECO 20 2.1 RUNNING TECO 20 2.2 CREATING A NEW FILE 20 2.3 EDITING AN EXISTING FILE 20 2.4 SWITCHES ON TECO AND MAKE COMMANDS 21 2.5 INVOKING A TECO PROGRAM 22 2.6 USER INITIALIZATION 23 CHAPTER 3 CONVENTIONS AND STRUCTURES 25 3.1 TECO CHARACTER SET 25 3.2 TECO COMMAND FORMAT 25 3.2.1 Numeric Arguments 26 3.2.2 Text Arguments 27 3.2.3 Colon Modifiers 28 3.3 DATA STRUCTURES 29 3.3.1 Text Buffer 30 3.3.2 Q-registers 31 3.3.3 Q-register Push-down List 31 3.3.4 Numeric Values and Flags 31 CHAPTER 4 COMMAND STRING EDITING 32 Standard TECO Page ii CHAPTER 5 COMMAND DESCRIPTIONS 37 5.1 FILE SPECIFICATION COMMANDS 38 5.1.1 File Opening Commands 38 5.1.2 File Specification Switches 40 5.1.3 File Close and Exit Commands 40 5.1.4 Secondary Stream Commands 43 5.1.5 Wildcard Commands 45 5.1.6 Direct I/O to Q-Registers 45 5.2 PAGE MANIPULATION COMMANDS 47 5.3 BUFFER POINTER MANIPULATION COMMANDS 49 5.4 TEXT TYPE OUT COMMANDS 51 5.5 DELETION COMMANDS 54 5.6 INSERTION COMMANDS 56 5.7 SEARCH COMMANDS 58 5.8 SEARCH ARGUMENTS 64 5.9 Q-REGISTERS 68 5.10 ARITHMETIC AND EXPRESSIONS 72 5.11 SPECIAL NUMERIC VALUES 75 5.12 COMMAND LOOPS 79 5.13 BRANCHING COMMANDS 80 5.14 CONDITIONAL EXECUTION COMMANDS 85 5.15 RETRIEVING ENVIRONMENT CHARACTERISTICS 87 5.16 MODE CONTROL FLAGS 89 5.17 SCOPE COMMANDS 95 5.17.1 Video Terminal Scope Commands 95 5.17.2 Refresh Scope Commands 97 5.18 PROGRAMMING AIDS 98 5.18.1 Text Formatting 98 5.18.2 Comments 98 5.18.3 Messages 99 5.18.4 Tracing 99 5.18.5 Convenience Characters 100 5.18.6 Memory Expansion 101 5.18.7 Case Control 101 5.19 MANIPULATING LARGE PAGES 102 5.20 TECHNIQUES AND EXAMPLES 103 Standard TECO Page iii APPENDIX A ASCII CHARACTER SET 108 APPENDIX B ERROR MESSAGES 109 APPENDIX C INCOMPATIBLE, OBSOLETE, AND SYSTEM-SPECIFIC COMMANDS 117 C.1 SPECIFIC FEATURES OF TECO-11 117 C.1.1 TECO Commands 117 C.1.2 String Build Constructs 119 C.2 SPECIFIC FEATURES OF RT-11 120 C.3 SPECIFIC FEATURES OF RSTS/E 120 C.4 SPECIFIC FEATURES OF RSX-11/M, RSX-11/D, and IAS 121 C.5 SPECIFIC FEATURES OF VAX/VMS 121 C.6 SPECIFIC FEATURES OF OS/8 121 C.7 SPECIFIC FEATURES OF TOPS-10 121 APPENDIX D RT-11 OPERATING CHARACTERISTICS 125 APPENDIX E RSTS/E OPERATING CHARACTERISTICS 129 APPENDIX F RSX-11 OPERATING CHARACTERISTICS 131 APPENDIX G VAX/VMS OPERATING CHARACTERISTICS 137 APPENDIX H OS/8 OPERATING CHARACTERISTICS 145 APPENDIX I TOPS-10 OPERATING CHARACTERISTICS 157 GLOSSARY 164 INDEX 178 Standard TECO Page 1 Introduction INTRODUCTION TECO is a powerful text editing program that runs under most DIGITAL operating systems. TECO may be used to edit any form of ASCII text: program sources, manuscripts, or correspondence, for example. Since TECO is a character-oriented editor rather than a line editor, text edited with TECO does not have line numbers associated with it, and it is not necessary to replace an entire line of text in order to change one character. The versatility of TECO makes it complex. To help users deal with this complexity, this manual presents TECO in two stages. The first part (Chapter 1) contains basic information and introduces enough TECO commands to allow the novice TECO user to begin creating and editing text files after only a few hours of instruction. The introductory commands are sufficient for any editing application; however, they are less powerful, in many cases, than the advanced commands presented later. Subsequent chapters describe the full TECO command set, including a review of the introductory 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 format which will quickly become apparent to the novice user. However, the end of Chapter 1 does include an extensive example employing most of the commands introduced up to that point. Students of TECO should experiment with each command as it is introduced, then duplicate the examples on their computer. 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. Standard TECO Page 2 Introduction 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 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 3 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 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. All text arguments are terminated by a special character (usually an ESCAPE) which 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 ESCAPE characters. The ESCAPE is a non-printing character which may be labelled ESC, ALT, or PREFIX on your keyboard. TECO echoes a dollar sign ($) whenever an ESCAPE is typed. The dollar sign character is used in examples throughout this manual to represent ESCAPE. Note that the carriage return character has no special significance to TECO. Only the double ESCAPE forces execution of the command string. 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 Standard TECO Page 4 Using TECO 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 5 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. 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 6 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 7 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 means of an ER command terminated by an ESCAPE. The ER command causes TECO to open the specified file and 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 an ESCAPE, which echoes as a dollar sign. 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 8 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 an EW command terminated by an ESCAPE. 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 defined, 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 an ESCAPE, which echoes as a dollar sign. 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 ESCAPE ($$) terminates the command string and causes the string to be executed. Note that the ESCAPE which terminates the EW command may be one of the two ESCAPEs 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 9 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 10 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, where n must be a positive (non-zero) integer. 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 11 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 12 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". 1.6.1 Immediate Action Commands [not in TECO-10] In addition, there are two special type out commands available as a convenience. They are abbreviations for two frequently used commands. These commands consist of a single character and must be the very first character typed after TECO prints its prompting asterisk. They take effect immediately; there is no need to follow these commands by an ESCAPE character. For this reason, these commands are known as immediate action commands. COMMAND FUNCTION Immediately execute the 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. Immediately execute the -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. Standard TECO Page 13 Type Out Commands These commands are useful for "walking through" a file, examining and/or modifying lines one at a time. Standard TECO Page 14 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 an ESCAPE (which echoes as a dollar sign). 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 15 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 an ESCAPE (which echoes as a dollar sign). 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. You must then 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 16 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 17 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 ESCAPE ($$), 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 ESCAPE. 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 struck the DELETE key once to delete the second "A". TECO echoed the deleted character. The user then typed the correct character Standard TECO Page 18 Sample Editing Job 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 closed the output file. 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 19 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 36, 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 20 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 21 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. The /VTEDIT switch may also take values (of the form :value). Standard TECO Page 22 Switches on TECO and MAKE Commands /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 23 User Initialization 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 24 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 25 Conventions and Structures CHAPTER 3 CONVENTIONS AND STRUCTURES 3.1 TECO CHARACTER SET TECO accepts the full 7-bit ASCII character set; all characters have their 8th bit (the parity 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). TECO command strings may be entered using upper case characters (as shown throughout this manual) or lower case characters. The commands MQ, mQ, Mq, and mq are treated alike. 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. 3.2 TECO COMMAND FORMAT A TECO command consists of one or two characters, optionally preceded by a numeric argument and sometimes followed by a text argument. TECO commands may be strung together by concatenating them into a single command string. No delimiter is necessary between commands, although a single ESCAPE or caret-[ may be inserted between them if desired. This ESCAPE will keep numeric values generated by the preceeding command from affecting the commands that follow the ESCAPE. TECO commands are accumulated into a command string as they are Standard TECO Page 26 Conventions and Structures typed. The command string is executed when it is terminated by typing two consecutive ESCAPE 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. 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. N = Standard TECO Page 27 Conventions and Structures 1 is assumed when n is omitted. 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 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 an ESCAPE character (or in the case of ! and ^A commands, by the command character). The string of ASCII characters may not include an ESCAPE, 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 Standard TECO Page 28 Conventions and Structures must be followed by an ESCAPE character, as follows: FSabc$def$ Replace string "abc" by "def" You can include an ESCAPE 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 . 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 any order. Standard TECO Page 29 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 These data structures are used to achieve two quite separate Standard TECO Page 30 Conventions and Structures 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). 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 Standard TECO Page 31 Conventions and Structures 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 36 data storage registers, called Q-registers, which may be used to store single integers and/or ASCII character strings. The Q-registers have one character names: A through Z and 0 through 9. Each Q-register is divided into two storage areas. In the numeric storage area, each Q-register can store one signed integer. In the text storage area, each Q-register can store an ASCII character string which may be either text or a TECO command string. Various TECO commands allow the storing and retrieving of numerical 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 and restored. 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 32 Command String Editing CHAPTER 4 COMMAND STRING EDITING While you are typing command strings at a terminal, TECO considers certain ASCII characters to have special meaning. Most of the special characters are immediate action commands, which cause TECO to perform a specified function immediately, instead of waiting for the double ESCAPE which terminates a command string. Immediate action commands may be entered at any point in a command string - even in the middle of a command or text argument. Many immediate action commands, such as DELETE, which deletes the immediately preceding character, cannot be used as regular TECO commands. If you enter a DELETE into a command string executed from a macro, the DELETE will not delete a character as part the execution of the command string. 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 command which deletes the current line. Thus you cannot type a (or any other sequence which doubles as an immediate action command) 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 in immediate action commands must be entered using the CONTROL key; they will not be recognized if entered as a caret or up-arrow. Tables 4-1 and 4-2 list the immediate action commands and explain their functions. Standard TECO Page 33 Command String Editing TABLE 4-1: IMMEDIATE ACTION COMMANDS These commands 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 echoes as $$ and also inserts two s into the command string. The two ESCAPES must be typed successively. If any other character is typed in between the two ESCAPEs (even if subsequently DELETEd), then the two ESCAPEs might be treated simply as two ESCAPEs to be entered into the command string rather than as an immediate action command. If you need to enter two ESCAPEs 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 ESCAPE character is not a special character and 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 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 Standard TECO Page 34 Command String Editing 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 35 Command String Editing TABLE 4-2: IMMEDIATE ACTION AIDS These immediate action commands are aids to the user. They have special meaning and take immediate effect only if they are typed as the very first keystroke after TECO's asterisk prompt. 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. [Not in TECO-11] Typing this immediate action command, line feed, as the first keystroke after TECO's prompt causes TECO to immediately execute the 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, backspace, (as the first keystroke after TECO's prompt) causes TECO to immediately execute the -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] *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 36 Command String Editing Although TECO accepts all 128 characters of the 7-bit ASCII character set, whether encountered in a macro, or entered directly into a command string from the terminal, 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-3. Note that these characters are still valid characters to TECO, but must be entered indirectly, such as by entering them into a macro using the nI$ command. TABLE 4-3: 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 ^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 37 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 38 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 39 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 40 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. 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 /B+ Handle a BASIC-PLUS file /B2 Handle a BASIC-PLUS-2 file /CLUSTERSIZE:n Specifies output file cluster size /MODE:n Use non-standard open mode /n Handle BASIC-PLUS-2 continuation character (&) in column n RSX-11 VAX/VMS /B2 Handle a BASIC-PLUS-2 file /CR Implied carriage control /-CR No (internal) carriage control /FT FORTRAN carriage control /RW Rewind magtape before opening file /SH Open the file in shared mode 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 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 Standard TECO Page 41 File Close and Exit Commands 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 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. Standard TECO Page 42 File Close and Exit Commands :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 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. Standard TECO Page 43 Secondary Stream Commands 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 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 ESCAPEs. 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 Standard TECO Page 44 Secondary Stream Commands 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 . 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 ESCAPE which has not yet been read is discarded. This command has no effect if no indirect file is already open. Standard TECO Page 45 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 less than 500 characters long. This command Standard TECO Page 46 Direct I/O to Q-Registers 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 47 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. 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 the output file if the last page read in (with a P, Y, Standard TECO Page 48 Page Manipulation Commands 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. [Not in TECO-8] nP Executes the P command n times, where n must be a non-zero positive integer. 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 positive integers. A form feed is not appended to this output, nor is the buffer cleared. The pointer position remains unchanged. m,nP Equivalent to m,nPW. HPW Equivalent to the PW command except that a form feed character is not appended to the output. HP Equivalent to HPW. YANK commands: Y Clears the text buffer and then reads the next page of the input file into the buffer. As the Y command can result in the loss of data, it is not permitted under certain circumstances (see ED flag in 5.14). :Y Same as the Y command but a value is returned. -1 is returned if the Yank succeeded. 0 is returned if the Yank failed because the end-of-file had been reached on the input file prior to the initiation of this command. [Not in TECO-8] EY Same as the Y command, but its action is always permitted regardless of the value of the Yank Protection bit in the ED flag. :EY Same as the :Y command, but its action is always permitted regardless of the value of the Yank protection bit in the ED flag. [Not in TECO-8] Standard TECO Page 49 Buffer Pointer Manipulation Commands 5.3 BUFFER POINTER MANIPULATION COMMANDS Table 5-3 describes all of the buffer pointer manipulation commands These commands may be used to move the pointer to a position between any two characters in the buffer, but they will not move the pointer across a buffer boundary. If any R or C command attempts to move the pointer backward beyond the beginning of the buffer or forward past the end of the buffer, the command is ignored and an error message is printed. If any L command attempts to exceed the buffer boundaries, the pointer is positioned at the boundary which would have been exceeded and no error message is printed. TABLE 5-3: BUFFER POINTER MANIPULATION COMMANDS COMMAND FUNCTION CHARACTER commands: C Advances the pointer forward across one character. nC Executes the C command n times. If n is positive, the pointer is moved forward across n characters. If n is negative, the pointer is moved backward across n characters. If n is zero, the pointer position is not changed. n:C Same as nC except that a value is returned. If the command succeeded, -1 is returned. If the command failed, the pointer does not move and a value of 0 is returned. [TECO-10 only] :C Equivalent to 1:C. -C Equivalent to -1C. JUMP commands: J Moves the pointer to a position immediately preceding the first character in the buffer. Equivalent to 0J. nJ Moves the pointer to a position immediately following the nth character in the buffer. ZJ Moves the pointer to a position immediately following the last character in the buffer. n:J Same as the nJ command except that if pointer position n is outside of the buffer, the pointer does not move and a value of 0 is returned. If the command succeeded, a value of -1 is returned. [TECO-10 only] Standard TECO Page 50 Buffer Pointer Manipulation Commands LINE commands: L Advances the pointer forward across the next line terminator (line feed, vertical tab, or form feed) and positions it at the beginning of the next line. nL Executes the L command n times. A positive value of n advances the pointer to the beginning of the nth line following its current position. A negative value of n moves the pointer backwards to the beginning of the nth complete line preceding its current position. If n is zero, the pointer is moved to the beginning of the line on which it is currently positioned. -L Equivalent to -1L. REVERSE commands: R Moves the pointer backward across one character. nR Executes the R command n times. If n is positive, the pointer is moved backward across n characters. If n is negative, the pointer is moved forward across n characters. If n is zero, the position of the pointer is not changed. -R Equivalent to -1R. n:R Same as the nR command except that a value is returned. If the command succeeded, then a value of -1 is returned. If the command failed, then the buffer pointer is not moved and a value of 0 is returned. [TECO-10 only] :R Equivalent to 1:R. Standard TECO Page 51 Text Type Out Commands 5.4 TEXT TYPE OUT COMMANDS Table 5-4 describes the commands used to type out part or all of the contents of the buffer for examination. These commands do not move the buffer pointer. TABLE 5-4: TEXT TYPE OUT COMMANDS COMMAND FUNCTION T Types out the contents of the buffer from the current position of the buffer pointer through and including the next line terminator character. nT Types n lines. If n is positive, types the n lines following the current position of the pointer. If n is negative, types the n lines preceding the pointer. If n is zero, types the contents of the buffer from the beginning of the line on which the pointer is located up to the pointer. -T Equivalent to -1T. m,nT Types out the contents of the buffer between pointer positions m and n. .,.+nT Types out the n characters immediately following the buffer pointer. n should be greater than zero. .-n,.T Types the n characters immediately preceding the buffer pointer. n should be greater than zero. n^T Types out the character whose ASCII code is n. This can be used to output any ASCII character to the terminal. HT Types out the entire contents of the buffer. V Types out the current line. Equivalent to 0TT. nV Types out n-1 lines on each side of the current line. Equivalent to 1-nTnT. [Not in TECO-8] m,nV Types out m-1 lines before and n-1 lines after the current line. [Not in TECO-8] ^Atext Types "text" on the terminal. While the command may begin with or Caret/A, the closing character must be a . A numeric argument must not be specified with this command. Standard TECO Page 52 Text Type Out Commands @^A/text/ Equivalent to the ^A command except that the text to be printed may be bracketed with any character. This avoids the need for the closing . Standard TECO Page 53 Text Type Out Commands You may stop or delay the output of any type out command by typing certain special characters at the keyboard while TECO is typing out at the terminal (via a T, V, ^A, or :G command). These characters are described in the table below: TABLE 5-4B: TYPE OUT TIME COMMANDS CHARACTER FUNCTION Stops the terminal output of the current command string. TECO continues to run and to send characters to the terminal, however, these characters are suppressed from actually printing on the terminal. You can resume printing characters by typing another while type out is being suppressed. TECO cancels this suppression the next time that it prompts for command string input. A TECO macro can cancel the effect of any by setting the 16's bit in the ET flag (see section 5.16). Freezes the terminal output of the current command string. TECO stops running the next time it tries to output a character to your terminal, and waits for you to type a to indicate that output should resume. Causes TECO to resume any type out that was frozen via use of the command described above. This character has this effect only while typout is frozen. Striking any key other than or while type out is frozen will have unpredictable results; consult the appropriate operating system manual. Note that , , and are legal TECO commands as well. When TECO is not typing on the terminal (when you are entering a command string, for example), these characters do not have the effect described above. They may be entered into your command string just like any other control character (except under operating systems that filter out these characters). Standard TECO Page 54 Deletion Commands 5.5 DELETION COMMANDS Table 5-5 summarizes the text deletion commands, which permit deletion of single characters, groups of adjacent characters, single lines, or groups of adjacent lines. TABLE 5-5: TEXT DELETION COMMANDS COMMAND FUNCTION DELETE commands: D Delete the first character following the current position of the buffer pointer. nD Execute the D command n times. If n is positive, the n characters following the current pointer position are deleted. If n is negative, the n characters preceding the current pointer position are deleted. If n is zero, the command is ignored. -D Equivalent to -1D. m,nD Equivalent to m,nK. [TECO-11 only] n:D Same as nD but returns a value (-1 if command succeeds, 0 if command failed because the range of characters to be deleted fell outside the text buffer). [TECO-10 only] FDtext$ Search for the specified text string and delete it. (See search commands in section 5.7.) [TECO-10 only] @FD/text/ Equivalent to FDtext$ except that the character is not necessary. FR$ Equivalent to -nD where n is the length of the last insert, get or search command. See the description of the FRtext$ command in section 5.6 for more details. @FR// Form of the FR$ command that does not require use of the character. KILL commands: K Deletes the contents of the buffer from the current position of the buffer pointer through and including the next line terminator character. nK Executes the K command n times. If n is positive, the n lines following the current pointer position are Standard TECO Page 55 Deletion Commands deleted. If n is negative, the n lines preceding the current pointer position are 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. It is not an error if more lines are specified than occur when a boundary of the text buffer is encountered. -K Equivalent to -1K. m,nK Deletes the contents of the buffer between pointer positions m and n. The pointer moves to the point of the deletion. The ?POP error message (or its equivalent) is issued if either m or n is out of range. FKtext$ Executes a Stext$ command then deletes all the text from the initial pointer position to the new pointer position. [TECO-10 only] @FK/text/ Equivalent to FKtext$ except that "text" may contain any character, including , other than the delimiter (shown here as /). [TECO-10 only] HK Deletes the entire contents of the buffer. Standard TECO Page 56 Insertion Commands 5.6 INSERTION COMMANDS Table 5-6 lists all of the text insertion commands. These commands cause the string of characters specified in the command to be inserted into the text buffer at the current position of the buffer pointer. Following execution of an insertion command, the pointer will be positioned immediately after the last character of the insertion. The length of an insertion command is limited primarily by the amount of memory available for command string storage. During normal editing jobs, it is most convenient to limit insertions to about 10 or 15 lines each. When command string space is about to run out, TECO will ring the terminal's bell after each character that is typed. From the time you hear the first warning bell, you have 10 characters to type in order to clean up your command line. Attempting to enter too many characters into the current command string causes unpredictible results to occur and should be avoided. Use the DELETE key to shorten the command to permit its termination. As explained above in Chapter 4, certain characters are filtered out by the operating system and/or may perform special functions, and some characters are immediate action commands and have special effect. If you want to insert such characters into the text buffer, use the nI$ command described in the following table. It will insert any ASCII character into the buffer, including the special characters that could not ordinarily be typed at a terminal. TABLE 5-6: TEXT INSERTION COMMANDS COMMAND FUNCTION INSERT commands: Itext$ Where "text" is a string of ASCII characters terminated by an ESCAPE. The specified text string is entered into the buffer at the current position of the pointer, with the pointer positioned immediately after the last character of the insertion. nI$ This form of the I command inserts the single character whose 7-bit ASCII code is n into the buffer at the current position of the buffer pointer. (n is taken modulo 128.) nI$ is used to insert characters that are not available on the user's terminal or special characters such as DELETE which may not be inserted from a terminal with the standard I command. @I/text/ Equivalent to the I command except that the text to be inserted may contain ESCAPE characters. A delimiting character (shown as a slash here) must precede and Standard TECO Page 57 Insertion Commands follow the text to be inserted, as described in Section 3.1.2 above. n@I// Equivalent to the nI$ command, but does not require the ESCAPE character. text$ This command is equivalent to the I command except that the is part of the text which is inserted into the buffer. FRtext$ Equivalent to "-nDItext$", where "n" is obtained from the most recent occurrence of the following: (a) the length of the most recent string found by a successful search command, (b) the length of the most recent text string inserted (including insertions from the FS, FN, or FR commands), or (c) the length of the string retrieved by the most recent "G" command. In effect, the last string inserted or found is replaced with "text", provided that the pointer has not been moved. [Not in TECO-8] @FR/text/ Equivalent to "FRtext$", except that "text" may contain ESCAPE characters. [Not in TECO-8] Standard TECO Page 58 Search Commands 5.7 SEARCH COMMANDS In many cases, the easiest way to position the buffer pointer is by means of a character string search. Search commands cause TECO to scan through text until a specified string of characters is found, and then position the buffer pointer at the end of the string. A character string search begins at the current position of the pointer. It proceeds within the current buffer in a forward or a reverse direction or through the file in a forward direction. Specifying a negative numeric argument to the search command causes the search to proceed backwards from the pointer. Your last explicitly specified search string is always remembered by TECO. If a search command is specified with a null search string argument, the last explicitly defined search string will be used. This saves having to retype a complex or lengthy search string on successive search commands. Normally searches are "unbounded" - they search from the current position to the end of the text buffer (or in the case of backwards searches, until the beginning of the buffer). A bounded search, however, will only search from the current position to the specified bound limit. If the search string is found within the bound limits, the pointer is positioned immediately after the last character in the string. If the string cannot be found, the pointer is left unchanged. A special case of the bounded search occurs when the upper and lower bound limits are the same. In such a case, the search command is called an anchored search, and is used to compare the search argument against the character string immediately following the text buffer pointer. TECO-8 does not permit backward, bounded, or anchored searches. This is a general property and will not be specifically mentioned again in the following tables. Standard TECO Page 59 Search Commands TABLE 5-7A: SEARCH COMMANDS Stext$ Where "text" is a string of characters terminated by an ESCAPE. This command searches the text buffer for the next occurrence of the specified character string following the current position of the buffer pointer. If the string is found, the pointer is positioned after the last character in the string. If it is not found, the pointer is positioned immediately before the first character in the buffer (i.e., a 0J is executed) and an error message is printed. nStext$ This command searches for the nth occurrence of the specified character string, where n is greater than zero. It is identical to the S command in other respects. -nStext$ Identical to "nStext$" except that the search proceeds in the reverse direction. If the string is not found, the pointer is positioned immediately before the first character in the buffer and an error message is printed. If the pointer is positioned at the beginning of or within an occurrence of the desired string, that occurrence is considered to be the first one found. Upon successful completion, the pointer is positioned after the last character in the string found. -Stext$ Equivalent to -1Stext$. 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. This is accomplished by executing an effective P command after each page is searched. If the end of the input file is reached, an error message is printed and it is necessary to close the output file and re-open it as an input file before any further editing may be done on that file. The N command will not locate a character string which spans a page boundary. nNtext$ This command searches for the nth occurrance of the specified character string, where n must be greater than zero. It is identical to the N command in other respects. _text$ The underscore command is identical to the N command except that the search is continued across page boundaries by executing effective Y commands instead of P commands, so that no output is generated. Since an underscore search can result in the loss of data, it is aborted under the same circumstances as the Y command (see the ED flag in section 5.16). Note that underscore is backarrow on some terminals. Standard TECO Page 60 Search Commands n_text$ This command searches for the nth occurrence of the specified character string, where n must be greater than zero. It is identical to the _ command in other respects. E_text$ Same as _text$ command except that effective EY (rather than Y) commands are used. Thus, this command is never aborted and is not controlled by the Yank protection bit in the ED flag. nE_text$ Same as n_text$ command except that effective EY (rather than Y) commands are used. TABLE 5-7B: BOUNDED SEARCH COMMANDS m,nStext$ System specific command. Consult Appendix C. m,nFBtext$ Performs the same function as the nStext$ command, but m and n (inclusive) serve as bounds for the search. In order for a search to be successful, the first character to match must occur between buffer pointer positions m and n. The string that is matched is permitted to extend beyond the search limits specified, provided that it begins within bounds. If mn, then the search proceeds in the reverse direction. nFBtext$ Performs a bounded search over the next n lines. If n is positive, the search proceeds forward over the next n lines; if n is negative the search proceeds backwards over the n preceding lines; if n is zero, the search proceeds backwards over the portion of the line preceding the pointer. FBtext$ Equivalent to 1FBtext$. -FBtext$ Equivalent to -1FBtext$. ::Stext$ Compare command. The ::S command is not a true search. If the characters in the buffer immediately following the current pointer position match the search string, the pointer is moved to the end of the string and the command returns a value of -1; i.e., the next command is executed with an argument of -1. If the characters in the buffer do not match the string, the pointer is not moved and the command returns a value of 0. Identical to ".,.:FBtext$". The search and replace commands listed below perform equivalent functions to the search commands listed next to them, but then delete "text1" and replace it with "text2". Standard TECO Page 61 Search Commands TABLE 5-7C: SEARCH AND REPLACE COMMANDS Search & Replace Search Command FStext1$text2$ Stext1$ nFStext1$text2$ nStext1$ FNtext1$text2$ Ntext1$ nFNtext1$text2$ nNtext1$ F_text1$text2$ _text1$ [not in TECO-10] nF_text1$text2$ n_text1$ [Not in TECO-10] FCtext1$text2$ FBtext1$ nFCtext1$text2$ nFBtext1$ m,nFCtext1$text2$ m,nFBtext1$ Standard TECO Page 62 Search Commands In addition, the four following commands can be used on TECO-10: FDtext$ Identical to the "FStext$$" command. [TECO-10 only] nFDtext$ Identical to the "nFStext$$" command. [TECO-10 only] nFKtext$ Searches for the nth following occurrence of "text" and then deletes all characters in the text buffer between the pointer positions before and after the search. [TECO-10 only] FKtext$ Equivalent to 1FKtext$ [TECO-10 only] The FS, F_, and FN commands above can also be reverse searches (n<0) or bounded searches (m,n argument). A reverse F_ or FN acts like a reverse S; that is the search terminates when the beginning of the text buffer is encountered. If a search command is entered without a text argument, TECO will execute the search command as though it had been entered with the same character string argument as the last search command entered. For example, suppose the command "STHE END$" results in an error message, indicating that character string "THE END" was not found on the current page. Entering the command "N$" causes TECO to execute an N search for the same character string. Although the text argument may be omitted, the command terminator (ESCAPE) must always be entered. Search commands can make use of the colon modifier described in Chapter 3. The following examples illustrate use of the colon modifier: COMMANDS: n:Stext$ m,n:Stext$ n:Ntext$ n:_text$ n:FStext1$text2$ m,n:FStext1$text2$ n:FNtext1$text2$ etc. FUNCTION: In each case, execute the search command. If the search is successful, execute the next sequential command with an argument of -1. If the search fails, execute the next command with an argument of zero. If the next command does not require a numeric argument, execute it as it stands. All search commands may also use the @ modifier to use alternate Standard TECO Page 63 Search Commands delimiters, to allow characters in search strings or to avoid the use of characters in command strings. Such search commands take the following forms: COMMANDS: @S/text/ m,n@FB/text/ n@FS/text1/text2/ @:N/text/ etc. Standard TECO Page 64 Search Arguments 5.8 SEARCH ARGUMENTS TECO builds the search string by loading its search string buffer from the supplied search command argument. To help you enter special characters or frequently used character sequences, the argument may contain special string building characters. Table 5-8A lists the string building characters and their functions. TECO-8 does not support the extended String Build functions or Match Control Constructs that begin with . This is a general property and will not be repeated in the following tables. Note that, as explained in Chapter 3, a caret (up-arrow) may be used to indicate that the character following it is to be treated as a control character. Any of the commands below may be entered using the caret. This function of the caret can be disabled by using the ED flag (see 5.16 and appendices). TABLE 5-8A: STRING BUILDING CHARACTERS CHARACTER FUNCTION A character in a search command argument indicates that the character following the is to be used literally rather than as a match control character. Same as . A character in a search command argument indicates that the character following the is to be used as the equivalent character in the lower case ASCII range (i.e., octal 100 to 137 is treated as octal 140 to 177). Two successive characters in a string argument indicate to TECO that all following alphabetic characters in this string are to be converted to lower case unless an explicit ^W is given to override this state. This state continues until the end of the string or until a ^W^W construct is encountered. [TECO-10 only] A character in a search command argument indicates that the character following the is to be used as the equivalent character in the upper case ASCII range (i.e., octal 140 to 177 is treated as octal 100 to 137). Standard TECO Page 65 Search Arguments Two successive characters indicates to TECO that all following alphabetic characters in this string are to be converted to upper case unless an explicit ^V is encountered to override this state. This state continues until the end of the string or until a ^V^V construct is encountered. [TECO-10 only] Qq Qq indicates that the string stored in Q-register q is to be used in the position occupied by the ^EQq in the search string. Q registers are discussed in section 5.9 below. [Not in TECO-10] Uq Uq indicates that the character whose ASCII code is specified by the numeric storage area of Q-register q is to be used in the position occupied by the ^EUq in the search string. [TECO-11 only] String build characters are also permitted inside the string arguments of the O, EB, ER, EW, and EG commands. TECO executes a search command by attempting to match the search command argument character-by-character with some portion of the input file. There are several special control characters that may be used in search command arguments to alter the usual matching process. Table 5-8B lists these match control characters and their functions. TABLE 5-8B: MATCH CONTROL CHARACTERS CHARACTER FUNCTION A character indicates that this position in the character string may be any character. TECO accepts any character as a match for . A character indicates that any separator character is acceptable in this position. TECO accepts any character that is not a letter (upper or lower case A to Z) or a digit (0 to 9) as a match for . x TECO accepts any character as a match for the x combination EXCEPT the character which follows the . can be combined with other special characters. For example, the combination D means match anything except a digit in this position. Standard TECO Page 66 Search Arguments A A indicates that any alphabetic character (upper or lower case A to Z) is acceptable in this position. B Same as . C C indicates that any character that is legal as part of a symbol constituent is acceptable in this position. TECO accepts any letter (upper or lower case A to Z), any digit (0 to 9), a dot (.), or a dollar sign ($) as a match for C. Additional characters may be matched depending upon the operating system; consult the appropriate appendix. D D indicates that any digit (0 to 9) is acceptable in this position. Gq Gq indicates that any character contained in Q-register q is acceptable in this position. For example, if Q-register A contains "A*:" then TECO accepts either A, *, or : as a match for GA. [Not in TECO-10] L L indicates that any line terminator (line feed, vertical tab, or form feed) is acceptable in the position occupied by L in the search string. M M indicates that any non-zero number of occurrences of the immediately following character or match control construct is acceptable at this position. [TECO-10 only] R R indicates that any alphanumeric character (letter or digit as defined above) is acceptable in this position. S S indicates that any non-null string of spaces and/or tabs is acceptable in the position occupied by S. V V indicates that any lower case alphabetic character is acceptable in this position. W W indicates that any upper case alphabetic character is acceptable in this position. X Equivalent to . indicates that the character whose ASCII octal code is nnn is acceptable in this Standard TECO Page 67 Search Arguments position. [TECO-10 only] [a,b,c,...] [a,b,c,...] indicates that any one of the specified characters is acceptable in this position. One or more characters or other match control constructs are permitted. [TECO-10 only] TECO-8 uses special symbols to represent certain match control characters when they are displayed by an error message. These display symbols are: Character Display ^N ^S ^X Standard TECO Page 68 Q-registers 5.9 Q-REGISTERS TECO provides 36 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: a number storage area and a text storage area. The number storage area can store one signed integer. The text storage area can store an ASCII character string which may be either text or a TECO command string. Each Q-register has a single character name which is one of the letters A to Z or one of the digits 0 to 9. Upper and lower case letters may be used interchangeably. TECO-10 allows additional Q-registers besides the 36 described above. Consult Appendix I for further details. Table 5-9A lists the commands which permit characters to be loaded into the Q-registers. TABLE 5-9A: Q-REGISTER LOADING COMMANDS COMMAND FUNCTION nUq Put n in the numeric storage area of Q-register q. m,nUq Equivalent to the nUqm command. That is, this command puts the number n into the numeric storage area of Q-register q and then returns the number m as a value. The command UAUB is useful at the beginning of a macro to save the two arguments specified on the macro call. (See the m,nMq command below.) n%q Add n to the contents of the number storage area of Q-register q. The resulting value contained in Q-register q is used as a numeric argument for the next command. If the next command does not require a numeric argument, this value is discarded. n%q$ Same as n%q but discards the value returned. %q Equivalent to 1%q. ^Uqstring$ This command inserts character string "string" into the text storage area of Q-register q. When entering a command string from the terminal, you must specify ^U using the caret/U format, since the character is the line erase immediate action command. :^Uqstring$ This command appends character string "string" to the text storage area of Q-register "q". [not in TECO-8] Standard TECO Page 69 Q-registers n^Uq$ This form of the ^Uq$ command inserts the single character whose 7-bit ASCII code is n into the text storage area of Q-register "q". [not in TECO-8] n:^Uq$ This form of the :^Uq$ command appends the single character whose 7-bit ASCII code is n to the text storage area of Q-register "q". [not in TECO-8] @^Uq/string/ @:^Uq/string/ n@^Uq// n@:^Uq// Equivalent, respectively, to the ^Uqstring$, :^Uqstring$, n^Uq$, and n:^Uq$ commands, except that alternate delimiters are used and no characters are necessary. nXq Clear Q-register q and move n lines into it, where n is a signed integer. If n is positive, the n lines following the current pointer position are copied into the text storage area of Q-register q. If n is negative, the n lines preceding the pointer are copied. 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 copied. The pointer is not moved. The text is not deleted. Xq Equivalent to 1Xq. -Xq Equivalent to -1Xq. m,nXq Copy the contents of the buffer from the m+1th character through and including the nth character into the text storage area of Q-register q. M and n must be positive, and m should be less than n. .,.+nXq Copy the n characters immediately following the buffer pointer into the text storage area of Q-register q. N should be greater than zero. .-n,.Xq Copy the n characters immediately preceeding the buffer pointer into the text storage area of Q-register q. N should be greater than zero. n:Xq Append n lines to Q-register q, where n is a signed integer with the same functions as n in the nXq command above. The pointer is not moved. [not in TECO-8] The colon construct for appending to a Q-register can be used with all forms of the X command. ]q Pop from the Q-register push-down list into Q-register Standard TECO Page 70 Q-registers q. Any previous contents of Q-register q are destroyed. Both the numeric and text parts of the Q-register are loaded by this command. The Q-register push-down list is a last-in first-out (LIFO) storage area. This command does not use numeric values. Numeric values are passed through this command as if it did not occur. This allows macros to restore Q-registers and still return numeric values. [Not in TECO-8] :]q Execute the ]q command and return a numeric value. A -1 indicates that there was another item on the Q-register push-down list to be popped. A 0 indicates that the Q-register push-down list was empty, so Q-register q was not modified. [Not in TECO-8] Table 5-9B lists the commands which permit data to be retrieved from the Q-registers. TABLE 5-9B: Q-REGISTER RETRIEVAL COMMANDS COMMAND FUNCTION Qq Use the integer stored in the number storage area of Q-register q as the argument of the next command. nQq Return the ASCII value of the (n+1)th character in Q-register q. The argument n must be between 0 and the Q-register's size minus 1. If n is out of range, a value of -1 is returned. Characters within a Q-register are numbered the same way that characters in the text buffer are numbered. The initial character is at character position 0, the next character is at character position 1, etc. Therefore, if Q-register A contains "xyz", then 0QA will return the ASCII code for "x" and 1QA will return the ASCII code for "y". :Qq Use the number of characters stored in the text storage area of Q-register q as the argument of the next command. Gq Copy the contents of the text storage area of Q-register q into the buffer at the current position of the buffer pointer, leaving the pointer positioned after the last character copied. :Gq Print the contents of the text storage area of Q-register q on the terminal. The text buffer and buffer pointer are not changed by this command. Mq Execute the contents of the text storage area of Q-register q as a command string. Mq commands may be Standard TECO Page 71 Q-registers nested recursively as far as TECO's push down storage will permit. nMq Execute the Mq command, using n as a numeric argument for the first command contained in Qregister q. m,nMq Execute the Mq command, using m,n as a numeric argument for the first command contained in Qregister q. [q Copy the contents of the numeric and text storage areas of Q-register q into the Q-register push-down list. This command does not alter either the numeric or text storage areas of Q-register q. It does not use numeric values. Numeric values are passed through this command as if it did not occur, allowing macros to save temporary Q-registers and still accept numeric values. The command sequence [A ]B copies the text and numeric value from Q-register A to Q-register B. [Not in TECO-8] Standard TECO Page 72 Arithmetic and Expressions 5.10 ARITHMETIC AND EXPRESSIONS The numeric argument of a TECO command may consist of a single integer, any of the characters listed in Table 5-11, the numeric contents of any Q-register, or an arithmetic combination of these elements. If an arithmetic expression is supplied as a numeric argument, TECO will evaluate the expression. All arithmetic expressions are evaluated from left to right without any operator precedence. Parentheses may be used to override the normal order of evaluation of an expression. If parentheses are used, all operations within the parentheses are performed, left to right, before operations outside the parentheses. Parentheses may be nested, in which case the innermost expression contained by parentheses will be evaluated first. Table 5-10A lists all of the arithmetic operators that may be used in arithmetic expressions. TABLE 5-10A: ARITHMETIC OPERATORS OPERATOR EXAMPLE FUNCTION + +2=2 Ignored if used before the first term in an expression. + 5+6=11 Addition, if used between terms. - -2=-2 Negation, if used before the first term in an expression. - 8-2=6 Subtraction, if used between terms * 8*2=16 Multiplication. Used between terms. / 8/3=2 Integer division with loss of the remainder. Used between terms. & 12&10=8 Bitwise logical AND of the binary representation of the two terms. Used between the terms. # 12#10=14 Bitwise logical OR of the binary of the two terms. Used between the terms. ^_ 5^_=-6 Unary one's complement. Used after an expression. This is a TECO command that complements its argument. Strictly speaking, it is not a unary operator. Standard TECO Page 73 Arithmetic and Expressions TABLE 5-10B: CONVERSION AND RADIX CONTROL COMMANDS COMMAND FUNCTION n= This command causes the value of n to be output at the terminal in decimal followed by a carriage return and line feed. Decimal numeric conversion is signed. For example, the unsigned number 65535 will output as -1 on TECO-11. TECO's radix is unaltered. n== This command causes the value of n to be output at the terminal in octal (base 8) followed by a carriage return and line feed. Octal numeric conversion is unsigned. For example, the unsigned number 8191 (decimal) will output as 17777 on TECO-8. TECO's radix is unaltered. n=== This command causes the value of n to be output at the terminal in hexadecimal (base 16) followed by a carriage return and line feed. Hexadecimal output is unsigned. TECO's radix is unaltered. [TECO-11 only] n:= n:== n:=== These commands are equivalent to n=, n==, and n===, except that they leave the carriage positioned at the end of the output. ^O (caret/O) causes all subsequent numeric input to be accepted as octal numbers. Numeric conversions using the \ or n\ commands will also be octal. The digits 8 and 9 become illegal as numeric characters. The octal radix will continue to be used until the next ^D command is executed or until TECO's radix is changed by an n^R command. NOTE: On TECO-10, this command only affects the immediately following digit string. ^D (caret/D) causes all subsequent numeric input to be accepted as decimal numbers. This is the initial setting. [Not in TECO-10] ^R This command returns the binary value of TECO's current radix. [TECO-11 only] n^R This command sets TECO's radix to the value of n. It is currently implemented only in TECO-11, where n may only be one of the values 8, 10, or 16 (representing octal mode, decimal mode, or hexadecimal mode). If n is not one of these values, TECO's radix remains unchanged and the ?IRA error message is produced. Standard TECO Page 74 Arithmetic and Expressions \ A backslash character which is not preceded by a numeric argument causes TECO to evaluate the digit string (if any) beginning with the character immediately following the buffer pointer and ending at the next character that is not valid for the current radix. The value becomes the numeric argument of the next command. The first character may be a digit or + or -. As the backslash command is evaluated, TECO moves the buffer pointer to a position immediately following the digit string. If there is no digit string following the pointer, the result is zero and the pointer position remains unchanged. Except on TECO-8, the digits 8 and 9 will stop the evaluation if TECO's current radix is octal. n\ The backslash command preceded by an argument inserts the value of n into the text buffer at the current position of the pointer, leaving the pointer positioned after the last digit of the insertion. The insertion is either signed decimal (decimal radix), unsigned octal (octal radix), or unsigned hexadecimal (hexadecimal radix). Note that \ is a "bidirectional" command. n\ inserts a string into text while \ (no argument) returns a numeric result. Standard TECO Page 75 Special Numeric Values 5.11 SPECIAL NUMERIC VALUES TECO maintains several internal variables which record conditions within TECO. The variable name is equivalent to the current contents of the variable and may be entered as a numeric argument to TECO commands. When the command is executed, the current value of the designated variable becomes the numeric argument of the command. Some of the characters which stand for specific values associated with the text buffer have been introduced earlier in this manual. For example, the dot character (.), which represents the current pointer position, may be used in the argument of a T command. The command ".,.+5T" causes the 5 characters following the buffer pointer to be typed out. When this command is executed, the number of characters preceding the buffer pointer is substituted in each case for the "dot". The addition is then carried out, and the command is executed as though it were of the form "m,nT". Table 5-11 lists all of the characters which have special numeric values. Any of these characters may be used as numeric argument in place of the value it represents. TABLE 5-11: CHARACTERS ASSOCIATED WITH NUMERIC QUANTITIES CHARACTER FUNCTION B Always equivalent to zero. Thus, B represents the position preceding the first character in the buffer. Z Equivalent to the number of characters currently contained in the buffer. Thus, Z represents the position following the last character in the buffer. . Equivalent to the number of characters between the beginning of the buffer and the current position of the pointer. Thus "." represents the current position of the pointer. H Equivalent to the numeric pair "B,Z", or "from the beginning of the buffer up to the end of the buffer." Thus, H represents the whole buffer. nA Equivalent to the ASCII code for the .+n+1th character in the buffer (that is, the character to the right of buffer pointer position .+n). The expression -1A is equivalent to the ASCII code of the character immediately preceding the pointer and 0A is equivalent to the ASCII code of the character immediately following the pointer (the current character). If the character position referenced lies outside the bounds of the text buffer, this command returns a -1. Standard TECO Page 76 Special Numeric Values Mq The Mq command (execute the contents of the text storage area of Q-register "q" as a command string) may return a numeric value if the last command in the string returns a numeric value and is not followed by an ESCAPE. Qq Equivalent to the value stored in the number storage area of Q-register q. :Qq Equivalent to the number of characters in the text storage area of Q-register q. [Not in TECO-8] \ Backslash is equivalent to the numeric value of the digit string in the text buffer at the current pointer position, interpreted in the current radix. The pointer is moved to the end of the digit string. ^B (caret/B) is equivalent to the current date via the following equations: OS/8: ^B = (((month*32)+day)*8)+((year-1970)&7)+k where k = 4096 if year>1977 and k=0 otherwise RT-11: ^B = (((month*32)+day)*32)+year-1972 RSTS/E: ^B = ((year-1970)*1000)+day within year RSX-11: ^B = ((year-1900)*16+month)*32+day VAX/VMS: ^B = ((year-1900)*16+month)*32+day TOPS-10: ^B = (((year-1964)*12+month-1)*31+day-1) ^E (caret/E) is equivalent to -1 if the buffer currently contains a full page of text (which was terminated by a form feed in the input file) or 0 if the buffer contains only part of a page of text (which either filled the buffer to capacity before the terminating form feed was read or which was not terminated by a form feed.) The ^E flag is tested by the P command and related operations to determine whether a form feed should be appended to the contents of the buffer on output. ^F (caret/F) is equivalent to the current value of the console switch register. n^F n is the terminal number plus 200000 (octal) for job n's terminal. -1^F is the terminal number plus 200000 (octal) for your job's terminal. The result is 0 if the specified job is detached or if there is no such job. [TECO-10 only] ^H (caret/H) is equivalent to the current time of day via the following equations: Standard TECO Page 77 Special Numeric Values OS/8: ^H = 0 RT-11: ^H = (seconds since midnight)/2 RSTS/E: ^H = minutes until midnight RSX-11: ^H = (seconds since midnight)/2 VAX/VMS: ^H = (seconds since midnight)/2 TOPS-10: ^H = 60ths of a second since midnight (or 50ths of a second where 50 Hz power is used) ^N (caret/N) is the end of file flag. It is equivalent to -1 if the file open on the currently selected input stream is at end of file, and zero otherwise. ^S (caret/S) is equivalent to the negative of the length of the last insert, string found, or string inserted with a "G" command, whichever occurred last. To back up the pointer to the start of the last insert, string found, etc., type "^SC". [Not in TECO-8] ^T (caret/T) is equivalent to the ASCII code for the next character typed at the terminal. Every ^T command executed causes TECO to pause and accept one character typed at the terminal. See the ET flag description (section 5.16) for variations. ^Y (caret/Y) is equivalent to ".+^S,.", the n,m numeric argument spanning the text just searched for or inserted. This value may be used to recover from inserting a string in the wrong place. Type "^YXAFR$" to store the string in Q-register A and remove it from the buffer. You can then position the pointer to the right place and type "GA" to insert the string. [TECO-11 only] ^Z (caret/Z) is equivalent to the total space occupied by text in the Q-registers (including the command line currently being executed). [TECO-11 only] ^^x The combination of the Control-caret (double caret or double up-arrow) followed by any character is equivalent to the value of the ASCII code for that character. The "x" in this example may be any character that can be typed in to TECO. MODE CONTROL FLAGS The use of these flags is described below in section 5.16. ED Equivalent to the current value of the edit level flag. EH Equivalent to the current value of the help level flag. Standard TECO Page 78 Special Numeric Values EO Equivalent to the version number of the version of TECO which is currently being run. This manual describes TECO-11 Version 36, TECO-8 Version 7, and TECO-10 Version 3. ES Equivalent to the current value of the search verification flag. [Not in TECO-8] ET Equivalent to the current value of the type out control flag. EU Equivalent to the current value of the upper/lower case flag. EV Equivalent to the current value of the edit verify flag. [TECO-11 only] ^X (caret/X) is equivalent to the current value of the search mode flag. [Not in TECO-8] Standard TECO Page 79 Command Loops 5.12 COMMAND LOOPS You can cause a command string to be executed any number of times by placing the command string within angle brackets and preceding the brackets with a numeric argument designating the number of iterations. Iterated command strings are called command loops. Loops may be nested so that one command loop contains another command loop, which, in turn, contains other command loops, and so on. The maximum depth to which command loops may be nested is determined by the size of TECO's push-down list (system dependent), but is always greater than 10. The general form of the command loop is: n where "command string" is the sequence of commands to be iterated and n is the number of iterations. If n is not supplied then no limit is placed on the number of iterations. If n is 0 or less than 0 then the iteration is not executed at all; command control skips to the closing angle bracket. If n is greater than 0, then the iteration is performed n times. Search commands inside command loops are treated specially. If a search command which is not preceded by a colon modifier is executed within a command loop and the search fails, a warning message is printed [on TECO-11], the command loop is exited immediately and the command following the right angle bracket of the loop is the next command to be executed. If an unmodified search command in a command loop is immediately followed by a semicolon, it is treated as if it were a colon-modified search (see section 5.13). Standard TECO Page 80 Branching Commands 5.13 BRANCHING COMMANDS TECO provides an unconditional branch command and a set of conditional execution commands. To branch within a command string, you must be able to name locations inside the string. TECO permits location tags of the form: !tag! to be placed between any two commands in a command string. The name "tag" will be associated with this location when the command string is executed. Tags may contain any number of ASCII characters and any character except an exclamation mark. (When using the @ form of this command, any character except the delimiter is legal.) Since tags are ignored by TECO except when a branch command references the tagged location, they may also be used as comments within complicated command strings. The unconditional branch command is the O command which has the form: Otag$ where "tag" is a location named elsewhere in the command string and "$" signifies an ESCAPE. When an O command is executed, the next command to be executed will be the one that follows the tag referenced by the O command. Command execution continues normally from this point. Use of the O command is subject to two restrictions. First, if an O command is stored in a Q-register as part of a command string which is to be executed by an M command, the tag referenced by the O command must reside in the same Q-register. Second, an O command which is inside a command loop may not branch to a tagged location preceding the command loop. However, it is always possible to branch out of a command loop to a location which follows the command loop and then branch to the desired tag. The string argument in the O command has the same format as the string arguments in the search and E commands. String build characters such as ^EQq can be embedded within the string in TECO-11. Also, in TECO-11 and TECO-10, the O command may be @-sign modified. In that case, the syntax of the command would be @O/tag/ where / represents any delimiting character that does not appear within the tag. Branching into a conditional poses no problems, but branching into a command loop will causes unpredictable results. Although tags may contain any sequence of ASCII characters, good programming practice dictates that tags should not contain unusual characters (such as space, comma, ESCAPE, etc.) and that Standard TECO Page 81 Branching Commands they should be mnemonic for the piece of code to which they refer. There are many other branching commands. Most of these are considerably faster than the O command and should be used wherever convenient. They are all described in the table below. TABLE 5-13: BRANCHING COMMANDS COMMAND FUNCTION Otag$ This command causes TECO to branch to the first occurrence of the specified label (tag) in the current macro level. In TECO-8 and TECO-11, branching to the left of the start of the current iteration is not permitted, and this command will only look for an occurrence of the specified tag following the < of the current iteration, if you are in an iteration. In any case, branching out of an iteration is poor programming practice. Command execution resumes at the first character after the delimiter terminating the specified tag. Using this syntax, any character except is permitted in the tag specification. The usual string build characters are permitted when specifying the tag. @O/tag/ Equivalent to Otag$ except that a delimiter (shown here as /) is used before and after the specified tag. Any character other than that delimiter is permitted inside the tag. The usual string build characters are permitted when specifying the tag. [Not in TECO-8] nOtag0,tag1,tag2,...$ This command causes TECO to branch to the tag specified by the nth tag in the accompanying list. The string argument to this command consists of a sequence of tags separated by commas. The tags may contain any characters other than comma or ; however, good programming practice dictates that the tags should consist only of letters and digits. There must be no intervening spaces since these would be considered part of the tag. If n is out of range, then command execution continues with the first command following the that delimits this command. [TECO-11 only] n@O/tag0,tag1,tag2,.../ Same as the preceding command except that the list of tags is bracketed by a delimiter shown here as "/". The delimiter can be any character that does not appear within the list of tags. In particular, using comma for the delimiter would not be very useful. [TECO-11 only] Standard TECO Page 82 Branching Commands ; This command causes TECO to branch out of the current iteration, if the immediately preceding search (or search and replace) command failed. In that case, control resumes at the character following the matching > at the end of the current iteration. On the other hand, if the preceding search succeeded, command execution continues with the character following the ;. If this command is encountered from outside of an iteration (in the current macro level), then the ?SNI error message is issued. n; This command causes TECO to branch out of the current iteration if the value of n is greater than or equal to 0. In that case, command execution resumes at the character following the matching > at the end of the current iteration. On the other hand, if n is less than 0, command execution continues with the character following the ;. If this command is encountered from outside of an iteration (in the current macro level), then the ?SNI error message is issued. :; This command causes TECO to branch out of the current iteration if the immediately preceding search (or search and replace) command succeeded. In that case, control resumes at the character following the matching > at the end of the current iteration. On the other hand, if the preceding search failed, command execution continues with the character following the ;. If this command is encountered from outside of an iteration (in the current macro level), then the ?SNI error message is issued. [TECO-11 only] n:; This command causes TECO to branch out of the current iteration if the value of n is less than 0. In that case, command execution resumes at the character following the matching > at the end of the current iteration. On the other hand, if n is greater than or equal to 0, command execution continues with the character following the ;. If this command is encountered from outside of an iteration (in the current macro level), then the ?SNI error message is issued. [TECO-11 only] ' This "command" is actually part of the syntax of TECO conditionals. It has no affect if "executed" other than to signify termination of the current conditional level. If an argument is specified to this command, the result is not defined. (Arguments pass through this command on TECO-11.) Conditionals are described in section 5.14. | This "command" is actually part of the syntax of TECO Standard TECO Page 83 Branching Commands conditionals. If executed, it causes control to branch to the end of the conditional. Command execution resumes with the character following the ' that ends the current conditional with the ELSE clause being skipped. > This "command" is actually part of the syntax of TECO iterations. If executed, it causes TECO to bump the current iteration count by 1 and test to see if the resulting count is equal to the maximum count permitted for the iteration (specified as an argument before the matching <). If the iteration count has not expired, then control returns to the command following the < at the beginning of the current iteration. If the iteration has expired, then command execution continues with the character following this >. If this command is encountered outside of an iteration (within the current macro level), then the ?BNI error message (or its equivalent) is issued. F> This command causes TECO to branch (flow) to the end of the current iteration. TECO effectively resumes execution at the matching >. The iteration count is tested as usual. If it has not expired, control returns back to the start of the iteration with the count having been incremented by 1. If the count was up, the iteration is exited and control continues with the first command after the >. If this command is encountered outside of an iteration, it has the same effect as the command. [TECO-11 only] F< This command causes TECO to branch (flow) to the start of the current iteration. TECO effectively resumes execution at the first command following the < at the beginning of the current iteration. The iteration count is not affected. If this command is issued outside of an iteration, it causes TECO to branch back to the start of the current command string (in the current macro level). [TECO-11 only] F' This command causes TECO to branch (flow) to the end of the current conditional. TECO effectively resumes execution at the first command following the ' at the end of the current conditional. Numeric arguments are eaten up by this command. If this command is issued while not in a conditional, the ?MAP error (or its equivalent) is issued. [TECO-11 only] F| This command causes TECO to branch (flow) to the else clause of the current conditional. TECO effectively resumes execution at the first command following the | Standard TECO Page 84 Branching Commands at the end of the current THEN clause. If the current conditional has no ELSE clause, or if an unmatched ' is encountered before an unmatched |, then control resumes at the command following the ' . Numeric arguments are eaten up by this command. If this command is issued while not in a conditional, the ?MAP error (or its equivalent) is issued. Well-structured programs should not need to use this command. [TECO-11 only] $$ The command causes TECO to exit from the current macro level. If this command is issued from top level (not from within a macro), then the command string execution is terminated and TECO returns to prompt level. Note that the second must be a true ESCAPE and may not be a ^[. Also, note that both ESCAPEs must be true TECO commands and not part of the syntax of some previous command. That is, the first does not count if it is the delimiting ESCAPE of a string. n$$ This command causes TECO to exit from the current amcro level, returning the number n as a value. This value will be used as the numeric argument to the first command following the macro call. m,n$$ This command causes TECO to exit from the current macro level, returning the pair of values m and n as arguments to the first command following the macro call. Good programming practice dictates that all ways of exiting a macro return the same number of arguments. ^C The (Caret-C) command when executed as a TECO command, causes command execution to stop and control return to TECO's prompt. No clean-up of push-down lists, flag settings, etc. is done. This command lets a macro abort TECO's command execution. [On TECO-8 and TECO-10, this command causes control to return to the operating system.] [On TECO-11, this command returns to the operating system if executed from the top level.] Consult the appendices for specific details concerning your operating system. ^C This command causes TECO to unconditionally abort and control exits from TECO. Control returns to the operating system. The second must be a true and may not be a Caret-C. Standard TECO Page 85 Conditional Execution Commands 5.14 CONDITIONAL EXECUTION COMMANDS All conditonal execution commands are of the form: n"X command-string ' or n"X then-command-string | else-command-string ' In the first form of the command, "n" is a numeric argument on which the decision is based, "X" is any of the conditional execution commands listed in table 5-14, and "command string" is the command string which will be executed if the condition is satisfied. The numeric argument is separated from the conditional execution command by a double quote (") and the command string is terminated with an apostrophe ('). If the condition is not satisfied, the command string will not be executed; execution will continue with the first command after the apostrophe. In the second form of the command, two command strings are specified. The first one is executed if the condition is satisfied and the second is executed if the condition is not satisfied. Only one of the command strings will be executed. After execution of the appropriate command string, control will continue with the first command after the apostrophe (unless the command string caused a branch out of the conditional to occur), since execution of the vertical bar command (|) causes TECO to scan to the next matching apostrophe. Conditional commands are similar to the IF-THEN-ELSE constructs that you find in other structured programming languages, although none can match the brevity and elegance of TECO's implementation. Nonetheless, you must use these facilities wisely. Good programming practice dictates that a branch into the range of a conditional (from outside that range) should not occur. Conditional execution commands may be nested in the same manner as iteration commands. That is, the command string which is to be executed if the condition on n is met may contain conditional execution commands, which may, in turn, contain further conditional execution commands. TABLE 5-14: CONDITIONAL EXECUTION COMMANDS COMMAND FUNCTION n"A Execute the following command string if n equals the ASCII code for an alphabetic character (upper or lower case A to Z). n"C Execute the following command string if n is the ASCII code of any character that is a symbol constituent. This is usually one of the upper or lower case letters Standard TECO Page 86 Conditional Execution Commands A to Z, one of the digits 0 to 9, or period, or dollar sign, but may include additional characters on some operating systems. Consult the appropriate appendix. n"D Execute the following command string if n equals the ASCII code for a digit (0 to 9). n"E Execute the following command string if n is equal to zero. n"F Execute the following command string if n is FALSE. Equivalent to n"E. n"G Execute the following command string if n is greater than zero. n"L Execute the following command string if n is less than zero. n"N Execute the following command string if n is not equal to zero. n"R Execute the following command string if n equals the ASCII code for an alphanumeric (upper or lower case A to Z or 0 to 9). n"S Execute the following command string if n is SUCCESSFUL. Equivalent to n"L. n"T Execute the following command string if n is TRUE. Equivalent to n"L. n"U Execute the following command string if n is UNSUCCESSFUL. Equivalent to n"E. n"V Execute the following command string if n equals the ASCII code for a lower case alphabetic character (lower case A to Z). [Not in TECO-8] n"W Execute the following command string if n equals the ASCII code for an upper case alphabetic character (upper case A to Z). [Not in TECO-8] n"< Identical to n"L n"> Identical to n"G n"= Identical to n"E Standard TECO Page 87 Retrieving Environment Characteristics 5.15 RETRIEVING ENVIRONMENT CHARACTERISTICS The following TECO commands return values of interest to users who want information about their current job, the operating system, their terminal, etc. All negative EJ commands return an operating system dependent value. Consult the appendices for operating system unique commands. TABLE 5-15A: RETREIVING ENVIRONMENT CHARACTERISTICS COMMAND FUNCTION -1EJ Return a number representing the computer and operating system upon which TECO is currently running. This value has the form 256m+n where m is a number representing the computer in use and n is a number representing the operating system that is running. Current values of m and n are: Computer (m) Operating System (n) 0 PDP-11 0 RSX-11D 1 RSX-11M 2 RSX-11S 3 IAS 4 RSTS/E 5 VAX/VMS (compatibility mode) 6 RSX-11M+ 7 RT-11 1 PDP-8 0 OS/8 2 DEC-10 0 TOPS-10 3 DEC-20 0 TOPS-20 4 VAX-11 0 VAX/VMS (native mode) 0EJ Returns a value equal to your job number. On single-user systems, this is always a 0. 1EJ Returns a value equal to your console keyboard number (the keyboard you detached from if you are running detached). On single-terminal systems, this is always a 0. 2EJ Returns a value equal to your operating system's user identification number. This may be called your UIC, PPN, Group, etc. under various operating systems. Consult the appendices for more information. Standard TECO Page 88 Retrieving Environment Characteristics TABLE 5-15B: SETTING ENVIRONMENT INFORMATION n,1EJ Set the terminal number to receive output. This will not affect terminal input. Your job will remain attached to, or detached from, your terminal, whichever it was before. Output will only occur if the specified terminal is ASSIGNed with a monitor ASSIGN command (you may ^C, issue that command and continue) and if your job has POKE privileges. This command also sets the terminal to be reattached if the set detach flag (64&ET) is cleared. The reattaching operation requires [1,2] or JACCT privileges. [TECO-10 only] n,2EJ Sets your [p,pn] to n where n has the same format as the number returned by the 2EJ command. Issuance of this command requires the appropriate privileges. [TECO-10 only] Standard TECO Page 89 Mode Control Flags 5.16 MODE CONTROL FLAGS TECO has flags which control various aspects of its operation. You can find a flag's current setting by executing its command name without an argument; the current setting of the flag is returned as a value. A flag may be set to a specific value by executing its command name preceded by a numerical argument; the flag is set to the value of the argument. The following table describes the commands that set and clear flags; represents any of the flags listed above. TABLE 5-16A: FLAG MANIPULATION COMMANDS Return value of flag. n Set value of flag to n. m,n In the flag, turn off those bits specified by m and turn on those bits specified by n. 0,n Turn on the bits in the flag specified by n. m,0 Turn off the bits in the flag specified by m. The flags have the following functions: TABLE 5-16B: MODE CONTROL FLAGS COMMAND FUNCTION ED The edit level flag, a bit-encoded word that controls TECO's behavior in various respects. Any combination of the individual bits may be set as the user sees fit. The bits have the following functions: ED&1 Allow caret (^) in search strings. If this bit is clear, a caret (^) in a search string modifies the immediately following character to become a control character. When this bit is set, a caret in a search string is simply the literal character caret. If you are editing a file that contains many caret characters (e.g., a RUNOFF file with case control), you will want to set this bit. ED&2 Allow all Y and _ commands. If this bit is set, the Y (Yank) command and _ (underscore or backarrow) command work unconditionally as described earlier in the manual. If clear, the behavior of the Y and _ commands are Standard TECO Page 90 Mode Control Flags modified as follows: If an output file is open and text exists in the text buffer, the Y or _ command will produce an error message and the command will be aborted leaving the text buffer unchanged. Note that if no output file is open the Y and _ commands act normally. Furthermore, if the text buffer is empty the Y command can be used to bring in a page of text whether or not an output file is open (HKY will always work). The _ command will succeed in bringing one page of text into an empty text buffer but will fail to bring in successive pages if an output file is open. ED&4 When this bit is clear, TECO will try to expand memory as much as it can in order to try to fit entire pages into memory when requested to do so. If this bit is set, arbitrary memory expansion will not occur. In that case, TECO will expand memory only on the A command and not on the Y, P, or N commands. This bit is always set in TECO-10 and has no significance in TECO-8 or in TECO-11 on RT-11. ED&8 Reserved for future use by TECO-8. ED&16 Allow failing searches to preserve dot. If this bit is set, then whenever a search fails, the original location of the text buffer pointer will be preserved. If this bit is clear, then failing searches (other than bounded searches) leave the text buffer pointer at pointer position 0 after they fail. [not in TECO-8] ED&32 Reserved for future use by TECO-11. ED&64 Only move dot by one on multiple occurence searches. If this bit is clear, TECO treats nStext$ exactly as n<1Stext$>. That is, skip over the whole matched search string when proceeding to the nth search match. For example, if the text buffer contains only A's, the command 5SAA$ will complete with dot equal to ten (10). If this bit is set, TECO increments dot by one each search match. In the above example, dot would become five (5). [TECO-11 only] The initial value of ED&1 is system dependent (See appendices). The initial value of the other bits in Standard TECO Page 91 Mode Control Flags the ED flag is 0. EH The help level flag, which controls the printing of error messages and failed commands. EH&3 The low two bits of EH (value range 0 through 3) control the printing of TECO error messages as follows (assuming the low two bits have value m): If m is equal to 1, error messages are output in abbreviated form ("?XXX"). If m is equal to 2, error messages are output in normal form ("?XXX Message"). If m is equal to 3, error messages are output in long or "War and Peace" form, that is, a paragraph of informative material is typed following the normal form of the error message. This mode is not implemented in TECO-11, in which case m=3 is equivalent to m=2. EH&4 If this bit of EH is set, the failing command is also output up to and including the failing character in the command followed by a question mark. (Just like TECO's response to the typing of a question mark immediately after an error.) This bit is not supported by TECO-10. The initial value of the EH flag is 0 which is equivalent to a value of 2. EO Setting the value of the EO flag to n allows features that were peculiar to that version of TECO to work. [TECO-10 only] ES The search verification flag, which controls the text typed out after searches. If n is equal to 0, nothing is typed out after searches. If n is -1, the current line is typed out when a successful search at top level is completed (i.e., a V command is done automatically). If n is between 1 and 31, the current line is typed out with a line feed immediately following the position of the pointer to identify its position. If n is between 32 and 126, the current line is typed out with the ASCII character corresponding to the value of n immediately following the position of the pointer to identify its position. If you want to see more than one line of type out, use the form m*256+n. The n is the same as above. The m is the number of lines of view. For example, 3*256+^^! would give two lines on either side of the found line, and the found line with the Standard TECO Page 92 Mode Control Flags character "!" at the pointer's position. The ES flag does not apply to searches executed inside iterations or macros; lines found inside iterations or macros are never typed out. [Not in TECO-8] The initial value of ES is 0. ET The ET flag is a bit-encoded word controlling TECO's treatment of the console terminal. Any combination of the individual bits may be set. The bits provide the following functions, when set: ET&1 Type out in image mode. Setting this bit inhibits all of TECO's type out conversions. All characters are output to the terminal exactly as they appear in the buffer or ^A command. For example, the changing of control characters into the "caret/character" form, and the conversion of to $ (dollar sign) are suppressed. This mode is useful for driving displays. It should be used with caution, especially if you are talking to TECO over a dial-up line. ET&2 Process DELETEs and s in "scope" mode. Scope mode processing uses the cursor control features of CRT type terminals to handle character deletion by actually erasing characters from the screen. ET&4 Read lower case. TECO normally converts all lower case alphabetics to upper case on input. Setting this bit causes lower case alphabetics to be input as lower case. TECO commands and file specifiers may be typed in either upper or lower case. For the purpose of searches, however, upper and lower case may be treated as different characters. (See ^X flag). ET&8 Read without echo for ^T commands. This allows data to be read by the ^T command without having the characters echo at the terminal. Normal command input to TECO will echo. ET&16 Cancel on type out. Setting this bit will cancel any outstanding when the next type out occurs. After TECO has canceled the , it will automatically clear the bit. ET&32 Read with no wait. This enables the ^T Standard TECO Page 93 Mode Control Flags command to test if a character is available at the user terminal. If a character has been typed, ^T returns the value of the character as always. If no character has been typed, ^T immediately returns a value of -1 and execution continues without waiting for a character. ET&64 Detach flag (See appendices). ET&128 When this bit is set: 1) all informational messages are supressed, 2) any causes the immediate termination of TECO, and 3) any error causes the termination of TECO after the error message is printed. ET&256 If this bit is set, all lines output to the terminal are truncated to the terminal's width if needed. (RSTS/E, RSX-11, and VAX/VMS only.) ET&512 If this bit is set, the scope "WATCH" feature of TECO is present and your terminal is a scope type terminal. This bit is a read-only bit; its state cannot be altered. (See Section 5.17.) ET&1024 If this bit is set, the refresh scope "WATCH" feature of TECO is present and a refresh scope is available. This bit is a read-only bit; its state cannot be altered. (See Section 5.17.) ET&32768 If this bit is set and a is typed, the bit is turned off, but execution of the current command string is allowed to continue. This allows a TECO macro to detect typed s. In TECO-8, this bit is the 2048's bit rather than the 32768's bit. The initial setting of ET is operating system dependent (See appendices). In addition, some of the ET bits are automatically turned off by certain error conditions. EU The upper/lower case flag. If n is -1, no case flagging of any type is performed on type out, lower case characters are output as lower case characters. If n is 0, lower case characters are flagged by outputting a ' (quote) before the lower case character and the lower case character is output in upper case; upper case characters are unchanged. If n is +1, upper case characters are flagged by outputting Standard TECO Page 94 Mode Control Flags a ' (quote) before each one and then the upper case character is output; lower case characters are output as their upper case equivalents. The initial value of the EU flag is -1 if TECO can tell from the operating system that the user's terminal supports display of lower case characters; otherwise te initial value is 0. Consult the appendices for more details. EV The edit verify flag is decoded just like the ES flag. Just before TECO prints its prompting *, the EV flag is checked. If it is non-zero the lines to be viewed are printed on the terminal. The initial value of the EV flag is 0. [TECO-11 only] ^X The search mode flag. [Not in TECO-8] If n is 0, the text argument in a search command will match text in the text buffer independent of case in either the search argument or the text buffer. Thus the lower case alphabetics match the upper case alphabetics and "`", "{", "|", "}", "~" match "@", "[", "\", "]", "^" respectively. If n is -1, the search will succeed only if the text argument is identical to text in the text buffer. The initial value of the ^X flag is 0. Standard TECO Page 95 Scope Commands 5.17 SCOPE COMMANDS The W command (scope "WATCH") is present in most implementations of TECO. There are two different variations of the W command. Neither, one, or both may be present. ET flag Bits 9 and 10 indicate which variation(s) are configured and can be used. 5.17.1 Video Terminal Scope Commands If the VT support is present and your terminal is a video terminal (such as a VT05, VT52, or VT100), ET flag Bit 9 (value 512) will be on. TABLE 5-17A: VIDEO TERMINAL WATCH COMMANDS COMMAND FUNCTION -1W Refresh the terminal's screen to show the contents of the text buffer. -nW Tell the video terminal screen refresher that the top n-1 lines of the screen have been altered. The screen refresher will completely redraw the top n-1 lines of the screen upon the next -1W command. nW Place the default cursor line at line n of the screen. The initial default cursor line is line 16. This command makes the window support forget the screen image and any special associated modes (SEEALL, MARK, HOLD). 0W Equivalent to "16W". W Forget screen image and special scope modes. -1000W Forget that output was done. Normally, if the user outputs to the terminal with a command such as T, n^T, or ^A, TECO will believe that the window needs updating, and upon the next -1W command, TECO will refresh the entire window display. Issuing the -1000W command informs TECO that the output command did not destroy the window. [TECO-11 only] The :W command is used to interrogate and set video terminal status information, as well as implement some of the more advanced features of the video terminal "WATCH" functions. Standard TECO Page 96 Video Terminal Scope Commands TABLE 5-17B: VIDEO TERMINAL STATUS COMMANDS COMMAND FUNCTION 0:W Return a number representing the type of scope in use as the editing terminal. Current values are: 0 VT52 1 VT61 [TECO-10 only] 2 VT100 in VT52 mode 4 VT100 in ANSI mode 6 VT05 :W Equivalent to 0:W 1:W Return the horizontal size of the user's editing scope. This number represents the number of character positions available horizontally along the face of the scope. 2:W Return the vertical size of the user's editing scope. This number represents the number of lines of text that can appear on the screen of the terminal. 3:W Returns SEEALL mode. 0 represents off and -1 represents on. In SEEALL mode, a visible indication is shown in the window for every character, including characters that normally don't print. 4:W Returns mark status of window support. 0 means that no mark has been set. A value of n means that a mark has been set at buffer ("dot") position n-1. This status is used by software that uses the window support and by the support itself in the case of scopes that support reverse video. 5:W Returns the hold mode indicator. 0 means off, -1 means hold whole screen, and a positive value, n, means hold all but top and bottom n lines. If hold mode is on, then scrolling is inhibited until the cursor is about to run off either end of the screen. This makes the window display more palatable on terminals on a slow line. If hold mode is on, the window support will scroll the window as necessary in an attempt to keep the cursor centered. 6:W Returns buffer pointer position of character that was in the upper left hand corner of the window as of the last -1W command. 7:w Returns the number of scrolling lines. If n is zero, then scrolling is turned off. When scrolling is enabled, n lines as specified are reserved at the bottom of the screen to scroll the terminal Standard TECO Page 97 Video Terminal Scope Commands interaction. The remainder of the screen is used as a window and is updated by TECO immediately before each command prompt. The scrolling feature only functions on terminals capable of split screen scrolling functions, such as the VT100. m,n:W Sets the entity represented by n:W to m and returns a value. If the new setting has been accepted, the returned value is m. Elsewise, the returned value is either the old value associated with n:W or whatever new setting was actually set. In all cases, the returned value reflects the new current setting. Specific operating systems may put restrictions on the valid values for m. 5.17.2 Refresh Scope Commands If refresh scope support is present and a refresh scope is available (such as a VS60 or a VR12), bit value 1024 of the ET flag will be on. TABLE 5-17C: REFRESH SCOPE WATCH COMMANDS COMMAND FUNCTION W Update the refresh scope screen to reflect the contents of the text buffer surrounding the text pointer ("dot"). 0W Turn off the refresh scope display. nW Set the number of lines to be displayed around the text pointer to n. Standard TECO Page 98 Programming Aids 5.18 PROGRAMMING AIDS In addition to the command string editing capabilities described in Chapter 4, TECO includes various features to facilitate programming. These are described in the following sections. 5.18.1 Text Formatting The characters carriage return, line feed, and space are ignored in command strings, except when they appear as part of a text argument. Numeric values are not affected. (Inserting a space between digits within a digit string may cause unpredictable results). These characters may be inserted between any two TECO commands to lend clarity to a long command string. The carriage return/line feed combination is particularly useful for typing command strings which are too long to fit on a single line. If the character form feed is encountered in a command string and it is not part of a text argument, a form feed is output to the terminal. This can be used to format terminal output. On TECO-10, execution of the form feed command will clear the screen if TECO is in scope command string editing mode (2&ET on). 5.18.2 Comments One of the most powerful features of TECO is its ability to store very long command strings so that a given sequence of commands may be executed whenever needed. Long command strings may be thought of as editing programs and, like any other type of program, they should be documented by means of comments. Comments may be inserted between any two commands by using a tag construction of the form: !THIS IS A COMMENT! Comments may contain any number of characters and any characters except the special characters. Thus a long TECO macro might look like: TECO commands !This comment describes line 1! TECO commands !This comment describes line 2! more commands more commands !end of comment string! Do not use characters to format long command strings! Only , , and can be used to format command strings since is an insertion command. Good TECO code is well structured and adequately commented. Unfortunately, massive comments in a TECO macro tend to slow execution, especially if they appear within text scanned by GOTOs Standard TECO Page 99 Programming Aids or unsatisfied conditionals. Unless speed is not a goal, it is common practice in larger TECO programs to strip out comments before loading up TECO macros. Thus the TECO program can be adequately commented, yet still run efficiently. A large TECO program can start by placing a comment stripper in a Q-register, say Q-register C. Then it can successively put subroutines (macro text) into the text buffer, do an MC, and load the appropriate Q-register with the resulting text buffer, until all the subroutines have been loaded. Finally, Q-register C can be zeroed and the program started. In order for you to strip the comments without losing essential tags, you must make a convention for the format of your comments so that your comment stripper can distinguish them from tags. There are two common conventions. In one, the first character in every comment after the initial ! is some distinctive character, such as *. In the other, all tags start in the left margin and all comments are embedded within the text. Any large comment that wants to be on a line by itself starts with a before the !. Both methods allow for readable code and easy comment stripping. 5.18.3 Messages The command may be used to print out a statement at any point during the execution of a command string. The command has the general form: ^Atext or @^A/text/ The first ^A is the actual command, which may be entered by striking the control key and the A key simultaneously or by typing a caret (uparrow) followed by an A character. The second character of the first form shown is the command terminator, which must be entered by typing the control key and the A key simultaneously. In the second form, the second occurrence of the delimiting character (shown as slash in the example) terminates the message. Upon execution, this command causes TECO to print the specified message at the terminal. The ^Amessage command is particularly useful when it precedes a command whose numeric argument contains ^T or ^F characters. The message may contain instructions notifying the user as to what sort of input is required. 5.18.4 Tracing