-*-TEXT-*- Copyright (c) 1999 Massachusetts Institute of Technology This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ------------------------------  File: ITSTTY Node: Top Next: A Up: (DIR) This file describes just about all there is to know about using and programming TTYs (abbreviation for "Teletypes", for which read "consoles") on the ITS operating system. * Menu: * Special: A Characters specially interpreted when typed on the tty. * Control: B "Control of the tty". * Opening: C Opening tty channels. * Input: D Input from terminals. * Output: E Output to terminals. * More: F **MORE** processing. * Vars: G Per-tty/per-job variables. * Perm: H Permanent and semipermanent tty information. * STYs: I Pseudo-teletypes (STYs). * Smart: J The intelligent terminal protocol. * SofTTYs: K Software ttys and ITS output buffer codes. This is the complete table of contents for this file: A. CHARACTERS SPECIALLY INTERPRETED WHEN TYPED ON THE TTY. 1. INTERRUPTING THE PROGRAM - THE CALL FUNCTION. a. Deferred CALL. 2. ENTERING STRANGE CHARACTERS - THE ESCAPE FUNCTION. a. Quoting the Characters Used for CALL and ESCAPE. b. "^_". c. Supplying Meta-Bits on Non-TV's. 3. MODE SETTING USING ESCAPE. a. "^_M" - Complement **MORE** Processing (%TSMOR). b. "^_^" - Complement Scroll-mode (%TSROL). c. "^_""" - Complement Use of SAIL Character Set (%TSSAI). d. "^_U" - Complement conversion to upper case (%TOCLC) 4. COMMUNICATE MODE. a. Entering a Com Link. b. Querying. c. Leaving a Com Link. d. When the System Prints "^_N". e. Input and Output Overrides. f. Slaving Another Terminal. g. Telling the System How to Respond to "^_C" Requests. 5. LIST OF ESCAPE CODES. B. "CONTROL OF THE TTY". 1. WHAT DETERMINES WHO HAS THE TTY. 2. .ATTY AND .DTTY. 3. PERMISSION TO TYPE OUT. 4. THE .TTY VARIABLE. 5. THE .CNSL VARIABLE. C. OPENING TTY CHANNELS. 1. OPENING "TTY". 2. OPENING "Tnm". 3. DEVICE-DEPENDENT BITS IN THE OPEN MODE. a. Per-channel Bits. b. Other Per-channel Bits on Input. c. Other Per-channel Bits on Output. d. First-time Bits on Output. e. First-time Bits on Input. D. INPUT FROM TERMINALS. 1. ECHO. 2. MAIN-PROGRAM INPUT. 3. ACTIVATION. 4. INPUT INTERRUPTS. 5. THROWING AWAY TYPE-IN. 6. TESTING FOR THE AVAILABILITY OF INPUT. 7. .STATUS ON TTY INPUT CHANNELS. 8. THE CHARACTER SET E. OUTPUT TO TERMINALS. 1. HOW TO CAUSE CHARACTERS TO BE OUTPUT. 2. NORMAL OUTPUT (SEQUENTIAL ACCESS). a. How the System Goes about Outputting. 1: ASCII Graphic Characters. 2: "^G". 3: Carriage-return. 4: Linefeed. 5: Tab. 6: Control-L (Formfeed). 7: Altmode. 8: Control-P. 9: Backspace. 10: Random Control Characters, and Rubout. b. Continuation - the Result of Line-overflow. c. Wraparound and Scrolling - the Results of Page-overflow. 1: Scrolling. 2: Wraparound. 3. DISPLAY-MODE CHANNELS. ^P-CODES. 4. THE ECHO AREA. a. How the Echo Area Works. b. Creating an Echo Area. 5. READING THE CURSOR POSITION. 6. SUPERIMAGE OUTPUT. 7. RELEVANT TTYOPT BITS. 8. THROWING AWAY TYPEOUT. 9. WAITING FOR OUTPUT TO BE SENT TO THE TERMINAL. 10. .STATUS ON TTY OUTPUT CHANNELS. F. **MORE** PROCESSING. 1. WHEN **MORE** PROCESSING IS TRIGGERED. 2. HOW **MORE** PROCESSING OPERATES. a. Stupid Programs. b. Smart Programs. 3. PROGRAMMED INVOCATION OF **MORE** PROCESSING. 4. INHIBITION OF **MORE** PROCESSING BY INPUT. G. PER-TTY/PER-JOB VARIABLES. 1. THE VARIABLES. a. the TTYST1 and TTYST2 variables. b. The TTYSTS variable. c. The Size of the Echo Area. 2. SYMBOLIC SYSTEM CALLS. a. TTYGET - read TTYST1, TTYST2, TTYSTS. b. TTYSET - set TTYST1, TTYST2, TTYSTS. c. SCML - Set Number of Command Lines. H. PERMANENT AND SEMIPERMANENT TTY INFORMATION. 1. THE VARIABLES. a. The Screen Size. b. The TTYOPT variable. c. The TCTYP variable. d. The TTYTYP variable. e. The TTYCOM variable. f. The TTYROL variable or "Scroll Count". g. The TTYSMT variable. 2. SYSTEM CALLS. a. RSSIZE. b. CNSGET. c. CNSSET. d. TTYVAR. I. PSEUDO-TELETYPES (STY'S). 1. OPENING STY'S. 2. OUTPUT TO STY'S. a. What happens when the buffer is empty. b. Interrupts. c. RESET on sty output channels. d. STATUS on sty output channels. 3. INPUT FROM STY'S. a. What happens when the buffer is empty. b. Interrupts. c. .STATUS on sty input channels. d. .RESET on sty input channels. 4. CLOSING STY'S. 5. CONTROLLING THE TTY ASSOCIATED WITH A STY. 6. DIRECT CONNECTIONS TO NETWORK CHANNELS: STYNET. 7. STYGET. J. THE INTELLIGENT TERMINAL PROTOCOL. 1. ESCAPE SEQUENCES. 2. ALLOCATION. 3. OUTPUT-RESET. K. SOFTWARE TTYS AND ITS OUTPUT BUFFER CODES. 1. ITS OUTPUT BUFFER CODES. 2. HANDLING %TDORS. 3. THE SCPOS SYSTEM CALL.  File: ITSTTY, Node: A, Previous: Top, Up: Top, Next: B A. CHARACTERS SPECIALLY INTERPRETED WHEN TYPED ON THE TTY. Normally, characters type on terminal keyboards have effect only by being read and acted on by user programs. There are, however, a few important exceptions. * Menu: * Interrupting: A/1 Interrupting the program - the CALL function * Strange: A/2 Entering strange characters - the ESCAPE function * Mode Setting: A/3 Mode setting using ESACPE * Communicate: A/4 Communicate mode * Escape Codes: A/5 List of ESCAPE codes  File: ITSTTY, Node: A/1, Previous: A, Up: A, Next: A/2 1. INTERRUPTING THE PROGRAM - THE CALL FUNCTION. A function available on all terminals that are in use as consoles is to stop the current program and interrupt its superior. On TV's, this function is requested by hitting the "CALL" key; on other terminals, which have no "CALL" key, the character "^Z" is used. This makes the character "^Z" difficult to type in as a normal characters on such terminals, requiring quoting (*Note Quoting: A/2.). In detail, the CALL function gives the job which owns the tty (*Note TTY-owning: B.) a fatal interrupt, causing its superior in the tree to be interrupted. The superior will usually react by retrieving the terminal from the job that had posessed it. Thus, CALL makes it possible to regain control when the program that has the terminal is out of control. When the terminal is in super-image input mode (%TSSII is 1), the CALL function is disabled - attempts to use it merely generate input to the program. Programs should not lightly enter this mode. a. Deferred CALL If you want to return from a program to DDT after the program is finished, if you use ordinary CALL you must not type it until then. And since DDT will flush all input when it sees the CALL, you can't type anything else until you have seen DDT respond. The "deferred CALL", which you can type as Control-CALL on a TV or as ^_D on any terminal, does about the same thing that ordinary CALL does except that it does not take effect until the program tries to read it. It thus acts like an "exit" command in all programs. DDT distinguishes deferred CALLs from ordinary ones (deferred ones give the program a %PIDCL interrupt instead of a %PIC.Z), and does not throw away input. Thus, you can type the deferred CALL ahead, and also some DDT commands to follow it.  File: ITSTTY, Node: A/2, Previous: A/1, Up: A, Next: A/3 2. ENTERING STRANGE CHARACTERS - THE ESCAPE FUNCTION. The ESCAPE function is requested by typing "BACK-NEXT" on TV's. This character is available as "^_" (control-underscore) on most terminals which have no "BACK-NEXT" key; on Lisp Machine keyboards it is labeled SCROLL or MACRO. The character used for the ESCAPE function is hard to type in, just as the character used for the CALL function is. However, it provides a mechanism that solves those problems. Note that the ITS ESCAPE terminal function should not be confused with the "ESCAPE" key on TV keyboards, which escapes all the way to the PDP-11 which handles the TV's. In the following, "^_" will designate the ESCAPE function, unless otherwise stated, regardless of whether it is actually obtained by the character "^_". * Menu: * Quoting: A/2/a Quoting the chars used for CALL and ESCAPE * ^_: A/2/b * Meta-bits: A/2/c Supplying Meta-Bits on Non-TV's  File: ITSTTY, Node: A/2/a, Previous: A/2, Up: A/2, Next: A/2/b a. Quoting the Characters Used for CALL and ESCAPE. One of the uses of the ESCAPE function is to enter characters that are not on the keyboard or otherwise hard to type in. The characters used for the CALL and ESCAPE functions may be entered as normal input by preceding them with an ESCAPE, which "quotes" them. For example, on a non-TV, typing "^_^_" causes a single "^_" to be read by the program, to interrupt if the program has enabled interrupts, etc., and "^_^Z" does the same thing for "^Z".  File: ITSTTY, Node: A/2/b, Previous: A/2/a, Up: A/2, Next: A/2/c b. "^_". If the terminal's keyboard is missing a character, that character may be entered by typing ESCAPE followed by the octal numerical code for the character. The number may have any number of digits, and is terminated by the first non-digit. If that non-digit is a space, it is discarded; otherwise, it is taken normally as input. The character entered as digits will be echoed (if echoing of that character is turned on). Thus, "^_001 " inputs a "^A" and echoes as "^_001^A", and "^_1q" enters "^Aq" and echoes as "^_1^Aq".  File: ITSTTY, Node: A/2/c, Previous: A/2/b, Up: A/2, Next: A/3 c. Supplying Meta-Bits on Non-TV's. It is possible to enter characters in the TV character set that are not in ASCII, using the ESCAPE function followed by ^B, ^C, ^D, or ^F, followed by the basic ASCII character. ^B means "set the CONTROL bit"; ^C, the META bit; ^F, the SUPER bit; ^D, the TOP bit. Any combination of those four characters should be followed by the basic ASCII character with which those bits will be OR'ed. To specify one of those four control characters, or ^Q, as the basic ASCII character, quote it with ^Q. For example, "^_^B^C1" specifies CONTROL-META-1. "^_^BA" is CONTROL-A, which has the code 301, and is not the same as ^A (code 001). The TOP bit is useful for programs (such as TECO) which distinuish SAIL graphics characters from CONTROL characters. TECO treats an ASCII ^K as an alias for CONTROL-K, but ^_^D^K (TOP-^K) is believed to be the SAIL character Uparrow. The reason that ^B and ^C stand for CONTROL and META is that they correspond to the SAIL characters Alpha and Beta, which are traditionally used for this purpose.  File: ITSTTY, Node: A/3, Previous: A/2, Up: A, Next: A/4 3. MODE SETTING USING ESCAPE. Most of the switches that are associated with each terminal are intended to be set or cleared by means of the TCTYP program. However, there are two switches for which each job that can use the terminal has its own setting. The TCTYP program may be used to set the default values of the switches, which are used to initialize new jobs. ESCAPE codes are provided for complementing the switch associated with the job that the terminal belongs to at the moment. a. "^_M" - Complement **MORE** Processing (%TSMOR). When **MORE** processing is enabled, the system causes output to pause at the bottom of the screen, until a space is typed. b. "^_^" - Complement Scroll-mode (%TSROL). When a terminal is in scroll mode, linefeeding past the bottom of the screen causes everything on the screen to move up, instead of wrapping around to write at the top of the screen. c. "^_""" - Complement Use of SAIL Character Set (%TSSAI). When %TSSAI is set, ascii mode and echo mode output of non-formatting control characters will send the character unmodified, assuming it to be a graphic character. Thus, "^B" will echo as an alpha, etc., on terminals that can handle the SAIL character set. d. "^_U" - Complement conversion to upper case (%TOCLC) When %TOCLC is set, characters typed at the terminal are converted to uppercase.  File: ITSTTY, Node: A/4, Previous: A/3, Up: A, Next: A/5 4. COMMUNICATE MODE. It is possible for a group of terminals to be put in a "com link". When that is done, anything typed on any one of the terminals echoes on all of them. Normally, what is typed on a terminal that is in a com link is ignored except for that echoing, however the user may cause it to be treated as normal input (see "^_I"). Also, programs are usually prohibited from typing out while the tty is in a com link, but that may be changed by the user (see "^_O"). It is also possible to cause one of the terminals in a com link to supply input for and view the output from another (see "^_S" and "^_E"). * Menu: * Entering: A/4/a Entering a COM link * Querying: A/4/b * Leaving: A/4/c Leaving a COM link * ^_N: A/4/d When the system prints "^_N" * Overrides: A/4/e Input and output overrides. "^_I" and "^_O". * Slaving: A/4/f Slaving another terminal. "^_S" and "^_E". * Respond: A/4/g Telling the system how to respond to "^_C" requests  File: ITSTTY, Node: A/4/a, Previous: A/4, Up: A/4, Next: A/4/b a. Entering a Com Link. From any terminal, a com link with any other terminal may be requested by means of "^_C", which should be followed by the number of the terminal to be linked to, or by the uname of the user logged in on that terminal. The name or number is terminated by the first space or CR, except that any number of spaces or CR's may follow right after the "C" and will be ignored. It is allowed for either the terminal on which "^_C" is typed or the terminal to which a link is requested to be in a com link already; in either case, if the request succeeds both of the terminals and all the other terminals that had been linked to either of them will form one com link. If there is no terminal with the specified number, or no one is logged in with the specified uname, the "^_C" will have no effect, and a "?" will be typed. The same thing will happen if the specified terminal is already in a com link with the requesting terminal. If the specified terminal is in the middle of typing in an ESCAPE code, or has characters unprocessed in its input buffer, the "^_C" fails, typing "Busy". When that happens, it is reasonable to try again in a few seconds. If the specified terminal's user has ordered it ro refuse com links, with "^_R" (it is in "refuse mode"), then "Refused" will be typed, and the request will fail. If these conditions for "^_C" are met, the request is basically acceptible, and what happens to it depends on whether the specified terminal is in "accept mode" (the usual case) or in "query mode". In accept mode, the two terminals will be linked right away. If the target terminal is already in a com link, a list of the terminals in that com link will be typed out and the user will be asked whether he wants to "break in". An answer other than "Y" or "y" will abort the request. In query mode, the specified terminal must be asked whether the link should be made - that process will be described later. Assuming that the specified terminal is in accept mode, and that if necessary the user has decided to break in, then, the link will be created, and the requesting terminal will be informed that the request has succeeded by a "OK". "F" will be typed in addition if the specified terminal is free. The "OK" tells the requesting user that he is linked to the specified terminal, but he may also be linked without knowing to other terminals already linked to the specified terminal. Also, the other terminals in the link at this point know nothing. Therefore, messages are typed on the terminals as follows: on the specified terminal and all terminals linked to it, the message "LINK FROM " will be typed, where the includes the requesting terminal and all terminals linked to it, and a terminal is referred to by its uname if it is a logged in console, and as "Tnn" otherwise. Also, if there are other terminals already linked to the requesting terminal, the message "LINK TO " will be typed, naming the specified terminal and any other terminals linked to it. Also, if the specified terminal is already linked to others, the message "LINK TO " naming only those others, and not the specified terminal, will appear on the requesting terminal. The result of all of those messages is that each terminal that ends up in the new com link is informed of all the other terminals that it is becoming linked to.  File: ITSTTY, Node: A/4/b, Previous: A/4/a, Up: A/4, Next: A/4/c b. Querying. When the specified terminal is in query mode (*Note ^_Q: A/4/g.), "QUERYING" is typed on the requesting terminal, and the "LINK FROM ..." message is typed on the specified terminal only (NOT on the terminals linked to it already), followed by "QUERYING", which informs its user that he is being queried. He need not pay immediate attention to the query, and his commands will continue to go to his program. When he wishes to respond, he may do "^_Y" to accept the link, "^_Z" to to refuse it, "^_Q" to list the people querying, or "^_C" to a specific user querying him. Such a "^_C" will always succeed immediately, even if the target is in refuse mode or query mode, as long as he is querying the "^_C"'er. This is how to accept some but not all of several simultaneous queries. When a query is accepted or rejected, "OK" or "REFUSED" will be typed on the requesting terminal. Until that happens, the requesting terminal may not do anything but "^_N" to give up waiting, aborting the request, or ^G, which echoes on the terminal being queried, to attract its user's attention. If "^_N" is used to abort the request, the queried terminal is not informed. If the request is accepted, "OK", the "LINK TO ..." messages and the remaining "LINK FROM ..." messages are typed as they would have been for accept mode.  File: ITSTTY, Node: A/4/c, Previous: A/4/b, Up: A/4, Next: A/4/d c. Leaving a Com Link. Any terminal may be removed from a com link by typing "^_N" on it. Also, any terminal in a com link may remove any of the other terminals from that link by typing "^_K" followed by the uname or number of the terminal to be unlinked (using the same syntax as "^_C"). If there is only one terminal left in the com link, the link is destroyed, and that terminal also returns to normal. Otherwise the terminals remaining in the link continue to be linked, and "BYE FROM " is typed on each of them.  File: ITSTTY, Node: A/4/d, Previous: A/4/c, Up: A/4, Next: A/4/e d. When the System Prints "^_N". Whenever a terminal enters a com link, or makes a "^_C" request, it is said to enter "com mode". That causes input not to be passed to the program, and prevents programs from typing out (but see "^_I" and "^_O"). This state persists until the terminal is no longer in com mode. Therefore, the system informs the user that the terminal has left com mode by typing "^_N" on the terminal, unless the terminal has left com mode because the user has just typed "^_N" on it (the idea is that if a "^_N" has just echoed there is no need to supply another).  File: ITSTTY, Node: A/4/e, Previous: A/4/d, Up: A/4, Next: A/4/f e. Input and Output Overrides. Normally, on a terminal in com mode input is not passed to the program and programs may not type out (.IOT's hang). That can be explicitly changed with "^_I" and "^_O". "^_O" complements the %TCOCO switch which, if on, allows programs to output to the terminal even when it is in com mode. %TCOCO is initialized to 0 whenever a terminal is initialized (when it starts to be used after being free for a while). DDT turns %TCOCO on temporarily when printing unsolicited messages such as "ITS GOING DOWN". %TCOCO can be set with :TCTYP OCO and cleared with :TCTYP NO OCO. "^_I" complements the %TCICO switch which, if on, causes input to be passed to the program even when in com mode, and also allows programs to type out (just like %TCOCO). %TCICO is initialized to 0 at the same time as %TCOCO, and may also be set with :TCTYP. Note that when the switch is off all characters echo regardless of what the program has requested, but when the switch is on, characters echo or not just as they would when not in com mode, according to the program's setting of the TTYST1 and TTYST2 variables.  File: ITSTTY, Node: A/4/f, Previous: A/4/e, Up: A/4, Next: A/4/g f. Slaving Another Terminal. In any com link at any time one terminal may be slaved. That means that those other terminals that wish to may supply input to the program using the slaved terminal, and see the output typed on it. (Actually, it isn't too hard to cause there to be two slaved terminals in a link). Any terminal that is slaved will always see program output, regardless of the setting of the "^_O" switch. The "^_I" switch functions normally on slaved terminals. Any terminal may explicitly slave any other terminal linked to it, by means of "^_S", which has the same syntax as "^_C". This automatically unslaves all terminals in the link other than the one requested to be slaved. Each terminal has a switch that determines whether input typed on it should be sent to the slaved terminal in the link, if there is one. This switch is complemented by "^_E", and initialized off when com mode is entered. If there are exactly two terminals in the link, typing "^_E" on one automatically does a "^_S" to the other. Otherwise, both the "^_E" and the "^_S" must be done to get any effect. If a terminal's "^_I" switch and its "^_E" switch are both set, input from it will be fed to both its own programs and those of the slaved terminal. That is, the two switches are independent. Similarly, the "^_O" switch does not interact with the "^_E" switch.  File: ITSTTY, Node: A/4/g, Previous: A/4/f, Up: A/4, Next: A/5 g. Telling the System How to Respond to "^_C" Requests. Any terminal may be in any one of three modes: accept mode, refuse mode, and query mode. Accept mode is the default, and causes "^_C" requests to succeed; refuse mode causes them to fail; query mode causes them to query as described in section b. Accept mode may be entered by typing "^_A"; refuse mode, by "^_R"; query mode, by "^_Q". In addition, "^_A" accepts all pending queries, and "^_R" refuses them. The program TCTYP also has the capability of changing the mode, using the CNSSET system call. The information is stored in the bits %TCRFS and %TCQRY in the TTYCOM variable (*Note Combits: H/1/e.).  File: ITSTTY, Node: A/5, Previous: A/4, Up: A 5. LIST OF ESCAPE CODES. In most cases, the escape code name is also the name of a footnote leading to a node containing more details on the specific code. ^_^Z Program receives "^Z". No quitting action, etc. ^_^_ " " "^_". No special action ^_" Complement %TSSAI for the job which has the tty. That flag, if 1, says that the SAIL character set should be used for echo mode and ascii mode output. *Note ": E/2/a. ^_ Enter the character whose ASCII code is . *Note nnn: A/2/b. ^_A Set "accept mode". *Note A: A/4/g. ^_B Cause typeout to pause. *Note B: F/1. ^_C Communicate with another terminal. *Note C: A/4/a. ^_D Deferred Call. *Note D: A/1/a. ^_E Start or stop sending input to a slaved terminal. *Note E: A/4/f. ^_I Complement the input override flag (%TCICO). *Note I: A/4/e. ^_J Give a %PIJST interrupt to the job that has the tty, or the closest superior that has the interrupt enabled. ^_K Take some other terminal out of com link. *Note K: A/4/c. ^_L Clears the screen (echoes "^PC"). ^_M Complement **MORE** processing for job that has the tty. *Note M: F/2. ^_N Leave com link or quit waiting for answer to query. *Note N: A/4/c. ^_O Complement the output override flag (%TCOCO). *Note O: A/4/e. ^_Q Set "query mode" (%TCQRY). *Note Q: A/4/g. ^_R Set "refuse mode" (%TCRFS). *Note R: A/4/g. ^_S Slave a specified terminal. *Note S: A/4/f. ^_U Complement conversion of to upper case (%TOCLC). *Note U: A/3/d. ^_Y Say yes to a query. *Note Y: A/4/b. ^_Z Say no to a query. *Note Z: A/4/b. ^_^ Complement scroll mode for job that has the tty. *Note ^: A/3/b. ^_^U Clear input for this TTY. This completely flushes what is in the input buffer and is useful for getting rid of unwanted typeahead.  File: ITSTTY, Node: B, Previous: A, Up: Top, Next: C B. "CONTROL OF THE TTY". A terminal that is a console may be used by any of the jobs in its tree, but not all at once. At any time, the terminal belongs to a particular job, and for the most part only that job can use it. Also, all input and output interrupts go to that job only. If any other job in the tree tries to use the tty for anything except to type out, it will not succeed (it may wait until it is allowed to use the tty, it may get an interrupt, or its system call may simply fail, depending on what the job is doing and on the setting of some bits in .TTY, described below). Permission to type out is controlled by a separate mechanism. The job that is allowed to use the tty is said to "have control of the tty", or to "have the tty". The .ATTY and .DTTY UUO's allow control of the tty to be passed between the jobs in a tree. * Menu: * Who Has: B/1 What determines who has the TTY * ATTY: B/2 .ATTY and .DTTY * Permission: B/3 Permission to type out * .TTY: B/4 The .TTY variable * .CNSL: B/5 The .CNSL variable  File: ITSTTY, Node: B/1, Previous: B, Up: B, Next: B/2 1. WHAT DETERMINES WHO HAS THE TTY. Each job has a variable - called .TTY, readable with a .SUSET or .USET - that says, among other things, whether it wishes to retain the tty or to pass it on to a particular one of its inferiors. Each job can alter that setting at any time. The instantaneous values of the .TTY variables of all the jobs in a tree determine which of them has the tty, as follows: If the top level job wishes to retain the tty, then it owns the tty; otherwise, if the one inferior which it wishes to pass the tty on to wishes to retain the tty, then that job owns the tty; otherwise the job that job wishes to pass the tty on to has its chance, etc. In other words, at any instant the tty is as far down as it can get before being blocked from further descent by a job that wishes to retain it.  File: ITSTTY, Node: B/2, Previous: B/1, Up: B, Next: B/3 2. .ATTY AND .DTTY. .DTTY is used when a job decides that it wishes to retain the tty. It skips if it succeeds; it fails if the job was already in the state of wishing to retain the tty, If the tty had actually belonged to some (possibly indirect) inferior, it will belong after the .DTTY to the job that executed it. The ATTY operation puts the job in the state of wishing to pass control of the tty to one of its direct inferiors. This is known as an "ATTY'ing state". If a job which is in an ATTY'ing state is allowed ownership of the TTY by its superiors (ie, they too are in ATTY'ing states pointing down to this job), then ownership passes yet another level to the ATTY'd inferior. Whenever an ATTY is done, the %TSATY bit will be set to 1 in TTYSTS, and the inferior receiving the tty will be given a %PIATY interrupt if it is enabled. The ATTY operation can be done with either the .ATTY UUO or the ATTY symbolic system call. .ATTY , specifies the inferior open on channel . The ATTY symbolic system call takes one argument, a job spec, to specify the inferior to ATTY to. ATTY'ing is illegal for the job which has the tty, when the %TSLCZ bit is set (meaning that the last char typed on the tty was "^Z"). This is a half-hearted attempt to make it possible to "^Z" up several levels past programs that are trying to prevent that. Since super-image input mode now exists, such an attempt is futile. This "feature" can probably be flushed if anyone wishes. The "P" command causes DDT to do an .ATTY, among other things. "^P" does not. DDT does a .DTTY when an "P"'ed job returns to DDT. A job need not have the tty to do an .ATTY or .DTTY. In fact, they are the only operations on ttys that work as well without the tty as with it.  File: ITSTTY, Node: B/3, Previous: B/2, Up: B, Next: B/4 3. PERMISSION TO TYPE OUT. The job that owns the TTY, and the job at the top of the tree, can always type out on the TTY. Those jobs can also grant permission to some of their inferiors, which can in turn grant it to their inferiors, and so on. Such indirect permission is controlled by two bits in the .TTY variable of each job. One bit, %TBOUT, is set by the superior to 1 to grant permission, or to 0 to deny it, to the job whose %TBOUT bit it is. The other, %TBINF, if set to 0, denies all inferiors permission to type out without forgetting the states of their %TBOUT's. A job inherits type-out permission from its superior only if its own %TBOUT and the superior's %TBINF are both 1. A job has type-out permission iff a chain of inheritance reaches up from it to the top of the tree or to the job which owns the TTY. The DDT command ^P works by means of this feature.  File: ITSTTY, Node: B/4, Previous: B/3, Up: B, Next: B/5 4. THE .TTY VARIABLE. This variable is actually called TTYTBL in the system. "%TB" and "$TB" identify bits and fields in the TTYTBL variable, which contains the information on the status of a job with respect to its console tty (if any). Note that it is not necessary for a job to belong to a tree that has a tty for these bits to make sense. The $TBECL field is actually a shadow location for a per-tty/per-job variable; it only contains real information when the job does NOT have the tty. Most of the fields are set only by the system, but %TBNVR and %TBINT are user options, settable by .SUSET or .USET. They decide what the job will do when it tries to use the tty, but doesn't have it. %TBNOT==400000 ;4.9 1 iff the job does not have the tty. %TBNVR==200000 ;4.8 1 => opens of TTY: should fail when ;the job does not have the tty. %TBINT==100000 ;4.7 1 => all attempts to use the tty when ;the job doesn't have the tty, should cause class 2 ;interrupts on bit 4.2 (%PJTTY) of the first interrupt word. ;0 => such attempts wait until the job gets the tty. %TBWAT==040000 ;4.6 1 => override the settings of %TBNVR and ;%TBINT, and always wait for the TTY. This bit can ;be set only by the job's superior, and means "you ;are supposed to have the TTY, even though for a ;short interval you may not really have it". %TBDTY==010000 ;4.4 1 iff job doesn't have tty, but wishes ;to retain it. Set by .DTTY, cleared by .ATTY. %TBOUT==004000 ;4.3 1 => this job can inherit type-out permission ;from its superior (can be altered only by superior). %TBINF==002000 ;4.2 1 => inferiors are allowed to inherit type-out ;permission from this job. $TBECL==220600 ;3.1 - 3.6 the job's setting of the number of ;lines in the echo area, if the job doesn't have ;the tty. RH: ;If the job has the tty, this is the tty number. ;If the job is in an .ATTY'ed state, this has the ;internal user index of the inferior the tty ;should be passed on to. ;Otherwise, 0.  File: ITSTTY, Node: B/5, Previous: B/4, Up: B 5. THE .CNSL VARIABLE. If a program needs to know the number of its tree's tty (or of some other job's tree's tty), it can get that information without actually possessing the tty by reading the .CNSL user variable. That variable contains the number of the tree's tty if there is one; -1 for a job scheduled as part of the system; -2 for a job scheduled as a disowned job. for a job device or its inferior, .CNSL will be the same as for the creator of the job device.  File: ITSTTY, Node: C, Previous: B, Up: Top, Next: D C. OPENING TTY CHANNELS. Terminals may be opened for I-O using either device TTY: or device Tnm:. TTY should be used by a job in a console-controlled tree to open the console. Tnm should be used to open a terminal "as a device" - that is, to open a tty that is not the console of the job doing the opening. * Menu: * Opening: C/1 Opening "TTY:" and "Tmn:" * Bits: C/3 Device-dependent bits in the OPEN mode  File: ITSTTY, Node: C/1, Previous: C, Up: C, Next: C/3 1. OPENING "TTY". Device TTY may only be successfully opened by a job in a console- -controlled tree which is in posession of the tty. If a job which does not meet that criterion tries to open the tty, the open may hang, fail, or generate a fatal interrupt, depending on the setting of the %TBNVR and %TBINT bits of the job (*Note NoTTY: B/3.). What such an open will definitely not do is succeed. 2. OPENING "Tnm". Opening device Tnm is the way for a program to make use of a tty other than its console (in fact, it need not have a console). "nm" should be replaced by the two-digit octal number of the terminal to be used. In order for the opening of device Tnm to succeed, the specified terminal must not be in use by any other job. An attempt to open by number a tty which happens to be the console of the job doing the open will succeed iff the job has the tty at the time. This is to make it possible to specify one's own tty when asked to specify a tty by number.  File: ITSTTY, Node: C/3, Previous: C/1, Up: C, Next: D 3. DEVICE-DEPENDENT BITS IN THE OPEN MODE. Many of the bits in the mode specified in a .OPEN have special meanings for devices TTY and Tnm. Some of them affect only the channel being opened; others merely initialize some of the per-tty/ per-job information, but those bits are effective only if the terminal is not open in the same direction on any other channel (those bits exist for historical reasons only, since the variables they set may be set explicitly at any time using the TTYSET and SCML symbolic system calls (*Note vars: G.)). The per-channel bits which have names are used only to initialize the IOCHNM word of the channel - thus, mode bit 4.6 (%TIECH) is copied into bit 4.6 of the IOCHNM word. Various I-O operations examine the IOCHNM word to decide what to do. With symbolic system call IOT's, the user may temporarily alter the settings of those bits, so the values supplied in the open are merely the defaults for the channel. The per-channel bits that are not named are interpreted by the OPEN routine, and act by setting some of the named bits, as described below. They exist for historical reasons. (that does not include bits 3.1 and 3.2, which are special). * Menu: * Bits: C/3/a Per-channel bits * Other: C/3/b Other Per-channel bits on input and output * First: C/3/d First-time bits on output and input  File: ITSTTY, Node: C/3/a, Previous: C/3, Up: C/3, Next: C/3/b a. Per-channel Bits. 3.1 1 => output; 0 => input. Affects the interpretation of the other bits. 3.2 1 => block mode; 0 => unit mode. In block mode, each character is treated as in unit mode, except that on output, "^C" is ignored, and on input, "^C" typed in will act like end-of-file (that is, the .IOT will return with the last word padded out with "^C"'s and the pointer not fully counted out). "^C" also terminates SIOT's on unit input channels, but it is not ignored by output SIOT's.  File: ITSTTY, Node: C/3/b, Previous: C/3/a, Up: C/3, Next: C/3/d b. Other Per-channel Bits on Input. %TIECH==40000 ;1 => can read even if char needs pi echoing. %TIPEK==20000 ;1 => don't remove char from buffer. %TIACT==4000 ;1 => don't wait for activation character. %TIINT==2000 ;1 => can read a char even if it is supposed to interrupt & hasn't yet. %TINWT==1000 ;1 => do not wait for input. If no input is available, ;unit mode IOT's return -1; unit mode SIOT's and block mode ;IOT's return without filling up the space available to them. %TIFUL==400 ;1 => use the full TV character set if possible. ;suppresses the conversion, which is normally ;performed on TV's, from the TV character set ;to ascii. See ITS TV. c. Other Per-channel Bits on Output. 3.4 1 => turn on %TJECH, %TJPP2, and %TJMOR. 3.5 1 => turn on %TJDIS. 3.6 1 => turn on %TJSIO. %TJECH==40000 ;1 => echo mode output (all chars output the ;way they would be echoed) %TJCTN==20000 ;1 => don't do line-continuation. %TJSTP==10000 ;1 => this channel is hung in **more**. ;this bit is unusual in that the system changes it %TJDIS==4000 ;1 => recognize "^P" as an escape for display commands %TJSIO==2000 ;1 => superimage output, no padding or cursor control. %TJMOR==1000 ;1 => don't do **MORE** processing. %TJPP2==400 ;1 => output in the echo area if there is one.  File: ITSTTY, Node: C/3/d, Previous: C/3/b, Up: C/3 d. First-time Bits on Output. 3.3 1 => image mode (set all %TGIMG bits in TTYST1 and TTYST2) If you think you want to do this, you probably really want to use %TJSIO. e. First-time Bits on Input. 3.3 1 => image mode (clear all %TGPIE and %TGMPE bits in TTYST1, TTYST2). It is UNWISE TO USE THIS FEATURE, because it will prevent the user from translating TTY: to a file of commands for your program. You should use a TTYGET and TTYSET to change these bits, and you should not complain if they fail. 3.4 1 => "DDT" (clear %TGPIE and %TGMPE bits for CR, LF and TAB) 3.6 1 => want 3 lines in echo area. (that is, the OPEN should do a SCML with argument 3. *Note SCML: E/4.).  File: ITSTTY, Node: D, Previous: C, Up: Top, Next: E D. INPUT FROM TERMINALS. Characters typed on a terminal, aside from those that invoke the CALL and ESCAPE functions, go into an input buffer from which they may eventually be read by the program (if the buffer is full, they are discarded, and a "^G" is output). Before being read, they may be echoed (and usually will be). A character may also cause an input interrupt - this allows specific characters to signal a program to perform some action immediately, at any time, without waiting for the program to get around to looking for input. If %TOALT is set, and %TSALT is not, characters 175 and 176 will be turned into 33 (this is "standardization of altmodes"). * Menu: * Echo: D/1 Echo * MP Input: D/2 Main-program input. * Activation: D/3 Activation. * Interrupts: D/4 Input interrupts. * Throw: D/5 Throwing away type-in. * Avail: D/6 Testing for the availability of input. * .STATUS: D/7 .STATUS on tty input channels. * Char Set: D/8 The character set  File: ITSTTY, Node: D/1, Previous: D, Up: D, Next: D/2 1. ECHO. "Echoing" is the act of typing out whatever the user types in. Its purpose is to give the user positive verification of his type-in. On ITS, echoing works by taking the typed-in characters and outputting them in echo mode, in the echo area if there is one (that is, outputting with %TIECH and %TIPP2 set). There are two types of echoing: PI echoing, and MP (main program) echoing. PI echoing happens as soon as possible after the character is typed in. MP echoing happens when the character is read in by the program. Each program may specify which characters ought to be PI echoed, and which ought to be MP echoed, using the per-tty/per-job variables TTYST1 and TTYST2 (specifically, the %TGPIE and %TGMPE bits, of each of which there is one for each group). It is permitted to specify that a character not be echoed at all, or that it be echoed in both ways (PI and MP). Most programs specify that all characters be PI echoed, and none MP echoed; DDT choses to have LF and TAB not echoed at all; some programs such as TELNET and PDP11 in certain modes turn off all echoing. MP echoing is not used much if at all, and is not clearly useful, so it may be flushed in the future, although if an important use is found it will stay. Therefore, new programs should avoid using MP echo if possible. If use of it is very desirable, please :BUG ITS the application. Normally, a character cannot be read in until any necessary echoing has taken place. However, if reading is done with the %TIECH bit set, any echoing (of the characters thus read) not yet performed will be skipped entirely. This does not guarantee that such characters will not be PI echoed; it just means that the system will not regard the PI echoing as essential, and will forgo it rather than wait for it. MP echoing will certainly not be done for characters read with %TIECH set. Extra bits will be returned with such characters saying what kinds of echoing were appropriate but were not yet done, to enable the program to echo the character itself if that is right. The bits are %TXPIE=200000 saying PI echo was desired, and %TXMPE=400000 saying MP echo was desired. The bit %TSNOE in the TTYSTS variable (*Note TTYSTS: G/1/b.), when set to 1, causes echoing to be deferred; that is, echoing will not be performed while the bit is set, but the system still remembers what echoing is pending, and will again start doing it when %TSNOE becomes 0. However, if a character with pending echoing is read in while %TSNOE is 1, the pending echoing will of necessity be forgotten. When %TSNOE is 1, the system acts as if %TIECH were 1 on all input IOT's from that tty, since otherwise such IOT's wuld simply wait forever. In particular, the %TXPIE and %TXMPE bits in the character read will tell the user what sorts of echoing were still pending.  File: ITSTTY, Node: D/2, Previous: D/1, Up: D, Next: D/3 2. MAIN-PROGRAM INPUT. Characters are read from the tty using the .IOT UUO or the symbolic system calls IOT or SIOT. .IOT has slightly less overhead, but the symbolic system calls allow the channel's characteristics to be temporarily altered. Unit mode IOT's read a single character and return it. SIOT's and block mode IOT's try to read enough characters to fill the block supplied, but the character "^C" will cause them to return what has been read so far, with pointers and counts not fully advanced. SIOT and block mode IOT input from ttys is relatively useless; it is provided for the sake of device-independence. Programs should normally read from the tty in unit mode. IOT'ing on the job's console cannot actually be done unless the job has control of the console (*Note Owner: B.). If it does not, either the IOT will wait until the job gets the tty, or a class 2 interrupt will result, depending on the %TBINT and %TBWAT bits in .TTY (*Note NoTTY: B/3.). Also, on any tty, IOT's will wait until either the tty is not in a com link, or the tty is slaved, or %TCICO is set (*Note Com: A/4/e.). Input IOT's executed when the input buffer is empty will normally wait until input is available (*Note Wait: D/3.). However, if %TINWT is set, the IOT will not wait at all. Instead, unit mode IOT's will immediately return -1; SIOT's and block mode IOT's will return with the supplied block not completely filled and the pointer and count advanced to point to the first unfilled character or word. When an IOT attempts to read a character, if PI echoing is necessary for the character and has not been performed, the IOT waits until it has been (unless %TIECH is set, or %TSNOE is set). Also, if the character is supposed to cause an input interrupt, the IOT waits until the character has been processed at interrupt level with .ITYIC (unless %TIINT is set or .PICLR holds 0 preventing interrupts from occurring). In that case, the interrupt will normally occur as soon as the IOT hangs up, and if the interrupt routine dismisses normally, the IOT will then be able to read the character. When any necessary PI echoing or interrupting is finished, the IOT performs MP echoing if necessary and not yet done (unless %TIECH is set, or %TSNOE is set). The character is then removed from the input buffer and returned to the user (but if %TIPEK is set, the character is left in the input buffer, so that the next IOT will re-read it). If echoing that normally would have been required before the IOT could return has been omitted because of %TIECH or %TSNOE, the following extra bits will be returned along with the character read (in unit mode only): %TXPIE = 200000 meaning that PI echo would have been done, and %TXMPE = 400000 meaning that MP echoing would have been done. It is at this point, when the character is about to be returned to the user, that conversion from the TV character set to ascii is done unless the %TIFUL bit is set. This conversion happens on all terminals but it has no effect on characters which are already ascii,as all characters are if the terminal is not a TV. The way symbolic system call IOT's and SIOT's change the settings of the per-channel bits is with the control-bit argument, which is XOR'ed into the IOCHNM word at the beginning and end of the IOT. Thus, if %TIACT is normally 0, and it is desired to read one character with %TIACT set to 1, the following call may be used: .CALL [ SETZ 'IOT,, 1000,,TYIC ;CHANNEL. AC ;CHARACTER READ GOES IN AC. 405000,,%TIACT] ;IMMEDIATE CONTROL-BIT ARGUMENT. .VALUE ... ;CHARACTER NOW IN AC. Note that the IOT does not change the settings permanently; to do that, the channel must be reopened. The specified bits are changed only for the duration of the IOT that specifies them.  File: ITSTTY, Node: D/3, Previous: D/2, Up: D, Next: D/4 3. ACTIVATION. An input IOT will, for an unclever program, unhang as soon as there is any character to be read in. However, it may be known that a particular program never needs to respond to type-in until a character from some small set (such as CR and rubout; for TECO, altmode, rubout and "^C") has been typed in. Such programs may lighten the scheduling and swapping load on the system by saying that other characters should not be "activation characters". Then an IOT will usually not unhang unless at least one activation character has been typed in. Note that no lossage will occur if a character that need not activate does so. Also, some other conditions cause activation. The set of activation characters is specified using the %TGACT bits in the TTYST1 and TTYST2 variables. Initially, all of them are 1, meaning that all characters should activate. A program may be able to get away with a small set of activation characters except in a few special circumstances (for example, TECO needs to be able to respond immediately to a "?" typed as the first character when a command string is expected, but most of the time a "?" requires no immediate response). The program may then specify that small set for activation, and when the unusual circumstances arise, it can do input in a special way that does not wait for activation, either by IOT'ing with the %TIACT bit set to 1, or by setting %TSACT to 1 before each character is read. Both of those bits mean "activate on any character". Note that %TSACT is cleared after each character, so setting it only affects the next attempt to do input. %TIACT may be set temporarily using a symbolic system call IOT.  File: ITSTTY, Node: D/4, Previous: D/3, Up: D, Next: D/5 4. INPUT INTERRUPTS. A program may enable an interrupt to occur whenever a character is typed in. In the simplest case, any character will cause an interrupt, but the program may prevent uninteresting characters from interrupting by clearing their %TGINT bits in TTYST1 and TTYST2. There are two kinds of interrupts that may be enabled. If the tty is a console, bit 1.1 (%PITYI) in the first interrupt word may be enabled. This bit is obsolete and should be avoided. For any tty, whether console or device, an interrupt may be enabled on one of the input channels - in which case an interrupt will be signaled on one and only one of the enabled channels. Both kinds of interrupt are class 3. Most programs normally read their input at main program level, and want only a few characters to be processed at interrupt level. Such programs need to be able to examine the character which caused the interrupt. IOT'ing it will not do, for other non-interrupting characters may have been typed in before the interrupt character, and not read yet at main program level. ITS provides a special mechanism for doing this: .ITYIC, which reads the next not-yet-.ITYIC'ed interrupt character. The program should execute .ITYIC for each tty input interrupt to see what character caused it. The calling sequence is: MOVEI AC,CHANNEL .ITYIC AC, JRST GIVEUP ;PRETEND THIS INTERRUPT HADN'T HAPPENED. ... ;CHARACTER NOW IN AC. The .ITYIC will skip if it succeeds; it can fail if the channel number is bad or does not have a tty open, if the tty is the job's console but does not belong to this job at the moment, or because no interrupt character is available. It can also cause a class 2 interrupt if the %TBINT bit is set and the job does not have the tty. .ITYIC is actually a special case of the WHYINT generic system call. Doing a WHYINT on a TTY input channel will return %WYTYI as the first value and the character which caused the interrupt as the second. WHYINT was invented by generalizing .ITYIC to other sorts of devices. Thus, .ITYIC is actually semi-obsolete, but everyone still uses it. The program should ignore any interrupt caused by a character that isn't supposed to interrupt (due to timing screws and moving the tty from one job to another that can happen). It should also ignore an interrupt if the .ITYIC doesn't skip (that can happen if DDT took the tty away and flushed the input between the interrupting and the .ITYIC'ing). If the interrupt routine decides that it needs to examine the next character also, it can set %TSINT to 1. That will cause the following character to interrupt even if it normally wouldn't (TECO uses this to distinguish a solitary altmode from a pair of altmodes at interrupt level). This feature will work regardless of whether that "following" character has already been typed in. .ITYIC'ing does not eliminate the need to IOT the character - it is specifically designed not to interfere with the expected later IOT'ing of the character. If the interrupt character is supposed to have no effect except for the interrupt, then it must be ignored explicitly when IOT'ed. Alternatively, the character can be flushed explicitly from the input stream by using the TTYFLS symbolic system call (see ITS .CALLS). It is not necessary for the interrupt handler to keep .ITYIC'ing until no more characters are available, because a separate interrupt will occur for each character that should cause one. An alternative to .ITYIC'ing at interrupt level and IOT'ing at main program level, is IOT'ing at interrupt level. This works reasonably as long as it is convenient for the program (for example, PEEK does this). The program can even IOT the characters at interrupt level and keep its own buffers for its main program level if it wishes to. If the characters are IOT'ed when they interrupt, there is no need to .ITYIC them. However, all characters must be set to cause interrupts, or the interrupts might get one off from the IOT's.  File: ITSTTY, Node: D/5, Previous: D/4, Up: D, Next: D/6 5. THROWING AWAY TYPE-IN. If a .RESET UUO or a RESET symbolic system call is done on a tty input channel, any input in the input buffer will be thrown away. If any of the characters being discarded has not echoed, or has not interrupted, then it never will.  File: ITSTTY, Node: D/6, Previous: D/5, Up: D, Next: D/7 6. TESTING FOR THE AVAILABILITY OF INPUT. A program may find out how much input is available using the UUO .LISTEN or the symbolic system call LISTEN. Both wait for the output buffer to empty, and then return the number of characters in the input buffer (To check for input without waiting for output to finish, use .STATUS - see below). .LISTEN AC, applies only to the job's console, and returns its value in AC. If the job has no console, or doesn't have its console at the moment, 0 is returned. The symbolic LISTEN call takes a tty channel as an argument and returns a value in the usual way. The call will fail if the channel number is bad, if the channel does not have a tty open, or if the tty is the job's console but the job doesn't own it at the moment. It will skip iff it succeeds. .CALL [ SETZ 'LISTEN 1000,,CHANNEL 402000,,FOO] ;PUTS # CHARS. IN FOO. JRST NOTTY ;I WAS ^P'D BY DDT. ... ;FOO NOW SET UP.  File: ITSTTY, Node: D/7, Previous: D/6, Up: D, Next: D/8 7. .STATUS ON TTY INPUT CHANNELS. A .STATUS or symbolic system call STATUS executed on a tty channel returns either 1 or 2 as the device type code - 2 if the tty is a display with selective erase (%TOERS is set); 1, otherwise. Bit 2.1 will be 1 iff the tty's input buffer is full; bit 2.2 will be 1 iff the buffer is empty. Thus, .STATUS on an input channel is a way of testing for the availability of input without waiting for the output buffer to empty out. Bit 2.4 will be 1 if the job currently owns its console. Bit 2.5 will be 1 iff the number of characters available for IOT'ing is different from the number available for interrupt level processing (I am not sure why this bit exists). Bit 2.8 will be 1 iff the terminal is located next to the 340 display or one of its slaves (it will always be 0 except on the AI KA-10 machine). Bit 2.9 will be 1 iff the terminal is "local" - that is, near the machine itself (only local ttys are allowed to use the LPT directly, for example).  File: ITSTTY, Node: D/8, Previous: D/7, Up: D 8. THE CHARACTER SET This section describes the 12-bit input character set. Terminals with the %TOFCI TTYOPT bit set can generate all of these. Other terminals can only generate the ascii subset. An input character consists of 7 bit of ascii character and 4 modifier bits. Note that the ascii codes from 0-37, if generated by a non-%TOFCI terminal, are control characters, but if generated by a %TOFCI terminal are either special keys (like RETURN) or are "SAIL" printing characters in which case they appear in combination with %TXTOP. TECO ORDER has more information on this. The modifier bits are: %TXTOP Indicates that the TOP key was held down (usually). Can also indicate some special characters (see below). %TXCTL Indicates that the CTRL key was held down. %TXMTA Indicates that the META key was held down. %TXSUP Indicates that the SUPER key was held down. (This used to mean that the SHIFT key was held down.) Numerically, %TXTOP=4000, %TXCTL=200, %TXMTA=400, and %TXSUP=1000. %TXASC=177 is a mask for the 7-bit ascii basic character. Note that the TOP key also modifies the ascii character code, but CTRL and META are simply added in. Some special keys are indicated by %TXTOP plus the ascii code for a capital letter. These can also be combined with %TXCTL, %TXMTA and %TXSUP. %TXTOP+A ESCAPE. Note that the ESCAPE key is used to send commands to the terminal controller (see ITS TV), so it cannot be sent to the system except with CTRL or META. %TXTOP+B BREAK. Recommended as the character for "getting out of" programs where CALL is not what you want. %TXTOP+C CLEAR. %TXTOP+D circle-minus. An unassigned printing character key. %TXTOP+E circle-plus. An unassigned printing character key. %TXTOP+F delta. An unassigned printing character key. (shift circle-minus) %TXTOP+G del. An unassigned printing character key. (shift circle-plus) %TXTOP+H Help key (top H). Recommended for getting help. This code is unusual in that it is passed to the program as %TXTOP+H even when %TIFUL is not set. %TXTOP+Z Internal code for deferred call. Other special keys, which generate codes in the ascii controls region and without %TXTOP, are: 10 Backspace 11 Tab 12 Line 13 VT 14 Form (recommended for clear and redisplay the screen) 15 Return (recommended for end of line) 37 Back-next (used for input escape, *Note Escape: A.) 33 Altmode 177 Rubout (recommended for character deletion) Some of these have printed representations on output. Backspace, Tab, Line, and Return are format effectors. Altmode is a printing character.  File: ITSTTY, Node: E, Previous: D, Up: Top, Next: F E. OUTPUT TO TERMINALS. The most basic forms of I-O are oriented toward stream-like devices. In fact, the ideal terminal is no longer a stream-like device but a random-access device - a display. Ordinarily, access proceeds sequentially using a pointer called the cursor. For more interesting operations, a set of display commands are provided to move the cursor or erase sections of the screen in ways independent of the hardware characteristics of the particular display in use, as long as the display has the ability to perform the specified function at all. There are also bits in the TTYOPT variable, which may be read with the CNSGET symbolic system call, that give information on which functions the particular terminal can perform. * Menu: * Output: E/1 How to cause characters to be output. * Normal: E/2 Normal output (sequential access). * Display: E/3 Display-mode channels. ^P-codes. * Echo: E/4 The echo area. * Cursorpos: E/5 Reading the cursor position. * Super: E/6 Superimage output. * TTYOPT: E/7 Relevant TTYOPT bits. * Flush: E/8 Throwing away typeout. * Waiting: E/9 Waiting for output to be sent to the terminal. * .STATUS: E/10 .STATUS on tty output channels.  File: ITSTTY, Node: E/1, Previous: E, Up: E, Next: E/2 1. HOW TO CAUSE CHARACTERS TO BE OUTPUT User programs output characters by means of the .IOT UUO or the symbolic system calls IOT or SIOT. .IOT is pretty much equivalent to symbolic IOT, but has slightly less overhead and is less flexible. Display commands, which are several characters long, are output by outputting in order the characters that compose them. Unit mode channels may be used to output single characters with IOT, or to output packed strings of characters with SIOT. Since SIOT is much more efficient, commonly used programs or programs doing much tty output should use it when possible. Block mode is semi-obsolete. On a block mode channel, IOT outputs a block of words, containing 5 characters each. The character "^C" is totally ignored, making it possible to output other than a multiple of five characters. Block mode IOT's have no advantage over SIOT's on unit mode channels. The symbolic system calls IOT and SIOT allow the respecification of the values of several per-channel mode bits (all those given names starting with "%TJ" - *Note Bits: C/3/c.). Unit mode IOT is somewhat slower than the .IOT UUO, but the same is not true for SIOT and block mode IOT. From now on, all three ways of outputting a character will be referred as IOT'ing, since their differences have all been described above. If the terminal is in a com link, output IOT's will hang up, unless %TCOCO (see "^_O") or %TCLFT (see "^_E") is set. If the tty is the job's console, the IOT will not do its work unless the job has the tty; otherwise it may wait or it may interrupt (*Note NoTTY: B/3.).  File: ITSTTY, Node: E/2, Previous: E/1, Up: E, Next: E/3 2. NORMAL OUTPUT (SEQUENTIAL ACCESS). The way terminal output works when display commands are not in use is that each ordinary character is printed where the cursor points, and advances the cursor over the positions that it occupies. Formatting characters such as CR, LF, TAB and BS act by moving the cursor in the appropriate way (that is, they are really display commands). * Menu: * How: E/2/a How the System Goes about Outputting. * Contin: E/2/b Continuation - the Result of Line-overflow. * Wrap: E/2/c Wraparound and Scrolling - the Results of Page-overflow  File: ITSTTY, Node: E/2/a, Previous: E/2, Up: E/2, Next: E/2/b a. How the System Goes about Outputting. The way the system outputs any particular character to the tty depends in general on the following factors: whether the relevant %TGIMG bit in the TTYST1 or TTYST2 variable says that the character should be output in image mode (this is the only way those bits have an effect), whether the channel specifies output in echo mode, whether the terminal can print the SAIL character set, and sometimes on random TTYSTS bits. Note that we are thinking of flushing the %TGIMG bits in TTYST1 and TTYST2. If that is done, all output will be done "in ASCII mode". If you want the effects described below for image mode, you should probably open a channel in superimage mode and use it at such times. * Menu: * Ascii: E/2/a/1 ASCII Graphic Characters. * ^G: E/2/a/2 "^G". * CR: E/2/a/3 Carriage-return. * LF: E/2/a/4 Linefeed. * Tab: E/2/a/5 Tab. * ^L: E/2/a/6 Control-L (Formfeed). * Altmode: E/2/a/7 Altmode. * ^P: E/2/a/8 Control-P, the escape code. * BS: E/2/a/9 Backspace. * Random: E/2/a/10 Random Control Characters, and Rubout.  File: ITSTTY, Node: E/2/a/1, Previous: E/2/a, Up: E/2/a, Next: E/2/a/2 1: ASCII Graphic Characters. These characters are simply sent to the terminal. The system assumes that they will occupy one printing position, and move the terminal's hardware cursor one place to the right.  File: ITSTTY, Node: E/2/a/2, Previous: E/2/a/1, Up: E/2/a, Next: E/2/a/3 2: "^G". "^G" is assumed to make a noise or other temporary indication, occupy no space on the screen, and not move the cursor.  File: ITSTTY, Node: E/2/a/3, Previous: E/2/a/2, Up: E/2/a, Next: E/2/a/4 3: Carriage-return. If the channel specifies echo mode, a "CRLF" will be done. That is, the results will be the as if a CR and a LF had been output in image mode. Otherwise, if the TTYST2 variable specifies that CR is output in ascii mode, a "CRLF" will be done just the same, except that a bit will be set so that if the next character output to the tty is a LF, it will be ignored. Thus, in ascii mode, a CR without a LF is the same as a CR with one LF. If CR is output in image mode, it moves the cursor to the beginning of the line it was on. The line is not cleared. However, this feature will eventually be flushed, so you should not use it. Instead, simply output ^PH^H to do a "stray CR". In fact, you can output all your CR's this way. For CR's which are not stray, this will not cause any trouble, and for those which are stray, it will cause the desired overprinting.  File: ITSTTY, Node: E/2/a/4, Previous: E/2/a/3, Up: E/2/a, Next: E/2/a/5 4: Linefeed. If a LF follows a CR that was output in ascii mode and not in echo mode, the LF is ignored. Otherwise, the LF is output in one standard way regardless of the settings of the several variables (but it is best to have TTYST2 specify ascii mode just in case image mode for LF ever means something). The action of LF is normally to move the cursor down one line. The horizontal cursor position is not changed by a LF. On displays with selective erase (%TOERS is set) LF clears the line it moves down to. The entire line is cleared even if the horizontal position is not zero. The bottom of the screen poses special problems for LF. If the LF reaches the lowest line on the screen, it may trigger **MORE** processing. If it starts from the bottom line of the screen, it needs to wrap around or scroll (*Note Wrap: E/2/c.).  File: ITSTTY, Node: E/2/a/5, Previous: E/2/a/4, Up: E/2/a, Next: E/2/a/6 5: Tab. If the channel specifies echo mode or TTYST2 specifies ascii mode, the tab causes the cursor to be moved rightward up to the next multiple of eight spaces from the left margin, or to the right margin if that comes first. If continuation is not suppressed and the cursor starts out at the continuation column, continuation will be done and then the tab will be handled (note that when continuation is in effect, the right margin is the continuation column). If output is not in ascii mode or echo mode, a tab character is sent to the tty, and assumed not to move the cursor.  File: ITSTTY, Node: E/2/a/6, Previous: E/2/a/5, Up: E/2/a, Next: E/2/a/7 6: Control-L (Formfeed). In echo mode, "^L" will normally echo as a clear screen ("^PC"). However, on printing ttys (ttys whose %TOMVU is off) or if the program has set %TSCLE (Control-L Echo) "^L" will echo like other random control characters (*Note Ctl: E/2/a/10.). Not in echo mode, "^L" is treated like other random control characters.  File: ITSTTY, Node: E/2/a/7, Previous: E/2/a/6, Up: E/2/a, Next: E/2/a/8 7: Altmode. If the TTYST2 variable says that altmode should be output in ascii mode, or if the channel specifies echo mode, then normally a dollar-sign will be sent, but if the %TOSAI bit in the TTYOPT variable, which means "ASCII mode should use the SAIL character set" is on, an altmode will be sent (it comes out as a diamond on the screen). In either case the cursor moves one position. If output is in image mode and not in echo mode, an altmode will be sent to the terminal. It will be assumed not to move the cursor unless %TOSAI is set, meaning "the terminal understands the SAIL character set", in which case it will be assumed to move the cursor one space right.  File: ITSTTY, Node: E/2/a/8, Previous: E/2/a/7, Up: E/2/a, Next: E/2/a/9 8: Control-P. "^P" is output like most other control characters (*Note Ctl: E/2/a/10.). However, on a channel open in display mode, "^P" serves as an escape prefix for display commands. In order to output a "^P" using such a channel, the display command "^PP" must be used.  File: ITSTTY, Node: E/2/a/9, Previous: E/2/a/8, Up: E/2/a, Next: E/2/a/10 9: Backspace. In echo mode on a terminal which can't backspace, "^H" echoes as uparrow-H. Otherwise, if in column 0, backspace does nothing. Otherwise, on an IMLAC, backspace sends a backspace, and assumes the cursor moves back one position. On other types of terminals, backspace simply moves the cursor back one position.  File: ITSTTY, Node: E/2/a/10, Previous: E/2/a/9, Up: E/2/a 10: Random Control Characters, and Rubout. If TTYST1 specifies ascii mode for these characters, or the channel specifies echo mode, then a control character will be sent as an uparrow followed by the appropriate graphic character (thus, "^A" as "^" followed by "A"), unless %TSSAI is set, in which case the control character itself will be sent, and the system will expect it to be a graphic that moves the cursor one position. If %TSSAI is 0 but %TOSAI is set, then a SAIL uparrow will be used instead of a "^" when typing the "^A". If not in ascii mode or echo mode, the control character itself will be sent, and the system will expect it not to move the cursor, unless %TOSAI is set, in which case it will be expected to move the cursor one space right. Note that this is just like the treatment of altmode except for the details of the conversion in the case of ascii or echo mode with %TSSAI not set.  File: ITSTTY, Node: E/2/b, Previous: E/2/a, Up: E/2, Next: E/2/c b. Continuation - the Result of Line-overflow. When typeout attempts to go past the right margin, the system inserts a "!" and a CRLF to make sure that output is not lost. The last printing position on each line is normally reserved for the "!" printed when continuation is done, and the line size of the terminal as specified in or returned by system calls does not count that column. The act of continuation takes place when an attempt is made to output a character and the cursor is pointing at the reserved continuation column; the "!" and CRLF are output, followed by the character that provoked the continuation (which will be in the next line). Continuation may be suppressed by opening a channel with the %TICTN bit set; then characters output on that channel will never provoke continuation no matter where the cursor points. The continuation column is available for use by the program. The display codes ^PX and ^PB "understand" continuation to some extent. See their descriptions.  File: ITSTTY, Node: E/2/c, Previous: E/2/b, Up: E/2 c. Wraparound and Scrolling - the Results of Page-overflow. When an attempt is made to linefeed past the bottom line of the screen, either the cursor wraps around or the screen scrolls up. Which one happens depends on whether the terminal is in scroll mode, as determined by the setting of %TSROL. That bit is stored per-tty/per-job, and may be set by the program with TTYSET, and complemented by the user with "^_^". Its value is initialized from %TOROL in each job separately. %TOROL is initialized whenever a tty begins to be used. The initial value is 0 except on the dynamod machine. %TOROL may be set with a CNSSET, or by the TCTYP program. The echo area cursor never causes scrolling. Whenever it reaches the bottom of the screen it wraps around to the top of the echo area, regardless of the setting of %TSROL. * Menu: * Scrolling: E/2/c/1 * Wraparound: E/2/c/2  File: ITSTTY, Node: E/2/c/1, Previous: E/2/c, Up: E/2/c, Next: E/2/c/2 1: Scrolling. Scrolling moves the contents of the screen up several lines (the number depends on the type of terminal) and then linefeeds normally. Only some types of terminals can scroll; others will always wrap around even if scroll mode is on.  File: ITSTTY, Node: E/2/c/2, Previous: E/2/c/1, Up: E/2/c 2: Wraparound. On displays that can erase selectively, wraparound simply puts the cursor on the top line, clearing it. On Tektronix-like displays (those which can't erase selectively), wrapaound clears the screen, since it can't clear only the top line. Because this is necessary, **MORE** processing is less likely to be suppressed on such terminals. Wraparound does take place on printing ttys, but it is indistinguishable from ordinary linefeed.  File: ITSTTY, Node: E/3, Previous: E/2, Up: E, Next: E/4 3. DISPLAY-MODE CHANNELS. ^P-CODES. It would be impossible to output a display command using a channel which simply printed any character sent out on it. If it is desired to make use of display commands, a channel may be opened in display mode. That causes the character "^P" to be an escape character when output on that channel. When a "^P" is output on a display-mode channel, it has no effect except for setting bits causing the next character output on that channel to be interpreted as a display code. The display codes are: A Advance to a fresh line. If at beginning of line do nothing, else act like a CRLF. B move Backward. Decrements the horizontal position. If the horizontal position is 0, it is set to the horizontal screen size minus two, and the vertical position is decreased by one. Thus, it moves back over one character position even if there was a line continuation in the way. C Clear screen. The cursor goes to the upper left corner and the whole screen is cleared. On a printing tty (%TOMVU is 0) a CRLF is output, since "clearing the screen" is undefined. If "^PC" is output to the echo area, only the echo area is cleared, and only the echo area cursor is moved. D move Down. The vertical position is incremented. If it becomes equal to the vertical screen size, it is set to 0. E clear to Eof. The remainder of the current line, and all lower lines, are erased. The cursor doesn't move. F move Forward. The horizontal position is incremented. At the end of the line it wraps around to the beginning of the next line. H set Horizontal position. Takes one argument: the following character should be the desired horizontal position setting plus 8. The vertical position is not changed. An attempt to set the position beyond a margin will position it at the margin. I Outputs a one-position printing character in image mode. Takes one argument: the numeric ASCII code of the desired character. K Kill (erase) the character the cursor points at. The cursor does not move. The position erased is the one that would be written in next by ordinary output. L clear Line. The current line, starting with the position that the cursor points at, is erased. The cursor does not move. M (More) hang up until a character is read in. *Note More: F/3. N (No home-up) similar, but don't home up after the character is read. P output "^P". Useful if it is desired to output "^P" in image mode with a display-mode channel, or if the terminal handles the SAIL character set. Q output "^C". Similar to "^PP". This is needed only for block mode IOT's. With SIOT, it is not needed since "^C" isn't special. R Restore cursor position. The cursor is set to the most recently saved value. S Save cursor position. Remembers the current cursor position for use with "^PR". There is no stack for saved cursor positions; only the most recent saved position is remembered. T go to Top of screen (home up). The cursor is positioned at the upper left corner of the screen. U move Up. The vertical position is decremented. If it was 0, it becomes equal to the vertical size minus one. V set Vertical position. Takes the following character as an argument - it should be 8 plus the desired vertical position. An attempt to set the cursor beyond the top or bottom margin will position it as far as allowed in the desired direction. Similarly, "^PV" will not move the echo area cursor outside the echo area. Note that vertical positions in the echo area are to be specified relative to the top of the echo area. X backspace and erase one character ("^PB" followed by "^PK"). If done at column zero, it clears the last TWO characters on the previous line (assuming that one of them was the character you intended to erase, and the other was an "!" indicating a continuation). Z home down. The cursor is positioned at the lower left corner. [ insert line. The current line and all lines below it are pushed down one slot. A blank line appears at the current position. The cursor does not move. Works only on terminals which have %TOLID set (^P\ also). \ delete line. The current line disappears, and all teh lines below it move up by one position. The bottom line becomes blank. The cursor does not move. ] obsolete - same as "^PL". ^ insert character. All the characters after the cursor move right one position. The last one moves off the right margin and disappears. A space appears at the cursor, which does not move. Works only on terminals which have %TOCID set. _ delete character. The character at the cursor disappears, and all the rest of the characters on the line move left one position. A space appears at the end of the line. The cursor does not move.  File: ITSTTY, Node: E/4, Previous: E/3, Up: E, Next: E/5 4. THE ECHO AREA. Normally there is only one cursor, used by all output, including echoing, and visible always on the screen. However, the program may create an "echo area", which means that there will be two cursors: one acting just like the normal one, and used for most program output; the other, restricted to a few lines at the bottom of the screen, and used for all echoing (and by program output that specifically requests it). The terminal will show whichever cursor was used most recently. The normal cursor is known as the "main-program cursor"; the other, as the "echo area cursor". * Menu: * How: E/4/a How the Echo Area Works. * Creating: E/4/b Creating an Echo Area.  File: ITSTTY, Node: E/4/a, Previous: E/4, Up: E/4, Next: E/4/b a. How the Echo Area Works. One of the per-tty/per-job variables in the system is the size of the echo area. This variable is 0 iff there is no echo area; this is the usual case, and all output (including echo) uses the main program cursor. If the variable isn't 0, it must be positive and less than the screen height; that many lines at the bottom of the screen become the echo area. Ordinary output using the main program cursor is not affected by the existence of the echo area, but output done with the %TIPP2 bit set (and this includes all system echoing), will use the echo area cursor. This cursor is restricted to the echo area; ^P-codes and wraparound for this cursor act as if the top of the screen were really located at the top of the echo area (the ^P-codes mention how they treat the echoing cursor if that is special). Scrolling never happens to the echo area cursor. **MORE** processing can happen, just as with the main program cursor, and completely independently, but all system echoing is done with %TIMOR set to prevent that.  File: ITSTTY, Node: E/4/b, Previous: E/4/a, Up: E/4 b. Creating an Echo Area. When a job is created it has no echo area on its console. When a tty in use as a device is first opened, it has no echo area. The size of the echo area may be changed (and, in particular, an echo area may be created or destroyed) with the SCML symbolic system call, described in section G.3.c. Also, one of the first-time-only bits in the mode of the tty input OPEN allows creation of a 3-line echo area.  File: ITSTTY, Node: E/5, Previous: E/4, Up: E, Next: E/6 5. READING THE CURSOR POSITION. The symbolic system call RCPOS returns to the program the values of the cursor positions of both the main-program area and the echo area. Each cursor position is returned as a single word consisting of the vertical position in the left half and the horizontal position in the right half. The first value is the main program area cursor; the second, the echo area cursor. The echo area cursor position is returned relative to the top of the echo area. *Note TTY Spec: G/2. for a description of the options for the first argument and the reasons why the call can fail. RCPOS does not require ownership of the terminal, just output permission (*Note Permit: B/3.). For example: .CALL [ SETZ SIXBIT/RCPOS/ 1000,,CHANNEL 2000,,MPPOS ;MP ARE POSITION GOES IN MPPOS. 402000,,ECHPOS] ;ECHO AREA POSITION GOES IN ;ECHPOS. .VALUE ;CALL FAILED. ... ;CALL SUCCEEDED.  File: ITSTTY, Node: E/6, Previous: E/5, Up: E, Next: E/7 6. SUPERIMAGE OUTPUT. When %TISIO is 1, output is done in superimage mode. That means that no padding will be done, and the system will not do cursor positioning or attempt to keep track of where the cursor is; every character IOT'ed will be sent without change. In addition, ITS output buffer display commands may be sent directly, rather than via ^P-codes (*Note SUPDUP: K/1). This mode is useful when output is being done to a strange device that is connected to the system via a tty line (for example, a logo music box or a PDP11 running the absolute loader), and when the output has already been put into the correct form for the particular type of tty (for example, the TELNET program has a mode that assumes that the foreign host has handled such things). It is also useful for programs which do cursor-position updating, line continuation, etc., themselves, and want to save time by stopping ITS from doing them. To be efficient, use SIOT. Block mode IOT will ignore "^C", which may be embarrassing. If the characters output in superimage mode will move the cursor, the SCPOS system call must be used to tell ITS about it. *Note SCPOS: K/3.  File: ITSTTY, Node: E/7, Previous: E/6, Up: E, Next: E/8 7. RELEVANT TTYOPT BITS. %TOERS says that the tty can erase selectively. If this bit is not set, "^PL", and "^PE" cannot be used. "^PX" and "^PK" will work anyway, if %TOOVR is off, since then ITS knows it can use a space to erase a single character. %TOMVU says that the tty can move its cursor up. If this bit is not set, the tty is a printing terminal. Any attempt to erase will have no effect. Horizontal and downward cursor motion will work but not upward motion. For the sake of those programs that wish to know about displays only to the extent of clearing the screen on them every so often, "^PC" on a printing terminal comes out as a CRLF. %TOOVR says that the tty can overstrike characters successfully. The effect of attempted overstriking on a terminal that can't handle it is undefined, but on a datapoints what will happen is that only the last character printed in a given position will be visible. Note that outputting a space character will erase iff the terminal cannot overstrike. Space should be output only when attempted overstriking is generally desired - for example, when copying out of a file. If erasing is specifically desired, "^PK" should be used (or "^PK^PF" = move forward, erasing). If it is specifically desired not to erase, "^PF" should be used. For "printing terminals" (or rather, terminals on which no cursor motion characters except ASCII format effectors are known) which lack %TOOVR, some cursor motion optimizations are not done (for example, moving backward can be done only by backspacing, since CR'ing and spacing forward might erase something useful). %TOMVB, if 0, means that the terminal can't backspace. This is true only of teletypes. The system will simulate a backspace with a CR and spaces, but, since that is so slow, backspace should be avoided on such terminals. For that reason, it echoes as uparrow-H rather than as a backspace. %TOSAI, if 1, says that control characters sent to the terminal will be one-position graphic characters. The system will assume that control characters output in image mode move the cursor one space right. Also, altmode will be output as itself, rather than as a dollarsign, even in ascii or echo mode (but the same is not true of random control characters, which check %TSSAI). %TORAW, if 1, says that the various cursor motion characters (space, tab, CR, LF, and BS) should be output to the terminal in the same order the program gave them to the system, and in the same way, if possible. This bit does not effect the padding done to CR, LF and TAB, and will not prevent the system from simulating BS and TAB on tty's that require such simulation. It will prevent the system from combining several cursor motion characters to produce their effect more efficiently; for example, CR's at the beginning of the line will be ignored when %TORAW is 0, but when it is 1, they will cause CR to be sent. Also, CR followed by spaces will always be output in that manner even if backspacing would be faster. This bit is normally set by the TELNET server except when the foreign host is a tip, for the sake of terminals that don't even always handle CR and LF correctly, but do manage to handle the sequence CR-LF correctly, etc.  File: ITSTTY, Node: E/8, Previous: E/7, Up: E, Next: E/9 8. THROWING AWAY TYPEOUT. Many programs have interrupt characters for requesting that some output be discarded. Normally they set flags telling the program not to output anything. But on slow terminals the text already in the output buffer will take an annoyingly long time to come out. For that reason, the .RESET UUO and the RESET symbolic system call when used on slow terminals (those for which %TPORS is 1) throw away the text in the output buffer. On fast terminals that is not done. On all terminals, an output RESET restores the state of several bits associated with the channel it is given on to normal. For example, if the RESET took place after an interrupt out from the middle of typing out a ^P-code, the RESET will cause the next output character to be treated normally rather than as a display code. If the channel had been hung in a **MORE** (*Note More: F/2/a.) it will be unhung.  File: ITSTTY, Node: E/9, Previous: E/8, Up: E, Next: E/10 9. WAITING FOR OUTPUT TO BE SENT TO THE TERMINAL. The symbolic system call FINISH may be used to wait until the output buffer is empty, meaning that all characters output by the program have actually been sent to the terminal. The call's only argument is a tty output channel number: .CALL [ SETZ SIXBIT/FINISH/ 401000,,CHTTYO] .LOSE %LSFIL ;CALL FAILS?? FINISH does not require ownership of the terminal; just output permission (*Note Permit: B/3.).  File: ITSTTY, Node: E/10, Previous: E/9, Up: E 10. .STATUS ON TTY OUTPUT CHANNELS. The information returned as the STATUS of an output channel resembles that returned for an input channel except that bits 2.1 and 2.2 refer to the output buffer rather than the input buffer, and bits 2.5, 2.8 and 2.9 are not returned with any information. *Note In-status: D/7.  File: ITSTTY, Node: F, Previous: E, Up: Top, Next: G F. **MORE** PROCESSING. This feature, when enabled, causes typeout to pause at certain times (for example, at the bottom of the screen). Certain events (such as reaching the last line on the screen) trigger a **MORE** by setting the %TFEOP bit. Once that has happened, the next attempt to output a character will cause the program to be interrupted if it is clever, or cause the system to wait for the user to order typeout to proceed if the program is not clever. * Menu: * When: F/1 When **MORE** processing is triggered. * How: F/2 How **MORE** processing operates. * Programmed: F/3 Programmed invocation of **MORE** processing. * Inhibition: F/4 Inhibition of **MORE** processing by input.  File: ITSTTY, Node: F/1, Previous: F, Up: F, Next: F/2 1. WHEN **MORE** PROCESSING IS TRIGGERED. The main occasion for triggering is .IOT'ing a LF that reaches the last line of the screen. However, triggering has complicated conditions: it will not happen if %TSMOR is set (%TSMOR's meaning is "disable **MORE** processing, and this is how it functions); in scroll mode triggering may not occur until the results of the previous triggering have scrolled to the top of the screen, or a home-up ("^PT" or "^PC") has happened. Note that printing terminals usually have the screen height set to 200000,, , but wrap around at line 118., so linefeed will never trigger. However, if the screen height of a printing terminal is set to a small value, **MORE** processing will take place. The user may trigger a **MORE** whenever he wishes to stop output temporarily, by typing "^_B". %TSMOR does not inhibit this, and scroll mode does not affect it.  File: ITSTTY, Node: F/2, Previous: F/1, Up: F, Next: F/3 2. HOW **MORE** PROCESSING OPERATES. Once one of the events described above has triggered it, **MORE** processing will happen at the next attempt to .IOT a character out to the terminal, except for output done with %TIMOR set to 1. The details differ depending on how clever the program wishes to be. * Menu: * Stupid: F/2/a Stupid Programs. * Smart: F/2/b Smart Programs.  File: ITSTTY, Node: F/2/a, Previous: F/2, Up: F/2, Next: F/2/b a. Stupid Programs. If the tty channel being used for the output IOT that caused **MORE** processing to occur, is not enabled to interrupt, ("**MORE**-interrupts are not enabled"), the system assumes that the program is not clever, and tries to handle the condition itself, telling the user that there is more output, and waiting for his command to go ahead and print it. Before handling the .IOT'ed character, "**MORE**" is typed out, and the system reads a character from the ordinary input stream. Output will resume, starting with the character whose .IOT'ing was put off to do the **MORE**, as soon as a character is available to be read. The input character will not be thrown away, however, unless it is a space (that is, if it is not a space, it will remain for the program to read eventually). The system will supply a home-up so that output will resume on the top line of the screen (which, on an Tektronix or other display without selective erase, requires clearing the screen). While the system is waiting for an input character, it is actually hung in the .IOT on the output channel. The terminal's variables are not in abnormal state, except for that channel, and .RESET will return the channel to normal. Thus, if the character typed in response to the "**MORE**" is an interrupt character, the interrupt will happen normally, and if it is dismissed without side-effect, the system will continue waiting for a character to tell it to proceed. But if the interrupt character tells the program to .RESET its output and await a new command, that will do the right thing. Also, when a program is "hung in a **MORE**", if the TTY is taken away by its superior and then given back, its state will be unchanged, although the superior will have had no trouble outputting to it (and might even have done **MORE** processing).  File: ITSTTY, Node: F/2/b, Previous: F/2/a, Up: F/2 b. Smart Programs. If the TTY output channel being used for output when **MORE** processing becomes necessary is enabled for interrupts, the system will signal an interrupt on it, and wipe its hands of the matter. It is up to the program to pause, or whatever is desired. It is a convention that smart programs that provide the user with the ability to "flush" the rest of the typeout should type "--MORE--" instead of "**MORE**". One algorithm for handling **MORE** interrupts might be: optionally set %TSNOE, type out "--MORE--", do a FLUSH to wait for the "--MORE--" to come out, then read a character with %TIPEK and %TIACT set. At this point, depending on the character, the routine may gobble it by IOT'ing it again without %TIPEK. Then, the routine may either flush by typing out a message such as "flushed", clearing %TSNOE if it was set, re-enabling interrupts and returning to a restart point, or it may proceed by clearing %TSNOE and dismissing the interrupt. The purpose of using %TSNOE here is to prevent the character typed at the "--MORE--" from echoing in case it is to cause flushing but not be gobbled - the idea is that it will echo LATER, when it is re-used as normal input. Programs which handle **MORE**-interrupts should not .IOT a control character expecting it to be printed as an uparrow and a printing character, because that will lose if a **MORE**-interrupt comes between the two.  File: ITSTTY, Node: F/3, Previous: F/2, Up: F, Next: F/4 3. PROGRAMMED INVOCATION OF **MORE** PROCESSING. The two display commands "^PM" and "^PN" cause the channel they are output on to enter the same state that a channel is in after the system has typed "**MORE**" through it - namely, waiting for a character to be read in before outputting any more. Those commands are not affected by enabling of **MORE**-interrupts - that is, these commands issued by even a clever program will enter the state the is normally entered only for stupid programs. "^PN" is unusual in that after the character has been read in, only a linefeed will be done, instead of a home-up.  File: ITSTTY, Node: F/4, Previous: F/3, Up: F 4. INHIBITION OF **MORE** PROCESSING BY INPUT. When the program waits for input, triggering of **MORE** processing is inhibited for a while. This is so that a program which is giving short replies to commands typed in will not do **MORE**'ing, which in those circumstances would probably be a nuisance. The details of the inhibition vary; in scroll mode triggering is inhibited until the place the cursor was when the program waited for input scrolls to the top of the screen; otherwise, inhibition takes place the very next time the bottom is reached, but only if the waiting occurred in the bottom 5 lines of the screen. In any case, if a home-up (or clear-screen) intervenes, there is no inhibition. It is not the typing of input or the reading of input that inhibits, but the waiting for input, for the following reasons: if typing ahead inhibited triggering, it would be impossible to type ahead to a **MORE**; if reading typed-ahead input inhibited triggering, it would be possible to lose by typing ahead commands that produced a surprisingly large amount of input.  File: ITSTTY, Node: G, Previous: F, Up: Top, Next: H G. PER-TTY/PER-JOB VARIABLES. Some of the variables which exist for a tty are intended to describe the tty to the system or user; others are intended as program-settable options. Of those, there are some that are per-channel, and others that are not, either for historical reasons, because they are too large to fit in the space that each channel has for variables, or because they are used by the input interrupt routine (at input interrupt time it is not known which channel will be used to read the character). These variables are maintained per-tty/per-job, which means that for a tty in use as a device, there is one setting of the variables, under the control of the job that has the tty open, but for a tty that is a console, each job in the tree controlled by the tty may set the variables independently. The values actually in effect at any time are those set by the program which has the tty at that time. The .ATTY and .DTTY UUO's that transfer the tty from one job to another in the tree automatically save the values set by the job that is losing control of the tty, and restore the per-tty/per-job variables from the last settings made by the job that is gaining control of the tty. When a job does not have the tty, its settings may be examined with the .TTY, .TTST, .TTS1 and .TTS2 .USET variables. The variables for a tty which is in use as a device are initialized when the tty is opened. Each job's copies of the variables for its console tty are initialized when the job is created. That latter initialization simply copies the job's superior's settings of the variables, except for the %TSMOR, %TSROL and %TSSAI bits, which are copied from the appropriate TTYOPT bits. The size of the echo area is always initialized to 0 for each new job or tty. Note that the first input tty open and the first output tty open will, between them, re-initialize all of TTYST1 and TTYST2. There exist symbolic system calls for reading and setting these variables. As usual, the calls to read them may be done to any tty, specified by number, while the calls to set them require a channel, and thus may be done only to a tty under the control of the job. Some of these variables are set by the first-time bits in the open-mode for tty opens. * Menu: * Variables: G/1 The variables. * Calls: G/2 Symbolic system calls.  File: ITSTTY, Node: G/1, Previous: G, Up: G, Next: G/2 1. THE VARIABLES. * Menu: * ST1&2: G/1/a The TTYST1 and TTYST2 variables. * STS: G/1/b The TTYSTS variable. * Size: G/1/c The Size of the Echo Area.  File: ITSTTY, Node: G/1/a, Previous: G/1, Up: G/1, Next: G/1/b a. the TTYST1 and TTYST2 variables. These variables contain the information on which characters should be echoed, and how; on which characters should activate (cause an .IOT to unhang), and which should interrupt (all this is used at input interrupt time). Also, they contain the information on which characters are to be output in image mode. A job that does not possess its console has its TTYST1 and TTYST2 settings for the console kept in the .USET variables .TTS1 and .TTS2. These words are divided into 6-bit bytes, one for each character group. All of the options for the characters in any group are located in the byte for that group, as follows: %TGINT==1 ;1 => characters in this group should interrupt. ;*Note Int: D/4. %TGACT==2 ;1 => characters in this group should activate. ;*Note Act: D/3. %TGSPC==4 ;1 => perform special hack. The meaning of this bit ;depends on which character-group is in question. ;Right now it is defined only for group 1 (letters) ;and means "convert lower case to upper case). %TGIMG==10 ;1 => output the characters of this group in image mode. ;*Note Image: E/2. for the consequences of setting this bit. ;It is likely that this feature will be flushed soon, ;since it cannot be made to work right with the $$^P ;feature that allows several jobs to type out at once %TGPIE==20 ;1 => echo these characters at interrupt level. ;*Note Echo: D/1. %TGMPE==40 ;1 => echo them at main program level ;(that is, when they are .IOT'ed in). *Note Echo: D/1. The characters are divided into groups based on the ascii code. TV characters are assigned to groups by converting them to ascii (thus, the meta bit is ignored, and the control bit is ignored except with letters, which are converted into ascii control characters). The groups of characters are: Group 0: "^@" - "^F", "^K", "^L", "^N" - "^R", "^T" - "^Z", "^\" - "^^". (in otherwords, random control characters). Group 1: Letters (both upper and lower case). Group 2: Digits. Group 3: !"#$%&',.:;?@\`|~ (random graphics). Group 4: *+-/=^_ (operators) Group 5: <>[](){} (brackets). Group 6: "^G" "^S" (most commonly used interrupt chars). Group 7: LF, TAB. Group 10: Altmode. Group 11: CR. Group 12: Rubout. Group 13: Space and BS.  File: ITSTTY, Node: G/1/b, Previous: G/1/a, Up: G/1, Next: G/1/c b. The TTYSTS variable. This variable contains many historical relics, as well as information used to control interrupt level actions, and to signal the user program. The prefix "%TS" is used for bits in the TTYSTS variable. When a job does not possess its console, its TTYSTS setting for the console may be found in its .TTST variable. %TSFRE==400000 ;4.9 1 => tty is free (not in use as device or console) %TSCLE==200000 ;4.8 1 => "^L" output in echo mode should always come ;out as uparrow-L. (Normally, "^L" echoes as a clear ;screen on displays). %TSHDX==100000 ;4.7 same as %TOHDX. This is vestigial. %TSFCO==040000 ;4.6 1 => use the full 12-bit TV character set for ;output and echoing. The control bit outputs as "^A" ;or "alpha", the meta bit outputs as "^B" or "beta", and ;the super bit outputs as "^F" or "epsilon". ;Also, the top bit is used to distinguish ASCII control ;characters from Sail graphic characters. The main value ;of this feature is for its effect on echoing. %TSALT==020000 ;4.5 1 => don't standardize altmodes. %TSROL==010000 ;4.4 1 => scroll mode is in effect. ;Complemented by "^_"""". %TSSAI==004000 ;4.3 1 => echo and ascii output should use SAIL chars. ;Complemented by "^_^". %TSACT==002000 ;4.2 1 => next input IOT shouldn't wait for an ;activation character to have been typed in. %TSNEA==001000 ;4.1 => Don't echo in echo area; echo in M.P. area. %TSINT==000400 ;3.9 1 => next input character should interrupt even ;if its %TGINT bit doesn't say it should. %TSMOR==000200 ;3.8 1 => inhibit **MORE** processing. ;Complemented by "^_M". %TSATY==000100 ;3.7 this bit is set whenever an .ATTY executed by a ;superior gives the tty to the job. It is what TECO ;uses to know that it should clear the screen before ;the next display. ;3.6-3.5 unused. %TSNOE==000010 ;3.4 1 => defer echoing (*Note Echo: D/1.). %TSLCZ==000004 ;3.3 1 => the last character typed in was "^Z". ;If this bit is 1, .ATTY fails (*Note ATTY: B/2.). %TSSII==000002 ;3.2 1 => superimage input. The special treatment of ;"^Z" and "^_" is suppressed. %TSCNS==000001 ;3.1 1 => the tty is a console (not a device). RH: ;the user-index of the job that owns the tty, or -1 ;if the tty is free. The actual system variable has ;the user-index in its internal form but TTYGET ;returns it in external form (=internal form ;divided by LUBLK).  File: ITSTTY, Node: G/1/c, Previous: G/1/b, Up: G/1 c. The Size of the Echo Area. The vertical size of the echo area is a per-tty/per-job variable. *Note Echo area: E/4.  File: ITSTTY, Node: G/2, Previous: G/1, Up: G 2. SYMBOLIC SYSTEM CALLS. These system calls all take, as the first argument, a tty-specifier which tells the system which tty's variables are to be read or written. The tty specifier should either be a channel number, on which a tty or pseudoteletype should be open (in the latter case, the variables of the tty which is the alter ego of the sty will be accessed), or be 400000 plus the number of the desired tty (this option is allowed only for calls that do not alter the variables. It enables a program to read the variables of a tty which is in use by a different job). An invalid tty specifier will cause the call to fail with an open-failure code such as "NO SUCH DEVICE" or "BAD CHANNEL NUMBER". If the job specifies its console, but it doesn't possess the console at the time, the call will wait until the tty is given back by the superiors. * Menu: * Get: G/2/a TTYGET - read TTYST1, TTYST2, TTYSTS. * Set: G/2/b TTYSET - set TTYST1, TTYST2, TTYSTS. * SCML: G/2/c SCML - Set Number of Command Lines.  File: ITSTTY, Node: G/2/a, Previous: G/2, Up: G/2, Next: G/2/b a. TTYGET - read TTYST1, TTYST2, TTYSTS. The TTYGET symbolic system call takes one argument, which specifies the tty whose variables are to be read, and returns up to five values, which are the TTYST1, TTYST2, TTYSTS, TTYTYP and TCTYP variables of that tty, as set by the job which has control of that tty at the time the system call is executed. The argument should be as described above. Actually, the right half of the third value returned is the user index in its external form, rather than its system-internal form, which is what the right half of the TTYSTS variable in the system really holds (The internal form is the external form times LUBLK, a symbol defined in the timesharing system. The external form is more useful to user programs - all interfaces with the system expect the external form, .USET of .UIND returns it, etc.). As an example, suppose TTYNUM contains the number of a tty whose variables are to be read. The following code will read the TTYST1, TTYST2 and TTYSTS respectively into ST1, ST2, and STS: MOVE A,TTYNUM .CALL [ SETZ 'TTYGET 1000,,400000(A) ;Immediate arg = 400000+ 2000,,ST1 ;1st value returned in ST1. 2000,,ST2 402000,,STS] ;Sign bit marks end of call. JRST TRANSL ;User must have translated TTY to a file. ... ;ST1, ST2, STS now set up. Note that the TTYGET call can fail quite legitimately, if the user translates device TTY: to a file of commands for the program. Therefore, you should not naively put a .VALUE or a .LOSE after a TTYGET, but instead write code to assume that a command file is being used and do the "appropriate" thing.  File: ITSTTY, Node: G/2/b, Previous: G/2/a, Up: G/2, Next: G/2/c b. TTYSET - set TTYST1, TTYST2, TTYSTS. The TTYSET symbolic system call takes either three or four arguments. The first specifies the tty (TTYSET, like the other calls that alter tty variables, do not allow a tty to be specified by number). The second and third arguments are used to set the TTYST1 and TTYST2 variables. The fourth, if present, sets the TTYSTS variable (if there are only three arguments, the TTYSTS variables is not changed). The bits %TSFRE, %TSHDX, %TSLCZ and %TSCNS, as well as the right half of TTYSTS, cannot be changed. If the %TSINT (the next character should interrupt whatever it is) bit is turned on, and there is a character in the input buffer already following the last one that has been .ITYIC'ed, that character will be made into an interrupt character if it wasn't already one. For example, if the desired values of the variables are contained in ST1, ST1+1, and STS, the variables may be set as follows (This isn't the simplest way; it is meant to illustrate the flexibility of the symbolic system call): MOVEI A,ST1 .CALL [ SETZ 'TTYSET 1000,,TYIC ;Immediate arg = tty channel. (A) ;Set TTYST1 from ST1 1(A) ;Set TTYST2 from ST1+1 400000,,STS] ;Set TTYSTS from STS JRST TRANSL ;User must have translated TTY to a file. ... ;Variables now set. Most of the time, when TTYSET is used, only a few of the bits are intended to be changed. Rather than giving the TTYSET constant arguments, which is tantamount to making baseless assumptions about the meanings of the other bits, you should read in the current values with a TTYGET, change only the bits you want to change, and then write out the result.  File: ITSTTY, Node: G/2/c, Previous: G/2/b, Up: G/2 c. SCML - Set Number of Command Lines. SCML takes two arguments: a tty channel number, and the desired size of the echo area. For example, to have 4 echo lines: .CALL [ SETZ SIXBIT/SCML/ ;Note 'SCML is right-justified, and won't do. 1000,,TYIC ;Immediate arg = tty channel 401000,,4] ;Immediate arg = <# command lines>. JRST TRANSL ;User must have translated TTY to a file. ... ;Echo area now set up. Before attempting to do a SCML, you should verify that the terminal being used is a display and not a printing terminal. You should also check for the possibility that TTY was translated to a file.  File: ITSTTY, Node: H, Previous: G, Up: Top, Next: I H. PERMANENT AND SEMIPERMANENT TTY INFORMATION. The permanent information on a tty describes the characteristics of the particular type of terminal in use and the line it is connected to. The semipermanent information consists of several user-settable bits controlling system options; they are all reinitialized whenever a free tty begins to be used. Also, when a TV or a tty on a dialup line is freed, the permanent information is reinitialized. When an STY is opened after being free its alter ego is similarly reinitialized. * Menu: * Variables: H/1 The variables. * Calls: H/2 System calls.  File: ITSTTY, Node: H/1, Previous: H, Up: H, Next: H/2 1. THE VARIABLES. * Menu: * Size: H/1/a The Screen Size. * TTYOPT: H/1/b The TTYOPT variable. * TCTYP: H/1/c The TCTYP variable. * TTYTYP: H/1/d The TTYTYP variable. * TTYCOM: H/1/e The TTYCOM Variable. * TTYROL: H/1/f The TTYROL variable or "Scroll Count". * TTYSMT: H/1/g The TTYSMT variable. Says what sort of CPU the terminal is, and to what extent it supports graphics.  File: ITSTTY, Node: H/1/a, Previous: H/1, Up: H/1, Next: H/1/b a. The Screen Size. The horizontal screen size is the number of character positions on a line, not including the column normally used for "!"'s produced by line continuation. The vertical screen size is the number of lines on the screen. For printing ttys on which **MORE** processing should never be done, it is 200000,, . If the screen height on a printing tty is set to a small value (less than 118.), **MORE** processing will be done if enabled (this is for the sake of terminals which are physically displays, but which are being operated as printing terminals because ITS does not know how to send display operations to them). Programs which make their output depend on the screen size will be totally screwed when the user detaches and reattaches on a different terminal, unless they are specially hacked to recover. Such programs should either enable the %PIATY interrupt, or test %TSATY in the TTYSTS variable regularly, since if the user switches terminal type for any reason those conditions will certainly be signaled. When the interrupt happens or %TSATY is seen, the program should read the screen size and TTYOPT once again from the system and take appropriate actions if they have changed. In the system, the horizontal size plus 1 is stored in the TCMXH variable, and the vertical size is stored in the TCMXV variable.  File: ITSTTY, Node: H/1/b, Previous: H/1/a, Up: H/1, Next: H/1/c b. The TTYOPT variable. This variable holds the rest of the information on the particular tty in use: what capabilities it has, and what special treatment it needs. Also it holds several user options: %TOMOR, %TOROL, %TOSA1 and %TOCLC. Programs that base their actions on the value of the value of the TTYOPT variable should provide for the possibility that the user changes his terminal type. They should either test %TSATY in the TTYSTS variable frequently, or enable %PIATY interrupts. When the chosen condition is detected, the program should the re-examine the value of TTYOPT. "%TO" signifies a bit in the left half of TTYOPT. "%TP" signifies a bit in the right half; "$TP", a byte pointer to a field. %TOALT==200000 ;4.8 => Standardize altmodes. %TOCLC==100000 ;4.7 => Convert lower case to upper on input. %TOERS==40000 ;4.6 => This tty can erase selectively %TOHDX==20000 ;4.5 => This tty is half-duplex. %TOMVB==10000 ;4.4 => This tty can handle backspaces directly. %TOSAI==4000 ;4.3 => This tty can handle the SAIL character ;set, if given control characters in image mode. %TOSA1==2000 ;4.2 => use the SAIL character set for echo and ;ascii mode output (actually just init %TSSAI of ;new jobs). %TOOVR==1000 ;4.1 => This tty can overprint successfully. %TOMVU==400 ;3.9 => This tty can move its cursor upward ;(that is, it is a display). %TOMOR==200 ;3.8 => do **MORE** processing on this tty ;(actually just used to init %TSMOR for new jobs). %TOROL==100 ;3.7 similarly, used to init %TSROL for new jobs. %TORAW==40 ;3.6 => don't optimize cursor motion (*Note Out: E/7.). %TOLWR==20 ;3.5 => this tty has lower case keyboard. ;(Doesn't affect system actions - exists to ;tell user programs what to do). %TOFCI==10 ;3.4 => this tty's keyboard has full TV character set. %TOIML==4 ;3.3 => this tty acts like an imlac %TOLID==2 ;3.2 => this tty can insert/delete lines. %TOCID==1 ;3.1 => thus tty can insert/delete characters. $TPPLF==170300 ;3-bit field saying how to pad LF. ;0 - don't. 1 - memowreck, 2741 (2 pad chars.). 2 - more. ;If a terminet, tells the baud rate. $TPPCR==140300 ;3-bit field saying how to pad CR. ;7 - unused. 6 - memowreck. 5 - 2741. 4 - execuport. ;0 - don't. 1 - normal. 2 - double. ;On datapoints, number of padding characters desired ;before each string of cursor motion commands. $TPPTB==110300 ;3 bit field saying how much padding needed after tab. ;0 => tabs not allowed; else 1 +<# padding chars needed> ;On displays: 0 don't use tabs, 1 use tabs, ;2 use VT52-style absolute positioning. %TPMTA==400 ;1.9 => treat bit 1.8 of input characters as the meta bit. ;This is for terminals such as Telerays which have Edit keys. %TPPRN==200 ;1.8 => interchange ( with [, and ) with ], on input. %TPTEL==100 ;1.7 => Treat CRLF input as CR for TELNET protocol. %TPCBS==40 ;1.6 => intelligent terminal protocol in use. ; *Note ITP: J. %TP11T==20 ;1.5 => PDP-11 TV tty. Reflects %TY11T. ;not settable by user. %TPORS==10 ;1.4 => output reset on this tty should really do something. %TPRSC==4 ;1.3 => this terminal implements %TDRSU and %TDRSD. ;These are commands usable in superimage output ;which perform region scrolling. *Note RSC: K/1.  File: ITSTTY, Node: H/1/c, Previous: H/1/b, Up: H/1, Next: H/1/d c. The TCTYP variable. It tells the system what type of display codes the terminal actually needs. The system takes the display commands that are output by programs and converts them into whatever will accomplish the desired result on the particular type of tty in use, according to the setting of the TCTYP variable. User programs should try to avoid looking at this variable; use TTYOPT instead. The possible values are: %TNPRT==0 ;printing terminal. %TNDP==1 ;good datapoint. %TNODP==2 ;"bad" datapoint or "loser". %TNIML==3 ;IMLAC. %TNTEK==4 ;Tektronix 4000 series. %TNTV==5 ;PDP-11 TV. %TNMEM==6 ;Memowreck. %TNSFW==7 ;"software" terminal that expects internal ITS ;display commands ("SUPDUP" codes). ; *Note SUPDUP: I/3/e. %TNTRM==10 ;Terminet. %TNESC==11 ;Display using ASCII standard display codes. %TNDTM==12 ;A Datamedia 2500. %TNRAY==13 ;Teleray 1061 %TNHDS==14 ;Concept-100 %TNH19==15 ;H19 %TNAAA==16 ;Ann Arbor Ambassador  File: ITSTTY, Node: H/1/d, Previous: H/1/c, Up: H/1, Next: H/1/e d. The TTYTYP variable. This variable contains the information on the line the tty is connected to, as opposed to the tty itself. Most of the fields in the TTYTYP table cannot be set with a system call. The exceptions are the input and output speed codes, which can be as the ISPEED and OSPEED variables with TTYVAR. "%TT" signifies a bit in the left half of TTYTYP; "$TT", a byte pointer to a field. "%TY" signifies a bit in the right half. %TTLCL==400000 ;BIT 4.9 ONE => LOCAL TTY %TT340==200000 ;BIT 4.8 ONE => CONSOLE NEXT TO 340 OR A 340 SLAVE %TT3HP==100000 ;BIT 4.7 HIGH PRIORITY ON 340 %TTPAR==004000 ;BIT 4.3 TTY needs to have parity sent. %TTDDI==002000 ;BIT 4.2 DONT DING ON EXCESS INPUT %TTIBM==001000 ;BIT 4.1 DATEL LINE $TTISP==260400 ;3.8-3.5 INPUT SPEED CODE $TTOSP==220400 ;3.4-3.1 OUTPUT SPEED CODE %TYDPK==400000 ;BIT 2.9 => this tty is on a datapoint controller line. %TYSTY==200000 ;BIT 2.8 => this tty is the alter ego of an STY. %TYNVA==100000 ;BIT 2.7 => this tty is a NOVA tty (They no longer exist) %TYMTY==040000 ;BIT 2.6 => this tty is on a Morton controller line. %TYDIL==020000 ;BIT 2.5 => this tty is on a dial-up line. %TY11T==010000 ;BIT 2.4 => this tty is a PDP-11 TV. %TYDL== 004000 ;BIT 2.3 => this tty is on a DC76 line. %TYOTY==002000 ;BIT 2.2 => this tty is a KA-10 console tty. %TYETY==001000 ;BIT 2.1 => this tty is a DTE-20 tty. %TYNTY==000400 ;BIT 1.9 => this tty is a TK-10 tty. %TYMDM==000200 ;BIT 1.8 => this tty is on a dial-up line with modem control. %TYKST==000100 ;BIT 1.7 => this tty is a KS-10 console tty. %TYDZT==000040 ;BIT 1.6 => this tty is a DZ-11 tty on a KS-10. %TYRLM==000020 ;BIT 1.5 => this tty is a connected to the ROLM data switch. The meanings of the possible 4-bit speed codes are: 0 = unknown 6 = 1800 baud 13 = 40K baud 1 = 600 baud 7 = 2400 baud 14 = 50K baud 2 = 110 baud 10 = 4800 baud 15 = 80K baud 3 = 150 baud 11 = 9600 baud 16 unused 4 = 300 baud 12 = 25K baud 17 unused 5 = 1200 baud  File: ITSTTY, Node: H/1/e, Previous: H/1/d, Up: H/1, Next: H/1/f e. The TTYCOM Variable. This variable contains the com link status of the tty, some user options associated with com links, and internal system flags. The following bits may be set with a CNSSET: %TCICO, %TCOCO, %TCRFS, %TCQRY. ;4.9 => tty in communicate mode %TCLFT==200000 ;4.8 => Local Feed Through (set if my program receiving his chars) %TCRFT==100000 ;4.7 => Remote Feed Through (set if his program receiving my chars) ;All characters typed on ttys with %TCRFT are given to all ttys ;with %TCLFT. ^_S and ^_E control these bits. %TCICO==40000 ;4.6 => Input Communicate Override (allows program to read and ;type out, even if the tty is in com mode. %TCOCO==20000 ;4.5 => Output Communicate Override (allows program to type out ;even if the tty is in com mode. ;4.4-4.3 => message receipt switch ;00 => accept %TCRFS==10000 ;10 => refuse %TCQRY==4000 ;01 => interrogate %TCMTR==2000 ;4.2 => tty's motor is off & must be turned ;on before any other output is done ;(only terminets have their motors shut off by ITS). %TCECH==1000 ;4.1 => the last output to this tty was PI echoing ;(used to prevent output RESET from throwing away echo). %TCDET==200 ;3.8 console's tree detached by top level interrupt. ;Set by NDETAC as signal to SYSCFM (console-free-msg typer) %TCDNG==100 ;3.7 => type bell on this tty (because input buffer full). %TCCBK==40 ;3.6 => reading args for a ^_K on this tty. %TCCBS==20 ;3.5 => reading args for a ^_S on this tty. %TCFPD==10 ;3.4 => First part of an output code sequence is done. %TCTPN==4 ;3.3 type ^_N on leaving com mode (unless user explicitly types ^_N) %TCPAD==2 ;3.2 0 => padding necessary on datapoint. %TCHNG==1 ;3.1 line seems not to be interrupting for output, ;so don't try to wait for output to get out. The right half is -1 for a tty that is not in a com link. For ttys in com links, the RH's are the links in a cirular list of all the ttys in the com loop. Each RH is the number of the next tty in the loop. The order of the ttys in the circular list has no significance.  File: ITSTTY, Node: H/1/f, Previous: H/1/e, Up: H/1, Next: H/1/g f. The TTYROL variable or "Scroll Count". The TTYROL variable contains the number of lines that the screen shifts up when, in scroll mode, an attempt is made to type past the bottom of the screen. On most terminals, this is 1. On terminals that can't scroll, it should be 0. On printing terminals (and inferior displays that ITS thinks are printing terminals) it should be 1.  File: ITSTTY, Node: H/1/g, Previous: H/1/f, Up: H/1 g. The TTYSMT or "SMARTS" variable. The TTYSMT variable is used to describe smart terminals. It contains information on three things: What sort of CPU the terminal has (in case you want to load a program into it), and To what extent (if at all) the terminal supports the ITS local-editing and line-saving protocols, and To what extent (if at all) the terminal supports the ITS terminal-independent graphics protocol. *Note Graphics: (SYSDOC;GRPHCS)*. %TQ signifies a bit or field in the left half of TTYSMT, and %TR signifies a bit or field in the right half. %TQMCH==700000 ;4.7-4.9 CPU type. 0 => unknown or uninteresting. ;1 => PDP11. 2 => IMLAC PDS4. 3 => IMLAC PDS1. ;These bits are for local-editing and line-saving (See SUPDUP doc) %TRLED==100000 ;2.7 Terminal supports the local-editing protocol. %TRLSV==034000 ;2.3-2.5 nonzero means terminal can save about 4**n lines. ;These bits record what timezone the terminal is physically in. %TRTIM==003700 ;2.2-1.7 signed offset from GMT minus 20. A value of zero ; means don't know, don't care, or user program hasn't ; implemented it yet. ;The remainder of TTYSMT pertains to the graphics protocol. ;If %TQGRF is 0, it should all be 0. %TQGRF==1 ;3.1 Terminal understands the graphics protocol. ;the old name for this was %TQGPH %TQHGT==76000 ;4.2-4.6 Character height in dots. %TQWID==1700 ;3.7-4.1 Character width in dots. ;The remaining bits and fields in TTYSMT indicate which optional ;features of the graphics protocol are supported. %TQSET==2 ;3.2 Terminal implements multiple sets. %TQREC==4 ;3.3 Terminal implements the rectangle commands. %TQXOR==10 ;3.4 Terminal implements XOR mode. %TQBNK==20 ;3.5 Terminal implements blinking. %TQVIR==40 ;3.6 Terminal implements virtual coordinates. %TRGIN==400000 ;2.9 Terminal provides graphic input. %TRGHC==200000 ;2.8 Terminal provides has graphic hardcopy. %TRSCN==040000 ;2.6 Terminal implements scan-line output.  File: ITSTTY, Node: H/2, Previous: H/1, Up: H 2. SYSTEM CALLS. * Menu: * RSSIZE: H/2/a RSSIZE. * CNSGET: H/2/b CNSGET. * CNSSET: H/2/c CNSSET. * TTYVAR: H/2/d TTYVAR.  File: ITSTTY, Node: H/2/a, Previous: H/2, Up: H/2, Next: H/2/b a. RSSIZE. The symbolic system call RSSIZE returns the horizontal and vertical screen size of a tty. It takes one argument, like the argument to TTYGET, and returns two values: the vertical size and the horizontal size.  File: ITSTTY, Node: H/2/b, Previous: H/2/a, Up: H/2, Next: H/2/c b. CNSGET. This symbolic system call takes one argument specifying the tty (like TTYGET's argument) and returns seven values: the vertical screen size, the horizontal screen size, the TCTYP variable, the TTYCOM variable, the TTYOPT variable, the TTYTYP variable, the TTYSMT variable. Note that the CNSGET call can fail quite legitimately, if the user translates device TTY: to a file of commands for the program. Therefore, you should not naively put a .VALUE or a .LOSE after a CNSGET, but instead write code to assume that a command file is being used and do the "appropriate" thing.  File: ITSTTY, Node: H/2/c, Previous: H/2/b, Up: H/2, Next: H/2/d c. CNSSET. This symbolic system call is used to set the permanent and semipermanent variables. It takes six arguments. The first is a tty channel; the next five are the new values of the vertical screen size, the horizontal screen size, the TCTYP variable, the TTYCOM variable, the TTYOPT variable. If the second, third or fourth argument is negative, the corresponding variable will not be altered. Fewer than six arguments may be given, in which case variables corresponding to arguments not given will not be changed. The system will make sure that the variables are not given inconsistent values, and will not allow some bits in TTYCOM to be changed. You should always make sure that a CNSSET does not change bits or variables that you do not specifically want to change. Do this by 1) specifying -1's for the screen sizes and TCTYP if you are not changing them, or 2) reading in the old setting s with a CNSGET, altering specific bits or variables, and then writing the altered settings out.  File: ITSTTY, Node: H/2/d, Previous: H/2/c, Up: H/2 d. TTYVAR. The TTYVAR symbolic system call allows you to read and/or write any of the permanent or semipermanent variables. See the entry for TTYVAR in the ITS .CALLS file for information on the several ways of using it. Variables may be specified by sixbit names and read, written, or modified (increased, decreased, bits set, cleared, or complemented). Of course, some fields of some variables may not be changed; attempts to change them will be ignored. The variable names now allowed are HEIGHT, IDLTIM, ISPEED, OSPEED, SMARTS, TCTYP, TTYCOM, TTYOPT, TTYROL, TTYSMT, TTYTYP, and WIDTH. Many of them have been described under semipermenent variables. Here are the rest: ISPEED and OSPEED are the input and output speeds of the terminal. They refer to the input and output speed codes stored in the TTYTYP variable. However, they are not speed codes; they are the speeds, in bauds. Also, you are allowed to set the ISPEED and OSPEED variables, while you are not allowed to set the whole TTYTYP variable. IDLTIM (not at all permanent) is the length of time since the last input character was typed on the tty, in 30'ths of a second. Note that the TTYVAR call can fail quite legitimately, if the user translates device TTY: to a file of commands for the program. Therefore, you should not naively put a .VALUE or a .LOSE after a TTYVAR, but instead write code to assume that a command file is being used and do the "appropriate" thing.  File: ITSTTY, Node: I, Previous: H, Up: Top, Next: J I. PSEUDO-TELETYPES (STY'S). Pseudo-teletypes are a facility that allows programs to do the things that users do with terminals - type in on them, and observe what is typed out on them. A sty is a device which is analogous to a user's physical terminal. Outputting to a sty device is like typing on a physical terminal's keyboard. Reading from a sty is analogous to a physical terminal's gobbling down of output. Thus, outputting a "^Z" to a sty just opened would load a DDT. DDT's initial typeout "xx ITS.nnn. DDT.nnn." etc. would then be available as input from the sty. The system contains many tty devices. A physical terminal that is online is the end of a pipeline whose other end is one of the tty devices. A sty device is also one end of a pipeline whose other end is one of the tty devices. Each sty device has a particular tty device permanently associated with it; the sty's are distinguished by number, as are tty's, and the number of the tty associated with a sty equals the sty number plus the value of the symbol NFSTTY. Since the most common use of stys is for network TELNET servers, a special feature called "direct connection" exists for tying a sty to a pair of network channels, so that all input from the net is fed to the sty and all input from the sty is fed to the net, without having to run the actual server program. * Menu: * Opening: I/1 Opening STYs. * Output: I/2 Output to STYs. * Input: I/3 Input from STYs. * Closing: I/4 Closing STYs. * Controlling: I/5 Controlling the tty associated with a STY. * Direct: I/6 Direct connections to network channels: STYNET. * STYGET: I/7 STYGET.  File: ITSTTY, Node: I/1, Previous: I, Up: I, Next: I/2 1. OPENING STY'S. There are two ways to open a sty: opening the STY device, and opening a Snm device, where nm is the number of the desired sty. Opening STY is a convenient way of obtaining any sty that is free. If STY is not open, opening it causes the system to find a sty which is free and whose associated tty is also free, and open it. Opening STY when STY is already open on another channel will use the same sty as before. Thus, a program that wishes to use one sty can avoid the trouble of finding a free sty and remembering its number by using device STY throughout. For more complicated applications, any sty may be opened by number (Open device S00 to get sty number 0). However, a sty that is open in another job may not be opened. When a sty is opened that was not already open, the tty on the other end of the pipeline is put into a standard state - the one that would result from doing :TCTYP PRINTING on that tty. Also, an input RESET and an output RESET are done, clearing all buffers. Sty opens recognize two special mode bits. Bit 3.3 ("image mode") on an input open is copied into the associated tty's %TOHDX bit, so if the sty is opened for input in image mode, characters output to the sty will not be read back in as echo. Bit 3.4, if 1 in either an input or an output open, causes the sty to operate in "don't hang" mode in that direction. *Note NH Out: I/2/a. *Note NH In: I/3/a. Bit 3.5, on input, says that %TDORS should be provided when tty output is reset, even if the tty is not a software tty (*Note TDORS: K/2.). This makes it possible for the sty handling job to tell when tty output has been thrown away. These modes are not remembered separately for each channel; each open sets the modes for all channels in that direction.  File: ITSTTY, Node: I/2, Previous: I/1, Up: I, Next: I/3 2. OUTPUT TO STY'S. IOT'ing a character to a sty output channel is like typing the character into the tty on the other end of the pipeline. The characters "^Z" and "^_" are special just as they are on physical terminals. Characters sent to a sty may be echoed, just as characters typed on a physical terminal may be (of course, the tty may be made half-duplex, in which case there will be no echoing. When the sty is opened for input, it is there is an option to make the tty half-duplex). The characters output need not be ascii - any character in the 12-bit TV character set may be output to the tty, which will treat it the way a TV would. * Menu: * Empty: I/2/a What happens when the buffer is empty. * Interrupts: I/2/b Interrupts. * Reset: I/2/c RESET on sty output channels. * Status: I/2/d STATUS on sty output channels.  File: ITSTTY, Node: I/2/a, Previous: I/2, Up: I/2, Next: I/2/b a. What happens when the buffer is empty. An attempt to output to a sty channel open in normal output mode when the tty input buffer has no room in it will wait until there is room. This is unlike the treatment of physical terminals, which unfortunately cannot be told to wait. If the channel is open in "don't hang" mode, then the character will be thrown away, and "^G" echoed, just as on a physical terminal. This mode is good for programs that simulate special types of terminals for the user.  File: ITSTTY, Node: I/2/b, Previous: I/2/a, Up: I/2, Next: I/2/c b. Interrupts. If a sty output channel is enabled to interrupt, an interrupt will happen whenever a job attempts to read from the associated tty and its input buffer (the sty's output buffer!) is empty.  File: ITSTTY, Node: I/2/c, Previous: I/2/b, Up: I/2, Next: I/2/d c. RESET on sty output channels. A .RESET UUO or a RESET symbolic system call done on a sty output channel is like a RESET on an input channel; of the associated tty; all characters waiting in the input buffer of the tty are thrown away. If they have not echoed already they will not; if they have not interrupted already they will not.  File: ITSTTY, Node: I/2/d, Previous: I/2/c, Up: I/2 d. STATUS on sty output channels. A .STATUS UUO or STATUS symbolic system call done on a sty output channel will return the device code 25, and will set bit 2.2 or bit 2.1 if the tty's input buffer is empty or almost full, respectively.  File: ITSTTY, Node: I/3, Previous: I/2, Up: I, Next: I/4 3. INPUT FROM STY'S. Characters read in by a sty are like characters received by a physical terminal's printer. The sty input effectively comes out of the tty output buffer. The sty will read the exact same sequence of characters that a physical terminal would receive with the same settings of the various tty variables. This includes padding and cursor motion characters according to the setting of the tty's TTYOPT variable, but the initial setting given to the tty when the sty is first opened causes padding not to be done. * Menu: * Empty: I/3/a What happens when the buffer is empty. * Interrupts: I/3/b Interrupts. * Status: I/3/c .STATUS on sty input channels. * Reset: I/3/d .RESET on sty input channels.  File: ITSTTY, Node: I/3/a, Previous: I/3, Up: I/3, Next: I/3/b a. What happens when the buffer is empty. There are two modes of input from sty's, distinguished by what happens when the tty has no characters to output. The normal mode waits for output from the tty to be available. The other mode, "don't hang" mode, returns immediately when there is no input, giving an indication of that fact. "Don't hang" unit mode IOT's return -1 instead of an input character. SIOT's return with the pointer and count not completely advanced. Block mode IOT's have a kludgerous scheme and should be avoided. "Don't hang" mode is selected by opening an input channel with the 20 bit in the open-mode set to 1.  File: ITSTTY, Node: I/3/b, Previous: I/3/a, Up: I/3, Next: I/3/c b. Interrupts. A sty input channel may be enabled to interrupt. It will do so whenever input (tty output) is available. In normal mode, it is expected that the interrupt routine will read one character; if when the interrupt is dismissed more are available another interrupt will occur. In "don't hang" mode, the interrupt routine should continue reading until it reads a -1, indicating that no more input is available at the moment.  File: ITSTTY, Node: I/3/c, Previous: I/3/b, Up: I/3, Next: I/3/d c. .STATUS on sty input channels. A .STATUS UUO or STATUS symbolic system call on a sty input channel returns bit 2.1 as 1 iff the tty's output buffer is full, and 2.2 as 1 iff it is empty.  File: ITSTTY, Node: I/3/d, Previous: I/3/c, Up: I/3 d. .RESET on sty input channels. A .RESET UUO or RESET symbolic system call on a sty input channel is approximately the same as a .RESET on an output channelof the associated tty - namely, it throws away what is in the tty's output buffer. However, RESET on a tty output channel also initializes some bits associated with that particular channel, while sty input reset doesn't change the settings of those bits for any of the tty output channels. Also, tty output reset may not actually discard the buffer if the tty's %TPORS bit is 0, or if the buffer contains PI-echoed characters, but sty input reset will always clear out the buffer even in those circumstances. An input RESET is part of the process of initializing a sty for use, performed when the sty is opened after being free.  File: ITSTTY, Node: I/4, Previous: I/3, Up: I, Next: I/5 4. CLOSING STY'S. When a sty channel is closed, but the sty is still open on some other channel, nothing special happens - if the channel were reopened, nothing would have changed. In particular, nothing is done to the state of the associated tty or to characters sitting in its buffers. When a sty is closed on the only channel it is open on (this happens when the only channel it is open on is reopened), if the associated tty is in use as a tree-controlling console, the tree will be logged out. If the tty is in use as a device its status will not be changed.  File: ITSTTY, Node: I/5, Previous: I/4, Up: I, Next: I/6 5. CONTROLLING THE TTY ASSOCIATED WITH A STY. Any of the special symbolic system calls for tty's, except for LISTEN, may be given a sty channel instead of a tty channel as its first argument, in which case the function will be performed for the tty associated with the specified sty. The calls that are most useful in this mode are TTYGET, CNSGET and CNSSET. TTYGET returns the TTYSTS variable, which tells whether the tty is in use (%TSFRE), by what job (the R.H.), and whether as a console or as a device (%TSCNS) (*Note TTYSTS: G/1/b. for a description of the TTYSTS variable and the values of those two bits). CNSGET returns the information that ITS uses in deciding exactly how to treat the tty. CNSSET sets that information. Programs that use sty's will often want to do a CNSSET to the sty as soon as it has been opened. For example, the 340D program does a CNSSET to the sty it uses, setting it to be a datapoint with a peculiar screen size. This causes ITS to send datapoint cursor motion codes to the tty. The 340D program reads them from the sty and simulates their effect in the display that it maintains on the 340. The TTYCOM variable may be examined with a CNSGET, and the com-mode status of the tty may be altered by outputting the appropriate ^_ codes to the STY. Any symbolic system call that requires a job-spec as an argument may be given a sty channel, which will signify whatever job has the associated tty in its possession.  File: ITSTTY, Node: I/6, Previous: I/5, Up: I, Next: I/7 6. DIRECT CONNECTIONS TO NETWORK CHANNELS: STYNET. It is possible with this call to connect a sty to a pair of network channels, one open for input, and one open for output. When the direct connection is established, anything received by the net input socket will be fed automatically as output to the sty, and any type-out that the sty receives from its TTY will be fed automatically to the net output channel. The transfer of data is handled by the system at clock level, eliminating the need for the program to wake up at each character. The STYNET call returns immediately, without actually transferring any data. Once established, the direct connection will last until broken explicitly by the user (with another STYNET), or until an escape condition is detected by the system. Escape conditions include receipt of a TELNET control character on the net input channel, and either net channel's getting into an abnormal state (other than %NSOPN, %NSINP, or %NSCLI) - in general, things which the system expects that the user program will want to take action on. When the system detects an escape condition it will break the direct connection and notify the user program with an interrupt on the net input channel. While the connection lasts, interrupts on the net channels due to arriving data are intercepted by the system, so an interrupt implies that the connection has been broken. Only one input and one output net channel can be connected to a sty, and only one sty can be connected to any net channel. Both sides of a sty are connected and disconnected at once. A job can connect a sty if it has the sty open in either direction (but it will generally want to have both directions open). When a %TDORS comes out of the sty, indicating that the TTY's output buffer has been cleared, this is indicated to the net output channel by means of a network interrupt, and the string of up to 3 characters specified as the fourth argument to the STYNET call. If the tty is a software tty and uses the intelligent terminal protocol, then output RESETs will also block the TTY at main program level. The sty-operating program will not be informed of this, so it is up to the program at the other end of the network connection to send back a ^\^P to turn output back on. If you use STYNET with the official TELNET protocol, you must turn on the %TPTEL bit in the sty TTY's TTYOPT variable, to cause the sequence CR-LF received from the net to be turned into just a CR. The arguments to a STYNET call are as follows: arg 1 sty channel (either direction). arg 2 -1 to disconnect the sty from its network channels (in which case args 3 and 4 are unnecessary), or Net input channel (to connect sty output to). arg 3 Net output channel (to connect sty input to). arg 4 Characters to send out on net when an output .RESET is done on the sty's TTY. Up to 3 8-bit characters, left-justified.  File: ITSTTY, Node: I/7, Previous: I/6, Up: I 7. STYGET. Sty handling programs that wish to take an active interest in managing the lives of the programs attached to the sty's alter ego may use the STYGET symbolic system call to get information on what those jobs are doing. STYGET takes one argument - a tty spec - and returns the following five values: 1) The RH is 0 if the sty is free; otherwise, it is the job number the job that owns the sty. The LH bits %SSHNG and %SSOHG if set indicate that input and output, respectively, are in don't hang mode. This value contains garbage if the tty is not associated with a sty. 2) -1 if the tty is free; otherwise, the job number of the job that owns the tty. 3) -1 if the tty is not a console; otherwise, the RH contains the job number of the top level job in the tty's tree and the LH is nonzero iff the tree is logging out. 4) Gives information on whether a job is hung trying to use the tty: Bit 1.1 if 1 => the job owning the tty is waiting for input. Bit 4.9 if 1 => that job is waiting for output buffer room. 5) Indicates the status of the tty's buffers: Bit 4.9 if 1 => input is available. Bit 4.8 if 1 => output buffer space is available. 6) Is the tty's TTYSTA word, which contains these bits: Bit 4.9 (%TACFM) 1 => tty has had a "console-free" message printed, and has not been in use since. Bit 4.8 (%TAC.Z) 1 => tty is being ^Z'd, but the tree has not been created yet. %TACFM will be 0. If %TACFM is 0 and %TAC.Z is also 0, the tty is in the process of being freed. Bit 4.7 (%TANJS) 1 => the ^Z attempt in progress on this tty is being ignored, because all the job slots in the system are in use. Bits 4.6-4.3 (%TANEC) Number of following chars to inhibit echo and ints for. This is used for the arg chars that follow Top-E, Top-S, Top-Y, etc.  File: ITSTTY, Node: J, Previous: I, Up: Top, Next: K J. THE INTELLIGENT TERMINAL PROTOCOL. The %TPCBS bit in the RH of TTYOPT turns on the intelligent terminal protocol. This gives the terminal some extra control over things through the use of escape sequences introduced by 034 (control backslash). These escape sequences are handled at a "lower level" than everything described above, and the characters composing them are not echoed. The idea is not that the user should produce the escape sequences by typing the characters, but that the terminal should send them of its own accord when necessary, invisibly to the user. For example, when the user types a ^\, the terminal should send ^\^\, which is how to cause the intelligent terminal protocol to pass the user's ^\ up to higher levels. * Menu: * Escape: J/1 Escape sequences. * Alloc: J/2 Allocation. * Reset: J/3 Output-reset.  File: ITSTTY, Node: J/1, Previous: J, Up: J, Next: J/2 1. ESCAPE SEQUENCES. (The spaces that appear inside the escape sequences are just for readability; they should not actually be sent) The escape sequences are: ^\ where is in {@, A, B, ..., _} and is any character inputs the character (&27)*200+. That is, supplies the 4 meta-bits for . The meta bits are (in their ultimate positions): %TXTOP 4000 "TOP" %TXSUP 1000 "SUPER" (Used to mean "SHIFT".) %TXMTA 400 "META" %TXCTL 200 "CONTROL" The bits should appear in shifted right 5; thus, "C" = 103 will set %TXCTL and %TXMTA. Note that %TXCTL and %TXMTA are used with the uncontrollified character, while %TXTOP is used with the code for a SAIL-graphic < 40, not with the letter which appears on that key on a TV keyboard. Thus, 32 is the code for CALL, while %TXTOP+32 is the code for the harmless SAIL graphic character NOT-EQUAL and %TXCTL+132 is the code for CONTROL-Z. %TXCTL+32 is CONTROL-CALL, and %TXCTL+%TXTOP+32 is CONTROL-NOT-EQUAL. %TXTOP+132 is meaningless, because %TXTOP makes sense only with basic 7-bit codes that are less than 40. (In the following, # represents a number between 0 and 177 (octal) which is simply transmitted as a character.) ^\ ^A # increments the allocation by # characters. ^\ ^Z zeros the allocation. ^\ ^I sets the allocation to infinity. ^\ ^S stops output at main program level. ^\ ^R restarts output at main program level. ^\ ^P # # sets the cursor position. The first # is the vertical position (zero at the top of the screen.) The second # is the horizontal position (0 at the left margin.) Output is then restarted at main program level. ^\ ^\ inputs a ^\. This is what to send when the user types ^\ on the keyboard (unless the full character set is being hacked in which case one would probably use either "^\ A \" to input a control-backslash, or "^\ P ^\" to input a less-than-or-equal). ^\ ^C signals that the screen has been "messed up". This gives a %PIATY interrupt to the running program, just as if its superior had taken the terminal away and presumably messed up the screen. Some programs (including TECO) will respond to this by redisplaying everything.  File: ITSTTY, Node: J/2, Previous: J/1, Up: J, Next: J/3 2. ALLOCATION. To provide for intelligent terminals which sometimes can't process characters as fast as ITS can send them, there is an output allocation mechanism. The output allocation is the number of characters which can be sent to the terminal without overloading it. After this number has been sent, ITS will cease outputting at interrupt level (but IOT'ing of output may continue if the output buffer is not full). Transmission will resume as soon as the terminal increases the allocation above zero with a ^\ ^A # or a ^\ I. The initial default value of the allocation is infinity; thus output normally never stops. When the terminal wishes to begin to use the allocation feature, it should do ^\ ^Z to initialize the allocation to zero. Then it should do one or more ^\ ^A #'s to tell ITS how much buffer space it has (more than one is needed if the terminal wants to say it can buffer more than 177 characters). When characters arrive from ITS, the terminal need not do anything, since ITS will decrement the allocation automatically; but, when the terminal processes the characters from its buffer, it must tell ITS that the buffer space is free once more by sending a ^\ ^A #. For example, the terminal might send ^\ ^A ^X once for each 24. characters it removes from its buffer. If the terminal has reason to suspect that it and ITS have gotten out of phase in remembering the allocation, it can always reinitialize without fear using ^\ ^Z ^\ ^A . To stop using the allocation feature, just do ^\ ^I.  File: ITSTTY, Node: J/3, Previous: J/2, Up: J 3. OUTPUT-RESET. If the TTY is a software-tty (*Note Soft: K.), uses the intelligent terminal protocol (has %TPCBS on in TTYOPT), and does output-resets (has %TPORS on in TTYOPT), then .RESET on an output channel to that tty is handled specially. Any characters in ITS's output buffer are thrown away, a %TDORS character is sent to the terminal, and output is blocked at main program level. The terminal should then throw away any characters in its buffer. If the terminal is connected to ITS through a network each node in the path should throw away the contents of its output buffer and pass on the %TDORS. When the %TDORS gets to the terminal, it should determine where the output that wasn't thrown away left the cursor and send back a ^\ ^P # #, which sets the ITS cursor to this position and restarts output.  File: ITSTTY, Node: K, Previous: J, Up: Top K. SOFTWARE TTYS AND ITS OUTPUT BUFFER CODES. When a tty's TCTYP variable is set to %TNSFW, ITS sends the contents of the tty output buffer directly to the terminal, instead of translating it into one of the codes used by any of the normal types of terminals. This can be very convenient for new types of intelligent terminals, and for sty-handling programs that must actually understand the data read from the sty. The data output to a software tty includes printing characters, and ITS display commands as are found in the tty output buffer. Not having to convert them into a different code at interrupt level saves time; in addition, the display commands encode a superset of the capabilities all real terminals supported by ITS, and therefore more convenient than the code of any actual terminal. * Menu: * Codes: K/1 ITS output buffer codes. * TDORS: K/2 Handling %TDORS. * SCPOS: K/3 The SCPOS system call.  File: ITSTTY, Node: K/1, Previous: K, Up: K, Next: K/2 1. ITS OUTPUT BUFFER CODES. The internal ITS output buffer codes are 8 bits long. Sty handlers should read them in unit mode only. To read more than one at a time, use SIOT with 8-bit bytes. Real terminals are assumed to be able to receive only 7-bit characters; for them, codes 0 - 176 are sent as is; codes above 176 have 176 subtracted from them and are escaped by a 177. 200-codes that have following arguments which can reasonably be zero (%TDMOV, %TDMV0, %TDMV1) have 1 added to each argument, so that 0 need not be sent. Note that not all 200-codes are meaningful on all types of terminals. Programs outputting them in superimage mode must be careful to use codes that work on the terminal they have. 0 - 177 Characters, to be output as is. Normally, only single-spacing graphic characters will be sent this way. Other characters will appear if programs output them in image mode. %TDMOV=200 Move cursor. followed by 4 bytes of arguments: first, the old vertical and horizontal positions (these are probably not needed by the sty handling program); next, the desired vertical and horizontal positions. Should not be used on "raw" ttys (%TORAW set), though it will work. %TDMV1==201 Should never be encountered. If it is, it is followed by 2 bytes of args - the desired vertical and horizontal positions. Should not be used on "raw" ttys (%TORAW set). %TDEOF==202 Clear rest of line and rest of page. Does not move the cursor. Does nothing on terminals that aren't selectively erasable, even if they are displays. %TDEOL==203 Clear rest of line %TDDLF==204 Clear out character after cursor, without moving cursor. %TDMTF==205 Turn off motor (should not come out except on terminets). %TDMTN==206 Turn on motor (" "). %TDCRL==207 Move cursor to beginning of next line, and clear that line. If done when the cursor is on the bottom line, it causes the terminal to scroll its whole screen up. The TTYROL variable tells ITS how many lines the terminal WILL scroll. %TDNOP==210 No-op. %TDBS==211 Backspace - used only on tty's with %TORAW set. %TDLF==212 Linefeed - ("). %TDRCR==213 Carriage return - ("). %TDORS==214 Output reset. Put in the buffer when a tty output reset is done, to inform the sty handling program or the terminal. Should never be sent by a program explicitly. %TDQOT==215 Quote the next character so that it is output to the terminal without being interpreted by ITS. %TDFS==216 Move cursor forward one column. This is identical to an appropriate %TDMOV command, and exists to increase the efficiency of utilisation of space in the output buffer. %TDMV0==217 Move cursor, followed by 2 args: the desired vertical and horizontal positions. Should not be used on "raw" ttys (%TORAW set). %TDCLR==220 Clear the screen, and move the cursor to the top left. On printing terminals, it does nothing. %TDBEL==221 Produce a sound on the terminal, or otherwise try to attract the user's attention, without permanently altering the contents of the screen. %TDINI==222 Sent at system start-up to all terminals, to tell them to reset themselves. %TDILP==223 Insert Line Positions. Followed by a byte containing the number of lines to insert. The current line and all lines below it are pushed down on the screen that many positions. Lines pushed off the bottom of the screen are lost. Blank lines appear at the cursor to replace the lines shifted downward. The cursor does not move. This code and the following one should be used only on terminals which have %TOLID set, and only with the cursor at the beginning of a line. %TDDLP==224 Delete Line Positions. Followed by a byte containing the number of positions to delete. That many lines, starting with the current line, disappear. The lines below them are shofted up to take their places. Blank lines are shifted in as necessary at the bottom of the screen. The cursor does not move. %TDICP==225 Insert Character Positions. Followed by a byte containing the number of spaces to insert. All of the characters on the current line from the cursor to the end move that many positions to the right. The last few move off the right margin and disappear. The terminal is not expected to know anything about continuation lines. Spaces are shifted in at the cursor to replace the characters that are moving right. This code and the following one should be used only on terminals which have %TOCID set. %TDDCP==226 Delete Character Positions. Followed by a byte containing the number of character positions to delete. All of the characters to the right of the cursor move that many positions left, except for the first few, which disappear rather than move past the cursor. Spaces appear at the right margin to replace them. %TDBOW==227 Turns on inverse video mode for characters which are output subsequently. The terminal should use some sort of alternate display mode to emphasize them. %TDRST==230 Turns off inverse video mode. If any other similar modes are created, %TDRST will turn them off too. %TDGRF==231 This is supposed to be for graphics, but it is not implemented by anything. %TDRSU==232 Region scroll upwards. %TDRSD==233 Region scroll downwards. These two commands can be used if the %TPRSC bit is on in TTYOPT. The %TDRSU/%TDRSD command is followed by two parameter characters. The first is the number of lines in the region to be scrolled; the second is the number of lines by which the text is to be scrolled. A region of the screen, which starts at the line containing the cursor and proceeds downward for the specified number of lines, is shifted by the specified amount. %TDRSU shifts text upwards, bringing in blank lines at the bottom of the region. %TDRSD shifts text downwards, bringing in blank lines at the top of the region. The cursor is not moved. If either parameter is 0 the command should be ignored. If the size of the region is larger than the size of the screen below the cursor, the region should end at the bottom of the screen. If the number of lines to scroll by is not less than the size of the region, the region should be cleared.  File: ITSTTY, Node: K/2, Previous: K/1, Up: K, Next: K/3 2. HANDLING %TDORS. %TDORS is output to a software tty when an output RESET was done on the tty, discarding some number of output characters. For a normal terminal, ITS keeps track of the cursor position at interrupt level; a RESET knows that the interrupt level value is the correct one. For software terminals, ITS does not remember an interrupt-level cursor position, so it is up to the terminal (or sty-handler) to inform ITS of the actual cursor position after each RESET. RESET turns on the "hold output" bit for the tty, to make sure that nothing happens to confuse the matter until that is done. Actual terminals should use the ^\ ^P # # command of the Intelligent Terminal Protocol (*Note ITP: J/3.). Sty handlers should use the SCPOS system call (*Note SCPOS: K/3.). %TDORS will be sent to sty ttys even if they are not software ttys, if %SSORS is set for the sty. That will be so if the sty was opened for input with bit 20 set in the open mode. In this case, SCPOS need not be done, since the system knows the cursor position. If the program does something with the %TDORS that changes the cursor position, however, it should do an SCPOS to inform ITS of the fact. Unlike the case of software ttys and intelligent-terminal protocol ttys, output will not be hung up until this SCPOS is received.  File: ITSTTY, Node: K/3, Previous: K/2, Up: K 3. THE SCPOS SYSTEM CALL. The SCPOS system call is used for telling ITS that a tty's cursor is actually located at a given spot. IT DOES NOT MOVE THE CURSOR. To move the cursor, ^P-codes or ITS output buffer codes must be output. SCPOS must be used after any event in which ITS does not understand how the cursor is moving. Luckily, there are only two. A program which has done super-image output must SCPOS if the output moves the cursor at all; a sty-handler using a software tty must SCPOS after an output RESET. Physical software ttys must do the equivalent of an SCPOS after output RESETs, but they use the Intelligent Terminal Protocol instead. The first argument to an SCPOS system call should be a tty specifier (*Note TTY spec: G/2.). The next two arguments should be the corrected vertical and horizontal positions. The third argument is optional, and if present sets the TTOALC variable of the tty. A third argument of -1 is the way to clear the hold-output bit after an output reset. SCPOS does not require ownership of the terminal; just output permission (*Note Permit: B/3.).  Tag Table: File: ITSTTY Node: Top³8 File: ITSTTY, Node: Aµ209 File: ITSTTY, Node: A/1µ783 File: ITSTTY, Node: A/1/a¶879 File: ITSTTY, Node: A/2·719 File: ITSTTY, Node: A/2/a¸631 File: ITSTTY, Node: A/2/b¹220 File: ITSTTY, Node: A/2/c¹852 File: ITSTTY, Node: A/3±1045 File: ITSTTY, Node: A/4±2512 File: ITSTTY, Node: A/4/a±3567 File: ITSTTY, Node: A/4/b±7111 File: ITSTTY, Node: A/4/c±8543 File: ITSTTY, Node: A/4/d±9171 File: ITSTTY, Node: A/4/e±9847 File: ITSTTY, Node: A/4/f²1071 File: ITSTTY, Node: A/4/g²2535 File: ITSTTY, Node: A/5²3286 File: ITSTTY, Node: B²4887 File: ITSTTY, Node: B/1²6017 File: ITSTTY, Node: B/2²6913 File: ITSTTY, Node: B/3²8783 File: ITSTTY, Node: B/4²9753 File: ITSTTY, Node: B/5³1853 File: ITSTTY, Node: C³2391 File: ITSTTY, Node: C/1³2882 File: ITSTTY, Node: C/3³3947 File: ITSTTY, Node: C/3/a³5386 File: ITSTTY, Node: C/3/b³5981 File: ITSTTY, Node: C/3/d³7382 File: ITSTTY, Node: D³8148 File: ITSTTY, Node: D/1³9205 File: ITSTTY, Node: D/2´2157 File: ITSTTY, Node: D/3´6093 File: ITSTTY, Node: D/4´7874 File: ITSTTY, Node: D/5µ2007 File: ITSTTY, Node: D/6µ2344 File: ITSTTY, Node: D/7µ3370 File: ITSTTY, Node: D/8µ4443 File: ITSTTY, Node: Eµ7111 File: ITSTTY, Node: E/1µ8393 File: ITSTTY, Node: E/2¶0094 File: ITSTTY, Node: E/2/a¶0749 File: ITSTTY, Node: E/2/a/1¶1944 File: ITSTTY, Node: E/2/a/2¶2245 File: ITSTTY, Node: E/2/a/3¶2467 File: ITSTTY, Node: E/2/a/4¶3456 File: ITSTTY, Node: E/2/a/5¶4395 File: ITSTTY, Node: E/2/a/6¶5078 File: ITSTTY, Node: E/2/a/7¶5516 File: ITSTTY, Node: E/2/a/8¶6293 File: ITSTTY, Node: E/2/a/9¶6663 File: ITSTTY, Node: E/2/a/10¶7087 File: ITSTTY, Node: E/2/b¶8083 File: ITSTTY, Node: E/2/c¶9177 File: ITSTTY, Node: E/2/c/1·0146 File: ITSTTY, Node: E/2/c/2·0486 File: ITSTTY, Node: E/3·1015 File: ITSTTY, Node: E/4·5836 File: ITSTTY, Node: E/4/a·6612 File: ITSTTY, Node: E/4/b·7759 File: ITSTTY, Node: E/5·8265 File: ITSTTY, Node: E/6·9269 File: ITSTTY, Node: E/7¸0518 File: ITSTTY, Node: E/8¸3878 File: ITSTTY, Node: E/9¸4869 File: ITSTTY, Node: E/10¸5413 File: ITSTTY, Node: F¸5791 File: ITSTTY, Node: F/1¸6575 File: ITSTTY, Node: F/2¸7551 File: ITSTTY, Node: F/2/a¸8009 File: ITSTTY, Node: F/2/b¸9958 File: ITSTTY, Node: F/3¹1464 File: ITSTTY, Node: F/4¹2155 File: ITSTTY, Node: G¹3306 File: ITSTTY, Node: G/1¹5754 File: ITSTTY, Node: G/1/a¹5983 File: ITSTTY, Node: G/1/b¹8395 File: ITSTTY, Node: G/1/c±00841 File: ITSTTY, Node: G/2±01029 File: ITSTTY, Node: G/2/a±02128 File: ITSTTY, Node: G/2/b±03852 File: ITSTTY, Node: G/2/c±05628 File: ITSTTY, Node: H±06320 File: ITSTTY, Node: H/1±07001 File: ITSTTY, Node: H/1/a±07472 File: ITSTTY, Node: H/1/b±08916 File: ITSTTY, Node: H/1/c±11981 File: ITSTTY, Node: H/1/d±12930 File: ITSTTY, Node: H/1/e±14851 File: ITSTTY, Node: H/1/f±17022 File: ITSTTY, Node: H/1/g±17487 File: ITSTTY, Node: H/2±18935 File: ITSTTY, Node: H/2/a±19126 File: ITSTTY, Node: H/2/b±19430 File: ITSTTY, Node: H/2/c±20089 File: ITSTTY, Node: H/2/d±21194 File: ITSTTY, Node: I±22741 File: ITSTTY, Node: I/1±24472 File: ITSTTY, Node: I/2±26344 File: ITSTTY, Node: I/2/a±27269 File: ITSTTY, Node: I/2/b±27858 File: ITSTTY, Node: I/2/c±28145 File: ITSTTY, Node: I/2/d±28569 File: ITSTTY, Node: I/3±28875 File: ITSTTY, Node: I/3/a±29684 File: ITSTTY, Node: I/3/b±30410 File: ITSTTY, Node: I/3/c±30935 File: ITSTTY, Node: I/3/d±31209 File: ITSTTY, Node: I/4±32076 File: ITSTTY, Node: I/5±32726 File: ITSTTY, Node: I/6±34279 File: ITSTTY, Node: I/7±37305 File: ITSTTY, Node: J±39088 File: ITSTTY, Node: J/1±40013 File: ITSTTY, Node: J/2±42507 File: ITSTTY, Node: J/3±44143 File: ITSTTY, Node: K±45038 File: ITSTTY, Node: K/1±46035 File: ITSTTY, Node: K/2±51091 File: ITSTTY, Node: K/3±52503  End Tag Table: Don't delete this page.