MINI MINI MANI MO
REM
REM $Header: plsql/admin/utlcomp.sql /main/9 2014/02/20 12:45:37 surman Exp $
REM
REM utlcomp.sql
REM
REM Copyright (c) 2001, 2014, Oracle and/or its affiliates.
REM All rights reserved.
REM
REM NAME
REM utlcomp.sql - PL/SQL Package for COMPRESSION (UTL_COMPRESS)
REM
REM DESCRIPTION
REM PL/SQL package to compress and uncompress RAW data strings.
REM
REM NOTES
REM
REM 1. It is the caller's responsibility to free the temporary lob returned
REM by the lz* functions with dbms_lob.freetemporary() call.
REM
REM 2. BFILE passed into lz_compress* or lz_uncompress* has to be opened
REM by dbms_lob.fileopen().
REM
REM 3. Compression is does not always result in smaller output.
REM For certain data, the size of compressed output be even
REM larger than original data because the input data is already
REM compressed.
REM
REM 4. As a corollary of 3, the compression ratio could stay the same
REM regardless of the level of quality specified, especially
REM when the data provided is already compressed.
REM
REM 5. The output of the utl_compress compressed data is compatible with
REM gzip(with -n option)/gunzip on a single file.
REM
REM
REM BEGIN SQL_FILE_METADATA
REM SQL_SOURCE_FILE: plsql/admin/utlcomp.sql
REM SQL_SHIPPED_FILE: rdbms/admin/utlcomp.sql
REM SQL_PHASE: UTLCOMP
REM SQL_STARTUP_MODE: NORMAL
REM SQL_IGNORABLE_ERRORS: NONE
REM SQL_CALLING_FILE: rdbms/admin/catpdbms.sql
REM END SQL_FILE_METADATA
REM
REM MODIFIED (MM/DD/YY)
REM surman 12/29/13 - 13922626: Update SQL metadata
REM surman 03/27/12 - 13615447: Add SQL patching tags
REM sylin 09/30/03 - Add more notes
REM lvbcheng 09/09/03 - Remove second arg from example
REM sylin 08/27/03 - Remove ratio from lz_compress
REM sylin 07/16/03 - Add BLOB piecewise uncompress support
REM sylin 07/08/03 - Add BFILE support
REM sylin 06/16/03 - Add BLOB piecewise compress support
REM sylin 06/12/03 - Add blob overloads
REM sylin 04/29/03 - BLOB support
REM sylin 05/08/03 - Change error 29258 to 29297
REM eehrsam 09/06/02 - eehrsam_new_utl_compress_pkg
REM eehrsam 12/03/01 - Created
REM
@@?/rdbms/admin/sqlsessstart.sql
CREATE OR REPLACE PACKAGE utl_compress AS
/* Define max number of handles for piecewise operations */
UTLCOMP_MAX_HANDLE CONSTANT PLS_INTEGER := 5;
/*
** Exceptions
*/
invalid_handle EXCEPTION;
invalid_argument EXCEPTION;
buffer_too_small EXCEPTION;
data_error EXCEPTION;
stream_error EXCEPTION;
invalid_argument_errcode CONSTANT PLS_INTEGER:= -29261;
buffer_too_small_errcode CONSTANT PLS_INTEGER:= -29297;
data_error_errcode CONSTANT PLS_INTEGER:= -29294;
stream_error_errcode CONSTANT PLS_INTEGER:= -29293;
invalid_handle_errcode CONSTANT PLS_INTEGER:= -29299;
PRAGMA EXCEPTION_INIT(invalid_argument, -29261);
PRAGMA EXCEPTION_INIT(buffer_too_small, -29297);
PRAGMA EXCEPTION_INIT(data_error, -29294);
PRAGMA EXCEPTION_INIT(stream_error, -29293);
PRAGMA EXCEPTION_INIT(invalid_handle, -29299);
/*----------------------------------------------------------------*/
/* LZ_COMPRESS */
/*----------------------------------------------------------------*/
/* LZ_COMPRESS - compress data
**
** This compression utility uses a basic form of the Lempel-Ziv
** compression algorithm.
**
** PARAMETERS
** src - the input data to be compressed
** 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
** the compressed data
**
*/
function lz_compress(src in raw,
quality in binary_integer default 6) return raw;
/* This lz_compress overload will return a temporary BLOB for the
* compressed data.
*/
function lz_compress(src in blob,
quality in binary_integer default 6) return blob;
/* This lz_compress overload will return the compressed data into the
* existing BLOB, dst. Original data will be overwritten.
*/
procedure lz_compress(src in blob,
dst in out nocopy blob,
quality in binary_integer default 6);
/* This lz_compress overload will return a temporary BLOB for the
* compressed data.
*/
function lz_compress(src in bfile,
quality in binary_integer default 6) return blob;
/* This lz_compress overload will return the compressed data into the
* existing BLOB, dst. Original data will be overwritten.
*/
procedure lz_compress(src in bfile,
dst in out nocopy blob,
quality in binary_integer default 6);
/*----------------------------------------------------------------*/
/* LZ_UNCOMPRESS */
/*----------------------------------------------------------------*/
/* LZ_UNCOMPRESS - uncompress data
**
** This compression utility uses a basic form of the Lempel-Ziv
** compression algorithm.
**
** PARAMETERS
** src - the input compressed data
**
** RETURN
** the uncompressed data
**
*/
function lz_uncompress(src in raw) return raw;
/* This lz_uncompress overload will return a temporary BLOB for the
* uncompressed data.
*/
function lz_uncompress(src in blob) return blob;
/* This lz_uncompress overload will return the uncompressed data into the
* existing BLOB, dst. Original dst data will be overwritten.
*/
procedure lz_uncompress(src in blob, dst in out nocopy blob);
/* This lz_uncompress overload will return a temporary BLOB for the
* uncompressed data.
*/
function lz_uncompress(src in bfile) return blob;
/* This lz_uncompress overload will return the uncompressed data into the
* existing BLOB, dst. Original dst data will be overwritten.
*/
procedure lz_uncompress(src in bfile, dst in out nocopy blob);
/* PIECEWISE COMPRESS */
/*
** lz_compress_open - Initialize a piecewise context that maintains the
** compress state and data.
**
** PARAMETERS
** 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
** 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.
**
** NOTES
** Make sure to close the opened handle with lz_compress_close once
** the piecewise compress is done and in the event of an exception in
** the middle of process, since lack of doing so will cause these
** handles to leak.
**
*/
function lz_compress_open(dst in out nocopy blob,
quality in binary_integer default 6)
return binary_integer;
/*
** lz_compress_add - add a piece of compressed data.
**
** PARAMETERS
** handle - handle to a piecewise compress context.
** dst - opened LOB from lz_compress_open to store compressed data.
** src - input data to be compressed.
**
** EXCEPTIONS
** invalid_handle - out of range invalid or unopened handle
** invalid_argument - NULL handle, src, dst, or invalid dst.
**
*/
procedure lz_compress_add(handle in binary_integer,
dst in out nocopy blob,
src in raw);
/*
** lz_compress_close - close and finish piecewise compress.
**
** PARAMETERS
** handle - handle to a piecewise compress context.
** dst - 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.
**
*/
procedure lz_compress_close(handle in binary_integer,
dst in out nocopy blob);
/* PIECEWISE Uncompress */
/*
** lz_uncompress_open - Initialize a piecewise context that maintains the
** uncompress state and data.
**
** PARAMETERS
** src - input data to be uncompressed.
**
** RETURN
** A handle to an initialized piecewise uncompress context.
**
** EXCEPTIONS
** invalid_handle - invalid handle, too many open handles.
** invalid_argument - NULL src.
**
** NOTES
** Make sure to close the opened handle with lz_uncompress_close once
** the piecewise uncompress is done and in the event of an exception in
** the middle of process, since lack of doing so will cause these
** handles to leak.
**
*/
function lz_uncompress_open(src in blob) return binary_integer;
/*
** lz_uncompress_extract - extract a piece of uncompressed data.
**
** PARAMETERS
** handle - handle to a piecewise uncompress context.
** dst - uncompressed data.
**
** EXCEPTIONS
** no_data_found - finished uncompress.
** invalid_handle - out of range invalid or uninitialized handle.
** invalid_argument - NULL handle.
*/
procedure lz_uncompress_extract(handle in binary_integer,
dst out nocopy raw);
/*
** lz_uncompress_close - close and finish piecewise uncompress.
**
** PARAMETERS
** handle - handle to a piecewise uncompress context.
**
** EXCEPTIONS
** invalid_handle - out of range invalid or uninitialized handle.
** invalid_argument - NULL handle.
**
*/
procedure lz_uncompress_close(handle in binary_integer);
/*
** isopen - Checks to see if the handle to a piecewise (un)compress context
** was opened or closed.
**
** PARAMETERS
** handle - handle to a piecewise (un)compress context.
**
** RETURN
** TRUE, if the given piecewise handle is opened, otherwise FALSE.
**
** Example
** if (utl_compress.isopen(myhandle) = TRUE) then
** utl_compress.lz_compress_close(myhandle, lob_1);
** end if;
**
** or
**
** if (utl_compress.isopen(myhandle) = TRUE) then
** utl_compress.lz_uncompress_close(myhandle);
** end if;
**
*/
function isopen(handle in binary_integer) return boolean;
END;
/
GRANT EXECUTE ON utl_compress TO PUBLIC;
CREATE OR REPLACE PUBLIC SYNONYM utl_compress FOR sys.utl_compress;
@?/rdbms/admin/sqlsessend.sql
OHA YOOOO