ftp.wwiv.com

home *** CD-ROM | disk | FTP | other *** search

/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / PPPBCKP / PPPD11.ZIP / CHAT.MAN < prev next >

Wrap

Text File | 1997-09-14 | 25KB | 560 lines

PPPD for DOS 0.6 beta NAME chat - Automated conversational script with a modem SYNOPSIS chat [ options ] script DESCRIPTION The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point Proto- col packet driver (pppd.exe) and the remote's PPP process. DOS NOTES The DOS version incorporates two flavours of the program, one intended for use with the 'connect' option from pppd (chat.exe) and another for standalone use (chat0.exe). The chat.exe program requires that pppd.exe be present in memory, as its access to COM ports is done through a private interface via the packet driver interrupt. The chat0.exe program directly accesses COM ports and leaves the DTR line high after exiting, in much the same way that kermit and other DOS terminal programs do when quitting without resetting the COM port. This means that chat0.exe accepts options for selecting a port, while chat.exe gets whatever port pppd.exe is using. If you don't specify a COM port with chat0.exe, COM1 is used by default. The OPTIONS sections will note options that are applicable to both executables and those that are applicable to chat0.exe only. The command line parsing done by DOS C compilers is quite different from *NIX regarding quotes. It means that you must use "" for quoting strings with embedded blanks and '' for inserting empty strings. It seems that the empty string "" doesn't store a null argument under DOS, which will cause the CHAT script not to work as intended. Some examples are in oder: "CONNECT 14400" generates the single string CONNECT 14400. "" no string is generated, the C startup code simply skips these. '' generates one single string which is empty. \"\" generates one single string which is empty. 'CONNECT 14400' tries to generate two strings, CONNECT and 14400', causing an unterminated quote error. '\"CONNECT 14400\"' tries to generate two strings, "CONNECT and 14400", causing an unterminated quote error. "'CONNECT 14400'" generates the single string CONNECT 14400. "\'CONNECT 14400\'" generates the single string 'CONNECT 14400'. "'\"CONNECT 14400\"'" generates the single string "CONNECT 14400". This change in behavior doesn't apply when reading the CHAT script from a file, because the program code is in charge of interpreting the characters and neither DOS nor the C compiler interferes with it. OPTIONS -p <COMn> (CHAT0.EXE only) Specifies the COM port to use for communicating with the modem. Ports COM1 through COM4 can be used; the standard base address and IRQ are asssumed unless you change the default with other options. Basic testing (through BIOS) is done to ensure COM availability. If chat0 fails with message: Invalid COM device COM? Then probably you have a non standard COM port setup. Omit the -p option from configuration and specify COM port values with the following two options, -b and -i. -b <port base> (CHAT0.EXE only) Specifies the base address for the COM port, in the event that it is a non-standard one. The number can be entered in hex, octal or decimal, following the C language rules for parsing numbers (0xnnn is hex for example). No attempt is made to verify that a valid COM port exists at the address, so use this option with care. -i <IRQ number> (CHAT0.EXE only) Specifies the IRQ number used by the COM port. The same considerations as above apply. -s <baud rate> (CHAT0.EXE only) Specifies the speed for modem to computer communication. Up to 115200 baud can be programmed, but beware that serial ports that have the old 8250 UART cannot handle speeds higher than 9600 reliably. The number can be entered in hex, octal or decimal, as in the above options. -f <chat file> Read the chat script from the chat file. The use of this option is mutually exclusive with the chat script parameters. Multiple lines are permitted in the file. Space or horizontal tab characters should be used to separate the strings. -t <timeout> Set the timeout for the expected string to be received. If the string is not received within the time limit, then the reply string is not sent. An alternate reply may be sent, or the script will fail if there is no alternate reply string. A failed script will cause the chat program to terminate with a nonzero error code. -r <report file> Set the file for output of the report strings. If you use the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use REPORT keywords, the stderr file is used for the report strings. -e Start with the echo option turned on. Echoing may also be turned on or off at specific points in the chat script by using the ECHO keyword. When echoing is enabled, all output from the modem is echoed to DOS standard error device. -v Request that the chat script be executed in verbose mode. The chat program will log all text received from the modem, and the output strings sent, to DOS standard output, which can be redirected. -V Request that the chat script be executed in stderr verbose mode. The chat program will then log all text received from the modem, and the output strings sent, to the DOS standard error device. This device is usually the local console at the station running the chat or pppd program. script If the script is not specified as a file with the -f option then the remaining parameters are taken as the script. CHAT SCRIPT The chat script defines the communications. 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:-BREAK-ogin: ppp ssword: hello2u2 This line indicates that the chat program should expect the string "ogin:". If it fails to receive a login prompt within the time interval allotted, it is to send a break sequence to the remote and then expect the string "ogin:". If the first "ogin:" is received then the break sequence is not generated. Once it receives the login prompt, the chat program 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. Chat scripts always begin at the 'expect' condition, so a nul '' expectation should be used as the first string if no response is to be received from the modem when the script begins execution. This is the most common case. Some "expect-send" strings are interpreted in a special way by chat, like report strings, abort conditions and a few others, more on this later. A carriage return is normally sent following the reply string. It is not expected in the "expect" string unless it is specifically indicated by using the \r character sequence. The expect sequence should contain only what is needed to identify the string. Since it is normally stored in a disk file, 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 that 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 In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2. In actual practice, simple scripts are rare. At the vary least, you should include sub-expect sequences in case the original string is not received. For example, consider the following script: ogin:--ogin: ppp ssowrd: hello2u2 This would be a better script than the simple one used earlier. This would look for the same "login:" prompt; if one were not received, a single return sequence would be sent, and then chat would look for "login:" again. Should line noise obscure the first login prompt, sending the empty line will usually generate another login prompt. 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 will 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, as in the following example: ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT This sequence will expect nothing and send the string ATZ. The expected response to this is the string OK. When chat receives OK, the string ATDT5551212 dials 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, matching the abort character sequence. The script will then fail because it found a match to the abort string. If it receives the string NO CARRIER, it will abort for the same reason. Either string may be received. Either string will terminate the chat script. REPORT STRINGS A "report" string is similar to an abort string. The difference is that the strings, and all characters up to the next control character (such as a carriage return), are written to the report file. The report strings may be used to isolate the transmission rate of the modem's connect string and return the value to the chat user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the expect string. The use of the same string for a report and abort sequence is probably not very useful, however, it is possible. The report strings do not change the return code of the program. These report strings may be specified in the script using the REPORT sequence, as in the following example: REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account This sequence will expect nothing and send 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. In addition the program will write to the expect file the string "CONNECT" plus any characters which follow it, such as the connection rate. ECHO The ECHO keyword controls whether the output from the modem is echoed to stderr. This behavior may be specified with the -e option, but it can also be controlled using the ECHO keyword. The "expect-send" pair ECHO ON enables echoing, and ECHO OFF disables it. With this keyword you can select which parts of the conversation should be visible. For instance, with the following script: ABORT 'BUSY' ABORT 'NO CARIER' '' AT&F OK\r\n ATD1234567 \r\n \c ECHO ON CONNECT \c ogin: account ... all output resulting from modem configuration and dialing is not visible, but starting with the CONNECT (or BUSY) message, everything will be echoed. TIMEOUT The initial timeout value is 45 seconds. This may be changed using the -t parameter. To change the timeout value for the next expect string, the following example may be used: ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2 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. INTERACTIVE MODE A very basic terminal mode can be entered by using the TERMINAL ON keyword combination. It only understands ASCII keystrokes and BACKSPACE, so don't expect a full blown ANSI terminal emulator. It might be useful for completing login sequences, consider the following example: ABORT 'BUSY' ABORT 'NO CARIER' '' AT&F OK\r\n ATD1234567 CONNECT \c TERMINAL ON '' After receiving the CONNECT string, chat goes into terminal mode and you can manually log into the remote system. When you are done, press ESC and the chat script resumes. As the next expect-send pair expects nothing, the chat script ends with a success exit code. Note how TERMINAL ON is introduced at a point of the script where you should normally place an expect string, this is a requeriment for a proper interpretation of the command. The example shown satisfies this requeriment by using \c as the send string in the line above TERMINAL ON, it means that nothing is sent after receiveing the CONNECT string, but the send part of the expect-send pair is completed and chat looks for an expectation as the next string. GRABBING VALUES SENT BY REMOTE Some login procedures send back useful information about the connection when you stablish a connection. This is the case for SLIP logins, where the local and remote IPs are sent by the remote after succesful login. You definately want to get this information, in order to proper configure your Internet software. For helping in such situations, a few directives was added to chat scripting language. What these directives do is create a DOS batch file which can be run after chat script completion for setting environment variables with the values received through the wire. These directives are: GRABIP varname GRABNUM varname GRABSTR varname The varname argument specifies the name of the environment variable that will receive the collected value. Each GRABxx directive is specialized in parsing determined text formats like IP numbers, decimal numbers and generic strings. They always parse words, so leading whitespace is discarded and the scan stops at the first trailing withespace. Lets see and example: ABORT 'BUSY' ABORT 'NO CARIER' '' AT&F OK\r\n ATD1234567 CONNECT '' ogin: myuserid assword: hello2u2 GRABIP MYIP '' '' GRABIP REMIP 'now.' After the CONNECT expectation, the nul string sends a CR to the remote. A normal *NIX login sequence follows, then the GRABIP directive is used for retrieving the local IP which the remote sends after login. The line below expects nothing and sends a CR, and GRABIP directive is used again for retrieving the remote IP. The script ends by expecting "now." which is the tail for the string "SLIP begins now." sent by the remote after starting his end SLIP process. The same rules for TERMINAL ON applies here, the GRABxx directives should start at an expectation point in the chat script, and they must be continued by an expectation string too. When the chat script ends, you should have a CHATENV.BAT file which looks like: set MYIP=192.168.1.1 set REMIP=192.168.1.2 By executing this batch file, you get the desired values into the MYIP and REMIP environment variables. 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 ^D. GENERATING BREAK The special reply string of BREAK will cause a break condition to be sent. The break is a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. It may be used to cycle through the available transmission rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded in the send string using the \K sequence. ESCAPE SEQUENCES The expect and reply strings may contain escape sequences. All of the sequences are legal in the reply string. Many are legal in the expect. Those which are not valid in the expect sequence are so indicated. '' Expects or sends a null string. If you send a null string, it will still send the return character. This sequence may be either a pair of apostrophes or a pair of quote characters. \b represents a backspace character. \c Suppresses the newline at the end of the reply string. This is the only method of sending 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.) \d Delay for one second. The program uses sleep(1) which will delay to a maximum of one second. (Not valid in expect.) \K Insert a BREAK (not valid in expect). \n Send a newline or linefeed character. \N Send a null character. The same sequence may be represented by \0. (Not valid in expect.) \p Pause for a fraction of a second. The delay is 1/10th of a second. (Not valid in expect.) \q Suppress writing the string to the SYSLOG file. The string ?????? is written to the log in its place. (Not valid in expect.) \r Send or expect a carriage return. \s Represents a space character in the string. This may be used when it is not desirable to quote the strings which contains spaces. The sequence 'HI TIM' and HI\sTIM are the same. \t Send or expect a tab character. \\ Send or expect a backslash character. \ddd Collapse the octal digits (ddd) into a single ASCII character and send that character. (Some characters are not valid in expect.) ^C Substitute the sequence with the control character represented by C, where C is a printable character. For example, the character DC1 (17) is shown as ^Q. (Some characters are not valid in expect.) TERMINATION CODES The chat program will terminate with the following completion (return) codes. 0 Normal termination of the program. This indicates that the script was executed without error to a normal conclusion. 1 One or more of the parameters are invalid, or an expect string was too large for the internal buffers. This indicates that the program was not properly executed. 2 An error occurred during the execution of the program. This may be due to a read or write operation failing for some reason or chat receiving a signal such as SIGINT. 3 A timeout event occurred when there was an expect string without having a "-subsend" string. This may mean that you did not program the script correctly for the condition, or that some unexpected event has occurred and the expected string could not be found. 4 The first string marked as an ABORT condition occurred. 5 The second string marked as an ABORT condition occurred. 6 The third string marked as an ABORT condition occurred. 7 The fourth string marked as an ABORT condition occurred. ... The other termination codes also indicate strings marked as an ABORT condition. Using the termination code, it is possible to determine which event terminated the script. It is possible to decide if the string "BUSY" was received from the modem as opposed to "NO DIAL TONE". While the first event may be retried, the second will probably have little chance of succeeding during a retry. AUTHORS DOS port by Antonio Lopez Molero, <tonilop@redestb.es>. NOTES You can use CTRL+BREAK to abort the program before CHAT script interpretation is done. An exit code of 2 is returned in that case. Note that CTRL+C may not work, use CTRL+BREAK. COPYRIGHT The chat program is in the public domain. This is not the GNU public license. If it breaks then you get to keep both pieces.