User`s guide

Advanced Communications
The Poll() function in detail:
Here is the script for the poll function with line numbers:
1 function Poll(string out, until)
2 // this function will poll the port with given string and read
3 // the response until the given character. Returns NULL (empty)
4 // if there is an error
5 if (argc < 2)
6 throw("Invalid number of parameters")
7 endif
8 private string in
9 try
10 // lock the port
11 if (!LockPort())
12 throw("Unable to lock port")
13 endif
14 // clear anything pending
15 Purge()
16 // output our string
17 Write(out)
18 // and read until the eol:
19 in = ReadUntil(until)
20 // release the port
21 UnlockPort()
22 // and return the response
23 return(in)
24 catch()
25 // error occured
26 UnlockPort()
27 throw()
28 endcatch
29 // return NULL to indicate error. This should never happen
30 // because of the throw() statement above
31 return(NULL)
The first line is a standard function declaration. Its not required, but it allows us
to quickly name the two parameters of this function, out and until. Lines 5
through 7 ensure that there were actually two parameters passed in. Argc is a
private variable set in all functions that contains the number of parameters passed.
If there are less then two passed in, we throw an error.
Next we have to lock the port in line 11. Locking the port prevents another
sequence or thread from trying to communicate over the port while we are in the
middle of a poll / response cycle. If we didn’t lock the port, we could have a case
where we send the device a command, and another thread sends another
command before we get a response. If this happened the response may not
match our request. The LockPort() function doesn’t always succeed. If the port is