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.

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. "^_<number>".
      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.
      g. The TTYROL variable or "Scroll Count".
   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.

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.

 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 (see Quoting.).

In detail, the CALL function gives the job which owns the tty
(see TTY-owning.) 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.

 2. ENTERING STRANGE CHARACTERS - THE ESCAPE FUNCTION.

The ESCAPE function is requested by typing "BACK-NEXT" on TV's;
"^_", on other terminals, which have no "BACK-NEXT" key.  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 "^_".

  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".

  b. "^_<number>".

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".

  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, ^E, or ^F, followed by the basic ASCII character.
^B means "set the CONTROL bit"; ^C, the META bit; ^D, the TOP
bit; ^E, the SHIFT-LOCK bit; ^F, the SHIFT bit.  Any combination
of those five characters should be followed by the basic ASCII
character with which those bits will be OR'ed.  To specify one
of those five 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.

 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.

 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").

  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 <list of
terminals and users>" will be typed, where the <list> 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 <list>" 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 <list>" 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.

  b. Querying.

When the specified terminal is in query mode (see ^_Q.),
"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.

  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 <unlinking terminal>" is typed on each of them.

  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).

  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.

  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.

  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 (see Combits.).

 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.  See ".
^_<number>
	Enter the character whose ASCII code is <number>.
	  See nnn.
^_A	Set "accept mode".  See A.
^_B	Cause typeout to pause.  See B.
^_C	Communicate with another terminal.  See C.
^_D	Deferred Call.  See D.
^_E	Start or stop sending input to a slaved terminal.
	  See E.
^_I	Complement the input override flag (%TCICO).  See I.
^_K	Take some other terminal out of com link.  See K.
^_L	Clears the screen (echoes "^PC").
^_M	Complement **MORE** processing for job that has the tty.
	See M.
^_N	Leave com link or quit waiting for answer to query.
	See N.
^_O	Complement the output override flag (%TCOCO).  See O.
^_Q	Set "query mode" (%TCQRY).  See Q.
^_R	Set "refuse mode" (%TCRFS).  See R.
^_S	Slave a specified terminal.  See S.
^_U	Complement conversion of to upper case (%TOCLC).
	  See U.
^_Y	Say yes to a query.  See Y.
^_Z	Say no to a query.  See Z.
^_^	Complement scroll mode for job that has the tty.
	  See ^.

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.

 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.

 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 <chn>, specifies the inferior open on
channel <chn>.  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.

 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.

 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.

 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.

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.

 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 (see NoTTY.).
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.

 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 (see vars.)).

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).

  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.

  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.

  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.
	  See SCML.).

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").

 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 (see TTYSTS.), 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.

 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 (see Owner.).  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 (see NoTTY.).
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
(see Com.).

Input IOT's executed when the input buffer is empty will
normally wait until input is available (see Wait.).  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.

 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.

 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.

 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.

 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.

 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 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).

 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 5 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).
	%TXMTA	Indicates that the META key was held down.
	%TXCTL	Indicates that the CTRL key was held down.

Numerically, %TXTOP=4000, %TXMTA=400, and %TXCTL=200.  %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 and %TXMTA.

	%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, see Escape.)
	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.

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.

   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" - see Bits.).  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 (see NoTTY.).

 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).

  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.

   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.

   2: "^G".

"^G" is assumed to make a noise or other temporary indication,
occupy no space on the screen, and not move the cursor.

   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.

   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 (see Wrap.).

   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.

   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 (see Ctl.).
Not in echo mode, "^L" is treated like other random
control characters.

   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.

   8: Control-P.

"^P" is output like most other control characters (see Ctl.).
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.

   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.

   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.

  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.

  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.

   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.

   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.

 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.
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.  See More.
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.

 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".

  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.

  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.

 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.  See TTY Spec 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 (see Permit.).  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.

 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
(see SUPDUP.  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.
See SCPOS.

 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.

 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** (see More.) it will be unhung.

 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 (see Permit.).

 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.  See In-status.

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.

 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.

 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.

  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).

  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.

 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.

 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.

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.

 1. THE VARIABLES.

   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.
		 ;see Int.
%TGACT==2	;1 => characters in this group should activate.
		 ;see Act.
%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.
		 ;see Image 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.
		 ;see Echo.
%TGMPE==40	;1 => echo them at main program level
		 ;(that is, when they are .IOT'ed in).  See Echo.

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.

   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", and the meta bit outputs as "^B" or "beta".
		 ;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.
		;4.1 unused.
%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 (see Echo.).
%TSLCZ==000004	;3.3 1 => the last character typed in was "^Z".
		 ;If this bit is 1, .ATTY fails (see ATTY.).
%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).

   c. The Size of the Echo Area.

The vertical size of the echo area is a per-tty/per-job
variable.  See Echo area.

 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.

  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+<tty #>
		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.

  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.

  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.

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.

 1. THE VARIABLES.

  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.

  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 (see Out.).
%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 suchg 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.
		 ; see ITP.
%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.  See RSC.

  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).
		; see SUPDUP.
%TNTRM==10	;Terminet.
%TNESC==11	;Display using ASCII standard display codes.
%TNDTM==12	;A Datamedia 2500.

  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.

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

  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.

  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.

  g. The TTYSMT or "SMARTS" variable.

The TTYSMT variable is used to describe smart terminals.
It contains information on two 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
      terminal-independent graphics protocol.
      See Graphics (ITSDOC;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.

;The remainder of TTYSMT pertains to the graphics protocol.
;If %TQGPH is 0, it should all be 0.
%TQGPH==1	;3.1 Terminal understands the graphics protocol.
%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.

 2. SYSTEM CALLS.

  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.

  b. CNSGET.

This symbolic system call takes one argument specifying the tty
(like TTYGET's argument) and returns six values:
the vertical screen size,
the horizontal screen size,
the TCTYP variable,
the TTYCOM variable,
the TTYOPT variable,
the TTYTYP 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.

  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.

  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.

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.

 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.
See NH Out.  See NH In.
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 (see TDORS.).  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.

 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.

  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.

  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.

  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.

  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.

 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.

  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.

  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.

  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.

  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.

 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.

 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) (see TTYSTS 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.

 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.

 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.

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.

 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:

^\ <ch1> <ch2> where <ch1> is in {@, A, B, ..., _} and <ch2> is
	any character inputs the character (<ch1>&37)*200+<ch2>.
	That is, <ch1> supplies the 5 meta-bits for <ch2>.  The
	meta bits are (in their ultimate positions):

		%TXTOP	4000	"TOP" key on a TV
		%TXSFL	2000	"SHIFT LOCK" key on a TV (useless)
		%TXSFT	1000	"SHIFT" key on a TV (useless)
		%TXMTA	 400	"META"
		%TXCTL	 200	"CONTROL"

	The bits should appear in <ch1> 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.

 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 <buffer size>.

To stop using the allocation feature, just do ^\ ^I.

 3. OUTPUT-RESET.

If the TTY is a software-tty (see Soft.), 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.

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.

 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	Delete 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	Crlf (does an eol first).
%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.

 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 (see ITP.).  Sty
handlers should use the SCPOS system call (see SCPOS.).

%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.

 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
(see TTY spec.).
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 (see Permit.).