SCRIPT

NAME

SYNOPSIS

DESCRIPTION

Script files consist of a series of lines, each of which contains a command word and zero or more arguments. The list of commands below shows which arguments are required for each command:

# comment...

Any blank line or line beginning with ``#'' is treated as a comment and is ignored.

{ 
   alternate
       # commands
   .
   .
   .
   alternate
       # commands

}

A sequence of commands enclosed by curly-braces is called a ``select block''. The curly-braces must appear by themselves on separate lines. A ``select block'' is composed of one or more ``alternate blocks''. An ``alternate block'' consists of a line containing the command name, alternate, and then some lines containing script commands. An ``alternate block'' is delimited by the start of another ``alternate block'' at the same level (``select blocks'' can be nested) or by the end of the current ``select block''.

The order of command execution within a ``select block'' follows some special rules. Control begins with the first command in the first ``alternate block''. If that ``alternate block'' terminates successfully, then control jumps to the command following the ``select block''. If any recv command in the ``alternate block'' times out, then control passes to the next ``alternate block'' in sequence. Successive ``alternate blocks'' are executed until one completes successfully (i.e. no timeouts). If no more ``alternate blocks'' are available, processing terminates with a FATAL error. For example, the following script excerpt uses a ``select block'' to send a ``break'' if no ``login'' prompt appears within 30 seconds:

        xmit "\r\r"
        {
        alternate
                recv "login" 30
        alternate
                xmit "\#"
                recv "login" 30
        }
        xmit "accountname\r"

abort

This command causes processing of the script file to cease. A FATAL error is returned.

alternate

This command marks the start of an ``alternate block'' (see the { ... } command above).

dial phone-number-spec [, phone-number-spec... ]

This command causes the number(s) given by the phone-number-spec's to be dialed or a connection via a direct line to be made. More than one phone-number-spec may be given, separated by commas. Each phone-number-spec has the general form:

      speed|<type>phone-number

The speed parameter is the baud rate at which the connection should be made (from the set: 50, 75, 110, 134.5, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600). The baud rate is separated from the rest of the phone-number-spec by a vertical bar, `|'.

The optional <type> specifies the line-type to use. If <type> is omitted, it defaults to ``LOCAL''. Note that the angle-brackets are part of the syntax and must surround the type to separate it from the rest of the phone-number-spec.

A phone-number is composed of a series of digits, in addition to the characters `(', `)', `-', and `:'. Parentheses and dashes are ignored, and may be used freely to enhance readability. The colon indicates that the dialer should await a secondary dial tone before proceeding with the dialing. This is used with phone systems that use preliminary digits to access outgoing lines, tie lines, etc.

If the phone-number-spec begins with a letter, it is taken to be the name of a direct connect line. The names and speeds of these lines are predefined. See the "Installing and Operating MMDFII" document for information about defining these lines.

Up to five phone-number-spec's can be given on a single dial command. If a connection cannot be made using the first number, succeeding phone-number-spec's will be tried in the order given before a failure is indicated. For example, the following command:

      dial 1200|738-2928, 300|738-8003

would initiate a call to the first number (738-2928) at 1200 baud. If the connection failed, it would try the second number (738-8003) at 300 baud.

The dial command also clears the input buffer to prevent rewinding by the replay command. See the explanation of the replay command below.

end

This command causes the terminal line to close and interpretation of the script file to cease.

go

This command is a synonym for the start command (see description below).

log message

This command causes message to be written into the ph.log file. Message should be a quoted string if it contains spaces.

mark

As data is read from the remote system, it is collected into a buffer. This buffer can be rewound and examined by the replay command (see below). Executing the mark command clears this input buffer. The dial command also clears the input buffer.

nrexmit retries

This command sets the maximum number of times to retransmit a given packet to the remote system in the event of failure to receive an acknowledgement within the timeout period (set with the waitack command). Retries must be greater than zero; five is the default.

prompt promptvalue

This command sets the character expected as the prompt to wait for before transmitting data to the dial-out or direct-connect line. Promptvalue is a decimal number giving the ASCII value of the prompt. If the prompt hasn't appeared within 10 seconds of a transmission attempt, the connection will be dropped. This command is used when running on half-duplex lines where the prompt indicates that writing is enabled.

replay

This command causes the input buffer to be rewound to the time of the most recent dial or mark command. The next recv command will then look at data which may have already been examined by previous recv commands. The ability to replay the input stream is useful for adapting intelligently to a selection of messages from the remote system. For example, the following script segment will connect to either line "A" or line "B" in a simple terminal switch:

        recv "Request"
        mark
        {
        alternate
                xmit "A\r"
                recv "A-Connected" 30
        alternate
                replay
                recv "A-Busy" 1
                log "A was busy-trying B"
                xmit "B\r"
                recv "B-Connected" 30
        alternate
                log "Both A and B were busy"
                abort
        }

Note that a small timeout value was given on the recv command which followed the replay command. A small value is adequate since the ``A-busy'' string, if received, will already be present in the input buffer.

recv quoted-string timeout

This command causes the interpretation of the script file commands to pause until quoted-string is received from the remote system. The timeout specifies the maximum number of seconds to wait for quoted-string before aborting with an error. This argument must be present and must be greater than zero seconds. Quoted-string is a string of characters surrounded by double-quotes and possibly containing any of these escape sequences:

\b      -        backspace (ASCII 8)
\f      -        form feed (ASCII 12)
\n      -        newline or line feed (ASCII 10)
\r      -        carriage return (ASCII 13)
\t      -        tab (ASCII 9)
\ddd    -        ASCII value ddd (in octal)      

If the recv command appears in a ``select block'', instead of causing the script to abort, a timeout causes control to be passed to the next ``alternate block'' (see the { ... } command above).

recvill illegal-character-codes

This command is used to specify the characters which cannot be received by the local system. Illegal-character-codes is a quoted string of the octal values of characters preceded by a backslash. For example, the following command would declare all the codes between 0 and 017 to be illegal:

        recvill "\0\1\2\3\4\5\6\7\10\11\12\13\14\15\16\17"

Any number of recvill commands can be given in a script file; the resulting illegal-character set will be the union of the codes given in each command. All recvill commands must come before the start command in the script file, so that the illegal character set has been completely specified before the protocol is started. The default illegal-character set is zeroed by the first recvill command to appear in the script. The default set is: the control characters (\0 through \37) and delete (\177).

recvsize size

this command specifies the maximum length packet that can be received by the local system, not including the carriage return. The number size is decimal, with a value:

      40 <= size <= 255

start

This is placed in the script file at the point in the login sequence where the PhoneNet protocol module on the remote system has been started. The start command starts the corresponding PhoneNet protocol module on the local system. When the protocol has completed, interpretation of the script file resumes with the line following the start command. This allows a clean logout procedure to be executed, if necessary.

stty-pr proto-set proto-clear

This command sets the terminal mode of the dial-out line when the dial package is in protocol mode (as opposed to script mode). Protocol mode is initiated by the start command and is the mode in which PhoneNet messages are exchanged. Proto-set is an octal number which determines which options should be set when protocol mode is entered. Proto-clear is an octal number which determines which options should be cleared when protocol mode is entered. The octal numbers are defined in <sgtty.h> and are documented in tty(4). The default value for proto-set is 0000300 (EVENP|ODDP). The default value for proto-clear is 0177474 (ALLDELAY|CRMOD|ECHO|RAW|LCASE).

stty-sc script-set script-clear

This command sets the terminal mode of the dial-out line when the dial package is in script mode (as opposed to protocol mode). Script mode is the mode during which the script file commands such as recv and xmit are used. Script mode is the initial mode and it is also re-entered when control returns from a start command. Script-set is an octal number which determines which options should be set when script mode is entered. Script-clear is an octal number which determines which options should be cleared when script mode is entered. The octal numbers are defined in <sgtty.h> and are documented in tty(4). The default value for script-set is 0000340 (EVENP|ODDP|RAW). The default value for script-clear is 0177434 (ALLDELAY|CRMOD|ECHO|LCASE).

use scriptfile [arguments]

This command passes control to the named scriptfile. If the scriptfile doesn't abort, then control is returned to the line following the use command in the original script file. There is no limit to the depth of nesting available with the use command. However, a failure at any level is passed back to the top and all script processing ceases. The optional arguments are made available in the named script as $1 $2 $3.... Arguments containing spaces should be quoted with double-quotes. To get a dollar sign within a script, use $$.

waitack timeout

This command sets the length of time to wait for data packet acknowledgements from the remote system. If no acknowledgment has been received within timeout seconds, the packet will be retransmitted. The nrexmit command sets the maximum number of times to retransmit the packet before dropping the connection. Timeout must be greater than zero; the default value is 10 seconds.

waitdata timeout

This command sets the length of time to wait for data packets from the remote system. If no data has been received within timeout seconds, the connection is dropped. Timeout must be greater than zero; the default value is 180 seconds. Occasionally, a heavily loaded system will take longer than 180 seconds to respond (perhaps while sorting the message queue). If the remote system cannot be made to respond faster by, say, subdividing its queue to reduce the sort time, then the timeout value will need to be increased.

window windowsize sendwindow

This command sets the link-level windowsize to use when sending data to the remote system. Allowable windowsize's are `1' (the default) and `2'. A windowsize of `1' causes the link-level to pause for acknowledgment from the remote system after sending one data packet. A windowsize of `2' causes the link-level to pause for acknowledgment only after sending two data packets. Normally, the remote system will have acknowledged the first data packet while the second was being transmitted. Therefore, setting a window size of two can greatly increase throughput by eliminating most pausing for acknowledgments. The sendwindow flag indicates whether a special ``windowsize packet'' should be sent to the remote system during protocol initialization. If sendwindow is 0, the packet is not sent. If sendwindow is 1, the packet is sent. This packet, if sent, sets the windowsize that the remote system should use in sending data back to the local system. Normally, implementations of the link-level package default to a windowsize of `1' and require the master side to set sendwindow to change the default setting.

xmit quoted-string

This command cause the characters in quoted-string to be sent to the remote system. The format of quoted-string is identical to that for the recv command (see above) except that two additional escapes apply:

\x      -        delay one second
\#      -        send a break

xmitill illegal-character-codes

This command specifies the character codes which the local system is incapable of transmitting. The xmitill command behaves exactly the same as the recvill command (described above).

xmitsize size

This command specifies the maximum length (not including the carriage return) of packets that should be transmitted by the local system The number size is decimal, with a value:

      40 <= size <= 255

EXAMPLES

Suppose you wanted to set up a script file to perform the following phone call and login dialog using a standalone autodialing modem, a Vadic 3451PA, configured on direct line "vadic1200":

^E               <-----  user types ^E to enter auto-dial mode
HELLO: I'M READY <-----  modem responds with message and prompt
*D               <-----  user types dial command
NUMBER?          <-----  modem prompts for phone number
                 <-----  user enters number and hits return
12225551000      <-----  user types <cr> to verify echo of number
DIALING: ON LINE <-----  dials and reports when carrier
                         is detected.
Welcome to the 11/70
Name: szurko     <-----  user types login name
Password:        <-----  user types password
channel: elec70  <-----  remote PhoneNet "slave" program
                         prompts for MMDF channel name
                 <-----  PhoneNet protocol startup

A script to perform this login sequence might be:

window 2 1
xmitpack 130
recvpack 130
dial vadic1200
xmit "\5\x\x\r"
recv "*" 20
xmit "D\x\r"
recv "NUMBER?\r\n" 30
xmit "12225551000\x\r"
recv "12225551000\r\n" 20
xmit "\r"
recv "ON LINE\r\n" 60
xmit "\x\x\r"
recv "Name:" 30
xmit "szurko\r"
recv "Password:" 30
xmit "secret\r"
recv "channel:" 45
xmit "elec70\r"
recv "elec70" 15
start
end

window 2 1
xmitpack 130
recvpack 130
dial 1200|<wats>12225551000
xmit "\x\x\r"
recv "Name:" 45
xmit "szurko\r"
recv "Password:" 15
xmit "secret\r"
recv "channel:" 45
xmit "elec70\r"
recv "elec70" 15
start
end

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

SEE ALSO