From f07f4674f996d0e86ff1e1cf6cfa7157a1a70dcf Mon Sep 17 00:00:00 2001 From: Steven Niu Date: Wed, 15 Apr 2026 09:05:00 +0000 Subject: [PATCH] RAWTOHEX function implementation --- CN/modules/ROOT/nav.adoc | 1 + .../oracle_builtin_functions/rawtohex.adoc | 55 ++++++++++++++++++ EN/modules/ROOT/nav.adoc | 1 + .../oracle_builtin_functions/rawtohex.adoc | 57 +++++++++++++++++++ 4 files changed, 114 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc create mode 100644 EN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 73f872ed..50611c55 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -93,6 +93,7 @@ *** 内置函数 **** xref:master/oracle_builtin_functions/sys_context.adoc[sys_context] **** xref:master/oracle_builtin_functions/userenv.adoc[userenv] +**** xref:master/oracle_builtin_functions/rawtohex.adoc[rawtohex] *** xref:master/gb18030.adoc[国标GB18030] * 参考指南 ** xref:master/tools_reference.adoc[工具参考] diff --git a/CN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc b/CN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc new file mode 100644 index 00000000..dec604ea --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc @@ -0,0 +1,55 @@ + +:sectnums: +:sectnumlevels: 5 + + += **功能概述** + +IvorySQL提供兼容Oracle内置函数 ```RAWTOHEX('parameter')``` ，用于将RAW类型转换成十六进制字符串。 + +== 实现原理 + +PostgreSQL 提供的pg_catalog.encode(bytea, 'hex')函数，可直接完成二进制到十六进制的转换。 +考虑到当前系统中已经存在的HEXTORAW函数通过封装pg_catalog.decode 的SQL方式实现，本次开发的 +RAWTOHEX 函数将使用相同的方式来实现，即使用 SQL 函数包装 PostgreSQL 内置函数pg_catalog.encode， +而非编写 C 扩展。 + +raw、text、bytea以及varchar2这四种类型做为输入需要被支持。 +sys.raw 是 bytea 的 domain 类型（typtype = 'd'，typbasetype = bytea），PostgreSQL 支持 domain 到 base type 的隐式转换，RAWTOHEX(bytea) 可自动接受 sys.raw 输入。 +sys.oravarcharchar（即 varchar2）到 pg_catalog.text 存在 IMPLICIT cast（datatype--1.0.sql），RAWTOHEX(text) 可自动接受 varchar2 输入。 +因此，定义两个重载（而不是四个）。 + +``` +sys.rawtohex(bytea) RETURNS varchar2 +sys.rawtohex(text) RETURNS varchar2 +``` + +具体功能则是在 `builtin_functions--1.0.sql` 中实现。 +```sql +/* support rawtohex function for oracle compatibility */ +CREATE OR REPLACE FUNCTION sys.rawtohex(bytea) +RETURNS varchar2 +AS $$ SELECT CASE WHEN pg_catalog.octet_length($1) > 0 THEN upper(pg_catalog.encode($1, 'hex'))::varchar2 END; $$ +LANGUAGE SQL +PARALLEL SAFE +STRICT +IMMUTABLE; + +CREATE OR REPLACE FUNCTION sys.rawtohex(text) +RETURNS varchar2 +AS $$ SELECT CASE WHEN pg_catalog.octet_length($1) > 0 THEN upper(pg_catalog.encode($1::bytea, 'hex'))::varchar2 END; $$ +LANGUAGE SQL +PARALLEL SAFE +STRICT +IMMUTABLE; +``` + +== RAWTOHEX 典型用例 +[cols="8,2"] +|==== +|*用例语句*|*返回值* +|SELECT sys.rawtohex('\xDEADBEEF'::bytea); | DEADBEEF +|SELECT sys.rawtohex('\xFF'::raw); | FF +|SELECT sys.rawtohex('hello'::text); | 68656C6C6F +|SELECT sys.rawtohex('hello'::varchar2); | 68656C6C6F +|==== diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 6444f5f4..6379a08d 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -93,6 +93,7 @@ ** Built-in Functions *** xref:master/oracle_builtin_functions/sys_context.adoc[sys_context] *** xref:master/oracle_builtin_functions/userenv.adoc[userenv] +*** xref:master/oracle_builtin_functions/rawtohex.adoc[rawtohex] ** xref:master/gb18030.adoc[GB18030 Character Set] * Reference ** xref:master/tools_reference.adoc[Tool Reference] diff --git a/EN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc b/EN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc new file mode 100644 index 00000000..013eed79 --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_builtin_functions/rawtohex.adoc @@ -0,0 +1,57 @@ + +:sectnums: +:sectnumlevels: 5 + + += **Feature Overview** + +IvorySQL provides compatibility with Oracle's built-in function ```RAWTOHEX('parameter')```, which is used to convert RAW to a character value containing its hexadecimal representation. + +== Implementation Principle + +The function pg_catalog.encode(bytea, 'hex') provided by PostgreSQL can directly convert binary data to hexadecimal. + +Given that the existing HEXTORAW function in the current system is implemented by wrapping pg_catalog.decode using SQL, the RAWTOHEX function developed this time will be implemented in the same way. That is, it will be a SQL function wrapping the PostgreSQL built-in function pg_catalog.encode, rather than implementing it via a C extension. + +The following four types need to be supported as input: raw, text, bytea, and varchar2. + +sys.raw is a domain type of bytea (typtype = 'd', typbasetype = bytea). PostgreSQL supports implicit conversion from a domain type to its base type, so RAWTOHEX(bytea) can automatically accept sys.raw as input. + +There is an IMPLICIT cast from sys.oravarcharchar (i.e., varchar2) to pg_catalog.text (defined in datatype--1.0.sql), so RAWTOHEX(text) can automatically accept varchar2 as input. + +Therefore, two overloaded versions (rather than four) will be defined. + +``` +sys.rawtohex(bytea) RETURNS varchar2 +sys.rawtohex(text) RETURNS varchar2 +``` + +The specific functionality is implemented in builtin_functions—1.0.sql. +```sql +/* support rawtohex function for oracle compatibility */ +CREATE OR REPLACE FUNCTION sys.rawtohex(bytea) +RETURNS varchar2 +AS $$ SELECT CASE WHEN pg_catalog.octet_length($1) > 0 THEN upper(pg_catalog.encode($1, 'hex'))::varchar2 END; $$ +LANGUAGE SQL +PARALLEL SAFE +STRICT +IMMUTABLE; + +CREATE OR REPLACE FUNCTION sys.rawtohex(text) +RETURNS varchar2 +AS $$ SELECT CASE WHEN pg_catalog.octet_length($1) > 0 THEN upper(pg_catalog.encode($1::bytea, 'hex'))::varchar2 END; $$ +LANGUAGE SQL +PARALLEL SAFE +STRICT +IMMUTABLE; +``` + +== RAWTOHEX use cases +[cols="8,2"] +|==== +|*SQL statement *|*return value* +|SELECT sys.rawtohex('\xDEADBEEF'::bytea); | DEADBEEF +|SELECT sys.rawtohex('\xFF'::raw); | FF +|SELECT sys.rawtohex('hello'::text); | 68656C6C6F +|SELECT sys.rawtohex('hello'::varchar2); | 68656C6C6F +|====