This file will be an interm on-line INFO file for TECO. -*-Text-*-  File: TECMAN Node: Top Up: (DIR) TECO, the Text Editor and Corrector, is both a text editor, and a language designed for the creation of higher level editing systems, such as EMACS, INFO, and RMAIL. Unfortunately, there is no on-line tutorial at this time. If you want to go hunting, somewhere around the ninth floor there is a thick velobound manual which someone produced by adapting DEC's TECO manual (fourteen years out of date) to the then-current version. It's on blue paper, and seems to have been printed on an impact printer of some type. I saw it last in CADR-1's room (907). If anyone knows the whereabouts of a tape, please let us know! What on-line documentation there is now exists in two forms: * Menu: * Ascii: (.TECO.;TECORD >)* A complete listing of TECO commands, in ASCII order. Usually requires use of an editor to find the entry you're looking for. Most useful when attempting to understand another user's TECO code. ("What does this mean?") * Concept:: The same data, resorted roughly by kind of command (editing, variables, mathematics, environmental, and so on. Refer to this section when you are writing new code. ("How can I do this?") Two abortive attempts have been made recently to produce a TECO tutorial manual. These are: * JKESS: (MC:.teco.;jkess info)Top * KMP: (MC:.teco.;kmp info)Top Also worth looking at: * Brief: (MC:.teco.;teco primer)*  File: TECMAN Node: Concept Up: Top At this time, these topics are not perfectly seperated. In many cases, a command could have been listed under several topics, and the decision was based on how I most often used it. If you don't find what you're looking for, be creative in guessing where else I might have put it. If all else fails, read .TECO.;TECORD > into EMACS, and try using search commands to look for it. * Menu: The current topics are: * Functions:: All commands which are used to obtain a value without modifying TECOs state. Specifically, values referring to locations in the editing buffer (in terms of characters, lines, words, LISP constructs and parentheses), the characters in the buffer, string comparison and examination, a random number generator, conversions (ASCII/SAIL/sixbit character sets), arguments passed to a TECO Macro, and so on. * Background:: General information about TECOs behavior. Init files, Journal files, data structure descriptions and internal formats, character sets, how to control TECO from other programs, neat programming hacks, debugging aids, and proposed TECO program standards. * Fancy:: High-powered commands: Sorting, command dispatching, LISP parsing, variable table hacking, text processing (justification etc.). * Deletion:: How to delete characters from the buffer. * Real-time:: "Real-time", or dynamic, command recognition. This is the system upon which EMACS is built. Also known as "^R-mode TECO". * Files:: How to read and write files; reading and modifying directories, Journal and Dump files, and I/O channel manipulation. * Named:: Analogous to EMACS' MM commands. These are commands which, while indespensable when needed, are not used often enough to warrent a one- or two-character name. Mostly environmental control variables. They are accessed via the FS command prefix. If you can't find it anywhere else, it's probably here. * Flow:: Program flow control: Branching, loops, conditionals, error traps, lisp-like "throw" and "catch". * Insertion:: Inserting characters into, and "writing over", the editing buffer and other data structures. * Math:: Mathematical and boolean operators. Note that booleans operate bitwise on data. * Motion:: How to get to the desired editing location, either explicitly by searching the buffer (and clean-up operations after searching), recovering automatically stored records of past locations, screen-oriented actions. * Variables:: Q-registers (built-in and user-defined) are the most commonly-used "variable" in TECO. They can hold text, numeric values, or an entire editing buffer. Text can be executed as a TECO command string (a TECO Macro, or program). A push-down list (stack) exists. This section also contains documentation of the special-purpose "..n" Q-registers. * Syntax:: Commands related to TECO syntax. How to execute a command; how to abort one; exiting TECO; error recovery and debugging commands; sleeping; comments and other command format questions; case conversion; communicating with other programs; error messages. * TTY:: Commands for reading from and outputting to the user's terminal, and controlling the format of these actions. * Valret:: Invoking other programs from within TECO.  File: TECMAN Node: Functions Up: Concept TECO COMMANDS: ARGUMENTS -- basicly, all commands which are FUNCTIONS -- that is, return a value without otherwise changing the system's state. >>>>>>>>>>>>>>>>>>>> Buffer Position Values <<<<<<<<<<<<<<<<<<<< . equals the number of chars to left of the pointer. B normally 0. Actually, the number of the first character within the virtual buffer boundaries - but that will be the first char in the buffer (char number 0) unless you have used FS BOUND or FS V B to change that. Z val=number of chars in buffer (more generally, the character number of the virtual end of the buffer, if virtual buffer boundaries are in use). H equivalent to B,Z; i.e., specifies whole buffer (or all within the virtual boundaries if they're in use) to commands taking two args for character positions such as K, T, or V. ^@ for nonnegative , is the same as ".,.+". For negative , is the same as ".+,.". "10^@XA" puts the 10 characters after the pointer in a string in qreg A. >>>>>>>>>>>>>>>>>>>> Buffer position in LINES <<<<<<<<<<<<<<<<<<<< F^@ returns, in numerical order, 2 args that delimit a range of the buffer extending lines from the pointer. Thus, "F^@T" is the same as "T". @F^@ is like F^@ but treats in CRLFs, not just CRs. >>>>>>>>>>>>>>>>>>>> Buffer position in LISP <<<<<<<<<<<<<<<<<<<< FL a list maniulating command, that returns 2 values specifying a range of the buffer. If is >0, the range returned is that containing the next lists to the right of the pointer; if is <0, the range is that containing lists to the left of the pointer. This command should be followed by a command such as K, T, X, FX ... which can take 2 args; the specified number of lists will be deleted, typed, put in q-reg, etc. To move to the other side of the lists, do "FLL". The syntax parsed by FL is controlled by the delimiter dispatch table in Q..D; the character types known are "A", " ", "|", "/", "(", ")" and "'", and any character can be redefined to be of any of those types. :FL is like FL, but stops before the ( that starts the list instead of after. -:FL stops after the ), etc. @FL is like "FL", but refers to s-expressions rather than lists. An s-expression is either a list or a LISP atom, whichever is encountered first. "@FW" is used to find LISP atoms when necessary. @:FL stops before the next s-expression - if it is a list, it stops before the (, and if it is quoted it stops before the quote. >>>>>>>>>>>>>>>>>>>> Buffer position in PARENS <<<<<<<<<<<<<<<<<<<< FU a list manipulating command whose main use is in FUL, which moves up levels of parentheses. FU where is positive returns a pair of args for the next command, specifying the range of the buffer from . Moving rightward to the first place levels up. If is negative, it moves left - levels up. >>>>>>>>>>>>>>>>>>>> Buffer position in WORDS <<<<<<<<<<<<<<<<<<<< FW similar to FL but hacks words instead. A word is defined as a sequence of non-delimiters. Initially, the non-delimiters are just the squoze characters but the user can change that - see q-reg ..D. This command returns a pair of args for the next one. Also, FW sets FS INSLEN equal to the length of the last word moved over. Main uses: FWL moves right one word, -FWL moves left one, FWK deletes one word to the right, FWFXA deletes and puts in q-reg A, FWFC converts one word to lower case. :FW similar to FW but stops before crossing the word instead of after. Thus, :1FWL moves up to before the next non-delimiter. :2FWL is the same as 2FWL-FWL. :FW sets FS INSLEN to the length of the last inter-word gap crossed. @FW like FW, but finds LISP atoms rather than words. Understands slashes and vertical bars but not comments. >>>>>>>>>>>>>>>>>>>> Numerical Functions <<<<<<<<<<<<<<<<<<<< ^Z normally causes an interrupt to DDT when typed. However, one can be given to TECO by quoting it with ^_ , in which case it is a normal command: with no arg, its value is a pseudo-random number. >>>>>>>>>>>>>>>>>>>> Examining buffer <<<<<<<<<<<<<<<<<<<< A value is the 7-bit ASCII value of char arg chars to the right of the pointer. Note that "0A" is the character immediately to the left of the pointer and "-A" is the character +1 characters left of the pointer. If .+-1 is not within the bounds (real or virtual) of the buffer, a "NIB" error occurs. ,A is like A except that when A would cause a "NIB" error, ,A will return . Thus, 13,1A will return 13 iff the pointer is either at the end of the buffer or before a carriage return. \ If no arg, converts digits in the buffer to a number. Value is the number represented as decimal digits to right of pointer in buffer (actually, the input radix comes from FS IBASE, as with numbers in commands). :\ allows an optional minus sign. Moves pointer to right of number. :\ returns a string containing the printed representation of , in the radix in ..E. Sets FS INSLEN. ,:\ makes a character string, with leading spaces. >>>>>>>>>>>>>>>>>>>> Arguments to Macros <<<<<<<<<<<<<<<<<<<< ^X only defined inside macro. Its value is the first arg of the M command which called the macro. See the F^X command for a more sophisticated way for macros to examine their arguments. ^Y like ^X, only second or only arg of the M command. :F^K can be used by a macro to tell whether it was called from the internals of TECO or from another macro. It returns -1 if the macro was called from the internals of TECO or was called with @M. Otherwise, it returns a positive number. F^X within a macro, this command returns as its values the arguments that were given to the macro. As many values are returned as args were given. To find out how many there were, use F^Y. F^Y returns a value saying how many args it was given. For example, WF^Y returns 0; W1F^Y, 1; W1,F^Y, 2; W1,2F^Y, 3. The : and @ flags are also indicated by bits in the value; :F^Y returns 4 and @F^Y returns 8. 1,2:@F^Y returns 15. The modifier flags, and the previous arguments, are flushed. >>>>>>>>>>>>>>>>>>>> String-handling Functions <<<<<<<<<<<<<<<<<<<< F^B: F^B searches for the character in . should be the ASCII code for a character. If that character does not occur in , -1 will be returned. If the char does occur, the value will be the position of its first occurrence (eg., 0 if it is the first char). ,F^B is like F^B but searches starting at position in the string. If no occurrence is found past there, the value is -1. F* reads and ignores a string argument. Useful in macros because "F*^]^X" reads and ignores a string argument passed to the macro. F= does an ordered comparison of strings. If "F=" has numeric args, they specify the range of buffer to be used as the first comparison string. Otherwise, the "=" should be followed by the name of a q-reg which should hold the first comparison string. The second comparison string should follow the command as a string argument, as for the "I" command. (the @ modifier works just as it does for the "I" command) the two strings are compared, and if they are equal 0 is returned as the value of the "F=" command. If the first string is greater, a positive value is returned; if the second, a negative value. If the value isn't 0, its absolute value is 1 + the position in the string of the first difference (1 if the first characters differ, etc.). A string is considered to be greater than any of its initial segments. F~ compares strings, ignoring case difference. It is just like F= except that both strings are converted to upper case as they are compared. >>>>>>>>>>>>>>>>>>>> Conversions <<<<<<<<<<<<<<<<<<<< F() converts feet inches to inches. ^^ (ctl caret) has the value of the 7-bit ASCII code for . F6 returns a word of SIXBIT containing the first six characters of . F6 interpreting as a word of SIXBIT, converts it to ASCII which is then inserted in the buffer before the pointer. : F6 returns a string containing the characters of . @F6 is an obsolete equivalent command. :FC returns the upper-case equivalent of the character whose numeric code is , as a numeric code. Meta-bits in are passed through unchanged. :FC may also be given a string pointer as argument. It returns a new string containing the upper-case of its argument. >>>>>>>>>>>>>>>>>>>> Q-Reg related <<<<<<<<<<<<<<<<<<<< F^^<^R-char> F^^ takes the name of a ^R-character definition, as a q-reg, and returns the 9-bit character code for the character. For example, F^^.^R. returns the code for Control-., which is 256 octal. :F^^ :F^^ is used to test whether a string contains a valid short q-register name. The string is passed as a string pointer in a prefix argument. If the string contains a short q-register name then the :FS QP HOME of that q-register is returned. Otherwise, zero is returned. >>>>>>>>>>>>>>>>>>>> "Searching" the buffer <<<<<<<<<<<<<<<<<<<< @F^B searches the buffer from point forward for a character NOT belonging to , and then returns .,
. If such a character is not found, .,Z is returned. -@F^B searches the buffer backwards from point for a character NOT belonging to , and then returns
,. If no such character is found, B,. is returned. ,@F^B searches the buffer from to (which can be either forward or backward) for a character NOT belonging to , and then returns .,
or
,., whichever puts the smaller value first. @:F^B is like @F^B with no colon except that it searches for a character which IS a member of . It takes the same sorts of arguments that non-colon @F^B takes, and returns the same sorts of values. >>>>>>>>>>>>>>>>>>>> Searching other structures <<<<<<<<<<<<<<<<<<<< F^S: ,F^S searches the buffer or word aligned string in for a word containing , starting at word . If one is found, its index is returned; otherwise, -1 is the value. The index of one occurrence can be used as in the next call to find the next occurrence. ,:F^S searches the ^R character definition table instead of a buffer. In other respects it is like F^S. >>>>>>>>>>>>>>>>>>>> Other functions <<<<<<<<<<<<<<<<<<<< FK returns minus the value of FS INSLEN; that is, minus the length of the last string inserted by "I", "G" or "\", or found by a search or "FW". FK is negative except after a successful backward search, or backward "FW". Thus, "SFOOFKC" will move to the beginning of the FOO found. "-SFOOFKC" will move to the end of the FOO found. See also the ^B command in this context. "SFOOFKDIBAR" will replace FOO with BAR. See "^F". "IBLETCHFKC" inserts BLETCH and backs over it. EG is a semi-obsolete command for getting random info. It inserts in buffer on successive lines the current date (as YYMMDD), the current time (as HHMMSS), TECO's current sname, TECO's default filenames for E-commands, the real names of the file open for input the date in text form, a 3-digit value as follows: 1st digit = day of week today (0 = Sunday) 2nd digit = day of week of 1st day of year 3rd digit should be understood as binary: 4-bit = normal year, and after 2/28 2-bit = leap year 1-bit = daylight savings time in effect. (this line is blank on Twenex) and the phase of the moon. There are better ways to get most of these things: FS FD CONV, FS D FILE, FS D SNAME, FS I FILE.  File: TECMAN Node: Background Up: Concept TECO COMMANDS: Background information. Lower case letters are interpreted like upper case letters when they are commands. Inside insert and search strings they are treated as themselves. When TECO is started for the first time, it initializes various data areas, prints its version number, and initializes several flags associated with the terminal (by executing FS TTY INIT). If TECO was started at 2 + the normal starting address, FS LISPT is set nonzero. Otherwise, it is set to 0. In either case, TECO looks for a "TECO INIT" file (see below), executing it as a program if it is found. When TECO is restarted, it does not clobber the buffer, q-regs or open files. It does, however, execute FS TTY INIT which resets some flags whose preferred setting depend on the type of terminal. Then, it quits to top level and executes whatever is in q-reg ..L (unless it is 0). Init files: Whenever TECO is started for the first time, it checks for a file ; TECO, for a file ;* TECO, and then for the file .TECO.;* TECO. The first one found is executed as TECO commands. The last of those files is the default init file. The other two would be personal init files. The personal init file can do whatever you want. The only thing the default init file does is interpret command lines from DDT as follows: ":TECO FOO BAR " typed at DDT causes "ET FOO BAR  EI ER Y" to be done by TECO -- that is, TECO starts editing FOO BAR. ":TECO FOO " edits FOO > . Because COM:.TECO. (INIT) sets FS FNAMSY temporarily. ":TECO  " typed at DDT executes " ET  ". A user's own init file should interpreted the JCL by reading it in with the "FJ" command. It may have any command format it wishes except that it should always respond to ";" in the JCL by flushing the JCL (do "@^K^W:JCLP^V") and loading and executing 's init file. See the default init file for how to do those things. Dumped macro packages runnable from DDT often also have init files. Such packages should use FS XUNAME and FS HSNAME to determine init file names the same way TECO does. Journal Files TECO can write a journal file describing all the commands typed by the user. If the system crashes, the user can replay the journal file later so that his work is not lost. The TECO program starts writing a journal file by doing FS JRN OPEN. This opens the file for output, using the default filenames. TECO automatically writes into the file representations of all command characters read from the terminal. To close the journal file, use :FS JRN OPEN. To see whether a journal file is being written, look at the value of FS JRN OUT (it is -1 in that case). Note that no output is ever written in a journal file while another journal file is being replayed. The TECO program requests the replaying of a journal file by doing FS JRN EXECUTE. This opens the file using the default filenames. When TECO is ready to read more commands, they will be read from the journal file until the file is exhausted, or the user types a ^G on the terminal, or the TECO program does :FS JRN EXECUTE to close the file. FS JRN IN is -1 when a journal file is being replayed. Each command character is represented by a pair of characters in the journal file. This is so that the Control and Meta bits can be represented in full generality. A character with neither the Control nor the Meta bit is represented in the journal file by a space followed by the character itself. A Control character (200+nnn) is represented by an "^" followed by the non-control character. A Meta character (400+nnn) is represented by "+" followed by the non-meta character. A Control-Meta character is represented by "*" followed by the basic character. Thus, Meta-F is represented by "+F". There are a few exceptions to the rule above. A CR character (015) is represented by the two characters CRLF. This makes the journal file look much nicer. The Help character is represented by "??". Other constructs which can appear in a journal file are ^G (007) to represent a quit command; comments, which start with semicolon and end with CRLF, and are ignored when replaying the file; and program commands, which start with a colon and whose format is up to the TECO program. When a ^G or a colon is seen in a journal file being replayed, the FS JRN MACRO is called, and given the character (^G or colon) as an argument. In the case of ^G, the macro should do 1F[JRN INHIBIT and then call ^R so that the user can fix up for any timing errors that occurred in quitting, and when the ^R returns it should do -1FS QUIT to replay the quit. Colon represents the start of program-specific information; the program which wrote the journal file and the one which replays it must agree on what format the following information takes. The information can be read using the FS JRN READ command. One specific colon-sequence is defined by TECO: colon followed by a ^G indicates a quit which happened synchronously, while TECO was waiting for input. Such a quit does not need a recursive ^R for the user to fix things up because everything is guaranteed correct. In this case, the FS JRN MACRO should just replay the quit with -1FS QUIT. Normally, journal files are written and read automatically. However, the TECO program may wish to add extra information to the journal file. This could be comments designed to aid humans who look at the journal file, or it could be information intended to be used in replaying the file properly. In that case, it should take the form of a colon followed by information to be read in by FS JRN MACRO later. In either case, the information is written by means of the FS JRN WRITE command, which accepts a character or a string. TECO's Data Structures (Strings, Buffers and Qvectors) TECO has two different data structures for storing sequences of characters: strings, and buffers. They differ in what operations are allowed on them, and how efficient they are. Strings have less overhead than buffers, but as a penalty they are not easily altered. Once a string has been created, its contents usually do not change; instead one might eventually discard the string and create a new one with updated contents. The sole exception is F^E, which makes it possible to alter characters in a string (but not to insert or delete). Commands which "put text in a q-register" all do so by consing up a string and putting a pointer to it in the q-register. Buffers are designed to be convenient for insertion and deletion. Each buffer has its own pointer, and its own virtual buffer boundaries, which are always associated with it. The contents of a buffer can be accessed just like the contents of a string (in which case only the part between the virtual boundaries is visible), but it can also be "selected" and then accessed or altered in many other ways: insertion, deletion, searching, etc. Each buffer also has a flag which is set nonzero whenever the buffer's contents are changed; it can also be set by the user with FS MODIFIED. A buffer has about 42 characters of overhead, and the number of buffers is limited (about 40). Initially, there is only one buffer in a TECO (pointers to which are initially found in q-registers ..O and ..Z), and new ones are only made when explicitly asked for with F[ B BIND, FS B CONS or FS B CREATE. Strings and buffers are normally represented in TECO by pointers. When a q-register "contains" a string, it actually contains a pointer to the string (see the sections on internal format for details). If q-register A contains a string, QA returns the pointer, which can be stored into q-register B; then QB and QA both point to the same string. The command :I* returns a pointer to a newly consed up string containing . :G can be used to extract a substring (which is copied, not shared). The commands :\, :F6 and X* are also useful for creating strings. A buffer is selected by putting a copy of a pointer to it into q-register ..O. TECO has a garbage collector, so that if all pointers to a buffer or string are eliminated, the storage it occupies will eventually be reclaimed. Most of the space occupied by a buffer can be reclaimed explicitly with the FS B KILL command; the buffer is becomes "dead", and even though pointers to it may still exist, any attempt to use them to select the buffer or examine its contents will be an error. Vectors of objects can also be represented in TECO, with either buffers or qvectors. Buffers can be used to as vectors of numbers, while qvectors are used as vectors of arbitrary objects (numbers, or pointers to strings, buffers or qvectors). The difference is due to the fact that the garbage collector knows that the objects in a qvector might be pointers and therefore must be marked, while the objects in a buffer cannot be pointers and are ignored. The words in a buffer or q-vector can be accessed easily with subscripted q-register names; if QA contains a q-vector, then Q:A(0) is its first element. To access the elements in hairier ways, you can select the buffer or q-vector and the insert or delete, etc. Q-vectors are created by means of FS Q VECTOR. The buffer block, and what buffers contain (and the gap): The current buffer is described by the 7-word "buffer block" which contains these variables: BEG char addr of start of buffer, BEGV char addr of lower buffer boundary, PT char addr of pointer, GPT char addr of start of gap, ZV char addr of upper buffer boundary, Z char addr of top of buffer, EXTRAC # chars in gap. (next come 2 words used by the communication protocol. See below). MODIFF nonzero if buffer has been modified. RDONLY value of FS READ ONLY for this buffer. Note that all character addresses normally used in TECO have BEG subtracted from them; "B" returns BEGV-BEG; "Z", ZV-BEG; "FS Z", Z-BEG; ".", PT-BEG; "FS GAP LOCATION", GPT-BEG. "FS GAP LENGTH" gives EXTRAC. The actual value of BEG is available as "FS REAL ADDRESS". GPT and EXTRAC describe the "gap", a block of unused space in the middle of the buffer. The real amount of space used by the buffer is Z-BEG+EXTRAC. BEGV, PT, Z and ZV are "virtual" addresses in that they take no account of the gap. To convert a virtual address to a real one, add EXTRAC to it if it is greater than or equal to GPT. Real address 0 refers to the first character in word 0; real address 5 refers to the first character in word 1, etc. It is OK for the superior to alter those variables or the contents of the buffer, if TECO is between commands or has returned because of ^K, FS EXIT or ^C; except that BEG should not be changed and the sum of Z and EXTRAC (the real address of the end of the buffer) should not be changed, unless appropriate relocation of other buffers and TECO variables is undertaken. TECO programs need not worry about the gap, except for efficiency reasons or when communicating with machine language programs, and they need never convert character addresses to real addresses; TECO does all that. Strings - internal format: A string containing characters takes up +4 consecutive characters in TECO. It need not start on a word boundary. The first four characters are the string header; the rest, the text of the string. The header starts with a rubout. The second character is &177; the third, (/200)&177; the fourth, /40000 (numbers in octal). Buffers - internal format: A buffer consists of a buffer-string, which points to a buffer frame, which points to the buffer's text. The buffer-string is similar to a string, and exists in a string storage space, but begins with a "~" (ASCII 176) instead of a rubout. It has only three more characers; the second is &177; the third, (/200)&177; the fourth, /40000; being the address of the buffer frame. The buffer frame is a seven-word block whose purpose is to save the buffer block for buffers which are not selected. While a buffer is selected, the buffer frame contents may not be up to date. The first word of the frame contains a few flag bits in the left half. The sign bit will be set to indicate that the block is in use as a buffer frame. The 200000 bit is the GC mark bit and should be ignored. The 100000 bit, if set, indicates that the buffer is really a qvector. The 40000 bit is the "buffer modified" flag. These bits are only in the buffer frame, not the buffer block (BEG). Buffer and string pointers - internal format: When a q-reg is said to hold a buffer or a string, it really contains a pointer to the buffer or string. The pointer is in fact a number, distinguished from other numbers by its value only! A range of the smallest negative numbers are considered to be pointers (this is why QAUB copies a string pointer from QA to QB without any special hair). Numbers which are pointers are decoded by subtracting 400000000000 octal (the smallest negative integer) to get a character address. This may either be the exact address of a character in pure space (what :EJ loads into), or the relative address of a character in impure string space (what "X" allocates within. The char address of the start of impure string space is held in location QRBUF). In either case, that character should be the rubout beginning a string or the "~" starting a buffer-string. If the number, thus decoded, does not point within either of those ranges, or doesn't point at a "~" or rubout, then it is not a pointer - just a plain number. For example, 400000000000.+(FS :EJPAGE*5*2000.) is a string pointer to a string whose first character is at the very beginning of the last :EJ'd file. If the file has the proper format (see "strings" above), that number may be put in a q-reg and the string then executed with "M" or gotten by "G", etc. The file might contain a buffer-string except that causing it to point to a legitimate buffer frame would be difficult. Making it point to a counterfeit buffer frame inside the file would lose, since TECO tries to write in buffer frames. Low Bits: On ITS, the low bits of the words of a "text" file are generally ignored, but on other systems such as BOTTOMS-10 any word whose low bit is 1 is effectively not present in the file. Because of this, TECO attempts not to turn on the low bits of files. However, for efficiency's sake, low bits are not cleared in files when they are read in; also, you can easily set low bit explicitly using FS WORD or U:(). If you wish specifically to clear the low bits of all the words of the buffer, you can do it as follows: J 0I ZJ 0I JD ZJ-D. On the other hand, when you have numeric data in a buffer, stored in words instead of as text, you must be careful to avoid operations which can clear the low bits of the words. Anything which moves text except on word boundaries can shuffle the positions of the characters in the words, and the low bits will be misplaced if not also cleared. You can avoid such problems if you never insert or delete characters except in groups of 5 or multiples of 5, starting at positions which are multiples of 5. In this context, note that 5,0I will NOT clear the low bit; you must do 0,.-5FS WORD or 0U:..Q() (or something else suitable) to do that. How superiors can put text (and other things) into TECO: A standard protocol for communication from a superior to TECO is hereby defined, which allows the superior to request space in the buffer for inserting text, or request that a file be loaded and a certain function be found. Macro packages may supply functions to handle the requests instead of TECO's default handler. A superior can make a request whenever TECO has deliberately returned control (by a ^K valret, FS EXIT or a ^C) by restarting TECO at a special place: 7 plus the address of the "buffer block", which address can be found in accumulator 2 at such times. Save the old PC before setting it, since you must restore the PC after the request is handled. The word after the starting location (8 plus the buffer block address) is used for an argument. There are two types of requests. If you wish to supply text for TECO to edit, the argument should be the number of characters of text you need space for (it may be 0). In that case, TECO will return (with an FS EXIT) after making at least that much space in the buffer, after which you should restore the PC at which TECO had stopped before you made the request. You can then insert the text in the buffer and restart TECO. If you want TECO to read in a file, supply a negative argument and be prepared to supply TECO with JCL, when it asks with the standard .BREAK 12, describing what it should do. When TECO does a .BREAK 16, (FS EXIT) you can assume it has done its work, and should restore the old PC. The formats for the JCL string are , ,, and ,. A decimal number should be the address within TECO of the place to start editing. A function name can be anything that isn't a number, and its interpretation is not specified. TECO macro packages can supply a handler for requests from the superior by putting it in FS SUPERIOR. It will receive the argument describing the type of request as its numeric argument (^Y), and can read the JCL with FJ and do an FS EXIT when finished. If FS SUPERIOR is zero, TECO's default actions will be taken Note that TECO's default handling of a request to load a file is to do nothing. TECO's character sets: (numbers in this section are in octal) The most important TECO character sets are ASCII (7-bit) and the 9-bit TV set. The contents of all files, strings, and buffers, and thus all TECO commands, are in ASCII; 9-bit is used only for terminal input. Here is how TECO converts between character sets: 14-bit to 9-bit conversion when characters are read in: When a character is actually read from the terminal, it is in a 14-bit character set which contains a basic 7-bit code, and the control, meta and top bits (also shift and shift- lock, which are ignored since they are already merged into the basic 7-bit character). TECO converts it to 9-bit as follows: if top is 0, and the 7-bit character is less than 40 and not bs, tab, LF, CR or altmode, then add control+100; then clear out top, shift and shift-lock. Thus, TV uparrow comes in as top+013 and turns into 013; TV control-K comes in as control+113 and stays control+113; TV "VT" comes in as 013 and turns into control+113; TV control-VT comes in as control+013 and becomes control+113; non-TV control-K comes in as 013 and becomes control+113; TV control-I comes in as control+111 and stays control+111; TV "tab" comes in as 011 and stays 011; TV control-tab comes in as control+011 and stays control+011; non-TV "tab" or control-I comes in as 011 and stays 011. The character 4110 (Top-H) is the HELP character; it is handled specially. It is not changed, even when any other character would be converted to 9-bit or 7-bit. It is always returned as 4110. However, if FS HELP MAC is nonzero, then 4110 typed AT ANY TIME will cause FS HELP MAC to be run. When FS HELP MAC is run, the 4110 is otherwise ignored, so TECO will continue to wait for input (unless FS HELP MAC sets FS REREAD to supply some). Only when FS HELP MAC is zero will 4110 ever be returned to the user. ^R ignores 4110 (except for running FS HELP MAC). 9-bit to ASCII, when TECO wants to read an ASCII code: input read in using "@FI", or read by the ^R-mode comand dispatch, is used as 9-bit. However, when input is read by "FI", or by the "^T" command reader, or by TECO top level, it must be converted to ASCII as follows: meta is thrown away; if control is 0 then nothing changes; otherwise, control is cleared and the following actions performed on the 7-bit character that is left: rubout stays the same; characters less than 40 stay the same; characters more than 137 have 140 subtracted; characters 100 to 137 have 100 subtracted; all others are unchanged, except for 40 (Space) which becomes 0 (^@). Thus, control+111 (TV control-I) becomes 011; control+011 (TV control-tab) becomes 011; and 011 (TV tab, or non-TV control-I) stays 011. Similarly, TV uparrow, TV "VT", TV control-K and non-TV control-K all become 013. ASCII to 9-bit in FS ^RCMACRO and FS ^R INIT: The ^R command dispatch table is indexed by 9-bit characters. For compatibility with the time that it was not, the commands FS ^R CMACRO and FS ^R INIT, when not given the atsign modifier, accept an ASCII argument, and try to have the effect of referring to the definition of that ASCII character - in fact, they convert the ASCII character to 9-bit and then index their tables. The conversion is as follows: if the character is less than 40, and is not bs, tab, LF, CR or altmode, then add control+100. Thus, 013 (^K) becomes control+113 (TV "VT" or control-K, not TV "uparrow"), which is just right. Tab, etc. have a harder time doing the right thing, since both 011 control+111 are plausible ways that the user could type what corresponds to ASCII 011. The solution chosen is to leave 011 ASCII the same in 9-bit, since the ^R-mode definition of control-111 is to use 011's definition. The initial ^R-mode definitions of all 9-bit characters: All characters whose bottom 7 bits form a lower case letter are defined to indirect through the corresponding upper case character. Their definitions are all 40,,RRINDR, where RRINDR is the indirect-definition routine, and 40 specifies the character 40 less. Control-BS and Control-H indirect through BS, and similarly for Tab and LF. Control-CR and Control-Altmode (but not Control-M and Control-[) indirect through CR and Altmode. An isomorphic indirection-pattern exists for meta characters. Control-, Meta- and Control-Meta-digits all accumulate into the numeric argument. Control-, Meta- and Control-Meta-Minus-sign all set the 4 bit in FS ^R ARGP, thus negating the next command's arg. All other meta characters are self-inserting. A few (mentioned above) are self inserting because they go indirect through other meta characters. All non-control non-meta characters, except for CR, altmode and rubout, are self-inserting. CR inserts CRLF; altmode leaves ^R-mode; rubout deletes backwards. Of the rest, ^H, ^I and ^J are defined to insert themeselves straight away, while the rest are defined to be "normal" and do whatever FS ^R NORMAL and FS ^R REPLACE say. Control-rubout has its own special routine, which deletes treating spaces as if they were tabs. Control-digits update the numeric arg for the next command. All other control characters not in the range control+101 through control+135 are errors. Control-M inserts just a CR. Control-[ is an error. The remaining control characters from control-101 to control-135 do what the ^R command table says, or else are errors. Neat hacks that are frequently useful: 1) To take an absolue value, use ^@^@. -1^@^@ and 1^@^@ are both 1. This assumes that there is no pre-comma argument. 2) When there is just a pre-comma argument, :^@ will make it a post-comma argument instead. There will be zero as a pre-comma argument, but another ^@ will flush that. Thus, :^@^@ gets a pre-comma argument as a post-comma argument with no pre-comma. If there is a post-comma argument already, start with *0 to clear it first, giving *0:^@^@. Since many commands ignore pre-comma arguments, simply :^@ may be enough. 3) ",0^@" negates its argument, like "*(-1)". 4) The easiest way to compute the maximum of two quantities is with F^@, as in QA,QBF^@. This, however, returns the other one as a pre-comma argument. For the minimum as a post-comma arg, add :^@. TECO program writing standards: 1) Each line that doesn't begin inside a string argument should be indented with at least one space, preferably with a number of spaces indicating how deep in conditionals and iterations it is. 2) The semantic content of one line of TECO program should be no greater than that of one line of any other language, if the program is to be understandable. in other words, break lines frequently - and put a comment on each line. There should be spaces between logical groups of commands, every few characters, as in "3K J IFOO", which also shows how long a line should be. 3) The standard way to write a comment is to make it look like a tag: !!. 4) Follow value-returning commands with "W"'s or CRLFs when the value is not used for anything. 5) An example of a well-commented TECO program is RMAIL. See EMACS1;RMAILX > and RMAILZ >. Note that these are written in EMACS compressor format. TECO program debugging aids: 1) Trace mode causes all TECO commands to be typed out as they are executed. See the "?" command. A good technique is " 1F[TRACE MA" for running q-reg A in trace mode. 2) FS STEP MACRO causes TECO to pause at each line, displaying the buffer and waiting for input before continuing execution. This works best when lines are short, as they ought to be anyway. 3) Break-loops on errors are available, by setting FS *RSET to nonzero, or by using Q..P. 4) It is easy to edit a "FTHere I am" or "Q0=" into the program and re-execute it. 5) If the standard top level is in use, "?" typed in after an error will cause a printout of a short section of command string up to the point of the error. User break loops in Q..P can use FS BACKTRACE to do similar or better things. 6) Setting FS .CLRMODE to 1 disables the ^L and F+ commands, which normally clear the screen. This may be useful for debugging programs that wipe out their trace output.  File: TECMAN Node: Fancy Up: Concept TECO COMMANDS: Various operations upon the buffer -- such as sorting, casification, LISP operations and other semi-AI-type actions. >>>>>>>>>>>>>>>>>>>> Sorting buffer <<<<<<<<<<<<<<<<<<<< ^P alphabetic (ASCII) or numeric sort command. The entire buffer, or the part within the virtual boundaries, is sorted, after being divided into sort records (i.e., things to be sorted) on the basis of the arguments given to the command in the form of three TECO command strings following the ^P, separated by altmodes (Notes: (1) two successive null args will result in a premature end of command input, so use spaces where needed; (2) a dollar sign in any arg will be replaced by an altmode; (3) the three args will be left in q-regs ..0, ..1, ..2). The three expressions are used to divide the buffer into sort records, each of which has a sort key. A sort key may be any substring of the record, or it may be a number. The records and keys are found as follows: 1. The pointer is moved to the beginning of the buffer, which is the beginning of the first sort record. 2. The first command string is executed. If the key is to be a substring of the record, this command string should leave point at the beginning of the key. If the key is to be a number, it does not matter what this command string does. 3. The second command string is executed. If this command string returns a value, that value is the key. Otherwise, this command string should leave point at the end of the key. 4. The last command string is executed. This should move the pointer to the end of the sort record, which is also the beginning of the next record. 5. If step 3 or 4 leaves the pointer at the end of the buffer, the creation of sort records is complete, and the sort takes place. Otherwise, go back to step 2. Sort records and keys may be variable length. No character (i.e., a shorter key) sorts before ^@, and keys are considered left-justified for the comparison. Numeric keys are always "less" than any string keys. Failing search commands are not errors while scanning for sort records, unless the FS S ERROR flag is nonzero. It is recommended that this flag be set, since code is easier to debug if all searches which are supposed to be allowed to fail have an explicit colon. There is nothing to prevent overlapping records from being specified; the sort will copy each record so the overlap region will be duplicated. Insertion and deletion are allowed but know that TECO remembers the boundaries of records and keys as character numbers, so deleting chars from a record already delimited will shift chars from the next record into it, etc. The sort is stable. :^P sorts in reverse order. If FS ^P CASE is nonzero, ^P ignores case; that is, it sorts lowercase letters as if they were the corresponding uppercase letters. >>>>>>>>>>>>>>>>>>>> Command Dispatching <<<<<<<<<<<<<<<<<<<< F^A: ,F^A this command scans the range of the buffer from to using the dispatch table in q-register . That is, each character found in the buffer during the scan will be looked up in the dispatch table and the specified actions will be performed. The dispatch table should be a string or buffer with at least 128*5 characters in it - 5 for each ASCII character. Each character seen has its ASCII code multiplied by 5 to index into the table, and the 5 chars found there are executed as TECO commands. When that is done, the char that was found in the buffer is in Q..0 as a number, point is after the character if forward, before if backward, Q..3 holds the dispatch table that was in use (so that the dispatch commands can change it if they wish) and Q..2 holds the end of the range to be scanned. For forward scans, it is in the form of the distance between the end of the range and Z; for backward scans, it is the distance between the end of the range and B. Thus, deleting or inserting characters never requires changing Q..2. The use for changing Q..2 is moving the end of the range - for example, stopping the scan early (do ZU..2). Nothing forbids the macro to change point - that is a fine way to skip over characters that are "quoted" by others. For efficiency, if the first of the 5 chars in the dispatch table is a space, the 5 are not macroed. Instead, the second character, minus 64, is added into Q..1, and the third is specially decoded. " " means no action; this feature makes to easy to skip over most chars, keeping track of horizontal position. Other permissible third characters are "(" and ")". Their use is in counting parens or brackets. "(" means that if the scan is backwards and Q..1 is positive, the scan should terminate. ")" means that if the scan is forward and Q..1 is negative, the scan should terminate. If an open-paren-like character is given the dispatch " A( " and the close is given " _) ", the same dispatch table may be used to find the end of a balanced string going either forward or backward. "F^A" may be given 0 or 1 arg - it turns them into 2 the way "K", "T", etc. do. ,@F^A the atsign modifier causes the scan to go backwards. ,:F^A scans like F^A but expects its dispatch table to be a q-vector containing string pointers. As with ordinary F^A, to each ASCII character there corresponds a word of the dispatch table, but this word should normally contain a pointer to a string to be executed when the character is seen. Thus, you can macro strings longer than 5 characters without having to use up lots of q-registers to hold them. Alternatively, the dispatch table word may contain five characters starting with a space, which are interpreted as in an ordinary F^A. Thus, simple characters that need only to be skipped over are no slower than in an ordinary F^A. The use of q-registers ..0, ..1, ..2 and ..3 is just like that in ordinary F^A. >>>>>>>>>>>>>>>>>>>> LISP-oriented <<<<<<<<<<<<<<<<<<<< F^F: F^F is the forward-only S-expression parser. ,F^F parses LISP s-expression from the starting value of point to address , assuming that the state at the starting point is , and returns the state at the ending point, leaving point there. A "state" includes all the essential information about the surroundings of a given spot in a LISP expression. Its right half is the depth in parentheses. Its left half is made up of several bits: 100,, => this spot is inside a comment. 4,, => this spot is between vertical bars. 2,, => the preceding character is an atom constituent or slash, or is slashified, and we're not in a comment. 1,, => the following character is slashified. Usually it is fine just to use zero for all the bits. Using a negative number as an initial state specifies a negative paren depth and makes all the bits zero. Several Q-registers are set up on return: Q..0 receives the address of the last comment-start or vertical-bar open encountered. It is useful when you find that the ending point is inside one or the other. Q..1 receives the address of the last unmatched "(", or -1 if there was none encountered. Q..2 receives the address of the start of the last complete s-expression (ie, its termination was passed), or -1 if no s-expression begun has terminated. Scanning stops either at address , or when the parenthesis depth becomes zero. Aside from this termination condition, the depth is used only as a relative quantity, so you can choose the initial depth to obtain the desired termination condition, or make it far away from zero to disable the feature. To use F^F to move forward, choose an initial parenthesis depth that will make it stop at the appropriate place. To use F^F to move backward, go to the beginning of a top-level s-expression, or the beginning of the buffer, and scan forward to the point you are trying to move from. The value in Q..1 or Q..2 will tell you where to move to. To determine whether a line has a comment on it, scan from such a known point to the end of that line (before the CRLF). When the F^F returns, it will tell you whether that point is inside a comment. If it is, Q..0 will address the semicolon. :F^F is like F^F, except that it stos scanning if it passes the start of an atom. It also stops when plain F^F stops. It is useful for such things as making sure that an F^F doesn't run away from you because there was a very long s-expression where you expected an atom. >>>>>>>>>>>>>>>>>>>> Operations on variable table <<<<<<<<<<<<<<<<<<<< F^G: ,F^G Performs a local variable value swap on an EMACS-format buffer table . should be the index in (in words) of the entry whose local variable values are to be swapped. is the offset within the entry of the first local variable. The number of local variables is determined from the length of the entry, which is the first word of the entry. Each local variable is described by two words: the first is the name; the second, the swapped-out value (the global one, for the selected buffer; the local one, for other buffers). The name of a local variable is either a string, for a QFOO-type variable, or the :FSQPHOME of a short-name q-register or ^R-mode character definition or FS flag. Each swapped-out value is exhanged with the value cell of the variable, found by looking the name up in q-reg ..Q if it is a string, or by using it as an address if it is a number. A number must represent a ^R character, a q-register, or an FS flag. Suitable numbers can be obtained by pushing the location involved and then looking at -1:FS QP HOME: [A -1:FS QP HOME( ]A) returns the address of q-register A; [^^@ -1:FSQP HOME( ]^^@), that of the definition of ^@; F[^R REPLACE -1FS QP HOME(F]^R REPLACE), the code for FS ^R REPLACE. To turn such an address into a string containing the name of the q-register, use @FS QP HOME. The @ and : flags make F^G transfer data only onw way instead of swapping. @F^G copies the current values into the local symbol table, but does not change the current values. :F^G copies from the local symbol table setting the current values. >>>>>>>>>>>>>>>>>>>> Text Handling <<<<<<<<<<<<<<<<<<<< FA performs text justification on a range of the buffer specified by 1 or 2 args (as for K, T, commands, etc.). The idea is that whenever you edit a paragraph, you use FA or a macro that uses FA to re-justify it. The line size is kept in FS ADLINE . A CRLF followed by a CRLF, space or tab causes a break. So does a CRLF, space or tab as the first character of the text being justified. An invisible break can be produced before or after a line by beginning or ending it with space-backspace. CRLFs that do not cause breaks are turned into spaces. Excess spaces that wind up at the end of a line are deleted. Other excess spaces are retained. Thus, to win, you should insert spaces after all ends of sentences which are at the ends of lines, before you call FA. You might insert spaces at the ends of all sentences, but you can presume that they are already there, when desired, in the middle of the line. Spaces at the beginning of a line are treated as part of the first word of the line for justification purposes, to prevent indentation of paragraphs from changing. The last part-line of stuff to be justified is only filled. Tabs prevent justification of what precedes them on a line; to prevent filling, you must put in a break (use sp-bs). I suggest using "FA" in the following macro: [0 Z-^YU0 ^XJ <.,Z-Q0FB. ^O? ; :0L I > !""Make sure .'s and ?'s at end of line have spaces! ^X,Q0FA !actually justify! ]0 If you want indented paragraphs, simply indent them the right amount when you type them in. "FA" will leave the indentation alone. "FA" knows about backspace. Sometimes it is desirable to put a space in a word. To do that, use space-backspace-space. @FA like "FA" but only fills (doesn't justify) FC takes arguments like K and converts the specified portion of the buffer to lower-case. Only letters are converted. @FC converts a specified portion of the buffer to upper case.  File: TECMAN Node: Deletion Up: Concept TECO COMMANDS:DELETION D delete arg chars to right of pointer. If arg<0, delete to left of pointer. K if no arg or one arg, kill chars from pointer to argth line feed following. (no arg, arg=1; negative arg, back up over 1-arg line feeds, space over last line feed found, and kill from there to pointer. A colon after the arg will move back over carriage return+linefeed before deleting. If no carriage return exists, TECO will only move back one character. There is an implicit line-feed at the end of the buffer. (note: this is the action of colon for all commands which take one or two args like K.) ,K kills characters through -1. The pointer is moved to . @K is like K, but only LF's preceded by CR's are recognized.  File: TECMAN Node: Real-time Up: Concept TECO COMMANDS: Real-time (dynamic) commands, also known as ^R MODE. ^R real time edit feature, intended mainly for display terminals. The position of the pointer is represented by the terminal's hardware cursor, rather than by any printed characters (^R ignores the contents of ..A, except on printing terminals). All non-control-non-rubout characters are normally self inserting; the others are normally editing commands. The user may redefine any character by means of the FS ^RCMAC flag. In ^R mode echoing is turned off, so typed-in characters manifest themselves only by their effect on the displayed buffer contents (but see FS ^R ECHO). Any command may be given a numeric argument, which most commands (including all characters that insert themselves) treat as a repetition count. If no argument is specified, 1 is the default, but commands can distinguish between an explicit 1 and a defaulted 1. The argument is computed as follows: = * (4 ** ) where is the explicit argument, if any, or 1 otherwise. An explicit argument is given with ^V or by control-digits. is initially 0 and incremented by ^U. All commands except argument-setting commands discard their arguments even if they don't use the arguments. Three flags contain the argument data: FS ^R ARG contains the explicit argument, if any, else 0; FS ^R EXPT contains the exponent of 4; FS ^R ARGP, if zero, indicates that no arg has been specified (neither the explicit arg nor the exponent of 4); if 1, indicates that only an exponent of 4 has been specified, and the basic arg is still 1; if 3, indicates that an explicit arg has been specified. The 4 bit, if set, indicates that the argument should be negated (Control-Minus sets this bit) All three are zeroed after any command that doesn't identify itself as an argument setting command by clearing FS ^R LAST. Any character may have a program associated with it, using the FS ^RCMACRO command. If that is done, when that character is typed, TECO will execute the program instead of inserting the char or using it as a built-in command. The definition of a character may also be treated as a q-register in the "Q", "U", "X", "G", "[", "]", "M" and "FQ" commands; see "Q" for directions. When the program is executed, q-reg ..0 will contain the character being handled. When errors take place inside ^R, or in macros called from ^R, after printing the error message TECO returns control to the innermost invocation of ^R (unless FS *RSET or ..P is nonzero). The same thing happens for quits. See ..P. One may wish to have a mode in which most editing commands are disabled, and most characters that are normally editing commands are self-inserting instead. The FS ^RSUPPRESS flag, when nonzero, suppresses all built-in commands except rubout and all user defined commands whose definitions do not begin with "W" (since "W" at the beginning of a macro is a no-op, the only reason to have one there is to prevent suppression). When a character is suppressed as a command, it becomes self-inserting. An additional feature is the FS CTL MTA flag; when it is negative, all control-meta-letters (and ctl-meta-[, ], \, ^ and _) have their definitions suppressed; this mode is useful when editing TECO commands. In "replace mode", printing characters overlay a character instead of making the line longer. Replace mode is controlled by FS ^R REPLACE, which see for more details. A more general facility for changing what ALL printing characters do is FS ^R NORMAL. If this is nonzero, it counts as the definition of all "normal" characters. That is, the definition which all printing characters initially have says to do whatever FS ^R NORMAL directs, and otherwise (if it is 0) insert or replace. You can redefine all "normal" characters whose Lisp syntax in ..D is ")" by putting a function in FS ^R PAREN. This function will be executed IN ADDITION to the actions for handling all "normal" characters. This is good for something to point out the location of the matching open-parenthesis. Normal characters which you don't redefine in one of those ways will sometimes be subject to system echoing, when that is implemented. This improves efficiency so it is done whenever it is safe. Characters which have been redefined and thus made not normal cannot be echoed by the system. If you redefine what "normal" means by making FS ^R NORMAL nonzero, system echoing will be turned off entirely. Sometimes Space is redefined with a definition which never does anything but insert a space unless the horizontal position is beyond a certain point (at which point it will typically break the line). Then it is desirable to enable spaces to be echoed when the cursor has not reached that column. This can be done by means of the FS ^R EC SD flag. Set it to the definition which Space has in that case, and set FS ADLINE to the column up to which it is safe to echo Space. Then, when Space actually has that definition, the system will be told to echo spaces but only up to that column. By setting FS ^R INHIBIT nonzero, you inhibit display updating. But ^R still remembers what is necessary, and as soon as FS ^R INHIBIT is zero again the updating will be done. Conversely, you may wish to inhibit the feature which causes redisplay to be suspended when input is available. Setting FS D FORCE nonzero does this. The ^R-mode input dispatch table is actually indexed by 9-bit TV character code. Each 9-bit code can be redefined. The list of ^R-mode initial definitions that follows refers to the characters obtainable on non-TV's - in other words, the 9-bit characters which are the results of reading in the 14-bit codes 0000 through 0177, which are precisely the 9-bit characters which are equivalent to some 7-bit ASCII character. A subsystem which is not TV oriented need not worry about the 9-bit character set; by using FI, and FS ^RCMACRO always without the atsign modifier, it can handle ASCII characters throughout. TECO will automatically do the conversion to and from 9-bit characters on TV's. For those who wish to handle the 9-bit character set, the definitions of all 9-bit characters are listed in the section "TECO's character sets", along with the appropriate conversions between character sets. One may wish to have some operation (such as filing the buffer away) performed every so often while in ^R mode. See "..F" for how to do this using the "secretary macro" feature. FS ^R DISPLAY can be set to a macro which will be run every time ^R is about to do nontrivial redisplay. Although ^R mode is intended for display terminals, the creation of large macro-systems intended for use with ^R mode has made it necessary for ^R to work at least marginally on printing terminals. Since the physical cursor is not suitable, the ordinary TECO cursor is used (whatever is in ..A). The buffer is displayed only when the screen is "cleared", such as by giving the built-in ^L command. Also, unless FS ^RECHO > 0, characters actually read by the ^R-mode command loop are typed out, although echoing is still turned off. This echoing can be made to happen even on displays by making FS ^RECHO negative (this is unwise to do if there is no echo area). Setting FS ^R SCAN to nonzero causes ^R commands to try to imitate printing terminal line editors by echoing the characters that they insert/delete/move over. In this case, FS ^R ECHO should be set to 1. FS ^R MAX is the maximum size deletion or insertion which ^R will try to print in the fancy way. Note that ^R recognizes insertion, deletion, and cursor motion from the values returned by the user's command definitions - see the following paragraph. Macros and ^R - reducing redisplay: Whenever control passes from normal TECO to ^R (that is, when a ^R is executed, when a @V is executed within a ^R-mode macro, or when a ^R-mode macro returns), ^R must be able to update the screen according to the changes that have been made in the buffer since the last time ^R mode lost control. ^R can do that in a way that makes no assumptions, but that way is slow. If information is still available on what areas of the buffer were changed, that info can be passed to ^R in the form of numeric args, and ^R will save time by assuming the info to be correct. If the info is not correct, the screen will not be properly updated. The options are: no args - the usual case - means assume nothing. One arg means that the buffer has not changed, although the pointer may have moved. The actual value of the arg does not matter in this case. Two args should specify a range of the buffer outside of which nothing was changed. ^R will limit redisplay to that range if possible. ^R also knows what to do about macros that type text out; if Q..H is nonzero when ^R is entered or returned to, ^R will not do any displaying until it has read one character (and executed it, unless it is a space). If the selected buffer when you return to ^R is not the same one that was selected when ^R was previously in control, then it doesn't matter what args you give. If you like ^R mode, try: :I..G EL 90^S ^R :I..B Q..H"N 90^S ' ^R The commands are: Control-Minus negates the argument of the next command. Control-digits accumulate a numeric argument for the next command. Thus, control-5 ^N will move down five lines. ^A go to beginning of current line (0L). With argument, -1 L. ^B go back over previous character (R) ^C complements the state of the comment mode switch. Types "C" for comment or "T" for text at the bottom of the screen, to say what mode you're in. When in comment mode, the ^N and ^P commands begin by going to the end of the line and if the last character is a semicolon, deleting it and any preceding tabs. Then, after moving to the next or previous line, if the line has a semicolon in it the pointer will be left after the semicolon; otherwise the pointer will move to the end of line, and enough tabs will be inserted to move the pointer at least to the specified comment column, followed by a semicolon. Numeric argument is ignored. ^D deletes the next character after . (D) If FS RUBCRLF is nonzero, ^D before CRLF deletes both the CR and the LF. ^E moves to end of line (:L). With argument, :L. ^F goes forward over the next character (C) ^G flushes any numeric argument or case-shift, unsets the mark if it had been set, and resets the case-lock. When ^R is actually in control (as opposed to a macro running inside ^R), ^G's quitting action is suppressed, and ^G acts as a command instead. Thus, it does not flush any type-in. ^H (backspace) inserts itself. ^J (linefeed) inserts itself. ^K kills to eol (K). With arg, K. The text deleted is put in q-reg ..K. ^L redisplays the screen (used to recover from datapoint lossage). Chooses a new window. A numeric argument specifies the number of lines of buffer to display - useful on printing terminals. On displays, if only a part of the screen is being used at the moment, only that part is cleared. ^M inserts a carrage return-line feed. ^N goes to next line (L). With argument, L. ^O inserts a CRLF, then backs over it. "^Ofoo" is equivalent to "foo^M" but often requires less redisplay. With argument, inserts CRLFs and backs over the last. If you want to insert several lines in the middle of a page, try doing ^U^U^O before and ^U^U^K afterward. ^P goes to previous line (-L). More generally, -L. ^Q inserts the folling character directly, regardless of its meaning as a command. If the char isn't already in the input buffer, ^Q will prompt with a "Q" at the bottom of the screen. An argument to ^Q causes it to insert the same character times. ^Q is not affected by replace mode; the quoted character is always inserted. ^R causes the column the pointer is at to become the comment column. Argument is ignored. ^S reads a character and searches for it. "^SA" in ^R mode is the like "SA" in TECO. ^T sets the ^R-mode mark at the current pointer position. The mark is really the value of FS ^RMARK and is used by the ^X and ^W commands in ^R mode. If FS ^R MARK holds -1 there is no mark; that is the case initially and after any insertion, deletion or quit in ^R mode. Attempting to use the mark when there is none rings the bell. ^U increments the exponent-of-4 for the next command. This usually is the same as repeating it 4 times. Does not use any previous argument, but leaves it around for the next command. ^V sets the basic arg for the next command. The argument is composed of digits optionally preceded by a minus sign, echoed at the bottom of the screen and turned into a number in the current radix (FS IBASE). The first non-digit terminates the arg and is treated as a command. ^G will flush the argument. ^W kills everything between the current pointer position and the mark, putting the deleted text in q-reg ..K. If there is no mark, nothing is deleted and the bell is rung. ^X sets the mark at the current pointer position, and moves the pointer to where the mark had been; in other words, exchanges the mark and the pointer. Does nothing if there is no mark. Do this several times to see both ends of the range that a ^W command would delete. ^[ (altmode) terminates edit ^] reads a q-reg name and executes that q-reg as a macro. The q-reg should contain ordinary TECO commands, not ^R mode commands. The numeric arg to the ^] will be given to the macro which will see it as the value of ^Y (If no argument is specified, ^Y will be 1, but F^X will indicate that the macro had no argument). The macro may return values to ^R telling it which areas of the buffer may need redisplay (see below). If the macro is to return values, it should end with a space - otherwise, the values might get lost within TECO. Example: " .,( G..K .) " gets q-reg ..K and returns 2 values limiting the range of the buffer in which changes took place. ^? (rubout) deletes bacwards (-D). If FS RUBCRLF is nonzero, rubout when the pointer is after a CRLF deletes the whole CRLF. ctl-rubout deletes backwards like rubout, except that tabs are converted to spaces and the spaces are deleted one at a time. F^R reports to ^R that completely unknown changes to the buffer have taken place, and that ^R should not assume that any of the information it remembers from previous display is still valid. F^R is a no-op, to round out F^R with zero or two args, so that you can pass to F^R any args you might have returned to ^R, with equivalent results. ,F^R reports to ^R that the range of characters to has changes made in it, and needs to be redisplayed. This is like doing ,@V except that F^R never actually does the redisplay; it just causes it to be done at the next opportuntity. F^R should not be used unnecessarily. For example, once a macro uses F^R, it cannot be used on any buffer except the one the next ^R up is displaying. ,@F^R reports to ^R that screen lines through , not including , need redisplay. This is used for exiting minibuffers. It is very important that the text previously displayed on line be unchanged in the buffer and still belong on that line. :F^R asks ^R to verify that the window in FS WINDOW is still valid, and choose a new valid one if it isn't. This operation is extremely fast when the window is still valid, because it assumes that FS ^R VPOS is up to date. If you want it to assume nothing, do a plain F^R first. Normally, the previous window is kept if it is still valid. To insist on re-centering point, do -1FS WINDOW first to flush the old window. :F^R asks ^R to choose a new window putting point on line of the window area. is relative to FS TOPLINE. The old window is never re-used. FS ^R VPOS is not depended on. @:F^R is like :F^R, except that on a terminal with insert/delete line capability ^R will attempt to move text on the screen IMMEDIATELY so as to optimize redisplay later. The number of lines up or down to move the text is determined by assuming that FS ^R VPOS is valid. @:F^R is like :F^R, but moves text on the screen if possible.  File: TECMAN Node: Files Up: Concept TECO COMMANDS: File oriented E is the prefix for most operations on files. ^A,^X ^A or ^X may be used in a file specification as the first or the second filename to stand for the default first name. ^B,^Y ^B or ^Y may be used in a file specification as the first or second file name to stand for the default second name. ******************** Setting Default Names ******************** ET sets the default filenames to . :ET (Twenex only) does a GTJFN reading from the terminal, to provide filename completion, etc. The numeric argument is the left-hand flags for the GTJFN. The flag FS :ET MODE controls which filenames' default values are provided for the GTJFN. The pre-comma argument is the prompt string; on Tops-20 this is used for setting up a call to the COMND JSYS. On Tenex, it is simply typed out in the echo area; so this is the correct way to prompt when reading a filename. **************** Determine if file can be opened **************** E? tries to open , and returns 0 if successful. Otherwise, the value is the system error code which describes why the file cannot be opened. In any case, the file does not stay open, and the open input file if any is not interfered with. The file's reference date is not set. If the device is USR:, the job will not be created if it does not exist. ******************** Opening file for input ******************** ER opens for input. The "Y", "A" and "FY" commands in various forms may be used to read from the file. As soon as the file is no longer needed (eg, if all of it has been read), an "EC" should be done to close the input channel. "@Y" and "EE" do an automatic "EC". FS IF ACCESS, FS IF LENGTH, and FS IF CDATE make it possible to get or set various parameters of the file. ER is similar but specifies open-mode (actually, IOR 2). should be even!! =4 specifies image mode, which makes a difference for file directories. This is only meaningful on ITS. ,ER bits in are interpreted as follows: 1: opens an input file and does not change its reference date. This is defined to work on all operating systems. 2: opens an input file in "thawed" mode. This is probably only useful on Tenex, where it allows multiple readers of the file. EP does ER, then bigprints file name twice on device(s) open for writing. ******************** Reading data from files ******************** Y kills the buffer, then inserts one page from the current input file (until first formfeed or eof). Point is left at the beginning of the buffer. If reading is terminated by a ^L, the ^L will go in the buffer iff FS ^LINSERT is nonzero. (FS ^LINSERT is initially 0) The input file is not closed, even if eof is reached. To close the input file, use EC. However, EE does close the input file. Closing the input file is not necessary but will lighten the drain on system resources. Trailing ^C's or ^@'s just before eof are considered padding and are flushed. To do input without having any padding characters removed, use FY. The virtual buffer boundaries are understood. If no file is open, the buffer is left empty. Because Y is an easy command to be screwed by, and isn't really necessary since the A command exists, there is a way to disable it. See FS YDISABLE. @Y yanks in all the rest of the file. ^L's within the file go in the buffer. A ^L at the end of the file will go in the buffer iff FS ^LINSERT is nonzero. Trailing ^C's and ^@'s are conidered padding, and flushed. The input file is closed automatically. A if no arg, append next page of input file to current contents of buffer, i.e., like "Y" only don't empty buffer first. If virtual buffer boundaries are in use, the appended text goes just below the upper virtual boundary. Does not close the input file. :A appends lines of the file (but won't append beyond a page boundary). Uses the same conventions for throwing away padding as "Y" does. Does not close the input file. @A appends all the rest of the file. A cross between "A" and "@Y". Closes the input file. FY insert all that remains of the current open input file before point. Error if no file is open. The input data are unaltered; no attempt is made to remove padding or ^L's. If the transfer is on a word boundary in the file and in the buffer, word operations will be used, so this command is suitable for use with binary data. The input file is not closed - use EC for that. FY like FY, but inserts at most characters, or until EOF, whichever comes first. Note that characters of space are always needed, even if the file is not really that long; thus, 1000000FY to read in the whole file will not work. The input file is not closed. ******************** Opening file for output ******************** EI opens a file for writing on the default device. The filenames used will be "_TECO_ OUTPUT". When the output file is closed, it will normally be renamed to whatever names are specified. However, if the TECO is killed, or another output file is opened, anything written will be on disk under the name "_TECO_ OUTPUT_" :EI like EI, but uses the current filename defaults instead of "_TECO_ OUTPUT". This is useful for opening on devics which do not support rename-while-open fully, such as the core link. Use :EF to close the file without renaming it. @EI like EI, but opens an old file in rewrite mode if there is one, rather than creating a new file in all cases. Together with FS OFACCESS and FS OFLENGTH this can be used to update an existing file in arbitrary ways. However, what you really want to use is: @:EI like @EI but uses the default filenames rather than "_TECO_ OUTPUT". EW like EI but device specified by following text string rather than by a numeric arg. :EW like EW, but uses the specified filenames instead of "_TECO_ OUTPUT". This is useful for opening on devics which do not support rename-while-open fully, such as the core link. @EW like EW, but opens an old file in rewrite mode if the file exists, rather than creating a new file in all cases. Together with FS OFACCESS and FS OF LENGTH, this can be used to update an existing file in arbitrary ways. However, what you really want to use is: @:EW like @EW but allows filenames to be specified rather than using "_TECO_ OUTPUT". ******************** Writing data to files ******************** P output contents of buffer to open output file, followed by form feed (^L) if FS ^LINSERT is 0; clear buffer and read into buffer from file open for reading until next form feed or end of file. A single argument means do this that many times. The P command usually writes zero into the low bit of each word of the output file. If the @ flag is set, then outputting on word boundaries in the buffer and the output file outputs the low bits as they are present in the buffer. ,P output the characters in the range through to the output file. Do not change the buffer or read from the input file. PW outputs like P but does not clear buffer or do input. Takes arg, meaning do it arg times. ******************** Closing files ******************** EC close the input file, if any. This should always be done whenever an input file is no longer needed; otherwise, one of the system's disk channels will be tied up. @Y, EE and EX automatically do an EC. All other input operations always leave the input file open. EE like infinity P commands then EF and EC. EX (Twenex only) if a file is open for output, does EE, then instructs the EXEC to repeat the last CCL type command (load, execute, compile, debug). EF files output accumulated by PW and P commands with the name . may not contain a device or SNAME; they must have been specified when the file was opened (with EI or EW) and may not be changed. :EF files the output without renaming the output file. ******************** Directory oriented ******************** E^U displays in the usual manner the directory of the device specified in the string argument, or the default device. More precisely, reads the string arg and sets defaults, then does "^U". EL display in the standard manner the directory of the default device. This command does not use the user's buffer display macro; in fact, the buffer display macro might well use this command. EY like EL but specified device and SNAME. On Twenex, the entire string, if provided, is used, including wildcards, for the GTJFN. Also, on Twenex, a numeric argument specifies the JFNS format. EM insert in buffer file directory of the default device. On Twenex, any pre-comma arg specifies don't include author name, and a post-comma arg is passed to the JFNS call. EZ like EM but etc. **************** File renaming, copying, linking **************** EN renames the file to have the name . The device and SNAME may not be changed; they should not be specified in . E_ makes a copy of the file and names it . I/O is done in ASCII block mode. The currently open input and output files are not affected. :E_ is similar but transfers the date of the input file to the output file. @E_ puts the real filenames of the input file into the defaults before reading the output file name, making it easy to preserve the version number. EQ creates a link named pointing to the file . devices COM:, TPL: and SYS: are understood. (ITS only) An attempt to link to a non-disk device is an error. ED deletes . :ED deletes the currently open input file (ITS only). @ED on Twenex, deletes and expunges . On ITS, same as plain ED. ******************** Journal/Dump files ******************** EJ restores the complete environment (q-reg values, buffer contents, flag settings, etc) from the specified file, which should be in the format produced by @EJ. This restores all q-regs, buffers, and flags to what they were when the file was dumped. Exception: pure (:EJ) space is not changed, nor is FS :EJPAGE. After loading, TECO restarts itself, which implies that if a nonzero value was loaded into Q..L, it will be macroed. This is intended to be used in init files, for loading up complicated macro packages which would take a long time to load from source files. If the file isn't a dump file, or was dumped in a different TECO version, an "AOR" error occurs. @EJ dump all variable areas of TECO on the file open for writing (it must already be open), and file it under the specified filenames. One should not write anything in the file before doing "@EJ". Files written with @EJ can be loaded into a TECO with the EJ command, or they can be run as programs directly, in which case they will bootstrap in all the constant parts of TECO from the canonical place: .TECO.;TECPUR . They also contain indirect symbol table pointers to that file, so that attempting to load the symbols of an @EJ'd file will load TECO's symbols. If you @EJ a file TS FOO on your home directory, then FOO^K will always get you that environment. :EJ inserts the specified file into core, shareable and read-only, and returns a string pointer to the beginning of it. :EJ assumes that FS :EJPAGE points to the lowest page used by :EJ's, and inserts the file below that page (updating the flag appropriately). Memory is used starting from the top of core and working down to page 340. See the sections "buffers - internal format" and "buffer and string pointers - internal format" for information on what can go in the file. An ordinary ASCII text file is not suitable for :EJ'ing. A file to be :EJ'ed must, first of all, be a single string whose length (including its header) must be a multiple of 5120 (1K words of characters). Within that string lives the other strings or whatever that are the data in the file. Their format is unrestricted except that the first thing in the file (starting after the header for the file as a whole) should be a string which is the file's "loader macro" which must know how to return the data in the file when asked for it. The loader macro should expect to be called with the name of the desired data (as a string) as the first argument (^X), and a pointer to the whole file (as a string) as the second argument (^Y). The reason for passing it the pointer to the file is so that the loader itself can be pure (independent of the particular file containing it). The pointer to the file, plus 4, gives a pointer to the loader itself, if the loader wishes to examine its body. The loader macro should return as its value the string which is the value associated with the specified name. If the name is undefined in the current file, the loader should pass the request on to the loader in the next file. The next file can be assumed to start right after the end of the current one, so that ^Y+FQ(^Y)+4 is a pointer to it. If there is another file, FQ of that will be positive; otherwise (this is the last file in memory) FQ of that will be -1. If there are no more files, the loader should return 0. The goal is that several files with different loader macros should be :EJ'able in any order, and yet allow things to be loaded out of any of them at any time. ******************** Manipulating channels ******************** E[ push the input channel, if any. Saves the current input file and position in it, or saves the fact that no file is open. Useful for reading in a file without clobbering any partially read input file. Note: for this and the next three commands ("E]", "E\", "E^"), the file open for input must be randomly accessible (=DSK). The one open for output need not be. FS PAGENUM and FS LASTPAGE are saved by E[ and restored by E]. E] pop the input channel. If any input file was open, the rest of it is flushed. Further input will come from the file that was popped. (see "E[".) E\ push output channel. (see "E[".) E^ pop output channel. If an output file is open, it is closed without being renamed, so it is probably filed as "_TECO_ OUTPUT". (see "E[".)  File: TECMAN Node: Named Up: Concept TECO COMMANDS: BY TYPE. This file: FS Flags -- mode setting and general outside-world-type info. FS reads in a flag name as a text argument. Flag names may be any length, but only the first six characters are significant. Spaces are totally ignored. Only enough of the flag name to make it non-ambiguous is required. However, in programs, abbreviation should be minimized. The result of the FS is the current value of the flag. If an argument is given to the FS and the flag can be set, is then set to that value. If a flag can be set, to make it's value the second operand of an arithmetic operator put the FS command in parens. Otherwise, FS will think it has an arg and set the flag. Flags labeled "read-only" do not require that precaution. Flags currently implemented are: FS % BOTTOM specifies the size of the bottom margin as a percentage of the number of lines being displayed. Initially 10. Rather than let the cursor appear inside the bottom margin, TECO will choose a new buffer window - unless the bottom of the buffer appears on the screen already. FS % CENTER specifies where TECO should prefer to put the cursor when choosing a new window, as a percentage of the screen from the top. Applies even if the end of the buffer appears on the screen - in fact, the purpose of this variable is to make sure that when you go to the end of the buffer some blank space is provided to insert into without total redisplay. Initialy 40. FS % END specifies (as a percentage of total size) the size of the area at the bottom such that TECO should never choose a new window putting the cursor in that area. Initially 30. FS %OPLSP (read only) nonzero if the terminal is inferior to a LISP job (actually, if the superior has set the %OPLSP bit in the .OPTION variable of the TECO). FS % TOP the size of the top margin. Analogous to FS %BOTTOM. Initially 10. FS %TOCID (read only) nonzero if the terminal can insert and delete characters. This flag reflects the bit with the same name in the terminal's TTYOPT variable, and it is updated whenever TECO is restarted or FS TTY INIT is done. FS %TOFCI (read only) nonzero if the terminal can generate the full 9-bit character set. See FS %TOCID. FS %TOHDX (read only) nonzero if the terminal is half-duplex. See FS %TOCID. FS %TOLID (read only) nonzero if the terminal can insert and delete lines. See FS %TOCID. FS %TOLWR (read only) nonzero if the terminal can generate lower case characters. See FS %TOCID. FS %TOMOR (read only) nonzero if the user wants --MORE-- processing, in general. See FS %TOCID. FS %TOOVR (read only) nonzero if the terminal is capable of overprinting. See FS %TOCID. FS %TOROL (read only) nonzero if the user has selected scroll mode. See FS %TOCID. FS %TOSAI (read only) nonzero if the terminal can print the SAIL character set. See FS %TOCID. FS *RSET initially 0. Nonzero suppresses automatic unwinding of TECO's various pdls each time through the top level loop. In other words, when FS *RSET is non-zero, errors not caught by errsets enter break-loops in which q-regs may be examined (unless the user's error-handler macro in q-reg ..P intervenes). The break-loop may be returned from with ")^\", or thrown out of with "^W" or "F;". The suspended program and its callers may be examined with FS BACKTRACE. For more info on break-loops, see under q-reg ..P. FS .CLRMOD (normally -1) if < 0, TECO clears the screen whenever it gets the terminal back from its superior. If 0, that is not done (used mainly for debugging TECO). If > 0, screen clearing is totally eliminated, even if requested by the program (use this for debugging macros that try to destroy trace information). FS .KILMOD normally -1. If 0, FS BKILL doesn't actually kill. FS .TYI BACK backs up the pointer FS .TYI PT by one step. Back up the pointer n steps and then you can use FS .TYI NXT n times to get the n previous input characters. FS .TYI NXT is used to extract from the ring buffer of saved type-in characters. See FS .TYI PT. FS .TYI PT is TECO's pointer into the ring buffer of the last 60 input characters. All input characters read by TECO are saved in this buffer, for the sake of programs to tell the user what he typed by mistake. This pointer is used in conjunction with FS .TYI BACK and FS .TYI NXT, for extracting the contents of the ring buffer. This is done with the following code: FS .TYIPT[1 [2 < FS .TYINXT U2 do something to print the character in Q2. FS .TYIPT-Q1@;> Each FS .TYI NXT extracts the next character from the buffer and advances the pointer. When the pointer has been advanced all the way around to its original position, the entire buffer has been printed. After an input character is read and stored in the buffer, FS .TYI PT is initialized to point at that character. Though FS .TYI PT is changed by ths use of FS .TYI NXT and FS .TYI BACK, this has no effect on how input characters are stored. FS :EJ PAGE is the number of the lowest page used by :EJ'd shared pure files. Initially 256. If multlipied by 5*1024, and then added to 400000000000 (octal), the result is a suitable string pointer to the last file :EJ'd. :EJ looks at this flag to figure out where to insert the next file to avoid clobbering the previous ones. It is an error to set this flag explicitly to a value lower than it already has; when it is set to a higher value, the intervening pages are removed from the address space. FS :ET MODE (Twenex only) controls how filename defaults are used by the :ET command. A bit mask of version, type, name, directory, and device (from 1 to 20 respectively). FS ADLINE is the line-size used by the FA command. FS ALTCOUNT the number of 's that TECO has seen at interrupt level. That is, an approximation to the number of command strings that the user has typed ahead. Useful in user-defined buffer display macros (q-reg ..B). FS BACK ARGS (read-only) returns the arguments of a macro call level up on the stack. It returns 0, 1, or 2 values, as F^X does. The argument to FS BACK ARGS is either the positive number of a frame counting from the bottom (0 = the outermost frame), or a negative number counting back from the currently executing macro (which, by the way, has no stack frame and cannot be referred to in either way). FS BACK DEPTH (read only) is the number of macro call frames on the stack. This does not include the currently executing macro. FS BACK PC returns the PC of a macro call frame. Which frame, is specified as in FS BACK ARGS. The PC of a frame is the number of the next character to be executed, relative to the beginning of the string. ,FS BACK PC sets the PC of the frame specified by , to . FS BACK QP PTR (read-only) gives the level of the bottom of a macro call frame's q-register pdl frame. This is the level which a ^\ done in that macro will unwind to. The macro call frame is specified as for FS BACK ARG. FS BACK RETURN (write-only) returns control to the macro call frame specified as for FS BACK ARG. If control left that frame not with an M but via an exit from within a TECO command (such as a ^R), control is returned to that command. -1 FS BACK RETURN is equivalent to ^\. FS BACK STRING (read-only) returns a pointer to the string or buffer being executed by macro frame specified as for FS BACK ARG. Sometimes a macro frame will be executing a string constant internal to TECO. There cannot be a string pointer to such an object, so a byte pointer to the object (a number, according to FQ) will be returned instead. All you can do with such values is compare them. FS BACKTRACE used to see what program is running at higher levels of the mcro pdl. The program is inserted in the buffer, and point is put at the place it is executing. The macro call frame is specified just as for FS BACK ARGS. FS B BIND is useless, but F[ B BIND and F] B BIND are useful for pushing to a temporary buffer, or popping back from one. F[ B BIND pushes ..O, then does FS B CREATE, but with the extra feature that if an error happens instead of just popping back ..O, the temporary buffer will be killed. That is because instead of doing ]..O, F] B BIND will be done, which is just like FS B KILL with no argument. If after creating a buffer with F[ B BIND you change your mind and want to keep it, pop the previously selected buffer off the pdl with the ] command. The F[ B BIND will no longer be on the stack to kill the new buffer when you return. An argument to F[ B BIND specifies the initial size of the termporary buffer in characters. FS B CONS returns a newly cons'ed up buffer characters long. The contents are all initially zeros, and the pointer starts out at the beginning of the buffer. If is not specified, 0 is assumed. When a buffer is newly created it is at the top of memory. The closer a buffer is to the top of memory, the more efficient it is to do large amounts of insertion in it. FS BCREATE is like FS B CONS U..O - the buffer is selected instead of returned. FS BKILL see q-reg ..O. FS BKILL is used for freeing buffers explicitly. With an argument, it frees the argument, which should be the result of applying the q command to a q-reg containing a buffer. Attempting to kill the currently selected buffer is an error. For example, QAFS BKILL kills the buffer in qa. After that is done, qa still contains a buffer pointer, but it has been marked "dead". If there were other pointers to the same buffer in other q-regs, TECO will regard them too as "dead" buffer pointers. An attempt to select the buffer using one of those pointers will result in an error. FS BKILL may be used without an argument, in which case it pops the q-reg pdl into Q..O, and if the new value of Q..O is different from the old, the old value is killed. FS BOTHCASE (initially 0) >0 => searches ignore case of letters. That is, the case used in the search string is irrelevant, and either lower or upper case will be found. <0 => searches ignore case of special characters also ("@[\]^_" = "`{|}~"). FS BOUNDARIES reads or sets the virtual buffer boundaries (this command returns a pair of values) the virtual boundaries determine the portion of the buffer that most other commands are allowed to notice. Normally the virtual boundaries contain the whole buffer. See the B, Z and H commands. FS BS NO LF if nonzero inhibits the LF that follows backward motion or rubbing out, in ^R mode on printing terminals. FS CASE like F$ (F-dollar) but neither inserts the case-shift and case-lock if no arg, nor expects a string arg. That is, it gets or sets the numeric quantity which determines the standard case and whether to flag on output. FS CCL FNAME (Twenex only) a string, in the same format as FS D FILE, of the jfn given in AC1 if TECO was started at the CCL entry point; or zero if it was not or the filename has already been read. FS CLK INTERVAL is the interval between real-time clock interrupts, in 60'ths of a second. If it is zero, real-time interrupts do not happen. Note that real-time interrupts are not actually processed unless/until TECO is waiting for input. Their main use is for saving the buffer if the user walks away from the terminal without saving it. FS IN COUNT may be useful with real-time interupts, and FS MODIFIED. Setting FS CLK INTERVAL postpones the next clock interrupt to one full interval in the future. FS CLK MACRO is the real-time interrupt handler macro. If the macro types out, it must not leave Q..H set. FS CTL MTA if negative suppresses the ^R-mode definitions of all control-meta-letters (and ctl-meta-[, \, ], ^ and _) to make it easy to insert control characters. This mode is convenient for editing TECO commands. FS DATA SWITCHES (read only) the contents of the PDP10 console switches. FS DATE (read only) is the current date and time, as a number in file-date format. It can be fed to FS FD CONVERT or to FS IF CDATE. FS D DEVICE is the current default device name, as a numeric sixbit word. See F6. FS DD FAST (read only) is nonzero if the current default device is a fast device - that is, the local machine's disk. FS D FILE is the current default filename (that ER would use) as a string pointer. Do G(FS D FILE) to insert it in the buffer. This flag is very useful for pushing and popping with F[ and F]. The exact format of the string is the SNAME, a semicolon, a space, the device name, a colon, a space, the FN1, a space, and the FN2. To extract specific names from the string, search for spaces (or colon or semicolon) not preceded by a ^Q. Note: on ITS, the default device name will never be DSK:. It will be the name of the local machine instead. This is so that comparison of two filenames which have been passed through the defaults and read out with FS D FILE will not say they are unequal because one has device DSK: and the other the machine name. FS D FN1 is the current default first file name, as a numeric sixbit word. See F6. FS D FN2 is the current default second filename, as a numeric sixbit word. See F6. FS D FORCE is to be used to "force out" a buffer redisplay for which the normal mechanism of deferring redisplay for input and later resumption will not do the right thing (such as, because the buffer being displayed is not the one permanently selected). Setting FS D FORCE nonzero has two effects: it forces the redisplay through to completion without considering the presence of input, and it inhibits updating the mode line. FS D SNAME is the current default SNAME, as a numeric sixbit word. See F6. FS D VERSION is the current default file version number; actually, a reflection of FS D FN2. If the default FN2 is numeric, FS D VERSION is that fn2 as a number. If the default fn2 is ">" or "<", FS D VERSION is respectively 0 or -2. Otherwise, FS D VERSION is -1. Writing -1 into FS D VERSION has no effect; writing any other value sets the default fn2 appropriately. On Twenex, versions are always numeric, so all values have their usual meaning. FS D WAIT if set nonzero causes TECO to pause slightly before each line of output. This should give better overall response on slow displays. It will make things much worse on fast displays, and slightly worse on printing terminals. This flag is initialized by FS TTY INIT and at startup, according to the terminal speed. FS ECHO ACTIVE if nonzero says that output has been printed in the echo area during this ^R command, so ^R should clear the echo area when it next wants to read a command. Clearing is not done by the FI command; only when the next distinct ^R command is to be read. Commands which wish to type in the echo area and not have their output erased can set this flag to zero. The FG command does, when it types in the echo area. FS ECHO FLUSH must be nonzero to enable this feature. Otherwise, the echo area is never cleared gratuitously. FS ECHO CHAR when a ^R command starts being executed, holds the character that invoked it; set to -1 if anything is typed out; when the command returns to ^R, if still not -1, it is echoed. The command can set this flag itself to control the echoing. A string may be put into this flag by a macro. Then, if the command must be echoed, the whole contents of the string will be typed. FS ECHO DISPLAY (write only) like FS ECHO OUT, but outputs in display mode, so that ITS ^P-codes may be sent. See .INFO.;ITS TTY for details on available options. FS ECHO ERRORS if nonzero, causes error messages to be printed in the echo area. FS ECHO FLUSH if nonzero, enables the automatic clearing of the echo area after each ^R command which uses it. See FS ECHO ACTIVE for details of how to control this. FS ECHO LINES the number of lines at the screen bottom to be used for command echoing. Default is 1/6 of screen size, except 0 on printing terminals. If this flag is set to -, echoing is turned off, and there are -1 echo lines. Thus, -1FS ECHOLINES makes no echo and no echo area; -5FS ECHOLINES makes no echo but a 4 line echo area; 0FS ECHOLINES makes echo but no echo area. Even if echoing is off, FS ECHOOUT may be used. FS ECHO OUT (write only) is used for outputting to the echo area. If the argument is a number, it is taken as the ASCII code for a character to be typed. If the argument is a string, all the characters in it are typed. Characters are output as they would actually echo. Thus, sending a CR will actually do a CRLF, and sending a ^A will print either downarrow (in :TCTYP SAIL mode) or caret-A. FS ERR same as FS ERROR if read; if written, causes an error with the error code that is written in it. Thus, to cause a "You Lose" error with 3-letter code LUZ, do :I*LUZYou Lose FS ERR. Your error message should not contain any CRLFs. Users who wish to generate errors themselves with the same codes that TECO uses should use TECO's standard strings for those errors (that is, do @FE IFN FS ERR) so that comparing FS ERROR against @FE values will still work. FS ERRFLG is used to signal the buffer display routine (whether built-in or user-written) that an error message is on the screen and should not be overwritten. Its value is - if the first lines contain an error message, or nonnegative if there is none. If typeout is done when FS ERRFLG is negative, TECO will not actually type the first lines of it. The +1st line of typeout will appear in its normal position, beneath the error message. By that time, FS ERRFLG will be zero again. FS ERROR the error code of the most recent error. Errors caught by errsets are included. A TECO "error code" is now just a string containing the text of the error message. Everything up to the first tab is the "brief" part of the error message; if FS VERBOSE is 0, that is all that TECO will print out. You can see if an error was (for example) an "IFN" error by doing F=(FS ERROR)IFN and seeing if the result's absolute value is 4. It still works to compare against @FEIFN, which returns the standard string that TECO always uses for internally-generated IFN errors. I.T.S. I/O errors now have messages starting with "OPNnnn" where nnn is the I.T.S. open-failure code. Macros which used to decode I/O errors by numeric comparison must switch to using F=, since the strings for such errors are consed up by TECO as needed. FS ERR THROW (write only) return control to the innermost error-containing command loop. This could be either an error catch command (:@< ... >), a ^R level, or the top level TECO command loop. This command is the correct way for a user error handler (..P) to abort the computation which got the error. The argument given to FS ERR THROW is returned from the error catch, if it happens to throw to an error catch. Otherwise, the argument is discarded. FS EXIT (write only) does a .BREAK 16, using the argument to FS EXIT as the address field. See DDT DOC for a description of what the arguments mean. "100000." is a good value. AC 2 will contain the address of the 7-word "buffer block" describing the current buffer. See the section "buffer block" at the end. FS EXPUNGE (T(w)enex only) expunges the connected directory. FS MSNAME can be used to connect to a directory so as to expunge it. FS FDCONVERT converts numeric file dates to text and vice versa. If there is a numeric arg, it is assumed to be in the format for its file dates, and converted to a text string which is inserted in the buffer. The form of the string is dd/mm/yy hh:mm:ss. In this case, no numeric value is returned. If there is no arg, a text string is read from the buffer starting at ., and . is moved over the string. The string should be in the format inserted by FS FDCONV with argument, and will be converted to a numeric file date which will be the value of FS FDCONV. See FS IFCDATE and FS OFCDATE. :FS FD CONV returns a string containing the printed representation of the file date , instead of inserting it in the buffer. Twenex uses ODTIM and IDTIM, and so is less picky about date formats it will accept. Also, a second argument to FS FSCONV is used as the ODTIM format flags. FS FILE PAD the character used to pad the last word of files written by TECO. Normally 3 (for ^C). FS FLUSHED is nonzero if a --MORE-- has been flushed, and type-out is therefore suppressed. The flag is positive if the flushage was due to a rubout, negative otherwise. You can stop generating type-out when FS FLUSHED is nonzero, or you can clear it to make type-out start actually appearing again. FS FNAM SYNTAX controls TECO's filename readed. If 0, when only one filename is present, it is used as the fn2 (this is the default). If positive, a lone filename is used as the fn1. If negative, a lone filename is used as the fn1 and automatically defaults the fn2 to ">". The default TECO init file uses this flag to process a DDT command line. FS FORK JCL (Twenex only) gives a command line (jcl) for the inferior fork invoked via the next FZ command. FS GAP LENGTH (read only) the length of the gap. This is the value of EXTRAC (see "buffer block"). FS GAP LOCATION (read only) the buffer position of the gap. This is GPT-BEG (see "buffer block"). FS HEIGHT (read only) number of lines on the screen, on display terminals (including --MORE-- and command lines). On printing terminals, wil be a very large number. FS HELP CHAR contains the character to be used as the HELP character. Normally, it contains the code for C-_. However, you may want to bind it to -1 from time to time to prevent HELP from being recognized (such as, in the C-Q command). FS HELP MAC is a macro to be executed if the HELP character is typed. HELP is Top-H on TV's, ^_H on any terminal. If FS HELP MAC is zero, the HELP character is ignored as a ^R command, and returned (as 4110 octal) by FI and VW. FS H POSITION (read-only) returns the number of character positions there would be to the left of the type ball if the contents of the buffer (or at least everything after the previous carret) were printed on a hardcopy terminal with hardware 8 character tabbing and backspace. FS HSNAME is the user's home directory. The home directory is a little more permanent than the working directory (FS MSNAME) and is used for storing things that permanently belong to the user, such as the RMAIL file, which do not have their own special directories the way init files do. FS I&D CHR if nonzero, tells TECO to try to use the insert and delete character operations to speed redisplay. Initialized nonzero if the terminal handles those operations. Don't set it nonzero otherwise! FS I&D LINE if nonzero, tells TECO to try to use the insert and delete line operations to speed redisplay. Initialized nonzero if the terminal handles those operations. Don't set it nonzero otherwise! FS IBASE the input radix for numbers not followed by "." (initially 8+2) FS I.BASE the input radix for numbers ended by ".". Initially 8. FS IF ACCESS (write-only) sets the access pointer of the current input file - the argument is the desired character address in the file. FS IF CDATE the creation date of the currently open input file. Arg and value are in numeric file date form - see FS FD CONVERT. FS IF DEVICE (read-only) is the device name of the current or most recent input file, as a numeric SIXBIT word. FS IF DUMP (ITS only) is the dumped-bit of the currently open input file. FS IF FDB (Twenex only) is used for reading and writing the file descriptor block of the current input file. FS IF FDB returns word , and ,FS IF FDB sets it to . FS I FILE (read-only) is the name of the current or most recent input file, as a string. The format is like that of FS D FILE. FS IF FN1 (read-only) is the first file name of the current or most recent input file, as a numeric SIXBIT word. FS IF FN2 (read-only) is the second file name of the current or most recent input file, as a numeric SIXBIT word. FS IF LENGTH (read-only) the length, in characters, of the currently open input file; or -1, if that length is unknown (because the file is on a device for which the fillen system call is unimplemented). Error if no file is open. FS IF MTAPE (write-only) executes a .MTAPE call on the input file. The last argument is the .MTAPE operation. A preceding argument specifies the count (default is 1). It is not clear that this feature really works. FS IF REAP is the don't-reap bit of the currently open input file. FS IF SNAME (read-only) is the SNAME of the current or most recent input file, as a numeric SIXBIT word. FS IF VERSION (read-only) is the version number of the open input file, or -1 if there is none or its FN2 isn't numeric. FS IMAGE OUT outputs arg as to the terminal as a character in superimage mode. Returns no value. If the argument is a string pointer, the contents of the string are output. FS IN COUNT is an old name for FS TYI COUNT. FS INSLEN length of last string inserted into the buffer with an "I", "G" or "\", or found with a search command or "FW". FS INSLEN will be negative after a backward search or "FW" with negative arg. See "FK" and "^F". FS INVMOD if nonzero, causes the mode line to be displayed in inverse video on terminals which support it. FS JNAME (read only) returns the JNAME of the job TECO is running in, as a numeric SIXBIT word, which can be converted into text by the F6 command. Note that the XJNAME is also available, and might be better for your purpose - see FS XJNAME. FS JRN EXECUTE (write only) opens a journal file for execution (replaying). The default filenames are used. With a colon modifier, the journal file being replayed is closed. See the section on journal files for more information. FS JRN IN (read only) is nonzero when a journal file is being replayed. FS JRN INHIBIT if nonzero causes input to be taken from the terminal even though a journal file is being replayed. This is how FS JRN MACRO can offer the user a recursive ^R to fix things up after a quit. FS JRN INTERVAL The value of this flag controls how often the journal file being written is updated on disk. It is in the form of a number of commands. It is initially 50. FS JRN MACRO This macro is called whenever TECO attempts to read a command from a journal file being replayed and finds a colon or a ^G character in the file. The colon or ^G is passed to the macro as a numeric argument. In the case of ^G, this macro should execute a ^R, and then quit by setting FS QUIT to -1. In the case of a colon, the macro should read more characters from the file using FS JRN READ and act on them. The format of these characters is not specified. FS JRN OPEN (write only) opens a journal file for writing. The default filenames are used. With a colon modifier, the output journal file is closed. See the section on journal files for more information. FS JRN OUT (read only) is nonzero when a journal file is being written. FS JRN READ (read only) reads a character from the input journal file being replayed. If there is none, it returns a random value. FS JRN WRITE (write only) outputs its argument, a character or string, to the journal file being written. It does nothing if no journal file is being written. FS LAST PAGE (read only) set to -1 when an input file is opened; set to 0 as soon as the last char of the file is read in. Saved by E[ - E]. Updated by FS IF ACCESS. Thus, FS LAST PAGE; will exit an iteration if there is no more to be read. FS LINES (initially 0) determines the number of lines displayed by standard buffer display, and, for display terminals, the number of lines to use at all. 0 => a full screen on displays, 2 lines on printing terminals. not zero => lines. FS LISPT normally 0, this flag is set nonzero if TECO is started at 2 + its normal starting address. This is intended to indicate to TECO programs that passing of text between TECO and its superior is desired. FS LISTEN returns nonzero if there is input available to be read by "FI". If given an arg, then if no input is available, the arg is typed out using FS ECHOOUT. FS LOAD AV (Twenex only) returns the system load average. FS MACHINE (read only) returns the name of the machine TECO is running on, as a numeric SIXBIT word, which can be turned into text with F6. On ARPANET Twenices, this returns the local hosts hostname as a string. FS MODE CHANGE if nonzero means that FS MODE MACRO needs to be run eventually, to update the contents of ..J. Whenever TECO is considering updating the mode line, depending on the value of this flag it may run FS MODE MACRO first. That macro can recompute ..J to display the current state of things. FS MODE CHANGE is set to zero before FS MODE MACRO is called. The precise condition is: if FS MODE CHANGE is positive, do run FS MODE MACRO. If FS MODE CHANGE is negative, its absolute value is compared with twice the value of FS QP PTR; if the latter is less, do run FS MODE MACRO. Thus, if FS MODE MACRO sets FS MODE CHANGE based on the current value of FS QP PTR, it can arranged to be called again if control returns to an outer level on the stack. See Q..J and FR. FS MODE MACRO if nonzero is the macro used to update Q..J when the mode line is about to be displayed. See FS MODE CHANGE and Q..J and FR. FS MODIFIED is the current buffer's modified flag. This flag is set nonzero whenever the buffer's contents are changed. It can be read or written by the user at any time. Each buffer has its own flag, but only the selected buffer's flag is accessible. The intended use is for deciding whether a file must be written back to the disk. When this flag is nonzero, a star appears at the end of the mode line. See also FS READ ONLY and FS X MODIFIED and FS ^R STAR. FS MP DISPLAY (write only, ITS only) outputs text to the main program area in display mode (^P is special). The argument may be a single character or a pointer to a string, whose entire contents are output. FS MSNAME is the user's working directory name (set up from the SNAME that TECO was given when it started up), as a numeric SIXBIT word, which can be converted into text by the F6 command. On Tenex or Tops-20, this is the connected directory and writing into it is used to connect to another directory. FS NOCEOL if nonzero, signifies that the terminal in use does not have the clear-to-end-of-line function. Programs may wish to clear the screen at times if this flag is set, if they know that clearing the screen would result in faster redisplay afterward on such terminals. FS NOOP ALTMODE if negative, altmode is always a noop as a command. If 0, altmode is an error as a command. If >0, always ends execution (as ^_ does). Initially -1. The old treatment of altmodes was as if this flag were set to 1. FS NOQUIT gives the user control of TECO's ^G-quit mechanism. See "^G". FS OF ACCESS (write-only) sets the access pointer in the output file. The argument must be a multiple of 5. If the last output done did not end on a word boundary, rather than throwing away the remaining characters, an error occurs. FS OF LENGTH gives the length of the file, if you want to append to the end. FS OF CDATE the creation date of the currently open output file, in numeric file-date form. FS O FILE returns the filenames of the last output file explicitly closed, as a string. The format is like that of FS D FILE. The intended use is for finding out what version number was actually written. FS OF LENGTH returns the length in characters of the currently open output file, or -1 if it cannot be determined. FS OF MTAPE (write-only) does a .MTAPE call on the output file. The last argument is the .MTAPE operation. A preceding argument specifies the count (default is 1). It is not clear that this feature really works. FS OF VERSION (read-only) is the version number of the last output file closed, or -1 if that file's FN2 was not numeric. FS OLD FLUSHED Saves the value of FS FLUSHED when that is set to zero, on returning to ^R. Thus, a ^R command can check FS OLD FLUSHED to see whether the previous command had output which was flushed. FS OLD MODE is the last ..J value actually displayed in the mode line. Setting this flag to zero will force redisplay of the mode line. FS OSPEED The terminal's ouput line speed in baud, or 0 if the speed is not known. FS OS TECO returns the operating system TECO is running on, 0 for ITS, 1 for 20X, 2 for 10X. FS OUTPUT if nonzero, suppresses output to the EW'd file. Output commands (P, etc) are errors. FS PAD CHAR (T(w)enex only) is the character to use for padding terminal output. Normally it is a Rubout (177). For some terminals a null (0) is better. Some may set it to 0 automatically. -1 means use an actual delay instead of padding characters. This may make some terminals work better, and may be more efficient of CPU time; however, it will not work across networks of any sort. FS PAGENUM the number of formfeeds read (with non-atsign Y and A commands) from the input file since it was opened. FS PJATY this is negative if TECO has detected that the terminal was temporarily taken away from it. A negative value here will cause the whole screen to be refreshed at the next opportunity. FS PROMPT the ASCII value of the prompt character (initially 38 for "&"). TECO will prompt on printing terminals only, whenever it is about to read from the terminal, and FS PROMPT is not 0. FS PUSHPT (write-only) pushes its argument on the "ring buffer of the pointer", but only if the argument differs from the value already at the top of the ring buffer. See the ^V command. Note that TECO's top level loop does Q..IFS PUSHPT each time it is about to read in a command string. FS QP HOME returns a string which says where the q-register pdl slot was pushed from. can be a nonnegative offset from the bottom of the stack or a negetive offset from the top. The string will contain the name of the q-register of FS flag that was pushed, as, for example, "QA", "Q.^RX", "QFoo", "FS DFILE", or "*" (for a [(...) ). "*" isn't really a q-register name, but what would be any better? :FS QP HOME returns the address of the q-register which q-register pdl slot was pushed from (for a variable, returns the name of the variable). Such numbers will be equal for two slots pushed from the same place in the same TECO. They are also used with F^G. @FS QP HOME turns a q-register address returned by :FS QP HOME into a string such as plain FS QP HOME would return. @FS QP HOME may be useful in for decoding the local q-register home numbers used with the F^G command. FS QP PTR the q-register pdl pointer (0 if nothing has been pushed, 1 if one q-reg has been pushed, etc.) FS QP PTR sets the pointer to if > 0; adds to it if is negative. It is illegal to increase the pointer value with this command. FS QP SLOT FS QP SLOT reads q-reg-pdl slot . ,FS QPSLOT sets it to . The first slot is numbered 0. If is negative, it is treated as FS QPPTR+. Thus, -1FS QP SLOT is the last slot pushed. FS QP UNWIND (write only!) like FS QP PTR but pops slots back into the q-reg's they were pushed from instead of simply decrementing the pdl poinetr. This unwinding is automatically done when an error is caught by an errset, and at the end of each command string, and by ^\ and FS ^REXIT. If Q..N is popped by this command, it is macroed first (see ..N). If is negative, FS QP UNWIND pops - slots. FS QUIT ^G-quit works by setting this flag negative. Whenever quitting is possible (see FS NOQUIT) and FS QUIT is negative, quitting will occur (and FS QUIT will be zeroed automatically). When TECO's quitting is inhibited, the user can test this flag explicitly to do his own special quitting. FS Q VECTOR (a pseudoflag) returns a newly cons'ed up q-register vector, characters long. should normally be a multiple of 5. The contents are initialized to zeros, and the pointer is at the beginning of the qvector. A q-vector is really a buffer, each word of which is marked by the garbage collector. See the section on data types. FS RANDOM reads or sets the ^Z command random number generator's seed. FS READ ONLY if nonzero makes it an error to modify the buffer. This flag is actually per-buffer, so when you set it, you set it only for the currently selected buffer. FS REAL ADDRESS returns the value of BEG, the character address of the beginning of the current buffer. Useful for communicating with other programs that need to be given addresses of data in their commands. Also useful for executing the buffer as PDP10 code (do FS REALAD/5U0 M0; the code should be position-independent, expect its address in accumulator 5, and start with SKIP (skip never) instruction. Its argument will be in AC 3.). FS REFRESH if nonzero, is macroed each time TECO really clears the whole screen. It is given no args and its values are ignored. The screen will already have been cleared. When only part of the screen is in use (because FS LINES and FS TOP LINE call for that), the only time that TECO will clear the whole screen is when it is continued after having been stopped, the primary use of this hook is to put back on the screen whatever is supposed to be in the part of the screen not being actively used for display. Functions which remove part of the screen from active use can sometimes be entered recursively, each one removing a few more lines from use. Each of them might supply an FS REFRESH to refresh those lines. What ought to happen is that all the FS REFRESHes are executed, in the order they were set up. To make this happen, any function which sets up an FS REFRESH should save the previous contents elsewhere, and the new FS REFRESH should call the old one first thing. FS REREAD (usually -1) if nonnegative, FS REREAD is the 9-bit TV code for a character to be re-read. Putting 65 into FS REREAD will cause the next "FI" command to return 65 (and set FS REREAD back to -1). FS RGETTY 0 if printing console, otherwise equal to the tctyp word of the terminal. However, it is better to decode the FS %TOCID, etc., flags than to decode FS RGETTY when trying to determine what kind of display the terminal is, and what functions it can perform. On Twenex it is actually allowed to set this variable in case the system is mistaken about your terminal type. What it must be set to is the TECO internal type code for the terminal you are using; and not all types are assembled in on any particular Twenex site. FS RUB CRLF if nonzero causes the initial definitions of ^D, rubout and control-rubout to delete both characters of a CRLF at one blow, as if it were a single character. FS RUB MACRO if nonzero is a macro to be called to perform the ^R commands Rubout and C-D when they have explicit numeric arguments. The normal definitions of the two characters call this macro in that case. FS RUNTIME (read-only) TECO's runtime in milliseconds. FS SAIL if nonzero, the terminal is assumed to be able to print non-formatting control chars as 1-space graphics. TECO outputs them as they are instead of outputting an ^ and a non-ctl char. Terminal initialization zeros this flag if the terminal's TOSA1 bit is 0 (this bit is set by :TCTYP SAIL). FS S ERROR if 0, as it is initally, a failing serach within an iteration or a ^P-sort key is not an error - it simply fails to move the pointer. If not 0, such searches cause sfl errors like all other searches. FS SHOW MODE if nonzero, causes FR to type out the mode line (Q..J) on printing terminals, if it has changed since last printed. Has no effect on displays. FS S HPOS (read only) is the horizontal position of point, taking control characters, CRs, etc. to appear the way they are currently being displayed, but assuming an infinitely wide line. FS S STRING is the default search string (which S will use), as a string pointer. Do G(F S STRING) to insert it in the buffer. This flag is most useful for pushing and popping. FS STEP MACRO (normally 0) if nonzero and numeric, TECO displays the buffer and waits at the beginning of every line of the program. See ^M for details. If it is a string, it is executed at the beginning of every line in the program. Exception: if a macro begins with a "W", stepping is inhibited at the beginning of that macro. The macro can inhibit stepping throughout itself by starting with "W 0F[STEP MAC". Exception: stepping is also done whenever a successful conditional begins. FS STEP DEPTH restricts the macro call stack levels at which stepping is done. If FS STEP DEPTH is -1, as it is initially, stepping goes on at all stack levels. Otherwise, the value of FS STEP DEPTH is the largest macro call depth (FS BACK DEPTH value) for which stepping can take place. FS SUPERIOR if nonzero is the macro to be called when TECO's superior makes a request to insert text into TECO. See "How Superiors Can Put Text into TECO" below. FS S VALUE the value stored by the last search command (0 if search failed; else negative, and minus the number of the search alternative which was actually found). FS TOP LINE is, on display terminals, the number of the first line on the screen that TECO should use. Normally 0, so TECO starts output at the top of the screen. FS TRACE nonzero iff TECO is in trace mode. See "?". 1F[ TRACE is a good way to start tracing temporarily. FS TRUNCATE says what to do with long lines of type-out. Negative => truncate them. Positive or zero => continue them to the next line. Entering ^R sets this flag to 0. FS TTMODE (initially 0) non-zero tells TECO that normal buffer display should display on printing terminals. (if there is a user buffer display macro, this flag has no effect unless the macro checks it) FS TT PAGE MODE (Twenex only) if non-zero, prevents TECO from leaving page mode, so that ^Q and ^S are still used for flow-control. Note that this means they are not available as commands. FS TTY FCI (Twenex only) if non-zero, we assume that the terminal has an Edit key, and that the 200 bit in incoming characters should be interpreted as "Meta". If this flag is zero, then the 200 bit is ignored on the assumption that it is a parity bit. FS TTY INIT (no argument or value) causes TECO to reexamine the system's terminal description and reset various flags, and the cursor in ..A, appropriately. Then, FS TTY MACRO is executed if nonzero. It can be used to digest the tty characteristics and set flags accordingly. FS TTY INIT is run automatically when TECO is started or restarted. In detail, ..A is set to "-!-" on printing terminals, and to "/\" on displays (but "^A^B" on imlacs). FS RGETTY is set up to be 0 on a printing terminal, nonzero otherwise. FS VERBOSE is set equal to FS RGETTY. FS TTYOPT is read in from the system. FS ^H PRINT is zeroed unless the terminal can backspace and overprint; FS ^M PRINT is zeroed unless the terminal can overprint. FS SAIL is set nonzero if the %TOSA1 bit is set in TTYOPT (this is the bit ":TCTYP SAIL" sets). FS LID is set nonzero if the %TOLID bit is set in TTYOPT. %TOLID says that the terminal can insert and delete lines. FS WIDTH and FS HEIGHT are read in from the system. FS ECHOLINES is set to 0 on printing terminals; 1/6 of the screen size on displays. FS D WAIT is set to -1 if FS OSPEED is positive and 600 or less; to zero, otherwise. FS TTY MACRO is a macro called by FS TTY INIT to give the user a chance to alter TECO flag settings based on the newly-gobbled terminal characteristics. If you don't like the way TECO initializes certain FS flags (namely FS ECHOLINES, FS TRUNCATE, FS VERBOSE, FS WIDTH, FS ^HPRINT, FS ^MPRINT, and FS SAIL) in FS TTY INIT, this macro can change them. Pure strings should NOT be used for this; when a saved EMACS environment is restored, FS TTY MACRO$ is processed before even the standard libraries are loaded in. So you must create the string with :I, X or :G. You can make an impure copy of a pure string in Q0 with :I00. FS TTYOPT (read-only) the TTYOPT word for the terminal. However, if you think you want to use this flag, see FS %TOCID, etc., first. FS TTYSMT (read-only) the TTYSMT word for the terminal. FS TYI BEG is the value which FS TYI COUNT had on the last time through the main ^R command loop. In other words, it is the number of terminal input characters so far, not including the last or current ^R command. Commands to set the numeric argument do not count as real commands in this regard; they are grouped with the commands for which they set the argument. When ^R is reading the first character of a command, FS TYI COUNT has been incremented already, so it equals FS TYI BEG+1. FS TYI COUNT is the number of characters read from the terminal so far. FS TYI SINK if nonzero holds a macro to be called every time a character is read from the terminal (not from FS REREAD or from FS TYI SOURCE). The character read, in the 9-bit code, is passed as a numeric argument to the macro. The macro should return a single value, for the sake of ^R display updating. FS TYI COUNT and FS TYI BEG may be of use in the macro. FS TYI SOURCE if nonzero holds a macro to be called to obtain "terminal input". This is instead of reading from the keyboard. The macro should put the input character it wishes to provide into FS REREAD and then return. The macro should return a single value, for the sake of ^R display updating, but this value is not used in any other way. That FS TYI SOURCE is nonzero is taken to imply that input is available, so display updating is suppressed. To cause displaying to be done, you must bind FS TYI SOURCE to zero and then request it. FS TYI SOURCE is set to zero by anything that discards keyboard input (errors, quits, etc). FS TYO HASH FS TYO HASH returns the hash code of the screen line at position . ,FS TYO HASH sets the hash code of that screen line to . This is useful primarily for -1,FS TYO HASH which will force that screen line to be redisplayed. FS TYO HPOS (read-only) while typeout is in progress (FS TYPEOUT nonnegative), holds the current typeout horizontal position, in which the next typed character will appear. FS TYO VPOS (read only) while typeout is in progress (FS TYPEOUT nonnegative), holds the current typeout vertical position, in which the next typed character will appear. FS TYPEOUT is -1 if typeout has not been happening recently, so typeout starting now would appear at the top of the window. FS TYPEOUT is not -1 when typeout was the last thing to happen and any more typeout will appear after the previous typeout. :FT types at the top of the window by putting -1 in FS TYPEOUT before typing. FS U HSNAME is used to determine a user's hsname. FS U HSNAME (where is sixbit) returns 's hsname in sixbit. , FS U HSNAME returns his hsname on machine (sixbit). FS UINDEX (read only) The user index of the TECO job. FS U MAIL FILE is used to determine the filename (including the machine) of a user's mail file. FS U MAIL sets the default filename to the name of 's mail file (where is in sixbit). ,FS U MAIL sets them to the name of his mail file on machine instead of his normal mail-receiving machine. FS UNAME (read only) returns the UNAME of the job TECO is running in, as a numeric SIXBIT word, which can be converted into text by the F6 command. See also FS XUNAME and FS MSNAME, one of which might be better for your purpose. FS UPTIME (read only) returns time system has been up, in 30'ths, (milliseconds on Twenex). FS UREAD (read-only) -1 iff an input file is open, else 0. Once an input file is opened, it remains open until "EC", "@Y", "@A", "EE" or "EX" is done. FS UWRITE (read-only) -1 if an output file is open, else 0. FS VAR MACRO if nonzero enables the feature whereby setting a named variable can run an arbitrary macro to make changes in other data structures. These data structures will appear automatically to reflect the value of the variable. To use this feature, allocate three words per variable in the symbol table in Q..Q. The macro to call is the contents of the third word, but only if it is a string which starts with a "!". If that is the case, it will be called with the new value of the variable as its argument. FS V B is the distance between the real beginning of the buffer and the virtual beginning. See FS BOUNDARIES, but unlike that flag, FS V B can be pushed and popped. FS VERBOSE if not 0, TECO will print the long error message of its own accord when an error occurs. Otherwise it will print only the 3-char code and the long message must be requested by typing ^X. Initially 0 except on displays. FS VERSION (read-only) the current TECO version number FS V Z is the distance between the virtual end of the buffer and the real end - the number of characters past the virtual end. See FS BOUNDARIES for more info, but note that FS V Z can be pushed and popped. FS WIDTH width of terminal's screen or paper, in characters. FS WINDOW the number of the first character in the current display window, relative to the virtual beginning of the buffer (that is, FS WINDOW+B is the number of that charcter). FS WINDOW+BJ (FS HEIGHT-(FS ECHOLINES)/2)L will put the pointer in the middle of the window (usually). Setting FS WINDOW will make TECO try to use the window specified. However, if the constraints of FS %TOP and FS %BOTTOM are not met, TECO will choose another window rather than use the specified one. FS WORD gets or sets words in the current buffer. This flag makes it possible for TECO programs to edit binary data bases. FS WORD returns the contents of the word containing character ; ,FS WORD sets that same word. When handling binary data, it is unwise to insert or delete characters other than in units of five, on word boundaries. The way to delete a word is to delete its five characters; insert a word with 5,0I (it will contain either 0 or 1). To read in a file of binary data, FY should be used, since Y might pay special attention to the characters in the file. Copying out of another buffer with G works, provided the transfer starts and ends on word boundaries (blt is used). For writing out binary data, use "HP" rather than "PW" - "PW" may add a "^L". "EF" is OK for closing the file - it will add no padding if it is done at a word boundary. FS XJNAME (read only) returns the XJNAME of the job TECO is running in, as a numeric SIXBIT word, which can be converted into text by the F6 command. The XJNAME is "what the JNAME was supposed to be", so if you want your init file to do different things according to how TECO was invoked, you should use the XJNAME rather than the JNAME. On Tops-20, this will be the first atom of the command line, if there is one; this is useful for the same reason. FS X MODIFIED is completely analogous to FS MODIFIED in how TECO treats it. However, the user can clear either one without changing the other. They can be used to detect the occurrence of modifications since two different types of events (such as, real saves and auto saves). FS X MODIFIED does not affect the star in the mode line; only FS MODIFIED does. FS X PROMPT On printing terminals, all commands that type out first print and zero FS X PROMPT if nonzero (using FS ECHO OUT). Do not try to use it on displays. FS XUNAME (read only) returns the XUNAME of the job TECO is running in, as a numeric SIXBIT word, which can be converted into text by the F6 command. The XUNAME is "who the user really is". For example, it is what TECO and other programs use to decide whose init file to use. FS Y DISABLE controls treatment of Y command. 0 => Y is legal. 1 => Y is illegal (gives "DCD" error). -1 => Y is always treated as @Y. FS Z (read only) the number of characters in the buffer. Will differ from value of Z command when virtual buffer boundaries don't include the whole buffer. This is Z-BEG (see "buffer block"). note: in the names of the following flags, "^" represents caret, not a control character. Control characters cannot be part of FS flag names. FS ^H PRINT controls how ^H is typed out. Negative => actually backspace (and overprint), otherwise type the ^H as caret-H. FS TTYINIT and G cause this flag to be zeroed if the terminal cannot handle overprinting. FS ^I DISABLE controls the treatment of the tab character as a TECO command. 0 => ^I is an insert command (see Tab for details). 1 => ^I is illegal (gives "DCD" error). -1 => ^I is a no-op. FS ^L INSERT (initially 0) if 0, formfeeds in files that terminate Y commands' reading, are thrown away, and the P and PW commands output a formfeed after the buffer. If FS ^LINSERT is nonzero, formfeeds read from files always go in the buffer, and P and PW never output anything except what is in the buffer. Either way, a Y and a P will write out what it reads in. FS ^M PRINT says when a stray CR or LF should be typed out as one, as opposed to being printed as "^M" or "^J". Possible values and initialization like FS ^H PRINT FS ^P CASE if nonzero, ^P sort ignores case (lowercase letters sort like the corresponding uppercase). FS ^R ARG is the explicit numeric argument for the next ^R mode command, or 0 (not 1!) if there was none. FS ^R ARGP contains two bits describing this ^R-command's argument: bit 1.1 (1) is set if any argument was specified (either numerically or with ^U). bit 1.2 (2) is set if a numeric argument was specified. If this bit is 0, the contents of FS ^R ARG are ignored, and 1 is used instead. bit 1.3 (4) is set if the argument, as specified by the other bits, should finally be negated. FS ^R CCOL the comment column, for ^R's comment mode. FS ^R CMACRO FS ^RCMAC gets the ^R-mode definition of the character whose ASCII code is . ,FS ^RCMAC sets it to . should be an ASCII code; it will be converted to 9-bit TV code which is what is actually used to index the ^R-mode dispatch table. If you wish to supply a 9-bit code yourself, use "@FS ^RCMAC" which skips the conversion. Also, these definitions may now be referred to as q-regs in all the q-reg commands - see "Q". The definition is either a built-in command or a user macro. In the former case, the definition is a positive number of internal significance only. However, built-in definitions may be copied from one character to another using FS ^RCMAC. For a character to be a user macro, its definition must be one of the funny negative numbers which are really string pointers. They can be obtained from strings by applying the "Q" command to a q-reg that contains text. For example, to make the definition of the character " " be the string which is at the moment in q-reg A, do "QA,^^ FS ^RCMACW". "QAU^R " is equivalent. To copy the definition of "A" into the definition of rubout, do "^^AFS ^RCMAC,127FS ^RCMACW". This will make rubout self inserting (unless "A" had been redefined previously). FS ^R DISPLAY if nonzero is macroed every time ^R is about to do nontrivial redisplay (anything except just moving the cursor). If the evaluation alters the needed redisplay (either by returning 0 or 2 values to ^R, or by doing some of the redisplay with ^V) then ^R will take note. If a FS ^R DISPLAY returns no values, it will force a full redisplay, thus effectively disabling ^R's short-cuts, so beware. If FS REFRESH is nonzero, then it will be called in addition to FS ^R DISPLAY, at those times when the whole screen is being cleared. FS ^R EXIT (write-only) exits from the innermost ^R invocation. Pops q-regs pushed within that ^R level, and ends iterations started within it. FS ^R ECHO 1 => characters read in by ^R should not be echoed. 0 (the default) => they should be echoed only on printing terminals. -1 => they should be echoed on all terminals. Note that this "echoing" is explicit typeout by TECO. System echoing is always off in ^R mode, currently. Also, rubout is not echoed on printing terminals. However, FS ^R RUBOUT on a printing terminal when FS ^R ECHO is <= 0, types out the char being deleted. FS ^R EC SD is used to allow system echoing to echo the Space character when some sort of auto-fill feature is in use and Space does not have the definition of a normal self-inserting character. This flag should be set to the definition which Space has when it does auto-filling. When Space has this definition, it will be considered safe to let the system echo Spaces just as if they were ordinary self-inserting characters; however, to prevent auto-fill from being lost, system echoing will be allowed only as far as the column which is the value of FS ADLINE, which should be set no greater than the column at which auto-fill starts to do something nontrivial. The definition of Space will not actually be executed when the space is echoed by the system, but for an auto-fill which isn't going to break the line this should make no difference. FS ^R ENTER is macroed (if nonzero) whenever ^R is entered at any level of recursion. FS ^R EXPT is the ^U-count for the next ^R-mode command. FS ^R H MIN (read only) is the hpos of the first change on the screen needing redisplay. It will be a large positive number if no redisplay is required. If FS WINDOW is negative then the value of this flag doesn't matter. FS ^R HPOS the current horizontal position of the cursor in ^R mode. Not updated when the pointer moves, unless ^R gets control back or @V is done. FS ^R INDIRECT given a 9-bit character, traces ^R alias-definitions to find the character it is equivalent to. If given a character that isn't an alias, returns the same one. Thus, 311. FS ^R IND returns 11. FS ^R INHIBIT when nonzero prevents ^R from updating the display. If FS ^R INHIBIT is zeroed again, all the pending updating will be done at the next opportunity. FS ^R INIT FS ^R INIT returns the initial definition of the character whose ASCII code is ; in other words, FS ^R INIT always returns what FS ^R CMACRO initially returns. The atsign modifier works for FS ^R INIT just as it does for FS ^R CMACRO; it says that the arg is a 9-bit code rather than ASCII. FS ^R INSERT the internal ^R-mode insert routine's user interface. It takes one argument - the ASCII code for the character to be inserted. This command itself take care of notifying ^R of the change that is made, so when returning to ^R this change should not be mentioned in the returned values (so if this is the only change made, return 1 value). This command is very sensitive; if the buffer or even "." has changed since the last time ^R was in progress or an @V was done, it may not work. Its intended use is in macros which, after thinking, decide that they wish only to insert 1 or 2 characters (such as a space-macro which might continue the line but usually inserts a space). FS ^R LAST holds the most recent character read by any ^R invocation (quite likely the one being processed right now). Commands that wish to set up arguments for following commands should zero FS ^R LAST, which tells ^R not to flush the argument when the command is finished. FS ^R LEAVE is macroed (if not zero) whenever ^R returns normally (including FS ^R EXIT but not throws that go out past the ^R). FS ^R MARK holds the mark set by ^T in ^R mode, or -1 if there is no mark. FS ^R MAX holds the maximum number of characters of insertion or deletion that will be printed out by ^R on a printing terminal. Larger changes will cause ^R to echo the command instead of displaying its effect. The default value is 50 . FS ^R MCNT the counter used by ^R to decide when to call the secretary macro. It starts at FS ^R MDLY and counts down. FS ^R MDLY sets the number of characters that should be read by ^R mode before it invokes the secretary macro kept in q-register ..F . Characters read by user macros called from ^R are not counted. FS ^R MODE (read-only) non-zero while in ^R-mode. FS ^R MORE if positive, --MORE-- is used for ^R-mode display instead of the usual --TOP--, --BOT-- and --nn%--. This is useful in command environments where Space means "show the next screenfull". If negative, then neither --MORE-- nor --TOP-- is displayed. This may be desirable on slow terminals, and also allows ..J to make use of the full width of the mode line. FS ^R NORMAL all "self-inserting" characters in ^R mode are really initially defined to go indirect through this word, if it is nonzero. If it is zero, as it is initially, the default definition is used for such characters. FS ^R PAREN holds a function to be executed whenever a self-inserting character is inserted whose Lisp syntax is ")". The idea is that this function will point out the location of the matching open parenthesis. If FS ^R PAREN is zero, the feature is turned off. FS ^R PREVIOUS holds the previous (second most recent) command read by ^R's command loop, not counting argument setting commands. FS ^R REPLACE if nonzero puts ^R in "replace mode", in which normal characters replace a character instead of simply inserting themselves. Thus, the character A would do DIA instead of just IA. There are exceptions, though; a ^H, ^J, ^L or ^M will not be deleted, and a tab will be deleted only if it is taking up just one space. Also, characters with the meta bit set will still insert. Replace mode actually affects only the default definition of "normal" characters. Characters which have been redefined are not affected, and if FS ^R NORMAL is nonzero no characters are affected (unless the user's definitions check this flag). Making FS ^R REPLACE positive has the additional effect of forcing all meta-non-control characters to be come normal, suppressing their definitions. FS ^R RUBOUT the internal ^R rubout routine's user interface. Takes 1 arg - the number of characters to rub out. This command is very sensitive and may fail to work if the buffer or "." has been changed since the last time ^R was in control, or an @V, FM, FS ^R RUB or FS ^R INSERT was done. Its intended use is for macros which, after thinking, decide to do nothing but rub out one character and return; it gives extra efficiency but only when rubbing out at the end of the line. FS ^R SCAN if nonzero causes ^R commands, when using a printing terminal, to try to imitate a printing terminal line editor by printing the characters they insert/delete/move over. FS ^R ECHO should be 1, to avoid double-echo. FS ^R STAR if nonzero, a star appears in the mode line if the buffer is modified. It is nonzero by default. FS ^R SUPPRESS (initially -1) nonnegative => builtin ^R-mode commands are suppressed, except for rubout, and user-defined commands are suppressed unless their definitions begin with "W". Suppressed command characters become self-inserting. The char whose 9-bit value is in FS ^R SUPPRESS is the unquoting char. It reenables suppressed commands temporarily by setting FS ^R UNSUPPR to -1. If FS ^RSUPPRESS is > 511, there is no unquote char. FS ^R THROW returns control to the innermost invocation of ^R. This is different from FS ^R EXIT, which returns control FROM that invocation. FS ^R TTM1 can be set to a macro to be called to handle long cursor motions in ^R mode on printing terminals. A long cursor motion is one which changes the vertical position upward or by more than one downward. Short cursor motions will still be handled by ^R itself. The macro in FS ^R TTM1 receives the old value of point as an argument, with point set to its new value. If FS ^R SCAN is zero, cursor motion is not handled at all and this macro is not called. FS ^R UNSUPP (initially 0) actually, builtin commands are suppressed only if this flag and FS ^RSUPRESS are nonnegative. However, this flag is zeroed after each command except ^U and ^V. Thus, setting this flag to -1 allows one builtin comand. FS ^R V MIN (read only) is the vpos of the first change on the screen needing redisplay. It will be a large positive number if no redisplay is required. If FS WINDOW is negative then the value of this flag doesn't matter. FS ^R VPOS the ^R-mode cursor's vertical position. FS _ DISABLE controls treatment of the "_" command. If 0 (the default), "_" is "search-and-yank" as it originally was. If 1, "_" is illegal (gives "disabled command" error). If -1, "_" is treated like "-" (good on memowrecks).  File: TECMAN Node: Flow Up: Concept TECO COMMANDS: Flow control (branching, conditionals) !