Skip Headers

PL/SQL Packages and Types Reference
10g Release 1 (10.1)

Part Number B10802-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

152
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 152-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 152-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 152-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 152-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 152-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 152-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 152-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 152-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 152-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 152-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 152-11 LZ_UNCOMPRESS_CLOSE Procedure Parameters
Parameter Description

handle

The handle to a piecewise uncompress context.

Exceptions