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 中的单件管道功能提供以下功能：

Singleton Pipe 可以是支持的 DBMS_PIPE 类型之一：

单例管道的 DBMS_PIPE 子程序概要

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

子程序 说明
CREATE_PIPE 函数 创建管道（私人管道所必需的）

NEXT_ITEM_TYPE 函数

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

PACK_MESSAGE 过程

 在本地缓冲区中构建消息

清除过程

 清除命名管道的内容
RECEIVE_MESSAGE 函数 将消息从命名管道复制到本地缓冲区

RESET_BUFFER 过程

 清除本地缓冲区的内容

REMOVE_PIPE 函数

 删除命名的管道
SEND_MESSAGE 函数 在命名管道上发送消息：如果命名管道不存在，则会隐式创建公共管道

UNIQUE_SESSION_NAME 函数

 返回唯一的会话名称

UNPACK_MESSAGE 过程

 访问缓冲区中的下一个项

CREATE_PIPE 函数

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

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

要创建单例管道，请将 singleton 参数设置为 TRUE。以下参数适用于单例管道：

语法

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE,
   singleton    IN BOOLEAN DEFAULT FALSE,
   shelflife    IN INTEGER DEFAULT 0)
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 时可以隐式创建公共管道。

singleton

使用 TRUE 创建单例管道。

默认值：FALSE
shelflife

在 Singleton Pipe 中高速缓存的消息的失效时间（秒）。超过指定的 shelflife 时间后，无法再从管道访问该消息。参数 shelflife 仅适用于单例管道。

默认值为 0，表示消息永不过期。

返回值

返回 说明
0

成功。

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

无法将现有管道转换为单件管道。

  • 具有多个现有消息的隐式管道无法转换为单例管道。
  • 对于不是 Singleton 的显式管道，DBMS_PIPE.SEND_MESSAGE 无法发送单例参数设置为 TRUE 的消息。
7 为 shelflife 参数指定了非零值，并且管道不是单例管道。
ORA-23322

由于命名冲突而失败。

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

异常错误

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

范例

创建具有 1 小时货架的 Singleton Pipe。

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

RECEIVE_MESSAGE 函数

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

语法

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename      IN VARCHAR2,
   timeout       IN INTEGER      DEFAULT maxwait,
   cache_func    IN VARCHAR2     DEFAULT NULL)
RETURN INTEGER;

参数

表 - RECEIVE_MESSAGE 函数参数

Parameter (参数) 说明
pipename

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

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

timeout

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

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

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

cache_func

用于在单例管道中自动缓存消息的高速缓存函数名称。

函数的名称应使用所有者方案进行完全限定：

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

默认值：NULL

返回值

表 - RECEIVE_MESSAGE 函数返回值

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

使用说明

高速缓存函数参数

单例管道支持缓存功能，可在以下两种情况下自动缓存管道中的消息：

函数的名称应使用所有者方案进行完全限定：

要使用高速缓存函数，调用 DBMS_PIPE.RECEIVE_MESSAGE 的当前会话用户必须具有执行高速缓存函数所需的特权。

高速缓存函数语法

CREATE OR REPLACE FUNCTION *cache_function_name* (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Parameter (参数) 数据类型 说明
pipename VARCHAR2 单例管的名称。
返回 说明
0 成功
非零值 从 DBMS_PIPE.RECEIVE_MESSAGE 返回失败值

定义高速缓存函数，以便从 Singleton Pipe 的读取器会话中提供复杂性的封装和抽象。高速缓存函数中的典型操作包括：

异常错误

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

范例

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.receive_message(pipename   => 'MY_PIPE1',
                                        timeout    => 1,
                                        cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/

SEND_MESSAGE 函数

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

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

要创建隐式单例管道，请将 singleton 参数设置为 TRUE。以下参数适用于单例管道：

CREATE_PIPE 函数，对于在单例管道中缓存的任何新消息，它都是默认值。

语法

DBMS_PIPE.SEND_MESSAGE (
    pipename     IN VARCHAR2,
    timeout      IN INTEGER DEFAULT MAXWAIT,
    maxpipesize  IN INTEGER DEFAULT 65536,
    singleton    IN BOOLEAN DEFAULT FALSE,
    shelflife    IN INTEGER DEFAULT 0)
RETURN INTEGER;

参数

表 - SEND_MESSAGE 函数参数

Parameter (参数) 说明
pipename

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

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

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

timeout

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

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

maxpipesize

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

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

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

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

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

singleton

使用 TRUE 创建单例管道。

默认值：FALSE
shelflife

在 Singleton Pipe 中高速缓存的消息的失效时间（秒）。

超过指定的 shelflife 时间后，无法再从管道访问该消息。参数 shelflife 仅适用于单例管道。

默认值为 0，表示消息永不过期。

返回值

返回 说明
0

成功。

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

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

1

超时。

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

发生中断。

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

无法将现有管道转换为单件管道。

  • 具有多个现有消息的隐式管道无法转换为单例管道。
  • 对于不是 Singleton 的显式管道，DBMS_PIPE.SEND_MESSAGE 无法发送单例参数设置为 TRUE 的消息。
7 为 shelflife 参数指定了非零值，并且管道不是单例管道。
ORA-23322

权限不足。

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

异常错误

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

相关内容

使用单例管道缓存消息