<< Click to Display Table of Contents >> Navigation: Reference (Scripting) > Docklight Script Commands - The DL Object > Methods (Advanced) > CalcChecksum |
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