DBMS_PIPEパッケージ
DBMS_PIPEパッケージによって、同じインスタンスにある複数のセッションの通信を行います。
Oracle Autonomous Databaseは、Oracle Database 19cで使用可能なコアDBMS_PIPE機能と拡張機能をサポートしています。
Oracle Databaseで提供されるDBMS_PIPEのコア機能の詳細は、DBMS_PIPEを参照してください。
- DBMS_PIPEシングルトン・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートのいくつかの潜在的なアプリケーションがあります。 - シングルトン・パイプのDBMS_PIPEサブプログラムの要約
この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。 - DBMS_PIPE永続メッセージング・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立トランザクションおよびアラートのいくつかの潜在的なアプリケーションがあります。 - 永続メッセージングのDBMS_PIPEサブプログラムの要約
この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。
DBMS_PIPEシングルトン・パイプの概要
パイプ機能には、複数の潜在的なアプリケーション(外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラート)があります。
Autonomous Databaseでは、DBMS_PIPEパッケージに、シングルトン・パイプをサポートするための拡張機能があります。
DBMS_PIPEのシングルトン・パイプ機能には、次のものがあります。
-
Oracleデータベース・メモリーで、最大32,767バイトのカスタム・メッセージをキャッシュおよび取得する機能。最大32,767バイトのメッセージサイズは、シングルトンパイプを含むすべてのパイプに適用されます。以前のバージョンの
DBMS_PIPEでは、最大メッセージ・サイズが小さくなりました。 -
キャッシュされたメッセージを複数のデータベース・セッション間で同時読取りと共有します。
-
キャッシュの無効化方法:
- ユーザーによって制御される明示的なキャッシュ無効化。
- ユーザー指定のパラメータ(
shelflife)の時間間隔(秒)後のキャッシュ無効化。
-
キャッシュ用に宣言的で使いやすいPL/SQL API。
-
読取り専用データベースと読取り専用データベースの両方をサポートします。
シングルトン・パイプには、サポートされているDBMS_PIPEタイプのいずれかを指定できます。
- 暗黙的パイプ:
DBMS_PIPE.SEND_MESSAGE関数を使用して不明なパイプ名でメッセージを送信すると、自動的に作成されます。 - 明示的パイプ:ユーザー指定のパイプ名で
DBMS_PIPE.CREATE_PIPE関数を使用して作成されます。 - パブリック・パイプ:
DBMS_PIPEパッケージに対するEXECUTE権限を持つすべてのユーザーがアクセスできます - プライベート・パイプ:パイプ作成者と同じユーザーを持つセッションからアクセスできます。
親トピック: DBMS_PIPEパッケージ化
シングルトン・パイプ用のDBMS_PIPEサブプログラムのサマリー
この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。
表6-1 DBMS_PIPEパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
パイプを作成します(プライベート・パイプの場合は必須です)。 |
|
|
バッファにある次の項目のデータ・タイプを戻します。 |
|
|
ローカル・バッファにメッセージを作成します。 |
|
|
名前付きパイプの内容をパージします。 |
|
|
名前付きパイプからローカルバッファーにメッセージをコピーします。 |
|
|
ローカル・バッファの内容をパージします。 |
|
|
名前付きパイプを削除します。 |
|
|
メッセージをNamed Pipに送信します。Named Pipが存在しない場合は、パブリック・パイプが暗黙的に作成されます。 |
|
|
一意のセッション名を戻します。 |
|
|
バッファにある次の項目にアクセスします。 |
- CREATE_PIPEファンクション
このファンクションは、パブリック・パイプまたはプライベート・パイプを明示的に作成します。privateフラグがTRUEの場合、パイプ作成者がそのプライベート・パイプの所有者として割り当てられます。 - RECEIVE_MESSAGEファンクション
このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。 - SEND_MESSAGEファンクション
このファンクションは、メッセージを指定されたパイプに送信します。
親トピック: DBMS_PIPEパッケージ化
CREATE_PIPEファンクション
このファンクションは、パブリック・パイプまたはプライベート・パイプを明示的に作成します。privateフラグがTRUEの場合、パイプ作成者がそのプライベート・パイプの所有者として割り当てられます。
明示的に作成されたパイプを削除するには、REMOVE_PIPEをコールするか、またはインスタンスをシャットダウンします。
シングルトン・パイプを作成するには、singletonパラメータをTRUEに設定します。シングルトン・パイプには、次の引数が適用されます。
-
singleton: パイプをシングルトン・パイプとして作成する必要があることを示します(デフォルト値:FALSE)。 -
shelflife: オプションで、シングルトン・パイプにキャッシュされたメッセージのシェルフ有効期限(秒単位)を指定します。シングルトン・パイプ内のメッセージの暗黙的な無効化に使用できます。シングルトン・パイプのメッセージ
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;
パラメータ
表6-2 CREATE_PIPEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
作成するパイプの名前。
注意: |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この上限を超えると、そのメッセージはブロックされます。 デフォルトの パイプの デフォルトの |
|
|
デフォルトの パブリック・パイプは、 |
|
|
シングルトン・パイプを作成するには、 デフォルト値: |
|
|
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。指定した デフォルトは |
戻り値
表6-3 CREATE_PIPEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 |
|
|
既存のパイプをシングルトン・パイプに変換できませんでした。
|
|
|
|
|
|
命名競合のために失敗。 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
表6-4 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;
パラメータ
表6-5 RECEIVE_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージを受信するパイプ名。
|
|
|
メッセージ待ち時間(秒単位)。タイムアウトを0に設定すると、ブロックされずに読み込むことができます。 タイムアウトには、 デフォルト値: 定数 |
|
|
シングルトンパイプにメッセージを自動的にキャッシュするためのキャッシュ関数名。 ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
デフォルト値: |
戻り値
表6-6 RECEIVE_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
完了 |
|
|
タイムアウトしました暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
パイプにあるレコードが、バッファに対して大きすぎます。 |
|
|
割込みが発生しました |
8 |
キャッシュ関数は、シングルトンパイプを使用している場合にのみ指定できます。 |
|
|
パイプから読み込むための十分な権限がユーザーにありません。 |
使用上のノート
メッセージをパイプから受信するには、最初にRECEIVE_MESSAGEをコールします。メッセージを受信すると、メッセージはパイプから削除されるため、メッセージは1回しか受信できません。暗黙的に作成されたパイプは、最後のレコードがそのパイプから削除された後で削除されます。
RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。メッセージが指定したタイムアウト間隔内に着信しなかった場合、そのコールは戻され、パイプは削除されます。
メッセージの受信後、1つ以上のUNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。
キャッシュ・ファンクション・パラメータ
シングルトン・パイプは、次の2つのシナリオの場合に、パイプにメッセージを自動的にキャッシュするキャッシュ機能をサポートしています。
- シングルトン・パイプが空
shelflife時間が経過したため、シングルトン・パイプのメッセージが無効です。
ファンクションの名前は、所有者スキーマで完全修飾されている必要があります:
OWNER.FUNCTION_NAMEOWNER.PACKAGE.FUNCTION_NAME
キャッシュ・ファンクションを使用するには、DBMS_PIPE.RECEIVE_MESSAGEを起動する現在のセッション・ユーザーに、キャッシュ・ファンクションの実行に必要な権限が必要です。
キャッシュ関数の構文
CREATE OR REPLACE FUNCTION cache_function_name (
pipename IN VARCHAR2
) RETURN INTEGER;| パラメータ | Datatype | 説明 |
|---|---|---|
|
|
VARCHAR2 |
シングルトンパイプの名前。 |
| 戻り | 説明 |
|---|---|
| 0 | 完了 |
| 0以外 | DBMS_PIPE.RECEIVE_MESSAGEから返される失敗値 |
シングルトンパイプのリーダセッションからの複雑なカプセル化と抽象化を提供するキャッシュ関数を定義します。キャッシュ・ファンクションの一般的な操作は次のとおりです。
DBMS_PIPE.CREATE_PIPEを使用して、明示パイプ用のシングルトン・パイプを作成します。- シングルトンパイプにキャッシュするメッセージを作成します。
- メッセージをシングルトン・パイプに送信します。オプションで、暗黙的メッセージに
shelflifeを指定します。
例外
表6-7 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パラメータをTRUEに設定します。シングルトン・パイプには、次の引数が適用されます。
singleton: パイプをシングルトン・パイプとして作成する必要があることを示します(デフォルト値:FALSE)。shelflife: オプションで、シングルトン・パイプでキャッシュされたメッセージのシェルフ有効期限を指定します。シングルトン・パイプ内のメッセージの暗黙的な無効化に使用できます。この引数は、暗黙的および明示的なシングルトン・パイプに適用されます。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;パラメータ
表6-8 SEND_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージを設定するパイプの名前。 明示的なパイプを使用している場合、この名前は、 注意: |
|
|
パイプにメッセージを設定する間の待機時間(秒単位。 デフォルト値は定数 |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この上限を超えると、そのメッセージはブロックされます。デフォルトは65536バイトです。 パイプの
デフォルトの |
|
|
シングルトン・パイプを作成するには、 デフォルト値: |
|
|
シングルトン・パイプにキャッシュされるメッセージの失効時間(秒)。 指定した デフォルトは |
戻り値
表6-9 SEND_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。
|
|
|
タイムアウトしました このプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できないためにタイムアウトできます。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
割込みが発生しました 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
既存のパイプをシングルトン・パイプに変換できませんでした。
|
|
|
|
|
|
十分な権限がありません 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
表6-10 SEND_MESSAGEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
権限エラーパイプに書込みを行うための権限がありません。パイプはプライベートで、別のユーザーが所有しています。 |
DBMS_PIPE永続メッセージング・パイプの概要
パイプ機能には、複数の潜在的なアプリケーション(外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラート)があります。
Autonomous Databaseでは、DBMS_PIPEパッケージに、永続メッセージング・パイプをサポートするための拡張機能があります。
DBMS_PIPEの永続メッセージ:
-
非常に大きなメッセージを送信および取得する機能をサポートします。
-
多数のパイプメッセージをサポートします。
-
1つのデータベース内、複数のデータベース間、および異なるリージョンのデータベース間でのメッセージの共有をサポートします。
-
同じクラウド・オブジェクト・ストアの場所URIを使用して複数のパイプをサポートします。
永続メッセージング機能を使用すると、2つ以上のデータベース・セッションが、クラウド・オブジェクト・ストアに格納されているメッセージと通信できます。パイプでこの機能メッセージを使用すると、現在のデータベースのみが使用できるようにすることも、同じリージョンまたは異なるリージョンの複数のデータベースで使用できるようにすることもできます。
永続メッセージング・パイプには、サポートされている
DBMS_PIPEタイプのいずれかを指定できます。- 暗黙的パイプ:
DBMS_PIPE.SEND_MESSAGE関数を使用して不明なパイプ名でメッセージを送信すると、自動的に作成されます。 - 明示的パイプ:ユーザー指定のパイプ名で
DBMS_PIPE.CREATE_PIPE関数を使用して作成されます。 - パブリック・パイプ:
DBMS_PIPEパッケージに対するEXECUTE権限を持つすべてのユーザーがアクセスできます。 - プライベート・パイプ:パイプ作成者と同じユーザーを持つセッションからアクセスできます。
- 暗黙的パイプ:
永続メッセージを使用して異なるデータベース間でメッセージを送受信する場合、Oracleでは、メッセージの送信または受信の前に
DBMS_PIPE.CREATE_PIPEをコールすることをお薦めします。DBMS_PIPE.CREATE_PIPEを使用して明示的なパイプを作成すると、(PRIVATEパラメータをFALSEに設定するか、デフォルト値TRUEを使用して)パブリックまたはプライベートのいずれかのアクセス権限でパイプが作成されます。
親トピック: DBMS_PIPEパッケージ化
永続メッセージング用のDBMS_PIPEサブプログラムのサマリー
この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。
表6-11 DBMS_PIPEパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
パイプを作成します(プライベート・パイプの場合は必須です)。 |
|
|
グローバル |
|
|
メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するデフォルトのロケーションURIとして使用されるグローバルな |
|
|
バッファにある次の項目のデータ・タイプを戻します。 |
|
|
ローカル・バッファにメッセージを作成します。 |
|
|
名前付きパイプからローカルバッファーにメッセージをコピーします。 |
|
|
ローカル・バッファの内容をパージします。 |
|
|
名前付きパイプを削除します。 |
|
|
メッセージを名前付きパイプに送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。 |
|
|
クラウド・オブジェクト・ストアに格納されているメッセージのデフォルトの資格証明として使用される |
|
|
クラウド・オブジェクト・ストアに格納されているメッセージのデフォルトの場所URIとして使用されるグローバル |
|
|
一意のセッション名を戻します。 |
|
|
バッファにある次の項目にアクセスします。 |
- CREATE_PIPEファンクション
このファンクションは、パブリック・パイプまたはプライベート・パイプを明示的に作成します。privateフラグがTRUEの場合、パイプ作成者がそのプライベート・パイプの所有者として割り当てられます。 - GET_CREDENTIAL_NAMEファンクション
このファンクションは、メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するグローバルなcredential_name変数値を返します。 - GET_LOCATION_URIファンクション
このファンクションは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの場所URIとして使用できるグローバルなlocation_uri変数値を返します。 - RECEIVE_MESSAGEファンクション
このファンクションは、メッセージをローカル・メッセージ・バッファにコピーします。 - SEND_MESSAGEファンクション
このファンクションは、メッセージを指定されたパイプに送信します。 - SET_CREDENTIAL_NAMEプロシージャ
このプロシージャは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの資格証明として使用されるcredential_name変数を設定します。 - SET_LOCATION_URIプロシージャ
このプロシージャは、グローバルなlocation_uri変数を設定します。
親トピック: DBMS_PIPEパッケージ化
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;
パラメータ
表6-12 CREATE_PIPEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
作成するパイプの名前。
注意: |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この上限を超えると、そのメッセージはブロックされます。 デフォルトの パイプの デフォルトの |
|
|
デフォルトの パブリック・パイプは、 |
戻り値
表6-13 CREATE_PIPEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。 |
|
|
命名競合のために失敗。 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
例外
表6-14 CREATE_PIPEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
アクセス権エラー: 同名のパイプが存在するため使用できません。 |
例
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;戻り値
| 戻り値 | 説明 |
|---|---|
|
|
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 |
例
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;
パラメータ
表6-15 RECEIVE_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージを受信するパイプ名。
|
|
|
メッセージ待ち時間(秒単位)。タイムアウトを0に設定すると、ブロックされずに読み込むことができます。 タイムアウトには、 デフォルト値: 定数 |
|
|
メッセージの格納に使用するクラウド・ストアの資格証明名。
この値は、 資格証明オブジェクトには、
|
|
|
メッセージの格納に使用されるクラウド・ストアの場所URI。
この値は、 |
戻り値
表6-16 RECEIVE_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
完了 |
|
|
タイムアウトしました暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
パイプにあるレコードが、バッファに対して大きすぎます。 |
|
|
割込みが発生しました |
|
|
パイプから読み込むための十分な権限がユーザーにありません。 |
使用上のノート
-
メッセージをパイプから受信するには、最初に
RECEIVE_MESSAGEをコールします。メッセージを受信すると、メッセージはパイプから削除されるため、メッセージは1回しか受信できません。暗黙的に作成されたパイプは、最後のレコードがそのパイプから削除された後で削除されます。 -
RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。メッセージが指定したタイムアウト間隔内に着信しなかった場合、そのコールは戻され、パイプは削除されます。 -
メッセージの受信後、1つ以上の
UNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。 -
永続メッセージは、1つのプロセスによる書込みまたは読取りが保証されます。これにより、同時書込みおよび同時読取りによるメッセージ・コンテンツの不整合が回避されます。永続メッセージング・パイプを使用すると、
DBMS_PIPEは1つの操作のみを許可し、メッセージまたは受信メッセージを一度にアクティブに送信します。ただし、進行中の操作のために操作が不可能な場合、timeout値に達するまで、プロセスは定期的に再試行します。 -
Oracle Cloud Infrastructure Object Storageを使用してメッセージを格納する場合は、Oracle Cloud InfrastructureネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプで一致する必要があります。
-
ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブのOracle Cloud Infrastructure署名キー認証を使用する必要があります。
-
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。
-
例外
表6-17 RECEIVE_MESSAGEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
権限エラーパイプからレコードを削除するための権限がありません。パイプは別のユーザーが所有しています。 |
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;パラメータ
表6-18 SEND_MESSAGEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
credential_name |
メッセージの格納に使用するクラウド・ストアの資格証明名。
この値は、 資格証明オブジェクトには、
|
location_uri |
メッセージの格納に使用されるクラウド・ストアの場所URI。
この値は、 |
|
|
パイプの最大サイズ(バイト単位)。 パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。この上限を超えると、そのメッセージはブロックされます。デフォルトは65536バイトです。 パイプの
デフォルトの |
|
|
メッセージを設定するパイプの名前。 明示的なパイプを使用している場合、この名前は、 注意: |
|
|
パイプにメッセージを設定する間の待機時間(秒単位。 デフォルト値は定数 |
戻り値
表6-19 SEND_MESSAGEファンクションの戻り値
| 戻り | 説明 |
|---|---|
|
|
成功 パイプがすでに存在し、パイプを作成しようとするユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。
|
|
|
タイムアウトしました このプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できないためにタイムアウトできます。暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
割込みが発生しました 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。 |
|
|
十分な権限がありません 同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、Oracleではエラー |
使用上のノート
-
永続メッセージは、1つのプロセスによる書込みまたは読取りが保証されます。これにより、同時書込みおよび同時読取りによるメッセージ・コンテンツの不整合が回避されます。永続メッセージング・パイプを使用すると、
DBMS_PIPEは1つの操作のみを許可し、メッセージまたは受信メッセージを一度にアクティブに送信します。ただし、進行中の操作のために操作が不可能な場合、timeout値に達するまで、プロセスは定期的に再試行します。 -
Oracle Cloud Infrastructure Object Storageを使用してメッセージを格納する場合は、Oracle Cloud InfrastructureネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプで一致する必要があります。
-
ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブのOracle Cloud Infrastructure署名キー認証を使用する必要があります。
-
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。
-
例外
表6-20 SEND_MESSAGEファンクションの例外
| 例外 | 説明 |
|---|---|
|
|
権限エラーパイプに書込みを行うための権限がありません。パイプはプライベートで、別のユーザーが所有しています。 |
SET_CREDENTIAL_NAMEプロシージャ
このプロシージャは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの資格証明として使用されるcredential_name変数を設定します。
構文
DBMS_PIPE.SET_CREDENTIAL_NAME ( credential_name IN VARCHAR2 );
パラメータ
| パラメータ | 説明 |
|---|---|
|
|
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。
|
使用上のノート
Oracle Cloud Infrastructure Object Storageを使用してメッセージを格納する場合は、Oracle Cloud InfrastructureネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプで一致する必要があります。
-
ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブのOracle Cloud Infrastructure署名キー認証を使用する必要があります。
-
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。
例
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 );
パラメータ
| パラメータ | 説明 |
|---|---|
location_uri |
オブジェクトまたはファイルURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、DBMS_CLOUD URI形式を参照してください。 |
使用上のノート
Oracle Cloud Infrastructure Object Storageを使用してメッセージを格納する場合は、Oracle Cloud InfrastructureネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプで一致する必要があります。
-
ネイティブURI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトでネイティブのOracle Cloud Infrastructure署名キー認証を使用する必要があります。
-
Swift URI形式を使用してOracle Cloud Infrastructure Object Storageにアクセスする場合は、資格証明オブジェクトで認証トークン認証を使用する必要があります。
例
BEGIN
DBMS_PIPE.GET_LOCATION_URI(
location_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/