Meeting Pearls 3/Meeting_Pearls_III.iso/Pearls/comm/Internet/IPDial/IPDial.doc

Text File | 1995-07-22 | 14KB | 402 lines

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: [e-mail]


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="\r" 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<return>

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<return>

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 <ECHO> <VERBOSE>
    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.