UTL_RAW系统包

📄字数 12.2K

👁️阅读量 加载中...

一、概述

UTL_RAW系统包是一个专门用于操作RAW（二进制）类型数据的工具包。它支持位运算、数据转换、字符编码处理、子串提取、字节比较等操作，适用于对底层二进制数据进行精细处理的各种场景。

在该系统包中提供了以下接口：

包体函数名	简要描述
BIT_AND	位运算，按字节做AND运算
BIT_COMPLEMENT	位运算，按字节对RAW做取反运算
BIT_OR	位运算，按字节做OR运算
BIT_XOR	位运算，按字节做XOR运算
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	数据转换，把RAW转换成BINARY_DOUBLE
CAST_TO_BINARY_FLOAT	数据转换，把RAW转换成BINARY_FLOAT
CAST_TO_BINARY_INTEGER	数据转换，把RAW转换成BINARY_INTEGER
CAST_TO_NUMBER	数据转换，把RAW转换成NUMBER
CAST_TO_NVARCHAR2	数据转换，把RAW转换成NVARCHAR2
CAST_TO_RAW	数据转换，把NVARCHAR2转换成RAW
CAST_TO_VARCHAR2	数据转换，把RAW转换成VARCHAR2
COMPARE	按字节比较两个 RAW
CONCAT	拼接两个RAW值
CONVERT	RAW数据字符集转换
COPIES	复制RAW数据
LENGTH	获取RAW的长度
OVERLAY	覆盖RAW数据
REVERSE	按字节反转RAW数据
SUBSTR	截取RAW的子串
TRANSLATE	根据给定的映射关系，替换RAW数据中的指定字节
TRANSLITERATE	根据给定的映射关系，替换RAW数据中的指定字节
XRANGE	构造一个指定起始值、结束值的连续字节序列

典型应用场景，如：

• 加密/解密数据配合DBMS_CRYPTO等包对数据进行加密传输
• 在RAW与常见数据类型（如数字、浮点、字符串）之间转换
• 底层数据分析。比较、分割、合并、替换二进制字段中的内容
• 网络通信编码时，对字符串、数字转换为符合传输协议格式的RAW
• 数据校验。校验数据包内容或字段是否一致

二、BIT_AND

2.1 功能描述

该接口用于对两个RAW数据进行按位与（&）操作

2.2 方法声明

FUNCTION BIT_AND (
    r1      IN RAW, 
    r2      IN RAW
    ) RETURN RAW;

2.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	否	RAW数据
r2	RAW	无	否	RAW数据

2.4 示例

-- 将十六进制的0与1转换为RAW，进行按位与运算
SQL> SELECT RAWTOHEX(UTL_RAW.BIT_AND(HEXTORAW('0'),HEXTORAW('1'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 00    |
+-------+

2.5 应用场景

• 场景一：从原始字节数据中，提取指定的位字段

三、BIT_COMPLEMENT

3.1 功能描述

该接口用于对RAW数据进行按位取反（~）操作

3.2 方法声明

FUNCTION BIT_COMPLEMENT (
    r1      IN RAW,
    r2      IN RAW
    ) RETURN RAW

3.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	否	RAW数据
r2	RAW	无	否	RAW数据（暂无无实际意义）

3.4 示例

-- 使用BIT_COMPLEMENT取反
SQL> SELECT RAWTOHEX(UTL_RAW.BIT_COMPLEMENT(HEXTORAW('3111'),HEXTORAW('7111'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| CEEE  |
+-------+

3.5 应用场景

• 场景一：在某些系统中，正向值代表某种行为，取反后表示‘非此行为’；可以通过BIT_COMPLEMENT，排查具有哪些行为

四、BIT_OR

4.1 功能描述

该接口用于对两个RAW数据进行按位或（|）操作

4.2 方法声明

FUNCTION BIT_OR (
    r1      IN RAW, 
    r2      IN RAW
    ) RETURN RAW;

4.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	否	RAW数据
r2	RAW	无	否	RAW数据

4.4 示例

-- 31与30的或运算
SQL> SELECT RAWTOHEX(UTL_RAW.BIT_OR(HEXTORAW('31'),HEXTORAW('30'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 31    |
+-------+

4.5 应用场景

• 场景一：将多个功能/权限标志合并成一个权限字段，例如用户权限、访问控制

五、BIT_XOR

5.1 功能描述

该接口用于对两个RAW数据进行按位异或（^）操作

5.2 方法声明

FUNCTION BIT_XOR (
    r1      IN RAW, 
    r2      IN RAW
    ) RETURN RAW;

5.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	否	RAW数据
r2	RAW	无	否	RAW数据

5.4 示例

-- 310与300的异或运算
SQL> SELECT RAWTOHEX(UTL_RAW.BIT_XOR(HEXTORAW('310'),HEXTORAW('300'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 0010  |
+-------+

5.5 应用场景

• 场景一：验证数据一致性或同步。根据异或值是否为0，可判断两个RAW内容是否一致
• 场景二：日志解析。某些日志以加密或变形的RAW格式存储，XOR是常用的轻量加密/混淆方法

六、CAST_FROM_BINARY_DOUBLE

6.1 功能描述

该接口用于返回一个BINARY_DOUBLE数据的原始二进制表示

6.2 方法声明

FUNCTION CAST_FROM_BINARY_DOUBLE (
    n           IN BINARY_DOUBLE, 
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN RAW;

6.3 参数说明

参数名	类型	取值范围	是否可选	描述
n	BINARY_DOUBLE	无	否	双精度浮点数据，对应DOUBLE
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

6.4 示例

-- 将binary_double转换为raw类型
SQL> SELECT RAWTOHEX(UTL_RAW.CAST_FROM_BINARY_DOUBLE(CAST(3.14 AS BINARY_DOUBLE))) FROM DUAL;

+------------------+
|      EXPR1       |
+------------------+
| 40091EB851EB851F |
+------------------+

6.5 应用场景

• 场景一：进行底层调试或二进制数据对比
• 场景二：在网络传输或持久化存储时节省空间
• 场景三：与其他系统交互时需要精确控制二进制格式

七、CAST_FROM_BINARY_FLOAT

7.1 功能描述

该接口用于返回一个BINARY_FLOAT数据的原始二进制表示

7.2 方法声明

FUNCTION CAST_FROM_CAST_FROM_BINARY_FLOAT (
    n           IN BINARY_FLOAT, 
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN RAW;

7.3 参数说明

参数名	类型	取值范围	是否可选	描述
n	BINARY_FLOAT	无	否	单精度浮点数据，对应FLOAT
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

7.4 示例

-- 将BINARY_FLOAT转换为raw类型
SQL> SELECT RAWTOHEX(UTL_RAW.CAST_FROM_BINARY_FLOAT(CAST(3.14 AS BINARY_FLOAT))) FROM DUAL;

+----------+
|  EXPR1   |
+----------+
| 4048F5C3 |
+----------+

7.5 应用场景

• 场景一：进行底层调试或二进制数据对比
• 场景二：在网络传输或持久化存储时节省空间
• 场景三：与其他系统交互时需要精确控制二进制格式

八、CAST_FROM_BINARY_INTEGER

8.1 功能描述

该接口用于返回一个BINARY_INTEGER数据的原始二进制表示

8.2 方法声明

FUNCTION CAST_FROM_CAST_FROM_BINARY_INTEGER (
    n           IN BINARY_INTEGER, 
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN RAW;

8.3 参数说明

参数名	类型	取值范围	是否可选	描述
n	BINARY_INTEGER	无	否	整数类型，对应INTEGER
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

8.4 示例

-- 将binary_integer转换为raw类型
SQL> SELECT RAWTOHEX(UTL_RAW.CAST_FROM_BINARY_INTEGER(CAST(3 AS BINARY_INTEGER))) FROM DUAL;

+----------+
|  EXPR1   |
+----------+
| 00000003 |
+----------+

8.5 应用场景

• 场景一：跨平台二进制兼容检查。不同平台浮点表示可能有字节序差异，运维可比对RAW表示是否一致
• 场景二：数据库导入导出一致性验证。在使用BINARY类型字段时，导出后比对RAW值以验证浮点数据是否被破坏

九、CAST_FROM_NUMBER

9.1 功能描述

该接口用于返回一个NUMBER数据的原始二进制表示

9.2 方法声明

FUNCTION CAST_FROM_NUMBER (
    n       IN NUMBER
    ) RETURN RAW;

9.3 参数说明

参数名	类型	取值范围	是否可选	描述
n	NUMBER	无	否	NUMBER数据

9.4 示例

-- 将number转换为raw类型
SQL> SELECT RAWTOHEX(UTL_RAW.CAST_FROM_NUMBER(CAST(3 AS NUMBER))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 0003  |
+-------+

9.5 应用场景

• 场景一：跨版本/跨平台兼容性验证。对比相同NUMBER值在不同版本/平台中的底层编码是否一致
• 场景二：数据一致性校验。将NUMBER值转换为RAW，用于比对导出前后的二进制结果，验证传输或同步准确性

十、CAST_TO_BINARY_DOUBLE

10.1 功能描述

该接口用于将一个BINARY_DOUBLE值的原始二进制表示（RAW 类型）转换回一个BINARY_DOUBLE值

10.2 方法声明

FUNCTION CAST_TO_BINARY_DOUBLE (
    r           IN RAW,
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN BINARY_DOUBLE;

10.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	二进制数据
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

10.4 示例

-- 将十六进制原始字节'40091EB850000000'转换为BINARY_DOUBL类型的数值
SQL> SELECT UTL_RAW.CAST_TO_BINARY_DOUBLE(HEXTORAW('40091EB850000000')) FROM DUAL;

+--------------+
|    EXPR1     |
+--------------+
| 3.140000e+00 |
+--------------+

10.5 应用场景

• 场景一：跨平台数据验证
• 场景二：系统监控日志解析。某些系统日志只会记录二进制表示，需转换为可读浮点值以便追踪异常或分析趋势

十一、CAST_TO_BINARY_FLOAT

11.1 功能描述

该接口用于将一个BINARY_FLOAT值的原始二进制表示（RAW 类型）转换回一个BINARY_FLOAT值

11.2 方法声明

FUNCTION CAST_TO_BINARY_FLOAT (
    r           IN RAW,
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN BINARY_FLOAT;

11.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	二进制数据
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

11.4 示例

-- 将十六进制原始字节'4048F5C3'转换为BINARY_FLOAT类型的数值
SQL> SELECT UTL_RAW.CAST_TO_BINARY_FLOAT(HEXTORAW('4048F5C3')) FROM DUAL;

+--------------+
|    EXPR1     |
+--------------+
| 3.140000e+00 |
+--------------+

11.5 应用场景

• 场景一：跨平台/跨库验证浮点数一致性。检查两个系统之间传输或备份的浮点数是否内容一致
• 场景二：日志中存储了RAW字节流，可用此函数转为可读浮点数进行排查

十二、CAST_TO_BINARY_INTEGER

12.1 功能描述

该接口用于将一个BINARY_INTEGER值的原始二进制表示（RAW 类型）转换回一个BINARY_INTEGER值

12.2 方法声明

FUNCTION CAST_TO_BINARY_INTEGER (
    r           IN RAW,
    endianess   IN BINARY_INTEGER DEFAULT 1
    ) RETURN BINARY_INTEGER ;

12.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	二进制数据
endianess	BINARY_INTEGER	1/2/3	是，默认为1	数据在内存中的排列顺序（字节序），1表示大端，2表示小端，3表示跟随主机

12.4 示例

-- 将十六进制原始字节'00000003'转换为BINARY_INTEGER类型的数值
SQL> SELECT UTL_RAW.CAST_TO_BINARY_INTEGER(HEXTORAW('00000003')) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 3     |
+-------+

12.5 应用场景

• 场景一：数据恢复与日志分析。转换RAW为可读值，帮助分析
• 场景二：跨平台迁移验证。通过对比RAW抓换为INTEGER校验导出/导入的一致性

十三、CAST_TO_NUMBER

13.1 功能描述

该接口用于将一个NUMBER值的原始二进制表示（RAW 类型）转换回一个NUMBER值

13.2 方法声明

FUNCTION CAST_TO_NUMBER (
    r   IN RAW
    ) RETURN NUMBER;

13.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	二进制数据

13.4 示例

-- 将十六进制原始字节'00000003'转换为NUMBER类型的数值
SQL> SELECT UTL_RAW.CAST_TO_NUMBER(HEXTORAW('0003')) FROM DUAL;

+--------+
| EXPR1  |
+--------+
| 3 |
+--------+

13.5 应用场景

• 场景一：数据恢复与日志分析。转换RAW为可读值，帮助分析
• 场景二：跨平台迁移验证。通过对比RAW抓换为NUMBER校验导出/导入的一致性

十四、CAST_TO_NVARCHAR2

14.1 功能描述

该接口用于将一个NVARCHAR2值的原始二进制表示（RAW 类型）转换回一个NVARCHAR2值

14.2 方法声明

FUNCTION CAST_TO_NVARCHAR2 (
    r   IN RAW
    ) RETURN NVARCHAR2;

14.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	二进制数据

14.4 示例

-- 将十六进制原始字节'54'转换为NVARCHAR2类型的数值
SQL> SELECT UTL_RAW.CAST_TO_NVARCHAR2(HEXTORAW('54')) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| T     |
+-------+

14.5 应用场景

• 场景一：日志或备份中字符串字段还原。将RAW还原为NVARCHAR2查看真实文本内容

十五、CAST_TO_RAW

15.1 功能描述

该接口用于返回一个VARCHAR2值的原始二进制表示（RAW 类型）

15.2 方法声明

FUNCTION CAST_TO_RAW (
    c   IN VARCHAR2
    ) RETURN RAW;

15.3 参数说明

参数名	类型	取值范围	是否可选	描述
c	VARCHAR2	无	否	原始VARCHAR2数据

15.4 示例

-- 把字符串'hello'转换为RAW类型，然后再转换为其十六进制形式输出
SQL> SELECT RAWTOHEX(UTL_RAW.CAST_TO_RAW('hello')) FROM DUAL;

+------------+
|   EXPR1    |
+------------+
| 68656C6C6F |
+------------+

15.5 应用场景

• 场景一：将文本信息编码为RAW便于存储压缩、加密，或对比底层字节日志内容

十六、CAST_TO_VARCHAR2

16.1 功能描述

该接口用于将RAW类型的数据转换为VARCHAR2类型的数据

16.2 方法声明

FUNCTION CAST_TO_VARCHAR2 (
    r   IN RAW
    ) RETURN VARCHAR2;

16.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据

16.4 示例

-- 将RAW数据'68656C6C6F'转换为VARCHAR2数据
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2('68656C6C6F') FROM DUAL;

+-------+
| EXPR1 |
+-------+
| hello |
+-------+

16.5 应用场景

• 场景一：字符集问题排查，分析VARCHAR2和RAW相互转换是否在不同字符集下出现乱码
• 场景二：日志或备份数据解析。某些日志、归档、转储中的文本字段是以RAW存储的，转换回可读文本

十七、COMPARE

17.1 功能描述

该接口用于按字节比较两个RAW类型的数据，完全相等时返回0，不相等时返回第一个不相等的字节序号

17.2 方法声明

FUNCTION COMPARE (
    r1      IN RAW,
    r2      IN RAW,
    pad     IN RAW DEFAULT NULL
    ) RETURN INTEGER;

17.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	否	原始RAW数据
r2	RAW	无	否	原始RAW数据
pad	RAW	无	是，默认为NULL	填充值。当两个原始数据进行字节比较时，超长的部分的值若等于填充值，此时视为相等

17.4 示例

-- 逐字节比较'37'和'38'大小
SQL> SELECT UTL_RAW.COMPARE(HEXTORAW('37'),HEXTORAW('38')) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 1     |
+-------+

-- 逐字节比较'38'和'38'大小
SQL> SELECT UTL_RAW.COMPARE(HEXTORAW('38'),HEXTORAW('38')) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 0     |
+-------+

17.5 应用场景

• 场景一：验证备份数据是否一致。比较备份文件中关键字段或哈希摘要的RAW值，确认是否一致
• 场景二：数据库同步校验。对两个数据库间同步后的RAW类型字段进行逐字节比较，检查同步内容是否精确一致

十八、CONCAT

18.1 功能描述

该接口用于将多个RAW数据按顺序拼接为一个完整的RAW数据

18.2 方法声明

FUNCTION 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;

18.3 参数说明

参数名	类型	取值范围	是否可选	描述
r1	RAW	无	是，默认为NULL	原始RAW数据
r2	RAW	无	是，默认为NULL	原始RAW数据
r3	RAW	无	是，默认为NULL	原始RAW数据
r4	RAW	无	是，默认为NULL	原始RAW数据
r5	RAW	无	是，默认为NULL	原始RAW数据
r6	RAW	无	是，默认为NULL	原始RAW数据
r7	RAW	无	是，默认为NULL	原始RAW数据
r8	RAW	无	是，默认为NULL	原始RAW数据
r9	RAW	无	是，默认为NULL	原始RAW数据
r10	RAW	无	是，默认为NULL	原始RAW数据
r11	RAW	无	是，默认为NULL	原始RAW数据
r12	RAW	无	是，默认为NULL	原始RAW数据

18.4 示例

-- 将十六进制字符'30'和'31'转换为RAW，然后进行拼接，转换为VARCHAR2字符串输出
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.CONCAT(HEXTORAW('30'),HEXTORAW('31'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| 01    |
+-------+

18.5 应用场景

• 场景一：通过PL/SQL构造一段符合特定协议格式的数据包，CONCAT可用于将数据逐一拼接成完整报文
• 场景二：有些系统日志或备份格式是以RAW形式存储的，需要将多个RAW段拼接后分析整体结构

十九、CONVERT

19.1 功能描述

该接口用于对RAW数据进行字符集转换，并返回转换后的RAW数据

19.2 方法声明

FUNCTION CONVERT(
    r               IN RAW,
    to_charset      IN VARCHAR2,
    from_charset    IN VARCHAR2
    ) RETURN RAW;

19.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据
to_charset	VARCHAR2	无	否	源字符集名称
from_charset	VARCHAR2	无	否	目标字符集名称

19.4 示例

-- CAST_TO_RAW先将'HELLO'转换为RAW二进制，然后CONVERT字符集转换，最后CAST_TO_VARCHAR2转换为字符串结果进行显示
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.CONVERT(UTL_RAW.CAST_TO_RAW('HELLO'),'GBK','UTF8')) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| HELLO |
+-------+

19.5 应用场景

• 场景一：字符集兼容性排查。在数据库迁移或字符集更换时，检测和转换RAW编码字段，确保不同字符集间的数据兼容
• 场景二：数据导入导出一致性校验。对导入文件中的RAW数据，按目标库字符集进行转换，确保还原无误

二十、COPIES

20.1 功能描述

该接口用于拼接指定份数的RAW原始数据，并将结果进行返回。

20.2 方法声明

FUNCTION COPIES (
    r       IN RAW,
    n       IN INTEGER
    ) RETURN RAW;

20.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据
n	INTEGER	无	否	份数

20.4 示例

-- 将RAW数据 0x41（即 'A'）复制5次，得到0x4141414141（即 'AAAAA'）
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.COPIES(UTL_RAW.CAST_TO_RAW('A'), 5)) AS result FROM DUAL;

+--------+
| RESULT |
+--------+
| AAAAA  |
+--------+

SQL> SELECT RAWTOHEX(UTL_RAW.COPIES(HEXTORAW('0F'), 4)) AS result FROM DUAL;

+----------+
|  RESULT  |
+----------+
| 0F0F0F0F |
+----------+

20.5 应用场景

• 场景一：构造模拟数据进行压测或测试。快速生成较长的RAW数据，用于模拟大字段、通信负载等数据
• 场景二：构造占位数据。在某些初始化脚本中，用复制模式批量填充RAW字段

二十一、LENGTH

21.1 功能描述

该接口用于返回RAW数据的字节长度（不是字符数，而是真实的字节数）

21.2 方法声明

FUNCTION LENGTH (
    r       IN RAW
    ) RETURN INTEGER;

21.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据

21.4 示例

-- 计算字符串'你好'转为 RAW 后的字节数。输出结果为6，因为UTF-8编码下'你'和'好'各占 3 字节
SQL> SELECT UTL_RAW.LENGTH(UTL_RAW.CAST_TO_RAW('你好')) AS bytes_len FROM DUAL;

+-----------+
| BYTES_LEN |
+-----------+
| 6         |
+-----------+

-- 十六进制串长度，每两个hex字符表示1字节，输出为4
SQL> SELECT UTL_RAW.LENGTH(HEXTORAW('DEADBEEF')) AS bytes_len FROM DUAL;

+-----------+
| BYTES_LEN |
+-----------+
| 4         |
+-----------+

21.5 应用场景

• 场景一：检测RAW字段是否超长。有些RAW类型字段（如日志、摘要）有最大长度限制，可通过该函数检测是否超限
• 场景二：排查存储异常或数据错位。在崩溃恢复、日志还原等操作中，通过比对RAW实际长度判断是否发生截断、拼接错误

二十二、OVERLAY

22.1 功能描述

该接口用于在指定位置将一个RAW值中的部分字节用另一个RAW值覆盖替换，返回修改后的新RAW值

22.2 方法声明

FUNCTION 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;

22.3 参数说明

参数名	类型	取值范围	是否可选	描述
overlay_str	RAW	无	否	用于覆盖的RAW数据
target	RAW	无	否	被覆盖的目标RAW数据
pos	BINARY_INTEGER	无	是，默认为1	指定开始位置
len	BINARY_INTEGER	无	是，默认为NULL	字节数
pad	RAW	无	是，默认为NULL	填充值

22.4 示例

-- 从'memory'的第2个字节位置开始替换，使用'hello'的2个字节替换部分'memory'
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.OVERLAY(UTL_RAW.CAST_TO_RAW('hello'),
                                                     UTL_RAW.CAST_TO_RAW('memory'),
                                                     cast(2 as BINARY_INTEGER),
                                                     cast(2 as BINARY_INTEGER))) FROM DUAL;

+--------+
| EXPR1  |
+--------+
| mheory |
+--------+

22.5 应用场景

• 场景一：在不修改整个数据的前提下，修复受损数据块的一部分字节
• 场景二：替换日志或数据文件中的关键字节，模拟崩溃、校验失败等场景的应急测试

二十三、REVERSE

23.1 功能描述

该接口用于按字节顺序反转RAW数据，返回一个新的RAW值

23.2 方法声明

FUNCTION REVERSE (
    r   IN RAW
    ) RETURN RAW;

23.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据

23.4 示例

-- 将'hello'转换为RAW后，按字节顺序进行反转
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.REVERSE(UTL_RAW.CAST_TO_RAW('hello'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| olleh |
+-------+

23.5 应用场景

• 场景一：数据格式转换与兼容性处理。不同平台字节序大小端差异时，反转字节以匹配目标系统格式

二十四、SUBSTR

24.1 功能描述

该接口用于从一个RAW类型数据中提取指定位置开始的子字节串

24.2 方法声明

FUNCTION SUBSTR (
    r   IN RAW,
    pos IN BINARY_INTEGER,
    len IN BINARY_INTEGER DEFAULT NULL
    ) RETURN RAW;

24.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据
pos	BINARY_INTEGER	无	否	开始位置
len	BINARY_INTEGER	无	是，默认为NULL	提取长度（单位：字节）

24.4 示例

-- 将'hello'转换为RAW后，从起始位置1，提取2字节长度
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.SUBSTR(UTL_RAW.CAST_TO_RAW('hello'),1,2)) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| he    |
+-------+

24.5 应用场景

• 场景一：从二进制日志/备份文件中截取特定字段或区域，定位问题或验证数据
• 场景二：定位并提取数据块中的某段字节，用于修复或对比
• 场景三：仅关注二进制字段某部分内容变换，截取后做差异对比

二十五、TRANSLATE

25.1 功能描述

该接口用于将一个RAW数据中的指定字节根据给定的映射关系，转换成对应的另一组字节。相当于RAW数据做字节级的”替换工作“

25.2 方法声明

FUNCTION TRANSLATE (
    r           IN RAW,
    from_set    IN RAW,
    to_set      IN RAW
    ) RETURN RAW;

25.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	原始RAW数据
from_set	RAW	无	否	用于匹配的RAW数据
to_set	RAW	无	否	用于替换的RAW数据，长度需和from_set一致

注意

在替换时，是对r的每个单个字节逐个扫描，如果这个字节出现在from_set中，则根据出现位置i，用to_set中第i个字节替换它；
当to_set字节数大于from_set时，只会取和from_set相同长度的前n字节一一对应进行替换；

25.4 示例

-- 将'hello'数据使用'll'匹配，匹配部分使用'oo'进行映射
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.TRANSLATE(UTL_RAW.CAST_TO_RAW('hello'),
                                                       UTL_RAW.CAST_TO_RAW('ll'),
                                                       UTL_RAW.CAST_TO_RAW('oo'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| heooo |
+-------+

25.5 应用场景

• 场景一：二进制日志数据清洗。对RAW日志数据中某些控制字节做替换，避免日志解析异常或乱码
• 场景二：安全敏感字节替换。替换敏感字节，防止日志泄漏或异常访问

二十六、TRANSLITERATE

26.1 功能描述

该接口同样用于将一个RAW数据中的指定字节根据给定的映射关系，转换成对应的另一组字节

26.2 方法声明

FUNCTION TRANSLITERATE (
    r           IN RAW,
    to_set      IN RAW DEFAULT NULL,
    from_set    IN RAW DEFAULT NULL,
    pad         IN RAW DEFAULT NULL
    ) RETURN RAW;

26.3 参数说明

参数名	类型	取值范围	是否可选	描述
r	RAW	无	否	目标节点
to_set	RAW	无	是，默认为NULL	用于映射的RAW数据
from_set	RAW	无	是，默认为NULL	用于匹配的RAW数据
pad	RAW	无	是，默认为NULL	填充值

提示

与TRANSLATE不同的是，当from_set字节数大于to_set时，此时可指定pad值用于填充

26.4 示例

-- 使用'a'进行填充
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.TRANSLITERATE(UTL_RAW.CAST_TO_RAW('hello'),
                                                                UTL_RAW.CAST_TO_RAW('o'),
                                                                UTL_RAW.CAST_TO_RAW('hel'),
                                                                UTL_RAW.CAST_TO_RAW('a'))) FROM DUAL;

+-------+
| EXPR1 |
+-------+
| oaaao |
+-------+

26.5 应用场景

• 场景一：跨平台文件字节兼容转换。某些平台之间备份或日志格式略有不同，可以使用TRANSLITERATE调整特定控制字节或标识位格式
• 场景二：数据修复。批量替换RAW数据中的”脏数据字节“或非法字节，提升可读性与可用性

二十七、XRANGE

27.1 功能描述

该接口用于构造一个指定起始值、结束值的连续字节序列

27.2 方法声明

FUNCTION XRANGE (
    start_byte  IN RAW DEFAULT NULL,
    end_byte    IN RAW DEFAULT NULL
    ) RETURN RAW;

27.3 参数说明

参数名	类型	取值范围	是否可选	描述
start_byte	RAW	无	是，默认为NULL	起始字符
end_byte	RAW	无	是，默认为NULL	结束字符

27.4 示例

-- 构造1至9的连续字节序列
SQL> SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_RAW.XRANGE(UTL_RAW.CAST_TO_RAW('1'),
                                                    UTL_RAW.CAST_TO_RAW('9'))) FROM DUAL;

+-----------+
|   EXPR1   |
+-----------+
| 123456789 |
+-----------+

27.5 应用场景

• 场景一：用于构造连续字节序列，测试网络传输、数据完整性验证、字符集编码等系统级问题
• 场景二：快速生成一段定长RAW数据，如作为密钥填充、初始化密码种子等