UTL_I18N is a group of services that consist of the ESCAPE_REFERENCE and UNESCAPE_REFERENCE functions. It can provide additional globalization features for applications written in PL/SQL.
Subprograms
Subprogram | Description |
ESCAPE_REFERENCE Function | Converts a text string to character reference replicas different from the character set that is used in the current document. |
UNESCAPE_REFERENCE Function | Converts an input string that contains character references to a text string. |
STRING_TO_RAW Function | Converts a VARCHAR2 or NVARCHAR2 string to another character set. This function returns results as RAW data. |
RAW_TO_CHAR Function | Converts RAW data that is not encoded in the database character set to a VARCHAR2 string. |
ESCAPE_REFERENCE
This function converts a text string to character reference replicas different from the character set that is used in the current document. Character references are used in HTML and XML documents to represent characters in a method that is independent of the encoding of the document. Character references can appear in two forms: numeric character references and character entity references. The following character sets are supported:
SQL_ASCII | UTF8 | EUC_CN |
GB18030 | ISO_8859_5 | LATIN1 |
Syntax
UTL_I18N.ESCAPE_REFERENCE(
str IN VARCHAR2 CHARACTER SET ANY_CS,
page_cs_name IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2 CHARACTER SET str%CHARSET;
Parameters
Parameter | Description |
str | The string that needs to be escaped. |
page_cs_name | The character set of the document. |
Return values
Return value | Description |
VARCHAR2 | The escaped result in the string format. |
Example
-- ESCAPE_REFERENCE
SELECT UTL_I18N.ESCAPE_REFERENCE('hello < '||chr(229),'sql_ascii') FROM dual;
escape_reference
-------------------
hello < å
(1 row)UNESCAPE_REFERENCE
This function returns a string for an input string that contains character references. This function is used to decode each character reference into the corresponding character value.
Syntax
UTL_I18N.UNESCAPE_REFERENCE (
str IN VARCHAR2 CHARACTER SET ANY_CS)
RETURN VARCHAR2 CHARACTER SET str%CHARSET;Parameters
Parameter | Description |
str | The string that needs to be unescaped. |
Return values
Return value | Description |
VARCHAR2 | The unescaped result in the string format. |
Example
-- UNESCAPE_REFERENCE
SELECT UTL_I18N.UNESCAPE_REFERENCE('hello < å') FROM dual;
unescape_reference
--------------------
hello < å
(1 row)STRING_TO_RAW
This function is used to convert a VARCHAR2 or NVARCHAR2 string to another character set and return the result as RAW data.
Syntax
UTL_I18N.STRING_TO_RAW(
data IN VARCHAR2 CHARACTER SET ANY_CS,
dst_charset IN VARCHAR2 DEFAULT NULL)
RETURN RAW;Parameters
Parameter | Description |
data | The VARCHAR2 or NVARCHAR2 string that you want to convert. |
dst_charset | The destination character set. |
Return values
Return value | Description |
RAW | RAW data that indicates the string to be converted in the destination character set. |
Example
The following example shows how to convert VARCHAR2 data into RAW data:
SELECT utl_i18n.string_to_raw('abcdef', 'utf8') FROM dual;
string_to_raw
----------------
\x616263646566
(1 row)RAW_TO_CHAR
This function is used to convert RAW data that is not encoded in the database character set into a VARCHAR2 string.
Syntax
UTL_I18N.RAW_TO_CHAR(
data IN RAW,
src_charset IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;Parameters
Parameter | Description |
data | RAW data that you want to convert. |
src_charset | (Optional) The character set that is used to export RAW data. |
Return values
Return value | Description |
VARCHAR2 | The VARCHAR2 string converted from RAW data that is not encoded in the database character set. |
Example
The following example shows how to convert RAW data that is not encoded in a database character set to a VARCHAR2 string:
SELECT utl_i18n.string_to_raw('ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'UTF8') FROM dual;
string_to_raw
--------------------------------------------------------
\x4142434445464748494a4b4c4d4e4f505152535455565758595a
(1 row)