<< Click to Display Table of Contents >> Navigation: Reference (Scripting) > Docklight Script Commands - The DL Object > Methods > WaitForSequence |
Waits for one or several occurrences of a Receive Sequence and returns the corresponding counter value (see GetReceiveCounter). Starts the communication, if not already running (see StartCommunication).
Return Value
Long
Syntax
result = DL.WaitForSequence( nameOrIndex [, maxCounter] [, timeout] )
The WaitForSequence method syntax has these parts:
Part |
Description |
nameOrIndex |
Required. String containing the Name of the Receive Sequence to count. The first Receive Sequence from the list with a name that matches nameOrIndex is used. As an alternative, you may pass an integer value specifying the Sequence Index. Valid Sequence Index range is from 0 to (NoOfReceiveSequences - 1). |
maxCounter |
Optional. Long number containing the counter limit until the function returns. Default value is 1 (one): WaitForSequence returns after detecting the first occurrence of the receive sequence. Return value is 1 in this case. If maxCounter is -1, WaitForSequence does not use a counter limit. It will only return after a timeout (see below). Use maxCounter = -1 to count all occurrences of a Receive Sequence within a limited period of time. |
timeout |
Optional. Long number specifying an additional timeout in milliseconds. Default value is -1 (no timeout). Maximum value is 86000000 (23.88 hours). |
Remarks
The WaitForSequence method checks the number of "hits" for this Receive Sequence since the communication has been started (see StartCommunication) or the counter has been reset (see ResetReceiveCounter). WaitForSequence waits until the number of "hits" specified by the maxCounter have been detected.
One basic application for WaitForSequence is waiting for a specific answer after sending out a test command to your serial device. To make sure that you do not miss a very quick response from your device, use the following command order:
1. Reset the counter(s) first using ResetReceiveCounter.
2. Send your test command using SendSequence
3. Now use WaitForSequence to wait for the expected answer
It is very important that you use ResetReceiveCounter before SendSequence. ResetReceiveCounter will not only set the detection counter to zero, but also reset the character matching process, so any characters that have been previously received are not considered when looking for a sequence match. See also the remarks on wildcard search for additional information on how Docklight handles Receive Sequence pattern matching.
During a WaitForSequence, no DL_OnReceive() procedure calls can be processed. If you need to process DL_OnReceive() events while waiting, see the pauseWithEvents() code described at OnReceive Example 2.
If you need to wait for any of the Receive Sequences to trigger, the DL_OnReceive() procedure provides the solution. See the OnReceive Example 3.
Example
' Example WaitForSequence
' Count the number of occurrences of
' the first Receive Sequence within a 10 seconds
' interval.
' Requires at least one Receive Sequence definition
DL.StartCommunication
DL.ClearCommWindows
result = DL.WaitForSequence(0 , -1, 10000)
DL.AddComment vbCrLf & vbCrLf & "Receive Sequence #0, hit count = " & result
' alternative way to read the counter afterwards
DL.AddComment "Receive Sequence #0, hit count = " & DL.GetReceiveCounter(0)
' Send the first Send Sequence and wait for a device response (no timeout)
DL.AddComment vbCrLf & vbCrLf & "Sending data and waiting for Receive Sequence #0"
DL.ResetReceiveCounter
DL.SendSequence 0
DL.WaitForSequence 0