Deflate

Description:              This statement compresses/decompresses a buffer of data using the DEFLATE algorithm, and returns the compressed/decompressed data.

Returns:                    Numeric

Usage:                       Script

Format:                      Deflate(InputBuffer, Decompress [, DeflateHandle, MaxDecompressedLength, FlushMode, CompressionLevel, Format])

Parameters:             InputBuffer     { buffer }  { required }  { no default }
          Any expression that will yield a buffer of data to be compressed or decompressed. This can be a string, a buffer, or a stream.

                                    Decompress     { Boolean }  { required }  { no default }
          A Boolean value. If set to true (non-zero), the data in the InputBuffer is decompressed. If set to false (zero), the data in InputBuffer is compressed.

                                    DeflateHandle     { handle }  { optional }  { no default }
          An optional parameter identifying a variable that holds an existing deflate handle or is to receive a new deflate handle (see the "Comments" section below for further details).

                                    MaxDecompressedLength     { numeric }  { optional }  { no default }
          An optional parameter that specifies the maximum length of the decompressed output (see the "Comments" section below for further details).

                                    FlushMode     { numeric }  { optional }  { default: 2 }
          An optional numeric parameter that indicates the type of flushing that the encoder should use when processing the data.  Values are:

 

                             Effective use of this parameter requires an understanding of the ZLib library (www.gzip.org/zlib).  The default value is Z_SYNC_FLUSH which is appropriate for continuous, stream mode type operations.  For a single encoding, as in a file or a web page, then Z_FINISH is likely to be more appropriate.  It is not normally necessary to specify a flush value for decompress but, if one is specified, it will be used.

                                    CompressionLevel     { numeric }  { optional }  { default: 9 }
          An optional numeric parameter that indicates the level of aggressiveness of the encoder.  Values range between 0 and 9 with typical values being:

 

                             The default value used by VTS is Z_BEST_COMPRESSION which should be fine for most applications.  Z_DEFAULT_COMPRESSION requests a default compromise between speed and compression (currently equivalent to level 6).  Again, it is not necessary to specify this on decompression as the decoder can determine the encoding scheme used.

                                    Format     { numeric }  { optional }  { default: 0 }
          An optional numeric parameter that indicates the type of compression to use. ZLib is more intended for streams, while GZip for files. Both are simply wrappers around the actual deflated data. Raw Deflate can be used to obtain or process just the deflated data without the ZLib or GZip overhead. Values are:

 

Comments:               Compression/decompression is performed using an implementation of the DEFLATE algorithm (RFC 1951).

                             The DEFLATE algorithm is a dictionary-based compression technique, suitable for many types of data. A dictionary-based algorithm needs to include dictionary tokens in the output buffer, so compression of small buffers can give poor results. The DeflateHandle parameter is an opaque quantity that identifies an existing dictionary, or, if the variable it identifies does not hold an existing deflate handle, is set to a new deflate handle on return from the statement. Supplying the same deflate handle for successive calls to Deflate results in the existing dictionary being used and augmented on successive calls. This usually improves compression significantly.

                             If you make a series of calls to Deflate, using the same deflate handle to decompress, then you must make a series of calls in the same sequence, with the initial call obtaining a new deflate handle, and subsequent calls using the newly-acquired deflate handle (see the "Example" section below for further details).

                             MaxDecompressedLength is useful when you already know the size of the decompressed data (usually because you recorded it before compression was performed). While this parameter is not necessary, its use reduces the memory required to decompress the data.

                             The default size of MaxDecompressedLength is 65536 bytes.  Expanding data larger than this size will cause the output to be clipped unless a larger value is provided in this parameter.

Example:

If 1 Done;  

[  

  CompressedData = Deflate("Mary had a little lamb", 0{compress});  

  OriginalData = Deflate(CompressedData, 1{decompress});  

]  

In the above example, OriginalData will hold "Mary had a little lamb", after the second call to Deflate.

If 1 Done;  

[  

  CompressHandle = DecompressHandle = Invalid;  

  CompressedData = Deflate("Mary had a little lamb", 0{compress},

                           CompressHandle);  

  OriginalData = Deflate(CompressedData, 1{decompress},

                         DecompressHandle);  

  CompressedData = Deflate("Mary had a little lamb", 0{compress},

                           CompressHandle);  

  OriginalData = Deflate(CompressedData, 1{decompress},

                         DecompressHandle);  

  CompressedData = Deflate("Mary had a little lamb", 0{compress},

                         CompressHandle);  

  OriginalData = Deflate(CompressedData, 1{decompress},

                         DecompressHandle);  

]  

In this example, OriginalData will still hold "Mary had a little lamb" after each call to Deflate, however successive use of the same dictionary will result in later compressions of the string being more efficient (i.e. smaller). This is because the second and third compressions do not need to send dictionary tokens in the output stream, as the tokens are "remembered" in DecompressHandle. This technique allows highly efficient "stream-oriented" continuous compression, so long as the compressed data is fed into Deflate in exactly the same order as it was compressed. Note that separate handles need to be used for both compression and decompression, and that these handles will both be initialized on the first call to Deflate in which they are used.