Short: SLIP dialer; stdin/out terminal program Author: wiedmann@neckar-alb.de Uploader: wiedmann@neckar-alb.de Type: comm/tcp IPDial - serial device communication program ============================================ IPDial is designed especially for creating a SLIP connection via the modem to a remote host: It can dial the remote hosts number, login into the host and initilize a SLIP connection. Configuring IPDial is rather easy, as it reads its command from a textfile. 1.) Disclaimer: Copyrights, (No) Warranty ----------------------------------------- This program is Copyright (C) 1994 Jochen Wiedmann Am Eisteich 9 72555 Metzingen Germany Phone: (0049) +7123 / 14881 Mail: wiedmann@neckar-alb.de Permission is granted to make and distribute either verbatim and modified copies of this documentation and the program IPDial provided the copyright notice and this permission notice are preserved on all copies and the "GNU General Public License" (in the file COPYING) is distributed as well. The author gives ABSOLUTELY NO warranty that the program described in this documentation and the results produced by them are correct. The author cannot be held responsible for ANY damage resulting from the use of this software. 2.) Installation ---------------- Rather simple. Just copy the program to a place in your path and edit the two files "login.script" and "hangup.script". (See Script file syntax below for details.) You might want to enter the line IPDial login.script at the beginning of AmiTCP's startnet script. Thus you get a SLIP connection by simply typing startnet. Similar you could add the line IPDial hangup.script at the bottom of the stopnet script. 3.) Invocation -------------- IPDial is started like this: IPDial SCRIPT,ECHO/S,VERBOSE/S,TERMINAL/S,DEVICE/K,PROTOCOL/K, UNIT/K/N,BAUD/K/N,RAW/S What IPDial does, depends on the TERMINAL switch: If this is active, the arguments DEVICE, UNIT, BAUD and PROTOCOL are used to open the serial.device. Once it is opened, the program acts as a very simple terminal program. See the "terminal" command for an explanation of the RAW argument. If TERMINAL is omitted, the given SCRIPT is read and the commands of the script are executed line by line. (See below) The argument ECHO instructs IPDial to print the modems replies to stdout, while VERBOSE is used to show what the program's doing. 4.) Script file syntax ---------------------- - Any line of the script file may contain only one command. In general command arguments are parsed with ReadArgs(), thus they may look like CLI command line arguments: The characters "" may surround a string which contains blanks. Note, that ReadArgs() treats the character '*' as an escape sequence: Thus you have to write ECHO "**" if you want to print a single '*'. - Empty lines or lines beginning with a semicolon are assumed to be comments and thus ignored. - Lines may begin with a label, an alphanumeric word followed by a colon. Labels are ignored, except that they may be used as destinations for "goto" instructions. (Anyone said BASIC? Yes, it is. :-) Labels are case-sensitive. - This is the list of possible commands: DEVICE NAME/A,PROTOCOL,UNIT/K/N Opens the given device NAME with unit UNIT (Default 0). This must be compatible to the serial.device. PROTOCOL may be one of XONXOFF, RTSCTS, 7WIRE (Synonym for RTSCTS) or NONE. Note that explicitly requesting a protocol overwrites the defaults set by the Derial preferences program. The DEVICE command should in general be the first command of each script. SET BAUD/N/K,DATABITS/N/K,STOPBITS/N/K,BUFSIZE/N/K,PARITY/K This command is used to modify the serial.device parameters. Note, that these overwrite the Serial preferences. Possible parameters are: BAUD baud rate DATABITS number of databits STOPBITS number of stopbits BUFSIZE read buffer size PARITY one of ODD, EVEN or NONE SHOWPARMS Writes the current serial.device settings to stdout. ECHO ARGS/M This will write the given ARGS to stdout. Note, that these strings may contain patterns like \r (Carriage Return), \n (Line Feed), \\ (Backslash :-) or \037 (octal digits, representing the character ASCII 31.) The arguments are separated by blanks, when they are printed. Sequences like $VAR or ${VAR} will be replaced with the value of the environment variable VAR. (Empty string, if VAR doesn't exist.) Use $$ to get the $ character itself. Note, that $VAR will only work, if the name VAR consists of alphanumeric characters only and the name is separated with a non-alphanumeric character from the following. For example, $VAR+NAME means $VAR and not $VAR+NAME. On the other hand $VARNAME means $VARNAME and not $VAR. (Obvious reason. :-) Note that ECHO does not write any Line Feeds or Carriage Returns unless you explicitly request it with the respective patterns. SEND ARGS/M This command sends the given strings to the serial.device using DoIO(). These strings may contain the same patterns as described with the ECHO command. Unlike ECHO the arguments aren't separeted by blanks. See ECHO for a description of patterns that may be inserted into SEND arguments. DELAY SECS/A Delays the given number of seconds. The value may contain a fraction of seconds which is rounded to ticks: 0.5 means 25 ticks. WAIT TIMEOUT/K/N/A,ARGS/M This command waits until either one of the given strings is read from the serial.device or the number of seconds given by TIMEOUT has gone. A variable called STATUS indicates what happened: It contains either -1 for timeout or the number of the string that was read, beginning with 0. This variable may be used by the ON statement. WAIT arguments are parsed like ECHO arguments. (See above.) SCAN FORMAT/A,GLOBAL/S,SAVE/S Used to scan the buffer read by the last "WAIT" command for certain words. These may be used set environment variables. The format string may contain the following patterns: %{WORD%} Ignores any characters until WORD is found in the buffer. Use %% to insert the '%' character into WORD. ' ' Ignores any number (including 0) and kind (blank, tab, line feed, carriage return, form feed) of white space characters. %[VAR%]%(SUFFIX%) Reads the next word from the buffer until the first white space character and stores it into the environment variable VAR. The optional SUFFIX is a sequence of characters to be removed from the end of the word. Any other characters in the format string are simply ignored. Usually environment variables are local (for IPDial and child processes only). Use the GLOBAL and SAVE keywords to store them in ENV: and ENVARC:, respectively. Note, that SAVE implies GLOBAL. Note, that you can use the SCAN command more than once on the same buffer. Example: SCAN "%{Your IP address is%} %[IPADDRESS]%%(.%)" Scans the buffer for a sentence like Your IP address is 145.2.1.34. and stores the value 145.2.1.34 into the variable IPADDRESS. Note, that the character '.' is removed. The SCAN command stores the number of created environment variables in the STATUS variable, which can later be used by the ON command. Note, that the value -1 is never stored in the STATUS variable, you have to use a dummy label in the ON command. ON STATUS GOTO LABELS/M There's currently only one version of the ON command. An ON command must follow a WAIT or SCAN command. ON reads the value of the STATUS variable and jumps to the first label, if STATUS is -1, to the second label, if STATUS is 0 and so on. A typical use of WAIT/ON looks like this: WAIT TIMEOUT=10 "Login:" "Busy" ON STATUS GOTO TimeOut Login Busy TimeOut: ECHO "Timeout happened, aborting.\n" EXIT 10 Busy: ECHO "Remote busy, delaying...\n" DELAY 25 ECHO "Trying again.\n" GOTO DialAgain Login: ; Execute the login procedure You do not need to supply a label for any wait string: This will suppress jumping and instead continue on the next line. GOTO LABEL/A Jumps to the given label TERMINAL NOECHO/S,RAW/S,EOF Enters terminal mode: What you enter at the keyboard will be sent to the serial.device and likewise the program will display any input from the serial.device to you. The TERMINAL command will be finished, if you enter EOF (Ctrl-\). The NOECHO and EOF options can be used to enter a password, if you don't like to include it into your login file: NOECHO makes your input invisible and the EOF string terminates terminal mode as soon, as you type in the first character of the string. Thus you can do something like WAIT TIMEOUT=10 "Password:" ON STATUS GOTO TimeOut Password Password: ECHO "Enter login password: " TERMINAL EOF="\n" NOECHO Usually you can send only complete lines to the modem, especially this means that you have all editing capabilities of the shell available. This is not the case in RAW mode: Every character you type will be sent immediately to the modem without any buffering or conversions. Notes: - You probably must put your modem into NOECHO mode too, if you use the "terminal" command for entering a password. - NOECHO mode implies RAW mode SYSTEM ARGS/M Executes the command given by ARGS. The arguments will be parsed like ECHO and SEND arguments (you may insert \ and $ patterns) and separated by blanks. The resulting string will be executed. For example SYSTEM "Echo" "Hello!" will execute the command "Echo Hello!" and not "EchoHello!". EXIT RESULT Terminates the program, returns the given RESULT. (Defaults to 0.) SETVAR NAME/A,VALUE/A,LOCALONLY/S,GLOBAL/S,SAVE/S Sets environment variable NAME to VALUE. If you set the GLOBAL switch, your variable will be set in ENV: and not in the programs local environment. The SAVE switch forces copying to ENVARC:. Note, that SAVE implies GLOBAL. Commands are case-insensitive. See the scripts Login.IPDial and Hangup.IPDial as examples. 5.) How to create a script file? -------------------------------- Enter the terminal mode. You should now be able to type commands like ATZ If all goes well, the modem should reply ATZ OK provided, that it is in echo mode. Now try to dial into your remote host with something like ATDP07071927920 If the remote host's phone line isn't busy, you should eventually see the remote's login message. This message should explain what to do. Try it and log out. Now have a look at Login.IPDial, in general you should understand how to edit it. 6.) Recommended Usage --------------------- Each time you reconfigure AmiTCP, it will destroy your startnet script. Thus it is not a good idea to modify the startnet script. Instead create a scriptfile, say "neton", which could look as follows: .key ECHO/S,VERBOSE/S IPDial Work:lib/Login.script If NOT WARN startnet EndIf Likewise, create a script "netoff" like this stopnet IPDial Work:lib/Hangup.IPDial And, from now on, use "neton" and "netoff" instead of "startnet" and "stopnet". 7.) History ----------- I never expected IPDial to become a little bit popular. However, the number of questions and/or enhancement requests forced new versions: This is 1.6 now. Time for a history, as people might like to know what's different. V 1.1 23.11.94 Initial version V 1.2 27.02.95 Added terminal mode Now using ReadArgs() for command line parsing. V 1.3 09.03.95 Added environment variable aupport to "send" command. Added unit support. Suggested by Quarvon (Jürgen Lang) V 1.4 21.04.95 Added "system" command. Suggested by Gutgolf (Michael Bauer) Added environment variable support to "echo" command. Terminal mode now converts LF to CR/LF, so that modem recognizes commands. (Let's hope, that will still work for entering passwords. :-( V 1.5 30.04.95 Added "scan" command. V 1.6 26.06.95 "delay" command supporting ticks; ParseString() supporting octal characters; "wait" command using ParseString() Suggested by Will Bow. Fixed bug in SerialSend(): *.io_Device = *.io_Unit V 1.7 21.07.95 Added NOECHO, RAW and EOF options to "terminal" command. Suggested by Klaus Heinz Added BAUD option to command line. Added "setvar" command. ============================= Archive contents ============================= Original Packed Ratio Date Time Name -------- ------- ----- --------- -------- ------------- 5188 2023 61.0% 21-Jul-95 17:19:34 +Buffer.c 17982 6993 61.1% 26-Mar-95 20:18:16 +COPYING 4474 1674 62.5% 21-Jul-95 17:19:02 +DeviceIO.c 3891 1271 67.3% 26-Jun-95 19:41:16 +DMakefile 1818 767 57.8% 21-Apr-95 15:38:44 +Hangup.IPDial 27760 15536 44.0% 22-Jul-95 11:53:16 +IPDial 23001 6557 71.4% 22-Jul-95 11:52:28 +IPDial.c 3079 1188 61.4% 21-Jul-95 17:18:42 +IPDial.h 12647 5421 57.1% 22-Jul-95 11:49:58 +IPDial.readme 4223 1480 64.9% 01-May-95 20:32:50 +Login.IPDial 15050 4304 71.4% 21-Jul-95 17:20:24 +Serial.c 2082 1083 47.9% 22-Jul-95 11:50:40 +setvar.c 2102 1031 50.9% 21-Jul-95 17:19:54 +StrReadArgs.c 4544 1926 57.6% 21-Jul-95 17:19:20 +vsscanf.c -------- ------- ----- --------- -------- 127841 51254 59.9% 01-Aug-95 22:20:52 14 files