UTL_RAW
パッケージは、RAW
データ・タイプを操作するためのSQLファンクションを提供します。
この章の内容は次のとおりです。
概要
使用上の注意
通常のSQLファンクションは複数のRAW
値で作動せず、PL/SQLはRAW
データ・タイプとCHAR
データ・タイプの間でのオーバーロードができないため、このパッケージが必要になります。
UTL_RAW
は、データベース環境に固有のものではなく、他の環境でも使用できます。このため、DBMS
のかわりに、UTL
という接頭辞がパッケージに付けられています。
UTL_RAW
では、RAW
レコードを多くの要素で構成できます。RAW
データ・タイプを使用すると、キャラクタ・セット変換は実行されず、リモート・プロシージャ・コールによる転送時にRAW
値は元の形式で保持されます。
また、RAW
ファンクションによって、以前はhextoraw
ファンクションとrawtohex
SQLファンクションに限定されていたバイナリ・データを操作できます。
RAW
値を戻すファンクションは、16進数エンコーディングでその処理を行います。
表11-1 UTL_RAWパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
2つの |
|
1つの |
|
2つの |
|
2つの |
CAST_FROM_BINARY_DOUBLEファンクション |
|
|
|
CAST_FROM_BINARY_INTEGERファンクション |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2つの |
|
最大12の |
|
|
|
|
|
|
|
ターゲット |
|
|
|
指定された開始位置から指定されたバイト数だけ、 |
|
指定された変換 |
|
指定された文字変換 |
|
指定されたバイト・コードで開始および終了する連続する1バイト・エンコーディングを含む |
注意:
|
このファンクションは、2つの提供されたRAW
値でビット単位の論理演算AND
を実行し、結果のRAW
を戻します。
構文
UTL_RAW.BIT_AND ( r1 IN RAW, r2 IN RAW) RETURN RAW;
パラメータ
戻り値
AND
演算の結果、またはNULL
(いずれかの入力値がNULL
の場合)を含みます。
使用上の注意
r1
とr2
の長さが異なる場合、2つのRAW
値のうち短い方の最終バイトが終わると演算は終了され、長い方のRAW
値の未処理部分が部分的な結果に追加されます。結果の長さは、2つの入力値のうち長い方に等しくなります。
このファンクションは、提供されたRAW
値でビット単位の論理演算COMPLEMENT
を実行し、結果のRAW
を戻します。結果の長さは、入力RAW
の長さに等しくなります。
構文
UTL_RAW.BIT_COMPLEMENT (
r IN RAW)
RETURN RAW;
パラメータ
戻り値
COMPLEMENT
演算の結果、またはNULL
(入力値がNULL
の場合)を含みます。
このファンクションは、2つの提供されたRAW
値でビット単位の論理演算OR
を実行し、結果のRAW
を戻します。
構文
UTL_RAW.BIT_OR ( r1 IN RAW, r2 IN RAW) RETURN RAW;
パラメータ
戻り値
OR
演算の結果、またはNULL
(いずれかの入力値がNULL
の場合)を含みます。
使用上の注意
r1
とr2
の長さが異なる場合、2つのRAW
値のうち短い方の最終バイトが終わると演算は終了され、長い方のRAW
値の未処理部分が部分的な結果に追加されます。結果の長さは、2つの入力値のうち長い方に等しくなります。
このファンクションは、2つの提供されたRAW
値でビット単位の論理演算XOR
(排他OR)を実行し、結果のRAW
を戻します。
構文
UTL_RAW.BIT_XOR ( r1 IN RAW, r2 IN RAW) RETURN RAW;
パラメータ
戻り値
XOR
演算の結果、またはNULL
(いずれかの入力値がNULL
の場合)を含みます。
使用上の注意
r1
とr2
の長さが異なる場合、2つのRAW
値のうち短い方の最終バイトが終わると演算は終了され、長い方のRAW
値の未処理部分が部分的な結果に追加されます。結果の長さは、2つの入力値のうち長い方に等しくなります。
このファンクションは、BINARY_DOUBLE
値のRAW
バイナリ表現を戻します。
構文
UTL_RAW.CAST_FROM_BINARY_DOUBLE( n IN BINARY_DOUBLE, endianess IN BINARY_INTEGER DEFAULT 1) RETURN RAW;
パラメータ
表11-6 CAST_FROM_BINARY_DOUBLEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
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
のバイトを示しています。
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
を指定した場合と同様です。
このファンクションは、BINARY_FLOAT
値のRAW
バイナリ表現を戻します。
構文
UTL_RAW.CAST_FROM_BINARY_FLOAT( n IN BINARY_FLOAT, endianess IN BINARY_INTEGER DEFAULT 1) RETURN RAW;
パラメータ
表11-7 CAST_FROM_BINARY_FLOATファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
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 | fbo |
fb1 |
fb2 |
fb3 |
little_endian | fb3 |
fb2 |
fb1 |
fb0 |
machine_endian
を指定すると、BINARY_FLOAT
引数の4バイトがRAW
戻り値に直接コピーされます。ユーザーがビッグエンディアン・システムでbig_endian
を、またはリトルエンディアン・システムでlittle_endian
を指定した場合と同様です。
このファンクションは、BINARY_INTEGER
値のRAW
バイナリ表現を戻します。
構文
UTL_RAW.CAST_FROM_BINARY_INTEGER ( n IN BINARY_INTEGER endianess IN BINARY_INTEGER DEFAULT 1) RETURN RAW;
パラメータ
表11-8 CAST_FROM_BINARY_INTEGERファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
BINARY_INTEGER
値のRAW
バイナリ表現、またはNULL
(入力がNULL
の場合)。
このファンクションは、NUMBER
値のRAW
バイナリ表現を戻します。
構文
UTL_RAW.CAST_FROM_NUMBER (
n IN NUMBER)
RETURN RAW;
パラメータ
戻り値
NUMBER
値のRAW
バイナリ表現、またはNULL
(入力がNULL
の場合)。
このファンクションは、BINARY_DOUBLE
値のRAW
バイナリ表現をBINARY_DOUBLE
値に変換します。
構文
UTL_RAW.CAST_TO_BINARY_DOUBLE ( r IN RAW endianess IN BINARY_INTEGER DEFAULT 1) RETURN BINARY_DOUBLE;
パラメータ
表11-10 CAST_TO_BINARY_DOUBLEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
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
内のバイトを示しています。
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
を指定した場合と同様です。
例外
RAW
引数が8バイト未満の場合、VALUE_ERROR
例外が発生します。
このファンクションは、BINARY_FLOAT
値のRAW
バイナリ表現をBINARY_FLOAT
値に変換します。
構文
UTL_RAW.CAST_TO_BINARY_FLOAT ( r IN RAW endianess IN BINARY_INTEGER DEFAULT 1) RETURN BINARY_FLOAT;
パラメータ
表11-11 CAST_TO_BINARY_FLOATファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
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
内のバイトを示しています。
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
を指定した場合と同様です。
例外
RAW
引数が4バイト未満の場合、VALUE_ERROR
例外が発生します。
このファンクションは、BINARY_INTEGER
値のRAW
バイナリ表現をBINARY_INTEGER
値に変換します。
構文
UTL_RAW.CAST_TO_BINARY_INTEGER ( r IN RAW endianess IN BINARY_INTEGER DEFAULT 1) RETURN BINARY_INTEGER;
パラメータ
表11-12 CAST_TO_BINARY_INTEGERファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
エンディアンを示す |
戻り値
BINARY_INTEGER
値、またはNULL
(入力がNULL
の場合)。
このファンクションは、NUMBER
値のRAW
バイナリ表現をNUMBER
値に変換します。
構文
UTL_RAW.CAST_TO_NUMBER (
r IN RAW)
RETURN NUMBER;
パラメータ
戻り値
NUMBER
値、またはNULL
(入力がNULL
の場合)。
このファンクションは、一定数のデータ・バイトを使用して表したRAW
値を、同じ数のデータ・バイトのNVARCHAR2
値に変換します。
注意: NVARCHAR2 への変換時、そのNVARCHAR2 値内の文字に対して現行のグローバリゼーション・サポート・キャラクタ・セットが使用されます。 |
構文
UTL_RAW.CAST_TO_NVARCHAR2 (
r IN RAW)
RETURN NVARCHAR2;
パラメータ
戻り値
入力RAW
値から変換されたデータ、またはNULL
(入力がNULL
の場合)を含みます。
このファンクションは、一定数のデータ・バイトを使用して表したVARCHAR2
値を、同じ数のデータ・バイトのRAW
値に変換します。データ自体は変更されませんが、そのデータ・タイプはRAW
データ・タイプに再変換されます。
構文
UTL_RAW.CAST_TO_RAW (
c IN VARCHAR2)
RETURN RAW;
パラメータ
戻り値
入力VARCHAR2
値から変換されたデータを含みます(入力値と同じバイト長で、先行する長さのフィールドはありません)。または、入力がNULL
の場合は、NULL
を含みます。
このファンクションは、一定数のデータ・バイトを使用して表したRAW
値を、同じ数のデータ・バイトのVARCHAR2
値に変換します。
注意: VARCHAR2 への変換時、そのVARCHAR2 値内の文字に対して現行のグローバリゼーション・サポート・キャラクタ・セットが使用されます。 |
構文
UTL_RAW.CAST_TO_VARCHAR2 (
r IN RAW)
RETURN VARCHAR2;
パラメータ
戻り値
入力RAW
値から変換されたデータ、またはNULL
(入力がNULL
の場合)を含みます。
このファンクションは、2つのRAW
値を比較します。それぞれの値の長さが異なる場合、短い方の値は、オプションのpad
パラメータに従って右側に拡張されます。
構文
UTL_RAW.COMPARE ( r1 IN RAW, r2 IN RAW, [pad IN RAW DEFAULT NULL]) RETURN NUMBER;
パラメータ
表11-17 COMPAREファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
比較する1つ目の |
|
比較する2つ目の |
|
入力値の短い方を延長するバイト。これはオプションです。デフォルトは |
戻り値
2つの入力値を比較した場合は最初の不一致バイトの位置番号(1から番号付けされている)に等しいNUMBER
値で、入力値が同一または両方がNULL
の場合は0。
このファンクションは、最大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;
パラメータ
項目r1...r12
は、連結するRAW
項目です。
戻り値
連結された入力値で構成されるRAW
値。
例外
入力の長さの合計がRAW
値で許容される最大長(32767バイト)を超えると、エラーが発生します。
このファンクションは、RAW
値をあるキャラクタ・セットから別のキャラクタ・セットに変換して、結果のRAW
を戻します。
どちらのキャラクタ・セットも、データベースに定義されているサポートされるキャラクタ・セットである必要があります。
構文
UTL_RAW.CONVERT ( r IN RAW, to_charset IN VARCHAR2, from_charset IN VARCHAR2) RETURN RAW;
パラメータ
表11-18 CONVERTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
変換する |
|
入力値の変換後のグローバリゼーション・サポート・キャラクタ・セットの名前。 |
|
入力値の変換前のグローバリゼーション・サポート・キャラクタ・セットの名前。 |
戻り値
指定したキャラクタ・セットに従って変換されたバイト文字列が含まれます。
例外
VALUE_ERROR
は、次のいずれかの場合に発生します。
入力バイト文字列が失われたか、NULL
または長さが0(ゼロ)の場合。
from_charset
またはto_charset
が失われたか、NULL
または長さが0の場合。
from_charset
またはto_charset
が無効であるか、サポートされていない場合。
このファンクションは、指定されたRAW
値を指定された回数だけコピーし、連結して戻します。
構文
UTL_RAW.COPIES ( r IN RAW, n IN NUMBER) RETURN RAW;
パラメータ
戻り値
指定された回数だけコピーされ、連結されたRAW
値。
例外
VALUE_ERROR
は、次のいずれかの場合に発生します。
コピーする値が失われたか、NULL
または長さが0(ゼロ)の場合。
値をコピーする回数が0以下の場合。
結果の長さがRAW
値で許容される最大長(32767バイト)を超える場合。
このファンクションは、RAW
値の長さをバイト単位で戻します。
構文
UTL_RAW.LENGTH (
r IN RAW)
RETURN NUMBER;
パラメータ
戻り値
RAW
値の長さを示すNUMBER
値(バイト単位)。
このファンクションは、ターゲット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;
パラメータ
表11-21 OVERLAYファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
ターゲットのオーバーレイに使用されるバイト文字列。 |
|
オーバーレイされるターゲットのバイト文字列。 |
|
オーバーレイを開始するターゲットのバイト位置(1から番号付けされている)。これはオプションです。デフォルトは1です。 |
|
オーバーレイするバイト数。これはオプションです。デフォルトは |
|
|
戻り値
指定どおりにオーバーレイされた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以下の場合。
このファンクションは、RAW
のバイトの順序をすべて逆転させます。たとえば、x'0102F3'
は逆転されてx'F30201'
になり、'xyz'
は逆転されて'zyx'
になります。結果の長さは入力の長さと同じです。
構文
UTL_RAW.REVERSE (
r IN RAW)
RETURN RAW;
パラメータ
戻り値
入力値の逆転であるRAW
値を含みます。
例外
入力値がNULL
または長さが0(ゼロ)の場合にVALUE_ERROR
が発生します。
このファンクションは、指定されたバイト数および開始位置のRAW
値のサブストリングを戻します。
構文
UTL_RAW.SUBSTR ( r IN RAW, pos IN BINARY_INTEGER, [len IN BINARY_INTEGER DEFAULT NULL]) RETURN RAW;
パラメータ
表11-23 SUBSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
サブストリングの抽出元の |
|
抽出を開始するバイト位置で、入力バイト文字列の先頭から前方へカウントされるか(正の値)、または末尾から後方へカウントされます(負の値)。 |
|
抽出するバイト数( |
戻り値
開始位置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
次の例では、開始位置として、入力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
次の例は、前の例と力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
このファンクションは、入力バイトのセット、入力バイト内で検索する変換前のバイトのセット、および変換後の対応するバイトのセットが指定されている場合に、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 とは逆であることに注意してください。 |
パラメータ
表11-24 TRANSLATEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
適用可能な場合に、バイトが変換される |
|
ソース・バイト文字列内で検索される |
|
変換後の |
戻り値
変換後のバイト文字列を含むRAW
値。
使用上の注意
to_set
がfrom_set
よりも短い場合、余ったfrom_set
バイトに対応する変換バイトはありません。そのようなfrom_set
バイトに一致する入力RAW
値からのバイトは、結果で変換されることも、結果に含まれることもありません。事実上、NULL
に変換されます。
to_set
がfrom_set
より長い場合、余ったto_set
バイトは無視されます。
あるバイト値がfrom_set
で繰り返し出現する場合、それは無視されます。
注意: TRANSLITERATE との相違点:
|
例外
ソース・バイト文字列、from_set
またはto_set
がNULL
または長さが0(ゼロ)の場合、VALUE_ERROR
が発生します。
例
例1
次の例では、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
次の例では、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
を指定した場合は動作が同じです(「例」を参照)。
from_set: 12AA12 to_set: CDABEF source raw: 1236567812125612344434341234567890ABAA1234 return raw: CD365678CDCD56CD34443434CD34567890ABABCD34 PL/SQL procedure successfully completed.
このファンクションは、入力バイトのセット、入力バイト内で検索する変換前のバイトのセット、および変換後の対応するバイトのセットが指定されている場合に、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 とは逆であることに注意してください。 |
パラメータ
表11-25 TRANSLITERATEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
適用可能な場合に、バイトが変換される |
|
変換後の |
|
ソース・バイト文字列で検索される |
|
|
戻り値
変換後のバイト文字列を含むRAW
値。
使用上の注意
to_set
がfrom_set
よりも短い場合、余ったfrom_set
バイトに対応する変換バイトはありません。そのようなfrom_set
バイトに一致した入力RAW
値は、結果でpad
バイトに変換されます。
to_set
がfrom_set
より長い場合、余ったto_set
バイトは無視されます。
あるバイト値がfrom_set
で繰り返し出現する場合、それは無視されます。
注意: TRANSLATE との相違点:
|
例外
ソース・バイト文字列がNULL
または長さが0(ゼロ)の場合にVALUE_ERROR
が発生します。
例
例1
次の例では、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
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
次の例では、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; /
結果は次のとおりです。TRANSLATE
でも同じ入力RAW
、from_set
およびto_set
を指定した場合は動作が同じです(「例」を参照)。
from_set: 12AA12 to_set: CDABEF source raw: 1236567812125612344434341234567890ABAA1234 return raw: CD365678CDCD56CD34443434CD34567890ABABCD34 PL/SQL procedure successfully completed.
例4
次の例では、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.
このファンクションは、指定したバイト・コードで開始および終了する連続した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;
パラメータ
表11-26 XRANGEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
戻される連続値の最初のバイト・コード値。デフォルトは |
|
戻される連続値の最後のバイト・コード値。デフォルトは |
戻り値
1バイト・エンコーディングの連続を含むRAW
値。
例
次の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.