UTL_I18N

268 UTL_I18N

UTL_I18Nは、PL/SQLで作成されたアプリケーションに追加のグローバリゼーション機能を提供するサービスを集めたものです。

参照:

Oracle Databaseグローバリゼーション・サポート・ガイド

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

268.1 UTL_I18Nの概要

UTL_I18Nは、PL/SQLで作成されたアプリケーションに追加のグローバリゼーション機能を提供します。

UTL_I18N PL/SQLパッケージは、次のカテゴリのサービスで構成されています。

各種データ・タイプに対応した文字列変換ファンクション
テキスト文字列と文字参照の間で変換を実行するファンクション
Oracle、JavaおよびISOの各言語と各テリトリの間でマップするファンクション
Oracle、Internet Assigned Numbers Authority (IANA)および電子メールで安全な文字セット間でマップするファンクション
Oracleの言語名からOracleの文字セット名を戻すファンクション
Oracle文字セットの文字の最大バイト数を戻すファンクション。
スクリプト変換を実行するファンクション
指定したテリトリでサポートされているISO通貨コード、ローカル・タイムゾーンおよびローカル言語を戻すファンクション
指定した言語でサポートされている最適な言語ソート、すべての適切な言語ソートのリストおよびローカル・テリトリを戻すファンクション
Oracleの完全言語名と短縮言語名の間でマップするファンクション
指定した言語およびテリトリ名の言語変換を戻すファンクション
最も一般的に使用されるタイムゾーンのリストを戻すファンクション

268.2 UTL_I18Nのセキュリティ・モデル

UTL_I18Nパッケージのファンクションは、データベースの内容の読取りも変更も行いません。これらのファンクションは、ファンクションの引数でのみ操作を行うか、またはNLSデータ・ファイルから静的な国際化情報を取得します(あるいはその両方を行います)。このパッケージの実行権限は、デフォルトでPUBLICに付与されます。

268.3 UTL_I18N定数

UTL_I18Nは、パラメータ値の指定時に使用する定数を定義します。

これらの定数を、次の表に示します。

表268-1 UTL_I18Nの定数

定数	タイプ	値	説明
`GENERIC_CONTEXT`	`PLS_INTEGER`	`0`	一般に使用するデフォルトの文字セットを戻します。
`MAIL_GENERIC`	`PLS_INTEGER`	`0`	Windows以外のプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。
`ORACLE_TO_IANA`	`PLS_INTEGER`	`0`	Oracleの文字セット名からIANAの文字セット名にマップします。
`SHIFT_IN`	`PLS_INTEGER`	`0`	`shift_status`とともに使用します。ピース単位の変換で初めてコールするときに設定する必要があります。
`IANA_TO_ORACLE`	`PLS_INTEGER`	`1`	IANAの文字セット名からOracleの文字セット名にマップします。
`MAIL_CONTEXT`	`PLS_INTEGER`	`1`	Oracleの文字セット名と電子メールで安全な文字セット名の間でマッピングが行われます。
`MAIL_WINDOWS`	`PLS_INTEGER`	`1`	Windowsプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。
`SHIFT_OUT`	`PLS_INTEGER`	`1`
`FWKATAKANA_HIRAGANA`	`VARCHAR2(30)`	`'fwkatakana_hiragana'`	全角カタカナのみを全角ひらがなに変換します。
`FWKATAKANA_HWKATAKANA`	`VARCHAR2(30)`	`'fwkatakana_hwkatakana'`	全角カタカナのみを半角カタカナに変換します。
`HIRAGANA_FWKATAKANA`	`VARCHAR2(30)`	`'hiragana_fwkatakana'`	全角ひらがなのみを全角カタカナに変換します。
`HIRAGANA_HWKATAKANA`	`VARCHAR2(30)`	`'hiragana_hwkatakana'`	全角ひらがなのみを半角カタカナに変換します。
`HWKATAKANA_FWKATAKANA`	`VARCHAR2(30)`	`'hwkatakana_fwkatakana'`	半角カタカナのみを全角カタカナに変換します。
`HWKATAKANA_HIRAGANA`	`VARCHAR2(30)`	`'hwkatakana_hiragana'`	半角カタカナのみを全角ひらがなに変換します。
`KANA_FWKATAKANA`	`VARCHAR2(30)`	`'kana_fwkatakana'`	すべてのタイプの仮名文字を全角カタカナに変換します。
`KANA_HIRAGANA`	`VARCHAR2(30)`	`'kana_hiragana'`	すべてのタイプの仮名文字を全角ひらがなに変換します。
`KANA_HWKATAKANA`	`VARCHAR2(30)`	`'kana_hwkatakana'`	すべてのタイプの仮名文字を半角カタカナに変換します。

268.4 UTL_I18Nサブプログラムの要約

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

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

プロシージャ	説明
ESCAPE_REFERENCEファンクション	指定したテキスト文字列をドキュメントの文字セット以外の文字に対応する文字参照に変換します。
GET_COMMON_TIME_ZONESファンクション	ロケールとは無関係な共通タイムゾーンIDのリストを戻します。
GET_DEFAULT_CHARSETファンクション	Oracleの言語名から、デフォルトのOracleの文字セット名または電子メールで安全なデフォルトの文字セット名を戻します。
GET_DEFAULT_ISO_CURRENCYファンクション	指定したテリトリのデフォルトのISO 4217通貨コードを戻します。
GET_DEFAULT_LINGUISTIC_SORTファンクション	指定した言語のデフォルトの言語ソート名を戻します。
GET_LOCAL_LANGUAGESファンクション	指定したテリトリのローカル言語名を戻します。
GET_LOCAL_LINGUISTIC_SORTSファンクション	指定した言語のローカル言語ソート名を戻します。
GET_LOCAL_TERRITORIESファンクション	指定した言語のローカル・テリトリ名を戻します。
GET_LOCAL_TIME_ZONESファンクション	指定したテリトリのローカル・タイムゾーンIDを戻します。
GET_MAX_CHARACTER_SIZEファンクション	指定された文字セットの最大文字サイズを戻します。
GET_TRANSLATIONファンクション	指定した変換言語の言語およびテリトリ名の変換を戻します。
MAP_CHARSETファンクション	Oracleの文字セット名をIANAの文字セット名にマップします。 IANAの文字セット名をOracleの文字セット名にマップします。 Oracleの文字セット名を電子メールで安全な文字セット名にマップします。
MAP_FROM_SHORT_LANGUAGEファンクション	Oracleの短縮言語名をOracleの言語名にマップします。
MAP_LANGUAGE_FROM_ISOファンクション	ISOのロケール名からOracleの言語名を戻します。
MAP_LOCALE_TO_ISOファンクション	Oracleの言語名およびテリトリ名からISOのロケール名を戻します。
MAP_TERRITORY_FROM_ISOファンクション	ISOのロケール名からOracleのテリトリ名を戻します。
MAP_TO_SHORT_LANGUAGEファンクション	Oracleの言語名をOracleの短縮言語名にマップします。
RAW_TO_CHARファンクション	データベース文字セットにエンコードされていない`RAW`データを`VARCHAR2`文字列に変換します。
RAW_TO_NCHARファンクション	各国語文字セットにエンコードされていない`RAW`データを`NVARCHAR2`文字列に変換します。
STRING_TO_RAWファンクション	`VARCHAR2`文字列または`NVARCHAR2`文字列を別の文字セットに変換します。結果は`RAW`データ・タイプとして戻されます。
TRANSLITERATEファンクション	日本語のひらがなとカタカナの変換を実行します。
UNESCAPE_REFERENCEファンクション	文字参照を含む入力文字列をテキスト文字列に変換します。
VALIDATE_CHARACTER_ENCODINGファンクション	VARCHAR2、NVARCHAR2、CLOBおよびNCLOBデータの文字エンコードを検証します。

268.4.1 ESCAPE_REFERENCEファンクション

このファンクションは、テキスト文字列を現行のドキュメントで使用されている文字セット以外の文字に対応する文字参照に変換します。

文字参照は主に、文書のエンコードとは無関係に文字を表すためにHTMLおよびXML文書で使用されます。文字参照は、数値文字参照と文字エンティティ参照の2つの形式で表される場合があります。数値文字参照では文字のUnicodeコード・ポイント値を指定し、文字エンティティ参照では同じ文字を参照するために記号名を使用します。たとえば、åは上に丸の付いた小文字aを表す数値文字参照で、åは同じ文字の文字エンティティ参照です。また、文字エンティティ参照を使用して、< (より小)記号を表す<などの特殊文字をエスケープすることもできます。これによって、マークアップ言語のタグの開始で発生する可能性がある混同を回避します。

構文

UTL_I18N.ESCAPE_REFERENCE(
    str            IN VARCHAR2 CHARACTER SET ANY_CS,
    page_cs_name   IN VARCHAR2 DEFAULT NULL)
 RETURN VARCHAR2 CHARACTER SET str%CHARSET;

パラメータ

表268-3 ESCAPE_REFERENCEファンクションのパラメータ

パラメータ	説明
`str`	入力文字列を指定します。
`page_cs_name`	ドキュメントの文字セットを指定します。`page_cs_name`が`NULL`の場合は、データベース文字セットが`CHAR`データに使用され、各国語文字セットが`NCHAR`データに使用されます。

使用上のノート

ユーザーが無効な文字セットまたはNULL文字列を指定すると、ファンクションはNULL文字列を戻します。

例

UTL_I18N.ESCAPE_REFERENCE('hello < '||chr(229),'us7ascii')

'hello < å'が戻されます。

268.4.2 GET_COMMON_TIME_ZONESファンクション

このファンクションは、最も一般的に使用されるタイムゾーンのリストを戻します。このリストには、データベースでサポートされているタイムゾーンのサブセットが示されます。

構文

UTL_I18N.GET_COMMON_TIME_ZONES
 RETURN STRING_ARRAY;

例

最も一般的に使用されるタイムゾーンのリストを戻します。

DECLARE
   retval UTL_I18N.STRING_ARRAY;
BEGIN
   retval := UTL_I18N.GET_COMMON_TIME_ZONES;
END;
/

268.4.3 GET_DEFAULT_CHARSETファンクション

このファンクションは、Oracleの言語名から、デフォルトのOracleの文字セット名またはデフォルトの電子メールで安全な文字セット名を戻します。

参照:

電子メールで安全な文字セットについては、「MAP_CHARSETファンクション」を参照してください。

構文

UTL_I18N.GET_DEFAULT_CHARSET( 
   language  IN VARCHAR2,
   context   IN PLS_INTEGER DEFAULT GENERIC_CONTEXT,
   iswindows IN BOOLEAN DEFAULT FALSE)
 RETURN VARCHAR2;

パラメータ

表268-4 GET_DEFAULT_CHARSETファンクションのパラメータ

パラメータ説明

パラメータ	説明
`language`	有効なOracle言語を指定します。
`context`	`GENERIC_CONTEXT \| MAIL_CONTEXT` `GENERIC_CONTEXT`: 一般に使用するデフォルトの文字セットを戻します。 `MAIL_CONTEXT`: 電子メールで安全な文字セット名を戻します。
`iswindows`	`context`が`MAIL_CONTEXT`として設定されている場合は、プラットフォームがWindowsであれば`iswindows`を`TRUE`に設定し、プラットフォームがWindows以外であれば`FALSE`に設定する必要があります。デフォルトは`FALSE`です。 `context`を`GENERIC_CONTEXT`に設定した場合、`iswindows`は無効です。

language

有効なOracle言語を指定します。

context

GENERIC_CONTEXT | MAIL_CONTEXT

GENERIC_CONTEXT: 一般に使用するデフォルトの文字セットを戻します。

MAIL_CONTEXT: 電子メールで安全な文字セット名を戻します。

iswindows

contextがMAIL_CONTEXTとして設定されている場合は、プラットフォームがWindowsであればiswindowsをTRUEに設定し、プラットフォームがWindows以外であればFALSEに設定する必要があります。デフォルトはFALSEです。

contextをGENERIC_CONTEXTに設定した場合、iswindowsは無効です。

使用上のノート

ユーザーが無効な言語名や無効なフラグを指定すると、ファンクションはNULL文字列を戻します。

例

GENERIC_CONTEXT, iswindows=FALSE

UTL_I18N.GET_DEFAULT_CHARSET('French', UTL_I18N.GENERIC_CONTEXT, FALSE)

'WE8ISO8859P1'が戻されます。

MAIL_CONTEXT, iswindows=TRUE

UTL_I18N.GET_DEFAULT_CHARSET('French', UTL_I18N.MAIL_CONTEXT, TRUE)

'WE8MSWIN1252'が戻されます。

MAIL_CONTEXT, iswindows=FALSE

UTL_I18N.GET_DEFAULT_CHARSET('French', UTL_I18N.MAIL_CONTEXT, FALSE)

'WE8ISO8859P1'が戻されます。

268.4.4 GET_DEFAULT_ISO_CURRENCYファンクション

このファンクションは、指定したテリトリのデフォルトのISO 4217通貨コードを戻します。

構文

UTL_I18N.GET_DEFAULT_ISO_CURRENCY (
   territory    IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN VARCHAR2;

パラメータ

表268-5 GET_DEFAULT_ISO_CURRENCYファンクションのパラメータ

パラメータ	説明
`territory`	有効なOracleテリトリを指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効なテリトリ名を指定した場合、ファンクションはNULL文字列を戻します。

例

中国のデフォルトのISO通貨コードを表示します。

DECLARE
   retval VARCHAR2(50);
BEGIN
   retval := UTL_I18N.GET_DEFAULT_ISO_CURRENCY('CHINA');
   DBMS_OUTPUT.PUT_LINE(retval);
END;
/

268.4.5 GET_DEFAULT_LINGUISTIC_SORTファンクション

このファンクションは、指定した言語の最も一般的に使用されるOracle言語ソート名を戻します。

構文

UTL_I18N.GET_DEFAULT_LINGUISTIC_SORT (
   language  IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN VARCHAR2;

パラメータ

表268-6 GET_DEFAULT_LINGUISTIC_SORTファンクションのパラメータ

パラメータ	説明
`language`	有効なOracle言語を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な言語名を指定した場合、ファンクションはNULL文字列を戻します。

例

現行のSQLセッションで使用されている言語の最適な言語ソート名を表示します。

DECLARE
   retval VARCHAR2(50);
BEGIN
  SELECT value INTO retval FROM nls_database_parameters
   WHERE parameter = 'NLS_LANGUAGE';
   retval := UTL_I18N.GET_DEFAULT_LINGUISTIC_SORT(retval);
   DBMS_OUTPUT.PUT_LINE(retval);
END;
/

268.4.6 GET_LOCAL_LANGUAGESファンクション

このファンクションは、指定したテリトリのローカル言語名を戻します。

構文

UTL_I18N.GET_LOCAL_LANGUAGES (
   territory    IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN STRING_ARRAY;

パラメータ

表268-7 GET_LOCAL_LANGUAGESファンクションのパラメータ

パラメータ	説明
`territory`	有効なOracleテリトリを指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効なテリトリ名を指定した場合、ファンクションはNULL文字列を戻します。

例

ベルギーで使用されているローカル言語のリストを戻します。

DECLARE
   retval UTL_I18N.STRING_ARRAY;
   cnt    INTEGER;
BEGIN
   retval   :=  UTL_I18N.GET_LOCAL_LANGUAGES('BELGIUM');
   DBMS_OUTPUT.PUT('Count = ');
   DBMS_OUTPUT.PUT_LINE(retval.LAST);
   cnt := retval.FIRST;
   WHILE cnt IS NOT NULL LOOP
      DBMS_OUTPUT.PUT_LINE(retval(cnt));
      cnt := retval.NEXT(cnt);
   END LOOP;
END;
/
...
Count = 2
DUTCH
FRENCH

268.4.7 GET_LOCAL_LINGUISTIC_SORTSファンクション

このファンクションは、指定した言語に適したOracle言語ソート名のリストを戻します。BINARYソートはすべての言語に含まれています。

構文

UTL_I18N.GET_LOCAL_LINGUISTIC_SORTS (
   language  IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN STRING_ARRAY;

パラメータ

表268-8 GET_LOCAL_LINGUISTIC_SORTSファンクションのパラメータ

パラメータ	説明
`language`	有効なOracle言語を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な言語名を指定した場合、ファンクションはNULL文字列を戻します。

例

JAPANESEのローカル言語ソート名を表示します。

DECLARE
   retval UTL_I18N.STRING_ARRAY;
   cnt INTEGER;
BEGIN
  retval := UTL_I18N.GET_LOCAL_LINGUISTIC_SORTS('Japanese');
  DBMS_OUTPUT.PUT('Count = ');
  DBMS_OUTPUT.PUT_LINE(retval.COUNT);
  cnt := retval.FIRST;
   WHILE cnt IS NOT NULL LOOP
      DBMS_OUTPUT.PUT_LINE(retval(cnt));
      cnt := retval.NEXT(cnt);
    END LOOP;
END;
/

...
Count = 2
JAPANESE_M
BINARY

268.4.8 GET_LOCAL_TERRITORIESファンクション

このファンクションは、指定した言語のローカル・テリトリ名を戻します。

構文

UTL_I18N.GET_LOCAL_TERRITORIES (
   language  IN VARCHAR2 CHARACTER SET ANY_CS)
 RETURN STRING_ARRAY;

パラメータ

表268-9 GET_LOCAL_TERRITORIESファンクションのパラメータ

パラメータ	説明
`language`	有効なOracle言語を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な言語名を指定した場合、ファンクションはNULL文字列を戻します。

例

ローカル言語の1つとしてドイツ語を使用するOracleテリトリのリストを戻します。

DECLARE
   retval  UTL_I18N.STRING_ARRAY;
   cnt     INTEGER;
BEGIN
   retval  := UTL_I18N.GET_LCOAL_TERRITORIIES('GERMAN');
   DBMS_OUTPUT.PUT('Count = ');
   DBMS_OUTPUT.PUT_LINE(retval.LAST);
  cnt := retval.FIRST;
   WHILE cnt IS NOT NULL LOOP
      DBMS_OUTPUT.PUT_LINE(retval(cnt));
      cnt := retval.NEXT(cnt));
   END LOOP;
END;
/
...
Count = 4
GERMANY
AUSTRIA
LUXEMBOURG
SWITZERLAND

268.4.9 GET_LOCAL_TIME_ZONESファンクション

このファンクションは、指定したテリトリのローカル・タイムゾーンIDを戻します。

構文

UTL_I18N.GET_LOCAL_TIME_ZONES ( 
   territory      IN VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL)
RETURN STRING_ARRAY;

パラメータ

表268-10 GET_LOCAL_TIME_ZONESファンクションのパラメータ

パラメータ	説明
`territory`	有効なOracleテリトリを指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効なテリトリ名を指定した場合、ファンクションはNULL文字列を戻します。

例

テリトリAZERBAIJANでローカルに使用されているタイムゾーンのリストの後に一般的な共通タイムゾーンを戻すファンクションを作成します。このファンクションは、ユーザーのテリトリがわかっていて、アプリケーションでユーザーが他のタイムゾーンをユーザーのプリファレンスとして選択できる場合に有効です。

CREATE OR REPLACE FUNCTION get_time_zones
(territory IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN utl_i18n.string_array
IS
  retval  utl_i18n.string_array;
  retval2 utl_i18n.string_array;
  stpos   INTEGER;
BEGIN
  retval  := utl_i18n.get_local_time_zones(
    territory);
  retval2 := utl_i18n.get_common_time_zones;
  stpos := retval.LAST + 1;
  retval(stpos) := '-----'; -- a separator
  FOR i IN retval2.FIRST..retval2.LAST LOOP
    stpos := stpos + 1;
    retval(stpos) := retval2(i);
  END LOOP;
  RETURN retval;
END;
/

AZERBAIJANのローカル・タイムゾーンが戻され、続いてセパレータ文字列である5つのダッシュ(-----)の下に共通タイムゾーンが戻されます。

DECLARE
   retval UTL_I18N.STRING_ARRAY;
   cnt INTEGER;
BEGIN
   DBMS_OUTPUT.ENABLE(100000);
   retval UTL_I18N.GET_TIME_ZONES('AZERBAIJAN');
   cnt := retval.FIRST;
  WHILE cnt IS NOT NULL LOOP
    DBMS_OUTPUT.PUT_LINE(retval(cnt));
    cnt := retval.NEXT(cnt);
  END LOOP;
END;
/

Asia/Baku
-----
Pacific/Pago_Pago
Pacific/Honolulu
America/Anchorage
America/Vancouver
America/Los_Angeles
America/Tijuana
America/Edmonton
America/Denver
America/Phoenix
America/Mazatlan
America/Winnipeg
America/Regina
America/Chicago
America/Mexico_City
America/Guatemala
America/El_Salvador
America/Managua
America/Costa_Rica
America/Montreal
...

268.4.10 GET_MAX_CHARACTER_SIZEファンクション

このファンクションは、指定された文字セットの最大文字サイズを戻します。

構文

UTL_I18N.GET_MAX_CHARACTER_SIZE(
    charset_name       IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN PLS_INTEGER;

パラメータ

表268-11 GET_MAX_CHARACTER_SIZEファンクションのパラメータ

パラメータ	説明
`charset_name`	有効な文字セット名を指定します。大文字と小文字は区別されません。

使用上のノート

シフト・センシティブ文字セットの場合、戻される最大文字サイズには追加シフト文字が含まれることがあります。

例

UTL_I18N.GET_MAX_CHARACTER_SIZE('AL32UTF8');

これは4を戻します。

268.4.11 GET_TRANSLATIONファンクション

このファンクションは、指定した変換言語の言語およびテリトリ名の変換を戻します。

構文

UTL_I18N.GET_TRANSLATION ( 
   parameter        IN VARCHAR2 CHARACTER SET ANY_CS,
   trans_language   IN VARCHAR2 'AMERICAN',
   flag             IN PLS_INTEGER DEFAULT LANGUAGE_TRANS)
RETURN VARCHAR2 CHARACTER SET parameter%CHARSET;

パラメータ

表268-12 GET_TRANSLATIONファンクションのパラメータ

パラメータ説明

パラメータ	説明
`parameter`	有効な言語名、テリトリ名または`language_territory`の形式の組合せ文字列を指定します。大文字と小文字は区別されません。
`trans_language`	変換言語名を指定します。たとえば、イタリア語の場合は`ITALIAN`を指定します。デフォルトは、米語を示す`AMERICAN`です。
`flag`	変換タイプを指定します。 `LANGUAGE_TRANS`: このファンクションは言語変換を戻します。 `TERRITORY_TRANS`: このファンクションはテリトリ変換を戻します。 `LANGUAGE_TERRITORY_TRANS`: このファンクションは言語およびテリトリの変換を戻します。デフォルトの変換タイプは`LANGUAGE_TRANS`です。

parameter

有効な言語名、テリトリ名またはlanguage_territoryの形式の組合せ文字列を指定します。大文字と小文字は区別されません。

trans_language

変換言語名を指定します。たとえば、イタリア語の場合はITALIANを指定します。デフォルトは、米語を示すAMERICANです。

flag

変換タイプを指定します。

LANGUAGE_TRANS: このファンクションは言語変換を戻します。
TERRITORY_TRANS: このファンクションはテリトリ変換を戻します。
LANGUAGE_TERRITORY_TRANS: このファンクションは言語およびテリトリの変換を戻します。

デフォルトの変換タイプはLANGUAGE_TRANSです。

使用上のノート

パラメータのタイプとしてVARCHAR2を使用すると、データベース文字セットへの変換が原因で、戻される変換テキストが破損する場合があります。パラメータのタイプとしてNVARCHAR2を使用すると、Unicodeですべての変換言語をエンコードできるため、変換テキストが保持されます。

指定した変換言語を使用できないか、または無効な名前が指定されている場合は、デフォルトの米語変換が戻されます。たとえば、OracleではGUJARATI変換は提供されていないため、米語変換が戻されます。

例

次の例では、Oracleでサポートされているすべての言語の名前がイタリア語で戻されます。

DECLARE
   CURSOR c1 IS
     SELECT value FROM V$NLS_VALID_VALUES
     WHERE parameter = 'LANGUAGE'
  ORDER BY value;
  retval NVARCHAR2(100);
BEGIN
   FOR item IN c1 LOOP
     retval := UTL_I18N.GET_TRANSLATION (TO_NCHAR(item.value), 'italian');
   END LOOP;
END;

268.4.12 MAP_CHARSETファンクション

このファンクションは、文字セットを別の文字セットにマップします。

これは、次のマッピングを行います。

Oracleの文字セット名からIANAの文字セット名へのマッピング。
IANAの文字セット名からOracleの文字セット名へのマッピング。
Oracleの文字セット名から電子メールで安全な文字セット名へのマッピング。

構文

UTL_I18N.MAP_CHARSET( 
   charset   IN VARCHAR2,
   context   IN PLS_INTEGER DEFAULT GENERIC_CONTEXT,
   flag      IN PLS_INTEGER DEFAULT ORACLE_TO_IANA)
RETURN VARCHAR2;

パラメータ

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

パラメータ説明

パラメータ	説明
`charset`	マップする文字セット名を指定します。マッピングでは大文字と小文字は区別されません。
`context`	`GENERIC_CONTEXT \| MAIL_CONTEXT` `GENERIC_CONTEXT`: Oracleの文字セット名とIANA文字セット名の間でマッピングが行われます。これはデフォルト値です。 `MAIL_CONTEXT`: Oracleの文字セット名と電子メールで安全な文字セット名の間でマッピングが行われます。
`flag`	`ORACLE_TO_IANA \| IANA_TO_ORACLE`(`GENERIC_CONTEXT`を設定した場合) `ORACLE_TO_IANA`: Oracleの文字セット名からIANAの文字セット名にマップします。これはデフォルトです。 `IANA_TO_ORACLE`: IANAの文字セット名からOracleの文字セット名にマップします。 `MAIL_GENERIC \| MAIL_WINDOWS`(`MAIL_CONTEXT`を設定した場合) `MAIL_GENERIC`: Windows以外のプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。 `MAIL_WINDOWS`: Windowsのプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。

charset

マップする文字セット名を指定します。マッピングでは大文字と小文字は区別されません。

context

GENERIC_CONTEXT | MAIL_CONTEXT

GENERIC_CONTEXT: Oracleの文字セット名とIANA文字セット名の間でマッピングが行われます。これはデフォルト値です。

MAIL_CONTEXT: Oracleの文字セット名と電子メールで安全な文字セット名の間でマッピングが行われます。

flag

ORACLE_TO_IANA | IANA_TO_ORACLE(GENERIC_CONTEXTを設定した場合)

ORACLE_TO_IANA: Oracleの文字セット名からIANAの文字セット名にマップします。これはデフォルトです。

IANA_TO_ORACLE: IANAの文字セット名からOracleの文字セット名にマップします。
MAIL_GENERIC | MAIL_WINDOWS(MAIL_CONTEXTを設定した場合)

MAIL_GENERIC: Windows以外のプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。

MAIL_WINDOWS: Windowsのプラットフォーム上で、Oracleの文字セット名から電子メールで安全な文字セット名にマップします。

使用上のノート

電子メールで安全な文字セットとは、アプリケーションで電子メール・メッセージを送信するとき通常に使用されるOracleの文字セットのことです。通常、この文字セットは、データベース文字セットの内容を電子メールで安全な内容に変換するために使用されます。メール・ヘッダーに文字セット名を指定するには、MAP_CHARSETファンクションにORACLE_TO_IANAオプションを指定してコールすることによって取得される、対応するIANAの文字セット名を使用して、電子メールで安全な文字セット名を入力として指定する必要があります。

たとえば、対応するIANA名がDEC-MCSであるWE8DEC文字セットのメッセージ内容を認識できる電子メール・クライアントは存在しません。WE8DECが、MAIL_CONTEXTオプションを指定したMAP_CHARSETファンクションに渡されると、ファンクションはWE8ISO8859P1を戻します。これに対応するIANA名であるISO-8859-1は、ほとんどの電子メール・クライアントで認識されます。

この例のステップは次のとおりです。

データベース文字セット名WE8DECをMAIL_CONTEXT | MAIL_GENERICオプションに指定して、MAP_CHARSETファンクションをコールします。この結果WE8ISO8859P1が戻されます。
データベースに格納されている内容を、WE8ISO8859P1に変換します。
電子メールで安全な文字セットWE8ISO8859P1をORACLE_TO_IANA | GENERIC_CONTEXTオプションに指定して、MAP_CHARSETファンクションをコールします。この結果ISO-8859-1が戻されます。
電子メール・メッセージの送信時に、メール・ヘッダーにISO-8859-1を指定します。

一致するものが見つかると、ファンクションは文字セット名を戻します。一致するものが見つからないか、フラグが無効の場合、ファンクションはNULLを戻します。

ノート:

Oracleの文字セットの多くは、電子メールで安全な1つの文字セットに対してマップできます。電子メールで安全な文字セットをOracleの文字セット名にマップするファンクションはありません。

例

一般的なコンテキスト

UTL_I18N.MAP_CHARSET('iso-8859-1',UTL_I18N.GENERIC_CONTEXT,UTL_I18N.IANA_TO_ORACLE)

'WE8ISO8859P1'が戻されます。

コンテキスト

UTL_I18N.MAP_CHARSET('WE8DEC', utl_i18n.mail_context,  utl_i18n.mail_generic)

'WE8ISO8859P1'が戻されます。

参照:

有効なOracleの文字セットのリストは、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

268.4.13 MAP_FROM_SHORT_LANGUAGEファンクション

このファンクションは、Oracleの短縮言語名をOracleの言語名にマップします。

構文

UTL_I18N.MAP_FROM_SHORT_LANGUAGE (
   language           IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN VARCHAR2;

パラメータ

表268-14 MAP_FROM_SHORT_LANGUAGEファンクションのパラメータ

パラメータ	説明
`language`	有効な短縮言語名を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な言語名を指定した場合、ファンクションはNULL文字列を戻します。

例

IDが9000の顧客のデフォルトの言語ソート名を戻します。表customersは共通スキーマのoeユーザーから取得されます。顧客の言語プリファレンスは短縮言語名で格納されるため、GET_DEFAULT_LINGUISTIC_SORTプロシージャをコールして完全言語名に変換する必要があります。

DECLARE
   short_n VARCHAR2(10);
   ling_n VARCHAR2(50);
BEGIN
   SELECT nls_language INTO short 
   FROM customers WHERE customer_id = 9000;
   ling_n := UTL_I18N.GET_DEFAULT_LINGUISTIC_SORT (
   UTL_I18N.MAP_FROM_SHORT_LANGUAGE(short_n));
   DBMS_OUTPUT.PUT_LINE(ling_n);
END;
/

268.4.14 MAP_LANGUAGE_FROM_ISOファンクション

このファンクションは、ISOのロケール名からOracleの言語名を戻します。

構文

UTL_I18N.MAP_LANGUAGE_FROM_ISO( 
  isolocale IN VARCHAR2)
RETURN VARCHAR2;

パラメータ

表268-15 MAP_LANGUAGE_FROM_ISOファンクションのパラメータ

パラメータ	説明
`isolocale`	ISOのロケールを指定します。マッピングでは大文字と小文字は区別されません。

使用上のノート

ユーザーが無効なロケール文字列を指定した場合、ファンクションはNULL文字列を戻します。

ユーザーが言語のみを含むロケール文字列を指定した場合(たとえばen_USではなくen_)、ファンクションは指定した言語のデフォルトの言語名(Americanなど)を戻します。

例

UTL_I18N.MAP_LANGUAGE_FROM_ISO('en_US')

'American'が戻されます。

参照:

有効なOracleの言語のリストは、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

268.4.15 MAP_LOCALE_TO_ISOファンクション

このファンクションは、Oracleの言語名およびOracleのテリトリ名からISOのロケール名を戻します。

有効な文字列には、少なくとも有効なOracleの言語名または有効なOracleのテリトリ名のいずれかが指定されている必要があります。

構文

UTL_I18N.MAP_LOCALE_TO_ISO ( 
   ora_language   IN VARCHAR2,
   ora_territory  IN VARCHAR2)
 RETURN VARCHAR2;

パラメータ

表268-16 MAP_LOCALE_TO_ISOファンクションのパラメータ

パラメータ	説明
`ora_language`	Oracleの言語名を指定します。大文字と小文字は区別されません。
ora_territory	Oracleのテリトリ名を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な文字列を指定した場合、ファンクションはNULL文字列を戻します。

例

UTL_I18N.MAP_LOCALE_TO_ISO('American','America')

'en_US'が戻されます。

参照:

有効なOracleの言語およびテリトリのリストは、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

268.4.16 MAP_TERRITORY_FROM_ISOファンクション

このファンクションは、ISOのロケールからOracleのテリトリ名を戻します。

構文

UTL_I18N.MAP_TERRITORY_FROM_ISO (
  isolocale IN VARCHAR2)
 RETURN VARCHAR2;

パラメータ

表268-17 MAP_TERRITORY_FROM_ISOファンクションのパラメータ

パラメータ	説明
`isolocale`	ISOのロケールを指定します。マッピングでは大文字と小文字は区別されません。

使用上のノート

ユーザーが無効なロケール文字列を指定した場合、ファンクションはNULL文字列を戻します。

ユーザーがテリトリのみを含むロケール文字列を指定した場合(たとえば、fr_frではなく_fr)、ファンクションは指定したテリトリのデフォルトのテリトリ名(Franceなど)を戻します。

例

UTL_I18N.MAP_TERRITORY_FROM_ISO('en_US')

'America'が戻されます。

参照:

有効なOracleのテリトリのリストは、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

268.4.17 MAP_TO_SHORT_LANGUAGEファンクション

このファンクションは、Oracleの言語名をOracleの短縮言語名にマップします。

構文

UTL_I18N.MAP_TO_SHORT_LANGUAGE (
   language    IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN VARCHAR2;

パラメータ

表268-18 MAP_TO_SHORT_LANGUAGEファンクションのパラメータ

パラメータ	説明
`language`	有効な完全言語名を指定します。大文字と小文字は区別されません。

使用上のノート

ユーザーが無効な言語名を指定した場合、ファンクションはNULL文字列を戻します。

例

言語の短縮言語名を戻します。

DECLARE  retval VARCHAR2(100);BEGIN  retval := UTL_I18N.MAP_TO_SHORT_LANGUAGE('american');  DBMS_OUTPUT.PUT_LINE(retval);END;/US

268.4.18 RAW_TO_CHARファンクション

このファンクションは、有効なOracleの文字セットのRAWデータを、データベース文字セットのVARCHAR2文字列に変換します。

このファンクションはオーバーロードされています。機能の各種形式は、構文宣言の箇所に併記してあります。

構文

バッファ変換:

UTL_I18N.RAW_TO_CHAR(
   data          IN RAW,
   src_charset   IN VARCHAR2 DEFAULT NULL)
 RETURN VARCHAR2;

ピース単位の変換では、生データが1つずつ文字データに変換されます。

UTL_I18N.RAW_TO_CHAR (
   data            IN RAW,
   src_charset     IN VARCHAR2 DEFAULT NULL,
   scanned_length  OUT PLS_INTEGER,
   shift_status    IN OUT PLS_INTEGER)
RETURN VARCHAR2;

パラメータ

表268-19 RAW_TO_CHARファンクションのパラメータ

パラメータ	説明
`data`	`VARCHAR2`文字列に変換する`RAW`データを指定します。
`src_charset`	`RAW`データを導出した文字セットを指定します。src_charsetが`NULL`の場合は、データベース文字セットが使用されます。
`scanned_length`	スキャンするソース・データのバイト数を指定します。
`shift_status`	スキャン終了時のシフト状態を指定します。ピース単位の変換で初めてコールするときは、`SHIFT_IN`に設定する必要があります。ノート: ISO 2022文字セットでは、エンコード方法を示すためにシフト文字ではなくエスケープ・シーケンスが使用されます。`shift_status`は、次に行われるファンクション・コールのエスケープ・シーケンスで提供されるエンコード方法の情報を保持できません。そのため、入力の各単位がクローズされた文字列であることが保証されないかぎり、このファンクションを使用して、ピース単位の方法で生データからISO 2022文字を再構築することはできません。クローズされた文字列の最初と最後は、7ビットのエスケープ状態になります。

使用上のノート

ユーザーが無効な文字セット、NULLデータまたは長さが0のデータを指定すると、ファンクションはNULL文字列を戻します。

例

バッファ変換

UTL_I18N.RAW_TO_CHAR(hextoraw('616263646566C2AA'), 'utf8')

次の文字列がデータベース文字セットで戻されます。

'abcde'||chr(170)

ピース単位の変換

UTL_I18N.RAW_TO_CHAR(hextoraw('616263646566C2AA'),'utf8',shf,slen)

次の文字列がデータベース文字セットで戻されます。

'abcde'||chr(170)

さらに、shfがSHIFT_INに、slenが8に設定されます。

次の例では、インターネットからのデータを1つずつデータベース文字セットに変換します。

rvalue RAW(1050); 
  nvalue VARCHAR2(1024); 
  conversion_state  PLS_INTEGER = 0; 
  converted_len   PLS_INTEGER; 
  rtemp  RAW(10) = ''; 
  conn   utl_tcp.connection; 
  tlen PLS_INTEGER;

  ... 
  conn := utl_tcp.open_connection ( remote_host => 'localhost', 
                                    remote_port => 2000); 
  LOOP 
      tlen := utl_tcp.read_raw(conn, rvalue, 1024); 
      rvalue := utl_raw.concat(rtemp, rvalue); 
      nvalue := utl_i18n.raw_to_char(rvalue, 'JA16SJIS', converted_len, conversion_stat); 
      if (converted_len < utl_raw.length(rvalue) ) 
      then 
        rtemp := utl_raw.substr(rvalue, converted_len+1); 
      else 
        rtemp := ''; 
      end if; 
      /* do anything you want with nvalue */ 
      /* e.g htp.prn(nvalue); */ 
    END LOOP; 
    utl_tcp.close_connection(conn); 
  EXCEPTION 
    WHEN utl_tcp.end_of_input THEN 
      utl_tcp.close_connection(conn);
END;

268.4.19 RAW_TO_NCHARファンクション

このファンクションは、有効なOracleの文字セットのRAWデータを、各国語文字セットのNVARCHAR2文字列に変換します。

このファンクションはオーバーロードされています。機能の各種形式は、構文宣言の箇所に併記してあります。

構文

バッファ変換:

UTL_I18N.RAW_TO_NCHAR ( 
   data         IN RAW,
   src_charset  IN VARCHAR2 DEFAULT NULL)
 RETURN NVARCHAR2;

ピース単位の変換では、生データが1つずつ文字データに変換されます。

UTL_I18N.RAW_TO_NCHAR ( 
   data            IN RAW,
   src_charset      IN VARCHAR2 DEFAULT NULL,
   scanned_length   OUT PLS_INTEGER,
   shift_status     IN OUT PLS_INTEGER)
 RETURN NVARCHAR2;

パラメータ

表268-20 RAW_TO_NCHARファンクションのパラメータ

パラメータ	説明
`data`	`NVARCHAR2`文字列に変換する`RAW`データを指定します。
`src_charset`	`RAW`データを導出した文字セットを指定します。`src_charset`が`NULL`の場合は、データベース文字セットが使用されます。
`scanned_length`	スキャンするソース・データのバイト数を指定します。
`shift_status`	スキャン終了時のシフト状態を指定します。ピース単位の変換で初めてコールするときは、`SHIFT_IN`に設定する必要があります。ノート: ISO 2022文字セットでは、エンコード方法を示すためにシフト文字ではなくエスケープ・シーケンスが使用されます。`shift_status`は、次に行われるファンクション・コールのエスケープ・シーケンスで提供されるエンコード方法の情報を保持できません。そのため、入力の各単位がクローズされた文字列であることが保証されないかぎり、このファンクションを使用して、ピース単位の方法で生データからISO 2022文字を再構築することはできません。クローズされた文字列の最初と最後は、7ビットのエスケープ状態になります。

使用上のノート

ユーザーが無効な文字セット、NULLデータまたは長さが0のデータを指定すると、ファンクションはNULL文字列を戻します。

例

バッファ変換

UTL_I18N.RAW_TO_NCHAR(hextoraw('616263646566C2AA'),'utf8')

次の文字列が各国語文字セットで戻されます。

'abcde'||chr(170)

ピース単位の変換

UTL_I18N.RAW_TO_NCHAR(hextoraw('616263646566C2AA'),'utf8', shf, slen)

次の文字列が各国語文字セットで戻されます。

'abcde'||chr(170)

さらに、shfがSHIFT_INに、slenが8に設定されます。

次の例では、インターネットからのデータを1つずつ各国語文字セットに変換します。

rvalue RAW(1050); 
  nvalue NVARCHAR2(1024); 
  converstion_state  PLS_INTEGER = 0; 
  converted_len   PLS_INTEGER; 
  rtemp  RAW(10) = ''; 
  conn   utl_tcp.connection; 
  tlen PLS_INTEGER;

  ... 
  conn := utl_tcp.open_connection ( remote_host => 'localhost', 
                                    remote_port => 2000); 
  LOOP 
      tlen := utl_tcp.read_raw(conn, rvalue, 1024); 
      rvalue := utl_raw.concat(rtemp, rvalue); 
      nvalue := utl_i18n.raw_to_nchar(rvalue, 'JA16SJIS', converted_len, conversion_stat); 
      if (converted_len < utl_raw.length(rvalue) ) 
      then 
        rtemp := utl_raw.substr(rvalue, converted_len+1); 
      else 
        rtemp := ''; 
      end if; 
      /* do anything you want with nvalue */ 
      /* e.g htp.prn(nvalue); */ 
    END LOOP; 
    utl_tcp.close_connection(conn); 
  EXCEPTION 
    WHEN utl_tcp.end_of_input THEN 
      utl_tcp.close_connection(conn); 
  END;

268.4.20 STRING_TO_RAWファンクション

このファンクションは、VARCHAR2またはNVARCHAR2の文字列を別の有効なOracleの文字セットに変換し、その結果をRAWデータとして戻します。

構文

UTL_I18N.STRING_TO_RAW( 
   data          IN VARCHAR2 CHARACTER SET ANY_CS,
   dst_charset   IN VARCHAR2 DEFAULT NULL)
RETURN RAW;

パラメータ

表268-21 STRING_TO_RAWファンクションのパラメータ

パラメータ	説明
`data`	変換する`VARCHAR2`または`NVARCHAR2`の文字列を指定します。
`dst_charset`	宛先となる文字セットを指定します。`dst_charset`が`NULL`の場合は、データベース文字セットが`CHAR`データに使用され、各国語文字セットが`NCHAR`データに使用されます。

使用上のノート

ユーザーが無効な文字セット、NULL文字列または長さが0の文字列を指定すると、ファンクションはNULL文字列を戻します。

例

DECLARE 
    r raw(50); 
    s varchar2(20); 
  BEGIN 
    s:='abcdef'||chr(170); 
    r:=utl_i18n.string_to_raw(s,'utf8'); 
    dbms_output.put_line(rawtohex(r)); 
  end; 
/

16進数の値'616263646566C2AA'が戻されます。

268.4.21 TRANSLITERATEファンクション

このファンクションは、スクリプト変換を実行します。このリリースでは、TRANSLITERATEファンクションは日本語の仮名変換のみをサポートします。

構文

UTL_I18N.TRANSLITERATE (
  data IN VARCHAR2 CHARACTER SET ANY_CS,
  name IN VARCHAR2)
RETURN VARCHAR2 CHARACTER SET data%CHARSET;

パラメータ

表268-22 TRANSLITERATEファンクションのパラメータ

パラメータ	説明
`data`	変換するデータを指定します。`CHAR`または`NCHAR`のどちらかのデータ・タイプを指定できます。
`name`	変換名文字列を指定します。有効な名前のリストについては、表268-23を参照してください。

定数

次のオプションは、日本語の仮名変換を指定します。

表268-23 TRANSLITERATEファンクションの定数

定数名	値	説明
`KANA_FWKATAKANA`	`'kana_fwkatakana'`	すべてのタイプの仮名文字を全角カタカナに変換します。
`KANA_HWKATAKANA`	`'kana_hwkatakana'`	すべてのタイプの仮名文字を半角カタカナに変換します。
`KANA_HIRAGANA`	`'kana_hiragana'`	すべてのタイプの仮名文字を全角ひらがなに変換します。
`FWKATAKANA_HWKATAKANA`	`'fwkatakana_hwkatakana'`	全角カタカナのみを半角カタカナに変換します。
`FWKATAKANA_HIRAGANA`	`'fwkatakana_hiragana'`	全角カタカナのみを全角ひらがなに変換します。
`HWKATAKANA_FWKATAKANA`	`'hwkatakana_fwkatakana'`	半角カタカナのみを全角カタカナに変換します。
`HWKATAKANA_HIRAGANA`	`'hwkatakana_hiragana'`	半角カタカナのみを全角ひらがなに変換します。
`HIRAGANA_FWKATAKANA`	`'hiragana_fwkatakana'`	全角ひらがなのみを全角カタカナに変換します。
`HIRAGANA_HWKATAKANA`	`'hiragana_hwkatakana'`	全角ひらがなのみを半角カタカナに変換します。

使用上のノート

このファンクションは、変換された文字列を戻します。

例

NVARCHAR2列enameを含む表japanese_empの場合は、次の文を使用して、enameのすべての仮名の名前をひらがなに正規化することができます。

UPDATE japanese_emp
   SET ename = UTL_I18N.TRANSLITERATE (ename, 'kana_hiragana');

次の図に、出力例を示します。

図268-1 データベースへのロケール固有のデータのロード

「図268-1 データベースへのロケール固有のデータのロード」の説明

次の文は、1つの仮名の名前をひらがなに正規化します。

DECLARE
   Name  japanese_emp.ename%TYPE;
   Eno   CONSTANT  NUMBER(4) := 1;
BEGIN
   SELECT ename INTO name FROM japanese_emp WHERE enumber = eno;
   name := UTL_I18N.TRANSLITERATE(name, UTL_I18N.KANA_HIRAGANA);
   UPDATE japanese_emp SET ename = name WHERE enumber = eno;
EXCEPTION
   WHEN  UTL_I18N.UNSUPPORTED_TRANSLITERATION THEN
   DBMS_OUTPUT.PUT_LINE('transliteration not supported');
END;
/

268.4.22 UNESCAPE_REFERENCEファンクション

このファンクションは、文字参照を含む入力文字列から文字列を1つ戻します。それぞれの文字参照は、対応する文字の値にデコードされます。

参照:

エスケープ・シーケンスの詳細は、「ESCAPE_REFERENCEファンクション」を参照してください。

構文

UTL_I18N.UNESCAPE_REFERENCE ( 
   str IN VARCHAR2 CHARACTER SET ANY_CS)
 RETURN VARCHAR2 CHARACTER SET str%CHARSET;

パラメータ

表268-24 UNESCAPE_REFERENCEファンクションのパラメータ

パラメータ	説明
`str`	入力文字列を指定します。

使用上のノート

ユーザーがNULL文字列または長さが0の文字列を指定すると、ファンクションはNULL文字列を戻します。ファンクションが失敗すると、元の文字列が戻されます。

例

UTL_I18N.UNESCAPE_REFERENCE('hello &lt; &#xe5;')

'hello <'||chr(229)が戻されます。

268.4.23 VALIDATE_CHARACTER_ENCODINGファンクション

このファンクションは、VARCHAR2、NVARCHAR2、CLOBおよびNCLOBデータの文字エンコードを検証します。検証は、VARCHAR2およびCLOBデータのデータベース文字セットとNVARCHAR2およびNCLOBデータの各国語文字セットに基づきます。

AL32UTF8、AL16UTF16、AL16UTF16LE、UTF8、UTFEなどのUnicode文字セットの場合、次のUnicodeコード・ポイントにマップされたバイト・シーケンスは無効とみなされます。

ペアになっていないサロゲート・コード・ポイント
文字以外のコード・ポイント

さらに、不規則または不正なUTF-8バイト・シーケンスはAL32UTF8およびUTF8文字セットに対して無効であるとみなされます。

VALIDATE_CHARACTER_ENCODINGファンクションはオーバーロードされています。1つはVARCHAR2およびNVARCHAR2データを検証するためのファンクションで、もう1つはCLOBおよびNCLOBデータを検証するためのファンクションです。

VARCHAR2およびNVARCHAR2データの検証

文字セットで定義された文字にマップされない場合、VARCHAR2バイトまたはNVARCHAR2バイトまたはそのバイト・シーケンスは、その文字セットに対して無効とみなされます。
CLOBおよびNCLOBデータの検証

LOBキャラクタのエンコーディングに対応するバイト(シングルバイト・データベース文字セットの場合)またはバイト・ペア(マルチバイト・データベース文字セットで使用されるUTF-16エンコーディングの場合)が文字セットで定義された文字にマップされない場合、LOBキャラクタはその文字セットに対して無効であるとみなされます。

構文

このファンクションはVARCHAR2およびNVARCHAR2データを検証します。

UTL_I18N.VALIDATE_CHARACTER_ENCODING (
   data IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN PLS_INTEGER;

このファンクションはCLOBおよびNCLOBデータを検証します。

UTL_I18N.VALIDATE_CHARACTER_ENCODING (
   lob_loc IN CLOB CHARACTER SET ANY_CS)
RETURN PLS_INTEGER;

パラメータ

表268-25 VALIDATE_CHARACTER_ENCODINGファンクションのパラメータ

パラメータ	説明
`data`	検証するVARCHAR2またはNVARCHAR2データ。
`lob_loc`	検証するCLOBまたはNCLOBデータ。

使用上のノート

このファンクションは、VARCHAR2データまたはNVARCHAR2データの最初の無効なバイトのオフセットを戻します。これは、CLOBデータまたはNCLOBデータの最初の無効な文字のオフセットを戻します。文字データのすべてのバイトが有効な場合、0を戻します。パラメータdataまたはlob_locの値がNULLの場合、NULLを戻します。

例

この例では、データベース文字セットがAL32UTF8であり、各国語文字セットがAL16UTF16であるNVARCHAR2およびCLOBデータの文字エンコーディングを検証します。

CREATE TABLE temp(col1 NVARCHAR2(20), col2 CLOB);
INSERT INTO temp VALUES(UNISTR('foo\D800bar'), UNISTR('foo\D800bar'));
COMMIT;
SELECT UTL_I18N.VALIDATE_CHARACTER_ENCODING(col1) invalid_offset_column1,
       UTL_I18N.VALIDATE_CHARACTER_ENCODING(col2) invalid_offset_column2
FROM temp;

問合せは次を戻します。

INVALID_OFFSET_COLUMN1 INVALID_OFFSET_COLUMN2
---------------------- ----------------------
                     7                      4

ここでは、サロゲート・コード・ポイントU+D800は無効です。col1の場合、‘foo’がNVARCHAR2で6バイトでエンコーディングされ、無効なコード・ポイントU+D800がオフセット7で開始されるため、数値7はINVALID_OFFSET_COLUMN1として戻されます。col2の場合、'foo'がCLOBで3 UTF-16コード・ポイントでエンコーディングされ、無効なコード・ポイントU+D800がオフセット4で開始されるため、数値4はINVALID_OFFSET_COLUMN2として戻されます。