 |
OpenVMS Utility Routines Manual
DCX$ANALYZE_DONE
The DCX$ANALYZE_DONE routine deletes the context area and sets the
context variable to zero, undoing the work of the DCX$ANALYZE_INIT
routine.
Call DCX$ANALYZE_DONE after data records have been analyzed and the
DCX$MAKE_MAP routine has created the map.
Format
DCX$ANALYZE_DONE context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword |
| 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.
Argument
context
| OpenVMS usage: |
context |
| type: |
longword |
| access: |
modify |
| mechanism: |
by reference |
Value identifying the data stream that DCX$ANALYZE_DONE deletes. 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.
Condition Values Returned
|
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$FREE_VM.
DCX$ANALYZE_INIT
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]
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.
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_RECORDS
|
A longword value containing your estimate of 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.
|
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.
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.
DCX$COMPRESS_DATA
The DCX$COMPRESS_DATA routine compresses a data record. Call this
routine for each data record to be compressed.
Format
DCX$COMPRESS_DATA context ,in_rec ,out_rec [,out_length]
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.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Value identifying the data stream that DCX$COMPRESS_DATA compresses.
The context argument is the address of a longword
containing this value. DCX$COMPRESS_INIT initializes the value; you
should not modify it. You can define multiple context
arguments to identify multiple data streams that are processed
simultaneously.
in_rec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Data record to be compressed. The in_rec argument is
the address of the descriptor of the data record string.
out_rec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Data record that has been compressed. The out_rec
argument is the address of the descriptor of the compressed record that
DCX$COMPRESS_DATA returns.
out_length
| OpenVMS usage: |
word_signed |
| type: |
word integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Length (in bytes) of the compressed data record. The
out_length argument is the address of a word into
which DCX$COMPRESS_DATA returns the length of the compressed data
record.
Description
The DCX$COMPRESS_DATA routine compresses a data record. Call this
routine for each data record to be compressed. As you compress each
record, write the compressed record to the file containing the
compression/expansion map. For each record, write the length of the
record and substring string containing the record to the same file. See
the COMPRESS DATA section in Example 7-1.
Condition Values Returned
|
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$_INVDATA
|
Error. You specified the item value DCX$C_BOUNDED in the
DCX$ANALYZE_INIT routine and attempted to compress a data record (using
DCX$COMPRESS_DATA) that was not presented for analysis (using
DCX$ANALYZE_DATA). Specifying the DCX$C_BOUNDED item value means that
you must analyze all data records that are to be compressed.
|
|
DCX$_INVMAP
|
Error; invalid map. The
map argument was not specified correctly in the
DCX$ANALYZE_INIT routine or the context area is invalid.
|
|
DCX$_NORMAL
|
Normal successful completion.
|
|
DCX$_TRUNC
|
Error. The compressed data record has been truncated because the
out_rec descriptor did not specify enough memory to
accommodate the record.
|
This routine also returns any condition values returned by
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.
DCX$COMPRESS_DONE
The DCX$COMPRESS_DONE routine deletes the context area and sets the
context variable to zero.
Format
DCX$COMPRESS_DONE context
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.
Argument
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Value identifying the data stream that DCX$COMPRESS_DONE deletes. The
context argument is the address of a longword
containing this value. DCX$COMPRESS_INIT writes the value 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.
Description
The DCX$COMPRESS_DONE routine deletes the context area and sets the
context variable to zero, undoing the work of the DCX$COMPRESS_INIT
routine. Call DCX$COMPRESS_DONE when all data records have been
compressed (using DCX$COMPRESS_DATA). After calling DCX$COMPRESS_DONE,
call LIB$FREE_VM to free the virtual memory that DCX$MAKE_MAP used for
the compression/expansion function.
Condition Values Returned
|
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$FREE_VM.
DCX$COMPRESS_INIT
The DCX$COMPRESS_INIT routine initializes the context area for the
compression of data records.
Format
DCX$COMPRESS_INIT context ,map
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.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Value identifying the data stream that DCX$COMPRESS_INIT initializes.
The context argument is the address of a longword
containing this value. You should not modify the
context value after DCX$COMPRESS_INIT initializes it.
You can define multiple context arguments to identify
multiple data streams that are processed simultaneously.
map
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The function created by DCX$MAKE_MAP. The map argument
is the address of the compression/expansion function's virtual address.
The map argument must remain at this address until
data compression is completed and the context is deleted by means of a
call to DCX$COMPRESS_DONE.
Description
The DCX$COMPRESS_INIT routine initializes the context area for the
compression of data records.
Call the DCX$COMPRESS_INIT routine after calling the DCX$ANALYZE_DONE
routine.
Condition Values Returned
|
DCX$_INVMAP
|
Error; invalid map. The
map argument was not specified correctly, or the
context area is invalid.
|
|
DCX$_NORMAL
|
Normal successful completion.
|
This routine also returns any condition values returned by LIB$GET_VM
and LIB$FREE_VM.
DCX$EXPAND_DATA
The DCX$EXPAND_DATA routine expands (or restores) a compressed data
record to its original state.
Format
DCX$EXPAND_DATA context ,in_rec ,out_rec [,out_length]
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.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Value identifying the data stream that DCX$EXPAND_DATA expands. The
context argument is the address of a longword
containing this value. DCX$EXPAND_INIT initializes this value; you
should not modify it. You can define multiple context
arguments to identify multiple data streams that are processed
simultaneously.
in_rec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Data record to be expanded. The in_rec argument is the
address of the descriptor of the data record string.
out_rec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Data record that has been expanded. The out_rec
argument is the address of the descriptor of the expanded record
returned by DCX$EXPAND_DATA.
out_length
| OpenVMS usage: |
word_signed |
| type: |
word integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Length (in bytes) of the expanded data record. The
out_length argument is the address of a word into
which DCX$EXPAND_DATA returns the length of the expanded data record.
Description
The DCX$EXPAND_DATA routine expands (or restores) a compressed data
record to its original state. Call this routine for each data record to
be expanded.
Condition Values Returned
|
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$_INVDATA
|
Error. A compressed data record is invalid (probably truncated) and
therefore cannot be expanded.
|
|
DCX$_INVMAP
|
Error; invalid map. The
map argument was not specified correctly, or the
context area is invalid.
|
|
DCX$_NORMAL
|
Normal successful completion.
|
|
DCX$_TRUNC
|
Warning. The expanded data record has been truncated because the
out_rec descriptor did not specify enough memory to
accommodate the record.
|
This routine also returns any condition values returned by
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.
|
