Skip Headers
Oracle® Database PL/SQL Packages and Types Reference
10g Release 2 (10.2)

Part Number B14258-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

164 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 164-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


Summary of UTL_COMPRESS Subprograms

Table 164-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 164-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 164-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


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 164-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


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 164-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


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 164-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

Usage Notes

Close the opened handle with LZ_COMPRESS_CLOSE

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 164-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 164-9 LZ_UNCOMPRESS_EXTRACT Function Parameters

Parameter Description
handle The handle to a piecewise uncompress context.
dst The uncompressed data.

Exceptions


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 164-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

Usage Notes

Close the opened handle with LZ_UNCOMPRESS_CLOSE

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 164-11 LZ_UNCOMPRESS_CLOSE Procedure Parameters

Parameter Description
handle The handle to a piecewise uncompress context.

Exceptions