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:

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] )

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.

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()

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.

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

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

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