NetBSD/gnu/libexec/uucp/contrib/xchat.man

.TH xchat 8
.SH NAME
xchat - Extended chat processor
.SH SYNOPSIS
.BI "xchat " "scriptfile"
.RI " [ " parameter... " ] "
.PP
where
.I scriptfile
is the name of a file containing an 
.I xchat
script. If 
.I scriptfile
begins with ``/'', then it is assumed to be a full path name for the
script file. If not, a configuration-dependent default directory path
(usually
.B "/usr/local/conf/uucp/"
) is prepended to the script file name. Normally, the default path
is the same as that for the Taylor UUCP configuration files.
.SH DESCRIPTION
.I Xchat
is a general-purpose dialing and login program designed for use 
with Taylor UUCP as a ``chat-program'', taking the place (or 
augmenting) the built-in chat scripting facility. It provides the 
ability to closely control timeouts, multiple simultaneous ``expect'' 
strings with separate actions, extended terminal control, modem 
command character pacing, and more.
.PP
When used in conjunction with Taylor UUCP's
configuration features, 
.I xchat
can provide you the ability to manage the most intricate login, 
dial and hangup needs. The scripts are written in a shell-like (well, 
sort-of) style with labels, commands, and parameters, easing the task 
of writing procedures for complex terminal communications situations.
.PP
Because 
.I xchat
assumes that it is connected to the terminal device via stdin/stdout, 
you can easily debug scripts by invoking it from the shell and 
responding to the script from the keyboard. A debug logging facility 
is included, with the debug output going to a separate user-specified 
file. This makes it easy to debug connection problems without wading 
through large 
.I uucico
log and debug files.
.PP
Formally, a script describes a state machine; 
.I xchat
interprets the script and does what the state machine
tells it to. This section will be much easier to understand 
if you obtain listings of the script files supplied with
.I xchat.
.SH "SCRIPT FILE FORMAT"
Script files are ordinary text files containing comments, labels,
and statements. Blank lines are ignored. 
Comments are denoted by leading ``#''
characters. Some statements (those which do not end with an
``extended string'' argument; see below) can also have trailing
comments.
.PP
.I Labels 
begin in column one and are ended by colons (:). A label
specifies a state name. All lines between a pair of labels are
the statements for a single state.
.PP
Processing always begins at the head of the script (no leading
state name is necessary).
.PP
.I Statements 
are divided into two categories, ``action'' and ``expect''.
When a state is entered, all of its actions are performed in the
order in which they appear in the file.
.PP
A 
.I transition 
to another state may occur for any of three reasons:
.IP (1) 5
One of the actions may cause a transition to
another state, in which case the rest of the
current state's actions are skipped.
Processing resumes with the first action
statement of the new state.
.IP (2) 5
If none of the actions cause a state
transition, and there are no expects in the
state, processing ``falls through'' to the next
state in the file.
.IP (3) 5
If none of the actions cause a state
transition, but there are expects in the
state, the state machine pauses until one of
the expects is ``satisfied''. It then transitions 
to the state named in the expect
statement.
.PP
Finally, there are two action statements which, when executed,
cause the script to exit.
.SH "SCRIPT FILE STATEMENTS"
This section describes all of the statements that may appear in script
files, except for a few special action statements. Those are described
in a later section, ``Overriding Defaults''.
.PP
Some statements accept one or two arguments, referred to in the
following descriptions as 
.IR int ", " ns ", " str ", or "
.IR xstr ", to"
indicate whether the argument is an integer, a new state name, a
string, or an ``extended string'' (described in a later section).
.PP
For all statements that accept two arguments, the first is the
name of a new state, and the second specifies a condition or
reason for changing to the new state.
.SS "Termination And Informational Statements"
These statements are used to place entries into the Taylor UUCP
.I Log
file, and to cause 
.I xchat
to exit with successful or failure status. It is also possible to open a 
separate
.I debug
log file and control the level of tracing and error reporting that will go
into that log file. This is very useful in debugging 
.I xchat
scripts.
.br
.ta 1.0i 1.5i 2.0i
.TP 2.0i
.B failed
Exit script with ``failed'' status. This causes 
.I xchat 
to exit with status 0.
.TP 2.0i
.B success
Exit script with ``success'' status. This causes
.I xchat
to exit with status 1.
.TP 2.0i
.BI "log	" xstr     
Send informational message
.I xstr 
to standard error. When used with Taylor UUCP, this is the 
.I Log
file for the 
.I uucico
program.
.TP 2.0i
.BI "logerr	" xstr     
Send message
.I xstr 
to standard error, with ``ERROR:'' indicator. When used 
with Taylor UUCP, this is the 
.I Log
file for the 
.I uucico
program.
.TP 2.0i
.BI "dbgfile	" xstr
Open script debugging file 
.I xstr.
If
.I xstr
begins with ``/'', it is assumed to be an absolute path name for the
debugging file. If not, then a configuration-dependent default directory 
path (usually
.B "/usr/spool/uucp"
) is prepended to
.I xstr.
Normally the default path is that of the directory where Taylor UUCP 
puts its log files.
The debugging file is used to capture a detailed log of the data sent
and received, errors encountered, and a trace of script execution.
The various types of logging are controlled by the
.I "debug mask,"
described next. 
.B Note:
A new log file is created each time 
.I xchat
runs. Use the 
.B log
and
.B loge
commands to log 
continuous information onto standard out, which is connected
to the Taylor UUCP
.I Log
file when 
.I xchat
is run by the Taylor
.I uucico.
.TP 2.0i
.BI "dbgset	" int
Set the bits specified in 
.I int
in the debugging mask. The value in
.I int
is ``or''ed into the mask. Set bit 0 (value \= 1) for error messages,
bit 1 (value \= 2) for dial, login and init errors, bit 2 (value \= 4)
for dial, login and init trace with character I/O, and bit 3 (value \= 8)
for script processing internals. Normally, you will just turn it all on
with a value of 15.
.TP 2.0i
.BI "dbgclr	" int
Clear the bits specified in
.I int
from the debugging mask.
.TP 2.0i
.BI "debug	" xstr
Write 
.I
xstr
into the debug log. The entry will be enclosed in angle brackets.
.TP 2.0i
.BI "debuge	" xstr
Write
.I xstr
into the debug log with ``ERROR: '' prepended. The entry will be enclosed
in angle brackets. 
.SS "Sending Data"
These statements are used to transmit data to standard out (the tty or TCP
port when used with Taylor UUCP).
.I
No implied carriage returns are sent.
You must include a \\r if you want a carriage return in the string
sent by the 
.B send
command. If you want a return sent after 
.B dial
or
.B sendstr,
you must send it with a separate
.B send
command.
.TP 2.0i
.B dial
Send the string previously set by the 
.B telno
command to the serial port.
.B W
and
.B P
characters in the phone number are
converted as described under 
.B 
Dial Strings,
below. This statement also sets a default
timeout value, as described under the 
.B timeout
statement.
.TP 2.0i
.BI "send	" xstr
Send the string 
.I xstr 
to the serial port.
.TP 2.0i
.BI "sendstr	" int
The argument of this statement is a digit from 0
through 7. Send the corresponding string
parameter as passed to 
.I xchat
following the script file name. The parameter is interpreted 
as an extended string.
.SS "Special Terminal Control Statements"
These statements are used to cause the terminal port to perform some special action, or to change the mode of the port.
.I 
The modes of the port are restored to their original settings
.I
by xchat before it exits.
.TP 2.0i
.B flush
Flush the terminal port's input buffer.
.TP 2.0i
.B break
Send a break signal.
.TP 2.0i
.B hangup
Momentarily drop Data Terminal Ready (DTR) on the
serial port, causing the modem to hang up. (Not
usually needed, since 
.I uucico
does this at the end of each call.)
.TP 2.0i
.B 7bit
Change the port to strip incoming characters to 7 bits. 
.I
This is the default mode.
This mode 
is implied when the port has parity enabled, since parity characters
are 7-bits wide.
.TP 2.0i
.B 8bit
Change the port to allow incoming 8-bit characters to be passed 
to the script processor. This mode has no effect if parity is 
enabled, since parity characters are 7-bits wide.
.TP 2.0i
.B nopar
Change the port to 8-bits, no parity. 
.I
This is the default mode.
.TP 2.0i
.B evenpar
Change the port to 7-bits, even parity. 
.I 
Incoming characters with parity errors are discarded.
.TP 2.0i
.B oddpar
Change the port to 7-bits, odd parity.
.I 
Incoming characters with parity errors are discarded.
.SS "Counting, Branching, Timing and Testing Statements"
These statements are used to control the flow of the 
.I xchat
script itself, including branching, delays, and counter manipulation.
.TP 2.0i
.BI "sleep	" int 
Delay for 
.I int
milliseconds.
.TP 2.0i
.B zero
Clear the counter.
.TP 2.0i
.B count
Add one to the counter.
.TP 2.0i
.BI "ifgtr	" "ns	int"
Go to state 
.I ns
if counter greater than 
.I int.
.TP 2.0i
.BI "goto	" ns
Go to state 
.I ns 
unconditionally.
.TP 2.0i
.BI "ifstr	" "ns	int"
Go to state 
.I ns
if string parameter 
.I int
is nonempty.
.TP 2.0i
.BI "ifnstr	" "ns	int"
Go to state
.I ns
if string parameter 
.I int
is empty.
.TP 2.0i
.BI "ifblind	" ns
Change to state
.I ns
if the port is ``blind'' without carrier (CD) asserted.
.I 
This is not yet implemented, the test always fails.
.TP 2.0i
.BI "ifblgtr	" "ns	int"
Change to state
.I ns
if the port is ``blind'' without carrier (CD) asserted, and counter
is greater then
.I int.
.I 
This is not yet implemented, the test always fails.
.SS "Expect Statements"
Expect statements are usually the last statements that appear in a
given state, though in fact they can appear anywhere within the
state. Even if they appear at the beginning, the script processor
always does all of the action statements first. As a practical
matter, the order of these statements is not significant; they are
all interpreted ``in parallel''.
.TP 2.0i
.BI "expect	" "ns	xstr"
Change to state 
.I ns 
if the string specified by
.I xstr 
is received from standard input (usually the serial port). 
Case is significant, but high-order bits are not
checked.
.TP 2.0i
.BI "expectstr	" "ns	int"
Change to state 
.I ns 
if the string specified in parameter
.I int 
is received from standard input (usually the serial port).
.I int 
must be in the range 0 to 7. 
Case is significant, but high-order bits are not
checked.
Useful where a prompt can change in different dial-in lines. 
.TP 2.0i
.BI "ifcarr	" ns
Change to state
.I ns 
if Carrier Detect (CD) is true.
.I
Not currently implemented. Always changes state.
.TP 2.0i
.BI "ifhang	" ns
Change to state
.I ns
if a data set hangup occurs (SIGHUP signal received).
.TP 2.0i
.BI "timeout	" "ns	int"
Change to state 
.I ns 
if the time (in milliseconds)
given by 
.I int
has elapsed without satisfying any
expects. If the time specified is 0, a default
timeout value (calculated from the length and
other characteristics of the most recent dial
string) is used.
.SH "SCRIPT PROCESSING DETAILS"
.SS "Extended Strings"
In the statements that accept string arguments, the strings are
interpreted as 
.I 
extended strings. 
Extended strings begin with
the first nonblank character and continue, including all imbedded
and trailing blanks and other whitespace, until (but not
including) the end of the line in the script file. (There is no
provision for line continuation.)  No trailing spaces should be
present between the last ``desired'' character of the string and the
end of the line, as they will be included in the stored string and
sent or expected, just as they appear in the script file. And,
obviously, no trailing comments are permitted!  They will just be
stored as part of the string.
.PP
Within an extended string, the following ``escape sequences'' will
be converted as indicated before being sent or expected:
.br
.nf
.in +0.5i
\fB\\d\fR	EOT character (control-D)
\fB\\N\fR	null character
\fB\\n\fR	line feed
\fB\\r\fR	carriage return
\fB\\s\fR	space
\fB\\t\fR	tab
\fB\\\-\fR	hyphen
\fB\\\\\fR	backslash
\fB\\ooo\fR	character with value ooo (in octal)
.in -0.5i
.fi
.PP
Since extended strings in scripts can include embedded spaces,
tabs, etc., these escape sequences are only required in strings
appearing in systems entries, though they may be used in script
files to improve readability.
.PP
The octal-character specification (\\ooo) may have from one to
three octal digits; it is terminated either after the third digit
or when a non-octal character is encountered. But if you want to
specify one of these followed by something that happens to be a
valid octal character (for example, a control-A followed by a 7)
make sure to include all three digits after the \\ . So \\0017
would become a control-A followed by the Ascii character ``7'', but
\\17 or \\017 would become a control-Y (decimal value 25). \\1S
would convert to a control-A followed by an ``S''.
.PP
Extended strings are stored without a trailing carriage return
unless one is explicitly present in the string (via \\r).
.SS "String Parameters"
The 
.B sendstr 
statement sends (after conversion from extended string
format) one of the parameters given on the 
.I xchat
command line following the script file name. 
The parameter is selected by the integer
argument of the statement.
.PP
This allows ``generic'' script files to serve
for many different systems; the string parameters 
provide the phone number, username, password, etc. Character
substitutions described under ``extended strings'' above are
performed on these strings.
.PP
The ifstr and ifnstr statements allow further generality in script
files, by testing whether a particular parameter is present in the
systems entry. For example, a single script can be
used both for those systems that require a password and
those that do not. The password is specified as the last argument
in the 
.xchat
command; the script can test for this
parameter's existence and skip the password sequence if
the parameter is empty.
.SS "``Wait'' And ``Pause'' Characters In Dial Strings"
An additional conversion is performed on dial strings. Dial strings
are interpreted as extended strings. Then the characters
.B W 
and
.B P
within a dial string are interpreted as ``wait for dial
tone'' and ``pause'', and may be converted to other characters. By
default, 
.B W
is left alone, and
.B P
is converted to a comma (,);
these are appropriate for Hayes-type modems. The script may
specify other substitutions (see below).
.PP
.B NOTE: 
The Taylor UUCP documentation states that the ``wait'' and ``pause''
characters are ``='' and ``-'', respectively. These are actual characters
understood by some modems. When using
.I xchat
you should put
.B W
and
.B P
in the dial strings you specify in the Taylor configuration files. 
This way, the 
.I xchat
processor can make the substitution appropriate for the particular 
modem in use. Make a separate 
.I xchat
script for each modem type, e.g.,
.I "dial.hayes"
and specify the translation there. This way, the phone number strings
in the Taylor configuration files can be used with a variety of modems.
.SS "Default Timeouts For Dial Strings"
When a 
.B dial 
statement is executed, a default timeout value is set.
This is the timeout value used by a subsequent timeout statement
if the statement specifies a timeout value of 0.
.PP
The default timeout is given by:
.br
.nf
.in +2
\fIctime\fR + (\fIndigits\fR * \fIdgttime\fR) + (\fInwchar\fR * \fIwtime\fR) + (\fInpchar\fR * \fI ptime\fR) 
.in -2
.fi
.PP
where 
.I 
ndigits, nwchar, 
and 
.I npchar
are the number of digits, wait characters, and pause characters in
the dial string, and 
.I ctime, dgttime, wtime, 
and 
.I ptime 
are 45 seconds, 0.1 seconds, 10 seconds, and 2 seconds, 
respectively.
All of these times may be changed as specified below under
``Overriding Defaults.''
.SS "Trailing Carriage Returns Not Assumed"
In the 
.B dial
and
.B sendstr 
statements, the dial string or
parameter is sent with no trailing carriage return;
if a carriage return must be sent after one of these, a separate
send statement must provide it.
.SH "OVERRIDING DEFAULTS"
The script processor sets several default values. The following
statements, which override these defaults, may be useful in
certain circumstances.
.TP 2.0i
.BI "chrdly	" int
Since many modems cannot accept dialing commands
at full ``computer speed'', the script processor
sends all strings with a brief inter-character
delay. This statement specifies the delay time,
in milliseconds. The default is 100 (0.1 second).
.TP 2.0i
.BI "pchar	" str
Specifies the character to which 
.BR P s 
in the
dial string should be converted. Default is
``,'', for use with Hayes-type modems.
.TP 2.0i
.BI "ptime	" int
Specifies the time, in milliseconds, to allow in
the default timeout for each pause character in
the dial string. Default is 2000 (2 seconds).
.TP 2.0i
.BI "wchar	" str
Specifies the character to which 
.BR W s 
in the
dial string should be converted. Default is
``W'', for Hayes modems.
.TP 2.0i
.BI "wtime	" int
Specifies the time, in milliseconds, to allow in
the default timeout for each wait-for-dialtone
character in the dial string. Default is 10000
(10 seconds).
.TP 2.0i
.BI "dgttime	" int
Specifies the time, in milliseconds, to allow in
the default timeout for each digit character in
the dial string. Default is 100 (0.1 second).
.TP 2.0i
.BI "ctime	" int
Specifies the time, in milliseconds, to allow in
the default timeout for carrier to appear after
the dial string is sent. Default is 45000 (45
seconds).
.SH "SEE ALSO"
uucico(8) for Taylor UUCP, and documentation for Taylor UUCP.
.SH AUTHOR
Robert B. Denny (denny@alisa.com)
.SH CONTRIBUTORS
Daniel Hagerty (hag@eddie.mit.edu)
.SH HISTORY
This program is an adaptation of the dial/login script processing 
code that is a part of DECUS UUCP for VAX/VMS, written by Jamie 
Hanrahan, et. al.
.SH BUGS
This version (1.1) does not support BSD terminal facilities. Anyone 
volunteer to add this?