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

Part Number E25788-04
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
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub
ARPLS381

221 UTL_COMPRESS

The UTL_COMPRESS package provides a set of data compression utilities.

This chapter contains the following topics:

ARPLS70827

Using UTL_COMPRESS

ARPLS70828

Constants

Define max number of handles for piecewise operations:

UTLCOMP_MAX_HANDLE   CONSTANT  PLS_INTEGER := 5; 
ARPLS70829

Exceptions

ARPLS70830Table 221-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


ARPLS70831

Operational Notes

ARPLS70832

Summary of UTL_COMPRESS Subprograms

ARPLS70833Table 221-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


ARPLS70834

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

ARPLS70835Table 221-3 ISOPEN Function Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.


ARPLS70836

Return Values

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

ARPLS70837

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; 
ARPLS70838

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

ARPLS70839Table 221-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

ARPLS70840

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

ARPLS70841Table 221-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.


ARPLS70842

Exceptions

ARPLS70843

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

ARPLS70844Table 221-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.


ARPLS70845

Exceptions

ARPLS70846

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

ARPLS70847Table 221-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.


ARPLS70848

Return Values

A handle to an initialized piecewise compress context.

ARPLS70849

Exceptions

ARPLS70850

Usage Notes

Close the opened handle with LZ_COMPRESS_CLOSE

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

ARPLS70851

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

ARPLS70852Table 221-8 LZ_UNCOMPRESS Function and Procedures Parameters

Parameter Description

src

Compressed data.

dst

Destination for uncompressed data.


ARPLS70853

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

ARPLS70854Table 221-9 LZ_UNCOMPRESS_EXTRACT Function Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.

dst

The uncompressed data.


ARPLS70855

Exceptions

ARPLS70856

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

ARPLS70857Table 221-10 LZ_UNCOMPRESS_OPEN Function Parameters

Parameter Description

src

The input data to be uncompressed.


ARPLS70858

Return Values

A handle to an initialized piecewise compress context.

ARPLS70859

Exceptions

ARPLS70860

Usage Notes

Close the opened handle with LZ_UNCOMPRESS_CLOSE

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

ARPLS70861

LZ_UNCOMPRESS_CLOSE Procedure

This procedure closes and finishes the piecewise uncompress.

Syntax

UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE(
   handle  IN   BINARY_INTEGER); 

Parameters

ARPLS70862Table 221-11 LZ_UNCOMPRESS_CLOSE Procedure Parameters

Parameter Description

handle

The handle to a piecewise uncompress context.


ARPLS70863

Exceptions

Reader Comment

   

Comments, corrections, and suggestions are forwarded to authors every week. By submitting, you confirm you agree to the terms and conditions. Use the OTN forums for product questions. For support or consulting, file a service request through My Oracle Support.

Hide Navigation

Quick Lookup

Database Library · Master Index · Master Glossary · Book List · Data Dictionary · SQL Keywords · Initialization Parameters · Advanced Search · Error Messages

Main Categories

This Page

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF