13 UTL_RAW

UTL_RAWパッケージは、RAWデータ・タイプを操作するためのSQLファンクションを提供します。

この章の内容は次のとおりです。

UTL_RAWの使用
- 概要
- 使用上の注意
UTL_RAWサブプログラムの要約

UTL_RAWの使用

概要
使用上の注意

概要

通常のSQLファンクションは複数のRAW値で作動せず、PL/SQLはRAWデータ・タイプとCHARデータ・タイプの間でのオーバーロードができないため、このパッケージが必要になります。

UTL_RAWは、データベース環境に固有のものではなく、他の環境でも使用できます。このため、DBMSのかわりに、UTLという接頭辞がパッケージに付けられています。

使用上の注意

UTL_RAWでは、RAWレコードを多くの要素で構成できます。RAWデータ・タイプを使用すると、キャラクタ・セット変換は実行されず、リモート・プロシージャ・コールによる転送時にRAW値は元の形式で保持されます。

また、RAWファンクションによって、以前はhextorawファンクションとrawtohex SQLファンクションに限定されていたバイナリ・データを操作できます。

RAW値を戻すファンクションは、16進数エンコーディングでその処理を行います。

UTL_RAWサブプログラムの要約

表13-1 UTL_RAWパッケージのサブプログラム

サブプログラム	説明
BIT_ANDファンクション	2つの`RAW`値でビット単位の論理演算`AND`を実行し、結果の`RAW`を戻します。
BIT_COMPLEMENTファンクション	1つの`RAW`値でビット単位の論理演算`COMPLEMENT`を実行して、結果の`RAW`を戻します。
BIT_ORファンクション	2つの`RAW`値でビット単位の論理演算`OR`を実行し、結果の`RAW`を戻します。
BIT_XORファンクション	2つの`RAW`値でビット単位の論理演算`XOR`(排他OR)を実行して、結果の`RAW`を戻します。
CAST_FROM_BINARY_DOUBLEファンクション	`BINARY_DOUBLE`値の`RAW`バイナリ表現を戻します。
CAST_FROM_BINARY_FLOATファンクション	`BINARY_FLOAT`値の`RAW`バイナリ表現を戻します。
CAST_FROM_BINARY_INTEGERファンクション	`BINARY_INTEGER`値の`RAW`バイナリ表現を戻します。
CAST_FROM_NUMBERファンクション	`NUMBER`値の`RAW`バイナリ表現を戻します。
CAST_TO_BINARY_DOUBLEファンクション	`BINARY_DOUBLE`値の`RAW`バイナリ表現を`BINARY_DOUBLE`に変換します。
CAST_TO_BINARY_FLOATファンクション	`BINARY_FLOAT`値の`RAW`バイナリ表現を`BINARY_FLOAT`に変換します。
CAST_TO_BINARY_INTEGERファンクション	`BINARY_INTEGER`値の`RAW`バイナリ表現を`BINARY_INTEGER`に変換します。
CAST_TO_NUMBERファンクション	`NUMBER`値の`RAW`バイナリ表現を`NUMBER`に変換します。
CAST_TO_NVARCHAR2ファンクション	`NVARCHAR2`値に`RAW`値をキャストします。
CAST_TO_RAWファンクション	`RAW`値に`VARCHAR2`値をキャストします。
CAST_TO_VARCHAR2ファンクション	`VARCHAR2`値に`RAW`値をキャストします。
COMPAREファンクション	2つの`RAW`値を比較します。
CONCATファンクション	最大12の`RAW`値を単一の`RAW`に連結します。
CONVERTファンクション	`RAW`値をあるキャラクタ・セットから別のキャラクタ・セットに変換して、結果の`RAW`を戻します。
COPIESファンクション	`RAW`値を指定回数コピーして、連結された`RAW`値を戻します。
LENGTHファンクション	`RAW`値の長さをバイトで戻します。
OVERLAYファンクション	ターゲット`RAW`値の指定部分をオーバーレイ`RAW`値でオーバーレイします(指定したバイト位置から開始され、指定したバイト数だけ進められます)。
REVERSEファンクション	`RAW`値内のバイトの順序を逆にします。
SUBSTRファンクション	指定された開始位置から指定されたバイト数だけ、`RAW`値のサブストリングを戻します。
TRANSLATEファンクション	指定された変換`RAW`値のバイトに従って、入力`RAW`値内の指定されたバイトを変換します。
TRANSLITERATEファンクション	指定された文字変換`RAW`値のバイトに従って、入力`RAW`値内の指定されたバイトを変換します。
XRANGEファンクション	指定されたバイト・コードで開始および終了する連続する1バイト・エンコーディングを含む`RAW`値を戻します。

注意:

PLS_INTEGERデータ・タイプとBINARY_INTEGERデータ・タイプは同じです。このドキュメントでは、リファレンス情報でデータ・タイプ(表タイプ、レコード・タイプ、サブプログラム・パラメータ、サブプログラム戻り値など)を示す場合にBINARY_INTEGERを使用しますが、説明および例ではいずれも使用される場合があります。
INTEGERデータ・タイプとNUMBER(38)データ・タイプも同じです。このドキュメントでは、全体をとおしてINTEGERを使用します。

BIT_ANDファンクション

このファンクションは、2つの提供されたRAW値でビット単位の論理演算ANDを実行し、結果のRAWを戻します。

構文

UTL_RAW.BIT_AND (
   r1 IN RAW,
   r2 IN RAW) 
RETURN RAW;

パラメータ

表13-2 BIT_ANDファンクションのパラメータ

パラメータ	説明
`r1`	`AND`演算の1つ目の`RAW`値
`r2`	`AND`演算の2つ目の`RAW`値

戻り値

AND演算の結果、またはNULL(いずれかの入力値がNULLの場合)

使用上の注意

r1とr2の長さが異なる場合、2つのRAW値のうち短い方の最終バイトが終わると演算は終了され、長い方のRAW値の未処理部分が部分的な結果に追加されます。結果の長さは、2つの入力値のうち長い方に等しくなります。

BIT_COMPLEMENTファンクション

このファンクションは、提供されたRAW値でビット単位の論理演算COMPLEMENTを実行し、結果のRAWを戻します。結果の長さは、入力RAWの長さに等しくなります。

構文

UTL_RAW.BIT_COMPLEMENT (
   r IN RAW) 
  RETURN RAW;

パラメータ

表13-3 BIT_COMPLEMENTファンクションのパラメータ

パラメータ	説明
`r`	`COMPLEMENT`演算の`RAW`値

戻り値

COMPLEMENT演算の結果、またはNULL(入力値がNULLの場合)

BIT_ORファンクション

このファンクションは、2つの提供されたRAW値でビット単位の論理演算ORを実行し、結果のRAWを戻します。

構文

UTL_RAW.BIT_OR (
   r1 IN RAW,
   r2 IN RAW) 
  RETURN RAW;

パラメータ

表13-4 BIT_ORファンクションのパラメータ

パラメータ	説明
`r1`	`OR`演算の1つ目の`RAW`値
`r2`	`OR`演算の2つ目の`RAW`値

戻り値

OR演算の結果、またはNULL(いずれかの入力値がNULLの場合)

使用上の注意

BIT_XORファンクション

このファンクションは、2つの提供されたRAW値でビット単位の論理演算XOR(排他OR)を実行し、結果のRAWを戻します。

構文

UTL_RAW.BIT_XOR (
   r1 IN RAW,
   r2 IN RAW) 
  RETURN RAW;

パラメータ

表13-5 BIT_XORファンクションのパラメータ

パラメータ	説明
`r1`	`XOR`演算の1つ目の`RAW`値
`r2`	`XOR`演算の2つ目の`RAW`値

戻り値

XOR演算の結果、またはNULL(いずれかの入力値がNULLの場合)

使用上の注意

CAST_FROM_BINARY_DOUBLEファンクション

このファンクションは、BINARY_DOUBLE値のRAWバイナリ表現を戻します。

構文

UTL_RAW.CAST_FROM_BINARY_DOUBLE(
   n          IN BINARY_DOUBLE,
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN RAW;

パラメータ

表13-6 CAST_FROM_BINARY_DOUBLEファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_DOUBLE`値
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

n

BINARY_DOUBLE値

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_DOUBLE値のRAWバイナリ表現、またはNULL(入力がNULLの場合)

使用上の注意

8バイトのBINARY_DOUBLE値からIEEE 754倍精度形式へのマッピングは、次のとおりです。

byte 0: bit 63 ~ bit 56
byte 1: bit 55 ~ bit 48
byte 2: bit 47 ~ bit 40
byte 3: bit 39 ~ bit 32
byte 4: bit 31 ~ bit 24
byte 5: bit 23 ~ bit 16
byte 6: bit 15 ~ bit  8
byte 7: bit  7 ~ bit  0

パラメータendianessは、BINARY_DOUBLE値のバイトがRAW値のバイトにマップされる方法を指定します。次のマトリックスのrb0からrb7はRAWのバイトを示し、db0からdb7はBINARY_DOUBLEのバイトを示しています。

Endianess rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7

big_endian db0 db1 db2 db3 db4 db5 db6 db7

little_endian db7 db6 db5 db4 db3 db2 db1 db0
machine_endianを指定すると、BINARY_DOUBLE引数の8バイトがRAW戻り値に直接コピーされます。ユーザーがビッグエンディアン・システムでbig_endianを、またはリトルエンディアン・システムでlittle_endianを指定した場合と同様です。

Endianess	rb0	rb1	rb2	rb3	rb4	rb5	rb6	rb7
big_endian	`db0`	`db1`	`db2`	`db3`	`db4`	`db5`	`db6`	`db7`
little_endian	`db7`	`db6`	`db5`	`db4`	`db3`	`db2`	`db1`	`db0`

CAST_FROM_BINARY_FLOATファンクション

このファンクションは、BINARY_FLOAT値のRAWバイナリ表現を戻します。

構文

UTL_RAW.CAST_FROM_BINARY_FLOAT(
   n          IN BINARY_FLOAT,
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN RAW;

パラメータ

表13-7 CAST_FROM_BINARY_FLOATファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_FLOAT`値
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

n

BINARY_FLOAT値

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_FLOAT値のRAWバイナリ表現、またはNULL(入力がNULLの場合)

使用上の注意

4バイトのBINARY_FLOAT値からIEEE 754単精度形式へのマッピングは、次のとおりです。
```
byte 0: bit 31 ~ bit 24
byte 1: bit 23 ~ bit 16
byte 2: bit 15 ~ bit  8
byte 3: bit 7 ~  bit  0
```
パラメータendianessは、BINARY_FLOAT値のバイトをRAW値のバイトにマップする方法を指定します。次のマトリックスのrb0からrb3はRAWのバイトを示し、fb0からfb3はBINARY_FLOATのバイトを示しています。

Endianess rb0 rb1 rb2 rb3

big_endian fbo fb1 fb2 fb3

little_endian fb3 fb2 fb1 fb0
machine_endianを指定すると、BINARY_FLOAT引数の4バイトがRAW戻り値に直接コピーされます。ユーザーがビッグエンディアン・システムでbig_endianを、またはリトルエンディアン・システムでlittle_endianを指定した場合と同様です。

Endianess	rb0	rb1	rb2	rb3
big_endian	`fbo`	`fb1`	`fb2`	`fb3`
little_endian	`fb3`	`fb2`	`fb1`	`fb0`

CAST_FROM_BINARY_INTEGERファンクション

このファンクションは、BINARY_INTEGER値のRAWバイナリ表現を戻します。

構文

UTL_RAW.CAST_FROM_BINARY_INTEGER (
   n          IN BINARY_INTEGER
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN RAW;

パラメータ

表13-8 CAST_FROM_BINARY_INTEGERファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_INTEGER`値。
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

n

BINARY_INTEGER値。

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_INTEGER値のRAWバイナリ表現、またはNULL(入力がNULLの場合)

CAST_FROM_NUMBERファンクション

このファンクションは、NUMBER値のRAWバイナリ表現を戻します。

構文

UTL_RAW.CAST_FROM_NUMBER (
   n  IN NUMBER)
 RETURN RAW;

パラメータ

表13-9 CAST_FROM_NUMBERファンクションのパラメータ

パラメータ	説明
`n`	`NUMBER`値

戻り値

NUMBER値のRAWバイナリ表現、またはNULL(入力がNULLの場合)

CAST_TO_BINARY_DOUBLEファンクション

このファンクションは、BINARY_DOUBLE値のRAWバイナリ表現をBINARY_DOUBLE値に変換します。

構文

UTL_RAW.CAST_TO_BINARY_DOUBLE (
   r          IN RAW
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN BINARY_DOUBLE;

パラメータ

表13-10 CAST_TO_BINARY_DOUBLEファンクションのパラメータ

パラメータ説明

パラメータ	説明
`r`	`BINARY_DOUBLE`値の`RAW`バイナリ表現
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

r

BINARY_DOUBLE値のRAWバイナリ表現

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_DOUBLE値、またはNULL(入力がNULLの場合)

使用上の注意

RAW引数が8バイトを超える場合、最初の8バイトのみが使用され、残りのバイトは無視されます。結果が-0の場合、+0が戻されます。結果がNaNの場合、値BINARY_DOUBLE_NANが戻されます。

8バイトのBINARY_DOUBLE値からIEEE 754倍精度形式へのマッピングは、次のとおりです。

byte 0: bit 63 ~ bit 56
byte 1: bit 55 ~ bit 48
byte 2: bit 47 ~ bit 40
byte 3: bit 39 ~ bit 32
byte 4: bit 31 ~ bit 24
byte 5: bit 23 ~ bit 16
byte 6: bit 15 ~ bit  8
byte 7: bit  7 ~ bit  0

パラメータendianessは、BINARY_DOUBLE値のバイトがRAW値のバイトにマップされる方法を指定します。次のマトリックスのrb0からrb7はRAW内のバイトを示し、db0からdb7はBINARY_DOUBLE内のバイトを示しています。

Endianess rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7

big_endian db0 db1 db2 db3 db4 db5 db6 db7

little_endian db7 db6 db5 db4 db3 db2 db1 db0
machine_endianを指定すると、RAW引数の8バイトがBINARY_DOUBLE戻り値に直接コピーされます。ユーザーがビッグエンディアン・システムでbig_endianを、またはリトルエンディアン・システムでlittle_endianを指定した場合と同様です。

Endianess	rb0	rb1	rb2	rb3	rb4	rb5	rb6	rb7
big_endian	`db0`	`db1`	`db2`	`db3`	`db4`	`db5`	`db6`	`db7`
little_endian	`db7`	`db6`	`db5`	`db4`	`db3`	`db2`	`db1`	`db0`

例外

RAW引数が8バイト未満の場合、VALUE_ERROR例外が発生します。

CAST_TO_BINARY_FLOATファンクション

このファンクションは、BINARY_FLOAT値のRAWバイナリ表現をBINARY_FLOAT値に変換します。

構文

UTL_RAW.CAST_TO_BINARY_FLOAT (
   r          IN RAW
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN BINARY_FLOAT;

パラメータ

表13-11 CAST_TO_BINARY_FLOATファンクション・パラメータ

パラメータ説明

パラメータ	説明
`r`	`BINARY_FLOAT`値の`RAW`バイナリ表現
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

r

BINARY_FLOAT値のRAWバイナリ表現

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_FLOAT値、またはNULL(入力がNULLの場合)

使用上の注意

RAW引数が4バイトを超える場合、最初の4バイトのみが使用され、残りのバイトは無視されます。結果が-0の場合、+0が戻されます。結果がNaNの場合、値BINARY_FLOAT_NANが戻されます。
4バイトのBINARY_FLOAT値からIEEE 754単精度形式へのマッピングは、次のとおりです。
```
byte 0: bit 31 ~ bit 24
byte 1: bit 23 ~ bit 16
byte 2: bit 15 ~ bit  8
byte 3: bit 7 ~  bit  0
```
パラメータendianessは、BINARY_FLOAT値のバイトをRAW値のバイトにマップする方法を指定します。次のマトリックスのrb0からrb3はRAW内のバイトを示し、fb0からfb3はBINARY_FLOAT内のバイトを示しています。

Endianess rb0 rb1 rb2 rb3

big_endian fbo fb1 fb2 fb3

little_endian fb3 fb2 fb1 fb0
machine_endianを指定すると、RAW引数の4バイトがBINARY_FLOAT戻り値に直接コピーされます。ユーザーがビッグエンディアン・システムでbig_endianを、またはリトルエンディアン・システムでlittle_endianを指定した場合と同様です。

Endianess	rb0	rb1	rb2	rb3
big_endian	`fbo`	`fb1`	`fb2`	`fb3`
little_endian	`fb3`	`fb2`	`fb1`	`fb0`

例外

RAW引数が4バイト未満の場合、VALUE_ERROR例外が発生します。

CAST_TO_BINARY_INTEGERファンクション

このファンクションは、BINARY_INTEGER値のRAWバイナリ表現をBINARY_INTEGER値に変換します。

構文

UTL_RAW.CAST_TO_BINARY_INTEGER (
   r          IN RAW
   endianess  IN BINARY_INTEGER DEFAULT 1) 
RETURN BINARY_INTEGER;

パラメータ

表13-12 CAST_TO_BINARY_INTEGERファンクションのパラメータ

パラメータ説明

パラメータ	説明
`r`	`BINARY_INTEGER`値の`RAW`バイナリ表現
`endianess`	エンディアンを示す`BINARY_INTEGER`値このファンクションは、定義済定数`big_endian`、`little_endian`および`machine_endian`を認識します。デフォルトは`big_endian`です。

r

BINARY_INTEGER値のRAWバイナリ表現

endianess

エンディアンを示すBINARY_INTEGER値

このファンクションは、定義済定数big_endian、little_endianおよびmachine_endianを認識します。デフォルトはbig_endianです。

戻り値

BINARY_INTEGER値、またはNULL(入力がNULLの場合)

CAST_TO_NUMBERファンクション

このファンクションは、NUMBER値のRAWバイナリ表現をNUMBER値に変換します。

構文

UTL_RAW.CAST_TO_NUMBER (
   r  IN RAW) 
 RETURN NUMBER;

パラメータ

表13-13 CAST_TO_NUMBERファンクションのパラメータ

パラメータ	説明
`r`	`NUMBER`値の`RAW`バイナリ表現

戻り値

NUMBER値、またはNULL(入力がNULLの場合)

CAST_TO_NVARCHAR2ファンクション

このファンクションは、一定数のデータ・バイトを使用して表したRAW値を、同じ数のデータ・バイトのNVARCHAR2値にキャストします。

注意:

NVARCHAR2への変換時、そのNVARCHAR2値内の文字に対して現行のグローバリゼーション・サポート・キャラクタ・セットが使用されます。

構文

UTL_RAW.CAST_TO_NVARCHAR2 (
   r IN RAW) 
RETURN NVARCHAR2;

パラメータ

表13-14 CAST_TO_NVARCHAR2ファンクションのパラメータ

パラメータ	説明
`r`	`NVARCHAR2`値に変更する`RAW`値(先行する長さのフィールドなし)

戻り値

入力RAW値から変換されたデータ、またはNULL(入力がNULLの場合)

CAST_TO_RAWファンクション

このファンクションは、一定数のデータ・バイトを使用して表したVARCHAR2値を、同じ数のデータ・バイトのRAW値にキャストします。データ自体は変更されませんが、そのデータ・タイプはRAWデータ・タイプに再変換されます。

構文

UTL_RAW.CAST_TO_RAW (
   c  IN VARCHAR2) 
RETURN RAW;

パラメータ

表13-15 CAST_TO_RAWファンクションのパラメータ

パラメータ	説明
`c`	`RAW`値に変更される`VARCHAR2`値

戻り値

先行する長さのフィールドはない、入力値と同じバイト長の、入力VARCHAR2値から変換されたデータ、またはNULL(入力がNULLの場合)

CAST_TO_VARCHAR2ファンクション

このファンクションは、一定数のデータ・バイトを使用して表したRAW値を、同じ数のデータ・バイトのVARCHAR2値にキャストします。

注意:

VARCHAR2への変換時、そのVARCHAR2値内の文字に対して現行のグローバリゼーション・サポート・キャラクタ・セットが使用されます。

構文

UTL_RAW.CAST_TO_VARCHAR2 (
   r IN RAW) 
RETURN VARCHAR2;

パラメータ

表13-16 CAST_TO_VARCHAR2ファンクションのパラメータ

パラメータ	説明
`r`	`VARCHAR2`値に変更する`RAW`値(先行する長さのフィールドなし)

戻り値

入力RAW値から変換されたデータ、またはNULL(入力がNULLの場合)

COMPAREファンクション

このファンクションは、2つのRAW値を比較します。それぞれの値の長さが異なる場合、短い方の値は、オプションのpadパラメータに従って右側に拡張されます。

構文

UTL_RAW.COMPARE (
   r1  IN RAW,
   r2  IN RAW
  [,pad IN RAW DEFAULT NULL]) 
  RETURN NUMBER;

パラメータ

表13-17 COMPAREファンクションのパラメータ

パラメータ説明

パラメータ	説明
`r1`	比較する1つ目の`RAW`値注意: 値は`NULL`またはゼロ長です。
`r2`	比較する2つ目の`RAW`値注意: 値は`NULL`またはゼロ長です。
`pad`	入力値の短い方を延長するバイト(デフォルト: `x'00'`)

r1

比較する1つ目のRAW値

注意: 値はNULLまたはゼロ長です。

r2

比較する2つ目のRAW値

注意: 値はNULLまたはゼロ長です。

pad

入力値の短い方を延長するバイト(デフォルト: x'00')

戻り値

2つの入力値を比較した場合は最初の不一致バイトの位置番号(1から番号付けされている)に等しいNUMBER値で、入力値が同じまたは両方がNULLの場合は0

CONCATファンクション

このファンクションは、最大12のRAW値を単一のRAW値に連結します。連結後のサイズが32 KBを超えると、エラーが戻されます。

構文

UTL_RAW.CONCAT (  
   r1  IN RAW DEFAULT NULL,
   r2  IN RAW DEFAULT NULL,
   r3  IN RAW DEFAULT NULL,
   r4  IN RAW DEFAULT NULL,
   r5  IN RAW DEFAULT NULL,
   r6  IN RAW DEFAULT NULL,
   r7  IN RAW DEFAULT NULL,
   r8  IN RAW DEFAULT NULL,
   r9  IN RAW DEFAULT NULL,
   r10 IN RAW DEFAULT NULL,
   r11 IN RAW DEFAULT NULL,
   r12 IN RAW DEFAULT NULL) 
  RETURN RAW;

パラメータ

項目r1...r12は、連結するRAW項目です。

戻り値

連結された入力値で構成されるRAW値

例外

入力の長さの合計がRAW値で許容される最大長(32767バイト)を超えると、エラーが発生します。

CONVERTファンクション

このファンクションは、RAW値をあるキャラクタ・セットから別のキャラクタ・セットに変換して、結果のRAWを戻します。

どちらのキャラクタ・セットも、データベースに定義されているサポートされるキャラクタ・セットである必要があります。

構文

UTL_RAW.CONVERT (
   r            IN RAW,
   to_charset   IN VARCHAR2,
   from_charset IN VARCHAR2) 
  RETURN RAW;

パラメータ

表13-18 CONVERTファンクションのパラメータ

パラメータ	説明
`r`	変換する`RAW`バイト列。
`to_charset`	入力値の変換後のグローバリゼーション・サポート・キャラクタ・セットの名前
`from_charset`	入力値の変換前のグローバリゼーション・サポート・キャラクタ・セットの名前

戻り値

指定したキャラクタ・セットに従って変換されたバイト文字列

例外

VALUE_ERRORは、次のいずれかの場合に発生します。

入力バイト文字列が欠落しているか、NULLまたは長さが0(ゼロ)。
from_charsetまたはto_charsetが失われたか、NULLまたは長さが0。
from_charsetまたはto_charsetが無効であるか、サポートされていない。

COPIESファンクション

このファンクションは、指定されたRAW値を指定された回数だけコピーし、連結して戻します。

構文

UTL_RAW.COPIES (
   r IN RAW,
   n IN NUMBER) 
  RETURN RAW;

パラメータ

表13-19 COPIESファンクションのパラメータ

パラメータ説明

パラメータ	説明
`r`	コピーする`RAW`値
`n`	`RAW`値をコピーする回数注意: これは正の値である必要があります。

r

コピーするRAW値

n

RAW値をコピーする回数

注意: これは正の値である必要があります。

戻り値

指定された回数だけコピーされ、連結されたRAW値

例外

VALUE_ERRORは、次のいずれかの場合に発生します。

コピーする値が失われたか、NULLまたは長さが0(ゼロ)。
値をコピーする回数が0以下。
結果の長さがRAW値で許容される最大長(32767バイト)を超える場合。

LENGTHファンクション

このファンクションは、RAW値の長さをバイト単位で戻します。

構文

UTL_RAW.LENGTH (
   r  IN RAW) 
RETURN NUMBER;

パラメータ

表13-20 LENGTHファンクション・パラメータ

パラメータ	説明
`r`	測定される`RAW`バイトストリーム

戻り値

RAW値の長さを示すNUMBER値(バイト単位)

OVERLAYファンクション

このファンクションは、ターゲットRAW値の指定部分をオーバーレイRAWでオーバーレイします(指定したバイト位置から開始され、指定したバイト数だけ進められます)。

構文

UTL_RAW.OVERLAY (
   overlay_str IN RAW,
   target      IN RAW
  [,pos         IN BINARY_INTEGER DEFAULT 1,
   len         IN BINARY_INTEGER DEFAULT NULL,
   pad         IN RAW            DEFAULT NULL]) 
  RETURN RAW;

パラメータ

表13-21 OVERLAYファンクションのパラメータ

パラメータ	説明
`overlay_str`	targetをオーバーレイするために使用するバイト列。
`target`	オーバーレイされるターゲットのバイト文字列
`pos`	オーバーレイを開始するターゲットのバイト位置(デフォルトは1で1から番号付けされている)
`len`	オーバーレイするバイト数(デフォルト: `overlay_str`の長さ)
`pad`	`len`が`overlay_str`の長さを超えた場合、または`pos`が`target`の長さを超えた場合に使用するpadバイト(デフォルト: `x'00'`)

戻り値

指定どおりにオーバーレイされたRAWターゲット・バイト値

使用上の注意

overlay_strがlenバイト未満の場合は、padバイトを使用してlenバイトまで延長されます。overlay_strがlenバイトを超える場合は、overlay_strの余分なバイトは無視されます。targetの位置posから始まるlenバイトがtargetの長さを超える場合、overlay_str全体の長さまでtargetが延長されます。

lenを指定する場合、0以上である必要があります。posを指定する場合、1以上である必要があります。posがtargetの長さを超える場合、targetはpadバイトを使用してposの位置までパディングされ、さらにtargetはoverlay_strバイトを使用して延長されます。

例外

VALUE_ERRORは、次のいずれかの場合に発生します。

overlay_strがNULLまたは長さが0(ゼロ)の場合。
targetが失われたか、未定義の場合。
targetの長さがRAW値の最大長(32767バイト)を超える場合。
lenが0未満の場合。
posが0以下の場合。

REVERSEファンクション

このファンクションは、RAWのバイトの順序をすべて逆転させます。たとえば、x'0102F3'は逆転されてx'F30201'になり、'xyz'は逆転されて'zyx'になります。結果の長さは入力の長さと同じです。

構文

UTL_RAW.REVERSE (
   r IN RAW) 
  RETURN RAW;

パラメータ

表13-22 REVERSEファンクションのパラメータ

パラメータ	説明
`r`	逆転する`RAW`値

戻り値

入力値の逆転であるRAW値

例外

入力値がNULLまたは長さが0(ゼロ)の場合にVALUE_ERRORが発生します。

SUBSTRファンクション

このファンクションは、指定されたバイト数および開始位置のRAW値のサブストリングを戻します。

構文

UTL_RAW.SUBSTR (
   r   IN RAW,
   pos IN BINARY_INTEGER
  [,len IN BINARY_INTEGER DEFAULT NULL]) 
  RETURN RAW;

パラメータ

表13-23 SUBSTRファンクションのパラメータ

パラメータ	説明
`r`	サブストリングの抽出元の`RAW`バイト文字列
`pos`	入力バイト文字列の先頭から前方へカウントされるか(正の値)、末尾から後方へカウントされる(負の値)抽出を開始するバイト位置
`len`	`pos`からバイト文字列の末尾方向へカウントされる抽出するバイト数(デフォルト: `RAW`バイト文字列の末尾方向)

戻り値

開始位置posからlenバイト分のRAWサブストリング、またはNULL(入力がNULLの場合)

使用上の注意

posが正の値の場合、SUBSTRはRAWバイト文字列の先頭からカウントされ、最初のバイトが見つけられます。posが負の値の場合、SUBSTRはRAWバイト文字列の末尾から後方にカウントされます。posの値に0は指定できません。

lenには正の値を指定する必要があります。lenを省略すると、SUBSTRはRAWバイト文字列の末尾までのすべてのバイトを戻します。

例外

VALUE_ERRORは、次のいずれかの場合に発生します。

posが0であるか、またはrの長さを超える場合。
lenが0以下の場合。
lenが、(rの長さ) - (pos-1) より大きい場合。

例

例1: ttIsqlで実行される次の例では、開始位置として、入力RAW値の末尾から15バイト後方にカウントし、そのポイントから開始して5バイト分のサブストリングを取得します。

declare
  sr raw(32767); 
  r raw(32767);

begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  r := UTL_RAW.SUBSTR(sr, -15, 5);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。

source raw: 1236567812125612344434341234567890ABAA1234
return raw: 5612344434
 
PL/SQL procedure successfully completed.

この機能の説明がより明確にわかるように、入力と出力を示します。

source raw: 12 36 56 78 12 12 56 12 34 44 34 34 12 34 56 78 90 AB AA 12 34
return raw: 56 12 34 44 34

サブストリングは、末尾から15バイト目に始まります。

例2: ttIsqlで実行される次の例は、前の例と入力RAW値と開始ポイントが同じですが、lenが指定されないため、サブストリングは開始ポイントから入力の末尾まで取得されます。

declare
  sr raw(32767); 
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  r := UTL_RAW.SUBSTR(sr, -15);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

次に結果を示します。

source raw: 1236567812125612344434341234567890ABAA1234
return raw: 5612344434341234567890ABAA1234

この機能の説明がより明確にわかるように、入力と出力を示します。

source raw: 12 36 56 78 12 12 56 12 34 44 34 34 12 34 56 78 90 AB AA 12 34
return raw: 56 12 34 44 34 34 12 34 56 78 90 AB AA 12 34

TRANSLATEファンクション

このファンクションは、入力バイトのセット、入力バイト内で検索する変換前のバイトのセット、および変換後の対応するバイトのセットが指定されている場合に、RAW値のバイト単位の変換を実行します。指定したfrom_set内のバイトが入力RAW値で見つかった場合は、to_set内の対応するバイトに変換されて出力RAW値が生成され、to_set内に対応するバイトがない場合は出力RAW値に含められません。from_setにはない入力RAW値内のバイトは、単にそのまま出力RAW値にコピーされます。

構文

UTL_RAW.TRANSLATE (
   r        IN RAW,
   from_set IN RAW,
   to_set   IN RAW) 
  RETURN RAW;

注意:

コール・シーケンス内でのto_setとfrom_setの順番が、TRANSLITERATEとは逆であることに注意してください。

パラメータ

表13-24 TRANSLATEファンクションのパラメータ

パラメータ説明

r

適用可能な場合に、バイトが変換されるRAWソース・バイト文字列

from_set

ソース・バイト文字列で検索されるRAWバイト・コード

見つかると結果で変換されます。

to_set

変換後のRAWバイト・コード

from_setバイトがソース・バイト文字列で見つかると、対応するto_setバイトに結果で変換されます(適用可能な場合)。

戻り値

変換後のバイト文字列を含むRAW値

使用上の注意

to_setがfrom_setよりも短い場合、余ったfrom_setバイトに対応する変換バイトはありません。そのようなfrom_setバイトに一致する入力RAW値からのバイトは、結果で変換されることも、結果に含まれることもありません。事実上、NULLに変換されます。
to_setがfrom_setより長い場合、余ったto_setバイトは無視されます。
あるバイト値がfrom_setで繰り返し出現する場合、それは無視されます。

注意:

TRANSLITERATEとの相違点:

コール・シーケンスでは、from_setパラメータはto_setパラメータの前にあります。
from_setに存在するソース・バイト文字列からのバイトで、to_setに対応する値がないものは、結果で変換されることも、含められることもありません。
結果のRAW値は、入力RAW値より短い場合があります。

TRANSLATEとTRANSLITERATEの機能は、to_setのバイト数がfrom_setより少ない場合にのみ異なります。

例外

ソース・バイト文字列、from_setまたはto_setがNULLまたは長さが0(ゼロ)の場合、VALUE_ERRORが発生します。

例

例1: ttIsqlで実行される次の例では、from_setがx'12AA34'で、to_setがx'CD'です。入力RAW値に'12'が含まれていると、結果で'CD'に置き換えられます。入力RAW値に'AA'または'34'が含まれている場合、to_setに対応するバイトがないため、これらのバイトは結果に含められません(事実上NULLに変換されます)。

TRANSLITERATEセクションの「例」と比較すると、機能の違いを確認できます。

declare
  sr raw(32767);     
  from_set raw(32767);
  to_set raw(32767); 
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  from_set := hextoraw('12AA34');
  to_set   := hextoraw('CD');
  dbms_output.put_line('from_set:   ' || from_set);
  dbms_output.put_line('to_set:     ' || to_set);
  r := UTL_RAW.TRANSLATE(sr, from_set, to_set);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。

from_set:   12AA34
to_set:     CD
source raw: 1236567812125612344434341234567890ABAA1234
return raw: CD365678CDCD56CD44CD567890ABCD

PL/SQL procedure successfully completed.

この機能の説明がより明確にわかるように、次に入力と出力を示します。

from_set:   12  AA 34
to_set:     CD
source raw: 12 365678 12 12 56 12 34 44 34 34 12 34 567890AB AA 12 34
return raw: CD 365678 CD CD 56 CD    44       CD    567890AB    CD

例2: ttIsqlで実行される次の例では、from_setがx'12AA12'で、to_setがx'CDABEF'です。入力RAWに'12'が含まれていると、結果で'CD'に置き換えられます。入力に'AA'が含まれていると、結果で'AB'に置き換えられます。from_setの2つ目の'12'は無視されるため、to_setの対応するバイトも無視されます。

declare
  sr raw(32767);     
  from_set raw(32767);
  to_set raw(32767); 
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  from_set := hextoraw('12AA12');
  to_set   := hextoraw('CDABEF');
  dbms_output.put_line('from_set:   ' || from_set);
  dbms_output.put_line('to_set:     ' || to_set);
  r := UTL_RAW.TRANSLATE(sr, from_set, to_set);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。TRANSLITERATEでも同じ入力RAW、from_setおよびto_setを指定した場合は動作が同じです(「TRANSLITERATE」の項の「例」を参照)。

from_set:   12AA12
to_set:     CDABEF
source raw: 1236567812125612344434341234567890ABAA1234
return raw: CD365678CDCD56CD34443434CD34567890ABABCD34
 
PL/SQL procedure successfully completed.

TRANSLITERATEファンクション

このファンクションは、入力バイトのセット、入力バイト内で検索する変換前のバイトのセット、および変換後の対応するバイトのセットが指定されている場合に、RAW値のバイト単位の文字変換を実行します。指定したfrom_set内のバイトが入力RAW値で見つかった場合は、to_set内の対応するバイトに変換されて出力RAW値が生成され、to_set内に対応するバイトがない場合は指定したパディング・バイトに変換されます。from_setにはない入力RAW値内のバイトは、そのまま出力RAW値にコピーされます。

構文

UTL_RAW.TRANSLITERATE (
   r        IN RAW,
   to_set   IN RAW DEFAULT NULL,
   from_set IN RAW DEFAULT NULL,
   pad      IN RAW DEFAULT NULL)
  RETURN RAW;

注意:

コール・シーケンス内でのto_setとfrom_setの順番が、TRANSLATEとは逆であることに注意してください。

パラメータ

表13-25 TRANSLITERATEファンクションのパラメータ

パラメータ	説明
`r`	適用可能な場合に、バイトが変換される`RAW`ソース・バイト文字列
`to_set`	変換後の`RAW`バイト・コード `from_set`バイトがソース・バイト文字列で見つかると、対応する`to_set`バイトに結果で変換されます(適用可能な場合)。これは、デフォルトで、`from_set`の長さになるまで、事実上`NULL`文字列は`pad`で延長されます。
`from_set`	ソース・バイト文字列で検索される`RAW`バイト・コード見つかると、結果で変換されます。デフォルトは`x'00'`から`x'FF'`で、結果で変換対象となるソース・バイト文字列内のすべてのバイトになります。
`pad`	`from_set`内のバイトと一致しても、`to_set`に対応するバイトがない場合に、ソース・バイト文字列内の任意のバイトの変換値として使用されるパディング・バイト(デフォルト: `x'00'`)

戻り値

変換後のバイト文字列を含むRAW値

使用上の注意

to_setがfrom_setよりも短い場合、余ったfrom_setバイトに対応する変換バイトはありません。そのようなfrom_setバイトに一致した入力RAW値は、結果でpadバイトに変換されます。
to_setがfrom_setより長い場合、余ったto_setバイトは無視されます。
あるバイト値がfrom_setで繰り返し出現する場合、それは無視されます。

注意:

TRANSLATEとの相違点:

コール・シーケンスでは、to_setパラメータはfrom_setパラメータの前にあります。
from_setに存在するソース・バイト文字列からのバイトで、to_setに対応する値がないものは、結果でpadに置き換えられます。
結果のRAW値は、入力RAW値と常に同じ長さになります。

TRANSLATEとTRANSLITERATEの機能は、to_setのバイト数がfrom_setより少ない場合にのみ異なります。

例外

ソース・バイト文字列がNULLまたは長さが0(ゼロ)の場合にVALUE_ERRORが発生します。

例

例1: ttIsqlで実行される次の例では、from_setがx'12AA34'で、to_setがx'CD'です。入力RAW値に'12'が含まれていると、結果で'CD'に置き換えられます。入力RAW値に'AA'または'34'が含まれている場合、to_setに対応するバイトがないため、これらのバイトはpadバイトに置き換えられます(padバイトが指定されていないためデフォルトのx'00'が使用されます)。

TRANSLATEセクションの「例」と比較すると、機能の違いを確認できます。

declare
  sr raw(32767);
  from_set raw(32767);
  to_set raw(32767); 
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  from_set := hextoraw('12AA34');
  to_set   := hextoraw('CD');
  dbms_output.put_line('from_set:   ' || from_set);
  dbms_output.put_line('to_set:     ' || to_set);
  r := UTL_RAW.TRANSLITERATE(sr, to_set, from_set);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。

from_set:   12AA34
to_set:     CD
source raw: 1236567812125612344434341234567890ABAA1234
return raw: CD365678CDCD56CD00440000CD00567890AB00CD00
 
PL/SQL procedure successfully completed.

この機能の説明がより明確にわかるように、次に入力と出力を示します。

from_set:   12  AA 34
to_set:     CD
source raw: 12 365678 12 12 56 12 34 44 34 34 12 34 567890AB AA 12 34
return raw: CD 365678 CD CD 56 CD 00 44 00 00 CD 00 567890AB 00 CD 00

例2: ttIsqlで実行される次の例は、padにx'FF'が指定されていること以外は、前の例と同じです。

declare
  sr raw(32767);     
  from_set raw(32767);
  to_set raw(32767); 
  pad raw(32767);
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  from_set := hextoraw('12AA34');
  to_set   := hextoraw('CD');
  pad      := hextoraw('FF');
  dbms_output.put_line('from_set:   ' || from_set);
  dbms_output.put_line('to_set:     ' || to_set);
  r := UTL_RAW.TRANSLITERATE(sr, to_set, from_set, pad);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。'AA'および'34'が、'00'ではなく'FF'に置き換えられています。

from_set:   12AA34
to_set:     CD
source raw: 1236567812125612344434341234567890ABAA1234
return raw: CD365678CDCD56CDFF44FFFFCDFF567890ABFFCDFF
 
PL/SQL procedure successfully completed.

例3: ttIsqlで実行される次の例では、from_setがx'12AA12'で、to_setがx'CDABEF'です。入力RAW値に'12'が含まれていると、結果で'CD'に置き換えられます。入力に'AA'が含まれていると、結果で'AB'に置き換えられます。from_setの2つ目の'12'は無視されるため、to_setの対応するバイトも無視されます。

declare
  sr raw(32767);     
  from_set raw(32767);
  to_set raw(32767); 
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  from_set := hextoraw('12AA12');
  to_set   := hextoraw('CDABEF');
  dbms_output.put_line('from_set:   ' || from_set);
  dbms_output.put_line('to_set:     ' || to_set);
  r := UTL_RAW.TRANSLITERATE(sr, to_set, from_set);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。この動作は、入力RAW、from_setおよびto_setを指定したTRANSLATEの場合と同じです(「TRANSLATE」の項の「例」を参照)。

from_set:   12AA12
to_set:     CDABEF
source raw: 1236567812125612344434341234567890ABAA1234
return raw: CD365678CDCD56CD34443434CD34567890ABABCD34
 
PL/SQL procedure successfully completed.

例4: ttIsqlで実行される次の例では、from_setおよびto_setが指定されていません。

declare
  sr raw(32767);
  r raw(32767);
begin
  sr       := hextoraw('1236567812125612344434341234567890ABAA1234');
  r := UTL_RAW.TRANSLITERATE(sr);
  dbms_output.put_line('source raw: ' || sr);
  dbms_output.put_line('return raw: ' || r);
end;
/

結果は次のとおりです。from_setおよびto_setのデフォルトに従って、すべてのバイトはx'00'で置き換えられます。

source raw: 1236567812125612344434341234567890ABAA1234
return raw: 000000000000000000000000000000000000000000
 
PL/SQL procedure successfully completed.

XRANGEファンクション

このファンクションは、指定したバイト・コードで開始および終了する連続した1バイト・エンコードを含むRAW値を戻します。指定するバイト・コードは、シングルバイトのRAW値である必要があります。start_byte値がend_byte値より大きい場合、結果バイトの連続はstart_byteで始まり、x'FF'からx'00'に折り返してend_byteで終わります。

構文

UTL_RAW.XRANGE (
   start_byte IN RAW DEFAULT NULL,
   end_byte   IN RAW DEFAULT NULL) 
  RETURN RAW;

パラメータ

表13-26 XRANGEファンクションのパラメータ

パラメータ	説明
`start_byte`	戻される連続値の最初のバイト・コード値(デフォルト: `x'00'`)
`end_byte`	戻される連続値の最後のバイト・コード値(デフォルト: `x'FF'`)

戻り値

1バイト・エンコーディングの連続を含むRAW値

例

ttIsqlで実行される次の3つの例に、start_byteがend_byteより小さい場合、start_byteがend_byteより大きい場合、およびデフォルト値の場合の結果を示します。

Command> declare
       >    r raw(32767);
       >    s raw(32767);
       >    e raw(32767);
       > begin
       >    s := hextoraw('1');
       >    e := hextoraw('A');
       >    r := utl_raw.xrange(s,e);
       >    dbms_output.put_line(r);
       > end;
       > /
0102030405060708090A
 
PL/SQL procedure successfully completed.
 
Command> declare
       >    r raw(32767);
       >    s raw(32767);
       >    e raw(32767);
       > begin
       >    s := hextoraw('EE');
       >    e := hextoraw('A');
       >    r := utl_raw.xrange(s,e);
       >    dbms_output.put_line(r);
       > end;
       > /
EEEFF0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF000102030405060708090A
 
PL/SQL procedure successfully completed.
 
Command> declare
       >    r raw(32767);
       > begin
       >    r := utl_raw.xrange();
       >    dbms_output.put_line(r);
       > end;
       > /
000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627
28292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F
505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F7071727374757677
78797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9F
A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7
C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
 
PL/SQL procedure successfully completed.