Sub DL_OnReceive() - Evaluating Receive Sequence Data

To analyse 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:

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( [format] )	Returns a string containing the actual data received. format 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.
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() Syntax 2: Returns a string instead of an integer value. representation specifies the format: "A" = ASCII, "H" = HEX, "D" = Decimal or "B" = Binary.

The DL.OnReceive_GetData() method is a good way to analyse 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.

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

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

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) and your PC's performance. The Communication Window could look like this: