The Data Compression/Expansion (DCX) facility routines decrease
the size of text, binary data, images, and any other type of
data. There is no DCL-level interface to this facility, nor is
there a DCX utility.
1 – DCX$ANALYZE_DATA
The DCX$ANALYZE_DATA routine performs statistical analysis
on a data record. The results of the analysis are accumulated
internally in the context area and are used by the DCX$MAKE_MAP
routine to compute the mapping function.
Format
DCX$ANALYZE_DATA context ,record
1.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.
1.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: read only
mechanism: by reference
Value identifying the data stream that DCX$ANALYZE_DATA analyzes.
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.
record
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Record to be analyzed. DCX$ANALYZE_DATA reads the record
argument, which is the address of a descriptor for the record
string. The maximum length of the record string is 65,535
characters.
1.3 – Description
The DCX$ANALYZE_DATA routine performs statistical analysis on
a single data record. This routine is called once for each data
record to be analyzed.
During analysis, the DCX facility gathers information that
DCX$MAKE_MAP uses to create the compression/expansion function
for the file. After the data records have been analyzed, call
the DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status
code from DCX$MAKE_MAP, you must again analyze the same data
records (in the same order) using DCX$ANALYZE_DATA and then call
DCX$MAKE_MAP again. On the second iteration, DCX$MAKE_MAP returns
the DCX$_NORMAL status code, and the data analysis is complete.
1.4 – 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$ANALYZE_SDESC_R2.
2 – 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
2.1 – 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.
2.2 – 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.
2.3 – 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.
3 – 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]
3.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.
3.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.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.
3.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.
4 – 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]
4.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.
4.2 – 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.
4.3 – 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.
4.4 – 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.
5 – DCX$COMPRESS_DONE
The DCX$COMPRESS_DONE routine deletes the context area and sets
the context variable to zero.
Format
DCX$COMPRESS_DONE context
5.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.
5.2 – 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.
5.3 – 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.
5.4 – 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.
6 – DCX$COMPRESS_INIT
The DCX$COMPRESS_INIT routine initializes the context area for
the compression of data records.
Format
DCX$COMPRESS_INIT context ,map
6.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.
6.2 – 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.
6.3 – 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.
6.4 – 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.
7 – 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]
7.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.
7.2 – 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.
7.3 – 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.
7.4 – 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.
8 – DCX$EXPAND_DONE
The DCX$EXPAND_DONE routine deletes the context area and sets the
context variable to zero.
Format
DCX$EXPAND_DONE context
8.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.
8.2 – Argument
context
OpenVMS usage:context
type: longword (unsigned)
access: write only
mechanism: by reference
Value identifying the data stream that DCX$EXPAND_DONE deletes.
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.
8.3 – Description
The DCX$EXPAND_DONE routine deletes the context area and sets
the context variable to zero, thus undoing the work of the
DCX$EXPAND_INIT routine. Call DCX$EXPAND_DONE when all data
records have been expanded (using DCX$EXPAND_DATA).
8.4 – 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.
9 – DCX$EXPAND_INIT
The DCX$EXPAND_INIT routine initializes the context area for the
expansion of data records.
Format
DCX$EXPAND_INIT context ,map
9.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.
9.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: write only
mechanism: by reference
Value identifying the data stream that DCX$EXPAND_INIT
initializes. The context argument is the address of a longword
containing this value. After DCX$EXPAND_INIT initializes this
context value, you should not modify 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
Compression/expansion 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 expansion
is completed and context is deleted by means of a call to
DCX$EXPAND_DONE.
9.3 – Description
The DCX$EXPAND_INIT routine initializes the context area for the
expansion of data records.
Call the DCX$EXPAND_INIT routine as the first step in the
expansion (or restoration) of compressed data records to their
original state.
Before you call DCX$EXPAND_INIT, read the length of the
compressed file from the compression/expansion function (the
map). Invoke LIB$GET_VM to get the necessary amount of storage
for the function. LIB$GET_VM returns the address of the first
byte of the storage area.
9.4 – 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.
10 – DCX$MAKE_MAP
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]
10.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.
10.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.
10.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.
10.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.