204 UTL_COMPRESS

UTL_COMPRESSパッケージは、一連のデータ圧縮ユーティリティを提供します。

この章では、次の項目について説明します。

• UTL_COMPRESSの使用方法

  • 定数

  • 例外

  • 使用上の注意

• UTL_COMPRESSサブプログラムの要約

---

UTL_COMPRESSの使用方法

• 定数

• 例外

• 使用上の注意

---

定数

ピース単位操作に使用するハンドルの最大数を定義します。

UTLCOMP_MAX_HANDLE   CONSTANT  PLS_INTEGER := 5;

---

例外

表204-1 UTL_COMPRESSの例外

例外	説明
BUFFER_TOO_SMALL	圧縮後の表現が大きすぎます。
DATA_ERROR	入力または出力データ・ストリームの書式が無効です。
INVALID_ARGUMENT	1つの引数のタイプまたは値が無効です。
INVALID_HANDLE	ピース単位の圧縮または圧縮解除には無効なハンドルです。
STREAM_ERROR	データ・ストリームの圧縮または圧縮解除中にエラーが発生しました。

---

使用上の注意

• LZ*ファンクションによって戻された一時LOBは、コール元がDBMS_LOB.FREETEMPORARYコールを使用して解放する必要があります。

• LZ_COMPRESS*またはLZ_UNCOMPRESS*に渡されたBFILEは、DBMS_LOB.FILEOPENでオープンする必要があります。

• 特別な状況（入力がすでに圧縮されている場合）では、UTL_COMPRESSサブプログラムの1つで生成された出力が、入力と同じ大きさかまたは入力よりもわずかに大きくなることがあります。

• UTL_COMPRESSで圧縮したデータの出力は、1つのファイル上のgzip（-nオプションを指定）/gunzipと互換性があります。

---

UTL_COMPRESSサブプログラムの要約

表204-2 UTL_COMPRESSパッケージのサブプログラム

サブプログラム	説明
ISOPENファンクション	ピース単位の圧縮（または圧縮解除）コンテキストに対するハンドルが、オープンしているかクローズしているかどうかを確認します。
LZ_COMPRESSファンクションおよびプロシージャ	Lempel-Ziv圧縮アルゴリズムを使用してデータを圧縮します。
LZ_COMPRESS_ADDプロシージャ	1つの圧縮データを追加します。
LZ_COMPRESS_CLOSE	ピース単位の圧縮操作をクローズして終了します。
LZ_COMPRESS_OPEN	圧縮状態とデータを保持するピース単位のコンテキストを初期化します。
LZ_UNCOMPRESSファンクションおよびプロシージャ	圧縮された入力を受け入れ、有効であることを確認して圧縮を解除します。
LZ_UNCOMPRESS_EXTRACTプロシージャ	1つの圧縮解除データを抽出します。
LZ_UNCOMPRESS_OPENファンクション	圧縮解除状態とデータを保持するピース単位のコンテキストを初期化します。
LZ_UNCOMPRESS_CLOSEプロシージャ	ピース単位の圧縮解除をクローズして終了します。

---

ISOPENファンクション

このファンクションは、ピース単位の圧縮（または圧縮解除）コンテキストに対するハンドルが、オープンしているかクローズしているかどうかを確認します。

構文

UTL_COMPRESS.ISOPEN(
   handle in binary_integer)
 RETURN BOOLEAN;

パラメータ

表204-3 ISOPENファンクションのパラメータ

パラメータ	説明
handle	ピース単位の圧縮解除コンテキストへのハンドル。

戻り値

指定したピース単位のハンドルがオープンしている場合はTRUE、それ以外の場合はFALSE。

例

IF (UTL_COMPRESS.ISOPEN(myhandle) = TRUE) then
   UTL_COMPRESS.LZ_COMPRESS_CLOSE(myhandle, lob_1);
END IF;

次のようにコーディングすることもできます。

IF (UTL_COMPRESS.ISOPEN(myhandle) = TRUE) THEN
   UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE(myhandle);
END IF;

---

LZ_COMPRESSファンクションおよびプロシージャ

このファンクションおよびプロシージャでは、Lempel-Ziv圧縮アルゴリズムを使用してデータを圧縮します。

構文

次のファンクションは、RAWを入力として使用し、圧縮して、圧縮後のRAWの結果とメタデータを戻します。

UTL_COMPRESS.LZ_COMPRESS (
   src       IN           RAW,
   quality   IN           BINARY_INTEGER DEFAULT 6)
 RETURN RAW;

次のファンクションは、BLOBを入力として使用し、圧縮して、圧縮後のデータの一時BLOBを戻します。

UTL_COMPRESS.LZ_COMPRESS (
  src       IN           BLOB,
  quality   IN           BINARY_INTEGER DEFAULT 6)
 RETURN BLOB;

次のプロシージャは、圧縮後のデータを、圧縮後のデータ・サイズにトリミングした既存のBLOB（dst）に戻します。

UTL_COMPRESS.LZ_COMPRESS (
  src      IN            BLOB,
  dst      IN OUT NOCOPY BLOB,
  quality  IN            BINARY_INTEGER DEFAULT 6);

次のファンクションは、圧縮後のデータの一時BLOBを戻します。

UTL_COMPRESS.LZ_COMPRESS (
   src     IN            BFILE,
   quality IN            BINARY_INTEGER DEFAULT 6)
 RETURN BLOB;

次のプロシージャは、圧縮後のデータを、圧縮後のデータ・サイズにトリミングした既存のBLOB（dst）に戻します。

UTL_COMPRESS.LZ_COMPRESS (
   src     IN            BFILE,
   dst     IN OUT NOCOPY BLOB,
   quality IN            BINARY_INTEGER DEFAULT 6);

パラメータ

表204-4 LZ_COMPRESSファンクションおよびプロシージャのパラメータ

パラメータ	説明
src	圧縮するデータ（RAW、BLOBまたはBFILE）。
dst	圧縮したデータを戻す宛先。
quality	1から9の範囲の整数。1は高速圧縮、9は最も効率のよい圧縮を指定します。デフォルトは6です。

使用上の注意

• qualityは、オプションで指定する圧縮チューニング値です。 UTL_COMPRESSの使用時に、速度と圧縮品質の関係（サイズ縮小の割合）を選択できます。圧縮速度を速くすると、データの圧縮率が低くなります。圧縮速度を遅くすると、データの圧縮率が高くなります。 有効な値は1から9で、1が最も速く、9が最も遅くなります。'quality'のデフォルト値は6です。

---

LZ_COMPRESS_ADDプロシージャ

このプロシージャは、1つの圧縮データを追加します。

構文

UTL_COMPRESS.LZ_COMPRESS_ADD (
   handle IN             BINARY_INTEGER,
   dst    IN OUT NOCOPY  BLOB,
   src    IN             RAW);

パラメータ

表204-5 LZ_COMPRESS_ADDプロシージャのパラメータ

パラメータ	説明
handle	ピース単位の圧縮コンテキストへのハンドル。
dst	圧縮したデータを格納するために、LZ_COMPRESS_OPENによってオープンしたLOB。
src	圧縮する入力データ。

例外

• invalid_handle - 範囲外であるため無効か、ハンドルがオープンではありません。

• invalid_argument - handle、srcまたはdstの値がNULLであるか、dstの値が無効です。

---

LZ_COMPRESS_CLOSE

このプロシージャは、ピース単位の圧縮操作をクローズして終了します。

構文

UTL_COMPRESS.LZ_COMPRESS_CLOSE (
   handle IN             BINARY_INTEGER,
   dst    IN OUT NOCOPY  BLOB);

パラメータ

表204-6 LZ_COMPRESS_CLOSEプロシージャのパラメータ

パラメータ	説明
handle	ピース単位の圧縮コンテキストへのハンドル。
dst	圧縮したデータを格納するために、LZ_COMPRESS_OPENによってオープンしたLOB。

例外

• invalid_handle - 範囲外であるため無効か、ハンドルが初期化されていません。

• invalid_argument - handle、dstの値がNULLであるか、dstの値が無効です。

---

LZ_COMPRESS_OPEN

このファンクションは、圧縮状態とデータを保持するピース単位のコンテキストを初期化します。

構文

UTL_COMPRESS.LZ_COMPRESS_OPEN (
   dst       IN OUT NOCOPY BLOB,
   quality   IN            BINARY_INTEGER DEFAULT 6)
 RETURN BINARY_INTEGER;

パラメータ

表204-7 LZ_COMPRESS_OPENファンクションのパラメータ

パラメータ	説明
dst	圧縮したデータを格納するためにユーザーが提供するLOB。
quality	結果としての圧縮出力の速度と効率の関係。 有効な値の範囲は1から9で、デフォルト値は6です。 1は最も速い圧縮です。9は最も遅い圧縮ですが、最適な圧縮ファイル・サイズになります。

戻り値

初期化されたピース単位の圧縮コンテキストへのハンドル。

例外

• invalid_handle - ハンドルが無効か、オープンしているハンドルが多すぎます。

• invalid_argument - dstの値がNULLであるか、qualityの指定が無効です。

使用上の注意

次の場合には、オープンしているハンドルをLZ_COMPRESS_CLOSEでクローズしてください。

• ピース単位の圧縮が完了したとき

• 処理の途中で例外が発生したとき

クローズしないとハンドルがリークします。

---

LZ_UNCOMPRESSファンクションおよびプロシージャ

このプロシージャは、RAW、BLOBまたはBFILEで圧縮された文字列を入力として使用し、有効な圧縮値であることを検証し、Lempel-Ziv圧縮アルゴリズムを使用して圧縮を解除して、圧縮を解除したRAWまたはBLOBの結果を戻します。

構文

次のファンクションは、圧縮解除後のデータをRAWとして戻します。

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  RAW)
  RETURN RAW;

次のファンクションは、圧縮解除後のデータを一時BLOBとして戻します。

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BLOB)
  RETURN BLOB;

次のプロシージャは、圧縮解除後のデータを既存のBLOB（dst）に戻します。BLOBは圧縮解除後のデータ・サイズにトリミングされます。

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BLOB,
   dst  IN OUT NOCOPY BLOB);

次のファンクションは、圧縮解除後のデータの一時BLOBを戻します。

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN BFILE)
 RETURN BLOB;

次のプロシージャは、圧縮解除後のデータを既存のBLOB（dst）に戻します。元のdstのデータは上書きされます。

UTL_COMPRESS.LZ_UNCOMPRESS(
   src  IN  BFILE,
   dst  IN OUT NOCOPY BLOB);

パラメータ

表204-8 LZ_UNCOMPRESSファンクションおよびプロシージャのパラメータ

パラメータ	説明
src	圧縮したデータ。
dst	圧縮解除したデータを戻す宛先。

---

LZ_UNCOMPRESS_EXTRACTプロシージャ

このプロシージャは、1つの圧縮解除データを抽出します。

構文

UTL_COMPRESS.LZ_UNCOMPRESS_EXTRACT(
   handle  IN          BINARY_INTEGER,
   dst     OUT NOCOPY  RAW);

パラメータ

表204-9 LZ_UNCOMPRESS_EXTRACTプロシージャのパラメータ

パラメータ	説明
handle	ピース単位の圧縮解除コンテキストへのハンドル。
dst	圧縮解除したデータ。

例外

• no_data_found - 圧縮解除が終了しました。

• invalid_handle - 範囲外であるため無効か、ハンドルが初期化されていません。

• invalid_argument - handleの値がNULLです。

---

LZ_UNCOMPRESS_OPENファンクション

このファンクションは、圧縮解除状態とデータを保持するピース単位のコンテキストを初期化します。

構文

UTL_COMPRESS.LZ_UNCOMPRESS_OPEN(
   src  IN  BLOB)
  RETURN BINARY_INTEGER;

パラメータ

表204-10 LZ_UNCOMPRESS_OPENファンクションのパラメータ

パラメータ	説明
src	圧縮解除する入力データ。

戻り値

初期化されたピース単位の圧縮コンテキストへのハンドル。

例外

• invalid_handle - ハンドルが無効か、オープンしているハンドルが多すぎます。

• invalid_argument - srcの値がNULLです。

使用上の注意

次の場合には、オープンしているハンドルをLZ_UNCOMPRESS_CLOSEでクローズしてください。

• ピース単位の圧縮解除が完了したとき

• 処理の途中で例外が発生したとき

クローズしないとハンドルがリークします。

---

LZ_UNCOMPRESS_CLOSEプロシージャ

このプロシージャは、ピース単位の圧縮解除をクローズして終了します。

構文

UTL_COMPRESS.LZ_UNCOMPRESS_CLOSE(
   handle  IN   BINARY_INTEGER);

パラメータ

表204-11 LZ_UNCOMPRESS_CLOSEプロシージャのパラメータ

パラメータ	説明
handle	ピース単位の圧縮解除コンテキストへのハンドル。

例外

• invalid_handle - 範囲外であるため無効か、ハンドルが初期化されていません。

• invalid_argument - handleの値がNULLです。