Module ibm.jzos
Package com.ibm.jzos

Class ZCompressor

java.lang.Object
com.ibm.jzos.ZCompressor
All Implemented Interfaces:
BufferCompressor
public class ZCompressor extends 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, InputStream dictionaryStream)
    Construct a ZCompressor instance.
    ZCompressor(int bits, String dictionaryFilename)
    Construct a ZCompressor instance.

  • Method Summary

    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 Details

    • 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:
      IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments

    • ZCompressor

      public ZCompressor(int bits, InputStream dictionaryStream) throws 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:
      IOException - if there is an error reading the dictionaries from the dictionaryStream
      IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments

    • ZCompressor

      public ZCompressor(int bits, String dictionaryFilename) throws 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:
      IOException - if there is an error reading the dictionaries from the dictionary file
      IllegalArgumentException - for invalid or incompatible dictionary or symbol bit length arguments

  • Method Details

    • 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:
      IllegalArgumentException - if not 9 invalid input: '<'= symbolBits invalid input: '<'= 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:

    • 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:

    • 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