$ZCRC (ObjectScript)
Synopsis
$ZCRC(string,mode,expression)
Arguments
| Argument | Description |
|---|---|
| string | A string on which a checksum operation is performed. |
| mode | An integer code specifying the checksum mode to use. |
| expression | Optional — The initial "seed" value, specified as an integer. If omitted, defaults to zero (0). |
Description
$ZCRC performs a cyclic redundancy check on string and returns an integer checksum value. The value returned by $ZCRC depends on the arguments you use.
-
$ZCRC(string,mode) computes and returns a checksum on string. The value of mode determines the type of checksum $ZCRC computes.
-
$ZCRC(string,mode,expression) computes and returns a checksum on string using the mode specified by mode. expression supplies an initial "seed" value when checking multiple strings. It allows you to run $ZCRC calculations sequentially on multiple strings and obtain the same checksum values as if you had concatenated those strings and then run $ZCRC on the resulting string.
Arguments
string
A byte string. Can be specified as a value, a variable, or an expression. Only use a byte string or you will receive a <FUNCTION> error.
mode
The checksum algorithm to use. All checksum modes can be used with 8-bit (ASCII) or 16-bit Unicode (wide) characters. Legal values for mode are:
| Mode | Computes |
|---|---|
| 0 | An 8-bit byte sum. Simply sums the ASCII values of the characters in the string. Thus $ZCRC(2,0)=50, $ZCRC(22,0)=100, $ZCRC(23,0)=101, and $ZCRC(32,0)=101. |
| 1 | An 8-bit XOR of the bytes |
| 2 | A 16-bit DataTree CRC-CCITT |
| 3 | A 16-bit DataTree CRC-16 |
| 4 | A 16-bit CRC for XMODEM protocols |
| 5 | A correct 16-bit CRC-CCITT |
| 6 | A correct 16-bit CRC-16 |
| 7 | A correct 32-bit CRC-32. This corresponds to the cksum utility algorithm 3 on OS X, and the CRC32 class in the Java utilities package. |
| 8 | A 32-bit Murmur3 hash (x64 variant) |
| 9 | A 128-bit Murmur3 hash (x64 variant) |
expression
An argument that is an initial "seed" value. $ZCRC adds expression to the checksum generated for string. This allows you to run $ZCRC calculations on multiple strings sequentially and obtain the saved checksum value as if you had concatenated those strings and run $ZCRC on the resulting string. Chaining $ZCRC expressions is useful for breaking up very large strings to prevent <MAXSTRING> errors. The expression argument is not supported for Murmur3 hashes (modes 8 and 9).
Examples
This example uses mode=0 on strings containing the letters A, B, and C and in each case returns the checksum 198:
write $ZCRC("ABC",0),!
write $ZCRC("CAB",0),!
write $ZCRC("BCA",0),!The checksum is derived as follows:
write $ASCII("A")+$ASCII("B")+$ASCII("C") /* 65+66+67 = 198 */This example shows the values returned by each mode for the string “ABC”:
for i=0:1:9 { write "mode ",i," = ",$ZCRC("ABC",i),! }This example shows how you can use the output of a previous $ZCRC value as the seed for the next calculation. In modes 1 through 7, the CRC of “ABC” is equal to the sequential CRC calculations of “A”, “B”, and “C”, each seeded with the CRC of the previous letter. In modes 8 and 9 (Mumur3 hashes), the CRC calculations are not equal, because Murmur3 does not support chained expressions.
for mode = 1:1:9 {
set crc1 = $zcrc("ABC",mode)
set crc2 = $zcrc("A",mode)
set crc2 = $zcrc("B",mode,crc2)
set crc2 = $zcrc("C",mode,crc2)
write "mode ", mode," ", "crc1 = crc2: ", crc1 = crc2, !
}See Also
-
$ZCYC function
