TECO TEXT EDITOR AND CORRECTOR FOR RSX-11D PREFACE The implementation of the TECO Text Editor under RSX-11D does NOT represent a supported product of the RSX-11D development team. This implementation evolved as a convenience for RSX-11D programmers who preferred TECO to SLPR or to LETTER (11-D EDIT). However, it is felt that TECO under RSX-11D is of value to others and is therefore being made available via DECUS. This manual describes TECO as currently implemented under RSX-11D. The manual is based primarily upon the OS/8 TECO Users Manual (DEC-S8-UTECA-A-D) augmented by DECsystem-10 documentation (DEC-10-NGZB-D). RSX-11D TECO is a superset of DECsystem-10 TECO. Experienced TECO users will find a description of changes from DECsystem-10 TECO in Appendix B. Note: Currently, TECO will crash disastrously if a control-@ is typed. RSX-11D TECO Page 2 INTRODUCTION TECO is a powerful text editing and correcting program that runs under the RSX-11D operating system. TECO may be used to edit any form of ASCII text such as program listings, manuscripts, correspondence and the like. Since TECO is a character-oriented editor rather than a line editor, text edited with TECO does not have line numbers associated with it, nor is it necessary to replace an entire line of text in order to change one character. Because TECO is very versatile, it is necessarily complex. This manual is, therefore, divided into two parts. Section I 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 convenient, in most cases, than the advanced commands presented later. Section II introduces the full TECO command set, including a review of the introductory commands presented earlier. This section also introduces the concept of TECO as a programming language and explains how basic editing commands may be combined into "programs" which are sophisticated enough to handle the most complicated editing tasks. Specific examples of the use of TECO commands have been de-emphasized throughout this manual. This was done because all of the TECO commands have a consistent, logical format which will quickly become apparent to the novice user. However, each section of the manual is concluded with one or more elaborate examples which employ most of the commands introduced up to that point. Users who are learning TECO commands should experiment with each command as it is introduced, then duplicate the examples on their computer. RSX-11D TECO Page 3 SECTION I INTRODUCTORY COMMANDS TECO considers text to be any string of ASCII codes. Text is broken down into units of pages, lines, and characters. A page of text consists of all the ASCII codes between two form feed characters, including the second form feed. A character is one ASCII code. Thus, every page of text contains one form feed character, which is the last character on the page. Every line of text contains one line feed, which is the last character on the line. TECO maintains a text buffer in which text is stored. The buffer usually contains one page of text consisting of up to about 11000 characters, but the terminating form feed character never appears in the buffer. TECO also maintains a buffer pointer. The pointer is simply a movable position indicator which is always located between two characters in the buffer, before the first character in the buffer, or after the last character in the buffer. The pointer is never located on a character. Line feed and form feed characters are inserted automatically by TECO. A line feed is automatically appended to every carriage return entered into the buffer, and a form feed is appended to the content 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. That is, all text preceding the form feed will appear on one page, and the text following the form feed will appear on the next page. Finally, TECO also maintains an input file and an output file, both of which are selected by the user through the use of file specification commands. The input file is any device from which text may be accepted. For example, if a block of text is stored on paper tape, the paper tape reader would be specified as an input file when the tape is edited. The output file is any device on which edited text may be written. If the paper tape file mentioned above were to be edited and written onto a disk, for example, the output file would be a user-named disk file. TECO may be called from the MCR by typing: MCR>TEC (terminated with a carriage return). TECO will respond by printing an asterisk at the left margin to indicate that it is ready to accept user commands. At this point, one or more commands may be typed at the terminal, and TECO will execute the commands upon receipt of two consecutive ALT MODE characters. The ALT MODE is a non-printing character which may be labelled RSX-11D TECO Page 4 ESCAPE or PREFIX on some keyboards. TECO echoes a dollar sign ($) whenever an ALT MODE is received. 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 might be used to indicate such things as the number of times a command should be executed. A text argument is a string of ASCII characters which might be words of text, for example, or an RSX-11D 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 ALT MODE) which indicates to TECO that the next character typed will be the first character of a new command. If more than one command is typed in response to the asterisk generated by TECO, the command string will be executed from left to right until either all commands have been executed or a command error is recognized. When an error is encountered, a message is printed and the rest of the command string is ignored. In any case, TECO prints another asterisk at the left margin as soon as it finishes execution of a command string, so that additional commands may be entered. The extensive text editing capability of TECO implies a large and versatile command set. However, the novice TECO user will find that little more than a dozen basic commands suffice for most editing requirements. The following section introduces the basic TECO commands. The full command set will be described later in this manual. TECO will accept input text from any input device in the RSX-11D system. If input is supplied from any device except the keyboard, the input device must be specified by means of an ER command terminated by an ALT MODE. If the input device is a file-structured device, the file name and extension (if any) must also be supplied. If a file name is specified and no device is explicitly defined, the default device SY is assumed. The ER command causes TECO to search for 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 ERde:filename.ext;n$ General form of the ER command where "de:filenam.ext;n" is the designation of the input file. The command is terminated by an ALT RSX-11D TECO Page 5 MODE, 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 default device. ERDK1:PROG$ Prepare to read input file PROG from DK1. TECO will write output text onto any device in the system. If output is written onto any device except the user terminal, the output device must be specified by means of an EW command terminated by an ALT MODE. If the output device is file-structured, a file name and extension (if any) must also be supplied. If a file name is specified but no device is explicitly defined, the defaut device SY is assumed. The following examples illustrate use of the EW command, which has the same format as the ER command: COMMAND FUNCTION EWde:filename.ext;n$ General form of the EW command where "de:filenam.ext;n" is the designation of the output file. The command is terminated by an ALT MODE, which echoes as a dollar sign. EWSY:TEST.LST$ Prepare to write output file TEXT.LST on the default system device. EWPROG$ Prepare to write output file PROG on the system default device. EWDK1:TEXT.LST$ Prepare to write output file TEST.LST on DK1. It is not always necessary to specify an input file. If the user desires to create a file without using any previously edited text as input, he may insert the necessary text directly into the text buffer from the keyboard and, at the end of each page, write the content of the buffer onto an output file. Since all input is supplied from the keyboard, no input file is necessary. An output file is unnecessary if the user desires only to examine an input file, without making permanent changes or corrections. In this case, the content 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. RSX-11D TECO Page 6 TECO will only keep one input and one output file open at a time. The current input file may be changed by simply using the ER command to specify a new file. Before an output file may be changed, it is essential that the current output file be closed by means of an EF command (or one of the other file closing commands presented later). If this is not done, the content of the file may be lost. The EF command is presented below along with several examples of file specification command strings. COMMAND: EF FUNCTION: Close the current output file. If the last EW command specified a file which already existed on the device, TECO created an additional file with the same file name and extension, but with the version number incremented by 1 at the time the new file was opened. COMMAND STRING: ERDK1:INPUT.MAC$EWOUTPUT.MAC$$ FUNCTION: Open an input file "INPUT.MAC" to be found on DK1 and open an output file named "OUTPUT.MAC" on SY. If file OUTPUT.MAC does not already exist, it will be created. The double ALT MODE ($$) terminates the command string and causes the string to be executed. COMMAND STRING: EFEWTEXT.LST$$ FUNCTION: Close the current output file and open an output file "TEST.LST" on the default device. Note that the ALT MODE which terminates the EW command may be one of the two ALT MODEs which terminates the command string. COMMAND STRING: ERPR:$EFEWSY:FILE$$ FUNCTION: Open the paper tape reader as an input file, then close the current output file and open "FILE" on the default device as an output file. The following commands permit pages of text to be read into the TECO text buffer from an input device or written from the buffer onto an output device. 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. P Write the content 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. RSX-11D TECO Page 7 nP Execute the P command n times, where n must be an integer in the range 0=TEC \ *EWDK1:FILE1.TXT$$ / *HKIMR. JOHN P. JONES ! COMPUTER ELECTRONICS CORPORATION ! BOSTON, MASAASACHUSETTS ! ! DEAR MR. JONES: ! 2< I WAS PLEASED TO RECEIVE YOUR REQUEST FOR INFORMATION ! PERTAINING TO THE NEW TECO-11 TEXT EDITING AND CORRECTING RSX-11D TECO Page 12 ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO-11 USERS'S GUIDE, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! SINCERELY, ! ! ! ! \ $$ 3/ *-20LSETTS$I 02150$$ \ *STION$2C13DIREGARDING$$ / *SGUIDE$-5DIMANUAL$$ ! *SELY$0T$$ ! SINCERELY*0KIVERY TRULY YOURS$$ ! *HT$$ ! MR. JOHN P. JONES ! COMPUTER ELECTRONICS CORPORATION ! BOSTON, MASSACHUSETTS 02150 ! ! DEAR MR. JONES ! 4< I WAS PLEASED TO RECEIVE YOUR REQUEST FOR INFORMATION ! REGARDING THE NEW TECO-11 TEXT EDITING AND CORRECTING ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO-11 USER'S MANUAL, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! VERY TRULY YOURS, ! ! ! ! \ 5/ *PEF \ *ERDK1:FILE1.TXT$EWPP:$$ / *Y5KIMR. JAMES B. SMITH ! DATEK ASSOCIATES, INC. ! 122 MAIN STREET WEST ! AUSTIN, TEXAS ! ! DEAR MR. SMITH: ! $$ 6< *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-11 TEXT EDITING AND CORRECTING RSX-11D TECO Page 13 ! PROGRAM. ! ! ENCLOSED IS A COPY OF THE TECO-11 USER'S MANUAL, WHICH ! SHOULD ANSWER ALL OF YOUR QUESTIONS. ! ! VERY TRULY YOURS, ! ! ! ! *PEF$$ \ * RSX-11D TECO Page 14 SECTION II COMMAND SUMMARY The remainder of this manual is devoted to a detailed description of the full TECO command set. It is assumed that the reader is familiar with the elementary TECO commands presented earlier. 2.0 TECO CHARACTER SET TECO accepts the full ASCII character set, which is presented in Appendix A. Most terminals will not transmit and receive all of the ASCII codes; however, characters that are not available on the user's terminal may be inserted into the TECO text buffer by means of special commands which will be presented later in this section. TECO command strings may be entered using upper case characters, as indicated throughout this manual, or by using the corresponding lower case characters. A file which contains upper and lower case text may be edited in the same manner as a file which contains only upper case text. If such a file is entered from a terminal that does not accept lower case characters, all characters will be printed at the terminal as their upper case equivalents. TECO recognizes the presence of record control attributes. If an input file has implied carriage control ('FD.CR') or Fortran carriage control ('FD.FTN'), TECO will append CR-LF to each record as it is read. Fortran carriage control characters are not interpreted but are left at the beginning of each record. If the file has no carriage control attributes (i.e., internal carriage control), records are accumulated in the buffer as read. Upon output, TECO treats occurrences of CR-LF as record separators. If the output file has implied or Fortran carriage control, the CR-LF pairs are stripped off as the file is written. The output file attributes are defaulted as follows: INPUT FILE OUTPUT FILE Implied C.C. Implied C.C. Fortran C.C. Fortran C.C. Internal C.C. Implied C.C. Standard RSX-11D source files use implied carriage control. RSX-11D TECO Page 15 The following switches may be used to force carriage control attributes on both input and/or output files: /CR Force IMPLIED C.C. /FT Force FORTRAN C.C. /-CR Force INTERNAL C.C. Example: ERFOO.BAR$EWFOO.DAT/FT$Y$$ TECO considers certain ASCII characters to be special characters. Most of the special characters are immediate action commands. Typing these characters in a command string causes TECO to perform a specified function immediately, without waiting for the double ALT MODE which terminates the 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. For this reason, the special characters should not be used in text arguments, except where specifically indicated throughout this manual. Table 2-0 lists the special characters, their functions and the restrictions associated with each character. TABLE 2-0: RESTRICTIONS ON SPECIAL CHARACTERS CHARACTER RESTRICTION ALT MODE The ALT MODE character is a command terminator. It may not be used in the argument of any command except where noted specifically throughout this manual. TECO echoes a dollar sign when an ALT MODE is received. ALT MODE may be labelled ESCAPE or PREFIX on some terminals. RUBOUT Typing a RUBOUT character deletes the last character typed. Typing several consecutive RUBOUTs deletes one character for each RUBOUT typed beginning with the last character typed. TECO echoes the deleted character whenever a RUBOUT is typed. Control-C Control-C, produced by striking the CONTROL key and the C key simultaneously, causes the MCR to become active. Since TECO remains active with files open, this procedure is not recommended. Control-G Typing two consecutive Control-G characters, produced by holding the CONTROL key depressed while striking the G key twice, 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 RSX-11D TECO Page 16 to erase an entire command string. A single Control-G character is interpreted as a different command and the single Control-G is not a special character. Control-U Control-U, produced by striking the CONTROL key and the U key simultaneously, causes the current line of the current command line to be deleted. TECO echoes the character as ^U followed by carriage return and line feed. Control-W Control-W, produced by striking the Control key and the W key simultaneously, will cause all subsequently typed lower case letters to be converted to upper case (it will not effect letters in the buffer being editted; only characters typed at the keyboard are converted.) the conversion is turned off by a second Control-W. Control-W echoes as a space, and is treated as a space by TECO. Control-G Control-G, produced by striking the the Control key and the G key simultaneously, followed by a space, causes the line currently being input to be retyped. This command is functionally identical to the R command of the RSX-11D multi-TTY handler. The Control-Z character is used as an end-of-file terminator. Inserting this character into a file will cause the file to be terminated prematurely the next time it is read as an input file. TECO also attaches special significance to the carriage return, line feed, space, and null characters. A line feed is appended to every carriage return entered into the text buffer. Thus, it is necessary to type a carriage return and then a RUBOUT in order to enter a carriage return which is not followed by a line feed. Carriage return, line feed, and space characters are ignored between commands in a command string; they may be inserted for clarity or convenience whenever necessary. The null character (control-shift-P) is ignored by all TECO input commands. Control characters which are not special characters (i.e. immediate action commands) may be included in the text argument of any TECO command. When used in this manner, the control character must be produced by striking the CONTROL key and a character key simultaneously. TECO will echo a caret (or uparrow) followed by the character which was typed whenever most control characters are entered; however, some control characters do not echo, while others, such as control-L (form feed) or control-G (bell) echo as the function they perform. RSX-11D TECO Page 17 Many control characters are also TECO commands. When a control character is entered as a command, it may be produced by striking the CONTROL key and the character key simultaneously or else by typing a caret (uparrow) followed by the desired character. This is advantageous because all control characters echo normally when typed in the caret/character format. 2.1 FILE SPECIFICATION COMMANDS An input file must be specified whenever TECO is requested to accept text from any source except the terminal. An output file must be specified whenever a permanent change is made to the input file. Input and output files are selected by means of file specification commands. File specifications include device, file name, extension, and version. If the device is file-structured, the file name and extension are required. If a file extension is not explicitly defined, the null extension is assumed. If a file name is specified but no device is explicitly defined, the system default device (SY) is assumed. If a version number is not specified, TECO uses the latest version number for input files and version number one for for output in cases where the output file does not already exist; where the output file exists, TECO increments the version number by one before opening the file for output. 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 only keep one input file and one output file active at a time, and the same file may not be used for both input and output. Table 2-1 lists the full file specification command set. TABLE 2-1: FILE SPECIFICATION COMMANDS COMMAND FUNCTION ERdv:filename.ext;n$ Opens a file for output where "dv:filename.ext;n" is the file specification and "$" signifies an Alt mode. EWdv:filename.ext;n$ Opens a file for output where "dv:filename.ext;n" is the file specification and "$" signifies an ALT MODE. EBdv:filename.ext;n$ The EB command may be used for files on file-structured devices only. It opens file dv:filename.ext;n for input and file dv:filename.ext;n+1 for output. RSX-11D TECO Page 18 EF Closes the current output file. EC Moves the remainder of the current input file to the current output file, then closes the output file. EX Performs the same function as the EC command, but then exits from TECO. EA Closes the current output file, but "remembers" the EOF. Subsequent typing of 'EW$' re-opens the output file for appending. Saving an output file with an 'EA' command works to one level only. EP Closes the current input file, but "remembers" the current record. Subsequent typing of 'ER$' re-opens the file for input at the current record. EK Kill the current edit. This command closes and deletes the current output file. EG Equivalent to EX. Many editing jobs are most conveniently accomplished by using the EB command to open the designated input and backup file, then terminating the job with either an EC command, which returns control to TECO, or an EX command, which exits from TECO. The presence of version numbers in FILES-11 causes some output file effects that have not appeared with TECO under other operating systems. An EB with version number defaulted (i.e., ";0" or unspecified) will generate a new file with the next highest version number. The previous version is not removed. Similarly, an EW with default version produces the next higher version (or version 1 for a new file). However, an EW with an explicit version number will supercede an existing file of the same name-type-version. No warning is generated when this occurs. An EB with an explicit version will input from the specified version, but the output fill be forced to the default value. During an EB, it is not possible to re-read the input file with an ER on the (defaulted) latest version, since the output file already appears in the directory. To re-read the input file, the version number must be specified. TECO is an MCR function, and may be started in either of the three following ways: RSX-11D TECO Page 19 MCR>TECO or MCR>TECO filename or MCR>MAKE filename "TECO" justs starts the editor. "TECO filename" starts the editor and effects an "EBfilename$Y". "MAKE filename" starts the editor and effects an "EWfilename$". 2.2 PAGE MANIPULATION COMMANDS The following commands permit whole pages of text to be read into the text buffer from an input file or written from the buffer onto an output file. TABLE 2-2: PAGE MANIPULATION COMMANDS COMMAND FUNCTION A Appends the next page of the input file to the content of the text buffer, thus combining the two pages of text on a single page with no intervening form feed character. Y Clears the text buffer and then reads the next page of the input file into the buffer. PW Write the content of the buffer onto the output file and appends 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 an integer in the range 0<=n<=65535. m,nPW Writes the content of the buffer from the m+1th character through and including the nth character onto the output file. M and n must be integers in the range 0<=n<=65535 and m should be less then n. A form feed is not appended to this output, nor is the buffer cleared. the pointer position remains unchanged. HPW Equivalent to the PW command except that a form feed character is not appended to the output. P Writes the content of the buffer onto the output file, appending a form feed, then clears the buffer and reads the next page of the input file into the buffer. nP Executes the P command n times, where n must be an integer in the range 0<=n<=65535. RSX-11D TECO Page 20 m,nP Equivalent to m,nPW. HP Equivalent to HPW. All of the input commands listed in Table 2-2 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 the buffer is more than 2/3 full and a line feed is encountered or until a point 128 characters from the end of the buffer is reached. Special techniques for handling pages in excess of the buffer capacity will be developed later in this section. 2.3 BUFFER POINTER MANIPULATION COMMANDS Table 2-3 summarizes the complete buffer pointer manipulation command set. 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 either 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 in this manner, the pointer is positioned at the boundary which would have been exceeded. No error message is printed. TABLE 2-3: BUFFER POINTER MANIPULATION COMMANDS COMMAND FUNCTION J Moves the pointer to a position immediately preceding the first character in the buffer. nJ Moves the pointer to a position immediately following the nth character in the buffer. N must be an integer. ZJ Moves the pointer to a position immediately following the last character in the buffer. C Advances the pointer forward across one character. nC Executes the C command n times, where n must be an integer. If n is positive, the pointer is moved forfard 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. -C Equivalent to -1C. R Moves the pointer backward across one character. nR Executes the R command n times, where n is an integer. RSX-11D TECO Page 21 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. L Advances the pointer forward across the next line feed and positions it at the beginning of the next line. nL Executes the L command n times, where n is an integer. 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 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. 2.4 TEXT TYPE-OUT COMMANDS Table 2-4 summarizes the commands which may be used to type out part or all of the content of the buffer for examination. These commands do not move the buffer pointer. TABLE 2-4: TEXT TYPE-OUT COMMANDS COMMAND FUNCTION T Types of the content of the buffer from the current position of the buffer pointer through and including the next line feed character. nT Executes the T command n times, where n is an integer. If n is positive, the n lines following the current position of the pointer are typed. If n is negative, the n lines preceding the pointer are typed. If n is zero, the content of the buffer from the beginning of the line on which the pointer is located up to the pointer is typed. -T Equivalent to -1T. m,nT Types out the content of the buffer from the m+1th character through and including the nth character in the buffer. M and n must be integers, and m should be less than 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 (i. e., -n RSX-11D TECO Page 22 should be less than zero). HT Types out the entire content of the buffer. V Equivalent to 0TT. Users may stop the execution of any T command by typing control-O at the keyboard. Typing control-O terminates execution of the current T command. When used in this manner, the control-O must be entered while TECO is actually in the process of typing out at the terminal. 2.5 DELETION COMMANDS Table 2-5 summarizes the text deletion commands, which permit deletion of single characters, groups of adjacent characters, single lines, or groups of adjacent lines. TABLE 2-5: TEXT DELETION COMMANDS COMMAND FUNCTION D Delete the first character following the current position of the buffer pointer. nD Execute the D command n times, where n is an integer. 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. K Deletes the content of the buffer from the current position of the buffer pointer through and including the next line feed character. nK Executes the K command n times, where n is an integer. If n is positive, the n lines following the current pointer position are deleted. If n is negative, the n lines preceding the current pointer position are deleted. If n is zero, the content of the buffer from the beginning of the line on which the pointer is located up to the pointer is deleted. -K Equivalent to -1K. m,nK Deletes the content of the buffer from the m+1th character through and including the nth character. M and n must be integers, and m should be less than n. HK Deletes the entire contents of the buffer. RSX-11D TECO Page 23 2.6 INSERTION COMMANDS Table 2-6 lists the full text insertion command set. All text insertion 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. If a very long insertion command begins to exceed the TECO command storage capacity, TECO will ring the terminal bell once after each additional character is entered. When this occurs, the command string should be terminated immediately. Attempting to enter more characters into the current command string causes TECOto delete them as they are entered. Use of the RUBOUT key should be attempted to shorten the command to permit its termination. With the exception of the nI$ command, insertion command arguments may contain any ASCII characters that are not special characters. The nI$ command will insert any character into the buffer, including the special characters. TABLE 2-6: TEXT INSERTION COMMANDS COMMAND FUNCTION Itext$ Where "text" is a string of ASCII characters terminated by an ALT MODE, which echoes as a dollar sign. 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$ Where n is any ASCII code. This form of the I command inserts the single character whose ASCII code is n into the buffer at the current position of the buffer pointer. It may be used to insert characters that are not available on the user's terminal or special characters such as RUBOUT which may not be inserted with the standard I command. text$ Where is a tabulation, produced by striking the TAB key or by pressing the CONTROL key and the I key simultaneously. The TAB character echoes as from one to eight spaces on most terminals. This command is equivalent to the I command except that the tabulation is also inserted into the buffer immediately preceding the specified text string. @I/text/ Equivalent to the I command except that the text to be RSX-11D TECO Page 24 inserted may contain ALT MODE characters as long as it does not contain two consecutive ALT MODEs. A delimiting character (shown as a slash here) must precede and follow the text to be inserted. This delimiter may be any character which does not appear in the insertion except for the special characters. FRtext$ Equivalent to "-nDItext$", where "n" is obtained from one of the following: (a) the length of the most recent search string, (b) the length of the last insert, or (c) the length of the string retrieved by the most recent "G" command. "^S" always contains the value of "-n". 2.7 SEARCH COMMANDS In many cases, the easiest way to position the buffer pointer is by means of a character string search. The search commands cause TECO to scan through text until a specified string of from 1 to 31 characters is found, and then position the buffer pointer at the end of the string. A character string search always begins at the current position of the pointer and proceeds in a forward direction. TABLE 2-7: SEARCH COMMANDS Stext$ Where "text" is a string of 1 to 31 characters terminated by an ALT MODE. 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 and an error message is printed. nStext$ This command searches for the nth occurrence of the specified character string, where n must be greater than zero. It is identical to the S command in other respects. -nStext$ Identical to "nStext$" except that the search is performed 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. Ntext$ Performs the same function as the S command except that the search is continued across RSX-11D TECO Page 25 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, if the content of the buffer was followed by a form feed character in the input file; otherwise by executing an effective HPY command string, which does not append a form feed character. 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 commands are excuted. The N command will not locate a character string which continues across a page boundary. _text$ The underscore (backarrow) command is identical to the N command except that the search is continued across page boundaries by executing effective Y commands instead of P or HPY commands, so that no output is generated. 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. ^Rtext1$text2$ Executes an Stext1$ command, then deletes "text1" and replaces it with "text2", where text1 is a string of 1 to 31 characters and text2 is a character string of any length. The ^R must be a caret (uparrow) character followed by an R character. TECO will accept a Control-R character, if passed by the RSX-11D terminal device handler. FRtext1$text2$ Equivalent to ^Rtext1$text2$. n^Rtext1$text2$ Executes an nStext1$ command, then deletes "text1" and replaces it with "text2", where text1 is a string of 1 to 31 characters and text2 is a character string of any length. 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 (ALT MODE, in this case) must always be entered. RSX-11D TECO Page 26 Any of the search commands listed above may be preceded by a colon (:). The colon is a search command modifier which supresses error message generation and causes the next sequential command to be executed with an argument of zero, if the search fails. If the search succeeds, the next sequential command is executed with an argument of -1. If the next sequential command belongs to the class of commands which require a positive argument, the -1 is interpreted as a positive 65535. If the next sequential command does not require an argument, it is executed as it stands. The following examples illustrate use of the colon modifier. COMMANDS: :nStext$ :Ntext$ :nNtext$ :_text$ :n_text$ :^Rtext1$text2$ :n^Rtext1$text2$ FUNCTION: In each case. execute the search command. If the search is successful, execute the next sequential command with an argument of -1 (or 65535, if it is a command which must have a positive argument). 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. A special case is the compare command, the format of which is '::Stext$'. The ::S command does not move the pointer. It returns a value of -1 if the text following the pointer is identical to the search string. Otherwise it returns a value of zero. The @ character is another search command modifier. Inserting an @ character between the numeric argument of any search command and the command itself causes TECO to accept the first character following the command as a delimiting character which will also be the command terminator. This character may be any character which does not appear in the search command argument, except for special characters. When the @ command is used, search command arguments may contain ALT MODE characters, as long as they do not contain two consecutive ALT MODEs. The following examples illustrate use of the @ command modifier. COMMANDS: @S/text/ n@S/text/ @N/text/ n@N/text/ @_/text/ n@_/text/ @^R/text1/text2/ n@^R/text1/text2/ RSX-11D TECO Page 27 FUNCTION: In each case, execute the search command with text string "text" as an argument. This argument must be preceded and followed by a delimiting character which does not appear in the argument ( a slash is shown here). The search command argument may contain ALT MODE characters, as long as it does not contain two consecutive ALT MODEs. 2.8 MATCH CONTROL CHARACTERS 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 four special control characters that may be used in search command arguments. These characters alter the usual matching process that occurs when a search is executed. TECO considers match control characters to be single characters (they echo as two characters) and counts them as one of the maximum 31 characters in the search command argument. Table 2-8 lists the match control characters and their functions. TABLE 2-8: MATCH CONTROL CHARACTERS CHARACTER FUNCTION Control-X A control-X character indicates that this position in the character string is unimportant. TECO accepts every other character as a match for control-X. Control-S A control-S 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 control-S. Control-N The control-N character and the character following it are treated as a single character in the search command argument, but counted as 2 of the maximum 31 characters. TECO accepts any character as a match for the control-N/character combination EXCEPT the character which follows the control-N. The combination control-N/control-S is legal; TECO accepts any character which is not a separator as a match for ^N/^S. Control-Q A control-Q character in a search command argument indicates that the character following the control-Q is to be interpreted literally rather than as a command. This character may be used to search for other match control characters. It does not count as one of the maximum 31 characters in the search command argument. RSX-11D TECO Page 28 Control-EA Control-EA indicates that any alpha character is acceptable in this position. TECO accepts any letter (upper or lower case A to Z) as a match for ^EA. Control-ED Control-ED indicates that any digit is acceptable in this positon. TECO accepts any digit (0 to 9) as a match for ^ED. Control-EL Control-EL indicates that any line terminator is acceptable in the position occupied by ^EL in the search string. Control-EX Equivalent to ^X. Control-ES Control-ES indicates than a string of spaces and/or tabs is acceptable in the position occupied by ^ES. Control-EQn Control-EQn indicates that the string stored in Q-register n is to be used in the position occupied by the ^EQn in the search string. As with all other control characters entered into text arguments, match control characters must be typed by holding the CONTROL key depressed while striking the character key. The caret (uparrow) construction may not be used. The match control characters may not be entered directly in a search command if the multi-TTY handler is used. To overcome this problem, the user may insert the command into the text buffer (the nI command is used to insert the match control character), transfer the command to a Q-register, and perform the search as a macro. The following example illustrates this procedure in a search for the string "end" followed by any digit: JISEND$5I$@I/D$/ 0XA0KMA$$ 2.9 COMMAND LOOPS The user may 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 which designates the number of iterations. Iterated command strings are called command loops. Loops may be nested in such a way that one command loop contains another command loop, which, in turn, contains other command loops, and so on. Command loops should not be nested to more than about 15 levels. The general form of the command loop is: n where "command string" is the sequence of commands to be iterated RSX-11D TECO Page 29 and n is the number of iterations. N must be a positive integer. If n is not supplied, a value of 65535 is assumed. If a search command which is not preceded by a colon modifier is entered into a command loop and the search fails, the command loop is exited immediately and the command following the right angle brackets of the loop is the next command to be executed. No error message is printed. 2.10 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. In the number storage area, each Q-register can store one integer in the range -32768<=n<=32767. In the text storage area, each Q-register can store an ASCII character string up to 2000 characters which may be either text or a TECOcommand string. Each Q-register has a single character name which is one of the upper case letters A to Z or one of the digits 0 to 9. In this manual, a Q-register name is indicated by a lower case "q", which stands for any one of the 36 Q-registers. Table 2-10A lists the commands which permit characters to be loaded into the Q-registers. TABLE 2-10A: Q-REGISTER LOADING COMMANDS COMMAND FUNCTION ^Uqstring$ Where ^U is a control-U character, "q" is the name of a user-specified Q-register, "string" is a string of ASCII characters, and "$" signifies ALT MODE. This command inserts character string "string" into the text storage area of Q-register "q". ^U must be specified in the caret (uparrow)/U format; the control-U character is a special RSX-11D terminal character for erasing the terminal line buffer. @^U/string/ Equivalent to the ^U command except that the character string to be inserted into Q-register q may contain ALT MODE characters as long as it does not contain two consecutive ALT MODE characters. The insertion must be delimited before and after by any character (a slash is shown here) which does not appear in the insertion. nUq Load n into the number storage area of Q-register q, where n must be an integer in the range -32768<=n<=32767. n%q$ Add n to the content of the number storage area of RSX-11D TECO Page 30 Q-register q, where n should be an integer that will not cause overflow. n%q Equivalent to n%q$ except that 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. Xq Copy the content of the buffer from the current position of the pointer through and including the next line feed character into the text storage area of Q-register q. nXq Execute the Xq command n times, where n is an integer in the range -32768<=n<=32767. 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 content of the buffer from the beginning of the line on which the pointer is located up to the pointer is copied. m,nXq Copy the content 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. Table 2-10B lists the commands which permit characters to be retrieved from the Q-registers. TABLE 10B: Q-REGISTER EXECUTION COMMANDS COMMAND FUNCTION Gq Copy the content 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. Qq Use the integer stored in the number storage area of Q-register q as the argument of the next command. The characters "Qq" may be considered as equivalent to "the value contained in the number storage area of Q-register q", where "q" is any Q-register name. Mq Execute the content of the text storage area of Q-register q as a command string. nMq Execute the content of the text storage area of Q-register q as a command string and use n as a RSX-11D TECO Page 31 numeric argument for the first command in this string. 2.11 BRANCHING COMMANDS TECO commands may be combined in sophisticated command strings which are capable of solving even the most complex editing problems. In fact, TECO might be considered a programming language which accepts an input file as data and processes this input to produce an output file. As with most programming languages, TECO provides an unconditional branch command and a set of conditional execution commands. To provide for branching within a command string, there must be some means of naming locations inside the string. TECO permits location tags which have 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 for special characters and exclamation points. 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 named location elsewhere within the command string and "$" signifies an ALT MODE. When an O command is executed, the next command to be executed will be the command following the tag referenced by the O command, and command execution continues normally from this point. 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 also reside in the same Q-register. An important restriction on the O command prevents any O command which is inside a command loop from branching 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. RSX-11D TECO Page 32 2.12 CONDITIONAL EXECUTION COMMANDS All conditonal execution commands are of the form: n"Gcommand string' where "n" is a numeric argument on which the decision is based, "g" may be any of the conditional execution commands listed in table 2-12, and "command string" is the command string which will be executed if the condition is satisfied. If the condition on n is not satisfied, the command string will not be executed. Note that the numeric argument is separated from the conditional execution command by a double quote (") and the command string is terminated with an apostrophe ('). 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 2-12 lists the conditional execution commands. Each conditional execution command must be followed by a command string (not shown in Table 2-12) which will be executed only if the condition is satisfied. This command string must be terminated by an apostophe. If the condition is not satisfied, the first command following the apostrophe will be the next command executed. TABLE 2-12: CONDITIONAL EXECUTION COMMANDS COMMAND FUNCTION n"G Execute the following command string (terminated by an apostrophe) if n is greater than zero. Otherwise skip the following command string. N must be an integer. n"L Execute the following command string (terminated by an apostrophe) if n is less than zero. Otherwise skip the following command string. n"E Execute the following command string (terminated by an apostrophe) if n is equal to zero. Otherwise skip the following command string. n"C Execute the following command string (terminated by an apostrophe) if n is the decimal ASCII code of any character which is one of the upper or lower case letters A to Z, one of the digits 0 to 9, or period, or dollar sign. Otherwise skip the following command string. n"N Execute the following command string (terminated by an apostrophe) if n is not equal to zero. Otherwise skip RSX-11D TECO Page 33 the following command string. n"T Execute the following command string (terminated by an apostrophe) if n is TRUE. Equvalent to n"L. n"S Execute the following command string (terminated by an apostrophe) if n is SUCCESSFUL. Equivalent to n"L. n"F Execute the following command string (terminated by an apostrophe) if n is FALSE. Equivalent to n"E. n"U Execute the following command string (terminated by an apostrophe) if n is UNSUCCESSFUL. EQUIVALENT TO N"E. N"A EXECUTE THE FOLLOWING COMMAND STRING (TERMINATED BY AN APOSTROPHE) IF N EQUALS AN ASCII alpabetic character (upper or lower case A to Z). n"D Execute the following command string (terminated by an apostrophe) if n equals the ASCII code for a digit (0 to 9). n"R Execute the following command string (terminated by an apostrophe) if n equals the ASCII code for an alphanumeric (upper or lower case A to Z or 0 to 9). There is one further conditional execution command which is not related to the commands listed in Table 2-12. The ;n command, where n is any integer, may be inserted between any two commands in an iterated command loop. It has the general form: mstring3 where "m" is the iteration count, "string1", "string2", and "string3" are command strings and "n;" is the conditional exit command. When the n; command is executed, it will cause TECO to exit the command loop so that "string3" will be executed next if n is greater than or equal to zero. If n is less than zero, the n; command is ignored and "string2" is executed next. The semicolon may be preceded by an argument such as Qq (the value of the numeric part of Q-register q), or the argument may be omitted if the semicolon command is preceded by a command that generates an argument, such as any colon-modified search command. Note that all unmodified search commands entered within command loops are executed as though then were preceded by a colon and followed by a semicolon. If the search command is preceded by a colon modifier, however, it will be executed as it stands. The conditional execution commands will accept user-supplied numeric arguments (n in Table 2-12) of the same form as most other TECO commands. This is generally a trivial case, however, because the user will know in advance whether the condition is satisfied, and need not use the conditional execution command. RSX-11D TECO Page 34 The following section introduces run-time numeric quantities computed by TECO which may also be used as numeric arguments. 2.13 NUMERIC ARGUMENTS Almost all TECO commands may be preceded by a numeric argument which generally indicates the number of iterations, or how many times the command should be executed. Some numeric arguments must be positive, while others may be negative or zero. In any case, every numeric argument is stored as a single 16-bit word. This leads to an important restriction on the maximum size of any numeric argument. Commands which require positive arguments must have an argument in the range 0<=n<=65535, since 65535 is the largest number which may be stored in one 16-bit word. Commands which have positive or negative arguments require an argument in the range -32768<=n<=32767, because -32768 is the smallest number which may be stored in 16 bits using 2's complement notation, while 32767 is the largest number which may be stored in this manner. TECO maintains several internal counters which record conditions within the text buffer. Each of the counters has a one-character name which is equivalent to the current contents of the counter. These characters may be entered as numeric arguments to TECO commands. When the command is executed, the current value of the designated counter is substituted for the character and used in 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 references a counter that always contains the number of characters between the beginning of the buffer and 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 (twice) for the "dot". The addition is then carried out, and the command is executed as though it were of the form "m,nT". Table 2-13A lists all of the characters which have special numeric values. Any of these characters may be used as numeric arguments in place of the values they represent. TABLE 2-13A: CHARACTERS ASSOCIATED WITH NUMERIC QUANTITIES CHARACTER FUNCTION B Always equivalent to zero. Thus, B represents the position at the beginning of the buffer, preceding the first character in the buffer. RSX-11D TECO Page 35 Z Equivalent to the number of characters currently contained in the buffer. Thus, Z represents the position at the end of the buffer, 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. ^Z Control-Z (or caret/Z) is equivalent to the number of characters presently stored in the Q-register storage area, including requirements for the command string containing the ^Z character. nA Where n is a positive integer. Equivalent to the ASCII code for the n+1th character following the current position of the pointer. ^E Control-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 N, EC, and EX commands to determine whether a form feed should be appended to the content of the buffer on output. ^F Control-F (Caret/F) is equivalent to the current value of the console switch register. ^^X The combination of the double caret (double uparrow) followed by any character is equivalent to the value of the ASCII code for the character. The "X" in this example may be any character except control-C. \ A backslash character which is not preceded by a numeric argument is equivalent to the value of the digit string (if any) that begins with the character immediatelty following the buffer pointer and is terminated by the next character that is not a digit. The first character may be a digit or one of the characters + or -. As each backslash 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 backslash is equivalent to zero and the pointer position remains unchanged. RSX-11D TECO Page 36 ^T Control-T (caret/T) is equivalent to the ASCII code for the next character typed at the terminal. Control-T may be entered in the numeric argument of any command. When TECO executes a command string, every ^T character encountered causes it to pause and accept one character typed at the terminal. The ASCII code for this character is then substituted for the ^T. ^V Control-V (caret/V) is equivalent to the version number of the version of TECO which is currently being run. This manual describes RSX-11D TECO version 14. ^H Control-H (caret/H) is equivalent to a value of elapsed time in seconds since midnight divided by two. ^B Control-B (caret/B) is equivalent to the current date via the following equation: ^B = day + (month*32) + ((year-1900)*512) Mq The Mq command (execute the content 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 ALT MODE. The numeric argument of a TECO command may consist of a single integer, any of the characters listed in Table 2-13A, or an arithmetic combination of integers and the characters listed in Table 2-13A. If an arithmetic expression is supplied as a numeric argument, TECO will evaluate the expression. All arithmetic expressions are evaluated from left to right. Parentheses may be used to override the normal order of evaluating an expression. If parentheses are used, all operations within the parentheses are performed, left to right, before performing operations outside the parentheses. Parentheses may be nested, in which case the innermost expression contained by parentheses will be evaluated first. Table 2-13B lists all of the arithmetic operators that may be used in arithmetic expressions. TABLE 2-13B: 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 RSX-11D TECO Page 37 * 8*2=16 Multiplication. used between terms. / 8/3=2 Integer divide and drop the remainder. Used between terms. & 12&10=8 Bitwise logical AND of the binary representation of the two terms. Used between terms. # 12#10=14 Bitwise logical OR of the binary representation of two terms. Used between terms. ^_ 5^_=-6 Unitary one's complement. Used before expressions. Table 2-13C lists two commands which may be used to facilitate entering arithmetic expressions into TECO command strings. TABLE 2-13C: RADIX CONTROL COMMANDS COMMAND FUNCTION n= where n is an arithmetic expression which may contain the operators listed in Table 2-13B. Upon execution, this command causes the value of the expression to be typed out at the terminal. ^O Control-O (caret/O) causes all subsequent numeric input to be accepted as octal numbers. This command must not be typed while TECO is executing a T command. The octal radix will continue to be used until the next ^D command is executed. ^D Control-D (caret/D) causes all subsequent numeric input to be accepted as decimal numbers. This is the initial setting. n\ Where n is any arithmetic expression. The backslash command (preceded by an expression) 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. Some TECO commands generate numeric arguments which they pass on to subsequent commands. An example is any colon-modified search command, which causes the next sequential command to be executed with an argument of -1 or 0, depending upon the outcome of the search. Commands of this sort are very useful, but occasionally it may be undesirable to have arguments passed in this manner. A single Alt mode character may be inserted between any two commands in a command string, as long as it is not placed adjacent to another ALT MODE character. This ALT MODE has no RSX-11D TECO Page 38 effect on the individual commands, however a numeric argument will never be passed across the extraneous ALT MODE. 2.14 PROGRAMMING AIDS The characters carriage return, line feed, vertical tab, and space are ignored in command strings, except when they appear as part of a text argument. 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. One of the most powerful features of TECO is the 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. It is often convenient to include carriage return and line feed characters within the comments so that the command string looks like: TECO commands! This comment describes line 1 !TECO commands! This comment describes line 2 !more commands! !$$! end of comment string! The control-A command may be used to print out a statement at any point during the execution of a command string. The control-A command has the general form: ^Atext^A where 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 control-A character is the command terminator, which must be entered by typing the control key and the A key simultaneously. The message which appears between the control-A characters may contain any characters except the special characters and the ^A character. Upon execution, this command causes TECO to print the specified message at the terminal. The ^Amessage^A command is particularly useful when it precedes a command whose numeric argument contains ^T or ^F characters. The message may contain instructions notifying the computer operator what sort of input is required. RSX-11D TECO Page 39 A question mark entered betweeen any two commands in a command string causes TECO to print all subsequent commands at the terminal as they are executed. Commands will be printed as they are executed until another question mark character is encountered. The second question mark character may be in the same command string as the first question mark, or it may appear in a later command string. It may not be the first character typed after a TECO-generated error message, however. If an error is typed while entering a command string, the error may be corrected at any time before the double ALT MODE which terminates the command string is typed. Characters may be deleted individually by striking the RUBOUT key. Each depression of the RUBOUT key deletes one character, beginning with the last character typed, and causes the deleted character to be printed at the terminal. An entire line of a command string may be deleted by typing control-U. If an entire command string is deleted in one of these manners, TECO responds by printing a new asterisk at the left margin. Typing Control-G causes TECO to retype the line currently being input. ^G is functionally equivalent to the RSX-11D multi-TTY ^R command. The caret form of the control-G may not be used for this command. Typing two successive control-G characters causes the current command string to be erased completely. The double control-G command must be produced by holding the control key depressed while striking the G key twice (if the terminal has a bell, it will ring). The caret form of the control-G may not be used for this command. After an error (or after ^G^G to cancel a command), the previous command buffer contents may be recovered by immediately typing "*q", where "q" is any Q-register name. This places the command buffer contents into the named Q-register. 2.15 ERROR MESSAGES When TECO encounters an illegal command or a command that cannot be executed, an error message is printed at the terminal. Error messages are of the form: ?XXX MESSAGE where "XXX" is an error code and "MESSAGE" is an explanatory message. When an error message is generated, the command to which it refers is not executed, the rest of the current command string is ignored, and TECO prints an asterisk at the left margin to indicate that it is ready to accept further commands. In some cases it may be difficult to determine which command in a long command string resulted in an error message. Typing a question mark immediately after the TECO-generated error message RSX-11D TECO Page 40 causes TECO to print the current command string up to and including the erroneous character. When used in this manner, the question mark must be the first character typed after the error message is printed. It is not necessary to follow the question mark with an ALT MODE. In general, TECO command strings should be limited to a maximum of about 2000 characters. Command strings which exceed 2000 characters in length should be split into smaller strings. Long command strings are impractical because the probability of a command error is increased and because a string which contains more than 2000 characters may be too long to be stored in a Q-register. TECO reserves a limited amount of memory for command string storage. If a very long command string (or a long insertion command) uses all of the command string storage locations, TECO prints one control-G character after every additional character that is entered. Should this occur, the current command string will be lost. 2.16 MANIPULATING LARGE PAGES TECO is designed to operate most efficiently when editing files that contain no more than about 11000 characters per page.[1] If any page of an input file contains more than 11000 characters, the various TECO input commands may terminate reading that page into memory when the first line feed is encountered after the buffer is 2/3 full or if a point 128 characters from the end of the buffer is reached. Most of the TECO output commands append a form feed to the content of the buffer whenever a page of text is written onto the output file. If an input file contains pages which exceed the buffer capacity, these output commands will cause form feed characters to be inserted into the file at locations where they may not be desired. To prevent this, the user must understand exactly how the output commands operate. These commands are described briefly in Table 2-16. TABLE 2-16: FORM FEED PROCESSING BY OUTPUT COMMANDS OUTPUT COMMAND FORM FEED PROCESSING P, nP, PW and nPW Always appends a form feed character to the next contained in the buffer, regardless of whether -------------------- [1]. TECO storage includes q-register storage and buffer space. The 11000-character limitation represents the approximate total storage capacity of TECO when built using the commands included in Appendix D. RSX-11D TECO Page 41 this text actually constitutes a complete page of the file. That is, a form feed is appended on output even though one may not have been present upon input. HP, HPW, m,nP and m,nPW Never appends a form feed character to the text contained in the buffer. N, EC and EX If the text contained in the buffer was followed by a form feed character in the input file, a form feed will be appended to this text upon output. If this text was not followed by a form feed, no form feed will be appended. If it becomes necessary to edit text that consists of large pages without introducing extraneous form feed characters into the output, this may be accomplished by avoiding all output commands except the N, EC, and EX commands. For example, if use of a P command would introduce an extraneous form feed, use an N command, instead, to search for a character string contained in the next page of the input file. 2.17 TECHNIQUES AND EXAMPLES TECO may be used in three ways. The most elementary application, described in Section I of this manual, involves using TECO to create and edit ASCII files on-line. The user enters short command strings, often consisting of a single command, and proceeds from task to task until the file is completely edited. Since every editing job is simply a long sequence of TECO commands, an entire job may be accomplished with one long command string consisting of all of the short command strings placed end to end with the intervening double ALT MODE characters removed. This leads to the concept of a TECO editing program, which is simply a long command string that performs a certain editing task. Editing programs may be written (using TECO) and stored in the same manner as any other ASCII file. Whenever the program is needed, it may be read into the buffer as text, stored in a Q-register, and executed by an Mq command (where "q" is the Q-register name). This is fine for clear-cut editing assignments, such as converting from one format to another or editing certain characters out of a file, but many editing jobs are so complex that a given editing program will only solve a small class of problems. The solution, in this case, is to write very specialized "editing subroutines." TECO subroutines might perform such elementary functions as replacing every occurrence of two or RSX-11D TECO Page 42 more consecutive spaces with a tabulation character, for example, or ensuring that words are not hyphenated across a page boundary. When an editing problem arises, the right combination of subroutines may be loaded into various Q-registers, augmented with additional commands if necessary, and called by a "mainline" command string. Editing subroutines are essentially macros; that is, sequences of commands which perform commonly required editing functions. Thus the third and most powerful application of TECO is the creation and use of a macro library. As each editing job is undertaken, the user may look for sequences of operations which might be required in future editing assignments. All of the TECO commands required to perform such an operation may be loaded into a Q-register and executed by means of an Mq or nMq command. When the job is finished, the content of any Q-register which contains a useful macro may be written onto an output file (via the buffer) and saved in the macro library. The nMq command, which was designed to facilitate use of macros, permits one run-time numeric argument to be passed to the macro. The following examples are intended to illustrate some of the techniques discussed earlier. It would not be practical to include examples of the use of every TECO command, since most of the commands admit to many diverse applications. Instead, users are encouraged to experiment with the individual commands. EXAMPLE 1: SPLITTING, MERGING, AND REARRANGING FILES Assume that the user has a file named PROGRAM.DAT on the system disk and that this file contains data in the following form: AB FORM CD FORM EF FORM GH FORM IJ FORM KL FORM MN FORM OP where each of the letters A, B, C etc., represents 20 lines of text and FORM represents a form feed character. The user intends to rearrange the file so that it appears in the following format: AOB FORM D FORM MN FORM EF FORM ICJ FORM KL FORM P FORM GH The following sequence of commands will achieve this rearrangement. (search command arguments are not listed explicitly.) MCR>TEC Call TECO. *EBPROGRAM.DAT$Y$$ Specify input file and get first page. *NC$$ Search for a character string in C to write A and B on the output file. *J20X1$$ Save all of C in Q-register 1. *20K$$ Delete C from the buffer. *NG$$ Search for a character string in G to write D, E, and F on the output file. *HX2$$ SAve G and H in Q-register 2. RSX-11D TECO Page 43 *Y$$ Delete GH from the buffer and read IJ. *20L$$ Move the pointer to the beginning of J. *G1$$ Insert C, which was stored in Q-register 1. *NM$$ Search for a character string in M to write ICJ and KL on the output file. *HX1$$ Save MN in Q-register 1 (the previous content is overwriten). *Y$$ Delete MN and read OP *J20X3$$ Save all of O in Q-register 3. *20K$$ Delete O from the buffer. *P$$ Write P onto the output file, leaving the buffer cleared (hte input file is exhausted). *G2$$ Bring GH into the buffer from Q-register 2. *HPEF$$ Write GH on the output file and close it. *EBPROGRAM.DAT$Y$$ Open the partially revised file. *20L$$ Move the pointer to the beginning of B. *G3$$ Insert all of O from Q-register 3. *ND$$ Search for a character string in D to write AOB on the output file. *PWHK$$ Write D on the output file and clear buffer. *G1$$ Bring all of MN from Q-register 1 into the buffer. *EX$$ Write MN onto the output file, then close the file and exit to the MCR. At this point the file has been rearranged in the desired format. Of course, this rearrangement could have been accomplished in fewer steps if the commands listed above had been combined into longer command strings. Note that the asterisks shown at the left margin in this example are generated by TECO, and not typed by the user. Assume, now, that the same input file mentioned earlier, containing data in the form: AB FORM CD FORM EF FORM ... FORM OP is to be split into two separate files, with the first file containing AB FORM CD and the second file containing KL FORM M, while the rest of the data is to be discarded. The following commands could be used to achieve this rearrangement: MCRTEC Call TECO. *ERDK1:MATH.TWO$$ Open the first input file. *EWMATH.NEW$$ Open the output file on the default device. *Y$$ Read MN into the text buffer. *NR$$ Search for a character string in R to write MN and OP onto the output file. *PW$$ Write QR onto the output file, appending a form feed. *ERDK1:MATH.ONE$$ Open the second input file. *Y$$ Read AB into the buffer. QR is over-written. *_G$$ Search for a character string in G to delete AB, CD, and EF, leaving GH in the buffer. *NK$$ Search for a character string in K to write GH and IJ on the output file, leaving KL in the buffer. *HPEX$$ Write KL onto the output file (without appending a form feed) and close the file, then exit to MCR. EXAMPLE 2: ALPHABETIZING BY BINARY SEARCH Assume that TECO is running and that the buffer contains many short lines of text beginning with an alphabetic character at the left margin (i.e. immediately following a line feed). The lines might consist of names in a roster, for example, or entries in an index. The following command string will rearrange the lines into rough alphabetical order. This command string groups all lines which begin with the character "A" at the beginning of the page, followed by all lines with "B", and so on. Note that the algorithm could be extended to place the entries in RSX-11D TECO Page 45 strict alphabetical order by having it loop back to perform the same binary sorting operation on successive characters in each line. !START! J 0AUA! LOAD FIRST CHARACTER OF FIRST LINE INTO Q-REGISTER A !!CONT! L 0AUB! LOAD FIRST CHARACTER OF NEXT LINE INTO Q-REGISTER B !QA-QB"G XA K -L GA 1UZ'! IF A>B, SWITCH THE LINES AND SET A FLAG (Q-REGISTER Z) !QBUA! LOAD B INTO A !L Z-."G -L OCONT$'! LOOP BACK IF THERE IS ANOTHER LINE IN THE BUFFER !QZ"G 0UZ OSTART$'! REPEAT IF A SWITCH WAS MADE ON THE LAST PASS !$$ RSX-11D TECO Page 46 APPENDIX A OCTAL & DECIMAL ASCII CHARACTER SET CHAR OCT DEC CHAR OCT DEC CHAR OCT DEC CHAR OCT DEC NULL 000 000 SP 040 032 @ 100 064 ` 140 096 ^A 001 001 ! 041 033 A 101 065 a 141 097 ^B 002 002 " 042 034 B 102 066 b 142 098 ^C 003 003 # 043 035 C 103 067 c 144 099 ^D 004 004 $ 044 036 D 104 068 d 144 100 ^E 005 005 % 045 037 E 105 069 e 145 101 ^F 006 006 & 046 038 F 106 070 f 146 102 ^G 007 007 ' 047 039 G 107 071 g 147 103 ^H 010 008 ( 050 040 H 110 072 h 150 104 TAB 011 009 ) 051 041 I 111 073 i 151 105 LF 012 010 * 052 042 J 112 074 j 152 106 VT 013 011 + 053 043 K 113 075 k 153 107 FF 014 012 , 054 044 L 114 076 l 154 108 CR 015 013 - 055 045 M 115 077 m 155 109 ^N 016 014 . 056 046 N 116 078 n 156 110 ^O 017 015 / 057 047 O 117 079 o 157 111 ^P 020 016 0 060 048 P 120 080 p 160 112 ^Q 021 017 1 061 049 Q 121 081 q 161 113 ^R 022 018 2 062 050 R 122 082 r 162 114 ^S 023 019 3 063 051 S 123 083 s 163 115 ^T 024 020 4 064 052 T 124 084 t 164 116 ^U 025 021 5 065 053 U 125 085 u 165 117 ^V 026 022 6 066 054 V 126 086 v 166 118 ^W 027 023 7 067 055 W 127 087 w 167 119 ^X 030 024 8 070 056 X 130 088 x 170 120 ^Y 031 025 9 071 057 Y 131 089 y 171 121 ^Z 032 026 : 072 058 Z 132 090 z 172 122 ALT 033 027 ; 073 059 [ 133 091 { 173 123 FS 034 028 < 074 060 \ 134 092 | 174 124 GS 035 029 = 075 061 ] 135 093 } 175 125 RS 036 030 > 076 062 ^ 136 094 ~ 176 126 US 037 031 ? 077 063 _ 137 095 RUB 177 127 RSX-11D TECO Page 47 APPENDIX B DESCRIPTION RELATIVE TO PDP-10 TECO With the exception of the absence of upper/lower case shift %RUNOFF-I-GFC, Given footnote count incorrect. Correct value is 4 on output page 47; on input line 20 of page 32 of file "$1$DUA19:[PETE.TECO.RSX.77B.340100]TECO.RNO;1" commands, this editor is a superset of the PDP-10 TECO.[1] The following is a description of the additional features included in the RSX-11D implementation of TECO. 1. TECO is an MCR Function, and may be started in either of the three following ways: MCR>TECO or MCR>TECO filename or MCR>MAKE filename . "TECO" just starts the editor. "TECO filename" starts the editor and effects an "EBfilename$Y" . "MAKE filename" starts the editor and effects an "EWfilename$" . 2. The command 'V' is equivalent to '0TT' . %RUNOFF-I-GFC, Given footnote count incorrect. Correct value is 5 on output page 47; on input line 62 of page 32 of file "$1$DUA19:[PETE.TECO.RSX.77B.340100]TECO.RNO;1" 3. '^G#' (Control-G-Space)[2] will retype the line currently being input. i.e., ^G# function in the same manner as does ^R with the multi-TTY Handler. 4. After an error (or after ^G^G to cancel a command), the previous command buffer contents may be recovered by immediately typing '*q' where "q" is any Q-register name. This places the command buffer contents into the named Q-register. 5. The command 'EA' closes the current output file, but "remembers" the current EOF. Subsequent typing "EW$" re-opens the output file for appending. Saving an output file with an 'EA' works to ONE LEVEL only. --------------- [1] THE PDP-10 TECO is described in document DEC-10-NGZB-D. --------------- [2] IN THIS APPENDIX "^" IS USED TO REPRESENT THE CTRL key, and "#" is used to represent a syntax critical space. RSX-11D TECO Page 48 6. The command 'EP' closes the current input file as above, but allows typing 'ER$' to re-open it at the current record. 7. The following special characters are recognized in searches: ^S matches any non-alphanumeric character. ^EA matches any ALPHA character. ^ED matches any DIGIT character. ^Nx matches any character except "x". ^EL matches any line terminator. ^EX matches ANY character. ^ES matches a string of SPACES and/or TABS. ^EQn matches the string stored in Q-register "n". 8. "Compare" type search '::S-----$' does not move the current text pointer. It gives a value of -1 if the current text string is identical to the search string, otherwise, it gives a value of zero. 9. "Negative" (reverse) searches '-nS-----$' searches the current text buffer in the reverse direction for the indicated string. i.e., roughly equivalent to '!START!::S-----$"EROSTART$' . 10. The command 'FR-----' is equivalent to '-nDI-----' where the value "n" is obtained from one of the following: a. The length of the last string searched for, b. The length of the last insert, or c. The length of the last "G" command. "^S" always contains the value of "-n" . 11. Most control characters (notably ^E) are not passed by the multi-TTY Handler. In command strings this problem can be circumvented by typing up-arrow & character instead of the control character, but in other cases, the single-unit TTY Handler is required. The Single-unit TTY Handler will allow all control characters to be input, however, it does not support the useful ^O & ^R features. 12. The presence of version numbers in FILES-11 causes some effects with output files that have not appeared in other operating systems. An 'EB' with default version (i.e., ";0" or not specified) will generate a new file with the next highest version number. The previous version is not re-named. Likewise, an 'EW' with default version will produce the next higher version (or a version 1 for a new file). An 'EW' with an explicit version will supercede an RSX-11D TECO Page 49 existing file of the same name-type-version with no warning. An 'EB' with explicit version will input from the specified version, but the output version number will be forced to the default value. During an 'EB' it is not possible to re-read the input file with an 'ER' on the latest version, since the output file already appears in the directory. To re-read the input file, the version number must be specified. 13. The command 'EK' kills the current edit. It closes and deletes the current output file. 14. The following conditionals are available: n"G n>0 n"L n<0 n"E n=0 n"N n not-equal 0 n"T n is TRUE (n<0) n"S n is SUCCESSFUL (n<0) n"F n is FALSE (n=0) n"U n is UNSUCCESSFUL (n=0) n"A n is Alphabetic (A thru Z) n"D n is a digit (0 thru 9) n"R n is alpha-numeric (A-Z or 0-9) n"C n is symbol constituent (A-Z, 0-9, point, or dollar sign). 15. The command '^UX$' places the string in Q-register "X". 16. The command '^R' is equivalent to 'FS'. 17. The command '^O' sets the radix for type-in and '\' to octal (base-8). 18. The command '^D' sets the radix for type-in and '\' to decimal (base-10). 19. The command '^B' returns the current date in the following format: DAY + (MONTH*32) + ((YEAR-1900)*512). RSX-11D TECO Page 50 20. The command '^H' returns the current time of day in seconds past midnight divided by two. 21. The command '^V' returns the version number of the running copy of TECO. 22. The command '^Z' returns the total size of the Q-register area (in bytes). 23. The command 'EG' is equivalent to 'EX'. 24. 'n^_' is the ones complement of "n". 25. Teco recognizes the presence of record control atributes. If an input file has implied carriage control ('FD.CR') or Fortran carriage control ('FD.FTN'), Teco will append CR-LF to each record as it is read. Fortran carriage control characters are not interpreted but are left at the beginning of each record. If the file has no carriage control atributes (i.e., internal carriage control), records are accumulated in the buffer as read. Upon output, Teco treats occurrances of CR-LF as record separators. If the output file has implied or Fortran carriage control, the CR-LF pairs are stripped off as the file is written. The output file attributes are defaulted as follows. INPUT FILE OUTPUT FILE Implied C.C. Implied C.C. Fortran C.C. Fortran C.C. Internal C.C. Implied C.C. Standard RSX-11D source files use implied carriage control. The following switches may be used to force carriage control attributes on both input and/or output files: /CR Force IMPLIED C.C. /FT Force FORTRAN C.C. /-CR Force INTERNAL C.C. . Example: ERFOO.BAR$EWFOO.DAT/FT$Y$$ RSX-11D TECO Page 51 APPENDIX C INSTALLATION OF TECO ------------ -- ---- This TECO package consists of four files that have been recorded via RSX-11D filex in DOS format. The four files are: TECO.RNO The RUNOFF source for the TECO manual, TECBLD.CMD TKB command file to build Task, TECO.OBJ Object module for body of editor, and TECOIO.OBJ Object module for RSX-11D I/O section. Following are examples of: (1) Reading the four files onto the system disk, (2) Producing this document, and (3) Bulding and installing the editor Task. INS [11,1]FLX (may already be installed) FLX SY:=DTn:[200,200]*.* (from DECtape) FLX SY:=MTn:[200,200]*.* (from Magtape) FLX SY:=DKn:[200,200]*.* (from RK disk) INS [11,1]RNO (may already be installed) RNO LP:=[200,200]TECO (96-char set printer) RNO LP:/UC=[200,200]TECO (64-char set printer) RNO TTn:/UC=[200,200]TECO (64-char set TTY) TKB @TECBLD (see Appendix D) INS [11,1]TECO INS [11,1]TECO/TASK=...MAK RSX-11D TECO Page 52 APPENDIX D -- TKB COMMAND FILE ; ; TASK BUILD FILE FOR RSX-11D TECO. TO WORK IN ITS NORMAL FASHION, ; TECO SHOULD BE INSTALLED TWICE, ONCE UNDER ITS NORMAL NAME AND ONCE ; UNDER ; THE NAME "...MAK" TO IMPLEMENT THE "MAKE" COMMAND. [11,1]TECO/-FP,TECO=TECO,TECOIO / TASK=...TEC LIBR=SYSRES:RO ; ; LUN 2 IS USED FOR CONSOLE I/O ; LUN 3 IS USED FOR THE OUTPUT FILE ; LUN 4 IS USED FOR THE INPUT FILE ; LUN 5 IS USED TO CALL MO ; ASG=CI:2 ASG=MO:5 ; ; ALL OF TECO'S DYNAMIC STORAGE IS KEPT IN THE STACK AREA ALLOCATED ; BY THE TASK BUILDER. ; STACK=6000 ; ; THE FOLLOWING PARAMETER SETS THE ACTUAL STACK USED BY THE TECO ; PROGRAM. ; THERE IS NORMALLY NO NEED TO CHANGE IT. GBLDEF=STACKZ:200 ; ; THE FOLLOWING PARAMETER SETS THE SIZE OF TECO'S PUSH DOWN LIST. ; IT MAY ; BE NECESSARY TO INCREASE THIS TO ACCOMMODATE MANY LEVELS OF ; ITERATION, MACRO CALLS, ETC. GBLDEF=PDLSIZ:100 ; ; THE FOLLOWING PARAMETER SETS THE SIZE OF THE SEARCH BUFFER. ; IT MAY BE INCREASED TO ACCOMMODATE VERY LONG SEARCH STRINGS. ; GBLDEF=SCHSIZ:100 ; ; THE REMAINING SPACE IS DYNAMICALLY SHARED BETWEEN TEXT BUFFER AND ; Q REGISTER STORAGE. ; //