Scripting Language For Trumpet Winsock 1.0B.15


Basic Commands

Each of the following commands is a scripting primitive and will return success or failure corresponding as to whether the command succeeded or not.  Commands always return success unless otherwise specified.

abort	Abort the script.  This command always returns failure.

address <timeout>	Parse the current stream for an IP address.  This value will be copied into the Winsock's primary IP address.  The address change will not be effective until the script finishes.  
	Returns success if an IP address was found, or failure if it timed out.

bootp	Tell the winsock to attempt a bootp when the script has finished executing.  This will normally only happen at the end of the login.cmd script and not the bye.cmd script.  This will modify any TCP/IP setup parameters that have been specified in the returned bootp response. 

display <string>	Display <string> on the tcpman console display.  

echo [ on | off ]	Turn the echoing of received characters on or off respective.  The default is on which will display any received data while dialling onto the tcpman debug screen.

exec [ <program command> ]	Execute the windows command specified.  This will usually be to start up a program from the script. eg. pingw to check the connectivity.

expect <timeout> <target string>	check that the current input stream contains the target string. It must match exactly, and will not search the stream.  If the command timed out or the string received does not match, the command returns failure.

input <timeout> <target string>	scan the current input stream for the matching string. The target string must be found for the command to be successful.  If no string is found within the timeout period, the command returns failure.

online	Tell the winsock to go online immediately.  SLIP packets will begin to be processed, and the state of the comms port will be adjusted to normal SLIP conditions.

output <string>	Send the specified string to the output stream on the comms port.  Any characters received during this process will be echoed to the display if the echo flag is on.

outputecho <string>	send the specified string to the output stream on the comms port.  As each character is output, the script processor waits for the corresponding character to be echoed.  If no character is echoed after 10 seconds, the command times out and a failure is returned.  If the received character does not match, the command will abort and a failure is returned.

password [ <prompt string> ]	Bring up a message box with the optional prompt for the password to be entered.  Any characters typed will be echoed with a "*" character.  If the user cancels the message box, the command returns failure.

query <string variable> [ <prompt string> ]
	Bring up a message box for the string variable to be entered.  An optional prompt may be provided.  If the user cancels the message box, the command returns failure.

quit	Post a quit message to the winsock tcp manager.  This will start a normal quit process.

read <timeout> <string variable>	Read the corresponding string variable from the comms input stream.  A whole line is read.  The line should be terminated by a line feed character. Any carriage returns are stripped. Returns failure if the command timed out.

set ( dtr | rts ) [ on | off ]	Set the modem controls DTR or RTS to the given state.

sleep <timeout>	Pause for timeout seconds.

trace [ on | off ]	Enable or disable the tracing of scripting commands.  This command is very useful for debugging scripts that may be misbehaving.

username [ <prompt string> ]	Bring up a message box for a username to be entered.  An optional prompt may be entered.  If the user cancels the message box, the command returns failure.

wait <timeout> [ dsr | cts | dcd | rlsd ]	Pause until the given modem signal changes state or a timeout occurs.  If the command times out, a failure is returned.
String formats

When a string is required for a parameter, all characters up until the end of the command line are processed as the string.  Strings conform to the following format.

A quote character (") means that all characters are to be taken as is without any special meaning until a corresponding closing quote (") has been found.  The string is not permitted to extend over more than one line.

If a reverse slash "\" is found, it denotes that the character following has a special meaning, or is to be taken literally.  Here is a list of the special character meanings.

\b	place a back space character into the string (control character number 8)
\t	place a tab character into the string (control character number 9)
\l	place a line feed character into the string (control character 10)
\r	place a carriage return character into the string (control character 13)
\f	place a form feed character into the string (control character 12)
\e	place an escape character into the string (control character 27)
\n	place an end of line sequence into the string (control characters 13, then 10)

\0 to \9	this denotes a decimal number of a character to be added into the stream.  Up to three digits may be supplied.  eg.  \0     \27   \255

\I	place the current IP address into the string.
\p	place the current password into the string.
\u	place the current username into the string.
\c	place the port number that the SLIP driver is using into the string as a decimal number.

If a # symbol is found that is not inside quotes, then it means that the rest of the logical line is to be ignored.  This can be used to annotate the script.

If a $ symbol is found, it denotes a string variable.  If the variable has been assigned a value when the command is executed, it's value will be placed in the string.  If not, an error message is displayed, and the script continues.

If a % symbol is found, it denotes an integer variable.  If the variable has been assigned a value when the command is executed, it's value will be placed in the string.  If not, an error message is displayed, and the script continues.  Integers are 32 bit signed integers in the range -2147483648 to 2147483647.

If you wish to use the characters \, #, $ or % inside a string, they must be quoted with " or have a \ character in front of them.  The " character may only be formed by preceding it with a \ character.

Program control commands.

In addition to the basic command primitives, there are the following special control statements.


If Statement.

if <condition>
  <statement list>
[ else
  <statement list> ]
end

If the condition evaluates as true, the first statement list is executed. If the condition evaluates as false, the first statement list is ignored, and if an else clause is present, it is executed instead.

While Loop.

while <condition>
   <statement list>
end

While the condition evaluates as true, the statement list is executed.

Repeat Loop.

repeat
  <statement list>
until <condition>

The statement list is repeatedly executed until the condition evaluates as true.


Assignments and Expressions.

Assignments are used to store new values into variables.  They take the following forms.

<integer variable> := <integer expression>

eg.	%attempts := %attempts + 1

<string variable> := <string>

eg. $name := "My IP address is "\i"."


The variable part may be a string variable (either unspecified or starting with a $), or an integer variable (starting with a %).

Integer expressions may be composed of the following operands.

numbers	eg. 1	43	7373
quoted strings	eg. "fred" 	"OK"
string variables	eg.	$name		$response
integer variables	eg.	%I 	%count


Integer expressions use the following operators in order of priority.

( )	
*  / %    meaning multiplication, division and modulo division.
+, -	meaning addition and subtraction

Also, integer operands may be formed by the comparison of strings.

eg.  $A = "FRED"   will evaluate to an integer operand of 0 or 1 depending on the value of $A.

conditional expressions may also be formed using conditions and boolean operators.
These operators have the following priorities.

= <> < > <= >=		equal, not equal, less than, greater than, less than or equal,
			greater than or equal.  They return 0 or 1 depending on the 				result of the condition.

not			boolean not operator
and			boolean and operator
or			boolean or operator


Commands as operands

As well as the normal type of operands one may expect with expressions, one can also use a scripting command as part of an expression in the following manner by surrounding the command with the [ and ] symbols as follows.

eg.	[input 10 OK\n]

This operand would have the value 1 if the command succeeded or 0 if it failed.

By the prudent use of such operators, quite sophisticated scripts can be formed.

for example, the following segment of script could be used to attempt a repeated dial of a given number.

%attempts := 0
repeat
  %attempts := %attempts + 1
  output atdt345772371
until [input 30 CONNECT\n] or %attempts = 10

This section of script is fine, but would take 30 seconds for the input function to timeout if a response other than CONNECT were returned. It could be refined further into the following lines

%attempts := 0
repeat
  %attempts := %attempts + 1
  output atdt345772371
  read 30 $result
until $result = "CONNECT" or %attempts = 10

This piece of script would be fine unless the modem failed to respond, in which case the script would abort.  A further refinement would be the following.

%attempts := 0
repeat
  %attempts := %attempts + 1
  output atdt345772371
  %timeout := [read 30 $result]
until $result = "CONNECT" or %attempts = 10 or %timeout