xxfile.info

XXFILø£E
	XXFILE is a program which is similar in concept to the XFILE
command of ddt:  one has a file of commands which is executed
frequently.  The distinction is that XXFILE command files can pass
control of the tty around from place to place, a property which the
xfile command does not possess.
	XXFILE operates by opening a STY, logging it in, and feeding
the command file(s) through it.  Thus, as far as the programs being run
are concerned, it is exactly as if they were receiving input from the
tty.  Input is supplied (with one exception) when the program on the
other end requests it, at which time XXFILE sends characters from the
file until it has sent an interrupt or activation character.  Output
(including echoing, since the connection is full-duplex) may be directed
to the tty, to a file, or to the bit bucket; regardless of that, it is
possible to specify various strings (initially '*ERROR*', '?U?', and
'??') which will cause an error when encountered in the output.  Errors
may also be generated when a fatal error is encountered.
	When errors are encountered, the file being executed is
suspended and input is taken from the tty (except see the 'E' switch
under JCL).  In this case, the connection is similar to that supplied by
SUPDUP.  It is also possible to start tty input manually during the
execution of a file, or to specify that tty input begin in the command
file itself--xxfile commands may be included in the command file, where
they are treated exactly as if they were entered from the tty.

	Note that when XXFILE starts it sets its ..SAFE variable to -1: 
attempts to kill one, or to log out while it is running, will provoke
the --Kill Protected Job-- query from DDT.

JCL:
	Three things may be specified on the jcl line, in any order: 
switches, the output file, and the input files.  Switches are letters
preceded by a '/'; there are currently three switches:
E:  If this switch was set, and an error is encountered while XXFILE is
    running disowned (has no console), then it will print any error
    messages to the output file (if one exists) and logout.  Normally,
    it will attempt to use the TTY, thereby hanging up.
P:  If this switch is set, the terminal seen by the programs you're
    running is just a printing console, rather than whatever you're
    running on.
S:  If set, XXFILE will keep trying if it gets a DEVICE FULL error when
    it tries to open its STY.  In particular, it will try every ten
    seconds for an hour before it gives up.  This is primarily useful
    for jobs running under BATCHN on DM, for example, since the user may
    not be around to make a STY available.
The output file (which defaults to the bit bucket) is a file name
followed by '_'; the default name is <HSNAME>;<XUNAME> >.  Input files may
be either file names, separated by commas, or text strings, which are
treated as files. Text strings should be enclosed in square brackets;
control characters may be included by using <uparrow><char>; the
characters '^' and ']' may be quoted with ctrl-Q.  Thus:
:xxfile tty:_[:muddle^m]taa;foo bar,taa;zork feep[<QUIT>]
will direct output to the tty; input will be
:muddle
followed by the contents of foo bar and zork feep, followed by <QUIT>.
	If no sname is provided for input files, your sname is assumed;
defaults are sticky from one input file to the next.

	Before any of the jcl line is executed, the following string is
sent:
<xuname>0U:GAG 0
This logs the tty in, and causes :sends to be refused.  The tty is also
put in refuse mode.  When the jcl line has finished executing, 0U is
sent to log the tty out.

Commands
	Commands may be included in files to be executed or typed in
from the tty.  In either case, they are of the form
<intercept character><single-letter command><optional command line>.  If
a command requires a command line, it must be terminated in the file
with <crlf>.  The intercept character is initially ctrl-^.
	When commands are typed from the tty, <rubout> erases the last
character, ctrl-W erases the last word, and ctrl-X, ctrl-U, and ctrl-@
erase the entire command line.  Attempts to rubout past the beginning of
the command line abort the command.
Commands currently implemented are:
A--Abort the current input source.  The current file or text field is
   flushed, and execution proceeds with the next part of the jcl line.
B--Begin tty input.  Suspend execution of the current file, and accept
   input from the tty until an 'S' command is given.  This command is
   executed implicitly when an error is detected and when the 'H'
   command is given.
C--Change output file.  Takes the new output file as a command line. 
   The current output file is closed, and output is directed to the
   specified location.
D--Return to ddt (like ctrl-Z).
E--Error strings.  Takes 0-n error strings, separated by commas, as a
   command line.  Initially the error strings are '*ERROR*', '?U?', and
   '??'.  Checking for errors may be disabled simply by giving this
   command with a null command line.
F--Force input.  Characters until the next 'F' command will be jammed
   down the throat of the running job, whether it wants them or not. 
   Some jobs (PUB, for example) do not explicitly request input, but
   read it at interrupt level.  This command is for them.
H--Halt job.  Sends ctrl-Z immediately, then does a 'B' command.
I--Set intercept character.  Takes the new character on a command line,
   as the first character.  Note that this must be a control character
   of some sort, so it will interrupt when typed.
J--Undo an 'R' command.
P--Proceed xxfile.
Q--Quit xxfile.
R--Remain in this job.  All input must go to the current job until a 'j'
   command is executed.  This allows fatal errors (ioc's which aren't
   handled, for example) to be detected.  When the input source is the
   tty, such checking is suppressed.
S--Stop tty input.  Revert to the current input file.
T--Set ctrl-T character.  See 'Job status'.
V--Valret string.  This reads a line from the current input source, and
   does a .value of it.  Control characters (cr, for example) may be
   included by giving uparrow followed by the normal character:  ctrl-M
   as uparrow (^) followed by M.
?--Give brief command summary.

	The intercept character may be sent by quoting it with the
intercept character.  The ctrl-T character is only noticed when typed on
the tty; it may be sent by quoting with the intercept character also.
Rubout is a null command.

The tty
	Unless the P switch is set in the jcl line, the tty your jobs
see will be a software tty very similar to the one you are using--the
major difference is that the screen is slightly smaller.  The P switch
causes the tty to be the default sty, which is a printing terminal 72
columns wide.
	When the input source is the tty, or output is to the tty, all
abnormal output from XXFILE is printed in a two-line echo area, to
preserve the display of output from the program.  It also tries to keep
the cursor on your tty in phase with the cursor on your job's tty.

TTY input
	When the input source is the tty, XXFILE enters super-image
input mode, meaning that ctrl-Z and ctrl-_ are treated as normal input
characters.  Should you need to get out of xxfile, the D command may be
used; also, ctrl-Z and ctrl-_ may be typed as commands, since
super-image input is turned off in the command reader.
	Since the foreign tty is similar to your own, rubouts and such
will be handled correctly.  It is, in fact, possible to run real-time
teco through xxfile, though I know of no good reason for doing so.

Job status
	Ctrl-T typed from the tty causes a brief summary of your job's
status to be printed, either in the echo area (if XXFILE is using the
tty for output) or on the next line.  The summary includes:
Tnn mm jname sname status % timusd %RD lastout
Where:
Tnn is the tty your jobs are running on.
mm is the index of the job currently having the tty.
jname is its jname
sname is its sname
status is like PEEK's:  WALK, RUN, FLY, &c, or the reason the job is not
   currently running.  This may be preceded by '=>', '<=', or '<=>';
   these mean, respectively, that XXFILE is currently sending characters
   to your job, receiving characters from it, or both.
% is the percentage of the system your job is getting
timusd is the amount of cpu time it has used so far.
%RD is the percentage of the current input file that has been used.
lastout is the first 10 or 15 characters of the last group sent to the
   job.  If the job is a ddt, which activates on every character, this
   will only be one character, the last one sent; if it is a muddle, it
   may be an entire form.

Cautions
	MUDDLEs, at least, are known to hang up occasionally when
talking to a sty.  As nearly as I can determine, this is a timing
problem in the system.  You can win, usually, by entering tty input mode
(the 'B' command), typing ctrl-Z, ctrl-P, and P, then leaving tty input
(the 'S' command).