DBMS_PIPE-Paket (Singleton Pipes)

Mit dem Package DBMS_PIPE können zwei oder mehr Sessions in derselben Instanz kommunizieren.

Oracle Autonomous Database on Dedicated Exadata Infrastructure unterstützt die in Oracle Database 19c verfügbare Corefunktionalität von DBMS_PIPE sowie Erweiterungen.

Weitere Informationen über die in Oracle Database bereitgestellte DBMS_PIPE-Kernfunktionalität finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Pakete und Typenreferenz oder Oracle Database 23ai PL/SQL-Pakete und -Typenreferenz.

Verwandte Themen

DBMS_PIPE Überblick für Singleton Pipes

Die Pipe-Funktionalität hat mehrere potenzielle Anwendungen: externe Serviceschnittstelle, Debugging, unabhängige Transaktionen und Warnungen.

In Autonomous Database verfügt das Package DBMS_PIPE über erweiterte Funktionen zur Unterstützung von Singleton-Pipes. Weitere Informationen finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Packages und Typenreferenz oder Oracle Database 23ai PL/SQL-Packages und Typenreferenz.

Singleton-Pipe-Funktionen in DBMS_PIPE bieten Folgendes:

  • Fähigkeit, eine benutzerdefinierte Nachricht von bis zu 32.767 Byte im Oracle-Datenbankspeicher zu cachen und abzurufen. Die maximale Nachrichtengröße von 32.767 Byte gilt für alle Pipes, einschließlich Singleton Pipes. Frühere Versionen von DBMS_PIPE hatten eine kleinere maximale Nachrichtengröße.

  • Geben Sie die gecachte Nachricht für mehrere Datenbanksessions mit gleichzeitigen Lesevorgängen frei.

  • Methoden zur Cache-Invalidierung:

    • Vom Benutzer gesteuerte explizite Cacheinvalidierung.
    • Cacheinvalidierung nach einem vom Benutzer angegebenen Parameter (shelflife) Zeitintervall (in Sekunden).

  • Deklarative und benutzerfreundliche PL/SQL-APIs für das Caching.

  • Unterstützt schreibgeschützte und schreibgeschützte Datenbanken.

Eine Singleton-Pipe kann einer der unterstützten DBMS_PIPE-Typen sein:

  • Implizite Pipe: Wird automatisch erstellt, wenn eine Nachricht mit einem unbekannten Pipe-Namen mit der Funktion DBMS_PIPE.SEND_MESSAGE gesendet wird.
  • Explizite Pipe: Wird mit der Funktion DBMS_PIPE.CREATE_PIPE mit einem benutzerdefinierten Pipe-Namen erstellt.
  • Öffentliche Pipe: Zugänglich für jeden Benutzer mit EXECUTE-Berechtigung für Package DBMS_PIPE
  • Private Pipe: Zugriff durch Sessions mit demselben Benutzer wie der Pipe-Ersteller.

Zusammenfassung der DBMS_PIPE-Unterprogramme für Singleton-Pipes

In dieser Tabelle werden die DBMS_PIPE-Unterprogramme aufgeführt und kurz beschrieben.

Tabelle - DBMS_PIPE-Packageunterprogramme

Unterprogramm Beschreibung

Funktion CREATE_PIPE

Erstellt eine Pipe (für private Rohre erforderlich)
Funktion NEXT_ITEM_TYPE

Gibt den Datentyp des nächsten Elements im Puffer zurück
PACK_MESSAGE Prozeduren

Erstellt Meldung im lokalen Puffer
Löschprozedur

Löscht den Inhalt der benannten Pipe

Funktion RECEIVE_MESSAGE

Kopiert Nachricht von benannter Pipe in lokalen Puffer
Prozedur RESET_BUFFER

Löscht den Inhalt des lokalen Puffers
Funktion REMOVE_PIPE

Entfernt die benannte Pipe

Funktion SEND_MESSAGE

Sendet eine Nachricht an eine benannte Pipe: Dadurch wird implizit eine öffentliche Pipe erstellt, wenn die benannte Pipe nicht vorhanden ist
Funktion UNIQUE_SESSION_NAME

Gibt einen eindeutigen Sessionnamen zurück
UNPACK_MESSAGE Prozeduren

Greift auf das nächste Element im Puffer zu

Funktion CREATE_PIPE

Diese Funktion erstellt explizit eine öffentliche oder private Pipe. Wenn das Flag private TRUE lautet, wird der Pipe-Ersteller als Eigentümer der privaten Pipe zugewiesen.

Explizit erstellte Pipes können nur durch Aufruf von REMOVE_PIPE oder durch Herunterfahren der Instanz entfernt werden.

Um eine Singleton-Pipe zu erstellen, setzen Sie den Parameter singleton auf TRUE. Die folgenden Argumente gelten für Singleton Pipes:

  • singleton: Gibt an, dass die Pipe als Singleton Pipe erstellt werden soll (Standardwert: FALSE).

  • shelflife: Geben Sie optional einen Shelflife-Ablauf (in Sekunden) der gecachten Nachricht in der Singleton-Pipe an. Es kann für die implizite Invalidierung der Nachricht in Singleton Pipe verwendet werden.

    Die Nachricht shelflife in Singleton Pipe kann auch beim Senden einer Nachricht angegeben werden (siehe Funktion SEND_MESSAGE).

Syntax

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;

Parameter

Tabelle - CREATE_PIPE-Funktionsparameter

Parameter Beschreibung

pipename

Name der Pipe, die Sie erstellen.

Sie müssen diesen Namen verwenden, wenn Sie SEND_MESSAGE und RECEIVE_MESSAGE aufrufen. Dieser Name muss in der Instanz eindeutig sein.

Achtung: Verwenden Sie keine Pipe-Namen, die mit ORA$ beginnen. Diese sind für die von Oracle bereitgestellten Verfahren reserviert. Pipename darf nicht länger als 128 Byte sein und muss nicht zwischen Groß- und Kleinschreibung unterschieden werden. Derzeit darf der Name keine Globalization Support-Zeichen enthalten.

maxpipesize

Die maximal zulässige Größe für die Pipe in Byte.

Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie diesen Höchstwert überschreitet.

Der Standard maxpipesize beträgt 66536 Byte.

Die maxpipesize für ein Rohr wird Teil der Eigenschaften des Rohrs und bleibt für die Lebensdauer des Rohrs bestehen. Aufrufer von SEND_MESSAGE mit größeren Werten führen zu einer Erhöhung von maxpipesize. Anrufer mit einem kleineren Wert verwenden den vorhandenen größeren Wert.

Die Standardeinstellung maxpipesize von 65536 gilt für alle Rohre.

private

Verwendet den Standardwert TRUE, um eine private Pipe zu erstellen.

Öffentliche Pipes können implizit erstellt werden, wenn Sie SEND_MESSAGE aufrufen.

singleton

Verwenden Sie TRUE, um eine Singleton-Pipe zu erstellen.

Standardwert: FALSE

shelflife

Ablaufzeit in Sekunden einer Nachricht, die in Singleton Pipe gecacht wird. Nachdem die angegebene shelflife-Zeit überschritten wurde, ist die Nachricht nicht mehr über die Pipe zugänglich. Der Parameter shelflife gilt nur für eine Singleton Pipe.

Standardwert ist 0, was bedeutet, dass die Nachricht nie abläuft.

Rückgabewerte

Tabelle - Rückgabewerte der Funktion CREATE_PIPE

Return Beschreibung

0

Erfolgreich.

Wenn die Pipe bereits vorhanden ist und der Benutzer, der versucht, sie zu erstellen, autorisiert ist, sie zu verwenden, gibt Oracle 0 zurück und gibt den Erfolg an. Alle bereits in der Pipe enthaltenen Daten bleiben erhalten.

6

Vorhandene Pipe konnte nicht in Singleton-Pipe konvertiert werden.

  • Implizite Pipe mit mehreren vorhandenen Nachrichten kann nicht in eine Singleton Pipe konvertiert werden.
  • Bei einer expliziten Pipe, die nicht Singleton ist, kann DBMS_PIPE.SEND_MESSAGE keine Nachricht senden, bei der das Singleton-Argument auf TRUE gesetzt ist.

7

Für den Parameter shelflife wird ein Wert ungleich Null angegeben, und die Pipe ist keine Singleton-Pipe.

ORA-23322

Fehler aufgrund eines Namenskonflikts.

Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler ORA-23322 an und gibt den Namenskonflikt an.

Exceptions

Tabelle - Funktionsausnahme CREATE_PIPE

Ausnahme Beschreibung

Null pipe name

Berechtigungsfehler: Pipe mit demselben Namen ist bereits vorhanden und darf nicht verwendet werden.

Beispiel

Erstellen Sie eine Singleton Pipe mit Regal von 1 Stunde.

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

Funktion RECEIVE_MESSAGE

Diese Funktion kopiert die Nachricht in den lokalen Nachrichtenpuffer.

Syntax

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename      IN VARCHAR2,
   timeout       IN INTEGER      DEFAULT maxwait,
   cache_func    IN VARCHAR2     DEFAULT NULL)
RETURN INTEGER;

Parameter

Tabelle - RECEIVE_MESSAGE-Funktionsparameter

Parameter Beschreibung

pipename

Name der Pipe, an der Sie eine Nachricht erhalten möchten.

Namen, die mit ORA$ beginnen, sind für die Verwendung durch Oracle reserviert.

timeout

Wartezeit auf eine Nachricht in Sekunden. Mit einem Timeout von 0 können Sie lesen, ohne zu blockieren.

Der Timeout enthält nicht die Zeit, die in der Ausführungscachefunktion verbracht wurde, die im Parameter cache_func angegeben ist.

Standardwert: ist die Konstante MAXWAIT, die als 86400000 (1000 Tage) definiert ist.

cache_func

Cachen Sie den Funktionsnamen, um eine Nachricht automatisch in einer Singleton Pipe zu cachen.

Der Name der Funktion muss mit dem Eigentümerschema vollqualifiziert sein:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Standardwert: NULL

Rückgabewerte

Tabelle - Rückgabewerte der Funktion RECEIVE_MESSAGE

Return Beschreibung

0

Erfolgreich

1

Wegen Timeout abgebrochen. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.

2

Datensatz in der Pipe ist zu groß für den Puffer.

3

Interrupt aufgetreten.
8

Die Cachefunktion kann nur bei Verwendung einer Singleton Pipe angegeben werden.

ORA-23322

Der Benutzer hat keine ausreichenden Berechtigungen zum Lesen aus der Pipe.

Verwendungshinweise

Um eine Nachricht von einer Pipe zu empfangen, rufen Sie zunächst RECEIVE_MESSAGE auf. Wenn Sie eine Nachricht erhalten, wird sie aus der Pipe entfernt. Daher kann eine Nachricht nur einmal empfangen werden. Bei implizit erstellten Rohren wird die Pipe entfernt, nachdem der letzte Datensatz aus der Pipe entfernt wurde.

Wenn die Pipe, die Sie beim Aufruf von RECEIVE_MESSAGE angeben, noch nicht vorhanden ist, erstellt Oracle implizit die Pipe und wartet auf den Empfang der Nachricht. Wenn die Nachricht nicht innerhalb eines festgelegten Timeoutintervalls ankommt, wird der Aufruf zurückgegeben und die Pipe entfernt.

Nachdem Sie die Nachricht erhalten haben, müssen Sie mindestens einen Aufruf an UNPACK_MESSAGE ausführen, um auf die einzelnen Elemente in der Nachricht zuzugreifen. Die Prozedur UNPACK_MESSAGE wird überladen, um Elemente des Typs DATE, NUMBER, VARCHAR2 zu entpacken. Außerdem gibt es zwei zusätzliche Prozeduren zum Entpacken von RAW- und ROWID-Elementen. Wenn Sie den Datentyp nicht kennen, den Sie entpacken möchten, rufen Sie NEXT_ITEM_TYPE auf, um den Typ des nächsten Elements im Puffer zu bestimmen.

Cache-Funktionsparameter

Singleton Pipes unterstützen die Cache-Funktion, um eine Nachricht im Fall der folgenden beiden Szenarios automatisch in der Pipe zu cachen:

  • Singleton Pipe ist leer.
  • Die Nachricht in Singleton Pipe ist aufgrund der verstrichenen shelflife-Zeit ungültig.

Der Name der Funktion muss mit dem Eigentümerschema vollqualifiziert sein:

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Um eine Cachefunktion verwenden zu können, muss der aktuelle Sessionbenutzer, der DBMS_PIPE.RECEIVE_MESSAGE aufruft, über die erforderlichen Berechtigungen zum Ausführen der Cachefunktion verfügen.

Cache-Funktionssyntax

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Parameter Datentyp Beschreibung

pipename

 VARCHAR2

Name der Singleton Pipe.
Return Beschreibung
0 Erfolgreich
Nicht null Fehlerwert zurückgegeben von DBMS_PIPE.RECEIVE_MESSAGE

Definieren Sie eine Cache-Funktion, um Verkapselung und Abstraktion der Komplexität aus den Lesersessions von Singleton Pipe bereitzustellen. Typische Vorgänge innerhalb einer Cachefunktion wären:

  • Erstellen Sie mit DBMS_PIPE.CREATE_PIPE eine Singleton-Pipe für eine explizite Pipe.
  • Erstellen Sie die Nachricht, die in der Singleton Pipe gecacht werden soll.
  • Nachricht an Singleton Pipe senden, optional shelflife für die implizite Nachricht angeben.

Exceptions

Tabelle - RECEIVE_MESSAGE-Funktionsausnahmen

Ausnahme Beschreibung

Null pipe name

Berechtigungsfehler. Unzureichende Berechtigung zum Entfernen des Datensatzes aus der Pipe. Die Pipe ist im Besitz einer anderen Person.

Beispiel

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.receive_message(pipename   => 'MY_PIPE1',
                                        timeout    => 1,
                                        cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/

Funktion SEND_MESSAGE

Diese Funktion sendet eine Nachricht an die benannte Pipe.

Die Nachricht ist im lokalen Nachrichtenpuffer enthalten, der mit Aufrufen an PACK_MESSAGE gefüllt wurde. Sie können eine Pipe explizit mit CREATE_PIPE erstellen. Andernfalls wird sie implizit erstellt.

Um eine implizite Singleton-Pipe zu erstellen, setzen Sie den Parameter singleton auf TRUE. Die folgenden Argumente gelten für Singleton Pipes:

  • singleton: Gibt an, dass die Pipe als Singleton Pipe erstellt werden soll (Standardwert: FALSE).
  • shelflife: Geben Sie optional einen Shelflife-Ablauf der gecachten Nachricht in der Singleton-Pipe an. Es kann für die implizite Invalidierung der Nachricht in Singleton Pipe verwendet werden.

    Dieses Argument gilt für implizite und explizite Singleton-Pipes. Ein in der Funktion SEND_MESSAGE angegebener shelflife-Wert überschreibt den für die explizite Singleton-Pipe in der Funktion CREATE_PIPE angegebenen shelflife-Wert und ist der Standardwert für alle neuen Nachrichten, die in der Singleton-Pipe gecacht werden.

Syntax

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;

Parameter

Tabelle - SEND_MESSAGE-Funktionsparameter

Parameter Beschreibung

pipename

Name der Pipe, auf der Sie die Nachricht platzieren möchten.

Wenn Sie eine explizite Pipe verwenden, ist dies der Name, den Sie beim Aufruf von CREATE_PIPE angegeben haben.

Achtung: Verwenden Sie keine Pipe-Namen, die mit "ORA$" beginnen. Diese Namen sind für die von Oracle bereitgestellten Prozeduren reserviert. Pipename darf nicht länger als 128 Byte sein und muss nicht zwischen Groß- und Kleinschreibung unterschieden werden. Derzeit darf der Name keine Globalization Support-Zeichen enthalten.

timeout

Wartezeit beim Versuch, eine Nachricht in einer Pipe zu platzieren, in Sekunden.

Der Standardwert ist die Konstante MAXWAIT, die als 864000000 (1000 Tage) definiert ist.

maxpipesize

Maximal zulässige Größe für die Pipe, in Byte.

Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie diesen Höchstwert überschreitet. Der Standardwert beträgt 65536 Byte.

Die maxpipesize für ein Rohr wird Teil der Eigenschaften des Rohrs und bleibt für die Lebensdauer des Rohrs bestehen. Aufrufer von SEND_MESSAGE mit größeren Werten führen zu einer Erhöhung von maxpipesize. Anrufer mit einem kleineren Wert verwenden einfach den vorhandenen, größeren Wert.

Wenn Sie maxpipesize als Teil der Prozedur SEND_MESSAGE angeben, ist kein separater Aufruf zum Öffnen der Pipe erforderlich. Wenn Sie die Pipe explizit erstellt haben, können Sie den optionalen Parameter maxpipesize verwenden, um die Spezifikationen für die Erstellungs-Pipe-Größe außer Kraft zu setzen.

Die Standardeinstellung maxpipesize von 65536 gilt für alle Rohre.

singleton

Verwenden Sie TRUE, um eine Singleton-Pipe zu erstellen.

Standardwert: FALSE

shelflife

Ablaufzeit in Sekunden einer Nachricht, die in Singleton Pipe gecacht wird.

Nachdem die angegebene shelflife-Zeit überschritten wurde, ist die Nachricht nicht mehr über die Pipe zugänglich. Der Parameter shelflife gilt nur für eine Singleton Pipe.

Standardwert ist 0, was bedeutet, dass die Nachricht nie abläuft.

Rückgabewerte

Tabelle - Rückgabewerte der Funktion SEND_MESSAGE

Return Beschreibung

0

Erfolgreich.

Wenn die Pipe bereits vorhanden ist und der Benutzer, der versucht, sie zu erstellen, autorisiert ist, sie zu verwenden, gibt Oracle 0 zurück und gibt den Erfolg an. Alle bereits in der Pipe enthaltenen Daten bleiben erhalten.

Wenn ein Benutzer, der mit SYSDBS/SYSOPER verbunden ist, eine Pipe neu erstellt, gibt Oracle den Status 0 zurück, das Eigentum an der Pipe bleibt jedoch unverändert.

1

Wegen Timeout abgebrochen.

Dieser Vorgang kann wegen Timeout abgebrochen werden, weil er keine Sperre für die Pipe erhalten kann oder weil die Pipe für die Verwendung zu voll bleibt. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.

3

Interrupt aufgetreten.

Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.

6

Vorhandene Pipe konnte nicht in Singleton-Pipe konvertiert werden.

  • Implizite Pipe mit mehreren vorhandenen Nachrichten kann nicht in eine Singleton Pipe konvertiert werden.
  • Bei einer expliziten Pipe, die nicht Singleton ist, kann DBMS_PIPE.SEND_MESSAGE keine Nachricht senden, bei der das Singleton-Argument auf TRUE gesetzt ist.

7

Für den Parameter shelflife wird ein Wert ungleich Null angegeben, und die Pipe ist keine Singleton-Pipe.

ORA-23322

Berechtigungen reichen nicht aus.

Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler ORA-23322 an und gibt den Namenskonflikt an.

Exceptions

Tabelle - Funktionsausnahme SEND_MESSAGE

Ausnahme Beschreibung

Null pipe name

Berechtigungsfehler. Unzureichende Berechtigung zum Schreiben in die Pipe. Die Pipe ist privat und gehört einer anderen Person.