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 Winsocks 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 [ timeout ] <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 the received character 
does not match, the command will 
abort and a failure is returned.  
If a timeout is not provided, a 
default of 10 seconds is used.  The 
timeout applies to the whole 
command.  In addition, the 
carriage-return is handled 
specially by waiting for a linefeed 
to be read after the carriage 
return is read. Both the sequences 
<CR><LF> and <CR><CR><LF> are 
acceptable.

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, its 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, its 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.

!			boolean not operator
&			boolean and operator
|			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. Note the use 
of the outputecho rather than output so that any characters 
echoed from the command will be consumed.

%attempts = 0
repeat
  %attempts = %attempts + 1
  outputecho atdt345772371
until [input 30 CONNECT\n] | %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
  outputecho atdt345772371
  read 30 $result
until $result = CONNECT | %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
  outputecho atdt345772371
  %timeout = [read 30 $result]
  if %timeout
    display Dial up timed out.\n
  end
until $result = CONNECT | %attempts = 10 | %timeout



