UTL_RAW

285 UTL_RAW

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

この章のトピックは、次のとおりです:

285.1 UTL_RAWの概要

通常のSQLファンクションは複数のRAWで作動せず、PL/SQLはRAWデータ・タイプとCHARデータ・タイプの間でのオーバーロードができないため、このパッケージが必要になります。UTL_RAWには、各種のCOBOL数値形式を複数のRAWの間で変換するサブプログラムも含まれています。

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

285.2 UTL_RAWの操作上のノート

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

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

ノート:

データ・タイプに関するノート:

PLS_INTEGERデータ・タイプとBINARY_INTEGERデータ・タイプは同一です。このドキュメントでは、(表タイプ、レコード・タイプ、サブプログラムのパラメータ、サブプログラムの戻り値などの)参照情報でデータ・タイプを示す場合にはBINARY_INTEGERを使用しますが、説明および例ではどちらも使用します。
INTEGERデータ・タイプとNUMBER(38)データ・タイプも同一です。このドキュメントでは、INTEGERのみを使用します。

285.3 UTL_RAWサブプログラムの要約

この表は、UTL_RAWサブプログラムを示し、簡単に説明しています。

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

サブプログラム	説明
BIT_ANDファンクション	`RAW` `r1`と`RAW` `r2`の値でビット単位の論理演算ANDを実行し、AND演算後の結果`RAW`を戻します。
BIT_COMPLEMENTファンクション	`RAW` `r`の値でビット単位の論理演算補数を実行し、補数演算後の結果`RAW`を戻します。
BIT_ORファンクション	`RAW` `r1`と`RAW` `r2`の値でビット単位の論理演算ORを実行し、OR演算後の結果`RAW`を戻します。
BIT_XORファンクション	`RAW` `r1`と`RAW` `r2`の値でビット単位の論理演算XORを実行し、XOR演算後の結果`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ファンクション	`RAW`値を`VARCHAR2`値に変換します。
CAST_TO_RAWファンクション	`VARCHAR2`値を`RAW`値に変換します。
CAST_TO_VARCHAR2ファンクション	RAW値を`VARCHAR2`値に変換します。
COMPAREファンクション	`RAW` `r1`と`RAW` `r2`を比較します。
CONCATファンクション	最大12までの`RAW`を単一の`RAW`に連結します。
CONVERTファンクション	`RAW` `r`を文字セット`from_charset`から文字セット`to_charset`に変換し、結果の`RAW`を戻します。
COPIESファンクション	`r`を`n`回のコピーで連結したものを戻します。
LENGTHファンクション	`RAW` `r`の長さをバイトで戻します。
OVERLAYファンクション	target `RAW`の指定部分をoverlay_str `RAW`でオーバーレイし、targetの位置`pos`バイトから始まる`len`バイト分を処理します。
REVERSEファンクション	`RAW` `r`のバイトの順序を、最後から最初に逆転させます。
SUBSTRファンクション	`RAW` `r`の`pos`から`len`バイトを戻します。
TRANSLATEファンクション	`from_set`と`to_set`のバイト列変換に従って、入力`RAW` `r`内のバイト列を変換します。
TRANSLITERATEファンクション	`from_set`と`to_set`のバイト列変換に従って、入力`RAW` `r`内のバイト列を変換します。
XRANGEファンクション	値`start_byte`で始まり値`end_byte`で終わる、連続した有効な1バイト・コードをすべて含む`RAW`を戻します。

285.3.1 BIT_ANDファンクション

このファンクションは、RAW r1とRAW r2の値でビット単位の論理演算ANDを実行し、AND演算後の結果RAWを戻します。

構文

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

プラグマ

pragma restrict_references(bit_and, WNDS, RNDS, WNPS, RNPS);

パラメータ

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

パラメータ	説明
`r1`	`r2`とAND演算をする`RAW`。
`r2`	`r1`とAND演算をする`RAW`。

戻り値

表285-3 BIT_ANDファンクションの戻り値

戻り値	説明
`RAW`	`r1`と`r2`のAND演算結果を含んでいます。
`NULL`	入力パラメータ`r1`または`r2`が`NULL`の場合。

使用上のノート

r1とr2の長さが異なる場合、AND演算は、短い方のRAWの最終バイト後に終了し、長い方のRAWの未処理部分は部分結果に追加されます。したがって、結果の長さは、2つの入力RAWの長い方と同じ長さになります。

285.3.2 BIT_COMPLEMENTファンクション

このファンクションは、RAW rの値でビット単位の論理演算補数を実行し、補数演算後の結果RAWを戻します。結果の長さは、入力RAW rの長さと等しくなります。

構文

UTL_RAW.BIT_COMPLEMENT (
   r IN RAW) 
  RETURN RAW;

プラグマ

pragma restrict_references(bit_complement, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-4 BIT_COMPLEMENTファンクションのパラメータ

パラメータ	説明
`r`	補数演算を実行する`RAW`。

戻り値

表285-5 BIT_COMPLEMENTファンクションの戻り値

戻り値	説明
`RAW`	`r1`の補数演算結果を含んでいます。
`NULL`	入力パラメータ`r`が`NULL`の場合。

285.3.3 BIT_ORファンクション

このファンクションは、RAW r1とRAW r2の値でビット単位の論理演算ORを実行し、OR演算後の結果RAWを戻します。

構文

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

プラグマ

pragma restrict_references(bit_or, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-6 BIT_ORファンクションのパラメータ

パラメータ	説明
`r1`	`r2`とOR演算をする`RAW`。
`r2`	`r1`とOR演算をする`RAW`。

戻り値

表285-7 BIT_ORファンクションの戻り値

戻り値	説明
`RAW`	`r1`と`r2`のOR演算結果を含んでいます。
`NULL`	入力パラメータ`r1`または`r2`が`NULL`の場合。

使用上のノート

r1とr2の長さが異なる場合、OR演算は、短い方のRAWの最終バイト後に終了し、長い方のRAWの未処理部分は部分結果に追加されます。したがって、結果の長さは、2つの入力RAWの長い方と同じ長さになります。

285.3.4 BIT_XORファンクション

このファンクションは、RAW r1とRAW r2の値でビット単位の論理演算XORを実行し、XOR演算後の結果RAWを戻します。

構文

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

プラグマ

pragma restrict_references(bit_xor, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-8 BIT_XORファンクションのパラメータ

パラメータ	説明
`r1`	`r2`とXOR演算をする`RAW`。
`r2`	`r1`とXOR演算をする`RAW`。

戻り値

表285-9 BIT_XORファンクションの戻り値

戻り値	説明
`RAW`	`r1`と`r2`のXOR演算結果を含んでいます。
`NULL`	入力パラメータ`r1`または`r2`が`NULL`の場合。

使用上のノート

r1とr2の長さが異なる場合、XOR演算は、短い方のRAWの最終バイト後に終了し、長い方のRAWの未処理部分は部分結果に追加されます。したがって、結果の長さは、2つの入力RAWの長い方と同じ長さになります。

285.3.5 CAST_FROM_BINARY_DOUBLEファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_from_binary_double, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-10 CAST_FROM_BINARY_DOUBLEファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_DOUBLE`値。
`endianess`	エンディアンを示す`BINARY_INTEGER`値。このファンクションは、定義済の定数`big_endian`(1)、`little_endian`(2)および`machine_endian`(3)を認識します。デフォルトは`big_endian`です。`machine_endian`設定の効果は、ビッグ・エンディアン・マシンでは`big_endian`と同じになり、リトル・エンディアン・マシンでは`little_endian`と同じになります。

n

BINARY_DOUBLE値。

endianess

エンディアンを示すBINARY_INTEGER値。このファンクションは、定義済の定数big_endian(1)、little_endian(2)およびmachine_endian(3)を認識します。デフォルトはbig_endianです。machine_endian設定の効果は、ビッグ・エンディアン・マシンではbig_endianと同じになり、リトル・エンディアン・マシンではlittle_endianと同じになります。

戻り値

BINARY_DOUBLEの値のバイナリ表現。入力が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のバイトを参照しています。

エンディアン	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マシン上のbig_endianまたはlittle-endianマシン上のlittle_endianを渡した場合も同じです。

285.3.6 CAST_FROM_BINARY_FLOATファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_from_binary_float, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-11 CAST_FROM_BINARY_FLOATファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_FLOAT`値。
`endianess`	エンディアンを示す`BINARY_INTEGER`値。このファンクションは、定義済の定数`big_endian`(1)、`little_endian`(2)および`machine_endian`(3)を認識します。デフォルトは`big_endian`です。`machine_endian`設定の効果は、ビッグ・エンディアン・マシンでは`big_endian`と同じになり、リトル・エンディアン・マシンでは`little_endian`と同じになります。

n

BINARY_FLOAT値。

endianess

戻り値

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のバイトを参照しています。

エンディアン	rb0	rb1	rb2	rb3
big_endian	fb0	fb1	fb2	fb3
little_endian	fb3	fb2	fb1	fb0

machine-endianの場合、BINARY_FLOAT引数の4バイトがRAWの戻り値に直接コピーされます。big-endianマシン上のbig_endianまたはlittle-endianマシン上のlittle_endianを渡した場合も同じです。

285.3.7 CAST_FROM_BINARY_INTEGERファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_from_binary_integer, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-12 CAST_FROM_BINARY_INTEGERファンクションのパラメータ

パラメータ説明

パラメータ	説明
`n`	`BINARY_INTEGER`値。
`endianess`	エンディアンを示す`BINARY_INTEGER`値。このファンクションは、定義済の定数`big_endian`(1)、`little_endian`(2)および`machine_endian`(3)を認識します。デフォルトは`big_endian`です。`machine_endian`設定の効果は、ビッグ・エンディアン・マシンでは`big_endian`と同じになり、リトル・エンディアン・マシンでは`little_endian`と同じになります。

n

BINARY_INTEGER値。

endianess

戻り値

BINARY_INTEGERの値のバイナリ表現。

285.3.8 CAST_FROM_NUMBERファンクション

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

構文

UTL_RAW.CAST_FROM_NUMBER (
   n  IN NUMBER)
 RETURN RAW;

プラグマ

pragma restrict_references(cast_from_number, WNDS, RNDS, WNPS, RNPS);

パラメータ

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

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

戻り値

NUMBERの値のバイナリ表現。

285.3.9 CAST_TO_BINARY_DOUBLEファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_to_binary_double, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-14 CAST_TO_BINARY_DOUBLEファンクションのパラメータ

パラメータ	説明
`r`	`BINARY_DOUBLE`のバイナリ表現。
`endianess`	big-endianまたはlittle-endianのアーキテクチャを表す`PLS_INTEGER`。デフォルトはbig-endianです。

戻り値

BINARY_DOUBLE値。

使用上のノート

RAW引数が8バイトを超える場合は、最初の8バイトだけが使用され、残りのバイトは無視されます。結果が-0の場合は、+0が戻されます。結果がNaNの場合は、BINARY_DOUBLE_NANの値が戻されます。
RAW引数が8バイト未満の場合は、VALUE_ERROR例外が発生します。

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

アーキテクチャ	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マシン上のbig_endianまたはlittle-endianマシン上のlittle_endianを渡した場合も同じです。

285.3.10 CAST_TO_BINARY_FLOATファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_to_binary_float, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-15 CAST_TO_BINARY_FLOATファンクションのパラメータ

パラメータ	説明
`r`	`BINARY_FLOAT`のバイナリ表現。
`endianess`	big-endianまたはlittle-endianのアーキテクチャを表す`PLS_INTEGER`。デフォルトはbig-endianです。

戻り値

BINARY_FLOAT値。

使用上のノート

RAW引数が4バイトを超える場合は、最初の4バイトだけが使用され、残りのバイトは無視されます。結果が-0の場合は、+0が戻されます。結果がNaNの場合は、BINARY_FLOAT_NANの値が戻されます。
RAW引数が4バイト未満の場合は、VALUE_ERROR例外が発生します。
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
```

エンディアン	rb0	rb1	rb2	rb3
big_endian	`fbo`	`fb1`	`fb2`	`fb3`
little_endian	`fb3`	`fb2`	`fb1`	`fb0`

machine-endianの場合、RAW引数の4バイトがBINARY_FLOATの戻り値に直接コピーされます。big-endianマシン上のbig_endianまたはlittle-endianマシン上のlittle_endianを渡した場合も同じです。

285.3.11 CAST_TO_BINARY_INTEGERファンクション

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

構文

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

プラグマ

pragma restrict_references(cast_to_binary_integer, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-16 CAST_TO_BINARY_INTEGERファンクションのパラメータ

パラメータ	説明
`r`	`BINARY_INTEGER`のバイナリ表現。
`endianess`	big-endianまたはlittle-endianのアーキテクチャを表す`PLS_INTEGER`。デフォルトはbig-endianです。

戻り値

BINARY_INTEGER値。

285.3.12 CAST_TO_NUMBERファンクション

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

構文

UTL_RAW.CAST_TO_NUMBER (
   r  IN RAW) 
 RETURN NUMBER;

プラグマ

pragma restrict_references(cast_to_number, WNDS, RNDS, WNPS, RNPS);

パラメータ

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

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

戻り値

NUMBERの値。

285.3.13 CAST_TO_NVARCHAR2ファンクション

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

ノート:

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

構文

UTL_RAW.CAST_TO_NVARCHAR2 (
   r IN RAW) 
RETURN NVARCHAR2;

プラグマ

pragma restrict_references(cast_to_NVARCHAR2, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-18 CAST_TO_NVARCHAR2ファンクションのパラメータ

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

戻り値

表285-19 CAST_TO_NVARCHAR2ファンクションの戻り値

戻り値	説明
`NVARCHAR2`	入力`RAW`と同じデータ。
`NULL`	入力パラメータ`r`が`NULL`の場合。

285.3.14 CAST_TO_RAWファンクション

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

構文

UTL_RAW.CAST_TO_RAW (
   c  IN VARCHAR2) 
RETURN RAW;

プラグマ

pragma restrict_references(cast_to_raw, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-20 CAST_TO_RAWファンクションのパラメータ

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

戻り値

表285-21 CAST_TO_RAWファンクションの戻り値

戻り値	説明
`RAW`	先行する長さのフィールドのない、入力`VARCHAR2`と同じバイト長の同じデータ。
`NULL`	入力パラメータ`c`が`NULL`の場合。

285.3.15 CAST_TO_VARCHAR2ファンクション

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

ノート:

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

構文

UTL_RAW.CAST_TO_VARCHAR2 (
   r IN RAW) 
RETURN VARCHAR2;

プラグマ

pragma restrict_references(cast_to_VARCHAR2, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-22 CAST_TO_VARCHAR2ファンクションのパラメータ

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

戻り値

表285-23 CAST_TO_VARCHAR2ファンクションの戻り値

戻り値	説明
`VARCHAR2`	入力`RAW`と同じデータ。
`NULL`	入力パラメータ`r`が`NULL`の場合。

285.3.16 COMPAREファンクション

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

構文

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

プラグマ

pragma restrict_references(compare, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-24 COMPAREファンクションのパラメータ

パラメータ	説明
`r1`	比較する1番目の`RAW`で、`NULL`または長さ0が可能。
`r2`	比較する2番目の`RAW`で、`NULL`または長さ0が可能。
`pad`	これはオプションのパラメータです。`r1`または`r2`の短い方を拡張するためのバイト列。デフォルトは、x'00'です。

戻り値

表285-25 COMPAREファンクションの戻り値

戻り値説明

戻り値	説明
`NUMBER`	`RAW`バイト列が両方とも`NULL`または等しい場合は、0(ゼロ)。または、最初に不一致になったバイト位置(1から番号付けされている)と等しい番号。

NUMBER

RAWバイト列が両方ともNULLまたは等しい場合は、0(ゼロ)。または、

最初に不一致になったバイト位置(1から番号付けされている)と等しい番号。

285.3.17 CONCATファンクション

このファンクションは、最大12までのRAWを単一のRAWに連結します。連結したサイズが32Kを超える場合は、エラーが戻ります。

構文

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;

プラグマ

pragma restrict_references(concat, WNDS, RNDS, WNPS, RNPS);

パラメータ

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

戻り値

表285-26 CONCATファンクションの戻り値

戻り値	説明
`RAW`	連結された項目。

例外

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

285.3.18 CONVERTファンクション

このファンクションは、RAW rを文字セットfrom_charsetから文字セットto_charsetに変換し、結果のRAWを戻します。

from_charsetとto_charsetは両方とも、Oracleサーバーに定義されているサポート・キャラクタのセットである必要があります。

構文

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

プラグマ

pragma restrict_references(convert, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-27 CONVERTファンクションのパラメータ

パラメータ	説明
`r`	変換する`RAW`バイト列。
`to_charset`	`r`の変換後の文字セットの名前
`from_charset`	`r`が変換される前の文字セットの名前

戻り値

表285-28 CONVERTファンクションの戻り値

戻り値	説明
`RAW`	指定した文字セットに従って変換されたバイト列`r`。

例外

表285-29 CONVERTファンクションの例外

エラー	説明
`ORA-06502`	PL/SQL: 数値または値のエラー
`ORA-12703`	この文字セット変換はサポートされません。
`ORA-12705`	NLSデータファイルにアクセスできないか、無効な環境が指定されました。

使用上のノート

NLS_LANGパラメータ・フォームlanguage_territory.character setは、to_charsetおよびfrom_charsetにも受け入れられます。ただし、このフォームは非推奨のため、使用しないことをお薦めします。languageおよびterritoryは、このサブプログラムでは無視されます。
変換後の値がRAW値の最大長である32767バイトを超えている場合は、警告なしで切り捨てられます。to_charsetとfrom_charsetのすべての可能な組合せでこの切捨てを避けたい場合は、floor(32767/4) = 8191バイトよりも長い値を変換しないでください。変換先の文字セットto_charsetの最大文字幅が判明している場合は、それを使用して制限をあまりペシミスティックでない値に拡大できます。たとえば、変換先の文字セットがZHS16GBKの場合、その最大限安全なソース文字列長さはfloor(32767/2) = 16383バイトになります。シングルバイトの変換先文字セットの場合、切捨ては一切必要ありません。

285.3.19 COPIESファンクション

このファンクションは、rをn回コピーして連結したものを戻します。

構文

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

プラグマ

pragma restrict_references(copies, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-30 COPIESファンクションのパラメータ

パラメータ	説明
`r`	コピーする`RAW`。
`n`	`RAW`をコピーする回数(必ず正の数で指定)。

戻り値

このファンクションは、n回コピーしたRAWを戻します。

例外

表285-31 COPIESファンクションの例外

エラー説明

エラー	説明
`VALUE_ERROR`	次のいずれかです。 - `r`が不明、`NULL`または長さ0です。 - `n` < 1 - 結果の長さが、`RAW`の最大長を超えました。

VALUE_ERROR

次のいずれかです。

- rが不明、NULLまたは長さ0です。

- n < 1

- 結果の長さが、RAWの最大長を超えました。

285.3.20 LENGTHファンクション

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

構文

UTL_RAW.LENGTH (
   r  IN RAW) 
RETURN NUMBER;

プラグマ

pragma restrict_references(length, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-32 LENGTHファンクションのパラメータ

パラメータ	説明
`r`	長さを測定する`RAW`バイト・ストリーム。

戻り値

表285-33 LENGTHファンクションの戻り値

戻り値	説明
`NUMBER`	`RAW`の現行の長さ。

285.3.21 OVERLAYファンクション

このファンクションは、target RAWの指定部分をoverlay_str RAWでオーバーレイし、targetの位置posバイトから始まるlenバイト分を処理します。

構文

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;

プラグマ

pragma restrict_references(overlay, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-34 OVERLAYファンクションのパラメータ

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

デフォルトとオプション・パラメータ

表285-35 OVERLAYファンクションのオプション・パラメータ

オプション・パラメータ	説明
`pos`	1
`len`	`overlay_str`の長さまで
`pad`	x'00'

戻り値

表285-36 OVERLAYファンクションの戻り値

戻り値	説明
`RAW`	指定したとおりにオーバーレイされたtargetの`byte_string`。

使用上のノート

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バイト列を使用して拡張されます。

例外

表285-37 OVERLAYファンクションの例外

エラー説明

エラー	説明
`VALUE_ERROR`	次のいずれかです。 - `Overlay_str`が`NULL`または長さ0です。 - targetが不明か、未定義です。 - targetの長さが、`RAW`の最大長を超えました。 - `len` < 0 - `pos` < 1

VALUE_ERROR

次のいずれかです。

- Overlay_strがNULLまたは長さ0です。

- targetが不明か、未定義です。

- targetの長さが、RAWの最大長を超えました。

- len < 0

- pos < 1

285.3.22 REVERSEファンクション

このファンクションは、RAW rのバイト順序を、最後から最初に逆転させます。

たとえば、x'0102F3'はx'F30201'になり、'xyz'は'zyx'に逆転されます。結果は、入力RAWと同じ長さになります。

構文

UTL_RAW.REVERSE (
   r IN RAW) 
  RETURN RAW;

プラグマ

pragma restrict_references(reverse, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-38 REVERSEファンクションのパラメータ

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

戻り値

表285-39 REVERSEファンクションの戻り値

戻り値	説明
`RAW`	`r`の逆転値を含んでいます。

例外

表285-40 REVERSEファンクションの例外

エラー	説明
`VALUE_ERROR`	`r`が`NULL`または長さ0です。

285.3.23 SUBSTRファンクション

このファンクションは、RAW rのposからlenバイトを戻します。

構文

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

プラグマ

pragma restrict_references(substr, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-41 SUBSTRファンクションのパラメータ

パラメータ	説明
`r`	一部が抽出される`RAW`バイト文字列
`pos`	`r`内で抽出を開始するバイト位置。
`len`	`r`から抽出する、`pos`からのバイト数(オプション)

デフォルトとオプション・パラメータ

表285-42 SUBSTRファンクションのオプション・パラメータ

オプション・パラメータ	説明
`len`	位置`pos`から`r`の終わりまでの長さ。

戻り値

表285-43 SUBSTRファンクションの戻り値

戻り値	説明
`portion of r`	`pos`から始まる`len`バイト長。
`NULL`	入力パラメータ`r`が`NULL`の場合。

使用上のノート

posが正の値の場合、SUBSTRはrの初めからカウントして最初のバイトを検索します。posが負の値の場合、SUBSTRはrの最後から逆方向にカウントします。posの値は0(ゼロ)に指定できません。
lenが省略された場合、SUBSTRはrの終わりまですべてのバイトを戻します。lenの値は1未満に指定できません。

例外

表285-44 SUBSTRファンクションの例外

エラー説明

エラー	説明
`VALUE_ERROR`	次の場合は`VALUE_ERROR`が戻されます。 pos = 0、またはpos > `r`の長さ len < 1、またはlen > `r`の長さ - (pos-1)

VALUE_ERROR

次の場合はVALUE_ERRORが戻されます。

pos = 0、またはpos > rの長さ
len < 1、またはlen > rの長さ - (pos-1)

285.3.24 TRANSLATEファンクション

このファンクションは、RAWs from_set とto_setのバイト列変換に従って、入力RAW r内のバイト列を変換します。

r内のバイト列がfrom_set内のバイト列と一致すると、to_set内の対応する位置にあるバイト列に置換され、一致しないと削除されます。

r内のバイト列がfrom_setで未定義の場合は、結果にコピーされます。from_setにある最初(最左端)のバイト列のみ使用されます。後続の複製部分はスキャンされずに無視されます。

構文

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

ノート:

コール順序のto_setおよびfrom_setが、TRANSLITERATEと比較して逆になっていることに注意してください。

プラグマ

pragma restrict_references(translate, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-45 TRANSLATEファンクションのパラメータ

パラメータ	説明
`r`	変換する`RAW`ソース・バイト列。
`from_set`	変換する`RAW`バイト・コード(`r`にある場合)。
`to_set`	対応する`from_str`バイト列が変換される`RAW`バイト・コード。

戻り値

表285-46 TRANSLATEファンクションの戻り値

戻り値	説明
`RAW`	変換されたバイト列。

使用上のノート

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

ノート:

TRANSLITERATEファンクションとは、次の点で異なります。

コール順序でto_setパラメータの前にfrom_setパラメータがあります。
from_setに存在するがto_setに対応する値が存在しないrのバイト列は、変換されないか、結果に含まれません。
結果のRAW値は、入力RAW値より短い場合があります。

TRANSLATEとTRANSLITERATEの機能は、to_setのバイト数がfrom_setより少ない場合にのみ異なることに注意してください。

例外

表285-47 TRANSLATEファンクションの例外

エラー説明

VALUE_ERROR

次のいずれかです。

- rがNULLまたは長さ0です。

- from_setがNULLまたは長さ0です。

- to_setがNULLまたは長さ0です。

285.3.25 TRANSLITERATEファンクション

このファンクションは、from_setとto_setのバイト列変換に従って、入力RAW r内のバイト列を変換します。

r内の連続するバイト列がfrom_set内で検索され、見つからない場合は、変更しないまま結果RAWにコピーされます。見つかった場合、そのバイト列は、to_setの対応するバイト列、対応するバイト列が存在しない場合はpadバイト列のいずれかに結果RAW内で置換されます。

r内のバイト列がfrom_setで未定義の場合は、結果にコピーされます。from_setにある最初(最左端)のバイト列のみ使用されます。後続の複製部分はスキャンされずに無視されます。結果RAWは、常にrと同じ長さになります。

構文

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と比較して逆になっていることに注意してください。

プラグマ

pragma restrict_references(transliterate, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-48 TRANSLITERATEファンクションのパラメータ

パラメータ	説明
`r`	変換する`RAW`入力バイト列。
`to_set`	対応する`from_set`バイト列が変換される`RAW`バイト・コード(任意の長さ)。
`from_set`	変換する`RAW`バイト・コード(`r`を示す場合)(任意の長さ)。
`pad`	to-setが`from_set`より短い場合に使用する1バイト列。

デフォルトとオプション・パラメータ

表285-49 TRANSLITERATEファンクションのオプション・パラメータ

オプション・パラメータ	説明
`to_set`	`NULL`文字列まで。実際は、必要に応じて`pad`を使用して、`from_set`の長さまで拡張されます。
`from_set`	`x'00'`から`x'fff'`まで。
`pad`	`x'00'`

戻り値

表285-50 TRANSLITERATEファンクションの戻り値

戻り値	説明
`RAW`	変換されたバイト列。

使用上のノート

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

ノート:

TRANSLATEファンクションとは、次の点で異なります。

コール順序でfrom_setパラメータの前にto_setパラメータがあります。
from_setに存在するがto_setに対応する値が存在しないrのバイト列は、結果でpadバイト列によって置換されます。
結果のRAW値は、常に入力RAW値と同じ長さになります。

TRANSLATEとTRANSLITERATEの機能は、to_setのバイト数がfrom_setより少ない場合にのみ異なることに注意してください。

例外

表285-51 TRANSLITERATEファンクションの例外

エラー	説明
`VALUE_ERROR`	`r`が`NULL`または長さ0です。

285.3.26 XRANGEファンクション

このファンクションは、指定したバイト・コードで開始および終了する連続した1バイト・エンコードを含むRAW valueを戻します。指定するバイト・コードは、シングルバイトの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;

プラグマ

pragma restrict_references(xrange, WNDS, RNDS, WNPS, RNPS);

パラメータ

表285-52 XRANGEファンクションのパラメータ

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

戻り値

表285-53 XRANGEファンクションの戻り値

戻り値	説明
`RAW`	連続した有効な1バイトの16進数コード。