diff --git a/CN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc new file mode 100644 index 00000000..58033a5b --- /dev/null +++ b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc @@ -0,0 +1,7 @@ += UTL_RAW 实现 + +`contrib/ivorysql_ora/src/builtin_packages/utl_raw` 下的 `utl_raw--1.0.sql` 定义了包规格和包体。`CAST_TO_RAW` 将输入转换为 `text`,再调用 `pg_catalog.convert_to`,目标编码由 `pg_catalog.getdatabaseencoding()` 提供。 + +包规格声明了用于二进制数值转换的 `BIG_ENDIAN`(`1`)、`LITTLE_ENDIAN`(`2`)和 `MACHINE_ENDIAN`(`3`)。当前 `CAST_TO_RAW` 只接受一个参数,会按原顺序复制文本编码后的字节。 + +`contrib/ivorysql_ora/sql/utl_raw.sql` 回归测试覆盖了 ASCII、多字节字符、空值和 LATIN1 输入。参见 xref:master/oracle_compatibility/compat_utl_raw.adoc[UTL_RAW 用法]。 diff --git a/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc new file mode 100644 index 00000000..2a0e7d10 --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc @@ -0,0 +1,15 @@ += UTL_RAW 包 + +在 Oracle 模式下,`UTL_RAW.CAST_TO_RAW(c IN VARCHAR2) RETURN RAW` 返回参数 `c` 按数据库编码存储的字节。跨库比较字节值前,先用 `SHOW server_encoding;` 确认编码。 + +[source,sql] +---- +SELECT RAWTOHEX(UTL_RAW.CAST_TO_RAW('ABC')) AS ascii_hex, + RAWTOHEX(UTL_RAW.CAST_TO_RAW('你好')) AS utf8_hex, + UTL_RAW.CAST_TO_RAW(NULL) IS NULL AS null_preserved +FROM dual; +---- + +在 UTF-8 数据库中,结果依次为 `414243`、`E4BDA0E5A5BD` 和 `t`。`CAST_TO_RAW` 的返回类型是 `RAW`,`RAWTOHEX` 将其中的字节显示为十六进制数字。如果输入本身是十六进制字符串,请用 `HEXTORAW` 解码。例如,`UTL_RAW.CAST_TO_RAW('41')` 包含 `34` 和 `31` 两个字节。 + +参见 xref:master/compatibility_features_design/utl_raw_impl.adoc[UTL_RAW 实现]。 diff --git a/EN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc new file mode 100644 index 00000000..bbb0e01a --- /dev/null +++ b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_raw_impl.adoc @@ -0,0 +1,7 @@ += UTL_RAW implementation + +The `utl_raw--1.0.sql` file under `contrib/ivorysql_ora/src/builtin_packages/utl_raw` defines the package specification and body. `CAST_TO_RAW` casts the input to `text` and calls `pg_catalog.convert_to` with the encoding returned by `pg_catalog.getdatabaseencoding()`. + +The package specification declares `BIG_ENDIAN` (`1`), `LITTLE_ENDIAN` (`2`), and `MACHINE_ENDIAN` (`3`) for binary number conversions. The current `CAST_TO_RAW` signature accepts a single argument and copies the encoded text bytes in order. + +The `contrib/ivorysql_ora/sql/utl_raw.sql` regression test covers ASCII, multibyte, null, and LATIN1 inputs. See xref:master/oracle_compatibility/compat_utl_raw.adoc[UTL_RAW usage]. diff --git a/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc new file mode 100644 index 00000000..5692af04 --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_raw.adoc @@ -0,0 +1,15 @@ += UTL_RAW package + +In Oracle mode, `UTL_RAW.CAST_TO_RAW(c IN VARCHAR2) RETURN RAW` returns the bytes of `c` in the database encoding. Check that encoding with `SHOW server_encoding;` before comparing byte values across databases. + +[source,sql] +---- +SELECT RAWTOHEX(UTL_RAW.CAST_TO_RAW('ABC')) AS ascii_hex, + RAWTOHEX(UTL_RAW.CAST_TO_RAW('你好')) AS utf8_hex, + UTL_RAW.CAST_TO_RAW(NULL) IS NULL AS null_preserved +FROM dual; +---- + +In a UTF-8 database, the results are `414243`, `E4BDA0E5A5BD`, and `t`. The result of `CAST_TO_RAW` itself is a `RAW` value. `RAWTOHEX` displays its bytes as hexadecimal digits. To decode a string that already represents hexadecimal bytes, use `HEXTORAW`. For example, `UTL_RAW.CAST_TO_RAW('41')` contains two bytes, `34` and `31`. + +See xref:master/compatibility_features_design/utl_raw_impl.adoc[UTL_RAW implementation].