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

    The DCX$MAKE_MAP routine uses the statistical information
    gathered by DCX$ANALYZE_DATA to compute the compression/expansion
    function.

    Format

      DCX$MAKE_MAP  context ,map_addr [,map_size]

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$MAKE_MAP maps. The
    context argument is the address of a longword containing this
    value. DCX$ANALYZE_INIT initializes this value; you should not
    modify it. You can define multiple context arguments to identify
    multiple data streams that are processed simultaneously.

 map_addr

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting address of the compression/expansion function. The map_
    addr argument is the address of a longword into which DCX$MAKE_
    MAP stores the virtual address of the compression/expansion
    function.

 map_size

    OpenVMS usage:longword_signed
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the compression/expansion function. The map_size
    argument is the address of the longword into which DCX$MAKE_MAP
    writes the length of the compression/expansion function.

3 - Description

    The DCX$MAKE_MAP routine uses the statistical information
    gathered by DCX$ANALYZE_DATA to compute the compression/expansion
    function. In essence, this map is the algorithm used to shorten
    (or compress) the original data records as well as to expand the
    compressed records to their original form.

    The map must be available in memory when any data compression
    or expansion takes place; the address of the map is passed as an
    argument to the DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines,
    which initialize the data compression and expansion procedures,
    respectively.

    The map is stored with the compressed data records, because the
    compressed data records are indecipherable without the map. When
    compressed data records have been expanded to their original
    state and no further compression is desired, you should delete
    the map using the LIB$FREE_VM routine.

    DCX requires that you submit data records for analysis and then
    call the DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN
    status code, you must again submit data records for analysis
    (in the same order) and call DCX$MAKE_MAP again; on the second
    iteration, DCX$MAKE_MAP returns the DCX$_NORMAL status code.

4 - Condition Values Returned

    DCX$_AGAIN         Informational. The map has not been created
                       and the map_addr and map_size arguments have
                       not been written because further analysis is
                       required. The data records must be analyzed
                       (using DCX$ANALYZE_DATA) again, and DCX$MAKE_
                       MAP must be called again before DCX$MAKE_MAP
                       will create the map and return the DCX$_NORMAL
                       status code.
    DCX$_INVCTX        Error. The context variable is invalid, or the
                       context area is invalid or corrupted. This may
                       be caused by a failure to call the appropriate
                       routine to initialize the context variable or
                       by an application program error.
    DCX$_NORMAL        Normal successful completion.

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