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 套裝程式不支援在使用不同字元集的資料庫之間傳送訊息。例如，如果您有一個使用 AL32UTF8 的自治式 AI 資料庫執行處理，以及另一個使用 WE8MSWIN1252 的執行處理，您就無法在這兩個資料庫之間傳送含有 DBMS_PIPE 的訊息。在此情況下，如果您嘗試在這兩個資料庫之間傳送含有 DBMS_PIPE 的訊息，系統將會發出 ORA-12704 錯誤。

永久訊息的 DBMS_PIPE 子程式摘要

此表格列出 DBMS_PIPE 子程式，並簡短說明它們。

子程式 描述
CREATE_PIPE 函數 建立管 (私有管是必要的)。
GET_CREDENTIAL_NAME 函數 傳回全域 credential_name 變數值。
GET_LOCATION_URI 函數 傳回當訊息儲存在「雲端物件存放區」中時，用來作為預設位置 URI 的全域 location_uri 變數值。

NEXT_ITEM_TYPE 函數

 傳回緩衝區中下一個項目的資料類型。

PACK_MESSAGE 程序

 在本地端緩衝區內建立訊息 。
RECEIVE_MESSAGE 函數 將已命名管道的訊息複製到本機緩衝區。

RESET_BUFFER 程序

 清除本機緩衝區的內容。

REMOVE_PIPE 函數

 移除已命名管道。
SEND_MESSAGE 函數 在具名管道上傳送訊息：如果具名管道不存在，這會以隱含方式建立公用管道。
SET_CREDENTIAL_NAME 程序 針對儲存在「雲端物件存放區」中的訊息，設定作為預設證明資料的 credential_name 變數。
SET_LOCATION_URI 程序 針對儲存在「雲端物件存放區」中的訊息，設定作為預設位置 URI 的全域 location_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 提供的程序使用。管線名稱的長度不應超過 128 個位元組，不區分大小寫。此時，名稱不得包含「全球化支援」字元。

maxpipesize

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

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

預設的 maxpipesize 為 66536 個位元組。

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

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

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 函數

此函數會傳回將管路訊息儲存至「雲端物件存放區」時，可作為預設位置 URI 的全域 location_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 參數來覆寫建立管道大小規格。

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

pipename

您要放置訊息的管道名稱。

如果您使用明確的管道，則此為您在呼叫 CREATE_PIPE 時所指定的名稱。

** 注意：** 請勿使用以 'ORA$' 為開頭的管線名稱。這些名稱保留供 Oracle 提供的程序使用。管線名稱的長度不應超過 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 原生 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 的格式視您使用的雲端物件儲存服務而定，如需詳細資訊，請參閱雲端物件儲存 URI 格式。

用途注意事項

如果您使用 Oracle Cloud Infrastructure Object Storage 來儲存訊息，可以使用 Oracle Cloud Infrastructure 原生 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;
/

相關內容