DBMS_PIPE 套件 (單一管道)
DBMS_PIPE 套裝程式可讓相同執行處理中的兩個或多個階段作業進行通訊。
Oracle Autonomous Database on Dedicated Exadata Infrastructure 支援 Oracle Database 19c 提供的核心 DBMS_PIPE 功能，以及擴充功能。
請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 DBMS_PIPE 或 Oracle Database 23ai PL/SQL Packages and Types Reference ，瞭解 Oracle Database 中提供的核心 DBMS_PIPE 功能詳細資訊。
相關主題
DBMS_PIPE Singleton Pipes 總覽
管線功能具有數個潛在的應用程式：外部服務介面、除錯、獨立交易和警示。
在 Autonomous Database 上，DBMS_PIPE 套件具有擴充功能，可支援單一管道。請參閱 Oracle Database 19c PL/SQL Packages and Types Reference 中的 DBMS_PIPE 或 Oracle Database 23ai PL/SQL Packages and Types Reference ，瞭解詳細資訊。
DBMS_PIPE 中的單一管道功能提供下列項目：
-
能夠在 Oracle 資料庫記憶體中快取及擷取最多 32,767 個位元組的自訂訊息。訊息大小上限為 32,767 個位元組，適用於所有管線，包括單一管線。舊版的
DBMS_PIPE訊息大小上限較小。 -
在多個資料庫階段作業之間以並行讀取方式共用快取訊息。
-
快取無效化方法：
- 由使用者控制的明確快取無效化。
- 在使用者指定的參數 (
shelflife) 時間間隔 (秒) 之後，快取無效化。
-
宣告式且易於使用的 PL/SQL API 進行快取。
-
同時支援「唯讀」和「讀寫」資料庫。
Singleton Pipe 可以是任何支援的 DBMS_PIPE 類型：
- 隱含管：使用
DBMS_PIPE.SEND_MESSAGE函數以不明的管路名稱傳送訊息時，會自動建立訊息。 - 明確管線：使用
DBMS_PIPE.CREATE_PIPE函數與使用者指定的管線名稱建立。 - 公用管道：任何具備
DBMS_PIPE套裝軟體EXECUTE權限的使用者均可存取 - 私人管道：具有與管道建立者相同之使用者的階段作業可存取。
單一管路的 DBMS_PIPE 子程式摘要
此表格列出 DBMS_PIPE 子程式並簡要說明。
表格 - DBMS_PIPE 套件子程式
| 子程式 | 描述 |
|---|---|
|
建立管道 (專用管道需有) |
|
|
傳回緩衝區中下一個項目的資料類型 |
|
|
在本地端緩衝區內建立訊息 |
|
|
清除具名管道的內容 |
|
|
將具名管道的訊息複製到本機緩衝區 |
|
|
清除本機緩衝區的內容 |
|
|
移除已命名的管道 |
|
|
在具名管道上傳送訊息：如果具名管道不存在，這將隱含地建立公用管道 |
|
|
傳回唯一的階段作業名稱 |
|
|
存取緩衝區中的下一個項目 |
CREATE_PIPE 函數
此功能會明確建立公用或專用管道。如果 private 旗標為 TRUE，則會將管道建立者指派為私人管道的擁有者。
明確建立的管道只能透過呼叫 REMOVE_PIPE 或關閉執行處理來移除。
若要建立單一管，請將 singleton 參數設為 TRUE。下列引數適用於 Singleton Pipes：
-
singleton：指示應該將管道建立為單一管路 (預設值：FALSE)。 -
shelflife：選擇性地在「單一管路」中指定快取訊息的儲存壽命到期 (秒)。它可用於「單一管線」中隱含的訊息無效化。當您傳送訊息時，也可以指定 Singleton Pipe 中的訊息
shelflife(請參閱 SEND_MESSAGE 函數 )。
語法
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;
參數
表格 - CREATE_PIPE 函數參數
| Parameter - 參數 | 描述 |
|---|---|
|
|
您正在建立的管道名稱。 當您呼叫 注意：請勿使用以 |
|
|
管道允許的最大大小 (位元組)。 管道上所有訊息的大小總計不得超過此數量。如果訊息超過此上限，就會被封鎖。 預設的 管的 65536 的預設 |
|
|
使用預設值 當您呼叫 |
|
|
使用 預設值： |
|
|
「單一管線」中快取之訊息的過期時間 (秒)。超過指定的 預設值為 |
傳回值
表格 - CREATE_PIPE 函數傳回值
| 傳回 | 描述 |
|---|---|
|
|
成功。 如果管道已存在，且嘗試建立該管道的使用者已獲授權使用該管道，則 Oracle 會傳回 0，表示成功，且管道中已存在的任何資料仍會保留。 |
|
|
無法將現有管道轉換成單一管道。
|
|
|
會為 |
|
|
發生命名衝突，因此失敗。 如果有相同名稱的管道存在且是由其他使用者所建立，則 Oracle 會發出錯誤 |
異常狀況
表格 - CREATE_PIPE 函數異常狀況
| 例外 | 描述 |
|---|---|
|
|
權限錯誤：相同名稱的管線已存在，您不能使用它 。 |
範例
創建一個 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 - 參數 | 描述 |
|---|---|
|
|
您要接收訊息的管道名稱。 名稱開頭為 |
|
|
等待訊息的時間 (秒)。逾時 0 可讓您讀取而不封鎖。 逾時不包括 預設值：常數 |
|
|
自動快取單一管線中訊息的快取函數名稱。 函數的名稱應與擁有者綱要完全限定：
預設值： |
傳回值
表格 - RECEIVE_MESSAGE 函數傳回值
| 傳回 | 描述 |
|---|---|
|
|
成功 |
|
|
已逾時。如果是隱含建立的管是空的，則將移除該管。 |
|
|
管線中的記錄對緩衝區而言太大。 |
|
|
發生岔斷。 |
8 |
只有在使用單一管路時，才能指定快取函數。 |
|
|
使用者的權限不足，無法從管道讀取。 |
使用注意事項
若要從管道接收訊息，請先呼叫 RECEIVE_MESSAGE。當您收到訊息時，該訊息會從管道中移除，因此只能收到一次訊息。對於隱含建立的管，在從管中移除最後一個記錄後，管將被移除。
如果您在呼叫 RECEIVE_MESSAGE 時指定的管道不存在，則 Oracle 會隱含地建立管道並等待接收訊息。如果訊息未在指定的逾時間隔內到達，則會傳回該呼叫並移除管道。
收到訊息之後，您必須對 UNPACK_MESSAGE 進行一或多個呼叫，才能存取訊息中的個別項目。UNPACK_MESSAGE 程序已超載以解壓縮類型為 DATE、NUMBER、VARCHAR2 的項目，另外還有兩個解壓縮 RAW 和 ROWID 項目的程序。如果您不知道您嘗試解壓縮的資料類型，請呼叫 NEXT_ITEM_TYPE 來判斷緩衝區中下一個項目的類型。
快取函數參數
Singleton Pipes 支援快取功能，可在下列兩種情況下自動快取管道中的訊息：
- 「單一管」空白。
- Singleton Pipe 中的訊息無效，因為經過
shelflife時間。
函數的名稱應與擁有者綱要完全限定：
OWNER.FUNCTION_NAMEOWNER.PACKAGE.FUNCTION_NAME
若要使用快取函數，呼叫 DBMS_PIPE.RECEIVE_MESSAGE 的目前階段作業使用者必須具有執行快取函數的必要權限。
快取函數語法
CREATE OR REPLACE FUNCTION cache_function_name (
pipename IN VARCHAR2
) RETURN INTEGER;| Parameter - 參數 | 資料類型 | 描述 |
|---|---|---|
|
|
VARCHAR2 |
Singleton Pipe 的名稱。 |
| 傳回 | 描述 |
|---|---|
| 0 | 成功 |
| 非零 | 從 DBMS_PIPE.RECEIVE_MESSAGE 傳回的失敗值 |
定義快取函數，以提供 Singleton Pipe 讀取器階段作業的複雜性封裝和抽象。快取函數內的一般作業為：
- 使用
DBMS_PIPE.CREATE_PIPE建立明確管的單一管。 - 建立要在單一管中快取的訊息。
- 傳送訊息至單一管線，選擇性地為隱含訊息指定
shelflife。
異常狀況
表格 - RECEIVE_MESSAGE 函數例外
| 例外 | 描述 |
|---|---|
|
|
權限錯誤。權限不足，無法從管道移除記錄。管道是由其他人所擁有。 |
範例
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。下列引數適用於 Singleton Pipes：
singleton：指示應該將管道建立為單一管路 (預設值：FALSE)。shelflife：選擇性地在「單一管路」中指定快取訊息的儲存壽命到期。它可用於「單一管線」中隱含的訊息無效化。此引數適用於隱含和明確的 Singleton 管道。SEND_MESSAGE 函數中指定的
shelflife值會覆寫 CREATE_PIPE 函數中為「明確單一管路」指定的shelflife，而且會是「單一管路」中快取之所有新訊息的預設值。
語法
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 - 參數 | 描述 |
|---|---|
|
|
您要在其上放置訊息的管道名稱。 如果您使用明確的管道，則這是您在呼叫 注意：請勿使用以 ' |
|
|
嘗試將訊息置於管道上的等待時間 (秒)。 預設值是常數 |
|
|
允許的管道大小上限 (位元組)。 管道上所有訊息的大小總計不得超過此數量。如果訊息超過此上限，就會被封鎖。預設值為 65536 位元組。 管的 在 65536 的預設 |
|
|
使用 預設值： |
|
|
「單一管線」中快取之訊息的過期時間 (秒)。 超過指定的 預設值為 |
傳回值
表格 - SEND_MESSAGE 函數傳回值
| 傳回 | 描述 |
|---|---|
|
|
成功。 如果管道已存在，且嘗試建立該管道的使用者已獲授權使用該管道，則 Oracle 會傳回 0，表示成功，且管道中已存在的任何資料仍會保留。 如果以 |
|
|
已逾時。 此程序可能會逾時，因為它無法取得管上的鎖頭，或是因為管仍然太滿而無法使用。如果是隱含建立的管是空的，則將移除該管。 |
|
|
發生岔斷。 如果已隱含地建立管並且是空的，則將其移除。 |
|
|
無法將現有管道轉換成單一管道。
|
|
|
會為 |
|
|
權限不足。 如果有相同名稱的管道存在且是由其他使用者所建立，則 Oracle 會發出錯誤 |
異常狀況
表格 - SEND_MESSAGE 函數異常狀況
| 例外 | 描述 |
|---|---|
|
|
權限錯誤。寫入管道的權限不足。此管是私人管路，由其他人負責。 |