DBMS_PIPE-Package (Singleton Pipes)

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

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure unterstützt die DBMS_PIPE-Kernfunktionalität wie in Oracle Database 19c verfügbar sowie Erweiterungen.

Weitere Informationen zur Oracle Database-Core-Funktionalität DBMS_PIPE finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Packages und Typenreferenz oder Oracle Database 26ai PL/SQL-Packages und Typenreferenz.

DBMS_PIPE - Übersicht für Singleton Pipes

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

In einer autonomen AI-Datenbank 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 and Types Reference oder Oracle Database 26ai PL/SQL Packages and Types Reference.

Die Singleton Pipe-Funktionen in DBMS_PIPE bieten Folgendes:

Möglichkeit, 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 geringere maximale Nachrichtengröße.
Geben Sie die gecachte Nachricht für mehrere Datenbanksessions mit gleichzeitigen Lesezugriffen frei.
Cacheinvalidierungsmethoden:
- Explizite Cacheinvalidierung, die vom Benutzer gesteuert wird.
- Cacheinvalidierung nach einem vom Benutzer angegebenen Parameterzeitintervall (shelflife) (in Sekunden).
Deklarativ und einfach zu verwendende PL/SQL-APIs für das Caching.
Unterstützt sowohl schreibgeschützte als auch 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: Zugriff durch jeden Benutzer mit der Berechtigung EXECUTE für das Package DBMS_PIPE
Private Pipe: Zugriff durch Sessions mit demselben Benutzer wie der Pipe-Ersteller.

Übersicht über DBMS_PIPE-Unterprogramme für Singleton-Pipes

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

Unterprogramm	Beschreibung
CREATE_PIPE-Funktion	Erstellt eine Pipe (für private Pipes erforderlich)
NEXT_ITEM_TYPE (Funktion) Oracle Database 19c PL/SQL-Packages und Typenreferenz Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Gibt den Datentyp des nächsten Elements im Puffer zurück
PACK_MESSAGE-Verfahren Referenz zu Oracle Database 19c PL/SQL-Packages und -Typen Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Build-Nachricht im lokalen Puffer
LÖSCHEN Oracle Database 19c PL/SQL-Packages und Typenreferenz Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Löscht den Inhalt der benannten Pipe
RECEIVE_MESSAGE-Funktion	Kopiert Nachricht aus benannter Pipe in lokalen Puffer
Prozedur RESET_BUFFER Oracle Database 19c PL/SQL-Packages und Typenreferenz Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Löscht den Inhalt des lokalen Puffers
REMOVE_PIPE-Funktion Oracle Database 19c PL/SQL-Packages und Typenreferenz Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Entfernt die benannte Pipe
SEND_MESSAGE-Funktion	Sendet Nachricht an benannte Pipe: Dadurch wird implizit eine öffentliche Pipe erstellt, wenn die benannte Pipe nicht vorhanden ist
UNIQUE_SESSION_NAME-Funktion Referenz zu Oracle Database 19c PL/SQL-Packages und -Typen Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Gibt einen eindeutigen Sessionnamen zurück
UNPACK_MESSAGE-Verfahren Referenz zu Oracle Database 19c PL/SQL-Packages und -Typen Referenz zu Oracle Database 26ai PL/SQL-Packages und -Typen	Greift auf das nächste Element im Puffer zu

CREATE_PIPE-Funktion

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

Explizit erstellte Pipes können nur entfernt werden, indem REMOVE_PIPE aufgerufen oder die Instanz heruntergefahren wird.

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 ein Ablaufdatum (in Sekunden) der gecachten Nachricht in der Singleton Pipe an. Sie kann für die implizite Invalidierung von Nachrichten in Singleton Pipe verwendet werden.

Die Nachricht shelflife in der Singleton Pipe kann auch angegeben werden, wenn Sie eine Nachricht senden (siehe SEND_MESSAGE-Funktion).

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

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 instanzübergreifend 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 die Groß-/Kleinschreibung wird nicht beachtet. Derzeit darf der Name keine Zeichen für die Globalisierungsunterstützung 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 dieses Maximum überschreitet. Der Standardwert für `maxpipesize` ist 66536 Byte. Die `maxpipesize` für ein Rohr wird Teil der Eigenschaften des Rohres und bleibt für die Lebensdauer des Rohres bestehen. Aufrufer von `SEND_MESSAGE` mit größeren Werten führen dazu, dass `maxpipesize` erhöht wird. Anrufer mit einem kleineren Wert verwenden den vorhandenen, größeren Wert. Der Standardwert `maxpipesize` von 65536 gilt für alle Pipes.
`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 in Singleton Pipe gecachten Nachricht. 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. Der Standardwert ist `0`. Dies bedeutet, dass die Nachricht nie abläuft.

Rückgabewerte

Return	Beschreibung
`0`	Erfolgreich. Wenn die Pipe bereits vorhanden ist und der Benutzer, der versucht, sie zu erstellen, zur Verwendung autorisiert ist, gibt Oracle 0 zurück, was den Erfolg anzeigt, und alle Daten, die sich bereits in der Pipe befinden, 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, deren 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, der auf den Namenskonflikt hinweist.

Exceptions

Ausnahme	Beschreibung
`Null pipe name`	Berechtigungsfehler: Pipe mit demselben Namen ist bereits vorhanden, und Sie dürfen ihn nicht verwenden.

Beispiel

Erstellen Sie eine Singleton Pipe mit einer Haltbarkeit von 1 Stunde.

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

RECEIVE_MESSAGE-Funktion

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

Parameter	Beschreibung
`pipename`	Name der Pipe, auf der eine Nachricht empfangen werden soll. Namen, die mit `ORA$` beginnen, sind für die Verwendung durch Oracle reserviert.
`timeout`	Wartezeit für 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: 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`

pipename

Name der Pipe, auf der eine Nachricht empfangen werden soll.

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

timeout

Wartezeit für 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: 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`	Eine Unterbrechung ist aufgetreten.
`8`	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 zuerst 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 das Rohr entfernt, nachdem der letzte Datensatz aus dem Rohr 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 vornehmen, 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 Typ der Daten, die Sie entpacken möchten, nicht kennen, rufen Sie NEXT_ITEM_TYPE auf, um den Typ des nächsten Elements im Puffer zu bestimmen.

Cachefunktionsparameter

Singleton Pipes unterstützt die Cache-Funktion, um eine Nachricht automatisch in der Pipe zu cachen, falls die folgenden beiden Szenarios auftreten:

Singleton Pipe ist leer.
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.

Cachefunktionssyntax

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 von`DBMS_PIPE.RECEIVE_MESSAGE` zurückgegeben

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

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

Exceptions

Ausnahme	Beschreibung
`Null pipe name`	Berechtigungsfehler. Unzureichende Berechtigung zum Entfernen des Datensatzes aus der Pipe. Die Pipe gehört 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;
/

SEND_MESSAGE-Funktion

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 Ablauf der gecachten Nachricht in der Singleton Pipe an. Sie kann für die implizite Invalidierung von Nachrichten in Singleton Pipe verwendet werden.

Dieses Argument gilt sowohl für implizite als auch explizite Singleton-Pipes. Ein in der SEND_MESSAGE-Funktion angegebener shelflife-Wert überschreibt die shelflife, die für die explizite Singleton Pipe in

CREATE_PIPE-Funktion 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 - Parameter der Funktion SEND_MESSAGE

Parameter	Beschreibung
`pipename`	Name der Pipe, auf der die Nachricht abgelegt werden soll. 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 Verwendung durch von Oracle bereitgestellte Prozeduren reserviert. Pipename darf nicht länger als 128 Byte sein und die Groß-/Kleinschreibung wird nicht beachtet. Derzeit darf der Name keine Zeichen für die Globalisierungsunterstützung enthalten.
`timeout`	Wartezeit beim Versuch, eine Nachricht in einer Pipe zu platzieren, in Sekunden. Der Standardwert ist die Konstante `MAXWAIT`, die als 86400000 (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 dieses Maximum überschreitet. Der Standardwert beträgt 65536 Byte. Die `maxpipesize` für ein Rohr wird Teil der Eigenschaften des Rohres und bleibt für die Lebensdauer des Rohres bestehen. Aufrufer von `SEND_MESSAGE` mit größeren Werten führen dazu, dass `maxpipesize` erhöht wird. 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. Der Standardwert `maxpipesize` von 65536 gilt für alle Pipes.
`singleton`	Verwenden Sie `TRUE`, um eine Singleton Pipe zu erstellen. Standardwert: `FALSE`
`shelflife`	Ablaufzeit in Sekunden einer in Singleton Pipe gecachten Nachricht. 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. Der Standardwert ist `0`. Dies bedeutet, dass die Nachricht nie abläuft.

Rückgabewerte

Return	Beschreibung
`0`	Erfolgreich. Wenn die Pipe bereits vorhanden ist und der Benutzer, der sie zu erstellen versucht, zur Verwendung autorisiert ist, gibt Oracle 0 zurück, was den Erfolg anzeigt, und alle Daten, die sich bereits in der Pipe befinden, bleiben erhalten. Wenn ein als `SYSDBS`/`SYSOPER` verbundener Benutzer eine Pipe neu erstellt, gibt Oracle den Status 0 zurück, der Eigentümer der Pipe bleibt jedoch unverändert.
`1`	Wegen Timeout abgebrochen. Bei diesem Verfahren kann ein Timeout auftreten, weil es keine Sperre für das Rohr erhalten kann oder weil das Rohr zu voll ist, um verwendet zu werden. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt.
`3`	Eine Unterbrechung ist 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, deren 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`	Unzureichende Berechtigungen. Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler `ORA-23322` an, der auf den Namenskonflikt hinweist.

Exceptions

Ausnahme	Beschreibung
`Null pipe name`	Berechtigungsfehler. Unzureichende Berechtigung zum Schreiben in die Pipe. Die Pfeife ist privat und gehört jemand anderem.

DBMS_PIPE-Package (Singleton Pipes)

DBMS_PIPE - Übersicht für Singleton Pipes

Übersicht über DBMS_PIPE-Unterprogramme für Singleton-Pipes

CREATE_PIPE-Funktion

Syntax

Parameter

Rückgabewerte

Exceptions

Beispiel

RECEIVE_MESSAGE-Funktion

Syntax

Parameter

Rückgabewerte

Verwendungshinweise

Cachefunktionsparameter

Cachefunktionssyntax

Exceptions

Beispiel

SEND_MESSAGE-Funktion

Syntax

Parameter

Rückgabewerte

Exceptions

Verwandte Inhalte