VMS Help DCX Routines, DCX$ANALYZE_INIT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The DCX$ANALYZE_INIT routine initializes the context area for a
    statistical analysis of the data records to be compressed.

    Format

      DCX$ANALYZE_INIT  context [,item_code ,item_value]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Value identifying the data stream that DCX$ANALYZE_INIT
    initializes. The context argument is the address of a longword
    containing this value. DCX$ANALYZE_INIT writes this context
    into the context argument; you should not modify its value. You
    can define multiple context arguments to identify multiple data
    streams that are processed simultaneously.

 item_code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item code specifying information that you want DCX$ANALYZE_INIT
    to use in its analysis of data records and in its computation
    of the mapping function. DCX$ANALYZE_INIT reads this item_code
    argument, which is the address of the longword contained in the
    item code.

    For each item_code argument specified in the call, you must
    also specify a corresponding item_value argument. The item_value
    argument contains the interpretation of the item_code argument.

    The following symbolic names are the five legal values of the
    item_code argument:

       DCX$C_BOUNDED
       DCX$C_EST_BYTES
       DCX$C_EST_RECORDS
       DCX$C_LIST
       DCX$C_ONE_PASS

 item_value

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Value of the corresponding item_code argument. DCX$ANALYZE_INIT
    reads the item_value argument, which is the address of a longword
    containing the item value.

    The item_code and item_value arguments always occur as a pair,
    and together they specify one piece of "advice" for the DCX
    routines to use in computing the map function. Note that, unless
    stated otherwise in the list of item codes and item values, no
    piece of "advice" is binding on DCX; that is, DCX is free to
    follow or not to follow the "advice."

    The following table shows, for each item_code argument, the
    possible values for the corresponding item_value argument:

    Item Code        Corresponding Item Value

    DCX$C_BOUNDED    A Boolean variable. If bit <0> is true (equals
                     1), you are stating your intention to submit
                     for analysis all data records that will be
                     compressed; doing so often enables DCX to
                     compute a better compression algorithm. If
                     bit <0> is false (equals 0) or if the DCX$C_
                     BOUNDED item code is not specified, DCX computes
                     a compression algorithm without regard for
                     whether all records to be compressed will also
                     be submitted for analysis.
    DCX$C_EST_BYTES  A longword value containing your estimate of
                     the total number of data bytes that will be
                     submitted for compression. This estimate is
                     useful in those cases where fewer than the total
                     number of bytes are presented for analysis. If
                     you do not specify the DCX$C_EST_BYTES item
                     code, DCX submits for compression the same
                     number of bytes that was presented for analysis.
                     Note that you may specify DCX$C_EST_RECORDS or
                     DCX$C_EST_BYTES, or both.
    DCX$C_EST_       A longword value containing your estimate of
    RECORDS          the total number of data records that will be
                     submitted for compression. This estimate is
                     useful in those cases where fewer than the total
                     number of records are presented for analysis.
                     If you do not specify the DCX$C_EST_RECORDS
                     item code, DCX submits for compression the same
                     number of bytes that was presented for analysis.
    DCX$C_LIST       Address of an array of 2*n+1 longwords. The
                     first longword in the array contains the value
                     2*n+1. The remaining longwords are paired; there
                     are n pairs. The first member of the pair is
                     an item code, and the second member of the pair
                     is the address of its corresponding item value.
                     The DCX$C_LIST item code allows you to construct
                     an array of item-code and item-value pairs and
                     then to pass the entire array to DCX$ANALYZE_
                     INIT. This is useful when your language has
                     difficulty interpreting variable-length argument
                     lists. Note that the DCX$C_LIST item code may be
                     specified, in a single call, alone or together
                     with any of the other item-code and item-value
                     pairs.
    DCX$C_ONE_PASS   A Boolean variable. If bit <0> is true (equals
                     1), you make a binding request that DCX make
                     only one pass over the data to be analyzed. If
                     bit <0> is false (equals 0) or if the DCX$C_
                     ONE_PASS item code is not specified, DCX may
                     make multiple passes over the data, as required.
                     Typically, DCX makes one pass.

3 - Description

    The DCX$ANALYZE_INIT routine initializes the context area for a
    statistical analysis of the data records to be compressed. The
    first (and typically the only) argument passed to DCX$ANALYZE_
    INIT is an integer variable to contain the context value. The DCX
    facility assigns a value to the context variable and associates
    the value with the created work area. Each time you want a
    record analyzed in that area, specify the associated context
    variable. You can analyze two or more files at once by creating a
    different work area for each file, giving each area a different
    context variable, and analyzing the records of each file in the
    appropriate work area.

4 - Condition Values Returned

    DCX$_INVITEM       Error; invalid item code. The number of
                       arguments specified in the call was incorrect
                       (this number should be odd), or an unknown
                       item code was specified.
    DCX$_NORMAL        Normal successful completion.

    This routine also returns any condition values returned by
    LIB$GET_VM.