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:
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 have downloaded the public domain text
//* of "Moby Dick" from http://www.gutenberg.org/files/2701/2701.txt
//* and 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.
Modifier and Type | Class and 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 and 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.
|
Modifier and Type | Method and 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.
|
public ZCompressor(int bits, byte[] dictionaries)
bits
- the number of bits in a dictionary symboldictionaries
- a byte array containing the compression dictionary followed by the
expansion dictionaryjava.lang.IllegalArgumentException
- for invalid or incompatible dictionary or symbol bit length argumentspublic ZCompressor(int bits, java.io.InputStream dictionaryStream) throws java.io.IOException
bits
- the number of bits in a dictionary symboldictionaryStream
- a binary InputStream that contains the compression dictionary
followed by the expansion dictionaryjava.io.IOException
- if there is an error reading the dictionaries from the dictionaryStreamjava.lang.IllegalArgumentException
- for invalid or incompatible dictionary or symbol bit length argumentspublic ZCompressor(int bits, java.lang.String dictionaryFilename) throws java.io.IOException
bits
- the number of bits in a dictionary symboldictionaryFilename
- the //fully.qualified.dsn (no quotes required) or the z/OS Unix
file name that contains the compression dictionary followed by the expansion dictionaryjava.io.IOException
- if there is an error reading the dictionaries from the dictionary filejava.lang.IllegalArgumentException
- for invalid or incompatible dictionary or symbol bit length argumentspublic static int getDictionaryLength(int symbolBits)
symbolBits
- the length in bits of a dictionary symboljava.lang.IllegalArgumentException
- if not 9 <= symbolBits <= 13public void release()
Note: release should not be invoked on a ZCompressor instance that is concurrently being used by other threads.
public int compressBuffer(byte[] output, int outoff, byte[] input, int inoff, int inlen) throws RcException
BufferCompressor
compressBuffer
in interface BufferCompressor
output
- output buffer that will hold the compressed dataoutoff
- offset into the output buffer to write the compressed datainput
- input buffer containing the data to be compressedinoff
- offset into the input bufferinlen
- the size of the data to be compressedRcException
- if the underlying z/Architecture CMPSC instruction
encounters a data exception or an access exceptionBufferCompressor.compressBuffer(byte[], int, byte[], int, int)
public ZCompressor.Result compress(byte[] output, int outoff, int outOffExtraBits, byte[] input, int inoff, int inlen) throws RcException
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.
output
- the output compression bufferoutoff
- the starting offset in the compression bufferoutOffExtraBits
- the starting bit offset in compression bufferinput
- the input buffer to be compressedinoff
- the offset to the first byte to be compressedinlen
- the number of bytes of input data to be compressedZCompressor.Result
that indicates the source and target bytes used as
well as the extra compressed bits used in the compressed output bufferRcException
- if the underlying CMPSC instruction encounters a
data exception or an access exceptionpublic int expandBuffer(byte[] output, int outoff, byte[] input, int inoff, int inlen) throws RcException
BufferCompressor
expandBuffer
in interface BufferCompressor
output
- output buffer that will hold the expanded dataoutoff
- offset into the output buffer to write the expanded datainput
- input buffer containing the data to be expandedinoff
- offset into the input bufferinlen
- the size of the data to be expandedRcException
- if the underlying z/Architecture CMPSC instruction
encounters a data exception or an access exceptionBufferCompressor.expandBuffer(byte[], int, byte[], int, int)
public ZCompressor.Result expand(byte[] output, int outoff, byte[] input, int inoff, int inOffExtraBits, int inlen) throws RcException
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.
output
- the target expansion bufferoutoff
- the starting offset in the expansion bufferinput
- the compressed input bufferinoff
- the starting byte offset in the compressed input bufferinOffExtraBits
- the starting bit offset in the starting byte of the compressed input bufferinlen
- the number of bytes in the compressed input buffer to expandZCompressor.Result
that indicates the source and target bytes used as
well as the extra compressed bits used in the compressed input bufferRcException
- if the underlying CMPSC instruction encounters a
data exception or an access exception