DBMS_PIPE 套裝程式 (單一管線)

DBMS_PIPE 套裝程式可讓相同執行處理中的兩個或多個階段作業進行通訊。

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure 支援 Oracle Database 19c 提供的核心 DBMS_PIPE 功能以及擴充功能。

請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 DBMS_PIPE 或 Oracle Database 26ai PL/SQL Packages and Types Reference ，瞭解 Oracle Database 中提供之核心 DBMS_PIPE 功能的詳細資訊。

單一管路的 DBMS_PIPE 總覽

管線功能具有數個潛在的應用程式：外部服務介面、除錯、獨立交易及警示。

在自治式 AI 資料庫上，DBMS_PIPE 套裝程式具有擴充的功能，可支援單一管道。請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 DBMS_PIPE ，或參閱 Oracle Database 26ai PL/SQL Packages and Types Reference 瞭解詳細資訊。

DBMS_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 提供的程序使用。管線名稱的長度不應超過 128 個位元組，不區分大小寫。此時，名稱不得包含「全球化支援」字元。

maxpipesize

允許的管道大小上限 (位元組)。

管道上所有訊息的總大小不得超過此金額。訊息若超過此上限，就會被封鎖。

預設的 maxpipesize 為 66536 個位元組。

管的 maxpipesize 會成為管的特性的一部分，並在管的生命週期中持續存在。具有較大值之 SEND_MESSAGE 的呼叫者會導致增加 maxpipesize。值較小的呼叫程式會使用現有、較大的值。

65536 的預設 maxpipesize 適用於所有管道。

private

使用預設值 TRUE 來建立專用管道。

當您呼叫 SEND_MESSAGE 時，可以隱含地建立公用管道。

singleton

使用 TRUE 來建立單一管線。

預設值：FALSE
shelflife

以「單一管線」快取之訊息的到期時間 (秒)。超過指定的 shelflife 時間之後，便無法再從「管」存取訊息。參數 shelflife 僅適用於單一管線。

預設值為 0，表示訊息永不過期。

傳回值

傳回 描述
0

成功。

如果管已存在，且嘗試建立管路的使用者已獲授權使用該管路，則 Oracle 會傳回 0，表示成功，且管路中已存在的任何資料都會保留。
6

無法將現有管道轉換為單一管道。

  • 具有多個現有訊息的隱含管道無法轉換為單一管道。
  • 對於非 Singleton 的明確管道，DBMS_PIPE.SEND_MESSAGE 無法傳送單一引數設為 TRUE 的訊息。
7 提供給 shelflife 參數的非零值，且管道不是單一管道。
ORA-23322

命名衝突導致失敗。

如果有相同名稱的管道存在，而且是由其他使用者所建立，則 Oracle 會發出錯誤 ORA-23322，指出命名衝突。

異常狀況

例外 描述
Null pipe name 權限錯誤：已經有相同名稱的管線存在，不允許使用。

範例

建立一個裝滿 1 小時的單一管道。

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 使用者的權限不足，無法從管道讀取。

使用注意事項

快取函數參數

Singleton Pipes 支援快取功能，以在下列兩種情況下自動快取管中的訊息：

函數的名稱應該與擁有者綱要完全合格：

若要使用快取功能，呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的目前階段作業使用者必須具有執行快取功能的必要權限。

快取函數語法

CREATE OR REPLACE FUNCTION *cache_function_name* (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Parameter - 參數 資料類型 描述
pipename VARCHAR2 單一管線的名稱。
傳回 描述
0 成功
非零 DBMS_PIPE.RECEIVE_MESSAGE 傳回的失敗值

定義快取函數，以提供單一管路讀取器階段作業的複雜性封裝和抽象。快取函數中的典型作業如下：

異常狀況

例外 描述
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 管道，請將 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 提供的程序使用。管線名稱的長度不應超過 128 個位元組，且不區分大小寫。此時，名稱不得包含「全球化支援」字元。

timeout

嘗試在管道上放置訊息時所等待的時間 (秒)。

預設值為常數 MAXWAIT，其定義為 86400000 (1000 天)。

maxpipesize

允許的管道大小上限 (位元組)。

管道上所有訊息的總大小不得超過此金額。訊息若超過此上限，就會被封鎖。預設值為 65536 位元組。

管的 maxpipesize 會成為管的特性的一部分，並在管的生命週期中持續存在。具有較大值之 SEND_MESSAGE 的呼叫者會導致增加 maxpipesize。值較小的呼叫程式只會使用現有、較大的值。

將 maxpipesize 指定為 SEND_MESSAGE 程序的一部分，不需要另外呼叫即可開啟管道。如果您明確地建立管道，則可以使用選擇性的 maxpipesize 參數來覆寫建立管道大小規格。

65536 的預設 maxpipesize 適用於所有管道。

singleton

使用 TRUE 來建立單一管線。

預設值：FALSE
shelflife

以「單一管線」快取之訊息的到期時間 (秒)。

超過指定的 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 權限錯誤。權限不足，無法寫入管道。此管是私密管，由其他人擁有。

相關內容

使用單一管線的快取訊息