1 PACKAGE utl_compress AS
2
3 /* Define max number of handles for piecewise operations */
4 UTLCOMP_MAX_HANDLE CONSTANT PLS_INTEGER := 5;
5
6 /*
7 ** Exceptions
8 */
9 invalid_handle EXCEPTION;
10 invalid_argument EXCEPTION;
11 buffer_too_small EXCEPTION;
12 data_error EXCEPTION;
13 stream_error EXCEPTION;
14
15 invalid_argument_errcode CONSTANT PLS_INTEGER:= -29261;
16 buffer_too_small_errcode CONSTANT PLS_INTEGER:= -29297;
17 data_error_errcode CONSTANT PLS_INTEGER:= -29294;
18 stream_error_errcode CONSTANT PLS_INTEGER:= -29293;
19 invalid_handle_errcode CONSTANT PLS_INTEGER:= -29299;
20
21 PRAGMA EXCEPTION_INIT(invalid_argument, -29261);
22 PRAGMA EXCEPTION_INIT(buffer_too_small, -29297);
23 PRAGMA EXCEPTION_INIT(data_error, -29294);
24 PRAGMA EXCEPTION_INIT(stream_error, -29293);
25 PRAGMA EXCEPTION_INIT(invalid_handle, -29299);
26
27 /*----------------------------------------------------------------*/
28 /* LZ_COMPRESS */
29 /*----------------------------------------------------------------*/
30
31 /* LZ_COMPRESS - compress data
32 **
33 ** This compression utility uses a basic form of the Lempel-Ziv
34 ** compression algorithm.
35 **
36 ** PARAMETERS
37 ** src - the input data to be compressed
38 ** quality - speed versus efficiency of resulting compressed output.
39 ** Valid values are the range 1..9, with a default value of 6.
40 ** 1=fastest compression, 9=slowest compression and best
41 ** compressed file size.
42 **
43 ** RETURN
44 ** the compressed data
45 **
46 */
47
48 function lz_compress(src in raw,
49 quality in binary_integer default 6) return raw;
50
51 /* This lz_compress overload will return a temporary BLOB for the
52 * compressed data.
53 */
54 function lz_compress(src in blob,
55 quality in binary_integer default 6) return blob;
56
57 /* This lz_compress overload will return the compressed data into the
58 * existing BLOB, dst. Original data will be overwritten.
59 */
60 procedure lz_compress(src in blob,
61 dst in out nocopy blob,
62 quality in binary_integer default 6);
63
64
65 /* This lz_compress overload will return a temporary BLOB for the
66 * compressed data.
67 */
68 function lz_compress(src in bfile,
69 quality in binary_integer default 6) return blob;
70
71 /* This lz_compress overload will return the compressed data into the
72 * existing BLOB, dst. Original data will be overwritten.
73 */
74 procedure lz_compress(src in bfile,
75 dst in out nocopy blob,
76 quality in binary_integer default 6);
77
78 /*----------------------------------------------------------------*/
79 /* LZ_UNCOMPRESS */
80 /*----------------------------------------------------------------*/
81
82 /* LZ_UNCOMPRESS - uncompress data
83 **
84 ** This compression utility uses a basic form of the Lempel-Ziv
85 ** compression algorithm.
86 **
87 ** PARAMETERS
88 ** src - the input compressed data
89 **
90 ** RETURN
91 ** the uncompressed data
92 **
93 */
94
95 function lz_uncompress(src in raw) return raw;
96
97 /* This lz_uncompress overload will return a temporary BLOB for the
98 * uncompressed data.
99 */
100 function lz_uncompress(src in blob) return blob;
101
102 /* This lz_uncompress overload will return the uncompressed data into the
103 * existing BLOB, dst. Original dst data will be overwritten.
104 */
105 procedure lz_uncompress(src in blob, dst in out nocopy blob);
106
107
108 /* This lz_uncompress overload will return a temporary BLOB for the
109 * uncompressed data.
110 */
111 function lz_uncompress(src in bfile) return blob;
112
113 /* This lz_uncompress overload will return the uncompressed data into the
114 * existing BLOB, dst. Original dst data will be overwritten.
115 */
116 procedure lz_uncompress(src in bfile, dst in out nocopy blob);
117
118
119
120 /* PIECEWISE COMPRESS */
121
122 /*
123 ** lz_compress_open - Initialize a piecewise context that maintains the
124 ** compress state and data.
125 **
126 ** PARAMETERS
127 ** dst - user supplied LOB to store compressed data.
128 ** quality - speed versus efficiency of resulting compressed output.
129 ** Valid values are the range 1..9, with a default value of 6.
130 ** 1=fastest compression, 9=slowest compression and best
131 ** compressed file size.
132 **
133 ** RETURN
134 ** A handle to an initialized piecewise compress context.
135 **
136 ** EXCEPTIONS
137 ** invalid_handle - invalid handle, too many open handles.
138 ** invalid_argument - NULL dst or invalid quality specified.
139 **
140 ** NOTES
141 ** Make sure to close the opened handle with lz_compress_close once
142 ** the piecewise compress is done and in the event of an exception in
143 ** the middle of process, since lack of doing so will cause these
144 ** handles to leak.
145 **
146 */
147 function lz_compress_open(dst in out nocopy blob,
148 quality in binary_integer default 6)
149 return binary_integer;
150
151
152 /*
153 ** lz_compress_add - add a piece of compressed data.
154 **
155 ** PARAMETERS
156 ** handle - handle to a piecewise compress context.
157 ** dst - opened LOB from lz_compress_open to store compressed data.
158 ** src - input data to be compressed.
159 **
160 ** EXCEPTIONS
161 ** invalid_handle - out of range invalid or unopened handle
162 ** invalid_argument - NULL handle, src, dst, or invalid dst.
163 **
164 */
165 procedure lz_compress_add(handle in binary_integer,
166 dst in out nocopy blob,
167 src in raw);
168
169 /*
170 ** lz_compress_close - close and finish piecewise compress.
171 **
172 ** PARAMETERS
173 ** handle - handle to a piecewise compress context.
174 ** dst - opened LOB from lz_compress_open to store compressed data.
175 **
176 ** EXCEPTIONS
177 ** invalid_handle - out of range invalid or uninitialized handle.
178 ** invalid_argument - NULL handle, dst, or invalid dst.
179 **
180 */
181 procedure lz_compress_close(handle in binary_integer,
182 dst in out nocopy blob);
183
184 /* PIECEWISE Uncompress */
185
186 /*
187 ** lz_uncompress_open - Initialize a piecewise context that maintains the
188 ** uncompress state and data.
189 **
190 ** PARAMETERS
191 ** src - input data to be uncompressed.
192 **
193 ** RETURN
194 ** A handle to an initialized piecewise uncompress context.
195 **
196 ** EXCEPTIONS
197 ** invalid_handle - invalid handle, too many open handles.
198 ** invalid_argument - NULL src.
199 **
200 ** NOTES
201 ** Make sure to close the opened handle with lz_uncompress_close once
202 ** the piecewise uncompress is done and in the event of an exception in
203 ** the middle of process, since lack of doing so will cause these
204 ** handles to leak.
205 **
206 */
207 function lz_uncompress_open(src in blob) return binary_integer;
208
209 /*
210 ** lz_uncompress_extract - extract a piece of uncompressed data.
211 **
212 ** PARAMETERS
213 ** handle - handle to a piecewise uncompress context.
214 ** dst - uncompressed data.
215 **
216 ** EXCEPTIONS
217 ** no_data_found - finished uncompress.
218 ** invalid_handle - out of range invalid or uninitialized handle.
219 ** invalid_argument - NULL handle.
220 */
221 procedure lz_uncompress_extract(handle in binary_integer,
222 dst out nocopy raw);
223
224
225 /*
226 ** lz_uncompress_close - close and finish piecewise uncompress.
227 **
228 ** PARAMETERS
229 ** handle - handle to a piecewise uncompress context.
230 **
231 ** EXCEPTIONS
232 ** invalid_handle - out of range invalid or uninitialized handle.
233 ** invalid_argument - NULL handle.
234 **
235 */
236 procedure lz_uncompress_close(handle in binary_integer);
237
238 /*
239 ** isopen - Checks to see if the handle to a piecewise (un)compress context
240 ** was opened or closed.
241 **
242 ** PARAMETERS
243 ** handle - handle to a piecewise (un)compress context.
244 **
245 ** RETURN
246 ** TRUE, if the given piecewise handle is opened, otherwise FALSE.
247 **
248 ** Example
249 ** if (utl_compress.isopen(myhandle) = TRUE) then
250 ** utl_compress.lz_compress_close(myhandle, lob_1);
251 ** end if;
252 **
253 ** or
254 **
255 ** if (utl_compress.isopen(myhandle) = TRUE) then
256 ** utl_compress.lz_uncompress_close(myhandle);
257 ** end if;
258 **
259 */
260 function isopen(handle in binary_integer) return boolean;
261
262 END;
[Home] [Help]