SYS(2017) - Record Checksum Value

Returns a checksum value based on the current record in the current work area. You can use a checksum to test the validity of data. You can also generate checksum values greater than 16 bits for large strings.

SYS(2017) offers complementary functionality to SYS(2007) - Checksum Value.

SYS(2017, cExpression [, nSeed [, nFlags]])

Parameters

  • cExpression
    Specifies a comma-delimited list, with or without spaces, containing one or more fields to exclude from the checksum calculation. The maximum length of the field string is limited to 256 characters.

    If cExpression is empty, Visual FoxPro does not exclude fields except for Memo and General fields.

  • nSeed
    Specifies a numeric seed value of 0 that is used to calculate the checksum and is included for backward compatibility. Passing a value of -1 for nSeed uses the default system value of 0. For CRC32 calculations, Visual FoxPro disregards nSeed.
  • nFlags
    Specifies additive bit values for generating the checksum.

    Versions of Visual FoxPro earlier than 8.0 used a CRC16 16-bit algorithm to calculate the checksum values of strings. Visual FoxPro now includes the CRC32 routine to calculate larger 32-bit values. You can control the setting of this algorithm by setting the first bit value of the nFlags parameter.

    The following table lists the bit values you can add to produce a value for nFlags.

    Value Bits Description

    1

    001

    Calculate checksum value using CRC32 checksum algorithm.

    2

    010

    Include Memo fields in the checksum calculation.

    You can use the second nFlags bit to include Memo fields in the CRC calculation. Visual FoxPro includes all Memo fields except any specified by cExpression in the calculation.

    The following table lists the possible values for nFlags, produced by the sum of the bit flags.

    nFlags Description

    0

    Calculate checksum based on cExpression parameter using CRC16 checksum algorithm. (Default)

    1

    Calculate checksum based on cExpression parameter using CRC32 checksum algorithm.

    2

    Calculate checksum based on current record contents including Memo fields using CRC16.

    3

    Calculate checksum based on current record contents including Memo fields using CRC32.

Return Value

Character data type. SYS(2017) returns a checksum value.

Remarks

When calculating the checksum value from the current record, Visual FoxPro disregards Memo and General fields unless nFlags is set to 2 or 3.

Visual FoxPro generates the checksum based on the current record in the current work area and passes the byte values of the string into the CRC32 routine.

Visual FoxPro returns a value of "0" if no cursor is open in the current work area or if the record pointer is not valid, for example, pointing to a phantom record.

When you create a string expression from a record, Visual FoxPro removes trailing blank spaces and returns the expression as a character string, similar to the ALLTRIM( ) function.

Usually, Visual FoxPro uses any excluded fields specified by cExpression to store the checksum value and does not include them in the calculation. Visual FoxPro does not perform any checks on the data type of these fields. If cExpression contains an invalid field, Visual FoxPro disregards that field.

Visual FoxPro calculates the checksum from all the fields included except for Memo, General, and those specified by cExpression. You can determine the fields used and their order using the FIELD( ) function. If you specified a setting for SET FIELDS, the checksum is calculated based on the current list specified by SET FIELDS which could include calculated fields.

Calculated fields are temporary fields that exist in the current cursor based on an expression but are not defined in the actual table structure. For example, the field LOCATION is a calculated field:

Use Customer
SET FIELDS TO LOCATION = ALLTRIM(city) + ',' + state

See Also

Reference

SYS( ) Functions Overview
SYS(2007) - Checksum Value
SET FIELDS Command
FIELD( ) Function
SET RESOURCE Command
Creating Character Expressions