XXFILE source code and documentation.

doc/README.md

@@ -15,6 +15,7 @@
 - CRTSTY: [manual](info/crtsty.39)
 - FIND: [manual](info/find.13)
 - DIRED: [manual](_info_/dired.info), [commands](_info_/dired.order)
+- XXFILE: [manual](_info_/xxfile.info)
 
 ### Programming
 

doc/_info_/xxfile.info

@@ -0,0 +1,166 @@
+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