java.lang.Object
- com.ibm.jzos.ZCompressor

All Implemented Interfaces:: BufferCompressor

public class ZCompressor
extends java.lang.Object
implements BufferCompressor

A wrapper for the z/Architecture CMPSC instruction.

Please refer to "z/Architecture Principles of Operation, SA22-7832-08" and "Enterprise Systems Architecture/390 Data Compression, SA22-7208-01" for details on the compression algorithm and on the CMPSC machine instruction.

The following CMPSC register 0 control bits are always set:

ST = 0 (no symbol translation)
F1 = 1 (dictionary has format-1 siblings)
ZP = 1 (zero padding may be done if the CMPSC-enhancement facility is installed)
CDSS = set based on dictionary symbol size as specified on ZCompressor constructor
E = 0 for compress, 1 for expand

The SAMPLE REXX exec 'SYS1.SAMPLIB(CSRBDICT)' may be used to create a compression and expansion dictionary for a representative sample dataset. The JCL below may be used to create these dictionaries and then to concatenate them into a single dataset as required by ZCompressor. See the documentation included in the comments of the CSRBDICT or in the above references for more information.


 //CSRBDICT JOB (),'USER'
 //*
 //* The following symbol defines the dataset containing the
 //* text that you will scan.  This will also become the
 //* prefix for other datasets that are created,
 //* and assumes that you have created a ".SPECFILE"
 //* dataset containing the specs for CSRBDICT.
 //* In this example, we will generate dictionaries with 4K entries 
 //* which implies 12 bit symbol sizes, since 4096 = 2**(12+3) / 8.
 //* 
 // SET DSNPREF=MYUSER.MOBYDICK
 //* 
 //TSOTMP   EXEC PGM=IKJEFT1A,DYNAMNBR=20
 //SYSPROC  DD  DSN=SYS1.SAMPLIB,DISP=SHR
 //SYSTSPRT DD  SYSOUT=*
 //SYSTSIN  DD  *
  %CSRBDICT 4 1 EB 'MYUSER.MOBYDICK'
 //* 
 //* Concatenate the dictionaries, selecting only
 //* the leading (non-blank) 8 bytes from each entry record
 //* This assumes that your specfile does NOT have the "asm"
 //* option.  For this example, the total size in bytes of the
 //* output dataset will be 64K (4K * 8 * 2).
 //* 
 //CONCAT   EXEC PGM=SORT,COND=(4,LT)
 //SORTIN   DD  DSN=&DSNPREF..ACDICT41,DISP=SHR
 //         DD  DSN=&DSNPREF..AEDICT41,DISP=SHR
 //SORTOUT  DD  DSN=&DSNPREF..CDICTS41,
 //             DISP=(NEW,CATLG),SPACE=(CYL,(1)),
 //             DCB=(LRECL=8,BLKSIZE=0,RECFM=FB)
 //SYSOUT   DD  SYSOUT=*
 //SYSIN    DD  *
  OPTION COPY
  INREC FIELDS=(1,8)
 //

For the above example, here are the contents of the &DSNPREF..SPECFILE dataset:


 ** This is the TEXT FILE example from SYS1.SAMPLIB(CSRBDICT):
 **    - removed "asm" option - output is 8-byte binary entries
 **    - added   "opt"
 **
 **The following is with a 4K-entry dictionary.
 **Provides 30.88% compression (output/input) for the source of
 **Chapter 5 of the ESA/390 Principles of Operation (30.32% if all output
 **bits are concatenated together).
 **Optimization (change x under opt to opt) improves compression by 0.7%.
 **results maxnodes maxlevels msglevel stepping prperiod dicts
   r       40000    60        3        f 7 2 7  1000     afd
 **colaps opt treedisp treehex treenode dupccs
   aam    opt x        h       n        x
 **FLD col type dcenmen              INT  intspec
   FLD 1   sa   dce 4                INT  aeis 1 (40)
                                     INT  a12b3s (40)
   FLD end
 **Note: Some text will be compressed better if the INT aeis 1 (40) is
 **omitted; i.e., try it with and without the INT aeis 1 (40).  Also, if
 **the text is ASCII instead of EBCDIC, the 40 should be changed to 20.

Since:: 2.4.4

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`ZCompressor.Result`	An instance of this inner class is returned for the continuous `compress(byte[], int, int, byte[], int, int)` and `expand(byte[], int, byte[], int, int, int)` methods to report the bytes and bits used in the input and output buffers.

Constructor Summary

Constructors
Constructor	Description
`ZCompressor(int bits, byte[] dictionaries)`	Construct a ZCompressor instance.
`ZCompressor(int bits, java.io.InputStream dictionaryStream)`	Construct a ZCompressor instance.
`ZCompressor(int bits, java.lang.String dictionaryFilename)`	Construct a ZCompressor instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`ZCompressor.Result`	`compress(byte[] output, int outoff, int outOffExtraBits, byte[] input, int inoff, int inlen)`	Compress data into a given byte and bit offset in a compressed buffer.
`int`	`compressBuffer(byte[] output, int outoff, byte[] input, int inoff, int inlen)`	Compress a discrete buffer.
`ZCompressor.Result`	`expand(byte[] output, int outoff, byte[] input, int inoff, int inOffExtraBits, int inlen)`	Expand data that was previously compressed by the same compression dictionary, starting at a given byte and bit offset in the input compressed buffer to a given offset in the output expansion buffer.
`int`	`expandBuffer(byte[] output, int outoff, byte[] input, int inoff, int inlen)`	Expand a discrete buffer.
`static int`	`getDictionaryLength(int symbolBits)`	Answer the size of a single dictionary, given the number of bits in a dictionary symbol.
`void`	`release()`	Release native resources (native dictionary memory) associated with this object.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ZCompressor
```
public ZCompressor(int bits,
                   byte[] dictionaries)
```
    Construct a ZCompressor instance.
    
    Parameters:
    
    bits - the number of bits in a dictionary symbol
    
    dictionaries - a byte array containing the compression dictionary followed by the expansion dictionary
    
    Throws:
    
    java.lang.IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments
  - ZCompressor
```
public ZCompressor(int bits,
                   java.io.InputStream dictionaryStream)
            throws java.io.IOException
```
    Construct a ZCompressor instance.
    
    Parameters:
    
    bits - the number of bits in a dictionary symbol
    
    dictionaryStream - a binary InputStream that contains the compression dictionary followed by the expansion dictionary
    
    Throws:
    
    java.io.IOException - if there is an error reading the dictionaries from the dictionaryStream
    
    java.lang.IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments
  - ZCompressor
```
public ZCompressor(int bits,
                   java.lang.String dictionaryFilename)
            throws java.io.IOException
```
    Construct a ZCompressor instance.
    
    Parameters:
    
    bits - the number of bits in a dictionary symbol
    
    dictionaryFilename - the //fully.qualified.dsn (no quotes required) or the z/OS Unix file name that contains the compression dictionary followed by the expansion dictionary
    
    Throws:
    
    java.io.IOException - if there is an error reading the dictionaries from the dictionary file
    
    java.lang.IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments
- Method Detail
  - getDictionaryLength
```
public static int getDictionaryLength(int symbolBits)
```
    Answer the size of a single dictionary, given the number of bits in a dictionary symbol. This size should be doubled to get the size of combined compression and expansion dictionaries.
    
    Parameters:
    
    symbolBits - the length in bits of a dictionary symbol
    
    Returns:
    
    int size of a dictionary
    
    Throws:
    
    java.lang.IllegalArgumentException - if not 9 <= symbolBits <= 13
  - release
```
public void release()
```
    Release native resources (native dictionary memory) associated with this object. Called automatically by object finalization, but explicit call of this method is recommended when no longer used.
    Note: release should not be invoked on a ZCompressor instance that is concurrently being used by other threads.
  - compressBuffer
```
public int compressBuffer(byte[] output,
                          int outoff,
                          byte[] input,
                          int inoff,
                          int inlen)
                   throws RcException
```
    Description copied from interface: BufferCompressor
    
    Compress a discrete buffer.
    
    Specified by:
    
    compressBuffer in interface BufferCompressor
    
    Parameters:
    
    output - output buffer that will hold the compressed data
    
    outoff - offset into the output buffer to write the compressed data
    
    input - input buffer containing the data to be compressed
    
    inoff - offset into the input buffer
    
    inlen - the size of the data to be compressed
    
    Returns:
    
    If the entire input buffer was compressed, this method returns the number of bytes used in the compressed output buffer, including the last partial byte (if any). If the entire input buffer could not be compressed into the given output buffer, this method returns a negative integer. This is an error, indicating that the request must be retried completely with a larger output buffer.
    
    Throws:
    
    RcException - if the underlying z/Architecture CMPSC instruction encounters a data exception or an access exception
    
    See Also:
    
    BufferCompressor.compressBuffer(byte[], int, byte[], int, int)
  - compress
```
public ZCompressor.Result compress(byte[] output,
                                   int outoff,
                                   int outOffExtraBits,
                                   byte[] input,
                                   int inoff,
                                   int inlen)
                            throws RcException
```
    Compress data into a given byte and bit offset in a compressed buffer.
    This method should be used when making repeated calls to compress contiguous blocks of input data. Each call should set outOffExtraBits to be the previous call's ZCompressor.Result.getExtraCompressedBitsUsed() value.
    
    Parameters:
    
    output - the output compression buffer
    
    outoff - the starting offset in the compression buffer
    
    outOffExtraBits - the starting bit offset in compression buffer
    
    input - the input buffer to be compressed
    
    inoff - the offset to the first byte to be compressed
    
    inlen - the number of bytes of input data to be compressed
    
    Returns:
    
    a ZCompressor.Result that indicates the source and target bytes used as well as the extra compressed bits used in the compressed output buffer
    
    Throws:
    
    RcException - if the underlying CMPSC instruction encounters a data exception or an access exception
  - expandBuffer
```
public int expandBuffer(byte[] output,
                        int outoff,
                        byte[] input,
                        int inoff,
                        int inlen)
                 throws RcException
```
    Description copied from interface: BufferCompressor
    
    Expand a discrete buffer.
    
    Specified by:
    
    expandBuffer in interface BufferCompressor
    
    Parameters:
    
    output - output buffer that will hold the expanded data
    
    outoff - offset into the output buffer to write the expanded data
    
    input - input buffer containing the data to be expanded
    
    inoff - offset into the input buffer
    
    inlen - the size of the data to be expanded
    
    Returns:
    
    If the entire input buffer was expanded, this method returns the number of bytes used in the expanded output buffer. If the entire input buffer could not be expanded into the given output buffer, this method returns a negative integer. This is an error, indicating that the request must be retried completely with a larger output buffer.
    
    Throws:
    
    RcException - if the underlying z/Architecture CMPSC instruction encounters a data exception or an access exception
    
    See Also:
    
    BufferCompressor.expandBuffer(byte[], int, byte[], int, int)
  - expand
```
public ZCompressor.Result expand(byte[] output,
                                 int outoff,
                                 byte[] input,
                                 int inoff,
                                 int inOffExtraBits,
                                 int inlen)
                          throws RcException
```
    Expand data that was previously compressed by the same compression dictionary, starting at a given byte and bit offset in the input compressed buffer to a given offset in the output expansion buffer.
    This method should be used when making repeated calls to expand contiguous blocks of input data. Each call should set inOffExtraBits to be the previous call's ZCompressor.Result.getExtraCompressedBitsUsed() value.
    
    Parameters:
    
    output - the target expansion buffer
    
    outoff - the starting offset in the expansion buffer
    
    input - the compressed input buffer
    
    inoff - the starting byte offset in the compressed input buffer
    
    inOffExtraBits - the starting bit offset in the starting byte of the compressed input buffer
    
    inlen - the number of bytes in the compressed input buffer to expand
    
    Returns:
    
    a ZCompressor.Result that indicates the source and target bytes used as well as the extra compressed bits used in the compressed input buffer
    
    Throws:
    
    RcException - if the underlying CMPSC instruction encounters a data exception or an access exception

Class ZCompressor

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ZCompressor

ZCompressor

ZCompressor

Method Detail

getDictionaryLength

release

compressBuffer

compress

expandBuffer

expand