From 7b838a2deebbeab36bf3cbdc3fa2d7088af3f79e Mon Sep 17 00:00:00 2001 From: Loyal-Young <266632325+Loyal-Young@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:21:47 +0800 Subject: [PATCH] docs: document UTL_URL encoding and decoding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fill the English and Chinese UTL_URL navigation entries with guidance on escaping complete URLs or individual components, selecting a character set, and decoding percent escapes. Describe how the implementation keeps literal text separate from decoded bytes. Assisted-by: Codex:GPT-6 Percentage of AI-generated code: 100% Signed-off-by: 王泽浩 <266632325+Loyal-Young@users.noreply.github.com> --- .../utl_url_impl.adoc | 14 ++++++++++ .../oracle_compatibility/compat_utl_url.adoc | 26 +++++++++++++++++++ .../utl_url_impl.adoc | 14 ++++++++++ .../oracle_compatibility/compat_utl_url.adoc | 26 +++++++++++++++++++ 4 files changed, 80 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc create mode 100644 CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc create mode 100644 EN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc create mode 100644 EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc diff --git a/CN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc new file mode 100644 index 00000000..d158aecb --- /dev/null +++ b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_URL 实现 + +== 按字节编码 + +`UTL_URL` 包调用 `contrib/ivorysql_ora/src/builtin_packages/utl_url/utl_url.c` 中的 C 入口。`ESCAPE` 先将输入转为指定编码,再逐字节处理。ASCII 字母、数字和非保留标点会保留。布尔参数控制是否保留分隔符,其余字节各转换为一个使用大写十六进制的 `%XX` 序列。 + +== 批量解码连续转义 + +`UNESCAPE` 先收集连续的 `%XX` 序列,再将还原的字节转为数据库编码。一组转义字节可以构成一个多字节字符。字面文本已采用数据库编码,会单独复制。解析器校验每组的两个十六进制数字,并拒绝转义的零字节。 + +可运行的示例见 xref:master/oracle_compatibility/compat_utl_url.adoc[UTL_URL 包]。 diff --git a/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc new file mode 100644 index 00000000..b7d4b64c --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc @@ -0,0 +1,26 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_URL 包 + +== 转义 URL 或其中的组件 + +请用具有包执行权限的角色连接 Oracle 兼容模式。对整个 URL 使用 `UTL_URL.ESCAPE(url)` 时,`/`、`?` 和 `&` 等分隔符会保留。如果输入将作为 URL 的一个组件,且其中的分隔符需要转义,请将第二个参数设为 `true`。两种用法都会将空格编码为 `%20`。 + +如果转义字节需要使用指定编码,请将字符集(例如 `UTF8`)传给 `ESCAPE` 的第三个参数或 `UNESCAPE` 的第二个参数。省略字符集或传入 NULL 时,包使用数据库编码。 + +[source,sql] +---- +SELECT utl_url.escape('https://example.test/a b?q=a+b') AS url; +SELECT utl_url.escape('a+b&c=d', true) AS query_value; +SELECT utl_url.escape('中文', false, 'UTF8') AS encoded; +SELECT utl_url.unescape('%E4%B8%AD%E6%96%87+a%20b', 'UTF8') AS decoded; +---- + +四条查询依次返回 `https://example.test/a%20b?q=a+b`、`a%2Bb%26c%3Dd`、`%E4%B8%AD%E6%96%87` 和 `中文+a b`。解码时字面加号仍为加号。 + +== 解码百分号转义 + +`UNESCAPE` 将 `%XX` 序列还原为字节。请传入生成这些序列时使用的字符集。无效或不完整的转义会报错。由于 `ESCAPE` 也会转义输入中的百分号,请对原始值调用该函数。 + +实现细节见 xref:master/compatibility_features_design/utl_url_impl.adoc[UTL_URL 实现]。 diff --git a/EN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc new file mode 100644 index 00000000..713c7793 --- /dev/null +++ b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_url_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_URL Implementation + +== Encode bytes + +The `UTL_URL` package delegates to the C entry points in `contrib/ivorysql_ora/src/builtin_packages/utl_url/utl_url.c`. `ESCAPE` converts the input to the requested encoding before examining its bytes. ASCII letters, digits and the unreserved punctuation pass through. The boolean argument controls whether reserved delimiters pass through. Each other byte becomes one uppercase hexadecimal `%XX` group. + +== Decode consecutive groups + +`UNESCAPE` accumulates consecutive `%XX` groups before converting the resulting bytes to the database encoding. A group of escaped bytes can form one multibyte character. Literal text is already in the database encoding and is copied separately. The parser checks the two hexadecimal digits in each group and rejects an escaped zero byte. + +For runnable examples, see xref:master/oracle_compatibility/compat_utl_url.adoc[UTL_URL package]. diff --git a/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc new file mode 100644 index 00000000..079930d4 --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_url.adoc @@ -0,0 +1,26 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_URL Package + +== Escape a URL or a component + +Connect in Oracle compatibility mode with a role that can execute the package. Use `UTL_URL.ESCAPE(url)` on a URL when you want to preserve delimiters such as `/`, `?` and `&`. Pass `true` as the second argument when a value will be inserted into a URL component and its delimiters need escaping. Spaces become `%20` in both cases. + +Pass a character set such as `UTF8` as the third argument to `ESCAPE` or the second argument to `UNESCAPE` when the encoded bytes need a specific encoding. With an omitted or NULL character set, the package uses the database encoding. + +[source,sql] +---- +SELECT utl_url.escape('https://example.test/a b?q=a+b') AS url; +SELECT utl_url.escape('a+b&c=d', true) AS query_value; +SELECT utl_url.escape('中文', false, 'UTF8') AS encoded; +SELECT utl_url.unescape('%E4%B8%AD%E6%96%87+a%20b', 'UTF8') AS decoded; +---- + +The results are `https://example.test/a%20b?q=a+b`, `a%2Bb%26c%3Dd`, `%E4%B8%AD%E6%96%87` and `中文+a b`, respectively. A literal plus remains a plus when decoding. + +== Decode percent escapes + +`UNESCAPE` decodes `%XX` byte sequences. Supply the same character set used to produce those sequences. Invalid or incomplete escapes raise an error. A percent sign in the input to `ESCAPE` is itself escaped, so apply it to the original value. + +See xref:master/compatibility_features_design/utl_url_impl.adoc[UTL_URL implementation].