Reference (Scripting) > Docklight Script Commands - The DL Object > Methods (Advanced)

Returns a checksum or CRC value for a given sequence, or a part of a sequence.

The CalcChecksum method is an advanced Docklight Scripting feature and requires some knowledge about checksums in serial application protocols, and how Docklight deals with send/receive data in general.

TIP: We recommend the section Calculating and Validating Checksums for introduction. If the CRC-specific terms and parameters seem confusing to you, see the CRC Glossary for some background information.

Return Value

String

Syntax

result = DL.CalcChecksum( checksumSpec, dataStr, [, representation] [, startPos] [, endPos] [, bigEndian ])

The CalcChecksum method syntax has these parts:

Part	Description
checksumSpec	Required. String that specifies the checksum algorithm and its parameters. CalcChecksum supports predefined names for common checksum algorithms, or you can pass a generic CRC specification for calculating more exotic CRCs. Predefined names are: "MOD256", "XOR", "CRC-8", "CRC-CCITT", "CRC-16", "CRC-MODBUS" and "CRC-32" See checksumSpec Format for the full format specification.
dataStr	Required. String value that contains the input Sequence for the checksum calculation, as for example returned by the OnSend_GetData() function.
representation	Optional. String value to define the format of the dataStr Sequence: "H" = Hex (default), "A" = ASCII , "D" = Decimal or "B" = Binary.
startPos	Optional Integer value. Specifies the character position where the calculation should start. Default value is 1 (beginning of the dataStr Sequence). startPos also accepts negative values, e.g. -1 for "last character", -2 for "2nd character from the end", -3 for "3rd character from the end".
endPos	Optional Integer value. Specifies the last character that should be included in the calculation. Default value is the size of the dataStr Sequence. endPos also accepts negative values, see startPos above.
bigEndian	Optional. Boolean value to define the byte order for result . True (default): Use big-endian byte order (first character is most significant) False: use little-endian byte order (first character is least significant)

Remarks

The return value is a string with the CRC/checksum in the Docklight HEX sequence format, e.g. "CB F4 39 26". The number of HEX bytes returned depends on the width of the checksum algorithm. See the example script and communications window output below.

With the help of CalcChecksum you can generate specific checksums for Send Sequences on the fly, or use advanced checksum validations for received data. See the Sub DL_OnSend() Event Procedure for details.

Standard checksums can already be processed without script code using the Checksum part of the Edit Send Sequence / Edit Receive Sequence dialogs. See also the related Modbus protocol example example.

Example

' Example CalcChecksum

DL.ClearCommWindows

DL.AddComment

DL.AddComment "Simple checksum (Mod 256) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("MOD256", "123456789", "A")

DL.AddComment

DL.AddComment "8 bit CRC (CRC DOW) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-DOW", "123456789", "A")

DL.AddComment

DL.AddComment "16 bit CRC (CRC-16) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-16", "123456789", "A")

DL.AddComment

DL.AddComment "16 bit CRC (CRC-Modbus) for '123456789' in 'LittleEndian' - lower byte first"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-Modbus", "123456789", "A", , ,False)

DL.AddComment

DL.AddComment "16 bit CRC (CRC-CCITT) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-CCITT", "123456789", "A")

DL.AddComment "Now do the same thing, but specify all CRC details yourself..."

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC:16,1021,FFFF,0000,No,No", "123456789", "A")

DL.AddComment

DL.AddComment "32 bit CRC (CRC-32) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-32", "123456789", "A")

DL.AddComment

DL.AddComment "A 32 bit CRC (CRC-32) on the first 5 bytes of HEX sequence 01 02 03 04 05 FF FF FF FF, result is Little Endian / lowest byte first"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-32", "01 02 03 04 05", "H", 1, 5, False)

The above script code produces the following output in the Docklight communication window:

Simple checksum (Mod 256) for '123456789'

CalcChecksum = DD

8 bit CRC (CRC DOW) for '123456789'

CalcChecksum = A1

16 bit CRC (CRC-16) for '123456789'

CalcChecksum = BB 3D

16 bit CRC (CRC-Modbus) for '123456789' in 'LittleEndian' - lower byte first

CalcChecksum = 37 4B

16 bit CRC (CRC-CCITT) for '123456789'

CalcChecksum = 29 B1

Now do the same thing, but specify all CRC details yourself...

CalcChecksum = 29 B1

32 bit CRC (CRC-32) for '123456789'

CalcChecksum = CB F4 39 26

A 32 bit CRC (CRC-32) on the first 5 bytes of HEX sequence 01 02 03 04 05 FF FF FF FF, result is Little Endian / lowest byte first

CalcChecksum = F4 99 0B 47