Reference (Scripting) > Docklight Script Commands - The DL Object > Methods

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