WinNET Mail and News (TM)
Copyright (c) 1992 - 1995 by WinNET Communications, Inc.
ALL RIGHTS RESERVED

Editing the chat script

If you are reading this while setting up WinNET  with
the setup program, you will probably also want to refer
to this file later when you edit your chat.rc file.


What is the chat.rc file?

The chat.rc file controls the log-in process between the
time that your modem connects to the remote site to the
time when the uucico (unix-to-unix-copy-in-copy-out)
protocol starts up.  (uucico is the basic mail/news
transfer program that handles data transfer under uucp).

A default chat.rc file is put in the directory where you
installed WinNET by the setup program.  The chat.rc that
is created by default may not be adequate to actually
log-in to your remote uucp site, so you'll have to
modify it so that it is complete.

When your modem connects and established a link/protocol
with the remote site, the remote site will start sending
various log-in prompts that your WinNET uucico module
needs to respond to successfully log-in.  In the
simplest type of log-in sequence, the remote site will
spawn some type of banner with information about itself
(such as the brand name of it's operating system and some
sort of welcome message), and then emit the prompt

login:

After receiving input for login, the remote will typically
then emit

password:

After receiving input for password, it will verify the
inputs and, if they are correct, start up its own uucico
and then mail / news transfer takes place.  

So, the chat.rc script is to control the scripting just of
this simple log-in phase.  However, in the 'real world',
the log-in process can become more complicated.  Many
uucp provider sites have several layers of logging in.  In
most cases, you have to log-in in 2 steps; first, you have
to log-in to a generic terminal server front end; after you
get past the terminal server, you can then log-in pretty
much as described above.  The precise sequence is
something that your uucp provider should be able to provide.

            Before Configuring your chat.rc File...

It is almost always a good idea to fire up a terminal
emulation program like Window's 'Terminal' or 'Procomm'
to directly dial the telephone number of your uucp provider
and try logging on to the remote system manually before
trying to configure chat.rc.

This exercise gives you a very clear idea of the behavior of
the remote system, and also allows you to verify that the
login name(s) and password(s) that your provider has given
you are actually correct.  

Doing this may well save you hours of exasperation trying
to configure your chat.rc file, particularly if you don't
have the correct login/password information to begin with! 

For uucp, you can tell that you've successfully logged-in
when you see the output:

    Shere=remote_name
    
from the remote site, where 'remote_name' is the machine
name of the remote system.  When you get this far, it
means that you've logged in completely, and the remote site
has permitted you access to uucico.  (You'll have to hang
up your modem at this point though, unless you know how to
manually enter the correct sequence to continue with
uucico!) 

Now, lets look at how the chat.rc script works.

The chat.rc script is designed to be able to do what you
could do manually if you called your uucp provider with a
terminal emulation program (like procomm or terminal for
Windows) and visually looked for the various prompts and
then typed in the proper inputs. In each case, you 'expect'
to see a prompt and then 'send' (type) the correct
response. The chat.rc file allows you the script these
expect/send pairs for up to 15 levels. 

For each prompt that is expected, you create an entry in
the chat.rc file.  Each entry consists of 2 lines, and each
entry is separated by a blank line.  Here is the syntax
format of an entry in chat.rc, followed by a realistic
example:

expect text
send text

; example entry
login:
$S\n

Let's break down each of the 2 lines in detail:

1. expect text

This line shows the literal text of the prompt that is
expected from the remote uucp site.  In most cases, this
will be case sensitive.  Spaces are acceptable, but it is
also fine just to use the last few characters of the
prompt if you know that these characters will not be
repeated in any of the other output from the remote.  Our
example expect text could usually be abbreviated as
'ogin:', for example.

2. send text

This line lists the text of what our system should
send to the remote as input for the prompt listed in the
expect text line.  The '$S' is a parameter in this example
is replaced with your UUCP system name.  This keeps your system
name from appearing in the chat script.

Often, other UUCP service providers use a different login
name than the system name.  If your login name is different,
you will need to edit the chat.rc file to put in the proper
login name.

It is also *crucial* to remember that the send text line will
almost always have to end with the correct line termination
character for the system you are connecting to (the
equivalent of hitting the ENTER or RETURN key of your
keyboard).  For this purpose, there are several special
characters that you can enter preceded by a backspace.  These
characters are not literal representations of the characters
that will be emitted to the remote site, but rather,
placeholders or symbols that will be replaced when the
program actually runs by the correct control characters. 
Presently, the following special characters are
implemented:

    \n      unix-style 'new line' character (ASCII 10)
    \r      carriage return (ASCII 13)
    \\      backslash
    \b      space character (you can enter a space directly,
            \b is just included to improve readability).
    \,      pause one second
    $S      insert system name
    $P      insert password
    $$      insert a single '$'

AS A RULE OF THUMB, IF YOU ARE CONNECTING TO A UNIX SYSTEM,
MAKE SURE TO TERMINATE EACH LINE OF THE SEND TEXT LINE
WITH A \n    IF THE SYSTEM YOU ARE CONNECTED TO IS *NOT* A
UNIX SYSTEM, INSTEAD TERMINATE EACH LINE OF THE SEND TEXT
LINE WITH A \r


Initiating Output

In some cases, when your modem connects to the remote site,
the remote site will not emit its prompts until it has
received some cueing or prompting from your system.  In most
cases where this is true, the remote will wait for one or
more end of line characters from your system before emitting
its first log-in prompt.  (If you called with a terminal
emulator, you'd have to hit the RETURN/ENTER key a few times
before seeing any output from the remote site).  This can
be tricky, because the number of carriage returns and the
interval of time between them can be unpredictable; it
doesn't always work exactly the same way twice! 
(Sometimes you have to hit ENTER twice, sometimes three or
four times).

To initiate unprompted output the chat.rc file provides a
special statement called the "INITIATE" statement.  The
syntax is:

INITIATE
send text

The send text line of the INITIATE statement can be
whatever you like, but in most situations where you would
want to use an INITIATE statement, it will be
something like \,\n\,\n\,\n\,\n which indicates
pause-newline-pause-newline-pause-newline,
pause-newline, a sequence that will sufficiently 'cue'
most terminal servers. 

Comments

You can put comments at the TOP of your chat.rc file.  Once
the script proper begins, NO comments are allowed. 
If you wish to put a comment(s) at the top of the
script, put a semi-colon character in column one of
each line that you intend as a comment.  It is also OK
to use blank lines in the chat.rc (with or without
comment semi-colons), up to the point where the script
actually begins -- BUT, once the script begins, blank
lines are syntactically significant, indicating the end
of an entry, so make sure that your entries are
separated by just 1 blank line once the script
begins. 

A Complete Sample chat.rc

; sample chat.rc
; the \,\r\, in the INITIATE statement indicates that
; the communications program should initiate the login
; process by pausing one second, issuing a carriage return
; character (ascii 13) and pausing again for one second.

INITIATE
\,\r\,

ogin:
$S\n

word:
$P\n



