⟦cb918e7ad⟧

TextFile

\chapter{Testing PP - the MTS User Interface}

A special user interface known as \pgm{mu} is
provided as a general tool to help test
\pgm{submit} and consequent operations in PP.
Setting defaults in the \file{mu.defaults} file allows a minimum
number of message-specific parameters to be provided.
It may be used to re-submit a modified text-encoded file taken from 
the queue.

\section{Overview}

The message submission tool \pgm{mu} takes input from the command
line, a defaults file \file{mu.defaults} if present in the working directory,
otherwise from the default command directory \verb+cmddfldir+ and then
any other files specified with \verb+-file+ flags. A full summary of
the flags to \pgm{mu} is given in Table~\ref{mu:flags} on
page~\pageref{mu:flags}.  Any command line option may be placed on a
line within an input file.  \pgm{mu} calls its command line parser
recursively when it encounters a line starting with \verb+`-'+
(FLAGCHAR).  Any line starting with \verb+`#'+ (COMMENTCHAR) is
ignored.  Otherwise, all lines are offered to the various
\pgm{submit} input routines in turn for incorporation into PP's
internal message structures ({\em prm\_vars\/}, {\em Qstruct\/} and
{\em ADDR\/}).  Any line which returns an error code (\verb+rp_isbad+)
from all these routines is assumed to be in error.

The input lines which specify assignments as specified in QUEUE(5) may
be received in any sequence, and inputs may override earlier entries.
Any value may also be assigned on the ( original ) command line with
\verb+-value v1 v2 +\ldots up to the next flag.

If input files are nested, input lines from the nested file are
processed before the remainder of the file containing the \verb+-file+
specifier.  The default file is parsed first ( \file{mu.defaults}
unless overridden with a \verb+-default+ flag on the command line),
then any \verb+-file+ specified files from the command line, finally
\verb+-value+ specifications from the command line.  Body part files
may be specified with \verb+-body+ commands, either on the command
line or embedded as with other commands.\\

\pgm{mu} uses PP's standard logging ---- additional logging messages generated by
--0 --1 --2 --3 flags are output to a channel (\verb+muout+) which defaults to \verb+stdout+
unless flag \verb+-logfile+ is specified.  Note that output may be re-routed
in the course of processing input files.  The flag --5 allows
these messages to be appended to the nominated logfile, rather than
replacing it. \\

In addition to the LLOG\_TRACE and LLOG\_DEBUG calls associated
with flags \verb+-0+ and \verb+-1+ shown below, there are some other
LLOG\_FATAL and LLOG\_EXCEPTIONS calls.  Note that functions \verb+list_args+
and \verb+show_args+ ( in \file{argh.c} ) do not generate LLOG events.
\pgm{mu} accepts a number of debug flags \verb+-0+, \verb+-1+ etc.
--- currently these are used as follows :\\[2ex]

\begin{tabular}{cp{3.5in}}

       flag      &       function\\[1ex]
        -0       &      log to {\em muout} progress messages, and PPLOG(LLOG\_TRACE ...)\\
        -1       &      log to {\em muout} command files as they are processed, and PPLOG(LLOG\_DEBUG ...)\\
        -2       &      list to {\em muout} body part files as they are io\_tdata'ed\\
        -3       &      list to {\em muout} structures prior to submit io\_ calls\\
        -4       &      abort prior to submit io\_ calls\\
        -5       &      append to logfile rather than overwrite\\[1ex]
\end{tabular}

\pgm{mu} accepts \verb+-body+ part file names with any arbitrarily long pathname. 
The full path is used :

\begin{tabular}{lp{4.0in}}

1.      &To open the file and check its length.  Two fatal errors are detected :\\

&        a.      \verb+unable to read body part %s+\\
&        b.      \verb+body part %s is null file+\\

2.&      To open the file in order to pass its contents to \pgm{submit}
        with a series of {\em io\_tdata(buf,length)} calls. Again, failure
        to open is reported :\\

&       \verb+unable to open body part for reading %s+\\

3.&     To pass a name for \pgm{submit} to use in the queue.
        \pgm{submit} generates a message directory to match the
        supplied pathname. Thus:\\

&      \verb+-body 4.ipm/hdr.822uk+ --- generates :\\
&       usr/spool/pp/queues/msg/msg.annnnnn/base/4.ipm/hdr.822uk\\
\end{tabular}

If a reserved character `*' (FILEMARKCHAR) is embedded in the
\verb+-body+ pathname, \pgm{mu} strips all characters up to and
including the `*' from the pathname before passing to \pgm{submit}.
This allows \pgm{mu} to distinguish between the path used to find the
file(s) and that required within the message. Thus:

\begin{quote}\small\begin{verbatim}
-body nest1/nest2/*3.ipm/1.ia5
\end{verbatim}\end{quote}
generates:
\begin{quote}\small\begin{verbatim}
/usr/spool/pp/queues/msg/msg.annnnnn/base/3.ipm/i.ia5
\end{verbatim}\end{quote}

The `*' is removed for purposes (1.) and (2.) above. The character `*'
may also be placed in the pathname to a directory to truncate the
pathname passed on to \pgm{submit} from a \verb+-tree+ command --- in
the same way as for \verb+-body+ specification.

Because the line parsing routines used in \pgm{mu} are exactly those
in \pgm{submit} itself, any values/options which are acceptable to
\pgm{submit} will also be accepted by \pgm{mu} ( but in any
sequence ).

To illustrate :
\begin{quote}\small\begin{verbatim}
mu  -- -0 -file test1 -body b1 /tmp/jtaylor/messdir/*b2 \
    -default new.defaults -value MsgiD Country=US
\end{verbatim}\end{quote}

will read from \verb+"new.defaults"+, ( processing any \verb+`-flag'+
specifiers it contains ), then from file \verb+"test1"+ finally
setting a new country \verb+US+ to override any file-specified value.
The \verb+-0+ flag turns on progress messages and \verb+--+ will list
the flag table.  During submission, files \verb+"b1"+ and \verb+"b2"+
will be transmitted individually.

\section{User input}

The reserved character \verb+`$'+ (TOKENCHAR) is used to indicate that
the user should input a value to replace the \verb+`$'+, unless the
line is a comment line or the \verb+`$'+ is immediately followed by a
second to escape a real \verb+$+ symbol.  The portion of the input
line up to and including the \verb+`$'+ is displayed on screen, then a
carriage return delimited string is input to replace the \verb+`$'+.
The substituted line is scanned for further unpaired \verb+`$'+
characters.  When all have been replaced, if the flag \verb+-confirm+
has been specified, the user input will be re-displayed awaiting user
confirmation or cancellation with \verb+`y'+ or \verb+`n'+.  The line
is then offered to the \pgm{submit} input routines.  Any error will
cause the input portions to be re-prompted {\em unless\/} the flag
\verb+-nofix+ has been specified, in which case \pgm{mu} will ignore
the error and continue.

To allow repeated user input, for example, of multiple recipient
lines, another reserved character \verb+`*'+ (REPEATCHAR) may be
placed at the start of a line to indicate repetition.  If this
character appears at the start of a line which contains no unpaired
\verb+`$'+ characters, an error

\begin{quote}\small\begin{verbatim}
error : no TOKENCHAR(s) in REPEAT line - REPEATCHAR ignored
\end{verbatim}\end{quote}

is reported.  Otherwise, user input takes place as before, terminated
by a null input ( just a carriage return ) on any substitution field
in the line.  Repeat lines are stripped of the \verb+`*'+ character
before passing to the \pgm{submit} input routines.

Example --- command line :
\begin{quote}\small\begin{verbatim}
mu  -confirm -file a1 -nofix
\end{verbatim}\end{quote}
where file \verb+a1+ contains :
\begin{quote}\small\begin{verbatim}
# Start-of-MsgEnvPrm
-body hdr.822
-body 2.ia5
# $$ implies $
-file level$$
Message-type User-Mpdu
# $ symbols in comments are ignored
Inbound-channel 822-local
Inbound-host UK.AC.UCL.CS
Content-type $
Encoded-info EncTypes=iA5Text
Priority $
PerMsg-Flags disclose-recipients
PerMsg-Flags return-contents
MsgId string $
Start-of-MsgEnvAddr
*Recip type=822 orig=$@uk.ac.ucl.$ End-of-addr
\end{verbatim}\end{quote}

will prompt for \verb+Content-type+, \verb+Priority+, \verb+MsgId
string+, and two components from \verb+Recip+ lines until a null
input.  Each input line must be confirmed with \verb+`y'+, but any
errors will be disregarded.  Section delimiters such as
\verb+Start-of-MsgEnvAddr+ are redundant, since \pgm{mu} accepts
control lines in any order, but are benign.

\tagtable{muflags}{Summary of MU flags}{mu:flags}

\section{mu internals}

\pgm{mu} uses the argument handling routine \verb+argh+ and can 
therefore accept any unambiguous prefix for a flag specifier. (See
separate document.)

\pgm{mu} has no knowledge of the significance of any input line
other than that it is valid for {\em txt2prm\/}, {\em txt2q\/} or {\em
txt2adr\/}.  The one exception to this is that, to allow a recipient
to be specified before the originator, each potential address line is
tested against \verb+"Origs"+. (Because the originator is held in a
separate structure from the recipient list, and {\em io\_wadr\/} needs
to have \verb+AD_ORIGINATOR+ or \verb+AD_RECIPIENT+ passed to it
explicitly.)  Second and subsequent \verb+"Origs"+ lines are treated
as errors.

After processing all inputs, a sequence of procedure calls to are made
to \pgm{submit} the message (as outlined in Volume 2).  Thus
(summarised) :
\tagrind[hbp]{musub}{io\_ Interface}{musub}

Each procedure call returns a status in the error structure
\verb+RP_Buf+ which is displayed as follows:

\begin{quote}\small\begin{verbatim}
RP_ERROR error_number error_string.
\end{verbatim}\end{quote}

Such errors abort the submission.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦cb918e7ad⟧ TextFile

Derivation

TextFile
