Format

    VARIANTS.
     {                                                       }
     {VARIANT [EXPRESSION IS cond-expr] .                    }
     {             [included-name-clause ]                   }
     {             [local-field-clause   ]                   } ...
     {             [structure-name-clause] ... END VARIANT . }
     {             [variants-clause      ]                   }
     {                                                       }
    END VARIANTS  .

1  –  Parameters

1.1  –  cond-expr

    Specifies an expression that represents the relationship between
    two value expressions. The value of a conditional expression is
    true, false, or null.

1.2  –  included-name-clause

    Includes existing field and record definitions within record
    elements. See DEFINE RECORD_Included_Name command for more
    information.

1.3  –  local-field-clause

    Specifies the locally defined field. See DEFINE RECORD_Local_Field
    command for more information.

1.4  –  structure-name-clause

    Creates structure definitions within record elements. See DEFINE
    RECORD_Structure command for more information.

1.5  –  variants-clause

    Creates variants definitions within record elements.

2  –  Description

    The Variants Clause syntax identifies a set of overlays that can
    be used by a COBOL REDEFINES statement or by other languages.
    Each variants definition can contain two or more fields, records,
    structures, variants, or any combination of these definitions.

    Be sure that the variants definitions you define conform to the
    requirements of the language or language processor that accesses
    the record element. For example, you must include a structure
    definition for each variants clause contained in a CDO record if
    you are developing a new application that will use a 3GL language
    and DIGITAL DATATRIEVE.

    You can specify a different data type for each definition in a
    variants definition.

    You can create any number of variants definitions within a record
    element.

    You can create any number of definitions within a variants
    definition.

    If you use an expression with one variant, you must use an
    expression with every other variant in the variants definition.

    In variant expressions, you can refer to a tag variable (field
    definition) whose runtime value determines which variant in a
    variants definition maps to the record element. The tag variable
    cannot be part of an array.

    At runtime, the product using CDO tests the value of each
    Boolean expression in the variants definition to determine which
    definition is the current variants definition. The variants with
    a Boolean expression that evaluates to true is chosen.

    The values that you test for in the expressions of a variants
    definition must conform to the following rules:

    o  The values being tested must be valid values for the data type
       of the tag variable. For example, if the data type for the tag
       variable is text, the value you test for must be a string.

    o  The range of values being tested in one expression must not
       overlap the range of values in any other expression.

    Each variants definition begins on the same byte in the record,
    subject to individual alignment options. The length of the
    longest definition in a variants definition determines the
    overall length of the variants definition.

3  –  Examples

  CDO>  DEFINE RECORD PRODUCT_INVENTORY.
  cont>   FIELD_ID.
  cont>     VARIANTS.
  cont>       VARIANT EXPRESSION IS
  cont>         FIELD_ID IN PRODUCT_INVENTORY EQ "S".
  cont>         IN_STOCK STRUCTURE.
  cont>           PRODUCT_NO.
  cont>           DATE_ORDERED.
  cont>           STATUS_CODE.
  cont>           QUANTITY.
  cont>           LOCATION.
  cont>           UNIT_PRICE.
  cont>         END IN_STOCK STRUCTURE.
  cont>       END VARIANT.
  cont>       VARIANT EXPRESSION IS
  cont>         FIELD_ID IN PRODUCT_INVENTORY EQ "B".
  cont>         BACK_ORDER STRUCTURE.
  cont>           PRODUCT_NO.
  cont>           DATE_ORDERED.
  cont>           STATUS_CODE.
  cont>           QUANTITY.
  cont>           SUPPLIER.
  cont>           UNIT_PRICE.
  cont>         END BACK_ORDER STRUCTURE.
  cont>       END VARIANT.
  cont>       VARIANT EXPRESSION IS
  cont>         FIELD_ID IN PRODUCT_INVENTORY EQ "O".
  cont>         OUT_OF_STOCK STRUCTURE.
  cont>           PRODUCT_NO.
  cont>           DATE_LAST_SOLD.
  cont>         END OUT_OF_STOCK STRUCTURE.
  cont>       END VARIANT.
  cont>     END VARIANTS.
  cont> END RECORD.

      In this example, the DEFINE RECORD command creates the PRODUCT_
      INVENTORY record element, which contains a variants definition
      consisting of three structure definitions. Each structure
      definition uses an expression whose value is compared to
      the value of the tag variable (FIELD_ID field definition) at
      runtime to determine which structure definition maps to the
      record element.