DBMS_PIPEパッケージ
DBMS_PIPEパッケージを使用すると、同じインスタンス内の2つ以上のセッションが通信できます。
Oracle Autonomous AI 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シングルトン・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートなど、複数の潜在的なアプリケーションがあります。
自律型AIデータベースでは、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パッケージのサブプログラム
| サブプログラム | 摘要 |
|---|---|
|
パイプを作成します(プライベートパイプに必要) |
|
|
バッファ内の次の項目のデータ型を返します |
|
|
ローカル・バッファにメッセージを作成します。 |
|
|
名前付きパイプの内容をパージします |
|
|
名前付きパイプからローカルバッファーにメッセージをコピーします |
|
|
ローカル・バッファの内容のパージ |
|
|
名前付きパイプを削除します。 |
|
|
名前付きパイプにメッセージを送信: 名前付きパイプが存在しない場合、パブリックパイプが暗黙的に作成されます。 |
|
|
一意のセッション名を返します |
|
|
バッファ内の次の項目にアクセスします。 |
- 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は暗黙的にパイプを作成し、メッセージの受信を待機します。メッセージが指定されたタイムアウト間隔内に届かない場合は、呼び出しが戻ってパイプが削除されます。
メッセージを受信した後、メッセージ内の個々のアイテムにアクセスするには、UNPACK_MESSAGEを1つ以上コールする必要があります。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;| パラメータ | データ型 | 摘要 |
|---|---|---|
|
|
VARCHAR2 |
シングルトン・パイプの名前。 |
| 返品 | 摘要 |
|---|---|
| 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永続メッセージング・パイプの概要
パイプ機能には、外部サービス・インタフェース、デバッグ、独立したトランザクションおよびアラートなど、複数の潜在的なアプリケーションがあります。
自律型AIデータベースでは、DBMS_PIPEパッケージに、永続メッセージング・パイプをサポートするための拡張機能があります。
DBMS_PIPEの永続メッセージ:
-
非常に大きなメッセージを送信および取得する機能をサポートします。
-
多数のパイプメッセージをサポートします。
-
単一のデータベース内、複数のデータベース間、および異なるリージョン内のデータベース間でのメッセージの共有をサポートします。
-
同じクラウド・オブジェクト・ストアの場所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パッケージでは、異なる文字セットを使用するデータベース間でのメッセージの送信はサポートされていません。たとえば、AL32UTF8を使用するAutonomous AI Databaseインスタンスが1つあり、WE8MSWIN1252を使用する別のインスタンスがある場合、これらの2つのデータベース間でDBMS_PIPEを含むメッセージを送信することはできません。この場合、これらの2つのデータベース間でDBMS_PIPEを含むメッセージを送信しようとすると、エラーORA-12704が発生します。
詳細は、Autonomous AI Databaseの文字セットの選択を参照してください。
親トピック: 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は暗黙的にパイプを作成し、メッセージの受信を待機します。メッセージが指定されたタイムアウト間隔内に届かない場合は、呼び出しが戻ってパイプが削除されます。 -
メッセージを受信した後、メッセージ内の個々のアイテムにアクセスするには、
UNPACK_MESSAGEを1つ以上コールする必要があります。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と資格証明は、次のようにタイプで一致する必要があります。
-
Oracle Cloud Infrastructure Object StorageへのアクセスにネイティブURI形式を使用する場合は、資格証明オブジェクトでネイティブ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と資格証明は、次のようにタイプで一致する必要があります。
-
Oracle Cloud Infrastructure Object StorageへのアクセスにネイティブURI形式を使用する場合は、資格証明オブジェクトでネイティブ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と資格証明は、次のようにタイプで一致する必要があります。
-
Oracle Cloud Infrastructure Object StorageへのアクセスにネイティブURI形式を使用する場合は、資格証明オブジェクトでネイティブ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の形式は、使用しているクラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、DBMS_CLOUD URIフォーマットを参照してください。 |
使用上のノート
Oracle Cloud Infrastructure Object Storageを使用してメッセージを格納する場合は、Oracle Cloud InfrastructureのネイティブURIまたはSwift URIを使用できます。ただし、ロケーションURIと資格証明は、次のようにタイプで一致する必要があります。
-
Oracle Cloud Infrastructure Object StorageへのアクセスにネイティブURI形式を使用する場合は、資格証明オブジェクトでネイティブ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;
/