The UTL_COMPRESS
package provides a set of data compression utilities.
This chapter contains the following topics:
Constants
Exceptions
Operational Notes
Define max number of handles for piecewise operations:
UTLCOMP_MAX_HANDLE CONSTANT PLS_INTEGER := 5;
Table 165-1 UTL_COMPRESS Exceptions
Exception | Description |
---|---|
|
The compressed representation is too big. |
|
The input or output data stream was found to be an invalid format. |
|
One of the arguments was an invalid type or value. |
|
Invalid handle for piecewise compress or uncompress. |
|
An error occurred during compression or uncompression of the data stream |
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.
Table 165-2 UTL_COMPRESS Package Subprograms
Subprogram | Description |
---|---|
Checks to see if the handle to a piecewise (un)compress context is open or closed |
|
Compresses data using Lempel-Ziv compression algorithm |
|
Adds a piece of compressed data |
|
Closes and finishes piecewise compress operation |
|
Initializes a piecewise context that maintains the compress state and data |
|
Accepts compressed input, verifies it to be a valid and uncompresses it |
|
Extracts a piece of uncompressed data |
|
Initializes a piecewise context that maintains the uncompress state and data |
|
Closes and finishes the piecewise uncompress |
This function checks to see if the handle to a piecewise (un)compress context is open or closed.
UTL_COMPRESS.ISOPEN( handle in binary_integer) RETURN BOOLEAN;
Table 165-3 ISOPEN Function Parameters
Parameter | Description |
---|---|
|
The handle to a piecewise uncompress context. |
TRUE
if the given piecewise handle is opened, otherwise FALSE
.
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;
These functions and procedures compress data using Lempel-Ziv compression algorithm.
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);
Table 165-4 LZ_COMPRESS Function and Procedures Parameters
Parameter | Description |
---|---|
|
Data ( |
|
Destination for compressed data |
|
An integer in the range 1 to 9, 1=fast compression, 9=best compression, default=6 |
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.
This procedure adds a piece of compressed data.
UTL_COMPRESS.LZ_COMPRESS_ADD ( handle IN BINARY_INTEGER, dst IN OUT NOCOPY BLOB, src IN RAW);
Table 165-5 LZ_COMPRESS_ADD Procedure Parameters
Parameter | Description |
---|---|
|
The handle to a piecewise compress context. |
|
The opened |
|
The input data to be compressed. |
invalid_handle
- out of range invalid or unopened handle.
invalid_argument
- NULL
handle, src, dst, or invalid dst
.
This procedure closes and finishes piecewise compress operation.
UTL_COMPRESS.LZ_COMPRESS_CLOSE ( handle IN BINARY_INTEGER, dst IN OUT NOCOPY BLOB);
Table 165-6 LZ_COMPRESS_CLOSE Procedure Parameters
Parameter | Description |
---|---|
|
The handle to a piecewise compress context. |
|
The opened |
invalid_handle
- out of range invalid or uninitialized handle.
invalid_argument
- NULL handle, dst
, or invalid dst
.
This function initializes a piecewise context that maintains the compress state and data.
UTL_COMPRESS.LZ_COMPRESS_OPEN ( dst IN OUT NOCOPY BLOB, quality IN BINARY_INTEGER DEFAULT 6) RETURN BINARY_INTEGER;
Table 165-7 LZ_COMPRESS_OPEN Function Parameters
Parameter | Description |
---|---|
|
User supplied LOB to store compressed data. |
|
Speed versus efficiency of resulting compressed output.
|
A handle to an initialized piecewise compress context.
invalid_handle
- invalid handle, too many open handles.
invalid_argument
- NULL
dst
or invalid quality specified.
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.
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.
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);
Table 165-8 LZ_UNCOMPRESS Function and Procedures Parameters
Parameter | Description |
---|---|
|
Compressed data. |
|
Destination for uncompressed data. |
This procedure extracts a piece of uncompressed data.
UTL_COMPRESS.LZ_UNCOMPRESS_EXTRACT( handle IN BINARY_INTEGER, dst OUT NOCOPY RAW);
Table 165-9 LZ_UNCOMPRESS_EXTRACT Function Parameters
Parameter | Description |
---|---|
|
The handle to a piecewise uncompress context. |
|
The uncompressed data. |
no_data_found
- finished uncompress.
invalid_handle
- out of range invalid or uninitialized handle.
invalid_argument
- NULL handle.
This function initializes a piecewise context that maintains the uncompress state and data.
UTL_COMPRESS.LZ_UNCOMPRESS_OPEN( src IN BLOB) RETURN BINARY_INTEGER;
Table 165-10 LZ_UNCOMPRESS_OPEN Function Parameters
Parameter | Description |
---|---|
|
The input data to be uncompressed. |
A handle to an initialized piecewise compress context.
invalid_handle
- invalid handle, too many open handles.
invalid_argument
- NULL
src
.
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.
This procedure closes and finishes the piecewise uncompress.
UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE( handle IN BINARY_INTEGER);
Table 165-11 LZ_UNCOMPRESS_CLOSE Procedure Parameters
Parameter | Description |
---|---|
|
The handle to a piecewise uncompress context. |
invalid_handle
- out of range invalid or uninitialized handle.
invalid_argument
- NULL
handle.