DBMS_PIPE 程序包（持久性消息传送管道）

DBMS_PIPE 软件包允许同一实例中的两个或更多会话进行通信。

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure 支持 Oracle Database 19c 中提供的核心 DBMS_PIPE 功能以及扩展功能。

有关 Oracle Database 中提供的核心 DBMS_PIPE 功能的详细信息，请参阅 Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 中的 DBMS_PIPE 。

持久性消息传送管道的 DBMS_PIPE 概览

管道功能有几个潜在的应用：外部服务接口、调试、独立的事务和警报。

在自治 AI 数据库上，DBMS_PIPE 程序包具有扩展功能来支持持久性消息传递管道。有关详细信息，请参阅《Oracle Database 19c PL/SQL Packages and Types Reference 》或《Oracle Database 26ai PL/SQL Packages and Types Reference 》中的 DBMS_PIPE 。

DBMS_PIPE 中的持久消息：

DBMS_PIPE 限制

DBMS_PIPE 软件包不支持在使用不同字符集的数据库之间发送消息。例如，如果您有一个使用 AL32UTF8 的自治 AI 数据库实例和另一个使用 WE8MSWIN1252 的实例，则无法在这两个数据库之间发送带有 DBMS_PIPE 的消息。在这种情况下，如果尝试在这两个数据库之间发送带有 DBMS_PIPE 的消息，系统将引发错误 ORA-12704。

持久性消息传送的 DBMS_PIPE 子程序概要

此表列出了 DBMS_PIPE 子程序并简要介绍了这些子程序。

子程序 说明
CREATE_PIPE 函数 创建管道（对于专用管道是必需的）。
GET_CREDENTIAL_NAME 函数 返回全局 credential_name 变量值。
GET_LOCATION_URI 函数 返回全局 location_uri 变量值，该值用作在云对象存储中存储消息时使用的默认位置 URI。

NEXT_ITEM_TYPE 函数

 返回缓冲区中下一个项的数据类型。

PACK_MESSAGE 过程

 在本地缓冲区中构建消息。
RECEIVE_MESSAGE 函数 将消息从命名管道复制到本地缓冲区。

RESET_BUFFER 过程

 清除本地缓冲区的内容。

REMOVE_PIPE 函数

 删除命名的管道。
SEND_MESSAGE 函数 在指定的管道上发送消息：如果指定的管道不存在，则会隐式创建公共管道。
SET_CREDENTIAL_NAME 过程 设置 credential_name 变量，该变量用作存储在云对象存储中的消息的默认凭证。
SET_LOCATION_URI 过程 设置全局 location_uri 变量，该变量用作存储在云对象存储中的消息的默认位置 URI。

UNIQUE_SESSION_NAME 函数

 返回唯一的会话名称。

UNPACK_MESSAGE 过程

 访问缓冲区中的下一个项。

CREATE_PIPE 函数

此函数显式创建公共或专用管道。如果 private 标志为 TRUE，则会将管道创建者分配为专用管道的所有者。

只能通过调用 REMOVE_PIPE 或关闭实例来删除显式创建的管道。

语法

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

参数

Parameter (参数) 说明
pipename

您正在创建的管道的名称。

调用 SEND_MESSAGE 和 RECEIVE_MESSAGE 时必须使用此名称。此名称在实例中必须是唯一的。

** 注意：** 请勿使用以 ORA$ 开头的管道名称。这些字段保留供 Oracle 提供的过程使用。Pipename 的长度不应超过 128 字节，并且不区分大小写。此时，该名称不能包含“全球化支持”字符。

maxpipesize

管道允许的最大大小（字节）。

管道中所有消息的总大小不能超过此数量。如果消息超过此最大值，则该消息将被阻止。

缺省 maxpipesize 为 66536 字节。

管道的 maxpipesize 成为管道特征的一部分，并在管道的寿命内持续存在。值较大的 SEND_MESSAGE 调用方会导致 maxpipesize 增加。值较小的调用方使用现有的大值。

缺省的 maxpipesize 为 65536 适用于所有管道。

private

使用缺省值 TRUE 创建专用管道。

调用 SEND_MESSAGE 时可以隐式创建公共管道。

返回值

返回 说明
0

成功。

如果管道已存在并且尝试创建该管道的用户有权使用该管道，则 Oracle 将返回 0，表示成功，并且管道中已存在的任何数据都会保留。
ORA-23322

由于命名冲突而失败。

如果存在同名的管道并且该管道是由其他用户创建的，则 Oracle 会发出错误 ORA-23322 来指示命名冲突。

异常错误

例外 说明
Null pipe name 权限错误：已存在同名的管道，您不能使用该管道。

范例

创建名为 MY_PIPE1 的显式专用

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

GET_CREDENTIAL_NAME 函数

此函数返回全局 credential_name 变量值，以便在消息存储到云对象存储时使用。

语法

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

返回值

返回值 说明
credential_name 用于访问云对象存储的身份证明的名称。

范例

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

GET_LOCATION_URI 函数

此函数返回全局 location_uri 变量值，当管道消息存储到云对象存储时，该变量值可用作默认位置 URI。

语法

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

返回值

返回值 说明
location_uri 对象 URI。

范例

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

RECEIVE_MESSAGE 函数

此函数将消息复制到本地消息缓冲区中。

语法

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename          IN VARCHAR2,
   timeout           IN INTEGER  DEFAULT maxwait,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

参数

表 - RECEIVE_MESSAGE 函数参数

Parameter (参数) 说明
pipename

要接收消息的管道的名称。

以 ORA$ 开头的名称保留供 Oracle 使用。

timeout

等待消息的时间（以秒为单位）。超时为 0 可让您在不阻塞的情况下读取。

超时不包括运行使用 cache_func 参数指定的高速缓存函数所花费的时间。

默认值：常量 MAXWAIT，定义为 86400000（1000 天）。

credential_name

用于存储消息的云存储的身份证明名称。

credential_name 是缺省情况下初始化为 NULL 的软件包参数。

可以在调用 DBMS_PIPE.RECEIVE_MESSAGE 之前设置此值。传递的参数值优先于全局变量的值。

凭证对象必须具有运行 DBMS_PIPE.RECEIVE_MESSAGE 的用户的 EXECUTE 和 READ/WRITE 特权。

location_uri

用于存储消息的云存储的位置 URI。

location_uri 是缺省情况下初始化为 NULL 的全局变量。

可以在调用 DBMS_PIPE.RECEIVE_MESSAGE 之前设置此值。传递的参数值优先于全局变量的值。

返回值

表 - RECEIVE_MESSAGE 函数返回值

返回 说明
0 成功
1 超时。如果管道是隐式创建的并且为空，则会将其删除。
2 管道中的记录对于缓冲区太大。
3 发生中断。
ORA-23322 用户没有足够的权限从管道读取数据。

使用说明

异常错误

表 - RECEIVE_MESSAGE 函数例外

例外 说明
Null pipe name 权限错误权限不足，无法从管道中删除记录。管道由其他人拥有。

SEND_MESSAGE 函数

此函数在指定的管道上发送消息。

该消息包含在本地消息缓冲区中，该缓冲区填充了对 PACK_MESSAGE 的调用。您可以使用 CREATE_PIPE 显式创建管道，否则将隐式创建管道。

语法

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

参数

表 - SEND_MESSAGE 函数参数

Parameter (参数) 说明
credential_name

用于存储消息的云存储的身份证明名称。

credential_name 是缺省情况下初始化为 NULL 的软件包参数。

可以在调用 DBMS_PIPE.SEND_MESSAGE 之前设置此值。传递的参数值优先于全局变量的值。

凭证对象必须具有运行 DBMS_PIPE.SEND_MESSAGE 的用户的 EXECUTE 和 READ/WRITE 特权。

location_uri

用于存储消息的云存储的位置 URI。

location_uri 是缺省情况下初始化为 NULL 的全局变量。

可以在调用 DBMS_PIPE.SEND_MESSAGE 之前设置此值。传递的参数值优先于全局变量的值。

maxpipesize

管道允许的最大大小（字节）。

管道中所有消息的总大小不能超过此数量。如果消息超过此最大值，则该消息将被阻止。默认值为 65536 字节。

管道的 maxpipesize 成为管道特征的一部分，并在管道的寿命内持续存在。值较大的 SEND_MESSAGE 调用方会导致 maxpipesize 增加。值较小的调用方只需使用现有的较大值。

如果将 maxpipesize 指定为 SEND_MESSAGE 过程的一部分，则无需单独调用即可打开管道。如果显式创建了管道，则可以使用可选的 maxpipesize 参数来覆盖创建管道大小规范。

缺省的 maxpipesize 为 65536 适用于所有管道。

pipename

要在其上放置消息的管道的名称。

如果使用的是显式管道，则这是您在调用 CREATE_PIPE 时指定的名称。

** 注意：** 请勿使用以 'ORA$' 开头的管道名称。这些名称保留供 Oracle 提供的过程使用。Pipename 的长度不应超过 128 字节，并且不区分大小写。此时，该名称不能包含“全球化支持”字符。

timeout

尝试将消息放置在管道上时等待的时间（秒）。

默认值为常量 MAXWAIT，定义为 86400000（1000 天）。

返回值

表 - SEND_MESSAGE 函数返回值

返回 说明
0

成功。

如果管道已存在并且尝试创建该管道的用户有权使用该管道，则 Oracle 将返回 0，表示成功，并且管道中已存在的任何数据都会保留。

如果以 SYSDBS/SYSOPER 身份连接的用户重新创建管道，则 Oracle 将返回状态 0，但管道的所有权保持不变。

1

超时。

此过程可能会超时，因为它无法在管道上获得锁，或者因为管道保持太满而无法使用。如果管道是隐式创建的并且为空，则会将其删除。
3

发生中断。

如果管道是隐式创建的并且为空，则会将其删除。
ORA-23322

权限不足。

如果存在同名的管道并且该管道是由其他用户创建的，则 Oracle 会发出错误 ORA-23322 来指示命名冲突。

使用说明

异常错误

表 - SEND_MESSAGE 函数异常

例外 说明
Null pipe name 权限错误权限不足，无法写入管道。管道是私有的，由其他人拥有。

SET_CREDENTIAL_NAME 过程

此过程设置当管道消息存储在云对象存储中时用作默认身份证明的 credential_name 变量。

语法

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

参数

Parameter (参数) 说明
credential_name 用于访问云对象存储的身份证明的名称。

用法附注

如果您使用 Oracle Cloud Infrastructure Object Storage 来存储消息，则可以使用 Oracle Cloud Infrastructure Native URI 或 Swift URI。但是，位置 URI 和身份证明在类型中必须匹配，如下所示：

范例

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

SET_LOCATION_URI 过程

此过程设置全局 location_uri 变量。

语法

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

Parameter (参数)

Parameter (参数) 说明
location_uri 对象或文件 URI。URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。

用法附注

如果您使用 Oracle Cloud Infrastructure Object Storage 来存储消息，则可以使用 Oracle Cloud Infrastructure Native URI 或 Swift URI。但是，位置 URI 和身份证明在类型中必须匹配，如下所示：

范例

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/

相关内容