Skip to main content

$ZCRC (ObjectScript)

Checksum function.

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

FeedbackOpens in a new tab