1 BOSS
BOSS is an interactive job controller.  It lets you run several interactive
sessions at once. In order to run BOSS type

    BOSS

at the dollar prompt.

BOSS can operate in one of two modes:
* regular mode.  This works with any terminal.  See subtopic Description for
  an overview.
* multi-window mode; this ONLY works with a Macintosh running the UW terminal
  emulator.  See subtopic Windows for an overview and further details.
2 Description
BOSS lets you create up to 8 processes on a VAX/VMS system.  Each process is
identified by a single letter (A thru Z).  This letter is used in the
process name and in the DCL prompt.  At most one of these processes is
`current'.  What you type is sent to that process, and output from that
process is sent to your terminal.  A process which is not current can run
but normally cannot do output.  (What happens to the output is governed by
the output flag for a particular process.  See topic Output_flags.)  You
usually switch between processes by typing control-\ followed by the
identifying letter.  It is also possible to have have of your processes
initiate the switch.  (See topic Communicating.)

You can run any program under BOSS.  For example, you might
    run Emacs or EVE                   in process E
    SET HOST to another machine        in process H
    run NETTY to the B machine         in process B
    do a FORTRAN compilation           in process F
    execute DCL commands               in process D
    talk to your colleague using PHONE in process P
and so on.

Of course, you would normally not need to run so many processes.  (Indeed
your subprocess quota may only let you run 5 processes.)  When you are
through with a process, you should log out of it (with `logout') and switch
to some other process.

BOSS makes no attempt to keep track of what is on your screen.  Usually when
switching to a process which manages the screen in an advanced manner, you
should issue a command to the program to get it to re-draw the screen.
(This is control-w for EVE, PHONE, SPELL; control-l for Emacs.)

However, you can GET Boss to remember things on your screen by giving the
Control-J and control-I commands, which cause BOSS to remember what is typed
to your screen for the last 4000 characters and restore it when returning to
your process. You can also get BOSS to record output to a virtual terminal
in a file BOSS<n>.LOG (where <n> is the 1-character process name) with the
control-L command.

BOSS uses needs to know the escape sequences for clearing your screen, etc.
By default, it uses the VT100 sequences which work for a wide range of
terminals.  See topic Terminal_types.
2 Commands    
Usually, all commands to BOSS begin with the command character which by
default is C-\ (control-\).  The command character can be changed by using
the /COMMAND_CHARACTER qualifier to BOSS.  The command character is not
required when there is no current process (i.e., initially and immediately
after logging out of a process).  In that case the command character is
optional.

The commands are:

    C-h (or BS) Print command summary
    C-z     Quit (asking confirmation if there are processes)
    C-x     Quit after the last process has terminated
    a       Switch to process labeled A (and similarly with a thru z)
    A       Clear screen and then switch to process A
    C-n a   Create new process A as a subprocess (C-n A clears screen first)
    C-t a   Create process A at top level (C-t A clears screen first)
    C-k     Kill the current process (asks for confirmation)
    C-b     Buffer output for this process
    C-o     Discard output for this process
    C-p     Print output from this process
    C-w     Stop output from this process
    C-i     Toggle buffering active output
    C-j     Toggle keeping buffer for more than 1
                process transition
    C-l (ell) Toggle logging to BOSSn.LOG. Separate logfiles to
                each process are kept and logging is of what is
                sent to the pseudoterminal, not the real one, so
                you can log a process that is in discard-output mode.
    C-v       Toggle logging to BOSSn.LOG. Similar to C-L except
		that C-L logging suspends the logfile write when
		toggled off again, and C-V logging closes the log
		file when toggled off.
    C-e     Toggle logging. This is similar to C-l except that it
    		closes the logfile when it stops logging. Thus you
		can use C-l when you need to log several items but
		want to skip the material between, keeping all the
		logged data in one file. Use control-E to log a bit
		of a session which you can then examine in a second
		session, without having to leave BOSS. Note that
		logging must be on to close the file.
    C-g n   Allows saving of n lines of buffered output (needs to be
                in C-i C-j mode) and replaying them into the next
                process you switch to, enabling cut/paste.
    +	    Enter command mode for one line
    ?       List processes and output flags
             (* means current, +/- means waiting for output)
    C-\     Sends the command character to the current process
    DEL     Do nothing
    other   Sound the bell on the terminal

  Command mode allows one command to be entered. This is done with a
normal $QIOW, so should be used for setup, as it may cause character
ASTs to be lost if used in heavy activity. A number of commands are
supported, short to minimize time needed to enter them:

  Schars  Sets current process to get chars (up to 7 of them)
	when the process is switched to. A common use will be
	S^W, where "^W" means the control-W character, which
	gets many fullscreen applications to repaint the screen.
  Gchars  Like Schars but sets the prefix for all processes. The
	prefix is initially nonexistent.
  Enumber  Causes the terminal buffer to only write "number" characters
	to the screen on a process switch where ^I and ^J modes
	are active. Otherwise the entire saved buffer is dumped
	on each switch, which may be more than is desired. The
	value is clamped between 100 and the buffer size. Enumber
	affects only the current process.
  Gnumber  Like Enumber, but resets the output size for all processes.

	The Enumber and Gnumber commands are designed to allow one to
	buffer a large number of characters, but only display a
	smaller number on context switches. Reissuing the commands
	with a larger value of "number" will allow the rest to be
	seen. Also, if ^I^J mode is not in use, the entire buffer
	is displayed as was the case in earlier versions of BOSS.

2 Qualifiers
When starting BOSS you can provide the following qualifiers:

/COMMAND_CHARACTER
 /COMMAND_CHARACTER=num
 Default: /COMMAND_CHARACTER=%O34 (i.e., C-\)

Use the character whose ASCII code is num as the command character instead
of C-\.  E.g.,
  BOSS/COMMAND_CHARACTER=%X1F   ! set command character to C-_
  BOSS/COMMAND_CHARACTER=%O37                   ! the same
  BOSS/COMMAND_CHARACTER=31                     ! the same
  BOSS/COMMAND_CHARACTER='F$CVSI(0,6,"_")'      ! the same
  BOSS/COMMAND_CHARACTER='F$CVSI(0,8,"`")'      ! set to ` (backquote)
Repeating the command character twice sends the character to the current
process.  C-z is disallowed as a command character since otherwise you
wouldn't be able to quit.

/START_PROCESS
 /START_PROCESS=(process-1,process-2,...)

BOSS immediately starts up the specified processes.  E.g.,
  BOSS/START_PROCESS=A
starts process A.  You are left in the last process specified; e.g.,
  BOSS/START_PROCESS=(E,D)
starts E and D and sets D to be the current process

/STUFF_STRING
 /STUFF_STRING=(string-1,string-2,...)

This qualifier is processed in parallel with /START_PROCESS.  string-n is
sent the process-n when it is started.  A carriage return is added to the
string unless the string is empty.  If the /STUFF_STRING list is shorter
than the /START_PROCESS list, then nothing is sent to the remaining
processes.  E.g.,
  BOSS/START=(E,D)/STUFF=EMACS
starts process E runs Emacs in it.  Then BOSS starts process D (and sends
nothing to it).  To send more than one command to a process, you can do,
e.g.,
  BOSS/START=(B,B)/STUFF=("SHOW TIME",FINGER)
which start process B and sends runs both SHOW TIME and FINGER.  (Or else
you can construct a DCL string with an imbedded carriage return.

/AUTO_STUFF_STRING
 /AUTO_STUFF_STRING=string

This specifies a string to stuff into each newly created subprocess.  A
carriage return is added to the string unless the string is empty.  This
gets sent to the subprocess before the strings specified by /STUFF_STRING
or BOSS$STUFF.  Top-level processes are unaffected by this qualifier.
There are three applications where this would be useful.  (1) If BOSS is
not installed with PHY_IO privilege (so that subprocesses don't
automatically inherit the parents terminal type), then use, e.g.,
  BOSS/AUTO_STUFF="SET TERM/VT100"
(2) If you are a privileged used and you want to be able to select any of
your authorized privileges in each subprocess, but you don't want them
turned on by default, then use
  $ DEFPRIV = F$GETJPI("","PROCPRIV")
  $ SET PROCESS/PRIV=ALL
  $ BOSS/AUTO_STUFF="SET PROCESS/PRIV=(NOALL,''DEFPRIV')"
This way each subprocess will have your standard set of current and
authorized privileges.  (Note that the authorized privileges for a
subprocess are set from the current privileges of its parent.)
(3) You want to turn off some classes of broadcasts in subprocesses.
  BOSS/AUTO_STUFF="SET BROAD=NOSHUTDOWN"
You will normally still receive such broadcasts when BOSS re-broadcasts
the broadcasts it receives to the current process.  However, you will only
receive one copy of each broadcast.  See also subtopic Broadcasts.

/OUTPUT_FLAGS
 /OUTPUT_FLAGS=(flag-1,flag-2,...)  flag-n is one of b, o, w, p

This qualifier is processed in parallel with /START_PROCESS.  The output
flag for process-n is set to flag-n.  If the /OUTPUT_FLAGS list is shorter
than the /START_PROCESS list, then the output flags for the remaining
processes are set to the default.

/DEFAULT_OUTPUT_FLAG
 /DEFAULT_OUTPUT_FLAG=flag (one of b, o, w, p)
 Default: /DEFAULT_OUTPUT_FLAG=b

This sets the default output flag.  See topic Output_flags.

/BEGIN_PROMPT
 /BEGIN_PROMPT=string
 Default: /NOBEGIN_PROMPT

This specifies the part of the DCL prompt which appears before the process
label.  E.g.,
  BOSS/BEGIN_PROMPT="--"/END_PROMPT=">> "
gives you DCL prompts of the form "--Q>> ".

/END_PROMPT
 /END_PROMPT=string
 Default: /END_PROMPT="> "

This specifies the part of the DCL prompt which appears after the process
label.

/SWITCH_CREATE
 /SWITCH_CREATE
 Default: /NOSWITCH_CREATE

By default, you have to create a process with either C-\ C-n x or C-\ C-t
x.  If /SWITCH_CREATE is set, then switching to nonexistent process
creates it as a subprocess.  (I.e., C-\ x is equivalent to C-\ C-n x).  If
you always want /SWITCH_CREATE set, then put
    $ setup boss
    $ boss == "''boss'/switch_create"
into your LOGIN.COM file.

/PROCESS_DEFAULT
 /PROCESS_DEFAULT=process-type (one of SUBPROCESS and TOP_LEVEL)
 Default: /PROCESS_DEFAULT=SUBPROCESS

This governs the types of the processes created by /START_PROCESS, process
switching initiated by BOSS$SWITCH.  (I.e., all process creation except for
via C-\ C-n x and C-\ C-t x.)

/FLOW_CONTROL
 /FLOW_CONTROL
 Default: /NOFLOW_CONTROL

Normally, everything you type is passed on to the current process.  This
includes the flow-control characters control-s and control-q.  This results
in some delay in these characters being acted upon.  Your terminal may
therefore receive many additional characters after a C-s is typed, causing
you to lose information off the top of your screen or your terminal's input
buffer to overflow.  With
    BOSS/FLOW_CONTROL
C-s and C-q are intercepted by the terminal driver and used as flow-
control.  This cause C-s to be acted on more promptly.  The drawback is
that you can never send C-s and C-q to your program.  This breaks certain
programs, notably Emacs, which need to be able to receive all the ASCII
characters.  A second drawback is that once the output is stopped with C-s,
only a C-q can get it going again.  You can't interrupt it with a C-y as
you can normally.  (This is because BOSS/FLOW_CONTROL only treats C-s and
C-q as special.  C-y and C-c are treated as ordinary characters.)

/DELETE_CHARACTER
 /DELETE_CHARACTER=num
 Default: /DELETE_CHARACTER=%O177 (i.e., DEL)

Use the character whose ASCII code is num as the delete character instead
of DEL.  This is useful on some terminals with weird keyboards.  E.g., on
some ADM terminals, the delete key is shift-underscore.  If you do
  BOSS/DELETE_CHARACTER='F$CVSI(0,8,"_")'
then underscore and delete are interchanged.  (I.e., the underscore key
sends a delete to your program, and the shift-underscore key sends an
underscore to your program.)

/UW
 /UW
 Default: /NOUW

Enter BOSS in multi-window mode.  You must be running the UW multi-window
terminal emulator on a Macintosh computer.  See topic Windows for more
information.

/RECORD
 /RECORD[=filespec]
 Default: /RECORD=boss.record

Generate a file (boss.record by default) containing the keystrokes entered
at the physical terminal, interspersed with timing information for later
playback.
 
The timing is recorded as delay specifications of the form \<n><newline>,
where <n> is the delay in 100 millisecond units, and <newline> is a linefeed
character (hex 0A). Delays between keypresses that are less than a certain
threshold (currently 0.3 sec) will not be recorded. A "\" occurring as
normal character will be written to the session record file as "\\".

/PLAYBACK
 /PLAYBACK[=filespec]
 Default: /PLAYBACK=boss.record
 
Playback a previously recorded session, see /RECORD.  Upon reaching the end
of the record file, Boss will switch from playback to interactive mode. The
switch to interactive will also happen if there is keyboard input, but see
the /LOCK qualifier for a way to prevent this.

NB: in order to duplicate exactly the environment in which the session
    is played back, you must make sure that Boss is started with the
    same qualifiers as during recording, except for the playback
    specific ones of course.

See also /GEAR to change the speed with which the session is replayed.

/GEAR
 /GEAR=I[nfinite]     or
 /GEAR=<real-value>
 Default: /GEAR=1.0

Use /GEAR with the playback mode to speed up (or slow down) the replay.  The
specified <real-value> will be used as a multiplier for the delay specifiers
encountered in the session record file. The default <real-value> is 1.0,
i.e. playback in real time. The value must be positive; specifying
I[nfinite] will have the effect that delays are ignored completely.
 
/LOCK
 /LOCK
 Default: /NOLOCK

Lock the keyboard during a playback session. At the end of the record file,
the keyboard will be unlocked.
 
You will need this if the applications that run issue commands to the
terminal that cause the terminal to respond all by itself, for instance a
'set terminal/inquire' on DCL level, or if you don't want the user to
interfere with a playback session.  In the absence of /LOCK, boss will
terminate a playback session and switch to interactive mode as soon as it
receives data from the physical terminal.

/QUIT_ON_IDLE
 /QUIT_ON_IDLE
 Default: /NOQUIT_ON_IDLE
 
 Perform an automatic quit if there are no more processes active. This is
 the equivalent of the control-x command (help topic "Commands").

/LOG
 /LOG=<log-file-prefix>
 Default: /LOG=BOSS

Make logging the default action when creating processes. See the description
of the control-l command (help topic "Commands").  If the optional
<log-file-prefix> is given, used that as the first part of the log file
name, else use the string "BOSS" instead.  The log file name will consist of
this prefix, followed by a 1-character name of the process and the string
".LOG".
2 Terminal_types
When switching processes, BOSS tries either to clear the screen or to move
to the bottom of the screen.  By default, it uses VT100 escape sequences for
these operations.  However, if you define the logical name BOSS$TERM to be
the name of some other terminal, then it will use the escape sequence for
that terminal.

E.g., if you're using an ADM3A terminal, you should do
    $ DEFINE/NOLOG BOSS$TERM ADM3A
before starting BOSS.  (ADM3A users would probably also want to set the
delete character to underscore.  See topic /DELETE_CHARACTER.)

At present BOSS only knows about three types of terminals: VT100, VT52,
ADM3A, and UNKNOWN.  The last choice makes minimal assumptions about the
terminal, and should always give a reasonable display.
2 Process_types
BOSS deals with two types of processes: subprocesses and top-level
processes.

Subprocesses are what you get with the DCL command SPAWN.  They inherit
symbols and logical names from the parent process (i.e., BOSS itself) at
creation time.  The resources it uses count against the parent's quotas.
The number of subprocesses is governed by your subprocess quota.
Subprocesses share the job logical name with the parent process.  This gives
a way for subprocesses to communicate with one another and with their
parent.

Top-level processes acts just like an entirely new login session (as though
you had done SET HOST 0).  Indeed, you have to log in to get the process
going.  The resources that such processes use do not count against the
parent's quotas.  SHOW USERS will show that you are logged in multiple
times.

Which type of process should you use?

In most cases subprocesses are best.  These usually are quicker to get
started (since you don't have to go through the login procedure again).
BOSS is able to set the process name and DCL prompt to include the process
label.  Synchronous switching to another process from a subprocess is
possible using the BOSS$SWITCH and BOSS$STUFF job logical names.

When should you use a top-level process?  Here are some cases:
* You need to log in as someone else.
* You need to run a large program that uses all of one of your quotas.
* You need to run with a different CLI. Log in with e.g., /CLI=SHELL.
* Your subprocess quota is too low to allow you to create subprocesses.

Type C-\ C-n a to start subprocess A; type C-\ C-t b to start top-level
process B.
2 Output_flags
Each process has an output flag which may be set by C-\ followed by one of
C-b, C-o, C-p, or C-w (this sets the flag to b, o, p, or w, resp.).  This
flag governs what BOSS does to the output of a process which is not current.
(The current process always gets its output displayed immediately.)  The
meanings of these settings are

 b  Buffer output for this process.  Output is saved in a 4k buffer.  Buffer
    is output when the process becomes current.  The process hangs when this
    buffer fills.  This is useful for running a program which dribbles
    output which you do not want to lose.  In the process list (obtained by
    C-\ ?), a - indicates that there is output ready to be displayed, and a
    + indicates that the buffer is full (and the process is probably
    hanging).

 o  Discard output for this process.  Only the most recent write will by
    output when the process becomes current.  This is useful for running a
    program which periodically outputs some straightforward information such
    as `Processing record 103', where all you care about is the most recent
    output.  In the process list, + means that there is output available
    (but the process is continuing to run).

 p  Print output from this process.  Output is output to the terminal
    regardless of whether this is the current process or not.  This is
    useful if you need to be informed when a program completes.  Also it can
    be used to display status information periodically on your screen (see
    subtopic Examples).

 w  Stop output from this process.  The process can do a single write which
    will be accepted and saved by BOSS.  The process will then hang when it
    attempts to do the next write.  In the process list + means that there
    is output available (and the process is probably hanging).

The default output flag is b.  The default can be changed by using the
DEFAULT_OUTPUT_FLAG qualifier or by issuing one of the flag setting commands
when there is no current process (i.e., immediately after starting BOSS or
after logging out of a process).

The best setting of the output flag very much depends on your application.
You will probably find the best setting to be b (the default).  If one
process is attempting to act synchronously with another, it may be necessary
to set their output flags to w.  However, if your synchronous switches are
all performed via the BOSS$SWITCH mechanism, this isn't necessary since BOSS
temporarily sets the output flag to w on these types of process switches
(see topic Communicating).

A potential problem with the b setting is that BOSS empties the buffer to
your terminal in a single operation.  This may overflow your terminal's
input buffer (this is not a problem with a Mac running VersaTerm at 9600
baud).  This is not a problem if BOSS is used with the /FLOW_CONTROL
qualifier (assuming that your terminal does flow control).
3 Examples
Suppose TIME.COM contains:
    $ esc[0,8]=27
    $ sc = esc + "7"                    ! Save cursor
    $ rc = esc + "8"                    ! Restore cursor
    $ home = esc + "[;76H"              ! cursor to top right of screen
    $ invert = esc + "[7m"              ! inverse video
    $ revert = esc + "[m"               ! normal
    $10$:
    $ time = sc+home+invert+f$extract(12,5,f$time())+revert+rc
    $ read/prompt="''time'"/end=43$/error=42$/time_out=0 sys$command dummy
    $42$:
    $ wait  ::5
    $ goto 10$
    $43$:

This displays the time at 5 second intervals in the top right corner of
the screen.  If this is running in a process whose output flag is p, the
time will displayed while in other processes.
2 Communicating
BOSS and the subprocesses under it can communicate via logical names.  These
only work for BOSS's subprocesses, not for its top-level processes (because
only the subprocesses share the job logical name table with BOSS).  The
following are recognized:

BOSS$ID (in process table);  BOSS defines this as the identifying letter of
the process.  This can be used in tailoring the DCL prompt etc.;  e.g.,
    $ set prompt "boss-''f$trnlnm("boss$id")'>"
It can also be used to indicate to a program that it is running under BOSS.

BOSS$SWITCH (in job table); whenever BOSS is writes output to the real
terminal, it checks whether BOSS$SWITCH is defined.  If it's defined as a
single letter, BOSS will switch to that process and delete the logical name.
If the process doesn't exist it is created as a subprocess.  Thus a DCL
procedure can initiate a switch to process G with
    $ define/job boss$switch g
    $ write sys$error ""        ! do some output to make BOSS wake up
The switch takes place synchronously by setting the output flag for the
originating process to w temporarily (see topic Output_flags).  Both
BOSS$SWITCH and BOSS$STUFF should be defined as supervisor mode logical
names in the job table.  They may be defined from programs with e.g.,
    status:=lib$set_logical('BOSS$SWITCH','D','LNM$JOB');

BOSS$STUFF (in job table); whenever a BOSS makes a process initiated switch.
It stuffs the definition of BOSS$STUFF into the input stream of the process
being switched to.  After being used, BOSS$STUFF is deleted.
3 Examples
The following command procedure will do a SHO DEF and leave SHO DEF in the
recall buffer:
    $ cr[0,8] = 13
    $ define/job boss$stuff "sho def''cr'"
    $ define/job boss$switch 'f$trnlnm("boss$id")'

Here's how to switch to process F and have the present job continue
running:
    $ define/job boss$switch f
    $ char[0,8] = 22                    ! control-V
    $ gosub out_char
    $ return
    $!
    $out_char:                          ! Spit out the character
    $ read/prompt='char'/end=40$/error=40$/time_out=0 sys$command dummy
    $40$: return

If you want the present process to wait, then repeat the `gosub out_char'
three times.

Return paths may be implemented via additional logical names.  E.g., the
procedure that runs Emacs under BOSS does the following.

If Emacs isn't running (boss$emacs undefined) do
    $ define/job boss$emacs 'f$trnlnm("boss$id")'
and start Emacs.

If Emacs is running (boss$emacs defined) do
    $ define/job boss$return_switch 'f$trnlnm("boss$id")'
    $ define/job boss$switch 'f$trnlnm("boss$emacs","lnm$job")'
    $ gosub out_char
    $ gosub out_char
    $ gosub out_char

The suspend-emacs function in Emacs is redefined to do the equivalent of
    $ define/job boss$switch 'f$trnlnm("boss$return_switch","lnm$job")'
    $ deassign/job boss$return_switch
    ...

Similarly boss$return_stuff may be used as the string to stuff into the
process on return.  The edit procedure that is called on a TeX error may
set this to the current TeX command line so that on exiting from the
editor the user has the input buffer prepared with the command to re-run
TeX.  The user then has the option either of accepting the command (by
typing return) or cancelling it (with C-u).
2 Logging
To save what gets sent to a process in a file, one can use the C-l toggle to
toggle creation of a logfile.  These files are named BOSSn.LOG (in the
directory where one was at the time of running BOSS, since they are created
by the BOSS process), where n is the internal BOSS process number (0 to n,
where the number is the process slot; usually this corresponds to the order
of process creation).  Whatever goes to the process as console output is
logged, even if BOSS is discarding terminal output from that process; the
file output is extracted (as a stream-LF file) prior to the BOSS decisions
on what to do with the text.  A C-e will close the file, and a new C-L or C-e
will open a new version, and so on.  This can be very convenient for
allowing an editor in another process to look over the log file.
Note that C-L and C-E both toggle logging. The difference is that C-L
does not close the logfile, just suspends output to it, while C-E
closes the logfile so that a new version can be created and the version
just created can be examined without having to leave BOSS (or exit the
process that was being logged).
2 Redisplay
C-i toggles a buffer capture mode.  Its function is to save all output to a
session in the BOSS internal buffer (just using it as a circular buffer)
even if the output is also going to the terminal.  Then upon switching out
of that session and coming back in, the entire BOSS buffer gets played back.
The net effect of this is that material that may have scrolled off the
screen or been lost due to fullscreen operations of another process gets put
back, in effect recreating the screen corresponding to the process that had
its control removed.

Due to internal logic, the C-i toggle will allow this playback to occur once
and delete the material, so that what gets saved and played back is what was
written during the current session on the screen.  That is, if I have
processes A and B and have process A in C-i mode then a screen session might
look (very schematically) like this:

    [in process A]
    foo bar
    mumble 
    random messup
    editing
    random commands
    [Switch to process B]
    random other messup
    [Switch to process A]
    foo bar
    mumble 
    random messup
    editing
    random commands
    more stuff typed to process A
    and so on
    [Switch to process B]
    other process B stuff
    [Switch to process A]
    more stuff typed to process A
    and so on
    newer still process A commands

Note that the initial "foo bar" and so on commands were played back only
once.

If it is desired to keep ALL the text as long as possible, an additional
mode (which I called "multishot buffering" for no particularly good reason)
can be toggled by C-j (linefeed) after the C-\ character.  In this mode, all
of the process A commands that will fit in the BOSS save buffer are kept as
long as possible.  (Note the BOSS buffer is not really used circularly; text
is moved up as new text gets added once the buffer fills.)  Thus, to buffer
text and keep it forever one needs C-i to turn on the buffering AND C-j to
keep the text as long as possible.  Since the BOSS buffer defaults to 4096
characters this will generally completely recreate whatever was on screen.
2 Paste
A very limited (and rather kludgey) cut and paste facility exists in that,
IF BOSS is saving output from a process in its buffer (i.e., at least C-i
mode is active), BOSS can be told to save off the last "n" lines of this
saved output from the current process.  These are played back into the next
process one switches to as though they had been typed in.  Clearly this is
not rectangular, allows no editing (unless the lines are pulled into an
editor running separately in another process and then pulled to a third
process), and will often not do what one wants.  Hokey as it is, though, it
could be of some limited value, usually for transferring text to an editor.
The number of such lines of text is limited by an internal BOSS compile time
parameter which is in the range of 10 to 20 lines normally; this is to
prevent unlimited garbage from being transferred and to recognize that the
transfer may fail if type-ahead is not sufficient.  In general BOSS works
better with large typeahead set in SYSGEN; I have it set to 1024 on our
system, which also aids asynchronous file transfer schemes by avoiding
character loss.  I recommend this also for cases where memory is not too
tight, to avoid lots of potential synchronization issues with the pty
drivers.
2 Broadcasts    
When running running under BOSS, there is the potential that you will
receive multiple copies of the same broadcast.  In order to understand what
is going on, it is useful to distinguish 3 types of broadcast messages:

(1) Broadcasts to a specific process.  E.g., the response of the system to
control-t.  These typically are sent to one of the processes under BOSS.

(2) Broadcasts to top-level processes.  E.g., mail notification.  These are
typically sent to the process running BOSS and any top-level processes
under BOSS.

(3) Broadcasts to all terminals (including pseudo terminals).  E.g.,
shutdown messages.  These are typically sent to the process running BOSS and
all processes under BOSS.

In order to help manage broadcast messages, BOSS intercepts any broadcasts
sent to the process running BOSS, and rebroadcasts them to the current
process.  The rebroadcasts are of type USER16.  This allows you to shut
these rebroadcast out with SET BROAD=NONE or SET BROAD=NOUSER16.  Control-s
also works to defer broadcasts.  Any broadcast handlers which the current
process has active will be called to process the broadcast.

In order to avoid getting multiple copies of the same broadcast, here's what
you should do:

In each subprocess under BOSS, disable type 3 broadcasts, i.e., do
    SET BROADCAST=NOSHUTDOWN    ! plus others maybe?
You can accomplish this automatically with the /AUTO_STUFF_STRING qualifier
to BOSS.

In each top-level process, disable type 2 and 3 broadcasts, i.e., do
    SET BROADCAST=(NOSHUTDOWN,NOMAIL,NOQUEUE,NOPHONE)   ! plus others?
This assumes that you are logged into the top-level process under the same
username.  If using a different username, then you wouldn't want to disable
most (all?) of the type 2 broadcasts.  For example, we would want to permit
mail notification.

In order to stop broadcasts to a particular process, do
    SET BROADCAST=NONE

There are some drawbacks with way BOSS rebroadcasts messages:

* There is no way of determining the original type of the broadcast was
(MAIL, PHONE, etc.).  For this reason, BOSS rebroadcasts everything as
USER16.

* If the rebroadcast fails, because the current process has broadcasts
disabled, then there is no way of getting this information to the original
sender.  E.g., if you SET BROAD=NONE is a process under BOSS and someone
tries to PHONE you, he will not be notified that you're not getting his
connection requests.
2 Playback
With the aid of the /RECORD and /PLAYBACK qualifiers it is possible to let
BOSS replay a session for you. However, this is a crude and rather limited
facility.

In particular, you should be aware of the following when executing a
playback.

It's easy for BOSS to overflow the pseudoterminal with data from the record
file. This may be expected to happen if you select a high /GEAR value of
course, or if you edit a record file and change the delay specifiers. But
even if the system load is a bit higher during playback than it was when the
session was recorded, you may get into trouble.
  
Problems manifest themselves in several ways:
  - BOSS feeds more data to the pseudoterminal than will fit in the typeahead
    buffer. In this case you will get DATAOVERUN warning messages on your
    terminal, and some characters will be lost.
    This problem may perhaps be solved in the future when BOSS learns how
    to handle thse overflow conditions properly.
  - Commands for BOSS in the record stream may get acted upon before the
    current process has completed processing its data. For example, a
    process switch may be executed by BOSS, when the current process is
    still active processing the data in its typeahead buffer.
  - Applications run in one of the processes controlled by BOSS may decide
    to throw away typeahead. If the timing is different, this may happen at
    another place in the input stream than during recording.
2 New_features
(1.7) Incompatible change: C-\ C-n x required to create a new process.  Use
BOSS/SWITCH_CREATE to get the old behavior (where C-\ x would create process
X if it doesn't exist).

(1.7) C-\ C-t x creates a process at top level.  See topic Process_types.

(1.8) BOSS accepts various qualifiers when it starts.  These control the
command character, DCL prompt string, etc.  They also can be used to tell
BOSS to start various processes.  See topic Qualifiers.

(1.9) Broadcast messages sent to the process running BOSS are trapped and
rebroadcast to the current process.  See topic Broadcasts.

(2.0) /DELETE_CHARACTER=num added to allow interchange of some character
with delete.  See topic /DELETE_CHARACTER.

(2.1) Logical name BOSS$TERM looked at to determine terminal type.  See
topic Terminal_types.

(2.2) BOSS fixed to work with new release of pseudo TTY drivers.

(2.4) /FLOW_CONTROL added to allow flow control by the top-level process.
See topic /FLOW_CONTROL.

(2.5) /PROCESS_DEFAULT=process-type added to get top-level processes
created by default.  See topic /PROCESS_DEFAULT

(2.5) C-\ C-k kills the current process.

(2.5) BOSS/UW acts as a server for the multi-window Macintosh terminal
emulator UW.  See topic Windows.

(3.0) File logging (topic Logging), screen redisplay (topic Redisplay), and
inter-process paste facility (topic Paste) added.  These features are due to
Glenn Everhart.

(3.1) Added record and playback facilities.
Qualifiers:
 /record[=filespec]     default: boss.record
 /playback[=filespec]   default: boss.record
 /gear=<f>              <f> is speedup factor for playback; default 1.0
 /lock                  ignore keyboard input during playback
The record file will contain the keystrokes from the physical terminal,
see the description of these qualifiers.
Added ^\^x to request an exit after all processes have terminated.
Added /quit_on_idle to perform the same function from the command line.
Added /log to set the default action to logging when creating a process,
 and optionally supply a prefix for the log-filename (def:"BOSS").
Do not close the logfile when logging is stopped, but at quit time.
Use the process name for the log filename iso a number.
  
(4.1) Updated for DEC's PTD pseudo TTY drivers.

(4.2) Added C-e toggle to allow logfiles to be closed when user wants.
	Fixed wrong lack of setup of log prefix filename.
(4.4) Changes to BOSS.C to minimize window switching when using the
        UW protocol.
(4.9) Port to Alpha AXP.

2 Bugs
BOSS does single character input.  This is rather slow.  Don't expect it to
be able to keep up with lots of data coming from the terminal.

The output on some terminals (Visual 550s in particular) at 9600 baud may
have glitches in it.  This is because these terminals need flow control
enabled to operate at 9600 baud, but BOSS doesn't react quickly enough to
the control-s sent by the terminal.  The solution is to run at 4800 baud or
slower or to use the FLOW_CONTROL qualifier to BOSS.

I have seen various strange bugs occurring when using BOSS.  These are all
associated with VMS running out of some quota.  The symptoms range from BOSS
hanging while creating a process (because LIB$SPAWN does not return) to
SYS$LIBRARY being mis-translated by LINK.  As far as I can tell these
problems occur only because of the additional stress multiple running jobs
puts on a users quota's and not because of BOSS problems per se.  The
culprits is usually BYTLM (8000 is too low, 40000 is OK).  However PGFLQUO
is another quota to check.

Output gets garbled when using BOSS via SET HOST (i.e., SET HOST followed by
BOSS).  This happens when you type while output is coming to your terminal.
The symptom is that the lines come out in the wrong order.  It's OK to use
SET HOST while in BOSS (i.e., BOSS followed by SET HOST).

I know of one program SMP (an algebra system) that grabs the entire PGFLQUO
on startup.  This obviously interfers with BOSS's other processes.  The
solution is to use a top-level process to run SMP (see topic Process_types).

PC file transfer using the XMODEM protocol (e.g., with MACX) doesn't work
through BOSS.  Kermit seems to work fine.

Attempting to attach to the process running BOSS from one of its
subprocesses causes a hangage.

Control-\ is used by the Switcher program on the Macintosh.  If you are
running your terminal emulation program under Switcher, you need to check
`Disable keyboard switching' in the Options menu item in Switcher.
Alternatively you can select a different command character with the
COMMAND_CHARACTER qualifier.

When you run /PLAYBACK, and there is no auto_stuff_string, the first
character sent to a newly created process is not echoed to your terminal; if
logging is active however, the character will show up in the logfile.
2 Windows    
If you are running the UW multi-window Macintosh terminal emulator or the
Meshugena Term Amiga VT200 series terminal emulator, then you can run BOSS
with

    $ BOSS/UW

and take advantage of a multi-window environment for communicating with the
VAX.  (UW stands for Unix Windows.)

Up to seven processes can be run.  Each process is identified by a single
digit 1 thru 7.  This digit is used in the process name and in the DCL
prompt.  Each process is associated with its own window, named Window #1,
etc., although the names can be changed within UW.

Before you run BOSS/UW, the UW terminal emulator will be operating in
single-window mode.  When you start BOSS/UW, this window will close.

DON'T run BOSS/UW if you're not using the UW software on the Macintosh or
one of the UW-speaking terminal emulators on the Amiga!

You create a window and associated VAX process by selecting New in the
Windows menu.

You can select a window by clicking on it (if a portion of it is visible),
typing command-1 thru command-7 (for windows 1 thru 7), or by selecting Open
in the Windows menu.

You can close a window by clicking on its close box or by selecting Close in
the Windows menu.  The associated VAX process remains running.  You can view
the output at a later time by selecting the window.

When you log out of a process, the window disappears.

Selecting Shutdown from the File menu causes BOSS to exit and UW to return
to single window operation.

Finally, UW also supports Option as a Meta key and high-level mouse support.
Both these are useful in Emacs.  See subtopic Emacs.

WARNING: UW is a less capable terminal emulator than VersaTerm.  Don't
expect too much of it!  It does however support multiple windows to
different processes; the lack of this in VersaTerm is its principle defect.
3 Configuration
Read the MacWrite documentation on UW for more information.

In UW you can set both the default Window configuration used when a new
process is created (Configure menu) and the configuration of the active
window (Settings in the Window menu).

I suggest the following default configuration:

  (a) Serial Port: set Flow control on
  (b) Protocol: set to "Original UW protocol"
  (c) Keyboard: set "META key"
  (d) Window Defaults: set "ANSI"
      (d') Set TTY Defaults: set "Mouse Action" to "Clipboard"

Save this configuration as uw.conf. (Then you don't need to repeat it each
time you start up.)
3 UW_availability
UW is available in the <INFO-MAC> area at SUMEX.STANFORD.EDU.  It's in
Unix shar format in files UNIX-UW-42-PART%.SHAR (PART1 thru PART8).

At a minimum you need the UW terminal emulator and (if you have Emacs
users) MACMOUSE.EL.

At PPL, the terminal emulator and documentation are in
    MAC$:[NEW]UNIX-UW-42.HQX
(in BinHex format).  MACMOUSE.EL is in the default library area for Emacs,
EMACS_LIBRARY:[LISP].
3 Emacs
In order to run Gnu Emacs under UW, you need to set you Emacs terminal
type to "uw", with e.g.,
    $ setup emacs uw

The option key acts as a Meta-shift.  Thus Option-F is the same as ESC F
(i.e., goes forward a word).

You should set UW to transmit the location of Mouse clicks to the VAX (in
Configure TTY under Settings in the Window menu).  This gets the mouse
click transmitted to the VAX for this window only.  To get Emacs to
understand what UW sends, insert

    (global-set-key "\em" 'move-mac-cursor)
    (autoload 'move-mac-cursor "macmouse" nil t)

into your Emacs init file (sys$login:.emacs).

Here's what happens with mouse clicks:

 Up or down mouse button in a window selects that window

 A scroll bar/thumbing area for each window with the following features:
      the mode lines are horizontal scroll bars
          (running from rightmost column to under leftmost column)
      the unused right window bar and the dividing lines between
          windows are vertical scroll bars
          (running from top of window THRU modeline
  for vertical scroll bars:
        click at line 1 does previous page
        click at last line does next page
        click anywhere else "thumbs" to the relative portion of the buffer.
        shift-click at line 1 scrolls one line down
        shift-click at last line scrolls one line up
        shift-click elsewhere moves line to top of window
        option-shift-click elsewhere moves line to bottom of window
  for horizontal scroll bars:
      click at column 1 does scroll right one window width
      click at last column does scroll left one window width
      click anywhere else moves to that "percent" of the buffer width
      shift-click at column 1 scrolls one column right
      shift-click at last column scrolls one column left
      shift-click elsewhere moves column to right of window
      option-shift-click elsewhere moves column to left of window

There is also basic positioning and kill-buffer support:
        click in a buffer moves dot there and selects that buffer
        drag copies the dragged region to the kill buffer
        shift-drag deletes the dragged region to the kill buffer

  It is possible to use the scrolling and thumbing area to make the region
  larger than a single screen; just click, scroll, release. Make sure
  that the last scroll is just a down event; the up must be in the buffer.
  The last mouse position is remembered for each different buffer (not
  window), and thus you can start a drag in one buffer, select another,
  go back to the first buffer, etc.

        option-click yanks from the kill buffer
        option-shift-click similarly yanks from a named buffer.
3 Other_features
Most of the capabilities of BOSS in its regular mode are available.
However, there are some differences in BOSS/UW

Only 7 processes can be run (instead of 8).

The processes are named 1 thru 7 not A thru Z.

BOSS/FLOW_CONTROL is used to be set (independent of what you actually ask
for).  Note that under UW the use of flow control by the Macintosh
hardware to prevent data overruns of the Mac's buffers is carried out
independently of your attempts to control output with C-s and C-q.  In
particular, C-s and C-q can be used for their regular functions in Emacs,
even though the Macintosh and the VAX are still using flow control.

BOSS/UW sets the default output flag to p (instead of b).  This allows
output from all processes to be sent to their respective windows.  This
default be overridden with DEFAULT_OUTPUT_FLAG qualifier.  And of course
you can use C-\ C-b, etc., to set this flag on a per-process basis.

BOSS/NOCOMMAND_CHARACTER can be used to indicate that no command character
is to be used.  (Thus all characters you type get seen by your VAX
process.)  By default, C-\ is still used as a command character.

BOSS doesn't print "[Switch to process 5...]" messages, since the
switching is obvious from the arrangement of windows.  Other messages
(e.g., the response to C-\ ? should appear in the active window).

C-\ 3 will tell BOSS to switch to process 3, but UW won't bring that
window to the front.  The same comment applies to process-initiated
switches (via the BOSS$SWITCH logical name.  You should probably use one
of the other methods for switching processes (clicking on the window,
command-3, etc.)

BOSS/PROCESS_DEFAULT=TOP will cause BOSS's processes to be top-level
processes.  Thus when you select New in the Windows menu, you will see a
Username: prompt.

You can create processes with C-\ C-n 4 or C-\ C-t 4 (for subprocesses and
top-level processes).  This allows you to create either type of process,
while selecting New in the Windows menu produces only a process of the
default type (governed by BOSS/PROCESS_DEFAULT).

BOSS/START=(1,2)/STUFF=Emacs will create processes 1 and 2 and start Emacs
in process 1.  This is just the same as BOSS behavior in its regular mode.
3 Misfeatures
Occasionally BOSS loses track of what UW thinks is the active window.
Your typed input will then be sent to the wrong process.  This is
corrected by switching to some other window (e.g., by clicking on it) and
then switching back to the original window.

Other than the fact that UW supports multiple windows and more intelligent
mouse behavior with Emacs, UW is a much worse terminal emulator than
VersaTerm.  In particular:

* It doesn't save what scrolls off the screen.

* I haven't been able to get EVE or LSE to work reasonably.  I presume
  there's some way of telling these programs what UW can do (via
  TERMTABLE);  I just haven't managed to get it to work right.  Emacs
  works just fine though.

* Keypad is not supported.

* Arrow keys don't work.

* UW implements a Tektronix 4010 emulation, but it's a pretty miserable
  affair.

* Can't print.

* Can't do file transfers.

I've only implemented the most basic level of UW service under BOSS.  The
next level allows windows to be retitled from the VAX, as well as setting
many of the other attributes of windows.  This will most likely not get
implemented.

The main reason for implementing the UW features in BOSS was to show that
the Macintosh can provide a multi-window enviroment for the VAXes.  Now we
have to get Lonnie Abelbeck to modify VersaTerm to support the UW
protocol...
2 Acknowledgements
BOSS was written by Charles Karney based on the PHOTO program written by
Asbed Bedrossian of USC.  It utilizes the Pseudo TTY package of Dale Moore
of CMU and Kevin Carosso of Network Research Co.  File logging, screen
redisplay, and inter-process paste were added by Glenn Everhart
(EVERHART@ARISIA.dnet.ge.com).  Record and playback were added by Henk
Davids (hdavids@mswe.dnet.ms.philips.nl).  PTD support was added by Steve
Alpert (sra@idx.com).

UW, the multi-window Macintosh terminal emulator was written by John D.
Bruner of LLNL.  The Emacs mouse support was written by Gregory S. Lauer of
BBN.

Bugs, questions, etc. to
   Charles Karney
   Plasma Physics Laboratory      E-mail:  Karney@Princeton.EDU
   Princeton University           Phone:   +1 609 243 2607
   Princeton, NJ 08543-0451       FAX:     +1 609 243 2662

