[its.git] / sysdoc / tv.100

Copyright (c) 1999 Massachusetts Institute of Technology

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
------------------------------

        A slightly revised TV-11 program is up and running.
There are the following features/changes:

SHIFT and SHIFT-LOCK no longer XOR.  The general reaction
        was against that feature, so it was removed.

[ESC]D  Buzzes the ninth-floor door for three seconds and
        then flashes your screen.  It works for free consoles
        as well.

[ESC]Q  Generates a hardcopy, as before, but the timeout is
        sixteen seconds, avoiding garbage output.

[ESC]L  Clears your screen.
          NOTE:  This is the same command as [ESC]I, which
                is retained for old times' sake for the 
                moment, but will be garbage-collected
                soon.
_______________________________________________________________

A. THE WHO-LINE.

The who-line is a line that appears at the bottom of the screen
on a TV terminal, describing the status of either the system as
a whole, or a particular job. In the former case, it is said
that the system who-line is being displayed; in the latter, the
user who-line. The information is updated every 5 seconds. The
who-line may be turned on or off, and various modes may be
selected, under either user or program control.

 1. WHAT APPEARS IN THE WHO-LINE.

  a. The User Who-line.

The user who-line begins with system status information:
the version number of ITS, the time of day and the date.
Then comes information on the job that is selected for who-line
display: the job number, the uname, jname and sname,
a "status" that says what the job is doing,
the percentage of the system's time that the job is running,
its total run time so far, and its core size in K.
An example of a user who-line is:

12/31/74 21:21:30 20 RMS    NT     .INFO. TTY    5% 0:03:09.2 24K RANDOM CRUFT

         ^time.      ^uname.       ^sname.       ^% runtime.  ^core size.
^date.            ^job #.   ^jname.       ^status.  ^job runtime. ^user-specified stuff.

  1: The Who-line Status.

STOP    means that the job has been stopped (presumably by its
         superior). This will be the case for jobs that have
         been ^Z'd.
RUN     for jobs that are running in user mode - that is,
         neither stopped nor executing a system call.
PAGE    means that the job is waiting to swap a page in.
<device>
        means that the job is executing an IOT (or SIOT) on that device.
        Appended to the name of the device may be the following
        characters:
                I       input.
                O       output.
                B       block mode.
                S       string mode.
        For example, DSKBI means block mode input from the disk.
<system call name>
        (for example, "OPEN", "CLOSE").
         means that the job is executing the system call named.

If the job is currently executing a system call (which implies
that the status is not RUN or STOP), a "+" will
appear in front of the status if the job is actually running, as
opposed to waiting (for buffer space, etc). 
Thus, "DSKBI" indicates that the job is waiting for a disk
transfer to take place, while "+DSKBI" indicates that it is
copying information out of a system disk buffer.

The user-specified part of the who-line is controlled by the
.WHO1, .WHO2 and .WHO3 variables of the job described by the
who-line. Those variables exist so that the program running can
show whatever internal status information it thinks the user might
want to know - what page of input is being processed, for example.
See the description of those variables in ITS USETS for details of
how to use them in a program.


  b. The System Who-line.

The items in the system who-line are as follows:

ITS XXX MM/DD/YY HH:MM:SS USERS RNBL/TJOB SWAPB PAGEW RCORE/UCORE FCORE

XXX             ITS version #
MM/DD/YY        today's date
HH:MM:SS        time of day
USERS           number of users logged in
RNBL            number of runnable jobs
TJOB            total number of ITS jobs
SWAPB           number of swap blocked jobs
PAGEW           number of jobs waiting for pages
RCORE           number of pages belonging to runnable jobs
UCORE           total number of pages in the system.
FCORE           number of user pages there is room for
                 in real core at one time.

In addition, if ITS is being debugged, the system who-line
will mention that fact.


 2. USER CONTROL OF WHO-LINES.

Currently, who-line control uses the [ESC]W command, interpreted
directly by the PDP11. When a command is given, it is not really
processed until the next time the who-lines are updated. The
issuing of a command triggers such updating immediately, even
if the normal time for updating has not arrived, but there may
be a delay nevertheless. In that case, a second command given
before the updating is done will overwrite the first.

 The options are:

[ESC]W          turns off the who-line.
[ESC]1W         selects the user who-line, migrating with the
                ownership of the tty. That is, each time the
                who-line is updated, it will describe whichever
                job has the tty at that moment.
                This is the default status.
[ESC]2W         freezes the who-line on whatever job was last
                shown. If you are about to ^Z - ^P a job but
                wish the who-line to continue to show that job
                instead of following the tty to its superior,
                this is the thing to do. The who-line remains
                frozen until the next time it is explicitly
                changed. If the job selected disappears, strange
                things may be displayed.
[ESC]3W         moves the who-line to a different job with
                the same uname as the one previously shown.
                Repeated use of this command will cycle through
                all the jobs with your uname. The who-line is
                left frozen on whichever job is reached.
[ESC]4W         moves similarly but in the other direction. That
                is, it will move back to the job that [ESC]3W
                left.
[ESC]5W         selects the system who-line.

[ESC]<n>U       selects the user wholine, for job number <n>.
                The job need not be part of your tree.


 3. PROGRAM CONTROL OF WHO-LINES.

  a. The Variables.

Two variables, WHMODE and WHJOB, contain the information
about which mode of who-line display is selected.
WHMODE is interpreted as follows:

-1      no who-line display.
0       user who-line, migrating with tty.
1       user who-line, frozen on a particular job
         whose job number is in WHJOB.
4       system who-line.

(2 and 3 are transitory states that occur while [ESC]3W or
[ESC]4W is waiting to be processed. [ESC]W actually works
by putting its argument plus 1 into WHMODE).

  b. System Calls.

The WHOLIN symbolic system call is used for reading and
writing the two variables WHMODE and WHJOB. Its first
argument specifies the tty to be used. The second and third
arguments are optional; if present, they will be used to set
WHMODE and WHJOB. In any case, two values are available:
the previous values of WHMODE and WHJOB.
If only one argument is given, the tty may be specified by
number, since it is not being modified. If two or three args
are given, the tty must be specified by a channel.
If the tty specified is not a TV, the call will fail with a
"wrong type device" error.

For example, to put the old values in FOO and FOO1, and
freeze the who-line on the job whose number is in BAR1:

        .CALL [ SETZ
                'WHOLIN
                1000,,TYIC      ;IMMEDIATE TTY CHANNEL ARGUMENT.
                1000,,1         ;NEW WHMODE = FREEZE ON JOB.
                BAR1            ;JOB TO LOOK AT.
                2000,,FOO       ;STORE OLD WHMODE.
                402000,,FOO1]   ;STORE OLD WHJOB.
         .VALUE
        ...

  c. Use of the TCTYP Program.

The TCTYP program when asked to describe a tty fully, or when
a tty's WHMODE is not -1, will print out "WHOLINE=" followed by
one plus the value of WHMODE (in other words, the argument to
[ESC]W needed to put the tty in the state it is in). The command
"WHOLINE" is also available; it takes an argument and acts like
[ESC]W, except that 1) it may be put in init files and valret
strings, while [ESC]W cannot, and 2) giving the WHOLINE command
an argument of 3 or 4 does not produce useful results.

Thus, if you like having a who-line,
:TCTYP WHOLINE 1
in your init file will give you one automatically.


B. FEATURES FOR PROCESSING WHAT IS ON A TV SCREEN.

What is sent to an ordinary terminal is unknowable to the
system unless specially remembered. That is not true
of TV terminals. Some standard facilities for processing
the contents of TV screens appear below. Of course, any
program may examine TV screens simply by mapping their
pages.

 1. THE HARD COPY PRINTER.

There exists a device for making a printed reproduction of
whatever appears on a TV screen. To use it, type [ESC]Q,
which causes one copy to be made immediately. If the device
is in use, the screen will flash and no action will be taken.
The process lasts 16 seconds; nothing prevents the screen from
changing during that period, and if such a thing happens the
results will be interesting.  When the copy is finished, the
screen will flash.  Thus [ESC]Q always flashes the screen,
but faster if you're losing.  If an infix argument is given as
for [ESC]S (see below), then the specified video input is copied.
This command can be used even on non-logged-in keyboards.

 2. RECORDINGS.

The system program RECORD will make an ascii file out of
whatever is on the TV screen. To use it, just type
RECORD^K at DDT. The file is called RECORD >
and goes on your default directory (the MSNAME).

Other more sophisticated programs for handling TV bit maps
may be found documented in AI:.INFO.;TVXGP INFO.

 3. SPYING.

When using a TV terminal, it is possible to spy on any other
TV terminal. This operates by routing a different video memory
through the video switch to your screen. Doing this does not
affect your programs in any way - their output continues to
be placed in your own video buffer and will be visible when
you stop spying. Also, spying does not affect the handling
of input in any way.
These commands can be used even on free keyboards.
[ESC]<n>S on free  keyboards, and [ESC]F on keyboards that are in use,
will time out after 40 seconds and an automatic [ESC]S will be done
to make the screen show its default picture once again.
Any character typed will make that happen prematurely.

The commands are:

[ESC]<n>S       begins spying. The number <n> should be the number
                of the terminal to spy on;  thus, [ESC]64S spies
                on TTY T64.  If the specified tty is not in use,
                the command is a no-op.
                <n> may also be 200 plus the number of a video buffer.
                This makes it possible to spy on a screen that nobody
                is currently using.
                <n> may also be a video switch input number,
                for those of you who are hardware hackers.

[ESC]S          stops spying. You are again viewing your own
                video buffer.

[ESC]F          spies on the video buffer used for logged-out consoles
                (this is the one with the useful information from
                the NAME dragon).

C. OTHER TV FEATURES.

 1. COMPLEMENTING THE SCREEN.

The last PDP-10 word of every display memory is used to hold
various information on how the contents of the memory should
be modified on their way to the screen. The 200000 bit of the
word controls complementation of the screen; if the bit is
on the screen appears black on white. This bit may be complemented
by the user with the command [ESC]C. Programs may, of course,
change the bit easily by accessing the display pages.

 2. CLEARING THE SCREEN COMPLETELY.

[ESC]L is guaranteed to clear every bit of the display memory,
and also reset the scroll-register (don't worry if you don't
understand that).  ^L usually does a good enough job, so this
command is hardly ever necessary.  If ^L doesn't clear the
screen (because a program has turned it off), ^_L will clear it.

 3. THE REPEAT KEY.

[ESC]R is the "repeat key";  it causes the previous input
character to be sent to the PDP-10 8 times a second, forever,
or until a character is typed on the keyboard (escape commands
not included).  The character that stops the repeat will be
ignored as input, unless it is CALL.

[ESC]<n>R, where <n> is an OCTAL number, will repeat the
previous input character <n> times (or until stopped by
the typing of a character).  <n> can't be more that 177 (octal).

 4.