249 UTL_COMPRESS

The UTL_COMPRESS package provides a set of data compression utilities.

This chapter contains the following topics:

Using UTL_COMPRESS

Constants

Define max number of handles for piecewise operations:

UTLCOMP_MAX_HANDLE   CONSTANT  PLS_INTEGER := 5; 

Exceptions

Table 249-1 UTL_COMPRESS Exceptions

Exception Description

BUFFER_TOO_SMALL

The compressed representation is too big.

DATA_ERROR

The input or output data stream was found to be an invalid format.

INVALID_ARGUMENT

One of the arguments was an invalid type or value.

INVALID_HANDLE

Invalid handle for piecewise compress or uncompress.

STREAM_ERROR

An error occurred during compression or uncompression of the data stream


Operational Notes

  • It is the caller's responsibility to free the temporary LOB returned by the LZ* functions with DBMS_LOB.FREETEMPORARY call.

  • A BFILE passed into LZ_COMPRESS* or lZ_UNCOMPRESS* has to be opened by DBMS_LOB.FILEOPEN.

  • Under special circumstances (especially if the input has already been compressed) the output produced by one of the UTL_COMPRESS subprograms may be the same size, or even slightly larger than, the input.

  • The output of the UTL_COMPRESS compressed data is compatible with gzip(with -n option)/gunzip on a single file.

Summary of UTL_COMPRESS Subprograms

Table 249-2 UTL_COMPRESS Package Subprograms

Subprogram Description

ISOPEN Function

Checks to see if the handle to a piecewise (un)compress context is open or closed

LZ_COMPRESS Functions and Procedures

Compresses data using Lempel-Ziv compression algorithm

LZ_COMPRESS_ADD Procedure

Adds a piece of compressed data

LZ_COMPRESS_CLOSE

Closes and finishes piecewise compress operation

LZ_COMPRESS_OPEN

Initializes a piecewise context that maintains the compress state and data

LZ_UNCOMPRESS Functions and Procedures

Accepts compressed input, verifies it to be a valid and uncompresses it

LZ_UNCOMPRESS_EXTRACT Procedure

Extracts a piece of uncompressed data

LZ_UNCOMPRESS_OPEN Function

Initializes a piecewise context that maintains the uncompress state and data

LZ_UNCOMPRESS_CLOSE Procedure

Closes and finishes the piecewise uncompress


ISOPEN Function

This function checks to see if the handle to a piecewise (un)compress context is open or closed.

Syntax

UTL_COMPRESS.ISOPEN(
   handle in binary_integer) 
 RETURN BOOLEAN;

Parameters

Table 249-3 ISOPEN Function Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.


Return Values

TRUE if the given piecewise handle is opened, otherwise FALSE.

Examples

IF (UTL_COMPRESS.ISOPEN(myhandle) = TRUE) then 
   UTL_COMPRESS.LZ_COMPRESS_CLOSE(myhandle, lob_1); 
END IF; 

Alternatively:

IF (UTL_COMPRESS.ISOPEN(myhandle) = TRUE) THEN 
   UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE(myhandle); 
END IF; 

LZ_COMPRESS Functions and Procedures

These functions and procedures compress data using Lempel-Ziv compression algorithm.

Syntax

This function accept a RAW as input, compress it and return the compressed RAW result and metadata:

UTL_COMPRESS.LZ_COMPRESS (
   src       IN           RAW,
   quality   IN           BINARY_INTEGER DEFAULT 6) 
 RETURN RAW;

This function accept a BLOB as input, compress it and returns a temporary BLOB for the compressed data:

UTL_COMPRESS.LZ_COMPRESS (
  src       IN           BLOB,
  quality   IN           BINARY_INTEGER DEFAULT 6) 
 RETURN BLOB;

This procedure returns the compressed data into the existing BLOB(dst) which is trimmed to the compressed data size:

UTL_COMPRESS.LZ_COMPRESS (
  src      IN            BLOB, 
  dst      IN OUT NOCOPY BLOB, 
  quality  IN            BINARY_INTEGER DEFAULT 6);

This function returns a temporary BLOB for the compressed data:

UTL_COMPRESS.LZ_COMPRESS (
   src     IN            BFILE, 
   quality IN            BINARY_INTEGER DEFAULT 6) 
 RETURN BLOB;

This procedure will return the compressed data into the existing BLOB(dst) which is trimmed to the compressed data size:

UTL_COMPRESS.LZ_COMPRESS (
   src     IN            BFILE, 
   dst     IN OUT NOCOPY BLOB, 
   quality IN            BINARY_INTEGER DEFAULT 6); 

Parameters

Table 249-4 LZ_COMPRESS Function and Procedures Parameters

Parameter Description

src

Data (RAW, BLOB or BFILE) to be compressed.

dst

Destination for compressed data

quality

An integer in the range 1 to 9, 1=fast compression, 9=best compression, default=6


Usage Notes

  • quality is an optional compression tuning value. It allows the UTL_COMPRESS user to choose between speed and compression quality, meaning the percentage of reduction in size. A faster compression speed will result in less compression of the data. A slower compression speed will result in more compression of the data. Valid values are [1..9], with 1=fastest and 9=slowest. The default 'quality' value is 6.

LZ_COMPRESS_ADD Procedure

This procedure adds a piece of compressed data.

Syntax

UTL_COMPRESS.LZ_COMPRESS_ADD (
   handle IN             BINARY_INTEGER, 
   dst    IN OUT NOCOPY  BLOB, 
   src    IN             RAW); 

Parameters

Table 249-5 LZ_COMPRESS_ADD Procedure Parameters

Parameter Description

handle

The handle to a piecewise compress context.

dst

The opened LOB from LZ_COMPRESS_OPEN to store compressed data.

src

The input data to be compressed.


Exceptions

  • invalid_handle - out of range invalid or unopened handle.

  • invalid_argument - NULL handle, src, dst, or invalid dst.

LZ_COMPRESS_CLOSE

This procedure closes and finishes piecewise compress operation.

Syntax

UTL_COMPRESS.LZ_COMPRESS_CLOSE (
   handle IN             BINARY_INTEGER, 
   dst    IN OUT NOCOPY  BLOB); 

Parameters

Table 249-6 LZ_COMPRESS_CLOSE Procedure Parameters

Parameter Description

handle

The handle to a piecewise compress context.

dst

The opened LOB from LZ_COMPRESS_OPEN to store compressed data.


Exceptions

  • invalid_handle - out of range invalid or uninitialized handle.

  • invalid_argument - NULL handle, dst, or invalid dst.

LZ_COMPRESS_OPEN

This function initializes a piecewise context that maintains the compress state and data.

Syntax

UTL_COMPRESS.LZ_COMPRESS_OPEN (
   dst       IN OUT NOCOPY BLOB, 
   quality   IN            BINARY_INTEGER DEFAULT 6) 
 RETURN BINARY_INTEGER;

Parameters

Table 249-7 LZ_COMPRESS_OPEN Function Parameters

Parameter Description

dst

User supplied LOB to store compressed data.

quality

Speed versus efficiency of resulting compressed output.

  • Valid values are the range 1..9, with a default value of 6.

  • 1=fastest compression, 9=slowest compression and best compressed file size.


Return Values

A handle to an initialized piecewise compress context.

Exceptions

  • invalid_handle - invalid handle, too many open handles.

  • invalid_argument - NULL dst or invalid quality specified.

Usage Notes

Close the opened handle with LZ_COMPRESS_CLOSE

  • once the piecewise compress is completed

  • in the event of an exception in the middle of process

because lack of doing so will cause these handles to leak.

LZ_UNCOMPRESS Functions and Procedures

This procedure accepts as input a RAW, BLOB or BFILE compressed string, verifies it to be a valid compressed value, uncompresses it using Lempel-Ziv compression algorithm, and returns the uncompressed RAW or BLOB result.

Syntax

This function returns uncompressed data as RAW:

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  RAW)
  RETURN RAW;

This function returns uncompressed data as a temporary BLOB:

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BLOB)
  RETURN BLOB;

This procedure returns the uncompressed data into the existing BLOB(dst), which will be trimmed to the uncompressed data size:

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BLOB,
   dst  IN OUT NOCOPY BLOB); 

This function returns a temporary BLOB for the uncompressed data:

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN BFILE) 
 RETURN BLOB; 

This procedure returns the uncompressed data into the existing BLOB(dst). The original dst data will be overwritten.

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BFILE,
   dst  IN OUT NOCOPY BLOB); 

Parameters

Table 249-8 LZ_UNCOMPRESS Function and Procedures Parameters

Parameter Description

src

Compressed data.

dst

Destination for uncompressed data.


LZ_UNCOMPRESS_EXTRACT Procedure

This procedure extracts a piece of uncompressed data.

Syntax

UTL_COMPRESS.LZ_UNCOMPRESS_EXTRACT(
   handle  IN          BINARY_INTEGER, 
   dst     OUT NOCOPY  RAW); 

Parameters

Table 249-9 LZ_UNCOMPRESS_EXTRACT Function Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.

dst

The uncompressed data.


Exceptions

  • no_data_found - finished uncompress.

  • invalid_handle - out of range invalid or uninitialized handle.

  • invalid_argument - NULL handle.

LZ_UNCOMPRESS_OPEN Function

This function initializes a piecewise context that maintains the uncompress state and data.

Syntax

UTL_COMPRESS.LZ_UNCOMPRESS_OPEN(
   src  IN  BLOB)
  RETURN BINARY_INTEGER;

Parameters

Table 249-10 LZ_UNCOMPRESS_OPEN Function Parameters

Parameter Description

src

The input data to be uncompressed.


Return Values

A handle to an initialized piecewise compress context.

Exceptions

  • invalid_handle - invalid handle, too many open handles.

  • invalid_argument - NULL src.

Usage Notes

Close the opened handle with LZ_UNCOMPRESS_CLOSE

  • once the piecewise uncompress is completed

  • in the event of an exception in the middle of process

because lack of doing so will cause these handles to leak.

LZ_UNCOMPRESS_CLOSE Procedure

This procedure closes and finishes the piecewise uncompress.

Syntax

UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE(
   handle  IN   BINARY_INTEGER); 

Parameters

Table 249-11 LZ_UNCOMPRESS_CLOSE Procedure Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.


Exceptions

  • invalid_handle - out of range invalid or uninitialized handle.

  • invalid_argument - NULL handle.