Digital Equipment Version 17 TECO-11 Reference Manual

CC Publication No. EDU-500 V.2 (4/77)

TECO-11 Reference Manual

(Describing Version 17 of TECO-11 for RSTS/E)

Version 2

April 1977

TECO-11 was written by:

Russell Hamm, Hank Maurer, Bob Hartman, Mark Bramhall,

Anton Chernoff, Richard Lary, and Mario DeNobili

Authors of this Manual:

G. Paul Koning and Anton Chernoff

Lawrence University

Computer Center

James S. Evans

Lawrence University

Department of Chemistry

Prepared and published by the staff of the

Lawrence University

Computer Center

Appleton, Wisconsin 54911

TECO-11 Reference Manual - CC Publication No. EDU-500

This Manual has been prepared for members of the Lawrence

University community. It describes TECO-11, operating as an alternate run-time system under RSTS/E on the PDP-11/45. Users of

TECO-11 may also refer to the more elementary TECO Introductory

____ ____________

Manual (CC Publication No. EDU-510). Readers' suggestions for______ improvements to this documentation will be welcomed by the authors and the Computer Center.

This Manual describes the specific operation of TECO-11 under

RSTS/E V6B-02. Nevertheless, with only a few exceptions hereinafter noted, users need not be concerned with the version of the RSTS/E monitor under which TECO-11 is running. Procedures for installing TECO-11 under V6B-02 and certain earlier versions of

RSTS/E are described in a companion document, the System Manager's

______ _________

Guide to TECO-11 (CC Publication No. MNG-500)._____ __ _______

Copyright (C) 1974, 1975, 1976, 1977 by Lawrence University of

Wisconsin. General permission to copy or modify, but not for profit, all or part of this Manual is hereby granted, provided that Lawrence's copyright notice is given, and reference is made to the fact that reproduction privileges were granted by permission of Lawrence University of Wisconsin.

Although every effort has been made to insure that this publication is accurate and that TECO-11 is free of errors, neither the authors of TECO-11 or of this publication, Lawrence

University, its funding sources, nor Digital Equipment Corporation make any warranty, expressed or implied, with respect to the correctness of the information contained in this publication or the functioning of TECO-11.

The following are trademarks of Digital Equipment Corporation,

Maynard, Massachusetts: DEC, DECtape, Digital, PDP, RSTS.

This publication was edited on a PDP-11/45 at Lawrence University using TECO-11 under RSTS/E (V5B-24, V6A-02, V6B-02). Layout was effected under RSTS/E using Lawrence's RUNOFF text formatting program. The copy masters were obtained on an IBM 360/44 at The

Institute of Paper Chemistry, Appleton, under OS/PCP using

Lawrence's program READRSTS to drive an IBM 1403 printer with an

IBM TN print chain.

Copies of this Manual may be purchased from Conkey's Book Store,

226 E. College Ave., Appleton WI 54911.

Portions of the computing resources available at Lawrence were purchased with grants from the National Science Foundation, the

National Endowment for the Humanities, the Andrew W. Mellon

Foundation, the Lilly Endowment, the American Council of Learned

Societies, and the United States Steel Corporation. Their support is gratefully acknowledged.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 1

TABLE OF CONTENTS _____ __

________

Section Page_______

____

1 INTRODUCTION 4

2 CONCEPTS 5

2.1 File specification 5

2.1.1 File name format 5

2.1.2 BASIC-PLUS mode ("/" in file name) 6

2.2 Character set 7

2.2.1 Special characters 7

2.2.2 Control characters 9

2.2.3 Terminal control functions 9

2.3 Data format (lines and pages) 10

2.4 Editing buffer 10

2.5 Buffer pointer 11

2.6 General command string syntax 11

2.7 Arguments 12

2.7.1 Text arguments 12

2.7.2 Numeric arguments 13

2.7.3 Commands that return a value 13

2.7.4 Examples 14

2.8 Q-registers 14

2.9 Core expansion 15

3 COMMANDS 16

3.1 Initialization commands 16

3.1.1 RUN $TECO Command (Invoke TECO-11) 16

3.1.2 MAKE Command (Create a file) 17

3.1.3 TECO Command (Edit a file) 17

3.1.4 Automatic setting of BASIC-PLUS mode

with ECO and MAKE commands 17

3.2 File selection commands 18

3.2.1 ER Command (Open file for input) 18

3.2.2 EW Command (Open file for output) 19

3.2.3 EB Command (Open file for editing) 19

3.3 Input commands 20

3.3.1 Y Command (Yank in a page: Destructive read) 20

___________

3.3.2 A Command (Append a page) 21

3.4 Special characters as buffer position numeric arguments 22

3.5 Buffer pointer positioning commands 22

3.5.1 J Command (Jump to buffer position) 23

3.5.2 C Command (Skip characters forward) 23

3.5.3 R Command (Skip characters backward) 23

3.5.4 L Command (Skip lines) 23

3.5.5 Examples 24

3.6 Text type-out commands 24

3.6.1 V Command (Verify) 24

3.6.2 T Command (Type-out) 25

3.6.3 ^O (CTRL/O) Special character (Stop type-out) 26

3.7 Deletion commands 26

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 2

3.7.1 K Command (Kill lines) 26

3.7.2 D Command (Delete characters) 26

3.7.3 Examples 27

3.8 Insertion commands 27

3.8.1 I Command (Insert) 27

3.8.2 TAB (CTRL/I) Command (Insert beginning with TAB) 28

3.8.3 @I Command (Insert using specified delimiter) 28

3.8.4 nI$ Command (Insert a character) 28

3.8.5 n\ Command (Insert a number) 28

3.8.6 FR Command (Replace) 29

3.8.7 Examples 29

3.9 Output commands 29

3.9.1 PW Command (Write a page) 30

3.9.2 P Command (Advance a page) 30

3.9.3 EF Command (End the output file) 31

3.10 Exit commands 31

3.10.1 EC Command (Close all files) 31

3.10.2 EX Command (Exit) 31

3.10.3 EG Command (Exit and go) 32

3.10.4 ^C (CTRL/C) Command (Emergency stop) 32

3.10.5 ^C (uparrow-C) Command (Immediate exit) 33

3.10.6 EK Command (Kill output file) 33

3.11 Search commands 33

3.11.1 S Command (Search) 34

3.11.2 FS Command (also ^R) (Search with replace) 34

3.11.3 N Command (Non-stop search) 35

3.11.4 FN Command (Non-stop search with replace) 35

3.11.5 _ (underscore or backarrow) Command

(Destructive search) 36

___________

3.11.6 Search modifiers 36

3.11.6.1 @ Modifier (Specify delimiter) 36

3.11.6.2 : Modifier (Return success/failure) 37

3.11.6.3 :: Modifier (Compare) 37

3.11.7 ES Command (Automatic typeout after searches) 37

3.11.8 Special control characters in search strings 38

3.11.9 Examples 39

3.12 Iteration commands 40

3.12.1 Iteration brackets (<...>) 40

3.12.2 ; Command (Conditional exit from iteration) 40

3.12.3 Examples 41

3.13 Flow control commands 41

3.13.1 Command string tags ("Labels") 42

3.13.2 O Command (Go to) 42

3.13.3 Conditional execution commands ("If...then") 42

3.14 Q-register commands 44

3.14.1 Commands that operate on numeric Q-registers 44

3.14.1.1 U Command (Store in numeric Q-reg) 44

3.14.1.2 Q Command (Retrieve numeric Q-reg) 45

3.14.1.3 % Command (Increment numeric Q-reg) 45

3.14.2 Commands that operate on text Q-registers 45

3.14.2.1 X Command (Load text Q-register) 45

3.14.2.2 G Command (Get text Q-register) 45

3.14.2.3 M Command (Execute macro) 46

3.14.2.4 ^U Command (Insert text into Q-reg) 46

3.14.3 * Command (Save the previous command string) 47

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 3

3.15 Numeric type-out and radix changing commands 47

3.15.1 = and == Commands (Numeric type-out commands) 47

3.15.2 Radix and radix changes 47

3.15.2.1 ^O Command (Set octal radix) 47

3.15.2.2 ^D Command (Set decimal radix) 48

3.16 Special numeric values 48

3.17 TECO-11 programming aids 50

3.17.1 ^A Command (Text type-out) 50

3.17.2 ? Command (Tracing) 51

3.18 Ignored characters in command strings 51

4 USER ERRORS AND ERROR RECOVERY 51

4.1 Erasing commands 52

4.1.1 RUBOUT Command (Cancel a character) 52

4.1.2 ^U (CTRL/U) Command (Cancel line) 52

4.1.3 ^G^G (double bell command (Cancel entire

command string) 52

4.1.4 ^Gspace (bell space) Command (Retype line) 53

4.2 Error messages 53

4.2.1 ? Command (Print traceback) 54

4.2.2 EH Command (Help flag) 54

4.3 Recovery from output device errors 55

4.4 Recovery from failure to specify BASIC-PLUS mode 55

5 EXAMPLES AND ADVANCED TECHNIQUES 56

5.1 Some uses of Q-registers 56

5.1.1 Back-up for the editing buffer 56

5.1.2 Moving a few lines 56

5.1.3 Typing a located passage of unknown length 57

5.2 Manipulating files 57

5.2.1 Dividing a file in one pass 58

5.2.2 Merging portions of different files 58

5.2.3 Rearranging a file 59

5.3 Using iteration loops 61

5.3.1 Counting lines in the editing buffer 61

5.3.2 Breaking a file into pages of 40 lines 61

5.3.3 Formatting a file 62

5.3.4 Passing arguments to and from macros 63

5.4 Using conditional commands 63

5.4.1 Replacing multiple spaces with tabs 63

5.4.2 Changing to integer variables in BASIC-PLUS 64

5.4.3 Rough alphabetizing by initial letter 66

5.4.4 Breaking a file into pages of 4000 characters 67

5.5 Preparing text for processing with RUNOFF 68

A TECO-11 Error Messages 75

B Summary of Commands 79

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 4

1 Introductiti

1 INTRODUCTION ____________

TECO, a very powerful Text Editing and COrrecting program, has

_ _ __ been implemented for several computer systems, including the

Digital Equipment PDP-10 and PDP-11. Since all editors that can properly be called "TECO" employ a similar command structure, the person who masters TECO at one computer installation can readily use TECO at another installation. In that sense, TECO is comparable to high-level programming languages like BASIC or

FORTRAN.

This manual is a complete reference manual for the experienced

TECO-11 user, or for the user who already has experience with other editing programs. It is not designed to be used as a

___ beginner's text, and persons who are learning TECO should not use it as such. Beginners are referred to the TECO Introductory

Manual (CC Publication No. EDU-510).

TECO-11 is a general-purpose text editor for editing any text or program file. Command input to TECO-11 is given from the user's terminal. Input and output files can reside on any of the standard I/O devices that are supported by RSTS/E. Although most editing can be accomplished using only a few simple commands, the sophisticated user can select from a large set of commands, such as character string search, command repetition, and text block movement. Refer to Appendix B for a summary of the commands available.

TECO-11 can be used at any terminal and under any user account on the Lawrence University RSTS/E timesharing system. TECO-11 is implemented as an alternate run-time system under RSTS/E, V6B-02, and occupies 4K of sharable memory whenever one or more users are doing text editing.

TECO-11 is frequently used to prepare text containing the necessary control commands for subsequent formatting of a document using Lawrence's RUNOFF program. The capabilities of RUNOFF include line filling, margin justification, paragraph indentation, footnote placement, underscoring, centering, page headers, and subtitles. By setting special flag commands in the input text file, the user can request RUNOFF to convert upper case characters to lower case, or vice versa; thus the input file can be prepared on terminals having only upper case characters. For full information about RUNOFF, refer to the RUNOFF Reference Manual (CC

Publication No. EDU-520) published by the Lawrence University

Computer Center.

TECO-11 is a character-oriented text editor; one or more characters in a line can be modified without retyping the rest of the line. Any text file can be edited, including programs written in BASIC-PLUS as well as natural language text. TECO-11 does not require that the text file have line numbers or other extraneous information in it. The full ASCII character set, printing and

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 5

2 Concepts non-printing characters alike, can be processed.

Cross-references to other sections in this manual will generally appear in the form '{x.y.z}', e.g. {2.2.1}.

2 CONCEPTS ________

This section covers fundamental concepts of TECO-11: input and output files {2.1}, the TECO-11 character set {2.2}, data format

{2.3}, the editing buffer {2.4}, the buffer pointer {2.5}, the general command string syntax {2.6}, the use of arguments in commands {2.7}, Q-registers {2.8}, and core expansion {2.9}. The information here is vital to a proper understanding of section 3

(on specific commands), section 4 (on user errrrs s nd error recovery), and section 5 (examples and advanced techniques).

Note: The IBM TN printer chain used to prepare this Manual cannot____ produce exact equivalents of certain ASCII characters used by

TECO-11. In particular, the backslash (ASCII decimal 92) is printed as "\", the uparrow or circumflex (ASCII decimal 94) as

"^", and the backarrow or underscore (ASCII decimal 95) as "_".

2.1 File specification

TECO-11 operates on ASCII files. The input file is the file that the user wants to change. The output file is the file that receives the newly created or edited data.

Inputting is the process of reading data that already exist in some machine-readable form (disk, DECtape, magtape, etc.). Data can be input from any device (including the user's terminal, although this is not recommended). Inputting must be distinguished from inserting, which is the actual typing in of new data at the user's terminal.

2.1.1 Filename format

An acceptable TECO-11 file name is any valid RSTS/E file name, consisting of:

1) A device name (optional; logical device names are

recognized);

2) An account number (optional; the special account

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 6

2.1 File Specification

designators $, !, %, and & are also valid);

3) A file name (mandatory);

4) An extension (optional, separated from the file name by a

".");

5) A protection code (optional, enclosed in "<>"); and

6) A "/" character (optional; invokes BASIC-PLUS mode

{2.1.2}).

Both the file name and the extension (where specified) must consist of alphabetic and numeric characters only. Lower-case characters are considered equivalent to the corresponding upper-case characters.

For a non-file structured input device such as a terminal, only the device name is needed as the file name specification. For disk, DECtape, and file-structured magtape, a full filename must be specified. In addition, the user may specify an account number and device name; if omitted, the user's account and the public disk structure are assumed.

TECO-11 contains its own file name scanner, which does not accept the file specification options (/CL, /FI, /MO, /RO, or /SI) that have been introduced with RSTS/E V6B-02. The only valid switch is the "/" character by itself, which enables the BASIC-PLUS mode described below.

2.1.2 BASIC-PLUS mode (optional "/" in file name)

TECO-11 treats all files as straight text unless instructed otherwise. In particular, its normal treatment of line feeds and nulls does not make it well suited for editing BASIC-PLUS programs. Thus the special "BASIC-PLUS mode" should be specified for any input or output file containing BASIC-PLUS code by appending "/", the ASCII slash character, to the file name specification.

When BASIC-PLUS mode is specified for an input file, TECO-11 inputs lines of text from the file into the editing buffer in a special way:

1) Carriage return characters are ignored;

2) Line feed characters are changed to CR-LF F F binations

before being stored in the editing buffer; and

3) Nulls are ignored (as always).

While editing the BASIC-PLUS program text, one should terminate continuation lines with the carriage return key, rather than the

line feed key. The only restriction is that continuation lines must begin with a non-digit character; a TAB character is recommended for program readability. If these practices are followed consistently, all of the line-oriented commands in

TECO-11 will function naturally.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 7

2.1 File Specification

When BASIC-PLUS mode is specified for an output file, TECO-11 takes the following actions when writing text from the editing buffer into the output file:

1) The special combination &<CR><LF>, which may be used with

EXTEND mode in BASIC-PLUS to terminate all but the last

physical line of a multi-line statement, is written out

unaltered;

2) Otherwise, carriage return characters are discarded;

3) A line feed character that is not followed by a digit is

___

written out as the <LF><CR><NULL> combination; and

4) A line feed character that is followed by a digit is written

out as the <CR><LF> combination.

2.2 Character set

The TECO-11 character set is the full 128-character ASCII character set. In general, the user must be concerned with this character set on two levels: the data level and the command level.

Every ASCII character from NULL (decimal value 0) through RUBOUT

(decimal value 127) is legal in TECO-11 data. Every character can be inserted from the keyboard or written into the output file.

The NULL and RUBOUT characters are ignored on input. The FORM

FEED character is treated specially on input {2.3}, {3.3}, {3.16}.

Because of the special way in which the characters LINE FEED

(abbreviated LF) and CARRIAGE RETURN (abbreviated CR) are treated in BASIC-PLUS programs, the user may select an option to treat these characters in a different way (on input and output only), as appropriate for BASIC-PLUS program text {2.1.2}.

Each basic TECO-11 command consists of one or two ASCII characters. Most of the ASCII characters have some meaning when used in a TECO-11 command. A few are recognized as special characters by the RSTS/E monitor {2.2.1}. When used in commands, lower-case characters have the same meaning as their upper-case equivalents. The table in Appendix B lists the various command characters explained in this manual and notes which characters have no meaning as TECO-11 commands.

2.2.1 Special characters

Editing commands are given to TECO-11 by typing a command string consisting of a series of characters {2.6}. But because of their use as special immediate-action commands (erasing commands, etc.), certain characters cannot be typed in as part of a command string, nor may they be present in text inserted from the terminal.

Nevertheless, they are legal in an input file. These characters,

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 8

2.2.1 Special Characters which are referred to in this manual as "special command characters", are listed in the table below. (The symbol '^' is printed by ASCII terminals as a circumflex or uparrow.)

Special Characters _______

__________

Character Remarks

^C (CTRL/C) Aborts whatever TECO-11 is doing at the

time ^C is typed. TECO-11 responds with

the message 'Re-entering TECO'. A single

______

CTRL/C should terminate a command that

caused an infinite loop, such as an

erroneous iterative command {3.12.1}. Such

an abort leaves the editing buffer {2.4}

in the state it was in when the ^C was

typed. The aborted (and possibly

erroneous) command may itself have done

damage, however. If ^C is typed again

before any delimiting character is entered

(delimiting characters are CR, LF, FORM

FEED, ESCAPE, RUBOUT, CTRL/U, CTRL/G, and

CTRL/D), TECO-11 exits immediately to

RSTS/E.

^G^G (2 successive An erasing command. Causes TECO-11 to

CTRL/Gs) erase the complete command and return back

to command level. A single CTRL/G has no

special meaning.

^Gspace (CTRL/G, Causes current line to be retyped.

space) Useful when repeated use of RUBOUT (see

below) has made the line being entered

illegible.

^O (CTRL/O) When typed while TECO-11 is printing out

text, causes printout to stop, but all

other processing continues normally. Used

when a long typeout is to be suppressed.

At any other time it is ignored.

^U (CTRL/U) Erases the current command line (i.e. all

typed characters back to, but not

including, the most recent line feed

character).

ESC or (The ESCAPE or One ESCAPE (also called "altmode")

ALT ALTMODE key) terminates a string argument. Two

successive ESCAPE characters terminate a

command string and start command

execution. ESCAPE echoes as $ (dollar

sign).

RUBOUT (The RUBOUT or Erases the previous character in the

DELETE key) command string. Echoes as the character

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 9

2.2.1 Special Characters

just deleted. Unlike BASIC-PLUS under

RSTS/E, TECO-11 does not enclose deleted

___

characters in backslashes.

In addition, the characters CTRL/S and CTRL/Q are special characters only on a scope terminal; then RSTS/E intercepts these characters (i.e. TECO-11 does not receive them) and they have the function of suspending and resuming printout.

Caution: If the system is heavily loaded, the ^U and RUBOUT characters may take a long time to echo, and may even echo out of sequence.

2.2.2 Control characters

Control characters are typed by holding down the CTRL key while striking a character key. The control characters have ASCII decimal values 1 through 31. When TECO-11 is printing or accepting text from the keyboard, a control character is printed out as an uparrow (circumflex), followed by the character that was typed to produce the control character. For example, CTRL/A prints as

"^A".

In most cases, an alternate method for entering control character commands is to type first an uparrow (circumflex) character, and then the desired character without depressing the CTRL key. For example, when used as a command, the two-character sequence uparrow-H is equivalent to the single character CTRL/H. This method can be used only for commands, not when a character is typed as text or as an alphanumeric argument. In this manual, control characters will be denoted as they would be printed by

TECO-11 (i.e. ^A will denote CTRL/A) and, unless stated otherwise, both the CTRL/character and the uparrow-character commands are acceptable.

2.2.3 Terminal control functions

A few of the control characters have special terminal functions:

BELL, BACKSPACE, TAB, CR, LF, and FORM FEED. All of these characters are echoed or printed by performing their function, regardless of whether TECO-11 is accepting command input or printing out text. CTRL/G echoes as uparrow-G (in addition to ringing the bell) only when entered as command input.

Since ESCAPE is not a printing character, it will be represented in this manual by a $, so that the examples appearing here will look precisely as if they had been echoed or printed out by

TECO-11.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 10

2.3 Data Format

2.3 Data format (lines and pages)

TECO-11 is capable of editing text written in any format. There are, however, certain features of TECO-11 that make use of the concept of a line and a page. ____ ____

Lines can be of any length. The character that defines the end of a line is the line feed (LF). The end of the editing buffer also acts as an end-of-line character even if there is no actual LF character at the end of the buffer. When TECO-11 counts lines, it does so by counting end-of-line characters. An end-of-line character is considered to belong to the line it terminates. Note that although the carriage return character is not itself a line-terminating character, it is transformed into a CR-LF combination by TECO-11 when it is typed in by the user at the terminal. Thus typing CR will result in insertion of the LF line-terminating character also.

Text to be edited by TECO-11 does not have to contain line-terminating characters. Of course, if it does not, those features of TECO-11 that count lines are useless.

Pages are defined in TECO-11 by form feed (FF) characters, which act as page separators. They are not considered to be a part of either of the two pages that they separate. Two consecutive FF characters delimit a null page. A form feed character at the beginning of the file delimits a null page at the beginning of the file. A form feed character at the end of the file has no significance and can be omitted.

TECO-11 can be used to edit BASIC-PLUS source programs {2.1.2} and other files containing sequence numbers or line numbers, but it makes no special use of such sequence or line numbers.

2.4 Editing buffer

Editing consists of:

1) Reading text from the input file into the editing buffer;

2) Making changes to the text in the editing buffer; and

3) Writing the modified text out to a new file (the output

file).

The editing buffer is a block of memory within the user's job area. Text is put into the editing buffer when it is read in or inserted, and is then kept in the editing buffer while it is being

modified. The largest job area available to any user at Lawrence, currently 12K of memory, could accommodate over 22000 characters.

If the input file is extremely large, however, only a portion of it can be kept in the editing buffer at any given time. In the interest of efficiency, it is always best to keep the number of characters in the editing buffer less than 22000 {5.3.2}, {5.4.4}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 11

2.5 Buffer Pointer

2.5 Buffer pointer

TECO-11 is a character-oriented editor; therefore, the user must understand the important concept of the buffer pointer. The

_______ position of the buffer pointer determines the effect of many editing commands. For example, insertion and deletion always take place at the current position of the buffer pointer.

The buffer pointer is a movable position indicator. It is always positioned between two characters in the editing buffer, or after

_______ the last character in the buffer, or before the first character in the buffer. The buffer pointer is never on a particular

__ character; it is positioned either immediately before or immediately after a character.

The pointer can be moved forward or backward over any number of characters, but it cannot be moved beyond the boundaries of the buffer. That is, it cannot be moved farther back than the position immediately preceding the first character in the buffer, nor farther ahead than the position immediately after the last character in the buffer.

When discussing text in the editing buffer, one frequently uses the phrase "current line". The current line is the line in which the buffer pointer currently resides, extending back to (but not including) the previous LF character or the start of the buffer, and forward to (and including) the next LF or the end of the buffer. The pointer can be positioned either at the beginning of a line or in the interior of a line.

2.6 General command string syntax

Commands are given to TECO-11 by typing a command string, which is a series of commands, typed one immediately after the other and concluded with two consecutive ESCAPE characters. (Refer to

Appendix B for a summary of commands.)

A command string may be typed after TECO-11 prints an asterisk to indicate that it is ready. An example of a command string is:

*YIHEADING$ 2K4D NTAG$ 2LT$$ (asterisk printed by TECO-11)

Execution of the command string begins only after the two

consecutive ESCAPEs have been typed. TECO-11 then indicates that it is beginning execution of the command string by sending a carriage return and a line feed. At that point, each command in the string is executed in turn, starting at the left. When all commands in the string have been executed, TECO-11 prints out another asterisk to indicate that it is ready to accept another command string.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 12

2.6 Command String Syntax

If a command in the string cannot be executed because of an error condition, execution of the command stops at that point, and an error message is printed. Commands preceding the command in error will have been executed. The erroneous command and the commands following it have been aborted. Errors, error messages, and error recovery techniques are fully discussed in section 4.

There are exceptions to the rule that commands a a not executed until the end of the command string has been denoted by ESC-ESC.

These exceptions (the special command characters) were discussed in section 2.2.1.

Note: The phrase "two consecutive ESCAPEs" as used here implies____ that nothing at all may come between them. For example, the string "ESC space RUBOUT ESC", although seemingly equivalent to two ESCAPEs, is not "two consecutive ESCAPEs". The same applies to the term "two consecutive CTRL/Gs" {2.2.1}.

2.7 Arguments

Some TECO-11 commands may (or must) include arguments. Some commands use text arguments (text to be inserted, substituted, etc.), while some use numeric arguments (buffer position, number of lines, etc.). In addition, some commands return a value which

______ can be used as an argument.

2.7.1 Text arguments

Most text arguments are to be interpreted as ASCII data by

TECO-11. In this category are data to be inserted into the editing buffer {3.8}, search character strings {3.11}, and command string tags for unconditional branches {3.13.2}. Other types of text arguments include device and file names and Q-register names

{2.8}.

A text argument always follows the command to which it applies.

_______

As a rule, most commands that take text arguments require that the argument be terminated by one ESCAPE; the few exceptions to this rule are explained at appropriate places in the manual.

The ESCAPE used to terminate a text argument can also function as one of the two ESCAPEs needed to terminate a command string.

Any ASCII character is legal in a text argument, with the exception of the special command characters {2.2.1}. However, when the argument is used as a target string in a search operation, several other characters have special meaning {3.11.8}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 13

2.7 Arguments

2.7.2 Numeric arguments

Numeric arguments always precede the command to which they apply.

_______

In some cases, only a single numeric argument is required; in others, a pair of numeric arguments is required. When two numeric arguments are used, they must be separated by a comma. In most cases, numeric arguments must be positive; however, some commands allow a numeric argument to be negative or zero. The number and type of numeric arguments allowed by each command are stated in the section in which the command is discussed.

Where a numeric argument is used to specify a buffer position, the number used is the number of characters in the editing buffer to the left of that position. Thus, N represents the position to the right of the Nth character in the editing buffer (between the Nth and the N+1st characters).

Numeric arguments used in pairs are always buffer position arguments. Such a pair specifies all characters in the editing buffer that lie between the two buffer positions represented by the two arguments. This definition is precise because the term

"buffer position" always indicates a position before or after a given character, not "on" or "at" the character.

Numeric arguments can be combined in arithmetic or logical expressions. Valid operations are addition, subtraction, multiplication, and division, all with integer operands, as well as logical AND (represented by the & operator) and logical OR

(represented by the # operator). Parentheses may be used freely in properly matched pairs. All operators have equal precedence

(unlike BASIC-PLUS, but similar to APL), and are executed from left to right if no parentheses are used.

Normally TECO-11 assumes that numbers are entered in decimal notation, but the ^O command (uparrow-O, not CTRL/O, which is a special command character) can be used to switch the mode within

TECO-11 to octal representation until the ^D command is used to reset the numeric mode to decimal {3.15.2}.

2.7.3 Commands that return a value

There are two general categories of TECO-11 commands:

1) Those which perform some operation, such as inserting text;

_______

and

2) Those which return a value, such as the number of characters

______

in the editing buffer.

(There are also some commands that do both.)

A command is said to "return" a value if the command causes the current value of some quantity to be calculated. Then the command takes on this value, becoming itself a numeric argument that can be ededby another command. Subsequent use of such a command is

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 14

2.7 Arguments equivalent to typing the particular number that the command returns as a value, except that the value is not usually known in advance. This value can thus be used as an argument by the next command in the command string, provided this subsequent command can take a numeric argument. Otherwise, the value is ignored.

(If you use a command that returns a value immediately followed by a command that accepts one, but you want TECO-11 to ignore the value that was returned, insert an ESCAPE between the commands.

There the ESCAPE behaves as a separator that performs no function, ignores any numeric argument, and does not return a value. This operation, in ALGOL68 terms, is called "voiding".)

An example of a command that returns a value is the Z command

{3.4}. The Z command returns a value equal to the number of characters in the buffer. Since it has no other function, Z must be used as a numeric argument preceding another command.

Commands that return values may be used in arithmetic or logical expressions with each other and with (explicit) numbers. All the usual rules apply. Each command that returns a value has all the properties of a number that has been explicitly typed in.

If commands that return values are concatenated with each other or with digits, the value returned is that of the last command or number in the string. An operator preceding such a string continues to apply.

2.7.4 Examples

Command string Result

Z= Prints out the value of Z {3.4, 3.15.1}. Z returns

the number of characters in the editing buffer, so

this command can be used to see how much space is

being taken up by text.

5%P$A This command string consists of two commands. The

first command (the % command {3.14.1.3}) adds 5 to

the numeric Q-register P {2.8} and returns the new

value. The ESCAPE (printed as a dollar sign)

causes the returned value to be ignored, so that

the A that follows is interpreted as an Append

command {3.3.2}. If the ESCAPE had not been

present, the A would have been interpreted as a

different command {3.16} with a numeric argument.

2.8 Q-registers

Q-Registers are data storage registers available to the TECO-11 user. Q-Registers provide a great amount of editing power by

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 15

2.8 Q-Registers enabling programmed editing and text block movement. Data stored in Q-registers are not disturbed by the flow of data into and out of the editing buffer, but can be preserved throughout an entire

TECO-11 editing session and retrieved or changed at any time.

There are two types of Q-registers, numeric and text. Each particular register within each type is designated by a single character, namely one of the letters A-Z or the digits 0-9; thus there are 36 Q-registers of each type. The two types of

Q-registers are completely separate, i.e., data stored in a numeric Q-register in no way affects data stored in a text

Q-register with the same name.

Each numeric Q-registers can hold a single integer number in the range -32768 to 32767. Numbers stored in Q-registers can be incremented, tested, or recalled. Hence numeric Q-registers can be used as switches or counters, as well as for simple data storage applications.

A text Q-register can hold a character string of arbitrary length

(limited only by the amount of memory available). Two types of text strings can be stored in a Q-register: ordinary text and

TECO-11 command strings. Text can be stored in a Q-register without disturbing data stored in the editing buffer. Storing ordinary text in a Q-register is useful for creating multiple copies of a piece of text, or for block text movement.

Textual data in the form of TECO-11 command strings can also be stored in Q-registers. Such a command string (called a "macro") can be recalled and executed over and over again during an editing job, much like calling a subroutine. Macro command strings can be edited just as any other text.

2.9 Core expansion

When started, TECO-11 automatically obtains a 2K area of memory from the user's area to be used for the following storage areas:

1) Fixed-length buffers, variable storage area, etc.;

2) The editing buffer;

3) The command string buffer; and

4) The storage area for the text Q-registers.

The first of these areas is of fixed length and remains permanently allocated during the entire job. The other three are of variable length, and as needs vary, the relative sizes of these

areas are adjusted to fit the available storage. Whenever these needs cannot be met (for example, because of the inputting of a large file from disk or the typing of a long command), TECO-11 automatically requests more memory space from the RSTS/E monitor.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 16

2.9 Core Expansion

If the request is successful, TECO-11 prints out an informational message of the form:

[xK memory] (where x is the number of 1K core segments

presently allocated to TECO-11) and continues. If TECO-11 attempts to obtain more storage than available (at Lawrence, ordinarily 8K, but up to 12K for privileged accounts), the attempt fails and TECO-11 prints out the error message:

?MEM Memory overflow

At this point you can still save the result of the editing, but it is not possible to add any more text to the editing buffer (unless you can clear some text Q-registers that have text in them).

3 COMMANDS ________

This section contains detailed descriptions of, and instructions for using, each of the TECO-11 commands. Users are cautioned that virtually every one of the 128 ASCII characters is used as a

TECO-11 command. Thus caution must be used to avoid typing

"spurious" characters in a command string, for TECO-11 will not treat them as spurious. Indeed, their effect may be catastrophic

{4}. Appendix B summarizes all of the TECO-11 commands.

3.1 Initialization commands

TECO-11 at Lawrence is invoked by giving one of three different commands to RSTS/E at any point after receiving the 'Ready' message. These commands are RUN $TECO, MAKE, and TECO.

3.1.1 RUN $TECO Command (Invoke TECO-11)

This causes the execution of a program that loads and starts

TECO-11. TECO-11 indicates its readiness for commands by printing out an asterisk. At this point there are no open input or output

files, and you must start by issuing an appropriate command to open input and/or output files {3.2}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 17

3.1 Initialization Commands

3.1.2 MAKE Command (Create a file)

This causes TECO-11 to run as if a RUN $TECO command had been issued; in addition, the file specified following the MAKE command is opened for output (as if an EW command {3.2.2} had been issued). Example:

MAKE TEST.TXT Starts TECO-11 and opens file TEST.TXT for

output.

3.1.3 TECO Command (Edit a file)

This command is similar to the MAKE command in that it takes a file name as argument, but in this case the file is opened for editing as though an EB command {3.2.3} had been issued. In addition, the first page of the file (or the whole file, if it has only one page, or that portion of it which fits, if it is huge) is read into the editing buffer, as with a Y command {3.3.1}.

Example:

TECO TEST.TXT Starts TECO-11 and opens the file TEST.TXT

for editing. When editing is completed, the

original file will be renamed to TEST.BAK

and the new file will be named TEST.TXT.

Note that if the file name is omitted from a TECO or MAKE command, the effect is the same as typing the command 'RUN $TECO'.

3.1.4 Automatic setting of BASIC-PLUS mode with TECO and MAKE

TECO-11 itself never attaches any special meaning to extensions of files, except for the action of the EG command {3.10.3}. In particular, the extension '.BAS' does not trigger BASIC-PLUS mode

___

{2.1.2}.

As a convenience for users at Lawrence, however, the loader program for TECO-11 does force TECO-11 into BASIC-PLUS mode by

____ appending "/" to the file specified with a TECO or MAKE command if the extension is one of the following:

null The autoloader first appends '.BAS' unless '.' is present.

.BAS The normal extension for BASIC-PLUS files.

.BEX The normal extension for files written in Lawrence's

XBASIC precompiler dialect of BASIC-PLUS.

.MAS The normal extension for files written for processing

through Lawrence's BUILD program for tailoring BASIC-PLUS

code to specific system parameters.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 18

3.1 Initialization Commands

In the rare circumstance that one must edit a file having one of the above extensions without using BASIC-PLUS mode, he may either

_______ enter TECO-11 via the 'RUN $TECO' command, or disable the automatic forcing of BASIC-PLUS mode by appending a "\" (backslash character) to the filename. The backslash is removed before the filename is passed to TECO-11.

The automatic setting of BASIC-PLUS mode applies onlylylythe file

____ specified with a TECO or MAKE command. Any further file specifications given directly to TECO-11 during the current editing session require explicit setting of BASIC-PLUS mode if it is desired {2.1.2}.

3.2 File selection commands

File selection is the specification of the devices and files from which input is to be taken and to which output is to be sent.

If the user only wants to create a file, or to edit an existing file, file selection is accomplished most easily by the commands described in section 3.1. In other cases, or when TECO-11 is started with the RUN $TECO command, one or more of the commands in this section should be used.

3.2.1 ER Command (Open file for input)

The ER command is used to select a file for input. The general form is:

ERdevice:[proj,prog]filename.ext$ where device, [proj,prog], and/or extension may be omitted. Any valid RSTS/E file name is accepted. If the file specified does not exist or the user does not have read access to it, an error message is printed and no file is opened. The ER command closes any previously opened input file before opening the specified file.

The user may open one file for input, read only part of the file, then open another file with a new ER command without having to read to the end of file on the first file. After opening the second file, the first file is no longer accessible. In other

words, there is never more than one input file open at a time.

Data cannot be input without first issuing an ER or equivalent command.

Examples:

ERDATA.TXT$ Prepares to read a text file that is not a

BASIC-PLUS program.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 19

3.2 File Selection Commands

ERPROG.BAS/$ Prepares to read a file that is a BASIC-PLUS

program. Note that the .BAS extension is

not sufficient indication to TECO-11 for

___

setting the special BASIC-PLUS mode.

3.2.2 EW Command (Open file for output)

The EW command is used to select a file for output. The general form is the same as for the ER command, except that a protection code for the file may be specified within angle brackets. If any file was previously opened for output, the EW command closes that file before opening the new file. There can be only one output file open at a time.

Note that the EW command does not check for the existence of the

___ output file. If the file named in the EW command already exists, it will be deleted (unless the protection code of that file makes this impossible, in which case an error message will be printed).

The EW and ER command are mutually independent, i.e. one can issue multiple EW commands without changing the input file, and vice versa.

As with the ER command, the user can specify the BASIC-PLUS option

{2.1.2} when creating the output file. When the option is specified for both input and output, a BASIC-PLUS program will be edited without problems by TECO-11. Example:

EWFILE.BAS/$ Creates an output file and sets the

BASIC-PLUS option for output. If the file

__ ___ ____

already exists, it is replaced without

_______ ______ __ __ ________ _______

warning. _______

3.2.3 EB Command (Open file for editing)

The EB command is used to open a file for editing. This command is also executed by a "TECO filename" command {3.1.3}. It can be used only for files that are stored on a directory-structured medium, i.e. disk or DECtape. The general form is identical to that of the EW command. The result of an EB command is:

1) The file specified is opened for input, as with an ER

command. Any file previously opened for input is closed.

2) A file named TECOxx.TMP, where xx is the user's job number,

is opened for output as by an EW command. The file resides

on the same device and account as the input file.

3) Further EW commands are disabled until the output file has

been closed.

When the output file is closed, the following takes place:

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 20

3.2 File Selection Commands

1) The input file is renamed to have the extension .BAK. If a

file with that name already exists, the old backup file is

deleted.

2) The temporary file opened in step 2 above is renamed to have

the same name and extension as the original input file; the

protection code is the one specified in the EB command (60

is assumed as the default value).

Thus when editing is completed, the specified file is replaced by the updated version, and the original still exists with the .BAK extension. Note that the EB command should not be used for input files with a .BAK extension, nor for files with a name such as

TECOxx.TMP. Furthermore, EB cannot be used by the non-privileged user to edit files on accounts other than his own.

The EB command, when used with a "/" in the file name, sets the

BASIC-PLUS option both for input and output {2.1.2}.

Example:

EBTEST.TXT$ Opens TEST.TXT for editing. After editing,

the new file will be named TEST.TXT, and the

original file will be renamed to TEST.BAK.

If TEST.BAK already exists, the existing

copy is deleted and replaced by the backup

for the new file.

EBPROG.BAS/$ Opens program file for editing in BASIC-PLUS

mode {2.1.2}.

3.3 Input commands

Input commands are used to read data into the editing buffer from the input file, which must have been previously opened; i.e., input commands can be used only after giving a command to open an input file, namely ER or EB. Input always starts at the beginning of the selected file. Subsequent input commands then read successive segments of data from the input file.

The amount of data read depends on the particular input command and on the data format, as explained below.

3.3.1 Y Command (Yank in a page: Destructive read)

___________

The Y (Yank) command first clears the editing buffer and then

______ reads text into the buffer until one of the following conditions is met:

1) The end of the input file is reached.

2) A form feed character is read.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 21

3.3 Input Commands

3) The editing buffer is less than 128 characters from being

full, and a line feed is read.

4) The buffer is completely filled.

The usual effect of the Y command is to clear the editing buffer and then read the next page of text into it. Less than a full page is read only when the page is too big to fit in the buffer in its entirety. When reading in the page, TECO-11 attempts to expand the editing buffer, if possible, whenever the current buffer is filled up. If this happens, TECO-11 notifies the user by printing out a message like [7K memory].

If a previous input command had encountered the end of the input file, the Y command only clears the text buffer.

If a form feed is read (which causes input to stop), the form-feed flag (returned by the command ^E {3.16}) is set to -1; if input stops for some other reason, the form-feed flag is set to 0. If input stops because of an end-of-file condition, the end-of-file flag (returned by ^N {3.16}) is set to -1; otherwise it is set to

0.

The "TECO file name" command {3.1.3} automatically executes the Y command once after executing an EB command on the file specified in the command.

The Y command sets the buffer pointer to the start of the text buffer. The Y command does not accept any numerical argument (if one is given, it is ignored). To do multiple Y operations, use a command such as n<Y> (iteration loop {3.12.1}).

3.3.2 A Command (Append a page)

The A (Append) command reads in the next page of text from the input file without first clearing the editing buffer. The new input data is appended to the end of the text already in the buffer. The buffer pointer is not relevant, nor is it changed. A form feed separating the pages (if present) is skipped. Thus, the

A command can be used to combine several pages.

In the same manner as the Y command, the A command will expand the editing buffer if needed. Also, it stops input in the same four cases as does Y and sets the form-feed and end-of-file flags in the same manner. If the end of the input file was previously reached, the A command has no effect.

The append command does not accept a numeric argument. Thus, to

do multiple appends, one must use an iteration loop {3.12.1}. Note that A, when given a numeric argument, performs a different function {3.16}. It is therefore important to insert an ESCAPE

{2.7.3} between the A command and any command returning a value which immediately precedes it.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 22

3.5 Buffer Position Arguments

3.4 Special characters as buffer position numeric arguments

In many cases, numeric arguments are used to specify buffer positions. Because such arguments tend to be large and not easily determined by counting, the buffer positions commonly used as arguments are represented by certain characters shown in the table below.

Buffer Position Arguments ______

________ _________

Character Value

B Equivalent to 0. It represents the position at the

beginning of the buffer, i.e. preceding the first

character in the buffer.

Z Equals the total number of characters in the

buffer. Thus, Z represents the position at the

end of the buffer, immediately after the last

character in the buffer.

.(period) Equals the number of characters to the left of the

current buffer position, i.e. represents the

current buffer position itself.

H Equivalent to the numeric argument pair B,Z. Thus,

in those arguments that take two numeric buffer

position arguments, H represents the whole buffer.

This letter is particularly useful with type-out

and output commands.

^Y Equivalent to ^S+.,. {3.16}. When used with

commands that accept a pair of arguments, this

represents the part of the text in the editing

buffer that was most recently inserted {3.8} or

found in a search {3.11}. Refer to section 3.6 for

an example.

The characters B, Z and . ("dot") may be used in arithmetic expressions, since they are normal commands that "return a value"

{2.7.3}.

3.5 Buffer pointer positioning commands

This section describes the most elementary commands for moving the

buffer pointer. These elementary commands, along with the search commands described in section 3.11, make up a set of powerful pointer-positioning commands.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 23

3.5 Buffer Pointer Positioning Commands

3.5.1 J Command (Jump to buffer position)

The nJ command moves the buffer pointer to the position immediately after the nth character in the buffer. The command 0J

(or BJ) moves the pointer to the beginning of the buffer, i.e. to the position immediately preceding the first character in the buffer. The command J, when not preceded by a numeric argument, is equivalent to 0J.

3.5.2 C Command (Skip characters forward)

The nC command adds n to the current buffer pointer position, i.e. if n<0, the buffer pointer is moved backwards |n| characters; otherwise the pointer is moved forward over n characters. The nC command is therefore equivalent to ".+nJ". The command C (without an argument) is equivalent to 1C; the command -C is equivalent to

-1C.

3.5.3 R Command (Skip characters backward)

The command nR is equivalent to -nC. R without argument is equivalent to -C; -R is equivalent to C.

3.5.4 L Command (Skip lines)

The L command moves the buffer pointer over entire lines. The pointer is moved forward or backward past n line feeds, and is always left immediately following a LF character. The use of the

L command with various arguments is shown in the table below.

L Commands _

________

Command Argument Function

L 1 assumed Advances the pointer to the beginning of

the next line.

nL n>0 Advances the pointer to the beginning of

the nth line following the current line.

0L 0 Moves the pointer back to the beginning of

the current line.

-L -1 assumed Moves the pointer back to the beginning of

the previous line.

nL n<0 Moves the pointer back to the beginning of

the |n|th line preceding the current line.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 24

3.5 Buffer Pointer Positioning Commands

If the user attempts to move the buffer pointer to some position beyond the boundaries of the editing buffer with the J, C or R commands, the error message:

?POP Pointer off page is printed and the pointer is not moved. In case of the L command no error message is printed, and the pointer is moved to the boundary of the buffer that the user attempted to cross. For example, the command -1J results in an error message, whereas the command ZJ L does not, but positions the pointer at the end of the buffer.

3.5.5 Examples

Command Result

J Puts the buffer pointer at the start of the

buffer.

L Goes to the start of the next line.

0L Goes to the start of the current line.

L 2R Goes to the end of the current line. Explanation:

First, we go to the next line ("L" command). Then

the 2R command "backspaces" over two characters,

namely the LF and CR characters that normally

delimit the line.

ZJ Goes to the end of the buffer

C Advances one character.

3.6 Text type-out commands

Type-out commands are used to identify the position of the pointer in the editing buffer, to inspect the text, or to verify the correctness of modifications.

3.6.1 V Command (Verify)

The V command is used to print out the current line. It ignores any numeric argument. It causes TECO-11 to print out the whole line in which the buffer pointer is currently located. The buffer pointer is not moved.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 25

3.6 Text Type-Out Commands

3.6.2 T Command (Type-out)

Any part of the text in the editing buffer can be typed out for examination with the T command. The text typed out depends on the position of the buffer pointer and the argument(s) given. The T command never moves the buffer pointer.

When used with a single argument, T is a line-oriented type-out command; when used with a pair of arguments, T is a character-oriented type-out command. The various T commands are described in the table below.

T Commands _

________

Command Argument Function

T 1 assumed Types out everything from the buffer

pointer through the next line terminator.

If the buffer pointer is at the beginning

of a line, T causes the entire line to be

typed out. If the pointer is in the

middle of a line, T causes that portion of

the line following the pointer to be typed

out.

nT n>0 Types out everything from the buffer

pointer through the nth line terminator

following it. If the pointer is at the

start of a line, nT causes the typing out

of the next n lines (including the current

line).

0T 0 Types out everything from the beginning of

the current line up to the buffer pointer.

This command is especially useful in

determining the current position of the

buffer pointer.

-T -1 assumed Types out everything in the line preceding

the current line, plus everything in the

current line up to the pointer. This

command types only the previous line if

the buffer pointer is at the beginning of

the current line.

nT n<0 Types out everything in the |n| lines

preceding the current line, plus

everything in the current line up to the

buffer pointer.

m,nT m<n Types the m+1st through the nth characters

of the buffer.

HT (H=B,Z) Types out the entire editing buffer.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 26

3.6 Text Type-Out Commands

^YT (^Y=^S+.,.) Used after a command such as:

Iinsert some text....$ ^YT

for printing the text most recently

inserted {3.8} or found in a search

{3.11}. In this example, TECO-11 prints:

insert some text....

This command is particularly useful to

verify an inserted string.

3.6.3 ^O (CTRL/O) Special character (Stop type-out)

During the execution of any T command, the user can stop the terminal output by typing the special command character CTRL/O.

The CTRL/O command causes TECO-11 to finish execution of the command string normally, omitting all further type-outs. This command can only be entered as a control character; the ^O

(uparrow-O) command has a different effect, namely, switching to octal mode {3.15.2.1}.

3.7 Deletion commands

The K and D commands are used to delete characters from the editing buffer. The K command used with a single numeric argument is line-oriented; the D command and the K command used with a pair of numeric arguments are character-oriented.

3.7.1 K Command (Kill lines)

The various forms for the K command precisely parallel those for the T command; at any point, the characters that would be typed out by the T T mmand are those that will be deleted by a K command using the same arguments. See the T command {3.6.2}, and substitute "delete" for "type out".

3.7.2 D Command (Delete characters)

Using the D command, characters can be deleted individually and in short strings. The nD command, where n>0, deletes the n characters immediately following the buffer pointer. If the argument is omitted, 1 is assumed. An argument of 0 does nothing.

The command nD, where n<0, causes the deletion of the n characters immediately preceding the pointer; -D is equivalent to -1D.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 27

3.7 Deletion Commands

After execution of any K or D command, the buffer pointer is positioned between the character that preceded the deletion and the character that followed it.

3.7.3 Examples

Command Result

2K Kills the remainder of the current line and the

next line, up to and including the terminating

line feed.

.,.+5K Deletes 5 characters starting at the current

position of the buffer pointer. This command is

equivalent to:

5D Deletes 5 characters starting at the current

position of the pointer.

-2D Deletes the 2 characters which immediately precede

the pointer.

HK Deletes all characters; clears the editing

buffer.

.,ZK Deletes all characters between the pointer and the

end of the editing buffer.

3.8 Insertion Commands

The insertion commands are used to insert characters into the editing buffer from the user's terminal.

3.8.1 I Command (Insert)

The basic text insertion command is the I command. Its argument is the text to be inserted, followed by a single ESCAPE. The general form is:

Itext$

This command inserts the ASCII string "text" into the editing

buffer just before the buffer pointer. After the insertion, the buffer pointer is positioned immediately following the last character inserted. The ESCAPE terminating the string is not inserted. The text may contain any characters except the special command characters {2.2.1} and the ESCAPE.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 28

3.8 Insertion Commands

3.8.2 TAB (CTRL/I) Command (Insert beginning with TAB)

The TAB (CTRL/I) command is equivalent to the I command, except that the TAB command causes the TAB itself to be inserted as well as the text following it. In other words, if the first character to be inserted is a TAB, the I can be omitted, making it a TAB command.

3.8.3 @I Command (Insert using specified delimiter)

The @I command is slightly more powerful than the I command. It enables the user to insert single (but not two consecutive) ESCAPE characters as well as the characters which can be inserted by an I command. The general form is:

@I`text`

In this form, "text" is the text string to be inserted. The text argument must be delimited both before and after by any single character which is not itself a part of the string to be inserted.

In this example, the delimiting character is the "`" character.

ESCAPE is not required to terminate the text string; the second occurrence of the delimiting character performs this function.

The text is inserted immediately preceding the buffer pointer, as with the I command. The delimiter is not inserted.

3.8.4 nI$ Command (Insert a character)

Any ASCII character can be inserted into the buffer using the nI$ command. This includes all characters that the I and @I commands cannot insert. However, the nI$ command inserts only one character at a time. The command nI$ inserts the character with

ASCII value n immediately before the buffer pointer. This command must be terminated with an ESCAPE. The "$" in this paragraph stands for the ESCAPE character. The value n is decimal unless

TECO has been put into octal mode {3.15}.

3.8.5 n\ Command (Insert a number)

The n\ command, where "\" is the ASCII backslash character, is used to insert the ASCII representation of a decimal or octal number n into the text buffer, depending on the current radix.

For example, assuming there are 3718 characters in the text

buffer, the command Z\ inserts either the string "3718" or the string "7206", depending on whether the current radix is decimal or octal. Note that the argument n does not have to be a number typed by the user; it can be the value of any arithmetic expression (which may involve commands that return a value).

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 29

3.8 Insertion Commands

3.8.6 FR Command (Replace)

The FR command replaces the string last inserted or found in a search (see section 3.11) with the string that is given as a text argument. For example:

IThis as an error$ inserts a string, and

FRThis is an error$ then corrects the obvious error.

Thus, the FR command is equivalent to "^YK" or "^SD" followed by an insert command.

If the new text includes an ESCAPE, the alternate form:

@FR`text` can be used. Here "`" is the delimiting character, as with the @I command {3.8.3}.

3.8.7 Examples

Command Result

Itext!$ Insert the string "text!" immediately before the

current position of the buffer pointer.

@I*text!* Same as above, using the @ modifier and "*" as a

delimiter.

97I$ Insert the character with ASCII value 97, i.e. the

"a" if the current radix is decimal. This command

is useful for inserting characters that cannot be

typed in normally, such as special command

characters or lower case characters at an upper

case terminal.

2*5+3\ Insert the string "13" if the radix is decimal,

and "15" if it is octal. Any arithmetic

expression can be used with this command.

3.9 Output commands

Output commands are used to transfer data from the editing buffer to the output file.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 30

3.9 Output Commands

3.9.1 PW Command (Write a page)

This is the basic output command. It does nothing but output.

The possible arguments and their functions are listed in the table below.

PW Commands __

________

Command Argument Function

PW 1 assumed Outputs the entire buffer, appending a

form feed to it.

nPW n>0 Outputs the entire buffer n times,

appending a form feed to each copy.

m,nPW m<n Outputs the characters between positions m

and n of the editing buffer, without

appending a form feed.

HPW H=B,Z Outputs the entire editing buffer without

appending a form feed.

The PW command neither moves the buffer pointer, nor deletes any text in the editing buffer.

3.9.2 P Command (Advance a page)

The P command is a combination command; used with a single numeric argument, it performs both input and output.

The P command with a pair of (numeric) arguments is equivalent to the PW command with that pair of arguments, i.e. only output is performed; the text in the buffer and the pointer are not changed.

The P command without an argument writes out the contents of the editing buffer, appending a form-feed only when the form-feed flag is set {3.3.1}. The editing buffer is then cleared and a new page is read into it as if a Y command had been issued {3.3.1}. The nP command is equivalent to the P command executed n times, i.e it outputs the current page, copies n-1 pages from the input to the output file and reads in the nth page.

If the editing buffer is empty when a P or PW command is executed, no output is done for that page. To create a blank page, one can

insert a form feed in the buffer, for example with the command

12I$ {3.8.4}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 31

3.9 Output Commands

3.9.3 EF Command (End the output file)

The EF command closes the output file, but does not perform any output by itself. The EF command, or an equivalent command (see below), must be used to close the output file after all output has been done. The EF command is normally used after the P or PW command which outputs the last page of the file. The exit commands EC, EX, and EG {3.10} automatically cause the execution an EF command. Also, an EW command causes an EF to be executed on the previously opened file (if any) before opening the new output file.

Note that if an EF command is used in the middle of the editing of a file, the output file is closed and the remaining pages of the input file cannot be sent to that output file. Another EW command must be issued (if desired) to copy the remaining text into a different file. Since the EF command does not clear the editing buffer, caution should be exercised lest extraneous text be attached to the beginning of the next file that is edited.

3.10 Exit commands

Exit commands are used to terminate editing on a file and sometimes to return control to the RSTS/E monitor. There are four exit commands: EX, EG, EC, and ^C.

3.10.1 EC Command (Close all files)

The EC command is the easiest way to end editing on a file. It performs the following functions:

1) Outputs the page currently in the editing buffer and all

pages following it in the input file to the output file,

appending form feeds only when they are read on input. In

this way, the EC command maintains the existing page sizes.

2) Closes the input and output files.

The editing buffer will be cleared, but the contents of all

Q-registers will be left intact.

3.10.2 EX Command (Exit)

The EX command first performs the same functions as the EC command. Then TECO-11 returns control to the user's private default run-time system (normally BASIC-PLUS), or to the system-wide default run-time system (normally BASIC-PLUS). The new run-time system then prints its customary prompting message, e.g.

"Ready" for BASIC-PLUS or "." for RT-11. (When TECO-11 operates

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 32

3.10 Exit Commands under RSTS/E versions prior to V6B-02, the exit is always to

BASIC-PLUS and "Ready" is always typed.)

3.10.3 EG Command (Exit and go)

The EG command is, in most cases, equivalent to the EX command.

When the output file has one of a certain group of extensions, however, the EG command starts a system program after it has performed all the functions of the EC command.

The extensions recognized, and the corresponding programs initiated by the EG command of TECO-11 at Lawrence, are as follows:

Extension Program started

.BEX XBASIC

.CTL QUE

.FOR FORTRA

.MAC MACRO

.RNO RUNOFF

This list is merely illustrative. Consult the system manager for current information. (When TECO-11 operates under RSTS/E versions prior to V6B-02, the EG command can initiate only the programs

$QUE.BAC, $RUNOFF.BAC, and $MAC.BAC.)

3.10.4 ^C (CTRL/C) Command (Emergency stop)

The CTRL/C command is used to stop a command in the middle of execution. It is most useful in a situation where the user has inadvertently put TECO-11 in an infinite loop by mistyping a command. CTRL/C interrupts whatever TECO-11 is doing at the time it is typed and prints the message:

Re-entering TECO

*

TECO-11 then waits for more command input. The command currently executing is interrupted, but the contents of the editing buffer are retained, and files are left open. Editing may be resumed, but beware of the possible damage caused by the user's error.

Warning: If the user types CTRL/C twice in a row (or rather twice_______ without any intervening delimiter character), TECO-11 will not print out the message "Re-entering TECO", but will exit

immediately to the default run-time system {3.10.2}. This is equivalent to executing the ^C (uparrow-C) command described below.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 33

3.10 Exit Commands

3.10.5 ^C (uparrow-C) Command (Immediate exit)

This command causes an immediate exit from TECO-11 to the default rununime system {3.10.2}. Open files are closed, but the text in the editing buffer is lost because it is not first written to the output file. The same action is performed by two successive

CTRL/Cs (see above).

3.10.6 EK Command (Kill output file)

The EK command closes the output file and kills it. If the file was created with the EB command, the original file is retained and is not renamed. Thus, this command is useful to undo the effect of the editing. For example, if you edit a 10-page file and discover at page 8 that you destroyed page 2, you can use the EK command to cancel the effect of this editing run. Aborting

TECO-11 with ^C has a similar effect in that it does not rename the output and input files for an EB, but it has the undesirable side-effect of leaving a temporary file on the disk and exiting from TECO-11.

3.11 Search commands

In many cases the simplest way to reposition the buffer pointer is to use a character string search. A search command causes TECO-11 to scan through the text until a specified string is found, and then to set the buffer pointer at the end of the string.

The search command uses the string given as a text argument following the command. The maximum length for a search string argument is 64 characters.

If an exact match is found for the search string supplied as a text argument, TECO-11 positions the buffer pointer immediately following the last character in this match. If an exact match is not found, the pointer is moved to the start of the editing buffer

_____ and TECO-11 notifies the user of the failure. This failure notice may take one of two forms, depending on the search command used.

For fufuher explanation, see the paragraphs below.

All searches begin at the current position of the buffer pointer.

If no text argument is provided for a search command (e.g. S$ or

@_``), the argument used for the most recently executed search command is reused.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 34

3.11 Search Commands

3.11.1 S Command (Search)

The S command is used to search for a character string within the current editing buffer. If the string is not found between the position of the buffer pointer and the end of the buffer, the search fails. After an unsuccessful S search, the pointer is reset to the start of the editing buffer and, unless the ":" modifier {3.11.6.2} was used or the search was in an iteration, the error message

?SRH Search failure for "text" is printed, where "text" is the text specified as a search string.

The general form of the S command is:

Sstring$

For the standard S command, the search string is specified as a normal text argument following the S and is terminated with an

ESCAPE. The string can contain any characters except the special command characters mentioned in section 2.2.1. In addition, several characters have special significance when used in search arguments {3.11.8}.

The S command may be used with a single numeric argument. The command

nSstring$ causes a search for the nth occurrence of the string "string".

When n is omitted, 1 is assumed. If n<0, the search is performed in a backwards direction; for example, if n=-1, TECO searches for the first occurrence of the search string at or preceding the current position of the buffer pointer. TECO-11 still searches for the same character string; i.e., the string is not reversed, and the pointer follows the "string" if the search succeeds.

_______

3.11.2 FS Command (also ^R command) (Search with replacement)

The FS command is used to search for a character string within the current editing buffer (i.e. perform the function of the S command) and then replace that string with another. If the string to be replaced is not found, the search fails and no replacement is made.

The general form of the FS command is:

FSstring1$string2$ where 'string1' is the string to search for and 'string2' is the text to replace 'string1'. If 'string2' is omitted, 'string1' is deleted without any replacement. However, even when 'string2' is

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 35

3.11 Search Commands omitted, its terminating ESCAPE must be present.

The FS command can be used with a single numeric argument. For example:

nFSaaa$AAA$

The first n-1 occurrences of the search string 'aaa' are left unchanged, and only the nth occurrence is replaced by the string given as the second d gument, in this case 'AAA'.

The ^R command is synonymous with the FS command.

3.11.3 N Command (Non-stop search)

The N command combines the S command with input-output functions.

The N command is used to search for a character string that may lie in a page of the input file which has not yet been read into the editing buffer. The N command has the same form as the S command.

The N command functions in exactly the same way as the S command, except that it does not stop at the end of the editing buffer. If no match has been found when the end of the editing buffer is reached, the current page is written out to the output file, the editing buffer is cleared, and a new page is read in (i.e. a P command {3.9.2} is simulated). If there are no more pages in the input file, the search fails. Otherwise, the search continues at the start of the newly filled editing buffer.

If the N command fails, the entire input file has been copied to the output file, the editing buffer is empty, and the end-of-file flag is set. The output file has not been closed. Unless the ":" modifier {3.11.6.2} was used or the search was in an iteration, an error message informs the user about the search failure.

An N search command will not find a string that is split by a page boundary.

When the N command performs output, it appends a form feed to the editing buffer only when one has been read on input (i.e. when the form-feed flag {3.3.1} is set).

The N command can be used with a single numeric argument as can the S command.

3.11.4 FN Command (Non-stop search with replacement)

The FN command is related to the N command in the same way that the FS command is related to the S command. It uses two text arguments. The first one represents a search string; the second

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 36

3.11 Search Commands one is the replacement when a match is found.

3.11.5 _ (underscore or backarrow) Command (Destructive search)

___________

The backarrow command is similar to the N command except that the backarrow search generates no output. Both commands start searching in the current editing buffer. If the search fails, the

N command writes out the current page of text before yanking in a new page, whereas the backarrow command simply deletes the current page of text and yanks in a new one. This command is called

'destructive', because if the string is not found within the current buffer, a new page is read in without writing out the current one, thus destroying the data in the buffer. This command should therefore be used with caution, since it can wipe out a large part of a file when used carelessly.

The backarrow command, like the N and S commands, can also be used with a single numeric argument specifying repetition.

3.11.6 Search modifiers

There are two search modifiers, the @ symbol and the colon. Both the @ and : modifiers can be used on a single search command, in either order.

3.11.6.1 @ Modifier (Specify non-standard delimiter)

The @ modifier is used to change the way in which TECO-11 reads the search argument from the command string. When the @ modifier is used, TECO-11 does not use the ESCAPE as a delimiter, but instead uses the same delimiter rule as the @I command {3.8.3}.

Example:

@S`text` and

Stext$ are equivalent.

The @ modifier is useful when searching for a string which contains an ESCAPE.

The @ modifier not only is applicable to search operations, but also can be used with most commands that take one or two string arguments. If there are two arguments, a single delimiter character is used between the strings, and another delimiter

character follows the second string. Example:

@FN`oldtext`newtext` replaces "oldtext" with "newtext".

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 37

3.11 Search Commands

3.11.6.2 : Modifier (Return success or failure)

The colon modifier is used to change the function of a search command if the search fails. Without the colon modifier, a search that fails causes a message to be printed out. With a colon modifier, no message is printed; instead, the search command is made into a command which returns a value that can be printed out, stored in a Q-register, or tested by a conditional branch. If the search is successful, the value -1 is returned; otherwise, the value 0 is returned. If a colon search is not followed by a command that takes a numeric argument, the value returned will be discarded.

The general form of a "colon-search" is:

:nStext$ where S can be replaced by N or _ (or by ^R, FS, or FN with two argument strings).

3.11.6.3 :: Modifier (Compare)

The :: (double colon) modifier converts the following search into a compare operation. 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 that the next command can pick up as its numeric argument. If the characters in the buffer do not match the search string, the pointer is not moved and the command returns a value of 0. This modifier may be used with the @ modifier.

Warning: Do not use a numeric argument with an anchored search;_______ such searches fail (return zero).

3.11.7 ES Command (Automatic typeout after searches)

The ES command allows the user to specify automatic typeout of the line where a successful search has terminated. It does not apply to search commands in iteration brackets, nor to colon-modified search commands. When an FN or FS command is used, the typeout takes place after the replacement has been performed. The user can also specify that a line-feed or other character be inserted in the typeout (not in the text in the editing buffer) to indicate the position of the pointer. The default is no automatic typeout.

The user can set the ES value in the following manner:

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 38

3.11 Search Commands

ES Commands __

________

Command Result

0ES Disable automatic typeout (the default setting).

-1ES Cause automatic typeout of the line in which the

pointer is positioned after a successful search

that was not in an iteration and not a

colon-search.

nES (n>0) Set the ES value to n. If n is in the range 1 to

31, a single LF character is inserted in the

typeout at the position of the pointer. When n is

greater than 31, the character with the ASCII

value n is inserted instead.

ES ES without argument returns the setting of the ES

flag.

3.11.8 Special control characters as search arguments

A number of special control characters can be used in a search string. These characters alter the character-match process that is performed when the search is done. They are inserted in the search argument string.

Since these control characters occur in the middle of a text argument, they cannot be written as uparrow-characters; they must be typed in as single control characters. Note: If ^S and ^Q are

____ typed at a scope terminal, they are ordinarily intercepted by

RSTS/E and not passed to TECO-11. One must either insert them into a macro search command (with nI$) or disable the special handling of these characters by running the TTYSET utility program (refer to RSTS/E System User's Guide).

The presence of a ^X indicates that any character is to be be accepted in that position. The ^X is the "wild card" in a character search.

The ^S character indicates that any separator character, i.e. any character except a letter (upper or lower case) or a digit, is to

______ be accepted in this position.

The ^N character must be followed by a single character. It indicates that any character, except the one following it, is to

______ be accepted as a match. The ^N can be followed by the ^S character, in which case any letter or digit (i.e. any non-separator character) will match.

The ^Q (quote) character is used to search for a character that has a special meaning in search strings. When preceded by a ^Q character, TECO-11 ignores the special meaning and searches for

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 39

3.11 Search Commands the character literally. This also applies to the ESCAPE character.

The ^E has a function that depends on the argument that follows it. The function of the various possible arguments is given below.

^EA Matches any alphabetic character (lower case or upper

case).

^ED Matches any digit.

^EL Matches a line feed, form feed, or vertical tab character.

^ES Matches one or more spaces and/or TAB characters.

^EX Matches any character (equivalent to ^X)

^EQq Copies the text in Q-register q into the search string

buffer. If the text in the Q-register contains another

^EQ, that one is not recognized as a special character

(i.e. nesting is not possible).

Note that the character following ^E must be in upper case.____

____

3.11.9 Examples

Command Result

2Stext$ Search for the second occurrence of the string

"text" starting at the current position of the

buffer pointer.

@N/xx/ Search for the first occurrence of "xx" following

the buffer pointer. If the string is not found in

the current buffer, the whole editing buffer is

written out to the output file, and a new page is

read in. The search then continues at the start

of the new page. The search stops when either the

string is found or the end of file is encountered

on the read operation from the input file.

-S^EA^X241^NX$ Search for the first occurrence preceding the

pointer of the following (preceding the pointer

because the search is backward):

Any alphabetic character, followed by any

character, followed by the string "241", followed

by any character except "X".

For example, if the pointer were at the end of the

editing buffer and the buffer contained the text:

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 40

3.11 Search Commands

*P241a xx" a*241P PQ p?241X hhgdhhgahh

the search would be successful and the pointer

would be set after the string "a*241P".

::SXX$ Return -1 if the next two characters are "XX", and

0 otherwise. If the string is found, the pointer

is set as usual. Otherwise, it is not moved.

3.12 Iteration commands

TECO-11 provides three general features for "automating" highly repetitive editing operations: iteration commands, flow control commands {3.13}, and macros {3.14.2.3}.

3.12.1 Iteration brackets (<...>)

The user can cause a group of commands to be executed repeatedly

(iterated) any number of times by enclosing the command string in angle brackets. The left angle bracket marks the beginning of the loop, the right angle bracket marks the end. Iteration brackets can be nested to a level of about 15. If the limit is exceeded, the error message

?PDO Push-down list overflow is printed and execution of the command string stops. A numeric argument can be used with iteration brackets to specify the number of iterations. The argument must precede the opening left angle bracket. If no argument is given or the argument is less than or equal to zero, the number of iterations is assumed to be

"infinite" (that is, 65536).

3.12.2 ; Command (Conditional exit from iteration)

The ; command is used to exit conditionally from an iteration loop. This command can be used only inside an iteration.

Normally, the semicolon command is used with a single numeric argument. In that case, the iteration continues (as if the semicolon had not been there) if the argument is less than zero.

Otherwise, the iteration loop is exited. This is done by

searching for the matching closing angle bracket, and continuing by executing the first command to the right of it. As a result, the ; command causes an exit only from the deepest level of the iteration; if there is nesting, the outer levels continue to be iterated.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 41

3.12 Iteration Commands

The semicolon can be used without a numeric argument only when it follows a search command. In that case the effect is as if the search had been a colon-modified search {3.11.6.2}. If the search is successful, execution continues. If it fails, the iteration is exited. If a search within an iteration fails, TECO-11 does not print out the regular error message. Instead it checks whether a

; command follows the search. If this is not the case, it prints out a warning message:

Search fail in iter and continues as if there had been a ; command, i.e. the current level of iteration is exited.

3.12.3 Examples

<P<FSx$y$;>^N^_;>

This command first reads in a page from the input file, writing out the editing buffer to the output file {3.9.2}. It then replaces every occurrence of "x" by "y" in the inner iteration loop {3.11.2}. When the search fails, the inner iteration is terminated by the ; command and the ^N^_; command is executed

{3.16}. The latter causes an exit from the outer loop if the end-of-file has been found on the input file.

Y< NExamples:$ ; < S<CR>

$; 9I$ L> >$$

In this example of nested loops, the outer loop searches for pages in a file that contain the heading "Examples:". Each time this heading is found, execution enters the inner loop, where a tab

(ASCII decimal 9) is inserted at the beginning of all succeeding lines on that page, i.e., after every CR-LF combination (remember that TECO-11 appends a line feed to each carriage return character that is typed). The second semicolon causes an exit from the inner loop when the S search fails (at the end of each page). The first semicolon causes an exit from the entire command string when the N search fails (at the end of the file).

Caution: Only the methods described in this section should be_______ used to exit from a loop. Specifically, the flow control commands

{3.13} should not be used to move out of, or into, the range of an

___ iteration loop. This restriction parallels the situation with DO loops in FORTRAN or FOR/NEXT loops in BASIC.

3.13 Flow control commands

TECO-11 contains commands to enable the user to write editing programs capable of solving even the most complex editing

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 42

3.13 Flow Control Commands problems. The iteration commands discussed in section 3.12 are a specialized example. In addition to these, TECO-11 has an unconditional branch command and a set of conditional execution commands that can be used to create any kind of conditional branch, execution, or skip.

3.13.1 Command string tags ("Labels")

To have branching in a commmand string, there must be some way of naming locations in the command string. Location tags have the general form:

!tag!

They may be placed anywhere in a command string except in text arguments. A tag is delimited before and after by an exclamation point and may contain any number of ASCII characters except the exclamation point, the ESCAPE, and the special command characters

{2.2.1}.

Tags are ignored except when an O command forces TECO-11 to scan for one.

Command tags can also be used to insert comments in TECO-11 command strings. This feature is especially useful in TECO-11 macros {3.14.2.3}.

3.13.2 O Command (Goto)

The unconditional branch command is the O command. The general form is:

Otag$

The text argument following the O command and delimited by the

ESCAPE is the tag naming the destination of the branch. The tag location itself may be either before or after the O command in the command string. The O command causes the command string pointer to be moved to the position following the tag, and execution continues from that point. Note that although the O command uses a text argument, it cannot be used with the @ modifier {3.11.6.1}.

Hence the ESCAPE is not a valid character in a tag.

3.13.3 Conditional execution commands ("If ... Then")

All conditional execution commands have the general form:

n"x...'

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 43

3.13 Flow Control Commands

In this form, n is the numeric argument on which the decision to execute or not to execute (that is the question) is based. The quotation mark is the first character of all conditional execution commands. The letter x represents the second character of the conditional execution command and determines the condition to be tested. The two command characters "x may be followed by any command string, terminated by a ' character. If the number n satisfies the condition represented by x, all commands between the

"x and the ' are executed. If the condition is not satisfied, execution continues at the command immediately following the ' character.

The commands "x and ' must be used in matched pairs and can be nested in the same manner that parentheses in arithmetic expressions can be nested. Each " or ' clears any preceding number or returned value.

The individual conditional execution commands are shown in the table below.

Conditional Execution Commands

___________ _________ ________

Command Function

n"G Execute the commands that follow if n>0; otherwise,

skip to the matching ' on the right.

n"L Execute the commands that follow if n<0; otherwise

skip.

n"E Execute the commands that follow if n=0; otherwise

skip.

n"N Execute the commands that folows if n<>0; otherwise

skip.

n"C Execute the commands that follow if n is the ASCII

value of one of the characters A-Z, a-z, 0-9, $, or

"." (i.e., a character that could be converted to

radix-50 format); otherwise skip.

n"R Execute the commands that follow if n is the ASCII

value of an alphanumeric character (A-Z, a-z, or 0-9);

otherwise skip.

n"D Execute the commands that follow if n is the ASCII

value of a digit (if it is between decimal 48 and 57);

otherwise skip.

n"A Execute the commands that follow if n is the ASCII

value of a letter (upper or lower case); otherwise

skip.

n"T Execute the commands that follow if n is "true" (flag

is on), i.e. if n<0 (equivalent to n"L)

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 44

3.13 Flow Control Commands

n"F Execute the commands that follow if n is "false" (flag

is off), i.e. if n=0

n"S Execute the commands that follow if n is "successful",

i.e. if n<0. Usually used after a colon-search.

n"U Execute the commands that follow if n is

"unsuccessful", i.e. if n=0.

Warning: In general, the ^_ binary complement operator {3.16}_______ following n would not invert the function of these conditional

___ execution commands, i.e., n^_"R does not test for non-alphanumeric

___ characters. Only ':' modified search flags {3.11.6.2} or special internal flags {3.16} that are known to be either -1 or 0 have binary complements that will give reliable results with conditional execution commands. Hence ^_ should never be used in

_____ front of "C, "R, "D, or "A.

Example:

::Sand$"SI text$' If the next 3 characters are "and",

the string " text" is inserted after

them. Otherwise, nothing happens.

3.14 Q-register commands

Q-Registers, which are among the most powerful features of

TECO-11, have many different uses. The general concept of a

Q-register has been explained in section 2.8. This present section explains the TECO commands that manipulate Q-registers.

The 36 numeric Q-registers and the 36 text Q-registers both have the single-character names A-Z (or equivalently a-z) and 0-9. In this section, the letter q will be used to represent an arbitrary

Q-register name.

3.14.1 Commands that operate on numeric Q-registers

The following commands are used to manipulate data in numeric

Q-registers.

3.14.1.1 U Command (Store in numeric Q-register)

The command nUq stores the integer n in Q-register q, where n may be any numeric value {2.7.2-3, 3.4, 3.14.1.2-3, 3.16}. Any number previously stored in the numeric Q-register q is destroyed.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 45

3.14 Q-Register Commands

3.14.1.2 Q Command (Retrieve from numeric Q-register)

The command Qq returns the value currently in numeric Q-register q

(without altering it). In order to be useful, Qq must be followed by a command which requires a value, such as a conditional command.

3.14.1.3 % Command (Increment numeric Q-register)

The command n%q adds n to the number stored in numeric Q-register q, and then "returns" the new value in the same manner as the Q command. If no argument is given, 1 is assumed; n may be either positive or negative. If the user is not interested in the new value in the Q-register, he should type an ESCAPE after the %q command (as explained in section 2.7.3).

3.14.2 Commands that operate on text Q-registers

The following commands are available to store and retrieve character strings of any length in a text Q-register (limited, of course, by the finite size of the available memory).

3.14.2.1 X Command (Load text Q-register)

The X command copies characters from the editing buffer into a

Q-register. The editing buffer is not changed by this operation.

Any data previously stored in the particular Q-register is lost.

The X command has the form:

m,nXq or nXq

Both forms store data in text Q-register q. The argument n or m,n is used in the same manner as with the K and T commands; whatever would be typed out by a T command {3.6.2} is inserted into the

Q-register by an X command with the same argument.

If necessary, TECO-11 will expand its core area to execute the X command. If that happens, a message of the form [7K memory] is printed.

3.14.2.2 G Command (Get text Q-register)

The command Gq copies the contents of text Q-register q into the

editing buffer immediately preceding the current position of the buffer pointer. The contents of the Q-register are not changed, but memory expansion may occur.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 46

3.14 Q-Register Commands

3.14.2.3 M Command (Execute macro)

Since TECO-11 command strings are merely text strings, they can be inserted into the editing buffer just like any other string. When a command string is in the editing buffer, TECO-11 cannot execute it, since at this point it is merely data. However, if the string has been stored in a text Q-register by an X command {3.14.2.1},

^U command {3.14.2.4}, or * command {3.14.3}, then the command string can be executed as a "macro".

The command Mq executes the command in Q-register q just as if it had been typed in as a command string. Using Mq is analogous to calling a subroutine. Any TECO-11 command may be included in the command string to be executed. The command string may include other Mq commands; i.e. macro calls may be nested or even recursive. The only requirement is that the text in a Q-register must be a complete command, i.e. the action of an Mq command is not identical to that of inserting the text of the Q-register in___ place of the Mq command and continuing. In other words, all text arguments must be properly terminated, all iteration brackets, parentheses, and conditional execution commands must be properly nested, and tags used with O commands must be present in the macro itself.

3.14.2.4 ^U Command (Insert text into Q-register)

The uparrow-U command (not CTRL/U, which is a special command character) is used to insert text directly into a text Q-register

(independent of any text in the editing buffer). The general form is as follows:

^Uqtext$ or, using the @ modifier as with a search or insertion:

@^Uq`text`

(where ` stands for any delimiter).

This ^U command places in Q-register q the text given as the text argument. The previous contents of the Q-register are lost. The pointer is not moved and the editing buffer is not changed. The alternative form @^U is useful if the text to be inserted has an

ESCAPE in it.

To release memory space when the previous contents of a text

Q-register are no longer needed, use the command ^Uq$ with a null string.

For examples of the use of Q-register commands, refer to section

5.1.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 47

3.14 Q-Register Commands

3.14.3 * Command (Save the previous command string)

After completion of the execution of a command string, after termination because of an error, or after typing ^G^G (two

CTRL/Gs), the command string just typed can be stored in a

Q-register. This is done by typing the command *q as the very first command. Typing anything at all, even if it was rubbed out, will destroy this unique chance. When the * command succeeds,

TECO-11 responds immediately by typing another asterisk.

The *q command is particularly useful if an error occurs in a long command string. The error can then be corrected by using the *q command, inserting the Q-register some place in the editing buffer, correcting the error, copying the command string back into a Q-register, deleting it from the editing buffer, and executing the string as a macro.

3.15 Numeric type-out and radix changing commands

3.15.1 = and == Commands (Numeric type-out commands)

The numeric typeout command is n=, where the value n to be typed out can be an expression of any form. The number is typed out in decimal radix; if the current radix is octal (because of an ^O command) it is reset to decimal.

The command n== (a double equal sign) prints out the value of n in octal, and also changes the current radix to octal.

3.15.2 Radix and radix changes

At any gives time, TECO-11 is said to be either in octal or in decimal radix because it interprets numbers typed as numeric arguments as, respectively, octal or decimal numbers. For example, if TECO-11 is in octal radix, the argument 1003 is interpreted as what is normally written in decimal as 515.

For setting the radix, there are two commands available in addition to the commands mentioned above, whose side-effect is to set the radix.

3.15.2.1 ^O Command (Set octal mode)

This command must be entered as uparrow-O, since CTRL/O is a special command character {2.2.1}. It sets the current radix to octal. Digits 8 and 9 are illegal in octal mode.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 48

3.15 Numeric Type-Out

3.15.2.2 ^D Command (Set decimal mode)

This command sets the current radix to decimal. When TECO-11 is started, the radix is initially set to decimal.

3.16 Special numeric values

Several TECO-11 commands whose function is to return some particular numeric value have already been discussed. These commands are B, Z, . (period) and Qq. Other commands execute a function while returning a numeric value, such as %q and colon searches. The concept of a command returning a value has been explained in section 2.7.3.

Any command that returns a value can be used (within arithmetic

_______ expressions if needed) as the numeric argument for any command that requires a numeric argument. For example, the command Z=

________ causes TECO-11 to type out the number of characters currently in the editing buffer.

There are several additional commands that return values; their functions are listed below. nA The nA command (where n can be any numeric argument)

returns the ASCII value of the character immediately to

the right of the buffer position designated by '.+n'. For

example, 0A returns the ASCII value of the character

immediately to the right of the pointer. This command is

quite useful together with the n"D, n"A, and n"C forms of

the conditional execution command.

^E The ^E command returns the value of the form feed flag.

If the last input command (Y, A, P, N, _, etc.) was

terminated because a form feed character was encountered,

^E returns -1; otherwise, it returns 0 {3.3.1}.

^N The ^N command returns the end-of-file flag. If the end

of file was encountered on the last input command, the ^N

flag is set to -1; it will remain -1 until cleared by the

opening of a new input file by an ER or EB command.

Otherwise, it is set to 0. This command is useful to test

whether the latest page read is the last page in the file.

For example, after opening a file, you can copy all pages

except the last into the output file and leave the last

page in the editing buffer with the command:

<^N^_;P> (for the ^_ command, see below)

^F The ^F command returns the value of the console switches.

^H The ^H command returns the time of day, in minutes before

midnight.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 49

3.16 Special Numeric Values

^B The ^B command returns the date (as a Julian date, e.g.

4359 designates 25-Dec-74).

EH The EH command returns the value of the error message flag

{4.2}.

ES The ES command (without numeric argument) returns the

value of the automatic typeout flag {3.11.7}.

^^x The ^^ command (which can be typed as two uparrows or

CTRL/uparrow, or as CTRL/SHIFT/N on a Teletype), followed

by an arbitrary character 'x', returns the ASCII value of

that character. The character 'x' cannot be one of the

special command characters {2.2.1}.

\ The \ (backslash) command without a numeric argument

returns the value of the digit string (optionally preceded

by a + or - sign) in the editing buffer immediately

following the buffer pointer, interpreted in the current

radix (octal or decimal). The command is terminated by the

first character that is not a valid digit in the current

radix. If there is no number following the buffer

pointer, the value returned is 0. The \ command moves the

buffer pointer to the end of the digit string, if any is

found; unlike searches, it does not set the value of ^S.

___ n^_ The ^_ (uparrow-underscore or CTRL/underscore, typed on

some terminals as CTRL/SHIFT/O) uses a single numeric

argument preceding it. It returns the binary complement

of the value; if the argument has the value n, the value

returned is -n-1. This command is useful to complement the

value of flags such as the end-of-file flag (refer to the

discussion of the end-of-file flag above).

^T The ^T command is used to enable type-in of characters

while the command string is being executed. When the ^T

command is encountered in a command string, execution of

the command string is suspended and TECO-11 waits for the

user to type any single character. This character is

echoed in the usual manner. (Note that the

carriage-return character causes the two characters CR and

LF to be entered in the keyboard buffer; these are

retrieved by two successive ^T commands.) When a character

is typed, the ^T command returns the ASCII value of the

character and execution of the command string resumes.

Hence the ^T command is useful only as an argument for a

command that takes a numeric argument. For example, the

command string '^TU1' loads the ASCII value of the

character typed into numeric Q-register 1. When waiting

for the character for a ^T command, TECO-11 does not type

out any prompting character. Whenever a prompt is needed,

the user should supply one himself using the ^A command

{3.17}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 50

3.16 Special Numeric Values

^V The ^V command returns the version number of TECO-11. This

manual applies to version 17.

^S The ^S command returns the negative of the length of the

last search string or the last insertion (whether by an I

command {3.8.1}, a TAB command {3.8.2}, or a G command

{3.14.2.2}). It can be used to set the pointer to the

start of an inserted string or a search string. For

example:

Stext$^SC

searches for "text" and positions the pointer before the

first "t". See also the FR command {3.8.6} and the ^Y

special numeric argument {3.4}. Note that the '\' command

does not set the value of ^S. ___

^Z The ^Z command returns the total number of characters

currently stored in all the text Q-registers. Since the

command string buffer is treated as a special

(inaccessible) Q-register, this value includes the length

of the current command string.

3.17 TECO-11 programming aids

Bugs can (and will) occur in command strings and macros, as in any other program; therefore TECO-11 provides the following debugging aids for the user.

3.17.1 ^A Command (Text type-out)

The user can cause a string to be typed out at any point in a command string. The ^A command, which is used to perform this function, has the general form:

^Atext^A

The first ^A is the actual command. It can be entered in uparrow or control-character form. The string "text" is the string that

TECO-11 types out when it encounters the command. The second ^A terminates the string, and can only be entered as a control character. The text can contain any characters except the special command characters {2.2.1} and the ^A character.

Note that the string is typed out exactly as entered; no carriage-return is appended by TECO-11. If the user desires a carriage return after the text, the carriage return must be entered along with the text before the terminating ^A.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 51

3.17 Programming Aids

3.17.2 ? Command (Tracing)

The ? command has two uses in TECO-11. When entered as the first character after TECO-11 has printed out an error message, it has the special function described in section 4.2. However, at any other time the question mark can be entered into a command string exactly like other commands. This use of the ? command causes

TECO-11 to enter trace mode. In trace mode, TECO-11 types out each command as it is executed. A second ? takes TECO-11 out of trace mode.

3.18 Ignored characters in command strings

Except as text arguments, the characters carriage return, line feed, form feed, vertical tab, and space have no meaning in command strings and are ignored. They can be used to make long command strings easier to read, or to conveniently enter command strings much longer than a single line.

4 USER ERRORS and ERROR RECOVERY ____ ______ ___ _____ ________

This chapter describes two types of errors:

1) Typing errors discovered by the user before a command string

is completed; and

2) Command errors detected by TECO-11.

The user should realize, however, that there is a third type of error. Because TECO-11 interprets almost every character as a command, there can be cases where, if the user fails to notice a typing error, TECO-11 executes a command the user did not intend.

For example, if the user intended to type:

INAME$$ but omitted the "I", then TECO-11 is forced to interpret the command as an N-search for "AME" and act accordingly {3.11.3}. The user must vigilantly avoid typing "Y", "K", "D", and "_" by mistake, for they are destructive commands. There is no way to

_____ __ __ ___ __

protect the user from errors of this type._______ ___ ____ ____ ______ __

____ ____

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 52

4.1 Erasing Commands

4.1 Erasing commands

If the user makes an error while typing a command string and discovers the error before terminating the command string with a double ESCAPE, the error can be corrected using one of the erasing commands below. All of these must be typed in before the double

ESCAPE that terminates the command string.

4.1.1 RUBOUT Command (Cancel a character)

RUBOUT is used to erase typed-in characters one at a time starting with the last character typed in. It functions in essentially the same way as during normal RSTS/E operation, with one difference.

Normally RSTS/E echoes the character rubbed out, enclosing them in backslashes. TECO-11 echoes the characters too, but leaves out the backslashes. A line typed in to RSTS/E as:

abceRUBOUTdegRUBOUTfghjklRUBOUTRUBOUTRUBOUTijkl will be echoed as:

abce\e\deg\g\fghjkl\lkj\ijkl whereas the same line types in to TECO-11 will be echoed as:

abceedeggfghjkllkjijkl

Obviously, using many RUBOUTs on a single line can be very confusing; for a solution, see section 4.1.4.

4.1.2 ^U (CTRL/U) Command (Cancel line)

The ^U command must be entered as a control character because uparrow-U has a different meaning; it erases the command line back to the last typed line feed. (Note that a carriage return is stored as the CR-LF combination.) The delimiter is not erased.

The ^U is echoed as ^U CR LF. This command behaves in almost the same way as with RSTS/E. However, ESCAPE, carriage return, and form feed do not act as line delimiters.

4.1.3 ^G^G (double bell) Command (Cancel entire command string)

The command ^G^G (two successive CTRL/Gs) is used to erase the

entire command string. TECO-11 discards all of the command string previously typed in and responds with an asterisk.

This command is useful in case an error is discovered in a long command string many lines back. The command string can then be saved in a Q-register with an immediate *q command {3.14.3}. The

_________

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 53

4.1 Erasing Commands faulty command can then be inserted into the editing buffer, corrected, reinserted in the Q-register, and executed as a macro

{3.14.2.3}.

4.1.4 ^Gspace (bell space) Command (Retype line)

The bell-space command is not an actual erasing command, in that it does not delete any characters. It is commonly used together with the RUBOUT command, and causes the current command line to be retyped. For the example of section 5.1.1, a clear view of what is left can be obtained by typing CTRL/G, immediately followed by a space. The result would look like:

abceedeggfghjkllkjijkl^G

abcdefghijkl where the first line was entered by the user (with rubouts) and the second line was typed by TECO-11.

4.2 Error messages

When TECO-11 encounters an illegal command or a command that cannot be executed, an error message is printed on the user's terminal. An error message has two parts. The first part consists of a question mark followed by a 3-character mnemonic code. The second part is a one-line error message which indicates the error mode clearly. For example, if the user typed the command:

Stexts$$ but the string "texts" cannot be found following the buffer pointer, the message printed out consists of:

?SRH (the mnemonic code for "Search failure") and

Search failure for "texts" (the full error message)

Normally TECO-11 prints both parts of the error message on a single line. The user can use the EH command {4.2.2} to cause

TECO-11 to print out only the mnemonic code, or to print the full error message plus a "command trace-back", which is a type-out of the command string up to and including the point where the error occurred.

When an error occurs, the command that caused the error and any commands following it are not executed, and TECO-11 returns to command mode, typing an asterisk to indicate its readiness for a new command.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 54

4.2 Error Messages

After an error has occurred, the user has available the special command ?. It has a special meaning only when typed immediately

____ after the asterisk TECO-11 prints out after an error. If any other character is typed, the ability to use the ? command with its special meaning is lost.

4.2.1 ? Command (Print traceback)

In some cases, the user may not be able to determine immediately where in the command string the error occurred. This could occur, for example, if several commands of the same type were entered in the same command string. In such a case, the user can use the ? command to obtain more information. The ? command, when used immediately after an error message printout, causes TECO-11 to print out the complete command string up to the end of the command that caused the error, followed by a question mark. Note that when a question mark is used in this manner, no delimiting character (i.e. ESCAPE or such) is needed.

This use of the question mark is not to be confused with the use explained in section 3.17.

4.2.2 EH Command (Help flag)

As was stated above, TECO-11 error messages consist of two parts.

The first, or code, part is always printed out automatically. By default the second part is also automatically printed.

The EH command can change this default. In addition, the

"trace-back" that is normally a result of the ? command {4.2.1} can be printed out automatically with the error message. This is done as follows:

EH Commands __

________

Command Result

1EH Sets TECO-11 so that only the code part is typed

out when an error occurs.

3EH Sets TECO-11 to automatically type out the command

trace-back.

0EH or Resets TECO-11 to the default setting, i.e. full

2EH error message, and no trace-back.

EH When used without argument, returns the current

value of the error message flag (the default

setting is 0).

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 55

4.3 Error Recovery

4.3 Recovery from output device errors

It is possible for other users of the RSTS/E system to tie up so much space on the device where TECO-11 is writing its output file that a long file cannot be processed. If this happens during execution of a P, PW, N, EC, EG, or EX command, TECO-11 prints the message

?ERR No room for user on device

The user should immediately issue an EF command {3.9.3} to close

___________ the output file (and to rename files if EB {3.2.3} or TECO {3.1.3} commands were used).

Warning: Do not repeat the command that failed, lest further_______ damage be caused to the text being edited.

At this point, some unknown portion of the text from the editing buffer will have been sent to the output file. In later recovery operations, it will be necessary to recognize and remove this partial "page" in the file just closed; therefore, the user should type out several lines from the beginning of the current editing buffer for identification. The original input file

(possibly renamed .BAK) is still intact.

Subsequent recovery, after adequate output space has been assured, should follow the procedure for merging portions of two files outlined in section 5.2.2. It is for this purpose that knowledge about the area of overlap between the two files is essential.

4.4 Recovery from failure to specify BASIC-PLUS mode

Failure to specify BASIC-PLUS mode {2.1.2} is usually obvious, since line-oriented commands in TECO-11 will behave strangely when they encounter BASIC-PLUS continuation lines ending with <LF><CR> instead of <CR><LF>. When this error is discovered, give an immediate EC command {3.10.1} and then attempt the following two-pass strategy for recovery:

*HK$$ Ensure that the editing buffer is empty.

*ERBAD.BAS/$$ Read corrupted file with BASIC-PLUS mode.

____

*EWFIX.TMP$$ Write a file without BASIC-PLUS mode.

_______

*Nxxxxxxx$$ Search for non-existent text to copy file.

*EC$$ Close files.

*ERFIX.TMP$$ Read the file without BASIC-PLUS mode.

_______

*EWGOOD.BAS/$$ Write repaired file with BASIC-PLUS mode.

____

*Nxxxxxxx$$ Search for non-existent text to copy file.

*EX$$ Close files and exit.

Ready

OLD GOOD Check for errors with BASIC-PLUS compiler.

Ready

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 56

5 Examples and Advanced Techniques

5 EXAMPLES and ADVANCED TECHNIQUES _____________________________

This section illustrates the versatility of TECO-11 and outlines numerous techniques that the user can adapt to his own particular applications. These examples do not pretend to be complete, however. The reader is expected to be able to extract the essence of each method and to fill in for himself such necessary details as attaching input or output files, filling or emptying the editing buffer, and verifying the pointer position adequately.

Furthermore, the illustrations will be kept as brief as possible, even at the risk of apparent triviality.

Several elementary illustrations are discussed in the TECO

Introductory Manual (CC Publication No. EDU-510).

5.1 Some uses of Q-registers

Q-registers in TECO-11 are like variables in a programming language; with the two types of Q-register, one can store and retrieve text passages {3.14.2} or numbers {3.14.1}.

5.1.1 Back-up for the editing buffer

It is all too easy to clobber the editing buffer unintentionally.

Even experienced users may occasionally "experiment" with the formulation of a tricky command string or macro. Such experimentation must sometimes be done while valuable text sits in the editing buffer.

The command "HXB" copies the entire editing buffer into Q-register

B, provided TECO-11 has enough memory space. If the editing buffer subsequently becomes hopelessly damaged, the command "HKGB" will kill the defective buffer contents and restore the text that had been saved in Q-register B. When working with a multi-page file, however, the back-up register should be reloaded each time that TECO-11 empties and refills the buffer as a result of A, N,

P, or Y commands.

5.1.2 Moving a few lines

Q-registers may be used to move several lines from one place to another in the editing buffer. For example, one may wish to find two misplaced lines and relocate them, as in this schematic illustration:

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 57

5.1 Using Q-registers

*HT$$

This is line 1

This is line 3

This is line 4

This is line 2

This is line 5

*J Sline 3$ 0L 2XH 2K Sline 2$ L GH HT$$

This is line 1

This is line 2

This is line 3

This is line 4

This is line 5

*

The command string directs TECO-11 to search for "line 3", go back to the beginning of that line, copy two lines into Q-register H, kill those two lines, go to the point just after "line 2", insert the two lines previously stored, and retype the entire buffer.

Spaces have been inserted in the command string for legibility;

TECO-11 ignores such spaces {3.18}, but not the spaces within

___ search arguments.

A similar illustration involving movement of larger blocks of text and requiring more than one pass through a file is given in section 5.2.3.

5.1.3 Typing a located passage of unknown length

The V command will display the current line, while the HT command will type out the entire editing buffer. An intermediate situation arises when one wishes to type a block of text in the middle of the buffer, but one does not know its precise location or length. A numeric Q-register can be used to store the starting location. Then the desired passage can be typed out with the m,nT command when the ending location has also been found:

*Sfirst line$ 0L .U8 Slast line$ L Q8,.T$$

5.2 Manipulating files

TECO-11 works with only one input file and one output file at a time. Nevertheless, Q-registers make it possible to retain large blocks of text (limited only by the maximum memory available) from

one file to be merged into another file or inserted at a later point in the same file. The general techniques are illustrated in the following exmples, where it is assumed that the files have already been broken into pages of moderate size.

If there is too much text on one page of a file, then position the pointer just past a portion of text that would make a nice page

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 58

5.2 Manipulating Files and move it out with the command string "12I$B,.PWB,.K", which will append a form feed to the text, write it out, and then delete that text from the editing buffer.

5.2.1 Dividing a file in one pass

It is sometimes desirable to divide long files into shorter ones.

A simple division into two files will be outlined in this section, but the technique can be extended to further subdivision, to exclusion of portions of the input file, or to rearrangements of blocks of text in the file {5.2.3}.

Assume that the file "PROG.ALL" is known to contain a line with the word "END" immediately followed by a carriage return. Further assume that all the text up to and including that line is to go into the new file "PROG.PT1", and all the text following that line into the new file "PROG.PT2". The following dialog illustrates the method:

*ERPROG.ALL$EWPROG.PT1$$ Input file is PROG.ALL {3.2.1}, first

output file is PROG.PT1 {3.2.2}.

*NEND<CR> Non-stop search for break point

{3.11.3}.

$-3T$$ Verify break point location.

....

....

....END

*B,.PW B,.K$$ Write out all lines of text in the

editing buffer up to the pointer

{3.9.1}, then kill those lines.

*EWPROG.PT2$$ Close the first output file and attach

the second {3.2.2}.

*EC$$ Write out the remainder of the editing

buffer and then the remainder of the

input file. Close both input and output

files {3.10.1}.

*

5.2.2 Merging portions of different files

Text for a given application may initially reside in several separate files. While one can merge entire files with the PIP utility program, one can selectively merge portions of files with

___________

TECO-11.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 59

5.2 Manipulating Files

Assume that the file USER.ONE contains information in this schematic form:

ab <FF> cd <FF> ef <FF> gh <FF> ij <FF> kl where <FF> denotes a form-feed character. Further assume that the file USER.TWO contains:

mn <FF> op <FF> qr

The sequence of commands below may be used to merge these two files into a single file, USER.NEW, which contains all of USER.TWO followed by the latter half of USER.ONE:

mn <FF> op <FF> qr <FF> gh <FF> ij <FF> kl

*EWUSER.NEW$ERUSER.TWO$$ Open the output file {3.2.2} and the

input file whose contents are wanted

first {3.2.1}.

*Nr$$ Non-stop search for r {3.11.3}, writing

out mn and op into the output file.

*PW HK$$ Write qr into the output file, appending

a form feed {3.9.1}. Kill the contents

of the editing buffer.

*ERUSER.ONE$$ Attach the other input file.

*_g$$ Search for a character string in the

early part of g, discarding all of the

earlier text blocks in this file

{3.11.5}.

*Nl$$ Search for a character string in the

latter part of l, writing out gh, ij,

and possibly a portion of kl.

*HP EC$$ Write kl into the output file without

_______

appending a form feed {3.9.2}. Close

input and output files {3.10.1}.

*

5.2.3 Rearranging a file

Multiple-line or even multiple-page sections of a file can be rearranged by using Q-registers and by making two passes through the input file. On the first pass, no output file is used, but blocks of text that must be moved to earlier positions in the file

_______ are picked up into Q-registers. On the second pass, selected blocks from the input file and from Q-registers are written into the output file. Any blocks of text that must be moved to later

_____

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 60

5.2 Manipulating Files positions in the file are picked up into Q-registers on the second pass.

This technique will be illustrated with a schematic file:

ab <FF> cd <FF> op which is to be rearranged into the sequence

bd <FF> c <FF> aop where a,b,c,d,o,p each represent arbitrary blocks of text, and

<FF> indicates the locations of the form feeds delimiting the

"pages" in the file {2.3, 3.3.1}. The following dialog outlines the procedure:

*ERFILE.TXT$_d$$ Attach the file for reading. Search for

a character string in the early portion

of d, doing no output, so as to get d

into the editing buffer {3.11.5}.

*0L .,ZXD HK$$ Use Q-register D to store d {3.14.2.1},

that is, all the text from the beginning

of d to the end of the editing buffer.

Clear the editing buffer.

*EBFILE.TXT$$ Reattach the file in backup mode.

*Na$ L B,.XA B,.K$$ Search for text in the last line of a,

save all of a in Q-register A, and clear

a from the editing buffer.

*ZJ GD P Sd$ 0L .,ZK$$ Insert d at the end of the buffer.

Write out bd (followed by the form

feed). Search on the next page for the

first line of d and clear d from the

editing buffer.

*P GA$$ Write out c (followed by the form feed).

Insert a from Q-register A at the

beginning of the buffer {3.14.2.2}.

*EC$$ Close both input and output files.

*

When this operation has been completed, the original file is intact and renamed "FILE.BAK", while the rearranged file is now

"FILE.TXT".

Note: Since TECO-11 dynamically reallocates the available memory between the Q-registers and the editing buffer, one can store rather large blocks of text in Q-registers if the file is properly paged {3.3, 5.3.2, 5.4.4} and if one clears Q-registers when their contents are no longer needed {3.14.2.4}.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 61

5.3 Using Iteration Loops

5.3 Using iteration loops

Iteration loops {3.12.1} and conditional exit from them with the ; command {3.12.2} significantly broaden the range of complex editing operations that can be accomplished with relatively simple command strings.

5.3.1 Counting lines in the editing buffer

The following iteration loop uses numeric Q-register N to count the number of lines in the editing buffer:

*J 0UN <L %N .-Z; > QN=$$

First we instruct TECO-11 to go to the beginning of the editing buffer and to set N=0. On each pass through the iteration loop, we go to the end of the current line, increment N by one {3.14.1.3}, and then test whether the expression ".-Z" is zero. As long as it is negative, the semicolon merely allows the flow of operations to proceed toward the closing iteration bracket {3.12.2}, which causes an indefinite repeat since no numeric argument was specified for the loop {3.12.1}. When the expression ".-Z" becomes zero, we have reached the end of the editing buffer and the ; command causes the flow of operations to jump out of the iteration loop. The value of N is then retrieved {3.14.1.2} and typed out in decimal mode {3.15.1}.

5.3.2 Breaking a file into pages of 40 lines

This example and the one in section 5.4.4 show two methods for breaking a long file into pages so that TECO-11 can subsequently edit the file using less memory. Assume that input and output files have been attached, and consider the command string:

*^D <0J 40L .-Z; 12I$ B,.P B,.K A> EC$$

After setting decimal radix {3.15.2.2}, we instruct TECO-11 to count down 40 lines. Unless we are then at the end of the buffer, we insert a form feed {3.8.4}, write out the 40 lines and the form feed, delete the text just written out, attempt to append more text from the input file, and loop back. Eventually, on the last page of 40 or fewer pages, the semicolon command will find that the pointer position coincides with the end of the editing buffer.

Control will pass out of the loop, and the EC command will output the last partial page (without a form feed) before closing the

input and output files.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 62

5.3 Using Iteration Loops

5.3.3 Formatting a file

The legibility of BASIC-PLUS programs with multi-line statements can be improved by putting each logical statement onto a separate physical line. Assume, for sake of illustration, the restricted case where no logical statement is longer than a physical line.

Also assume that the BASIC-PLUS mode {2.1.2} has been specified.

Consider this specific example:

*HT$$

32000 PRINT FOR L9%=0 TO 5:PRINT SPACE$(35-LEN(X9$)/2);X9$:

PRINT:PRINT:PRINT TAB(40);"BY W. ATOM YEE":

PRINT TAB(44);"AND":PRINT TAB(44);"DAVID S. RUTTY":

PRINT FOR L9%=1 TO 14

32001 X9$="UNIVERSITY OF CALIFORNIA, SANTA CRUZ":

PRINT SPACE$(35-LEN(X9$)/2);X9$:SLEEP 5%:RETURN

32767 END

*^D <S:$; RI $C 0A-13"N 13I$ 10I$ 9I$' > HT$$

32000 PRINT FOR L9%=0 TO 5 :

PRINT SPACE$(35-LEN(X9$)/2);X9$ :

PRINT :

PRINT :

PRINT TAB(40);"BY W. ATOM YEE" :

PRINT TAB(44);"AND" :

PRINT TAB(44);"DAVID S. RUTTY" :

PRINT FOR L9%=1 TO 14

32001 X9$="UNIVERSITY OF CALIFORNIA, SANTA CRUZ" :

PRINT SPACE$(35-LEN(X9$)/2);X9$ :

SLEEP 5% :

RETURN

32767 END

*

Here we have inserted a space in front of every colon, and a

CR-LF-TAB combination after each colon unless it was already at

______ the end of a physical line. The decimal ASCII value of the character following the colon is tested against 13, the value for a carriage return. Whenever the difference is zero, the "N command transfers control past the single quote and we do not

___ insert CR-LF-TAB, in order to avoid creating a blank line.

Warning: The command string given in this section cannot distinguish between the various legal uses of the colon in

BASIC-PLUS syntax: separator between logical lines, separator between device name and file name, occurrence in other string constants, and occurrence in REM statements or after the ! separator. A much more complex TECO-11 routine would be necessary

to sort out all these cases. Possibly the best approach would be to ask for a go-ahead signal from the user whenever any logical line contained both a colon and another diagnostic entity (", ',

!, or REM).

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 63

5.3 Using Iteration Loops

5.3.4 Passing arguments to and from macros

Any numeric argument (or "returned" value) in front of the M command will be passed to the macro about to be executed:

*^UA=$$

*5MA$$

5

*

Similarly, any numeric argument (or "returned" value) occurring at the end of a macro will be passed to the first command to be executed when the macro is finished:

*^UB7$$

*MB=$$

7

*

5.4 Using conditional commands

This section illustrates some of the editing power of the flow control and conditional commands in TECO-11 {3.13}. These commands, ordinarily used in conjunction with numeric flags

{3.16}, commands that return values {2.7.3, 3.11.6.2}, and tags

{3.13.1, 3.13.2}, are considerably more powerful than the ; command used in iterations {5.3}.

For example, a very convenient programming construction is

IF...THEN...ELSE, used when one must do one of two things and then

___ return to a common line of commands. This construction may be implemented in TECO-11 using two conditional tests:

*...condition"t...then...1+'0"E...else...'continue... where "t" denotes one of the conditional execution commands chosen such that the "then" option will be executed if the "condition" is met. If this branch is taken, the numeric expression 1+0 will make the "E test fail, bypassing the "else" option. Otherwise, if the "then" option is not taken, the numeric value 0 will make the

"E test succeed, allowing the "else" option to be executed instead. In either case, execution will subsequently proceed with the portion of the command string denoted by "continue".

5.4.1 Replacing multiple spaces with tabs

Files that originated from punched cards or paper tapes are often unnecessarily long because they contain multiple spaces instead of the TAB character (ASCII decimal value 9). The following command string, which could be stored in a Q-register and executed as a

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 64

5.4 Using Conditional Commands macro, replaces multiple spaces in the editing buffer with tabs, but leaves single spaces alone:

*<S $; Find a space, or exit if the end of the editing buffer

is reached.

.U2 Store the address in numeric Q-register 2.

S^N $ R Search for any character but a blank {3.11.8}, then back

___

up over it.

.-Q2 "G Test whether the current pointer position is beyond the

location of the first blank. If the "greater than" test

is met, then execute the next few instructions up to the

' mark; otherwise skip them {3.13.3}.

Q2-1,.K Delete all the blanks, including the first one.

9I$'>$$ Insert a tab and continue looping

*

If there are one or more blanks at the end of the editing buffer, the message "Search fail in iter" will be printed and those blanks will not be deleted. Otherwise, the ; command will control termination of the loop and no message will be printed.

Caution: This command string will replace every occurrence of

_____ multiple spaces with tabs. This result may be undesirable if the text had included extra spaces to achieve particular columnar formats.

5.4.2 Changing to integer variables in BASIC-PLUS

The BASIC-PLUS language recognizes variables whose names end with the % character as integers and processes them much more rapidly than ordinary BASIC variables, which are implemented as floating-point quantities. Frequently a program will grow from modest beginnings to a size where, on the one hand, conversion to integer variables would greatly improve execution speed, but on the other hand, such conversion might entail lengthy retyping of the program text. Unfortunately a thorough, completely foolproof macro in TECO-11 for accomplishing this conversion would be highly intricate, for it would have to recognize all the elements of

BASIC-PLUS syntax. Nevertheless, a partial solution is possible under certain restrictions.

Each variable to be changed must be preceded and followed by a

________ ___ ________ non-alphanumeric character, that is, "PRINT I" but not "PRINTI", even though the latter is quite acceptable to BASIC-PLUS.

Moreover, text within quotation marks, in remarks, or in DATA statements may also be converted to the % format. An editing macro subject to these limitations is outlined below. It is similar to the technique of section 5.4.1, except for the addition

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 65

5.4 Using Conditional Commands of a prompting message and a capability for the user to enter the variable name (or possibly the integer constant) to be converted to the % format.

*^D @^UB/ Set decimal radix and store the following

macro in Q-register B.

UN .UP Accept the numeric argument passed by the M

command {5.3.4} and save it in numeric

Q-register N. Save the current pointer

position in numeric Q-register P.

^AChange?^A Prompt the user to enter N characters.

QN<^TI$> ^A<CR> Accept N characters in single-character input

mode, inserting each into the editing buffer.

Print <CR><LF>.

^A QP,.XV QP,.D Store these N characters in text Q-register V,

and then delete them from the editing buffer.

<S^S^EQV^S$; Enter an "infinite" loop {3.12.1}. Search in

the current editing buffer for the target

string saved in Q-register V, provided it is

preceded and followed by a separator character

{3.11.8}. This S-search would be changed to an

N-search to convert a multi-page file.

R (0A-36)UC Back up and put the ASCII value of the

separator character, minus the value for a

dollar sign, into Q-register C.

QC"N -%C"N Retrieve C for testing. If the separator was

not a dollar sign, test for a percent sign

___

(ASCII decimal value 37) by decrementing C

{3.14.1.3}.

-3%C"N -6%C"N Similarly decrease C to test successively for

a left parenthesis (ASCII decimal value 40) or

a period (ASCII decimal value 46).

37I$ ''''>/$$ Insert one % character unless the target

______

string was followed by $, %, (, or a period.

Terminate the four if/then conditional blocks,

the iteration loop, the @^U command, and the

command string.

*EBTEST.BAS/$YHT$$ Set the BASIC-PLUS option {2.1.2} and test the

procedure on a small file.

10 REM INTEGER CONVERSION WITH TECO MACRO

20 DIM X(100),I(20)

30 A=1.2 : I$="TEST"

40 PRINT I;I*A3%,X(I) FOR I=1 TO 20 IF A3=1

50 DEF FNI(Z)=Z*A3

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 66

5.4 Using Conditional Commands

60 END

*1MB$$

Change?I

*HT$$

10 REM INTEGER CONVERSION WITH TECO MACRO

20 DIM X(100),I(20)

30 A=1.2 : I$="TEST"

40 PRINT I%;I%*A3%,X(I%) FOR I%=1 TO 20 IF A3=1

50 DEF FNI(Z)=Z*A3

60 END

*2MB$1MB$$

Change?A3

Change?1

*HT$$

10 REM INTEGER CONVERSION WITH TECO MACRO

20 DIM X(100),I(20)

30 A=1.2 : I$="TEST"

40 PRINT I%;I%*A3%,X(I%) FOR I%=1% TO 20 IF A3%=1%

50 DEF FNI(Z)=Z*A3%

60 END

*

Thus, within certain limits, it is possible to convert a single-character variable, a double-character variable, or an integer constant into the corresponding integer form. Notice how the four if/then tests have protected the string variable I$ in line 30, the original variable A3% in line 40, the array variable

I in line 20, the user-defined function I in line 50, and the decimal number containing the digit 1 in line 20. The search string would have to be changed to "S^S^EQV($" and the if/then test for a left parenthesis would have to be omitted in order to convert array I; similarly, the search string would have to be

"SFN^EQV($" to convert user-defined function I.

Although this macro changed 1 to 1% without incident, it could not change 20 to 20% without also affecting the line number 20.

Indeed, implementing a completely foolproof macro for certain conversions may be exceptionally challenging.

5.4.3 Rough alphabetizing by initial letter

Assume that TECO-11 is running and that the editing buffer contains many short lines of text, each beginning with an alphabetic character immediately following a line feed. For example, these lines might consist of names in a roster or entries in an index. The command string outlined below will rearrange the lines into rough alphabetical order. That is, it will group all

the lines beginning with A at the beginning of the page, followed by all the lines beginning with B, and so on.

*!START! 0UZ J 0AUA Tag this point of the procedure for later

looping {3.13.1}. Set numeric Q-register Z

equal to zero. Start at the beginning of

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 67

5.4 Using Conditional Commands

the editing buffer. Load the ASCII value

of the first character of the first line

into numeric Q-register A.

!CONT! L 0AUB Load the ASCII value of the first

character of the next line into numeric

Q-register B.

QA-QB"G XA K -LGA 1UZ' If A>B, move line B in front of line A and

set a flag (Q-register Z).

QBUA L Load B into A and go to the next line.

Z-."G -L OCONT$' Loop back {3.12.2} if there is another

line in the buffer.

QZ"G OSTART$'$$ Repeat from the start if a switch of lines

was made on the pass just completed.

*

Lines beginning with letters early in the alphabet are progressively pushed back to the start of the editing buffer. The algorithm could be extended to perform the same sorting operation on successive characters in each line. TECO-11 is not optimized for sorting or list-processing operations, however, and we will neither discuss such applications further, nor advocate using

TECO-11 for them.

5.4.4 Breaking a file into pages of 4000 characters

An earlier example {5.3.2} showed how to break a file into "pages" of 40 lines. The "lines" may be of little consequence in some text-editing applications, however, and pages with roughly the same number of characters may be more convenient. The following command string will break a file into pages containing no more than 4000 characters. The form feed character is always inserted immediately after a line feed, however, so that the numerous line-oriented commands in TECO-11 will operate properly with the edited file.

!MORE! ^N"FA Tag this point in the procedure for looping

back {3.13.1}. Test the end of file flag

{3.16} to see if more text remains in the

input file. If the flag is not set (false),

the commands between "F and its matching ' at

the end of the fifth line are executed

{3.13.3}. On the first time through, at least,

there will be more text, and the A command

appends more text into the editing buffer,

clearing any old form feed {3.3.2}.

!PAGE! Z-3999"G Define another tag for branching. Test

whether there are 4000 or more characters in

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 68

5.4 Using Conditional Commands

the buffer. If so, the next two lines of the

command string are executed. If not, TECO-11

skips to the matching apostrophe and then

encounters OMORE$.

4000J 0L 12I$ Move the pointer to the 4000th character, then

back up to the nearest preceding line feed.

Insert a form feed character (ASCII decimal

value 12).

B,.P B,.K OPAGE$' Write out the newly delineated page, then

delete this text from the editing buffer.

Return to !PAGE!.

OMORE$' Return to !MORE! whenever there are fewer

than 4000 characters in the editing buffer.

Z"N HP' EF$$ When the end of file flag comes true, control

passes here. If Z is non-zero, it is

necessary to write out the final partial page

of text. Close the output file.

*

Variations of this scheme are possible, for instance, backing up to the previous section heading or paragraph break instead of the nearest line feed. Another input file could be attached when the end of file flag comes on, if it were desired to prepare a single paged output file from several input files.

5.5 Preparing text for processing with RUNOFF

This Manual has been prepared using TECO-11 for original text entry, revisions, and insertion of special commands for Lawrence's version of RUNOFF, a text formatting program. RUNOFF commands may be inserted into a text either as one goes along or in a final editing session. This section demonstrates the final editing of an excerpt from an obsolete term paper and outlines several techniques in the form of editing macros that readers may be able to adapt for their own applications.

The original text in the file AGING.TXT has been typed according to simple manuscript conventions. Paragraphs begin with a TAB character or multiple spaces, but are not separated by skipped lines, which we assume have already been removed by an appropriate editing macro. Footnote numbers do not appear explicitly, since they will vary as the manuscript is revised. A footnote citation

in parentheses is to be generated with TECO-11 at each break that is followed by dashes, or at the end of each quoted passage. One should always work from an up-to-date printed draft of the original text file, since titles of works must be distinguished manually from quoted passages; moreover, stylistic conventions for certain disciplines would preclude indentation of very short

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 69

5.5 Preparing Text for RUNOFF quotations. The material for each footnote is assumed to follow

______ its citation, set off from the text by dashes. It is beyond the scope of this Manual to explain how RUNOFF could double-space the main text, but single-space the quotations and footnotes.

Although the purpose of the inserted RUNOFF commands will be mentioned in the example, the reader must refer to the RUNOFF

Reference Manual (CC Publication No. EDU-520) for further details about the style and function of RUNOFF commands. Note: The following example uses incremental margin changes, which are

___________ supported by Lawrence's RUNOFF, but not by the version described in Digital's RUNOFF User's Guide (DEC-11-ORUNA-B-D).

*@^UP/ J Define a macro {3.14.2.4} to standardize

the autoparagraphing signal for RUNOFF.

Each page of text must be processed with

this macro before attempting to use macro

Q.

<S^EL^ES$; .UA Search indefinitely many times for the

line terminator followed by any number of

spaces or tabs {3.11.8}.

-S^EL$" .,QAD I $> /$$ Each time such a combination is found, go

back to the line terminator, delete the

intervening spaces and tabs, and insert a

single space.

*@^UQ/ UN S"$ -D Define a macro to indent quoted passages.

Save the footnote number passed by the M

command {5.3.4}. Find the opening

quotation mark and delete it.

(-1A-10)"E -2D' I<CR> Kill any previous CR-LF that would trigger

unwanted paragraphing by RUNOFF.

.LM +5;.RM -5;.B;$ Change to indented left and right margins.

Skip a line, but do not indent as a

paragraph.

S"$ -D I($ QN\ I)<CR> Find the closing quotation mark and delete

it. Insert the ASCII representation

{3.8.5} of the footnote number inside

parentheses, followed by a carriage

return.

.LM -5;.RM +5$ .UA Also insert commands to restore normal

margins.

::S^ES$ QA,.D Use a compare {3.11.6.3} to skip past any

spaces or tabs that would trigger unwanted

paragraphing. Delete them.

(0A-13)"N I;.B;$ OGO$' Test the ASCII value of the next character

{3.16}. If it is not a carriage return

___

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 70

5.5 Preparing Text for RUNOFF

{3.13.3}, then skip a line but do not

indent for a paragraph; bypass the next

line of the macro {3.13.2}.

L (0A-32)"N I.B;$' If a carriage return was seen, skip past

the corresponding line feed and test the

next character. If it is not a space

___

(which will trip autoparagraphing), then

skip a line.

!GO! MF /$$ Tag for preceding O command {3.13.1}.

Invoke macro F to handle the footnote

corresponding to this quoted passage.

There will be a "search fail" if the

footnote cannot be found.

*@^UC/ UN Define a macro to insert citations that do

not appear as direct quotations. Save the

footnote number passed by the M command

{5.3.4}.

S---$ 0L 2R Find a footnote. Back up past the

preceding CR-LF combination.

I($ QN\ I)$ Insert the ASCII representation of the

footnote number inside parentheses.

MF /$$ Invoke the macro that handles footnotes.

*@^UF' $S---$ 0KK .UB Define a macro to handle footnote

formatting for RUNOFF. This macro begins

with an ESCAPE to clear any previous

argument returned {2.7.3}. Find the start

of the footnote and kill the dashed line.

S---$ 0L Find the end of the footnote.

(.-QB)/55+2UL QBJ Estimate the number of lines this footnote

will require (integer arithmetic: minimum

is 2 lines). Return to the start of the

footnote.

I.FN $ QL\ I<CR> Specify the ASCII representation of the

number of lines to be allocated for this

footnote.

.LM 0;.RM 60;.B<CR> Specify full-width margins for footnotes

(RUNOFF goes back to any special settings

when it exits from footnote mode). Each

footnote begins with one blank line.

$ QN\ I.##$ Insert ASCII representation of the

footnote number, followed by a period and

two "non-expandable" spaces.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 71

5.5 Preparing Text for RUNOFF

S---$ 0KK I!<CR> Find the end of the footnote. Kill the

dashed line. Insert the exclamation point

(must be on a line by itself) to mark the

end of footnote text.

$ '$$

*EWAGING.RNO$ Open output file with proper default

extension for RUNOFF.

ERAGING.TXT$YHT$$ Open input file and obtain a copy (if not

already at hand).

In Caroline Gordon's "Old Red" we meet Professor Maury, a man who regrets that time passes by so rapidly and a man whose pride resists accepting the deceleration in pace of living that age necessitates. His leg bothers him more and more, but he stoically insists that he is learning better all the time how to handle it.

-----

Caroline Gordon, "Old Red," in Masters and Masterpieces of the Short Story, ed. by Joshua McClennen (New York: Henry Holt and Co., 1957), p. 19.

-----

The tail of stubbornness does not, however, completely wag the dog of reason. Mr. Maury does concede that his game leg has precluded his hunting. On the other hand, he continues to fish; indeed, "He himself had never lost one day's fishing on account of his leg. He had known from the start how to handle it. It meant simply that he was slowed down that much. It hadn't really made much difference in fishing." In

-----

Loc. cit.

----- refusing to admit that he is growing old, Mr. Maury compares himself to the clever fox, Old Red, and sums up his philosophy:

"The thing was to be up and ready, ready to run for your life at a moment's notice. Yes, it had always been like that. It always would be."

-----

Ibid., p. 23.

-----

In contrast to Mr. Maury's lack of time in old age,

Jody's grandfather in John Steinbeck's "Leader of the People" has nothing to do but to think and talk about his pioneering days....

*I.PS 40,60;.AP<CR> Insert RUNOFF commands for page size (40

lines for demonstration) and autoparagraph

mode. A paragraph break will be triggered

by a line that begins with a space.

$ MP J Invoke the macro to fix up

autoparagraphing signals. Return to the

beginning of the editing buffer.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 72

5.5 Preparing Text for RUNOFF

4UN QNMC$$ Set the footnote number to 4 (this excerpt

is not the start of the paper). Process

the footnote. There should be no error

type-out.

*-SMaster$ ^SC I^&$ Flag the title of a book for underscoring.

SStory$ I\&$$ End of underscored title.

*2<%NMQ> $$ Format two successive quotations and their

corresponding footnotes, incrementing the

footnote number before doing each. Note:

It is important that we have already

passed the title "Old Red" which the macro

would misinterpret as a quoted passage.

*-SLoc. cit.$ ^S-2UB Find foreign phrase and save the negative

of its length {3.16}.

I\&$ QBC I^&$$ Flag the phrase for underlining.

*SIbid.$ ^S-2UB Find another foreign phrase.

I\&$ QBC I^&$$ Flag it for underlining.

*HT$ Here we type out the text to show its

RUNOFF commands.

.PS 40,60;.AP

In Caroline Gordon's "Old Red" we meet Professor Maury, a man who regrets that time passes by so rapidly and a man whose pride resists accepting the deceleration in pace of living that age necessitates. His leg bothers him more and more, but he stoically insists that he is learning better all the time how to handle it.(4)

.FN 4

.LM 0;.RM 60;.B

4. Caroline Gordon, "Old Red," in ^&Masters and Masterpieces of the Short Story\&, ed. by Joshua McClennen (New York: Henry Holt and Co., 1957), p. 19.

!

The tail of stubbornness does not, however, completely wag the dog of reason. Mr. Maury does concede that his game leg has precluded his hunting. On the other hand, he continues to fish; indeed,

.LM +5;.RM -5;.B;He himself had never lost one day's fishing on account of his leg. He had known from the start how to handle it. It meant simply that he was slowed down that much. It hadn't really made much difference in fishing.(5)

.LM -5;.RM +5;.B;In

.FN 2

.LM 0;.RM 60;.B

5. ^&Loc. cit.\&

! refusing to admit that he is growing old, Mr. Maury compares

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 73

5.5 Preparing Text for RUNOFF himself to the clever fox, Old Red, and sums up his philosophy:

.LM +5;.RM -5;.B;The thing was to be up and ready, ready to run for your life at a moment's notice. Yes, it had always been like that. It always would be.(6)

.LM -5;.RM +5

.FN 2

.LM 0;.RM 60;.B

6. ^&Ibid.\&, p. 23.

!

In contrast to Mr. Maury's lack of time in old age,

Jody's grandfather in John Steinbeck's "Leader of the People" has nothing to do but to think and talk about his pioneering days....

*<CR>

EG$$ Exit to RUNOFF {3.10.3}.

RUNOFF

Source File? AGING

Output File? <CR>

Underscore (B, L, S or N)? B

Simulate Form Feed (Y or N)? Y

Pause? <CR>

In Caroline Gordon's "Old Red" we meet Professor Maury, a man who regrets that time passes by so rapidly and a man whose pride resists accepting the deceleration in pace of living that age necessitates. His leg bothers him more and more, but he stoically insists that he is learning better all the time how to handle it.(4) The tail of stubbornness does not, however, completely wag the dog of reason. Mr.

Maury does concede that his game leg has precluded his hunting. On the other hand, he continues to fish; indeed,

He himself had never lost one day's fishing on

account of his leg. He had known from the start

how to handle it. It meant simply that he was

slowed down that much. It hadn't really made much

difference in fishing.(5)

In refusing to admit that he is growing old, Mr. Maury compares himself to the clever fox, Old Red, and sums up his philosophy:

The thing was to be up and ready, ready to run for

your life at a moment's notice. Yes, it had

always been like that. It always would be.(6)

In contrast to Mr. Maury's lack of time in old age,

Jody's grandfather in John Steinbeck's "Leader of the

People" has nothing to do but to think and talk about his

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 74

5.5 Preparing Text for RUNOFF pioneering days....

4. Caroline Gordon, "Old Red," in Masters and Masterpieces

_______ ___ ____________ of the Short Story, ed. by Joshua McClennen (New York:__ ___

_____ _____

Henry Holt and Co., 1957), p. 19.

5. Loc. cit. ____ ____

6. Ibid., p. 23. _____

KB:RUNOFF.DOC created, 1 pages

15.3 sec. CPU time used

Source File? ^Z

Ready

This example illustrates the tradeoffs between, on the one hand, the time required to design and test intricate macros and, on the other hand, the time required to do all of the editing using simpler commands. Note that the macros could be stored in files and be read in by TECO-11 for use again at a later date.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 75

Appendix A TECO-11 Error Messages

This appendix lists all TECO-11 mnemonics and error messages. For ease of reference, it also lists other informational messages that are unrelated to error conditions.

Mnemonic Message and Explanation

(none) Fatal error - xxxx

An internal error from which it is impossible to

recover has occurred either in TECO-11 or in RSTS/E.

TECO-11 attempts to close the input and output files,

but the contents of the editing buffer are lost.

TECO-11 then exits to the default run-time system.

Please report the circumstances of such an error

promptly to the Computer Center, and bring along all

of your output. It is particularly helpful to know

what message was printed in place of xxxx.

(none) [xK memory]

TECO-11 prints this informational message after

expanding its memory area. The number of 1K segments

of memory currently in use is substituted for the x in

this message {2.9}.

(none) Re-entering TECO

This message is printed when the user types CTRL/C

while TECO-11 is executing a command string. This is

in general only necessary when the user put TECO-11 in

an infinite loop. When this message is printed,

execution of commands is terminated, but the buffer is

not cleared and no files are closed. The user can

continue editing normally {3.10.4}.

(none) Search fail in iter

If a search without a colon modifier fails inside an

iteration, and the next command is not the semicolon

command, this warning message is printed and execution

of the iteration is terminated; TECO-11 proceeds with

the first command to the right of the closing

iteration bracket, as if there were a ; command

{3.12.2}.

?BNI > not in iteration

This message indicates that iteration brackets were

improperly matched, and that a right angle bracket was

found without a matching left angle bracket.

?CCC Can't clobber command

A macro attempted to change the contents of the text

Q-register in which the macro itself is stored.

?DTB Delete too big

Caused by an attempt to delete characters beyond a

buffer boundary.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 76

Appendix A TECO-11 Error Messages

?ERR (RSTS/E error message)

This message is printed when an input/output operation

such as opening a file, or reading from it or writing

into it, could not be completed successfully by

RSTS/E. The cause of the problem is indicated by the

remainder of the message. Example:

?ERR Device hung or write-locked

is most probably caused by attempting to use a device

(such as DECtape) that was off-line.

?ICC Illegal " character

The " command (conditional execution command) was

followed by a character not recognized as a valid

condition.

?IEC Illegal E character

The E character (first character of several

two-character commands) was followed by an invalid

second character.

?IFC Illegal F character

The F character (first character of several

two-character commands) was followed by an invalid

second character.

?IFN Illegal file name "xxxx"

The file name specified in an EW, ER or EB command was

not a valid RSTS/E filename. The file name is printed

out in place of the "xxxx".

?ILL Illegal command

A character was encountered where a command character

was expected, but the character was not valid as such.

?ILN Illegal number

An invalid digit (8 or 9) was encountered while

TECO-11 was operating in octal radix mode.

?IQN Illegal Q register name

A Q-register command referred to a Q-register with a

name that was not a letter or digit.

?MEM Memory overflow

TECO-11 attempted to obtain a larger memory area to

execute a command, but was unsuccessful. Adding text

to the editing buffer or to a Q-register is no longer

possible. Other operations are still feasible, and

those that reduce the amount of data in the

Q-registers or in the editing buffer can free space

before one attempts the failing command again.

?MLP Missing (

A right parenthesis has been reached, but it had no

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 77

Appendix A TECO-11 Error Messages

matching left parenthesis.

?MRP Missing )

TECO-11 has reached the logical end of an arithmetic

expression that contained a left parenthesis without a

matching right parenthesis.

?NAB No arg before ^_

The ^_ command (complementation) was used without a

numeric argument preceding it.

?NAC No arg before ,

The , operator (used for denoting argument pairs) was

not preceded by a numeric argument.

?NAE No arg before =

?NAP No arg before )

?NAQ No arg before "

?NAS No arg before ;

?NAU No arg before U

?NEB No EB if EB active

When an EB command is issued, further commands that

would cause opening of an output file are prohibited.

This error message is caused by an attempt to perform

an EB after one had been issued before.

?NEW No EW if EB active

Caused by an attempt to open an output file after

executing an EB command.

?NFI No file for input

A command that performs input (A, P, N, etc.) was

attempted before opening an input file with EB or ER.

?NFO No file for output

A command that performs output (PW, P, N) was

attempted before opening an output file with EB or EW.

?PDO Push-down list overflow

Iteration brackets or macros were nested too deeply.

?POP Pointer off page

A command such as C, J, or R was used to move the

pointer beyond the boundaries of the editing buffer.

?SNI ; not in iteration

The semicolon command was used outside an iteration

loop.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 78

Appendix A TECO-11 Error Messages

?SRH Search failure for "xxxx"

A search command could not find the search string

passed as an argument. The string is printed out in

place of the "xxxx".

?STL Search string "xxxx" too large

The specified search string exceeded 64 characters

(check for failure to type I command). The first 64

characters are printed out in place of the "xxxx".

?UIF Unimplemented feature

The user issued a command that is recognized by

TECO-11 as a valid command, but that is not available

in the current RSTS/E implementation.

?UTC Unterminated command

This error message can be caused by a variety of

errors. Most often the reason will be a missing ) or

>, a missing terminator for an @I or @ search command,

or a missing tag.

?UTM Unterminated macro

This message is caused by the same error conditions as

the ?UTC message, but is printed when the error occurs

inside a macro.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 79

Appendix B Summary of Commands

This appendix lists all TECO-11 commands, the sections of this

Manual where they are described, and brief indications of their purposes. The commands are listed according to increasing value of their decimal ASCII codes.

Command Paragraph Comments

NULL 2.2 Ignored on input; can be inserted only with

0I$.

^A 3.17.1 Text typeout, for debugging or prompting.

^B 3.16 Return date as a number (Julian date).

^C 3.10.4 Exit from infinite loop (CTRL/C).

3.10.5 Immediate exit from TECO-11 (uparrow-C or

CTRL/C twice in succession).

^D 3.15.2.2 Set current radix to decimal.

^E 3.16 Return form-feed flag.

3.11.8 Special match character in search strings

(CTRL/E).

^EA 3.11.8 Match alpha (lower or upper case).

^ED 3.11.8 Match digit.

^EL 3.11.8 Match line terminator.

^EQq 3.11.8 Match contents of Q-register q.

^ES 3.11.8 Match spaces or tabs.

^EX 3.11.8 Match any character.

^F 3.16 Return value in console switches (normally

-1).

^G^G 4.1.3 Kill command string.

^Gspace 4.1.4 Retype current command line.

^H 3.16 Return time of day in minutes before

midnight.

^I(TAB) 3.8.2 Insert text beginning with TAB.

LF 2.3 Delimit lines in editing buffer.

3.18 Ignored in command strings. For command

formatting or insertion only.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 80

Appendix B Summary of Commands

VTAB 3.18 Ignored in command strings.

FF 2.3 Delimit pages on input.

3.18 Ignored in command strings.

CR 3.18 Ignored in command strings.

^N 3.16 Return end-of-file flag.

^Nx 3.11.8 Special search character (CTRL/N). Ignore

all but x.

^O 3.6.3 Stop typeout (CTRL/O).

3.15.2.1 Set octal radix (uparrow-O).

^Q 3.11.8 Special quote character in search strings

(CTRL/Q).

^R 3.11.2 Search with replace (synonymous with FS).

^S 3.16 Return the negative of the length of the

last inserted or searched string.

3.11.8 Special match character for separators in

search strings (CTRL/S).

^T 3.16 Return ASCII value of next character typed

on terminal.

^U 4.1.2 Erase typed line (CTRL/U).

^Uq 3.14.2.4 Store text argument in Q-register

(uparrow-U).

^V 3.16 Return TECO-11 version number (17 for the

version described in this manual).

^W No function in TECO-11.

^X 3.11.8 Wild card character in search strings

(CTRL/X).

^Y 3.4 Buffer position argument.

^Z 3.16 Return total number of characters stored in

Q-registers.

ESCAPE 2.2.1 String argument delimiter. Double ESCAPE is

command terminator.

^\ Illegal command.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 81

Appendix B Summary of Commands

^] Illegal command.

^^ 3.16 Return ASCII value of next character in

command string.

^_ 3.16 Complement operator.

SPACE 3.18 Ignored in command strings except in the

special combination ^Gspace {2.2.1, 4.1.4}.

! 3.13.1 Delimit command string tag.

" 3.13.3 Open a conditional execution block.

# 2.7.2 Logical OR operator in arithmetic

expressions.

$ 2.2.3 Illegal command. Used as echo for ESCAPE.

n%q 3.14.1.3 Increment numeric Q-register q by n.

& 2.7.2 Logical AND operator in arithmetic

expressions.

' 3.13.3 Close a conditional block.

( and ) 2.7.2 Have their usual meaning in arithmetic

expressions.

* 2.7.2 Multiplication operator.

*q 3.14.3 Save previous command string.

+ 2.7.2 Addition operator.

, 2.7.2 Separate arguments of a numeric argument

pair.

- 2.7.2 Subtraction or negation operator.

. 3.4 Return the value of the buffer pointer.

/ 2.7.2 Integer division operator.

2.1.2 Set BASIC-PLUS mode for file name.

0-9 Digits.

: 3.11.6.2 Search modifier (returns success/failure

value).

:: 3.11.6.3 Search modifier (converts search to a

compare operation and returns value).

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 82

Appendix B Summary of Commands

n; 3.12.2 Conditional exit from iteration (if n>=0).

< 3.12.1 Open iteration loop.

= 3.15.1 Type decimal value and change radix to

decimal.

== 3.15.1 Type octal value and change radix to octal.

> 3.12.1 Close iteration loop.

? 3.17.2 Trace flag (acts as flip-flop).

4.2.1 Error trace-back.

@ 3.11.6.1 Modifier for commands with string arguments.

A 3.3.2 Append page to the editing buffer (no

argument).

nA 3.16 Return ASCII value of a character in the

text buffer (with numeric argument).

B 3.4 Equivalent to 0, the position of the start

of the buffer.

C 3.5.3 Skip characters forward.

D 3.7.2 Delete characters.

EB 3.2.3 Open a file for editing with provision for

backup.

EC 3.10 Finish copying the input file and close all

files.

EF 3.9.3 Close the output file.

EG 3.10.3 Exit and go; performs an EC, then starts a

system program.

EH 4.2.2 Set or return help flag (determines length

of error messages).

EK 3.10.6 Close and kill the output file (cancel

editing).

ER 3.2.1 Open a file for input.

ES 3.11.7 Set or return automatic type-out flag.

EW 3.2.2 Open a file for output.

EX 3.10.2 Exit to the default run-time system.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 83

Appendix B Summary of Commands

FN 3.11.4 Non-stop search with replacement.

FR 3.8.6 Replace previously inserted or replaced

string.

FS 3.11.2 Search with replacement, equivalent to ^R.

Gq 3.14.2.2 Copy a text Q-register into the editing

buffer.

H 3.4 Equivalent to B,Z; specifies the entire

editing buffer.

I 3.8.1 Insert text.

nI 3.8.4 Insert ASCII character n.

J 3.5.1 Jump to absolute character position in the

buffer.

K 3.7.1 Kill lines.

L 3.5.4 Skip lines forward.

Mq 3.14.2.3 Execute text in Q-register as macro.

MAKE 3.1.2 When given to RSTS/E, starts TECO-11, then

performs an EW.

N 3.11.3 Non-stop search.

O 3.12.2 Skip forward or backward in the command

string to a tag.

P 3.9.2 Advance a page.

PW 3.9.1 Write a page, leaving the editing buffer

unchanged.

Q 3.14.1.2 Read numeric Q-register.

R 3.5.3 Skip characters backward.

S 3.11.1 Search for a string in the current editing

buffer.

T 3.6.2 Type text from the editing buffer.

TECO 3.1.3 When given to RSTS/E, starts TECO-11, then

performs EB and Y commands.

Uq 3.14.1.1 Store value in numeric Q-register.

V 3.6.1 Verify current line.

TECO-11 Reference Manual - CC Publication No. EDU-500 Page 84

Appendix B Summary of Commands

W Illegal command.

Xq 3.14.2.1 Load text Q-register from editing buffer.

Y 3.3.1 Clear the editing buffer and read a new page

(destructive read).

___________

Z 3.4 Return the position of the end of the

editing buffer.

[ Illegal command.

\ 3.16 Backslash; read a number from the editing

buffer (no argument).

n\ 3.8.5 Insert a number into the editing buffer.

] Illegal command.

^ 2.2.2 Uparrow or circumflex; interpret next

character as the corresponding control

character.

_ 3.11.5 Destructive search.

___________

` Accent grave; equivalent to @.

a-z 2.2 Equivalent to the corresponding upper-case

command characters in commands (except after

^E).

{ Illegal command.

| Equivalent to \.

} Illegal command.

~ Tilde; equivalen