|
<< 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:
Function |
Description |
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. 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, ... Returns a string instead of an integer value. representation specifies the format: "A" = ASCII, "H" = HEX, "D" = Decimal or "B" = Binary.
|
Remarks
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
Do
DL.Pause 1 ' (the pause reduces CPU load while idle)
Loop
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
Next
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.