Sub DL_OnSend() - Send Sequence Data Manipulation

<< Click to Display Table of Contents >>

Navigation:  Reference (Scripting) > OnSend / OnReceive Event Procedures >

Sub DL_OnSend() - Send Sequence Data Manipulation

To allow additional calculations and algorithms (e.g. checksums) on Send Sequence data, the following procedure can be defined in a Docklight script:


Sub DL_OnSend()

... my script code ...

End Sub


Before sending out a new Send Sequence, the DL_OnSend() procedure is called by the Docklight script engine. Inside the DL_OnSend() procedure, the following functions are available to read and manipulate the current sequence data:




result = DL.OnSend_GetSize()

Returns the send data size / number of characters


result = DL.OnSend_GetName()

Returns the name of the Send Sequence to be transmitted.

If this is a custom data sequence created by a DL.SendSequence command, the return value is an empty string ("").


result = DL.OnSend_GetIndex()

Returns its index within the Send Sequence list.

If this is a custom data sequence created by a DL.SendSequence command, the return value is -1.


result =

  DL.OnSend_GetData( [representation] )









Syntax 2:

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

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

The data returned does not contain any wildcards. All wildcard positions have already been replaced by actual characters. NOTE: If the original Send Sequence contains '#' wildcards (zero or one character), the length of the DL.OnSend_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.OnSend_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.

DL.OnSend_SetData newData

  [, representation]

Replaces the data to be transmitted with the data provided in the newData string. representation specifies the format of newData "A" = ASCII (default), "H" = HEX, "D" = Decimal or "B" = Binary.

After exiting the DL_OnSend() procedure, Docklight will transmit newData, regardless of what the original Send Sequence looked like. The newData length can be different from the original Send Sequence length.

NOTE: If newData is an empty string, the transmission of the original Send Sequence is effectively suppressed.


DL.OnSend_Poke charNo, value

Set the character at position charNo to value. value is the new character as an integer number from 0..255. See also DL.OnSend_Peek(...)


result = DL.OnSend_Peek( charNo )




Syntax 2:

result = DL.OnSend_Peek( charNo, representation )

Returns one character of the send data as an integer value from 0..255. charNo is the position within the send data. Valid charNo range: 1 .. DL.OnSend_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.





Using the DL.OnSend_GetSize(), DL.OnSend_Peek(..) and DL.OnSend_Poke functions, checksum calculations and other algorithms can be easily implemented. See the example below.


The DL_OnSend() procedure is only executed while the script is running. While executing the DL_OnSend() 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.


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




' Example DL_OnSend() event code


' Predefined Send Sequences

' (0) Test: TestX<CR><NUL>


' Endless loop to prevent the script from terminating immediately


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



Sub DL_OnSend()

  ' Simple checksum: Last byte of sequence

  ' is a checksum on all previous bytes, mod 256

   seqSize = DL.OnSend_GetSize()

  ' we need at least a three-byte sequence

  If seqSize > 2 Then

  ' instead of the "X" after Test, put a random character

   DL.OnSend_Poke seqSize - 2, 65 + Rnd * 25

  ' calculate a simple checksum on the new sequence

       chksumHex = DL.CalcChecksum("MOD256", DL.OnSend_GetData("H"), "H", 1, seqSize -1)

      ' Overwrite the last character of the Send Sequence with the actual checksum value

       DL.OnSend_Poke seqSize, CInt("&h" + chkSumHex)

            ' Using the Peek function for additional documentation

  DL.AddComment vbCrLf & vbCrLf

       DL.AddComment "Checksum on", False, False

      For i = 1 To seqSize - 1

           DL.AddComment " " & DL.OnSend_Peek(i, "H"), False, False


       DL.AddComment " is " &  DL.OnSend_Peek(seqSize, "H") & "(Hex), " & DL.OnSend_Peek(seqSize, "D") & "(Decimal)"

  End If

End Sub


After starting the script and manually sending the "Test" sequence twice, the ASCII communication window of Docklight could display the following output:  


Checksum on 54 65 73 74 53 0D  is 00(Hex), 000(Decimal)


23.06.2015 11:28:31.695 [TX] - 54 65 73 74 53 0D 00


Checksum on 54 65 73 74 4E 0D  is FB(Hex), 251(Decimal)


23.06.2015 11:28:32.568 [TX] - 54 65 73 74 4E 0D FB


NOTE: Calculating and Validating Checksums and the MODBUS protocol example describe how to calculate and validate common CRCs and other checksums without DL_OnSend() / DL_OnReceive() code. This processing happens before the sequence data is passed to the DL_OnSend() procedure. But if you want to modify your Send Sequence data before sending and require a checksum on the modified data, the above example is the correct solution.