To analyze the Receive Sequence data (e.g. check the actual values received for a wildcard area) or perform additional tasks after receiving the sequence, the following procedure can be defined in a Docklight script:

Sub DL_OnReceive()

... my script code ...

End Sub

After detecting a new Receive Sequence and performing the predefined Actions (add comment, send a sequence, ...), the DL_OnReceive() procedure is called by the Docklight script engine. Inside the DL_OnReceive() procedure, the following functions are available to read out the Receive Sequence data:

Function

Description

result = DL.OnReceive_GetSize()

Returns the received data size / number of characters

result = DL.OnReceive_GetName()

Returns the name of the corresponding Receive Sequence.

result = DL.OnReceive_GetIndex()

Returns its index within the Receive Sequence list

result = DL.OnReceive_GetData( [representation] )

Syntax 2:

result = DL.OnReceive_GetData( [representation] [, start] [, length] )

Returns a string containing the actual data received. representation specifies the representation of result: "A" = ASCII (default), "H" = HEX, "D" = Decimal or "B" = Binary.

The data returned does not contain any wildcards. At wildcard positions, the actual characters received are returned.

NOTE: If the original Receive Sequence contains '#' wildcards (zero or one character), the length of the DL.OnReceive _GetData() sequence can be shorter than the original sequence with wildcards.

Syntax 2:
Returns a string containing a specified number of characters from the data received.

start: range: 1 .. DL.OnReceive_GetSize(), or -1 = start at last character, -2 = start at second last character, ... Default value is 1.

length: number of characters, or -1 = until last character,

-2 = until second last character, ....

Default value is -1.

result = DL.OnReceive_GetChannel()

Returns the communication channel number on which this sequence has been detected. In Communication Mode "Monitoring", the return value is 1 or 2. In Communication Mode Send/Receive, the return value is 2 always (RX channel).

result = DL.OnReceive_Peek( charNo )

Syntax 2:

result = DL.OnReceive_Peek( charNo, representation )

Returns one character of the received data as an integer value from 0..255

charNo is the position within the received data. Valid charNo range: 1 .. DL.OnReceive_GetSize(), or -1 = start at last character, -2 = start at second last character, ...

Syntax 2:

Returns a string instead of an integer value. representation specifies the format:

"A" = ASCII, "H" = HEX, "D" = Decimal or "B" = Binary.

myDateTime = DL.OnReceive_GetDateTime()

milliseconds = DL.OnReceive_GetMilliseconds()

These functions return the actual Docklight date/time stamp when this Receive Sequence was triggered. The result is stored in two separate VBScript standard data types:

myDateTime: VBScript Date value with the Date/Time in 1 seconds resolution

milliseconds: Integer value with the corresponding milliseconds information from 0..999

Remarks

The DL.OnReceive_GetData() method is a good way to analyze the actual data received when you are using ASCII protocols with printing characters only. If you require the HEX or decimal value of individual characters, you may use the DL.OnReceive_Peek( .. ) function as a convenient alternative. See the DL_OnSend() event procedure for a related example.

The DL_OnReceive() procedure is only executed while the script is running. While executing the DL_OnReceive() code, no further communication processing and display updates are performed. To avoid performance and timing problems, keep the execution time low. Avoid nested loops for example, and do not perform time-consuming calculations.

DL_OnReceive() procedures are not executed while a Pause or a WaitForSequence method is blocking the program flow. If a Receive Sequence is detected, the DL_OnReceive() call is queued and executed after Pause (or WaitForSequence) returns. See Example 2 below for a workaround to this problem.

See also Timing and Program Flow for some insight on how Docklight handles receive data events and executes the DL_OnReceive() code section.

Example

' Example DL_OnReceive() event code

' Predefined Send Sequence

' (0) Send Value:

' VALUE=<?><?><CR><LF>

' Predefined Receive Sequence

' (0) Value Received:

' VALUE=<?><?><CR><LF>

' Run this test on a COM port with a loopback connector

' (TX connected to RX of the same port).

finished = False

DL.ClearCommWindows

DL.Pause 1 ' (the pause reduces CPU load while idle)

Loop Until finished

Sub DL_OnReceive()

If DL.OnReceive_GetName() = "Value Received" Then

DL.AddComment "Value received = " & DL.OnReceive_GetData("A", 7, -3)

' Read the value from the receive data, but only the changing "value" part

myValue = Mid(DL.OnReceive_GetData(), 7, 2)

' Ensure this is a numeric value

If IsNumeric(myValue) Then

' increase

myValue = myValue + 1

If myValue < 100 Then

' If the value is still below 100, send it out again

newValueStr = CStr(myValue)

DL.SendSequence "Send Value", newValueStr

Else

DL.AddComment "VALUE=99, stopping..."

finished = True

End If

End Sub

After starting the script and manually sending out a "Send Value" sequence with parameter value "95", the Communication Window could look like this:

7/29/2012 15:43:43.823 [TX] - VALUE=95

7/29/2012 15:43:43.826 [RX] - VALUE=95

Value received = 95

7/29/2012 15:43:43.879 [TX] - VALUE=96

7/29/2012 15:43:43.880 [RX] - VALUE=96

Value received = 96

7/29/2012 15:43:43.926 [TX] - VALUE=97

7/29/2012 15:43:43.927 [RX] - VALUE=97

Value received = 97

7/29/2012 15:43:43.977 [TX] - VALUE=98

7/29/2012 15:43:43.978 [RX] - VALUE=98

Value received = 98

7/29/2012 15:43:44.025 [TX] - VALUE=99

7/29/2012 15:43:44.026 [RX] - VALUE=99

Value received = 99

VALUE=99, stopping...

Example 2

' Example using DL_OnReceive() in code with Pause statements

' Predefined Send Sequence

' (0) Hello:

' Hello<CR><LF>

' Predefined Receive Sequence

' (0) Hello:

' Hello<CR><LF>

' Run this test on a COM port with a loopback connector

' (TX connected to RX of the same port).

DL.ClearCommWindows

' Get the communication started

started = True

DL.SendSequence "Hello"

' Wait for about 1 second, but make sure that the DL_OnReceive() events

' are processed meanwhile

pauseWithEvents 1000

' Stop sending and wait until all data came back properly

started = False

DL.Pause 20

' Data throughput?

DL.AddComment

DL.AddComment "Number of 'Hello' sequences detected: " & DL.GetReceiveCounter("Hello")

Sub DL_OnReceive()

If started Then

myDate = DL.OnReceive_GetDateTime()

msec = DL.OnReceive_GetMilliseconds()

DL.AddComment " receive timestamp = " & DL.GetDocklightTimeStamp(myDate, msec)

' Send out the same sequence that has just been received

DL.SendSequence DL.OnReceive_GetIndex()

End If

End Sub

Sub pauseWithEvents(milliseconds)

' Unlike the DL.Pause command, this function allows DL_OnReceive()

' statements to be processed while waiting

startTime = Timer

While (Timer - startTime) < milliseconds / 1000

' consider midnight 'jump' / reset of the Timer variable

If Timer < (startTime - 1) Then startTime = startTime - 86400

DL.Pause 1

Wend

End Sub

After starting the script, Docklight will keep sending and receiving the "Hello" sequence for about 1 second. The total number of sequences sent and received depends on the COM port settings (baud rate), PC speed and Docklight display settings. The Communication Window could look like this:

8/1/2012 11:00:41.830 [TX] - Hello<CR><LF>

8/1/2012 11:00:41.834 [RX] - Hello<CR><LF>

receive timestamp = 8/1/2012 11:00:41.834

8/1/2012 11:00:41.846 [TX] - Hello<CR><LF>

8/1/2012 11:00:41.849 [RX] - Hello<CR><LF>

receive timestamp = 8/1/2012 11:00:41.849

8/1/2012 11:00:41.861 [TX] - Hello<CR><LF>

...

8/1/2012 11:00:42.825 [TX] - Hello<CR><LF>

8/1/2012 11:00:42.827 [RX] - Hello<CR><LF>

receive timestamp = 8/1/2012 11:00:42.827

8/1/2012 11:00:42.839 [TX] - Hello<CR><LF>

8/1/2012 11:00:42.841 [RX] - Hello<CR><LF>

receive timestamp = 8/1/2012 11:00:42.841

8/1/2012 11:00:42.852 [TX] - Hello<CR><LF>

8/1/2012 11:00:42.855 [RX] - Hello<CR><LF>

Number of 'Hello' sequences detected: 70

Example 3

' Example using Sub DL_OnReceive() to wait for ANY sequence

found = False

foundName = ""

foundDate = Now

foundMSec = 0

DL.Pause 1 ' (the pause reduces CPU load while idle)

Loop Until found

DL.AddComment

DL.AddComment "Sequence received: " & foundName

DL.AddComment "Date/Time received: " & DL.GetDocklightTimeStamp(foundDate, foundMSec)

Sub DL_OnReceive()

If Not found Then

found = True

foundName = DL.OnReceive_GetName()

foundDate = DL.OnReceive_GetDateTime()

foundMSec = DL.OnReceive_GetMilliseconds()

End If

End Sub

Sub DL_OnReceive() - Evaluating Receive Sequence Data

Sub DL_OnReceive() - Evaluating Receive Sequence Data

Example