機械翻訳について

DBMS_PIPEパッケージ

DBMS_PIPEパッケージによって、同じインスタンスにある複数のセッションの通信を行います。

Oracle Autonomous Databaseは、Oracle Database 19cで使用可能なコアDBMS_PIPE機能と拡張機能をサポートしています。

Oracle Databaseで提供される主要なDBMS_PIPE機能の詳細は、DBMS_PIPEを参照してください。

親トピック: Autonomous Database提供されているパッケージ参照

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パッケージ・サブプログラム

サブプログラム 説明

CREATE_PIPEファンクション

パイプを作成します(プライベート・パイプの場合は必須です)。

NEXT_ITEM_TYPEファンクション

バッファにある次の項目のデータ・タイプを戻します。

PACK_MESSAGEプロシージャ

ローカル・バッファにメッセージを作成します。

PURGEプロシージャ

名前付きパイプの内容をパージします。

RECEIVE_MESSAGEファンクション

名前付きパイプからローカル・バッファにメッセージをコピーします。

RESET_BUFFERプロシージャ

ローカル・バッファの内容をパージします。

REMOVE_PIPEファンクション

名前付きパイプを削除します。

SEND_MESSAGEファンクション

メッセージを名前付きパイプに送信します。名前付きパイプが存在しない場合は、パブリック・パイプが暗黙的に作成されます。

UNIQUE_SESSION_NAMEファンクション

一意のセッション名を戻します。

UNPACK_MESSAGEプロシージャ

バッファにある次の項目にアクセスします。
  • 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ファンクション・パラメータ

パラメータ 説明

pipename

作成するパイプの名前。

SEND_MESSAGEおよびRECEIVE_MESSAGEをコールするときは、この名前を使用する必要があります。 この名前は、インスタンス間で一意である必要があります。

注意: ORA$で始まるパイプ名を使用しないでください。 これは、オラクル社が提供する製品用に予約されています。 パイプ名は128バイト以下で指定し、大/小文字区別がありません。 現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。

maxpipesize

パイプの最大サイズ(バイト単位)。

パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。 この最大値を超えると、そのメッセージはブロックされます。

デフォルトのmaxpipesizeは66536バイトです。

パイプのmaxpipesizeはパイプ特性の一部となり、パイプが存続するかぎり有効です。 これより大きいパイプ・サイズでSEND_MESSAGEをコールすると、maxpipesizeの値が大きくなります。 これより小さいサイズでコールした場合は、より大きい既存の値を使用します。

デフォルトの65536のmaxpipesizeは、すべてのパイプに適用されます。

private

デフォルトのTRUEを使用して、プライベート・パイプを作成します。

パブリック・パイプは、SEND_MESSAGEをコールして、暗黙的に作成できます。

singleton

TRUEを使用して、シングルトン・パイプを作成します。

デフォルト値: FALSE

shelflife

シングルトン・パイプにキャッシュされたメッセージの有効期限(秒)。 指定したshelflife時間を超えると、メッセージはパイプからアクセスできなくなります。 パラメータshelflifeは、シングルトン・パイプにのみ適用されます。

デフォルト値は0で、メッセージは期限切れになりません。

戻り値

表6-3 CREATE_PIPEファンクションの戻り値

戻る 説明

0

成功

パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。

6

既存のパイプをシングルトン・パイプに変換できませんでした。

  • 複数の既存のメッセージがある暗黙的なパイプは、シングルトン・パイプに変換できません。
  • シングルトンではない明示的なパイプの場合、DBMS_PIPE.SEND_MESSAGEはシングルトン引数をTRUEに設定してメッセージを送信できません。

7

shelflifeパラメータに0以外の値が指定され、パイプはシングルトン・パイプではありません。

ORA-23322

命名競合のために失敗。

同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、OracleではエラーORA-23322を通知して命名競合であることを示しています。

例外

表6-4 CREATE_PIPEファンクション例外

例外 説明

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;
/

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

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ファンクション・パラメータ

パラメータ 説明

pipename

メッセージを受信するパイプ名。

ORA$で始まる名前は、オラクル社で使用するために予約されています。

timeout

メッセージを待つ時間(秒単位)。 タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。

タイムアウトには、cache_funcパラメータで指定された実行キャッシュ関数に費やされた時間は含まれません。

デフォルト値: 定数MAXWAITは、86400000 (1000日)として定義されます。

cache_func

シングルトン・パイプにメッセージを自動的にキャッシュするためのキャッシュ機能名。

関数の名前は、所有者スキーマで完全修飾する必要があります:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

デフォルト値: NULL

戻り値

表6-6 RECEIVE_MESSAGEファンクションの戻り値

戻る 説明

0

成功

1

タイムアウトしました。 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

2

パイプにあるレコードが、バッファに対して大きすぎます。

3

割込みが発生しました。
8

キャッシュ機能は、シングルトン・パイプを使用する場合にのみ指定できます。

ORA-23322

パイプから読み込むための十分な権限がユーザーにありません。

使用上のノート

パイプからメッセージを受信するには、最初にRECEIVE_MESSAGEをコールします。 メッセージを受信すると、メッセージはパイプから削除されるため、メッセージは1回しか受信できません。 暗黙的に作成されたパイプは、最後のレコードがそのパイプから削除された後で削除されます。

RECEIVE_MESSAGEのコール時に指定したパイプがすでに存在しない場合、Oracleはパイプを暗黙的に作成してメッセージの受信を待ちます。 メッセージが指定したタイムアウト時間内に着信しなかった場合、そのコールは戻され、パイプは削除されます。

メッセージの受信後、1つ以上のUNPACK_MESSAGEをコールして、メッセージ内の個別の項目にアクセスする必要があります。 UNPACK_MESSAGEプロシージャは、DATE、NUMBER、VARCHAR2タイプの項目をアンパックするためにオーバーロードされ、さらに、RAWおよびROWID項目をアンパックするための2つのプロシージャがあります。 アンパックするデータのタイプが不明の場合は、NEXT_ITEM_TYPEをコールして、バッファ内にある次の項目のタイプを判別します。

キャッシュ関数パラメータ

シングルトン・パイプは、次の2つのシナリオの場合に、メッセージをパイプに自動的にキャッシュするキャッシュ機能をサポートしています:

  • シングルトン・パイプが空です。
  • shelflife時間が経過したため、シングルトン・パイプのメッセージが無効です。

関数の名前は、所有者スキーマで完全修飾する必要があります:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

キャッシュ関数を使用するには、DBMS_PIPE.RECEIVE_MESSAGEを起動する現在のセッション・ユーザーに、キャッシュ関数を実行するために必要な権限が必要です。

キャッシュ関数の構文

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
パラメータ データ型 説明

pipename

 VARCHAR2

シングルトン・パイプの名前。
戻る 説明
0 成功
Non-zero DBMS_PIPE.RECEIVE_MESSAGEから返された失敗値

シングルトン・パイプのリーダー・セッションから複雑なカプセル化と抽象化を実現するキャッシュ機能を定義します。 キャッシュ関数内の一般的な操作は次のとおりです:

  • DBMS_PIPE.CREATE_PIPEを使用して、明示的なパイプ用のシングルトン・パイプを作成します。
  • シングルトン・パイプにキャッシュするメッセージを作成します。
  • メッセージをシングルトン・パイプに送信します。オプションで、暗黙的メッセージのshelflifeを指定します。

例外

表6-7 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;
/

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

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ファンクション・パラメータ

パラメータ 説明

pipename

メッセージを設定するパイプの名前。

明示的なパイプを使用している場合、この名前は、CREATE_PIPEをコールしたときに指定した名前です。

注意: ORA$で始まるパイプ名を使用しないでください。 これは、オラクル社が提供する製品用に予約されています。 パイプ名は128バイト以下で指定し、大/小文字は区別されません。 現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。

timeout

パイプにメッセージを設定する間の待機時間(秒単位)。

デフォルト値は定数MAXWAITで、86400000(1000日)に定義されています。

maxpipesize

パイプの最大サイズ(バイト単位)。

パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。 この最大値を超えると、そのメッセージはブロックされます。 デフォルトは65536バイトです。

パイプのmaxpipesizeはパイプ特性の一部となり、パイプが存続するかぎり有効です。 これより大きいパイプ・サイズでSEND_MESSAGEをコールすると、maxpipesizeの値が大きくなります。 これより小さいサイズでコールした場合は、より大きい既存の値を使用します。

SEND_MESSAGEプロシージャの一部としてmaxpipesizeを指定すると、別のコールでパイプをオープンする必要がなくなります。 明示的にパイプを作成した場合は、オプションのmaxpipesizeパラメータを使用して、作成したパイプのサイズを上書きできます。

デフォルトの65536のmaxpipesizeは、すべてのパイプに適用されます。

singleton

TRUEを使用して、シングルトン・パイプを作成します。

デフォルト値: FALSE

shelflife

シングルトン・パイプにキャッシュされたメッセージの有効期限(秒)。

指定したshelflife時間を超えると、メッセージはパイプからアクセスできなくなります。 パラメータshelflifeは、シングルトン・パイプにのみ適用されます。

デフォルト値は0で、メッセージは期限切れになりません。

戻り値

表6-9 SEND_MESSAGEファンクションの戻り値

戻る 説明

0

成功。

パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。

SYSDBS/SYSOPERとして接続したユーザーがパイプを再作成した場合、Oracleはステータス0(ゼロ)を戻しますが、そのパイプの所有者は変更されないままです。

1

タイムアウトしました。

このプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトできます。 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

3

割込みが発生しました。

暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

6

既存のパイプをシングルトン・パイプに変換できませんでした。

  • 複数の既存のメッセージがある暗黙的なパイプは、シングルトン・パイプに変換できません。
  • シングルトンではない明示的なパイプの場合、DBMS_PIPE.SEND_MESSAGEはシングルトン引数をTRUEに設定してメッセージを送信できません。

7

shelflifeパラメータに0以外の値が指定され、パイプはシングルトン・パイプではありません。

ORA-23322

権限が不十分です。

同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、OracleではエラーORA-23322を通知して命名競合であることを示しています。

例外

表6-10 SEND_MESSAGEファンクション例外

例外 説明

Null pipe name

アクセス権エラー。 パイプに書込みを行うための権限が不十分です。 パイプはプライベートで、別のユーザーが所有しています。

親トピック: シングルトン・パイプのDBMS_PIPEサブプログラムの要約

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パッケージは、異なる文字セットを使用するデータベース間でのメッセージの送信をサポートしていません。 たとえば、AL32UTF8を使用する1つのAutonomous Databaseインスタンスと、WE8MSWIN1252を使用する別のインスタンスがある場合、これら2つのデータベース間でDBMS_PIPEを含むメッセージを送信することはできません。 この場合、これらの2つのデータベース間でDBMS_PIPEのメッセージを送信しようとすると、エラーORA-12704が発生します。

詳細については、「Autonomous Databaseの文字セットの選択」を参照してください。

親トピック: DBMS_PIPEパッケージ

永続メッセージング用のDBMS_PIPEサブプログラムの要約

この表は、DBMS_PIPEサブプログラムを示し、簡単に説明しています。

表6-11 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の場合、パイプ作成者がそのプライベート・パイプの所有者として割り当てられます。
  • 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ファンクション・パラメータ

パラメータ 説明

pipename

作成するパイプの名前。

SEND_MESSAGEおよびRECEIVE_MESSAGEをコールするときは、この名前を使用する必要があります。 この名前は、インスタンス間で一意である必要があります。

注意: ORA$で始まるパイプ名を使用しないでください。 これは、オラクル社が提供する製品用に予約されています。 パイプ名は128バイト以下で指定し、大/小文字区別がありません。 現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。

maxpipesize

パイプの最大サイズ(バイト単位)。

パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。 この最大値を超えると、そのメッセージはブロックされます。

デフォルトのmaxpipesizeは66536バイトです。

パイプのmaxpipesizeはパイプ特性の一部となり、パイプが存続するかぎり有効です。 これより大きいパイプ・サイズでSEND_MESSAGEをコールすると、maxpipesizeの値が大きくなります。 これより小さいサイズでコールした場合は、より大きい既存の値を使用します。

デフォルトの65536のmaxpipesizeは、すべてのパイプに適用されます。

private

デフォルトのTRUEを使用して、プライベート・パイプを作成します。

パブリック・パイプは、SEND_MESSAGEをコールして、暗黙的に作成できます。

戻り値

表6-13 CREATE_PIPEファンクションの戻り値

戻る 説明

0

成功

パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。

ORA-23322

命名競合のために失敗。

同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、OracleではエラーORA-23322を通知して命名競合であることを示しています。

例外

表6-14 CREATE_PIPEファンクション例外

例外 説明

Null pipe name

アクセス権エラー: 同名のパイプが存在するため使用できません。

例

MY_PIPE1という名前の明示的なプライベートの作成

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

GET_CREDENTIAL_NAMEファンクション

この関数は、メッセージがクラウド・オブジェクト・ストアに格納されるときに使用するグローバルcredential_name変数値を返します。

構文

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

戻り値

戻り値 説明

credential_name

Cloud Object Storageにアクセスするための資格証明の名前。

例

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

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;
/

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

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ファンクション・パラメータ

パラメータ 説明

pipename

メッセージを受信するパイプ名。

ORA$で始まる名前は、オラクル社で使用するために予約されています。

timeout

メッセージを待つ時間(秒単位)。 タイムアウトを0(ゼロ)に指定すると、ブロックされずに読み込むことができます。

タイムアウトには、cache_funcパラメータで指定されたキャッシュ関数の実行に費やされた時間は含まれません。

デフォルト値: 定数MAXWAITは、86400000 (1000日)として定義されます。

credential_name

メッセージの格納に使用されるクラウド・ストアの資格証明名。

credential_nameは、デフォルトでNULLとして初期化されるパッケージ引数です。

この値は、DBMS_PIPE.RECEIVE_MESSAGEをコールする前に設定できます。 渡されたパラメータ値は、グローバル変数の値よりも優先されます。

資格証明オブジェクトには、DBMS_PIPE.RECEIVE_MESSAGEを実行しているユーザーによるEXECUTEおよびREAD/WRITE権限が必要です。

credential_name値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。 リソース・プリンシパル・ベースの認証の詳細は、「リソースにアクセスするためのポリシーおよびロールの構成」を参照してください。

location_uri

メッセージの格納に使用されるクラウド・ストアのロケーションURI。

location_uriは、デフォルトでNULLとして初期化されるグローバル変数です。

この値は、DBMS_PIPE.RECEIVE_MESSAGEをコールする前に設定できます。 渡されたパラメータ値は、グローバル変数の値よりも優先されます。

戻り値

表6-16 RECEIVE_MESSAGEファンクションの戻り値

戻る 説明

0

成功

1

タイムアウトしました。 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

2

パイプにあるレコードが、バッファに対して大きすぎます。

3

割込みが発生しました。

ORA-23322

パイプから読み込むための十分な権限がユーザーにありません。

使用上のノート

  • パイプからメッセージを受信するには、最初に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ファンクションの例外

例外 説明

Null pipe name

アクセス権エラー。 パイプからレコードを削除するための権限が不十分です。 パイプは別のユーザーが所有しています。

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

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

メッセージの格納に使用されるクラウド・ストアの資格証明名。

credential_nameは、デフォルトでNULLとして初期化されるパッケージ引数です。

この値は、DBMS_PIPE.SEND_MESSAGEをコールする前に設定できます。 渡されたパラメータ値は、グローバル変数の値よりも優先されます。

資格証明オブジェクトには、DBMS_PIPE.SEND_MESSAGEを実行しているユーザーによるEXECUTEおよびREAD/WRITE権限が必要です。

credential_name値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。 リソース・プリンシパル・ベースの認証の詳細は、「リソースにアクセスするためのポリシーおよびロールの構成」を参照してください。

location_uri

メッセージの格納に使用されるクラウド・ストアのロケーションURI。

location_uriは、デフォルトでNULLとして初期化されるグローバル変数です。

この値は、DBMS_PIPE.SEND_MESSAGEをコールする前に設定できます。 渡されたパラメータ値は、グローバル変数の値よりも優先されます。

maxpipesize

パイプの最大サイズ(バイト単位)。

パイプ上のすべてのメッセージの合計サイズは、この数を超えることはできません。 この最大値を超えると、そのメッセージはブロックされます。 デフォルトは65536バイトです。

パイプのmaxpipesizeはパイプ特性の一部となり、パイプが存続するかぎり有効です。 これより大きいパイプ・サイズでSEND_MESSAGEをコールすると、maxpipesizeの値が大きくなります。 これより小さいサイズでコールした場合は、より大きい既存の値を使用します。

SEND_MESSAGEプロシージャの一部としてmaxpipesizeを指定すると、別のコールでパイプをオープンする必要がなくなります。 明示的にパイプを作成した場合は、オプションのmaxpipesizeパラメータを使用して、作成したパイプのサイズを上書きできます。

デフォルトの65536のmaxpipesizeは、すべてのパイプに適用されます。

pipename

メッセージを設定するパイプの名前。

明示的なパイプを使用している場合、この名前は、CREATE_PIPEをコールしたときに指定した名前です。

注意: ORA$で始まるパイプ名を使用しないでください。 これは、オラクル社が提供する製品用に予約されています。 パイプ名は128バイト以下で指定し、大/小文字は区別されません。 現時点では、名前にグローバリゼーション・サポート文字を含めることはできません。

timeout

パイプにメッセージを設定する間の待機時間(秒単位)。

デフォルト値は定数MAXWAITで、86400000(1000日)に定義されています。

戻り値

表6-19 SEND_MESSAGEファンクションの戻り値

戻る 説明

0

成功。

パイプが存在し、パイプを作成するユーザーにそのパイプの使用が認可されている場合、Oracleは0(ゼロ)を戻して成功であることを示し、パイプ内のデータはそのまま残ります。

SYSDBS/SYSOPERとして接続したユーザーがパイプを再作成した場合、Oracleはステータス0(ゼロ)を戻しますが、そのパイプの所有者は変更されないままです。

1

タイムアウトしました。

このプロシージャは、パイプでロックが取得できないか、またはパイプがいっぱいで使用できない理由でタイムアウトできます。 暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

3

割込みが発生しました。

暗黙的に作成されたパイプが空の場合、そのパイプは削除されます。

ORA-23322

権限が不十分です。

同じ名前のパイプが存在し、別のユーザーがそのパイプを作成した場合、OracleではエラーORA-23322を通知して命名競合であることを示しています。

使用上のノート

  • 永続メッセージは、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ファンクション例外

例外 説明

Null pipe name

アクセス権エラー。 パイプに書込みを行うための権限が不十分です。 パイプはプライベートで、別のユーザーが所有しています。

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

SET_CREDENTIAL_NAMEプロシージャ

このプロシージャは、パイプ・メッセージがクラウド・オブジェクト・ストアに格納されるときにデフォルトの資格証明として使用されるcredential_name変数を設定します。

構文

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

パラメータ

パラメータ 説明

credential_name

Cloud Object Storageにアクセスするための資格証明の名前。

credential_name値は、OCIリソース・プリンシパル、Azureサービス・プリンシパル、Amazonリソース名(ARN)またはGoogleサービス・アカウントです。 リソース・プリンシパル・ベースの認証の詳細は、「リソースにアクセスするためのポリシーおよびロールの構成」を参照してください。

使用上のノート

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;
/

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約

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と資格証明は、次のように型で一致する必要があります:

  • ネイティブ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;
/

親トピック: 永続メッセージング用のDBMS_PIPEサブプログラムの要約