Chapter 149. CHAT Scripts

The automated conversational scripting supported by the eCos PPP package is a subset of the scripting language provided by the chat command found on most UNIX and Linux systems.

Unlike the chat command, the eCos cyg_ppp_chat() function takes as a parameter a zero-terminated array of pointers to strings. In most programs this will be defined by means of an initializer for a static array, although there is nothing to stop the application constructing it at runtime. A simple script would be defined like this:

static char *chat_script[] =
{
    "ABORT"        ,  "BUSY"        ,
    "ABORT"        ,  "NO CARRIER"  ,
    ""             ,  "ATD5551234"  ,
    "ogin:--ogin:" ,  "ppp"         ,
    "ssword:"      ,  "hithere"     ,
    0
};

The following sections have been abstracted from the public domain documentation for the chat command.

149.1. Chat Script

A script consists of one or more "expect-send" pairs of strings, separated by spaces, with an optional "subexpect- subsend" string pair, separated by a dash as in the following example:

    "ogin:--ogin:"     ,  "ppp"       ,
    "ssword:"          ,   "hello2u2" ,
    0

This script fragment indicates that the cyg_ppp_chat() function should expect the string "ogin:". If it fails to receive a login prompt within the time interval allotted, it is to send a carriage return to the remote and then expect the string "ogin:" again. If the first "ogin:" is received then the carriage return is not generated.

Once it received the login prompt the cyg_ppp_chat() function will send the string "ppp" and then expect the prompt "ssword:". When it receives the prompt for the password, it will send the password "hello2u2".

A carriage return is normally sent following the reply string. It is not expected in the "expect" string unless it is specifically requested by using the "\r" character sequence.

The expect sequence should contain only what is needed to identify the string. It should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, or other variable pieces of data as an expect string.

To help correct for characters which may be corrupted during the initial sequence, look for the string "ogin:" rather than "login:". It is possible that the leading "l" character may be received in error and you may never find the string even though it was sent by the system. For this reason, scripts look for "ogin:" rather than "login:" and "ssword:" rather than "password:".

A very simple script might look like this:

    "ogin:"    , "ppp"       ,
    "ssword:"  , " hello2u2" ,
    0

In other words, expect "….ogin:", send "ppp", expect "…ssword:", send "hello2u2".

In actual practice, simple scripts are rare. At the very least, you should include sub-expect sequences should the original string not be received. For example, consider the following script:

    "ogin:--ogin:"  , "ppp"     ,
    "ssword:"       , "hello2u2",
    0

This would be a better script than the simple one used earlier. This would look for the same "login:" prompt, however, if one was not received, a single return sequence is sent and then it will look for "login:" again. Should line noise obscure the first login prompt then sending the empty line will usually generate a login prompt again.

149.2. ABORT Strings

Many modems will report the status of the call as a string. These strings may be CONNECTED or NO CARRIER or BUSY. It is often desirable to terminate the script should the modem fail to connect to the remote. The difficulty is that a script would not know exactly which modem string it may receive. On one attempt, it may receive BUSY while the next time it may receive NO CARRIER.

These "abort" strings may be specified in the script using the ABORT sequence. It is written in the script as in the following example:

    "ABORT"    , "BUSY"    ,
    "ABORT"    , "NO CARRIER"  ,
    ""         , "ATZ"         ,
    "OK"       , "ATDT5551212" ,
    "CONNECT"  , …

This sequence will expect nothing; and then send the string ATZ. The expected response to this is the string OK. When it receives OK, it sends the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received the remainder of the script is executed. However, should the modem find a busy telephone, it will send the string BUSY. This will cause the string to match the abort character sequence. The script will then fail because it found a match to the abort string. If it received the string NO CARRIER, it will abort for the same reason. Either string may be received. Either string will terminate the chat script.

149.3. TIMEOUT

The initial timeout value is 45 seconds. To change the timeout value for the next expect string, the following example may be used:

    ""              , "ATZ"         ,
    "OK"            , "ATDT5551212" ,
    "CONNECT"       , "\\c"         ,
    "TIMEOUT"       , "10"          ,
    "ogin:--ogin:"  , "ppp"         ,
    "TIMEOUT"       , "5"           ,
    "assword:"      , "hello2u2"    ,
    0

This will change the timeout to 10 seconds when it expects the login: prompt. The timeout is then changed to 5 seconds when it looks for the password prompt.

The timeout, once changed, remains in effect until it is changed again.

149.4. Sending EOT

The special reply string of EOT indicates that the chat program should send an EOT character to the remote. This is normally the End-of-file character sequence. A return character is not sent following the EOT. The EOT sequence may be embedded into the send string using the sequence "\x04" (i.e. a Control-D character).

149.5. Escape Sequences

Most standard chat escape sequences can be replaced with standard C string escapes such as '\r', '\n', '\t' etc. Additional escape sequences may be embedded in the expect or reply strings by introducing them with two backslashes.

\\c
Suppresses the newline at the end of the reply string. This is the only method to send a string without a trailing return character. It must be at the end of the send string. For example, the sequence "hello\\c" will simply send the characters h, e, l, l, o. (not valid in expect strings.)