xchat

Section: Maintenance Commands (8)
Index Return to Main Contents

NAME

xchat - Extended chat processor

SYNOPSIS

xchat scriptfile [ parameter... ]

where scriptfile is the name of a file containing an xchat script. If 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 /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.

DESCRIPTION

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.

When used in conjunction with Taylor UUCP's configuration features, 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.

Because 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 uucico log and debug files.

Formally, a script describes a state machine; 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 xchat.

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.

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.

Processing always begins at the head of the script (no leading state name is necessary).

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.

A transition to another state may occur for any of three reasons:

(1): 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.
(2): 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.
(3): 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.

Finally, there are two action statements which, when executed, cause the script to exit.

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''.

Some statements accept one or two arguments, referred to in the following descriptions as int, ns, str, or xstr, to indicate whether the argument is an integer, a new state name, a string, or an ``extended string'' (described in a later section).

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.

Termination And Informational Statements

These statements are used to place entries into the Taylor UUCP Log file, and to cause xchat to exit with successful or failure status. It is also possible to open a separate 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 xchat scripts.

failed: Exit script with ``failed'' status. This causes xchat to exit with status 0.
success: Exit script with ``success'' status. This causes xchat to exit with status 1.
log xstr: Send informational message
xstr to standard error. When used with Taylor UUCP, this is the Log file for the uucico program.
logerr xstr: Send message
xstr to standard error, with ``ERROR:'' indicator. When used with Taylor UUCP, this is the Log file for the uucico program.
dbgfile xstr: Open script debugging file
xstr. If 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 /usr/spool/uucp ) is prepended to 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 debug mask, described next. Note: A new log file is created each time xchat runs. Use the log and loge commands to log continuous information onto standard out, which is connected to the Taylor UUCP Log file when xchat is run by the Taylor uucico.
dbgset int: Set the bits specified in
int in the debugging mask. The value in 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.
dbgclr int: Clear the bits specified in
int from the debugging mask.
debug xstr: Write
xstr into the debug log. The entry will be enclosed in angle brackets.
debuge xstr: Write
xstr into the debug log with ``ERROR: '' prepended. The entry will be enclosed in angle brackets.

Sending Data

These statements are used to transmit data to standard out (the tty or TCP port when used with Taylor UUCP). No implied carriage returns are sent. You must include a \r if you want a carriage return in the string sent by the send command. If you want a return sent after dial or sendstr, you must send it with a separate send command.

dial: Send the string previously set by the telno command to the serial port. W and P characters in the phone number are converted as described under Dial Strings, below. This statement also sets a default timeout value, as described under the timeout statement.
send xstr: Send the string
xstr to the serial port.
sendstr int: The argument of this statement is a digit from 0
through 7. Send the corresponding string parameter as passed to xchat following the script file name. The parameter is interpreted as an extended string.

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. The modes of the port are restored to their original settings by xchat before it exits.

flush: Flush the terminal port's input buffer.
break: Send a break signal.
hangup: Momentarily drop Data Terminal Ready (DTR) on the serial port, causing the modem to hang up. (Not usually needed, since uucico does this at the end of each call.)
7bit: Change the port to strip incoming characters to 7 bits. This is the default mode. This mode is implied when the port has parity enabled, since parity characters are 7-bits wide.
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.
nopar: Change the port to 8-bits, no parity. This is the default mode.
evenpar: Change the port to 7-bits, even parity. Incoming characters with parity errors are discarded.
oddpar: Change the port to 7-bits, odd parity. Incoming characters with parity errors are discarded.

Counting, Branching, Timing and Testing Statements

These statements are used to control the flow of the xchat script itself, including branching, delays, and counter manipulation.

sleep int: Delay for
int milliseconds.
zero: Clear the counter.
count: Add one to the counter.
ifgtr ns int: Go to state
ns if counter greater than int.
goto ns: Go to state
ns unconditionally.
ifstr ns int: Go to state
ns if string parameter int is nonempty.
ifnstr ns int: Go to state
ns if string parameter int is empty.
ifblind ns: Change to state
ns if the port is ``blind'' without carrier (CD) asserted. This is not yet implemented, the test always fails.
ifblgtrnsint: Change to state
ns if the port is ``blind'' without carrier (CD) asserted, and counter is greater then int. This is not yet implemented, the test always fails.

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''.

expect ns xstr: Change to state
ns if the string specified by xstr is received from standard input (usually the serial port). Case is significant, but high-order bits are not checked.
expectstr ns int: Change to state
ns if the string specified in parameter int is received from standard input (usually the serial port). 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.
ifcarr ns: Change to state
ns if Carrier Detect (CD) is true. Not currently implemented. Always changes state.
ifhangns: Change to state
ns if a data set hangup occurs (SIGHUP signal received).
timeout ns int: Change to state
ns if the time (in milliseconds) given by 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.

SCRIPT PROCESSING DETAILS

Extended Strings

In the statements that accept string arguments, the strings are interpreted as 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.

Within an extended string, the following ``escape sequences'' will be converted as indicated before being sent or expected:

\d        EOT character (control-D)
\N        null character
\n        line feed
\r        carriage return
\s        space
\t        tab
\-        hyphen
\\        backslash
\ooo      character with value ooo (in octal)

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.

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''.

Extended strings are stored without a trailing carriage return unless one is explicitly present in the string (via \r).

String Parameters

The sendstr statement sends (after conversion from extended string format) one of the parameters given on the xchat command line following the script file name. The parameter is selected by the integer argument of the statement.

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.

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 command; the script can test for this parameter's existence and skip the password sequence if the parameter is empty.

``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 W and P within a dial string are interpreted as ``wait for dial tone'' and ``pause'', and may be converted to other characters. By default, W is left alone, and P is converted to a comma (,); these are appropriate for Hayes-type modems. The script may specify other substitutions (see below).

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 xchat you should put W and P in the dial strings you specify in the Taylor configuration files. This way, the xchat processor can make the substitution appropriate for the particular modem in use. Make a separate xchat script for each modem type, e.g., 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.

Default Timeouts For Dial Strings

When a 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.

The default timeout is given by:

ctime + (ndigits * dgttime) + (nwchar * wtime) + (npchar *  ptime)

where ndigits, nwchar, and npchar are the number of digits, wait characters, and pause characters in the dial string, and ctime, dgttime, wtime, and 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.''

Trailing Carriage Returns Not Assumed

In the dial and 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.

OVERRIDING DEFAULTS

The script processor sets several default values. The following statements, which override these defaults, may be useful in certain circumstances.

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).
pchar str: Specifies the character to which
Ps in the dial string should be converted. Default is ``,'', for use with Hayes-type modems.
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).
wchar str: Specifies the character to which
Ws in the dial string should be converted. Default is ``W'', for Hayes modems.
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).
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).
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).