1 DCX_Routines 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. 2 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 3 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 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. 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. 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$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 3 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. 3 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. 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. 2 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 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 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. 3 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. 2 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] 3 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 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. 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. 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$_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. 2 DCX$COMPRESS_DONE The DCX$COMPRESS_DONE routine deletes the context area and sets the context variable to zero. Format DCX$COMPRESS_DONE context 3 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 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. 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. 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. 2 DCX$COMPRESS_INIT The DCX$COMPRESS_INIT routine initializes the context area for the compression of data records. Format DCX$COMPRESS_INIT context ,map 3 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 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. 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. 3 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. 2 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] 3 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 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. 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. 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$_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. 2 DCX$EXPAND_DONE The DCX$EXPAND_DONE routine deletes the context area and sets the context variable to zero. Format DCX$EXPAND_DONE context 3 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 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. 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). 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. 2 DCX$EXPAND_INIT The DCX$EXPAND_INIT routine initializes the context area for the expansion of data records. Format DCX$EXPAND_INIT context ,map 3 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 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. 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. 3 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. 2 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] 3 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 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. 3 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.