270 UTL_RAW

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

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

270.1 UTL_RAWの概要

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

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

270.2 UTL_RAWの使用上の注意

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

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

注意:

データ・タイプに関する注:

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

  • INTEGERデータ・タイプとNUMBER(38)データ・タイプも同一です。このドキュメントでは、INTEGERのみを使用します。

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

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

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

サブプログラム 説明

BIT_ANDファンクション

RAW r1RAW r2の値でビット単位の論理演算ANDを実行し、AND演算後の結果RAWを戻します。

BIT_COMPLEMENTファンクション

RAW rの値でビット単位の論理演算補数を実行し、補数演算後の結果RAWを戻します。

BIT_ORファンクション

RAW r1RAW r2の値でビット単位の論理演算ORを実行し、OR演算後の結果RAWを戻します。

BIT_XORファンクション

RAW r1RAW 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_DOUBLERAWバイナリ表現をBINARY_DOUBLEに変換します。

CAST_TO_BINARY_FLOATファンクション

BINARY_FLOATRAWバイナリ表現をBINARY_FLOATに変換します。

CAST_TO_BINARY_INTEGERファンクション

BINARY_INTEGERRAWバイナリ表現をBINARY_INTEGERに変換します。

CAST_TO_NUMBERファンクション

NUMBERRAWバイナリ表現をNUMBERに変換します。

CAST_TO_NVARCHAR2ファンクション

RAW値をVARCHAR2値に変換します。

CAST_TO_RAWファンクション

VARCHAR2値をRAW値に変換します。

CAST_TO_VARCHAR2ファンクション

RAW値をVARCHAR2値に変換します。

COMPAREファンクション

RAW r1RAW r2を比較します。

CONCATファンクション

最大12までのRAWを単一のRAWに連結します。

CONVERTファンクション

RAW rをキャラクタ・セットfrom_charsetからキャラクタ・セットto_charsetに変換し、結果のRAWを戻します。

COPIESファンクション

rn回のコピーで連結したものを戻します。

LENGTHファンクション

RAW rの長さをバイトで戻します。

OVERLAYファンクション

target RAWの指定部分をoverlay_str RAWでオーバーレイし、targetの位置posバイトから始まるlenバイト分を処理します。

REVERSEファンクション

RAW rのバイトの順序を、最後から最初に逆転させます。

SUBSTRファンクション

RAW rposからlenバイトを戻します。

TRANSLATEファンクション

from_setto_setのバイト列変換に従って、入力RAW r内のバイト列を変換します。

TRANSLITERATEファンクション

from_setto_setのバイト列変換に従って、入力RAW r内のバイト列を変換します。

XRANGEファンクション

start_byteで始まり値end_byteで終わる、連続した有効な1バイト・コードをすべて含むRAWを戻します。

270.3.1 BIT_ANDファンクション

このファンクションは、RAW r1RAW 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); 

パラメータ

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

パラメータ 説明

r1

r2とAND演算をするRAW

r2

r1とAND演算をするRAW

戻り値

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

戻り値 説明

RAW

r1r2のAND演算結果を含んでいます。

NULL

入力パラメータr1またはr2NULLの場合。

使用上の注意

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

270.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); 

パラメータ

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

パラメータ 説明

r

補数演算を実行するRAW

戻り値

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

戻り値 説明

RAW

r1の補数演算結果を含んでいます。

NULL

入力パラメータrNULLの場合。

270.3.3 BIT_ORファンクション

このファンクションは、RAW r1RAW 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); 

パラメータ

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

パラメータ 説明

r1

r2とOR演算をするRAW

r2

r1とOR演算をするRAW

戻り値

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

戻り値 説明

RAW

r1r2のOR演算結果を含んでいます。

NULL

入力パラメータr1またはr2NULLの場合。

使用上の注意

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

270.3.4 BIT_XORファンクション

このファンクションは、RAW r1RAW 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); 

パラメータ

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

パラメータ 説明

r1

r2とXOR演算をするRAW

r2

r1とXOR演算をするRAW

戻り値

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

戻り値 説明

RAW

r1r2のXOR演算結果を含んでいます。

NULL

入力パラメータr1またはr2NULLの場合。

使用上の注意

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

270.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);

パラメータ

表270-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と同じになります。

戻り値

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を渡した場合も同じです。

270.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);

パラメータ

表270-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と同じになります。

戻り値

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を渡した場合も同じです。

270.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);

パラメータ

表270-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と同じになります。

戻り値

BINARY_INTEGERの値のバイナリ表現。

270.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);

パラメータ

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

パラメータ 説明

n

NUMBERの値。

戻り値

NUMBERの値のバイナリ表現。

270.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);

パラメータ

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

270.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);

パラメータ

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

270.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);

パラメータ

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

パラメータ 説明

r

BINARY_INTEGERのバイナリ表現。

endianess

big-endianまたはlittle-endianのアーキテクチャを表すPLS_INTEGER。デフォルトはbig-endianです。

戻り値

BINARY_INTEGER値。

270.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);

パラメータ

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

パラメータ 説明

r

NUMBERのバイナリ表現。

戻り値

NUMBERの値。

270.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); 

パラメータ

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

パラメータ 説明

r

NVARCHAR2に変更するRAW(先行する長さのフィールドなし)。

戻り値

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

戻り値 説明

NVARCHAR2

入力RAWと同じデータ。

NULL

入力パラメータrNULLの場合。

270.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); 

パラメータ

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

パラメータ 説明

c

RAWに変換されるVARCHAR2

戻り値

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

戻り値 説明

RAW

先行する長さのフィールドのない、入力VARCHAR2同じバイト長の同じデータ。

NULL

入力パラメータcNULLの場合。

270.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); 

パラメータ

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

パラメータ 説明

r

VARCHAR2に変更するRAW(先行する長さのフィールドなし)。

戻り値

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

戻り値 説明

VARCHAR2

入力RAWと同じデータ。

NULL

入力パラメータrNULLの場合。

270.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); 

パラメータ

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

パラメータ 説明

r1

比較する1番目のRAWで、NULLまたは長さ0が可能。

r2

比較する2番目のRAWで、NULLまたは長さ0が可能。

pad

これはオプションのパラメータです。r1またはr2の短い方を拡張するためのバイト列。デフォルトは、x'00'です。

戻り値

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

戻り値 説明

NUMBER

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

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

270.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項目です。

戻り値

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

戻り値 説明

RAW

連結された項目。

例外

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

270.3.18 CONVERTファンクション

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

from_charsetto_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);  

パラメータ

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

パラメータ 説明

r

変換するRAWバイト列。

to_charset

rの変換後のキャラクタ・セットの名前

from_charset

rが変換される前のキャラクタ・セットの名前

戻り値

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

戻り値 説明

RAW

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

例外

表270-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_charsetfrom_charsetのすべての可能な組合せでこの切捨てを避けたい場合は、floor(32767/4) = 8191バイトよりも長い値を変換しないでください。変換先のキャラクタ・セットto_charsetの最大文字幅が判明している場合は、それを使用して制限をあまりペシミスティックでない値に拡大できます。たとえば、変換先のキャラクタ・セットがZHS16GBKの場合、その最大限安全なソース文字列長さはfloor(32767/2) = 16383バイトになります。シングルバイトの変換先キャラクタ・セットの場合、切捨ては一切必要ありません。

270.3.19 COPIESファンクション

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

構文

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

プラグマ

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

パラメータ

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

パラメータ 説明

r

コピーするRAW

n

RAWをコピーする回数(必ず正の数で指定)。

戻り値

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

例外

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

エラー 説明

VALUE_ERROR

次のいずれかです。

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

- n < 1

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

270.3.20 LENGTHファンクション

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

構文

UTL_RAW.LENGTH (
   r  IN RAW) 
RETURN NUMBER;

プラグマ

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

パラメータ

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

パラメータ 説明

r

長さを測定するRAWバイト・ストリーム。

戻り値

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

戻り値 説明

NUMBER

RAWの現行の長さ。

270.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); 

パラメータ

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

パラメータ 説明

overlay_str

targetをオーバーレイするために使用するバイト列。

target

オーバーレイするバイト列。

pos

オーバーレイを開始する、target内での位置(1から番号付けされている)。

len

オーバーレイするtargetバイトの数。

pad

オーバーレイlenoverlay_str長を超えた場合、またはpostargetの長さを超えた場合に使用するpadバイト列。

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

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

オプション・パラメータ 説明

pos

1

len

overlay_strの長さまで

pad

x'00'

戻り値

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

戻り値 説明

RAW

指定したとおりにオーバーレイされたtargetのbyte_string

使用上の注意

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

lenを指定する場合は、0 (ゼロ)以上にする必要があります。posを指定する場合は、1以上にする必要があります。postargetの長さを超える場合、targetpadバイト列を使用してposの位置まで埋め込まれます。さらに、targetoverlay_strバイト列を使用して拡張されます。

例外

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

エラー 説明

VALUE_ERROR

次のいずれかです。

- Overlay_strNULLまたは長さ0です。

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

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

- len < 0

- pos < 1

270.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); 

パラメータ

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

パラメータ 説明

r

逆転するRAW

戻り値

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

戻り値 説明

RAW

rの逆転値を含んでいます。

例外

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

エラー 説明

VALUE_ERROR

rNULLまたは長さ0です。

270.3.23 SUBSTRファンクション

このファンクションは、RAW rposから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); 

パラメータ

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

パラメータ 説明

r

一部が抽出されるRAWバイト文字列

pos

r内で抽出を開始するバイト位置。

len

rから抽出する、posからのバイト数(オプション)

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

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

オプション・パラメータ 説明

len

位置posからrの終わりまでの長さ。

戻り値

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

戻り値 説明

portion of r

posから始まるlenバイト長。

NULL

入力パラメータrNULLの場合。

使用上の注意

  • posが正の値の場合、SUBSTRrの初めからカウントして最初のバイトを検索します。posが負の値の場合、SUBSTRrの最後から逆方向にカウントします。posの値は0(ゼロ)に指定できません。

  • lenが省略された場合、SUBSTRrの終わりまですべてのバイトを戻します。lenの値は1未満に指定できません。

例外

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

エラー 説明

VALUE_ERROR

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

  • pos = 0、またはpos > rの長さ

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

270.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); 

パラメータ

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

パラメータ 説明

r

変換するRAWソース・バイト列。

from_set

変換するRAWバイト・コード(rにある場合)。

to_set

対応するfrom_strバイト列が変換されるRAWバイト・コード。

戻り値

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

戻り値 説明

RAW

変換されたバイト列。

使用上の注意

  • to_setfrom_setより短い場合、from_setの余分なバイト列に対応する変換バイト列はありません。このようなfrom_setバイト列に一致する入力RAWのバイト列は、変換されないか、結果に含まれません。これらのバイト列は、事実上NULLに変換されます。

  • to_setfrom_setより長い場合、to_setの余分なバイト列は無視されます。

  • バイト値がfrom_setで繰り返されている場合、その繰返し部分は無視されます。

注意:

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

  • コール順序でto_setパラメータの前にfrom_setパラメータがあります。

  • from_setに存在するがto_setに対応する値が存在しないrのバイト列は、変換されないか、結果に含まれません。

  • 結果のRAW値は、入力RAW値より短い場合があります。

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

例外

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

エラー 説明

VALUE_ERROR

次のいずれかです。

- rNULLまたは長さ0です。

- from_setNULLまたは長さ0です。

- to_setNULLまたは長さ0です。

270.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); 

パラメータ

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

パラメータ 説明

r

変換するRAW入力バイト列。

to_set

対応するfrom_setバイト列が変換されるRAWバイト・コード(任意の長さ)。

from_set

変換するRAWバイト・コード(rを示す場合)(任意の長さ)。

pad

to-setがfrom_setより短い場合に使用する1バイト列。

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

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

オプション・パラメータ 説明

to_set

NULL文字列まで。実際は、必要に応じてpadを使用して、from_setの長さまで拡張されます。

from_set

x'00'からx'fff'まで。

pad

x'00'

戻り値

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

戻り値 説明

RAW

変換されたバイト列。

使用上の注意

  • to_setfrom_setより短い場合、from_setの余分なバイト列に対応する変換バイト列はありません。このようなfrom_setバイト列に一致する入力RAWのバイト列は、結果でpadバイト列に変換されます。

  • to_setfrom_setより長い場合、to_setの余分なバイト列は無視されます。

  • バイト値がfrom_setで繰り返されている場合、その繰返し部分は無視されます。

注意:

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

  • コール順序でfrom_setパラメータの前にto_setパラメータがあります。

  • from_setに存在するがto_setに対応する値が存在しないrのバイト列は、結果でpadバイト列によって置換されます。

  • 結果のRAW値は、常に入力RAW値と同じ長さになります。

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

例外

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

エラー 説明

VALUE_ERROR

rNULLまたは長さ0です。

270.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); 

パラメータ

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

パラメータ 説明

start_byte

戻される連続値の最初のバイト・コード値。デフォルトは、x'00'です。

end_byte

戻される連続値の最後のバイト・コード値。デフォルトは、x'FF'です。

戻り値

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

戻り値 説明

RAW

連続した有効な1バイトの16進数コード。