Package DBMS_PIPE (Singleton Pipes)

Il pacchetto DBMS_PIPE consente a due o più sessioni nella stessa istanza di comunicare.

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure supporta la funzionalità DBMS_PIPE di base, come disponibile in Oracle Database 19c, oltre alle estensioni.

Per informazioni dettagliate sulla funzionalità DBMS_PIPE di base fornita in Oracle Database, vedere DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference oppure Oracle Database 26ai PL/SQL Packages and Types Reference.

Panoramica di DBMS_PIPE per le tubazioni Singleton

La funzionalità Pipe ha diverse potenziali applicazioni: interfaccia di servizio esterna, debug, transazioni indipendenti e avvisi.

In Autonomous AI Database, il package DBMS_PIPE ha esteso le funzionalità per supportare i tubi singleton. Per ulteriori informazioni, vedere DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference oppure Oracle Database 26ai PL/SQL Packages and Types Reference.

Le funzioni della pipe Singleton in DBMS_PIPE forniscono quanto riportato di seguito.

Possibilità di inserire nella cache e recuperare un messaggio personalizzato, fino a 32.767 byte, nella memoria del database Oracle. La dimensione massima del messaggio di 32.767 byte è applicabile a tutti i tubi, inclusi i tubi Singleton. Le versioni precedenti di DBMS_PIPE avevano una dimensione massima del messaggio inferiore.
Condividere il messaggio inserito nella cache in più sessioni di database con letture simultanee.
Metodi di invalidamento della cache:
- Invalidamento esplicito della cache controllato dall'utente.
- Invalidamento della cache dopo un intervallo di tempo (in secondi) del parametro specificato dall'utente (shelflife).
API PL/SQL dichiarative e di facile utilizzo per l'inserimento nella cache.
Supporta database di sola lettura e lettura-scrittura.

Un tubo Singleton può essere uno qualsiasi dei tipi DBMS_PIPE supportati:

Tubo implicito: creato automaticamente quando un messaggio viene inviato con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
Tubo esplicito: creato utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome di pipe specificato dall'utente.
Public Pipe: accessibile da qualsiasi utente con autorizzazione EXECUTE sul pacchetto DBMS_PIPE
Tubo privato: accessibile da sessioni con lo stesso utente dell'autore della pipe.

Riepilogo dei sottoprogrammi DBMS_PIPE per Singleton Pipes

Questa tabella elenca i sottoprogrammi DBMS_PIPE e li descrive brevemente.

Sottoprogramma	Descrizione
Funzione CREATE_PIPE	Crea un tubo (necessario per tubi privati)
Funzione NEXT_ITEM_TYPE Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Restituisce il tipo di dati dell'elemento successivo nel buffer
Procedure PACK_MESSAGE Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Genera il messaggio nel buffer locale
Procedura di rimozione Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Rimuove i contenuti della pipe denominata
Funzione RECEIVE_MESSAGE	Copia il messaggio dalla named pipe nel buffer locale
Procedura RESET_BUFFER Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Rimuove i contenuti del buffer locale
Funzione REMOVE_PIPE Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Rimuove la pipe denominata
Funzione SEND_MESSAGE	Invia un messaggio alla pipe denominata: questa operazione crea implicitamente una pipe pubblica se la pipe denominata non esiste
Funzione UNIQUE_SESSION_NAME Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Restituisce un nome sessione univoco
Procedure UNPACK_MESSAGE Pacchetti e riferimenti ai tipi di Oracle Database 19c PL/SQL Oracle Database 26ai - Pacchetti e riferimenti dei tipi PL/SQL	Accede all'elemento successivo nel buffer

Funzione CREATE_PIPE

Questa funzione crea in modo esplicito una pipe pubblica o privata. Se il flag private è TRUE, l'autore della pipe viene assegnato come proprietario della pipe privata.

I tubi creati in modo esplicito possono essere rimossi solo chiamando REMOVE_PIPE o chiudendo l'istanza.

Per creare una Singleton Pipe, impostare il parametro singleton su TRUE. I seguenti argomenti sono applicabili a Singleton Pipes:

singleton: indica che la pipe deve essere creata come pipe singleton (valore predefinito: FALSE).
shelflife: è possibile specificare una scadenza della durata di conservazione (in secondi) del messaggio inserito nella cache nel tubo Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

Il messaggio shelflife in Singleton Pipe può essere specificato anche quando si invia un messaggio (vedere Funzione SEND_MESSAGE).

Sintassi

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;

Parametri

Parametro	Descrizione
`pipename`	Nome della pipe che si sta creando. È necessario utilizzare questo nome quando si chiamano `SEND_MESSAGE` e `RECEIVE_MESSAGE`. Questo nome deve essere univoco nell'istanza. Attenzione: non utilizzare nomi di pipe che iniziano con `ORA$`. Questi sono riservati all'utilizzo da parte delle procedure fornite da Oracle. Il nome della pipeline non deve superare i 128 byte e non fa distinzione tra maiuscole e minuscole. Al momento, il nome non può contenere caratteri del Supporto alla globalizzazione.
`maxpipesize`	La dimensione massima consentita per la pipe, in byte. La dimensione totale di tutti i messaggi nella pipe non può superare questa quantità. Il messaggio viene bloccato se supera questo limite massimo. Il valore predefinito `maxpipesize` è 66536 byte. Il `maxpipesize` per un tubo diventa parte delle caratteristiche del tubo e persiste per la vita del tubo. I chiamanti di `SEND_MESSAGE` con valori maggiori causano l'aumento di `maxpipesize`. I chiamanti con un valore inferiore utilizzano il valore esistente e più grande. Il valore predefinito `maxpipesize` di 65536 è applicabile a tutti i tubi.
`private`	Utilizza il valore predefinito `TRUE` per creare una pipe privata. I tubi pubblici possono essere creati in modo implicito quando si chiama `SEND_MESSAGE`.
`singleton`	Utilizzare `TRUE` per creare una Singleton Pipe. Valore predefinito: `FALSE`
`shelflife`	Tempo di scadenza in secondi di un messaggio inserito nella cache in Singleton Pipe. Dopo il superamento dell'ora `shelflife` specificata, il messaggio non sarà più accessibile dalla pipe. Il parametro `shelflife` è applicabile solo a una Singleton Pipe. Il valore predefinito è `0`, il che significa che il messaggio non scade mai.

Valori restituiti

Return	Descrizione
`0`	Operazione riuscita. Se la pipe esiste già e l'utente che sta tentando di crearla è autorizzato a utilizzarla, Oracle restituisce 0, indicando l'esito positivo e tutti i dati già presenti nella pipe rimangono.
`6`	Impossibile convertire la pipe esistente in pipe singleton. Impossibile convertire una pipe implicita con più messaggi esistenti in una pipe Singleton. Per una pipe esplicita che non è Singleton, `DBMS_PIPE.SEND_MESSAGE` non può inviare un messaggio con l'argomento singleton impostato su `TRUE`.
`7`	Viene fornito un valore diverso da zero per il parametro `shelflife` e la pipe non è una pipe singleton.
`ORA-23322`	Errore a causa di un conflitto di denominazione. Se esiste una pipe con lo stesso nome ed è stata creata da un utente diverso, Oracle segnala l'errore `ORA-23322`, indicando il conflitto di denominazione.

Eccezioni

Eccezione	Descrizione
`Null pipe name`	Errore di autorizzazione: un pipe con lo stesso nome esiste già e non è consentito utilizzarlo.

Esempio

Crea un tubo Singleton con durata di 1 ora.

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

Funzione RECEIVE_MESSAGE

Questa funzione copia il messaggio nel buffer dei messaggi locale.

Sintassi

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

Parametri

Tabella - Parametri funzione RECEIVE_MESSAGE

Parametro Descrizione

Parametro	Descrizione
`pipename`	Nome della pipe in cui si desidera ricevere un messaggio. I nomi che iniziano con `ORA$` sono riservati all'uso da parte di Oracle.
`timeout`	Tempo di attesa di un messaggio, in secondi. Un timeout di 0 ti permette di leggere senza bloccare. Il timeout non include il tempo trascorso nella funzione della cache di esecuzione specificata nel parametro `cache_func`. Valore predefinito: è la costante `MAXWAIT`, definita come 86400000 (1000 giorni).
`cache_func`	Nome della funzione cache per inserire automaticamente nella cache un messaggio in una pipe Singleton. Il nome della funzione deve essere completamente qualificato con lo schema proprietario: `OWNER.FUNCTION_NAME` `OWNER.PACKAGE.FUNCTION_NAME` Valore predefinito: `NULL`

pipename

Nome della pipe in cui si desidera ricevere un messaggio.

I nomi che iniziano con ORA$ sono riservati all'uso da parte di Oracle.

timeout

Tempo di attesa di un messaggio, in secondi. Un timeout di 0 ti permette di leggere senza bloccare.

Il timeout non include il tempo trascorso nella funzione della cache di esecuzione specificata nel parametro cache_func.

Valore predefinito: è la costante MAXWAIT, definita come 86400000 (1000 giorni).

cache_func

Nome della funzione cache per inserire automaticamente nella cache un messaggio in una pipe Singleton.

Il nome della funzione deve essere completamente qualificato con lo schema proprietario:

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

Valore predefinito: NULL

Valori restituiti

Tabella - Valori restituiti funzione RECEIVE_MESSAGE

Return	Descrizione
`0`	Operazione riuscita
`1`	Timeout. Se la pipe è stata creata implicitamente ed è vuota, viene rimossa.
`2`	Il record nella pipe è troppo grande per il buffer.
`3`	Si è verificata un'interruzione.
`8`	La funzione cache può essere specificata solo quando si utilizza un tubo Singleton.
`ORA-23322`	L'utente non dispone di privilegi sufficienti per leggere dalla pipe.

Note sull'uso

Per ricevere un messaggio da una pipe, chiamare prima RECEIVE_MESSAGE. Quando si riceve un messaggio, viene rimosso dalla pipe; quindi, un messaggio può essere ricevuto solo una volta. Per i tubi creati in modo implicito, la pipe viene rimossa dopo la rimozione dell'ultimo record dalla pipe.
Se la pipe specificata quando si chiama RECEIVE_MESSAGE non esiste già, Oracle crea la pipe in modo implicito e attende di ricevere il messaggio. Se il messaggio non arriva entro un determinato intervallo di timeout, la chiamata viene restituita e la pipe viene rimossa.
Dopo aver ricevuto il messaggio, è necessario effettuare una o più chiamate a UNPACK_MESSAGE per accedere ai singoli elementi del messaggio. La procedura UNPACK_MESSAGE viene sovraccaricata per disimballare gli elementi di tipo DATE, NUMBER, VARCHAR2 e sono disponibili due procedure aggiuntive per disimballare gli elementi RAW e ROWID. Se non si conosce il tipo di dati che si sta tentando di decomprimere, chiamare NEXT_ITEM_TYPE per determinare il tipo di elemento successivo nel buffer.

Parametro funzione cache

Singleton Pipes supporta la funzione cache per inserire automaticamente nella cache un messaggio nella pipe in caso dei seguenti due scenari:

Singleton Pipe è vuoto.
Il messaggio in Singleton Pipe non è valido a causa del tempo trascorso di shelflife.

Il nome della funzione deve essere completamente qualificato con lo schema proprietario:

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

Per utilizzare una funzione cache, l'utente della sessione corrente che richiama DBMS_PIPE.RECEIVE_MESSAGE deve disporre dei privilegi necessari per eseguire la funzione cache.

Sintassi funzione cache

CREATE OR REPLACE FUNCTION *cache_function_name* (
       pipename  IN VARCHAR2
) RETURN INTEGER;

Parametro	Tipo di dati	Descrizione
`pipename`	`VARCHAR2`	Nome del tubo Singleton.

Return	Descrizione
0	Operazione riuscita
Non zero	Valore di errore restituito da`DBMS_PIPE.RECEIVE_MESSAGE`

Definire una funzione cache per fornire l'incapsulamento e l'astrazione della complessità dalle sessioni di lettura di Singleton Pipe. Le operazioni tipiche all'interno di una funzione cache sono le seguenti:

Creare una tubazione Singleton per una tubazione esplicita utilizzando DBMS_PIPE.CREATE_PIPE.
Creare il messaggio da inserire nella cache nella tubazione Singleton.
Invia messaggio a Singleton Pipe, specificando facoltativamente un shelflife per il messaggio implicito.

Eccezioni

Eccezione	Descrizione
`Null pipe name`	Errore di autorizzazione. Privilegi insufficienti per rimuovere il record dalla pipe. La pipe è di proprietà di un altro utente.

Esempio

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

Funzione SEND_MESSAGE

Questa funzione invia un messaggio sulla pipe denominata.

Il messaggio è contenuto nel buffer dei messaggi locale, che è stato riempito con chiamate a PACK_MESSAGE. È possibile creare una pipe in modo esplicito utilizzando CREATE_PIPE, altrimenti viene creata in modo implicito.

Per creare una pipe Singleton implicita, impostare il parametro singleton su TRUE. I seguenti argomenti sono applicabili a Singleton Pipes:

singleton: indica che la pipe deve essere creata come pipe singleton (valore predefinito: FALSE).
shelflife: è possibile specificare una scadenza della durata di conservazione del messaggio inserito nella cache nella tubazione Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

Questo argomento è applicabile per tubi Singleton impliciti ed espliciti. Un valore shelflife specificato nella funzione SEND_MESSAGE sovrascrive il valore shelflife specificato per la pipe Singleton esplicita in

Funzione CREATE_PIPE e sarà l'impostazione predefinita per tutti i nuovi messaggi inseriti nella cache nella pipe Singleton.

Sintassi

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;

Parametri

Tabella - Parametri funzione SEND_MESSAGE

Parametro	Descrizione
`pipename`	Nome della pipe su cui si desidera posizionare il messaggio. Se si utilizza una pipe esplicita, questo è il nome specificato quando si chiama `CREATE_PIPE`. Attenzione: non utilizzare nomi di pipe che iniziano con '`ORA$`'. Questi nomi sono riservati all'uso da parte delle procedure fornite da Oracle. Il nome della pipeline non deve superare i 128 byte e non fa distinzione tra maiuscole e minuscole. Al momento, il nome non può contenere caratteri del Supporto alla globalizzazione.
`timeout`	Tempo di attesa durante il tentativo di posizionare un messaggio su una pipe, in secondi. Il valore predefinito è la costante `MAXWAIT`, definita come 86400000 (1000 giorni).
`maxpipesize`	Dimensione massima consentita per la pipe, in byte. La dimensione totale di tutti i messaggi nella pipe non può superare questa quantità. Il messaggio viene bloccato se supera questo limite massimo. Il valore predefinito è di 65536 byte. Il `maxpipesize` per un tubo diventa parte delle caratteristiche del tubo e persiste per la vita del tubo. I chiamanti di `SEND_MESSAGE` con valori maggiori causano l'aumento di `maxpipesize`. I chiamanti con un valore inferiore utilizzano semplicemente il valore esistente e più grande. La specifica di `maxpipesize` come parte della procedura `SEND_MESSAGE` elimina la necessità di una chiamata separata per aprire la pipe. Se la pipe è stata creata in modo esplicito, è possibile utilizzare il parametro facoltativo `maxpipesize` per sostituire le specifiche delle dimensioni della pipe di creazione. Il valore predefinito `maxpipesize` di 65536 è applicabile a tutti i tubi.
`singleton`	Utilizzare `TRUE` per creare una Singleton Pipe. Valore predefinito: `FALSE`
`shelflife`	Tempo di scadenza in secondi di un messaggio inserito nella cache in Singleton Pipe. Dopo il superamento dell'ora `shelflife` specificata, il messaggio non sarà più accessibile dalla pipe. Il parametro `shelflife` è applicabile solo a una Singleton Pipe. Il valore predefinito è `0`, il che significa che il messaggio non scade mai.

Valori restituiti

Return	Descrizione
`0`	Operazione riuscita. Se la pipe esiste già e l'utente che sta tentando di crearla è autorizzato a utilizzarla, Oracle restituisce 0, indicando l'esito positivo e tutti i dati già presenti nella pipe rimangono. Se un utente connesso come `SYSDBS`/`SYSOPER` ricrea una pipe, Oracle restituisce lo stato 0, ma la proprietà della pipe rimane invariata.
`1`	Timeout. Questa procedura può scadere perché non è possibile ottenere un blocco sulla pipe o perché la pipe rimane troppo piena per essere utilizzata. Se la pipe è stata creata implicitamente ed è vuota, viene rimossa.
`3`	Si è verificata un'interruzione. Se la pipe è stata creata implicitamente ed è vuota, viene rimossa.
`6`	Impossibile convertire la pipe esistente in pipe singleton. Impossibile convertire una pipe implicita con più messaggi esistenti in una pipe Singleton. Per una pipe esplicita che non è Singleton, `DBMS_PIPE.SEND_MESSAGE` non può inviare un messaggio con l'argomento singleton impostato su `TRUE`.
`7`	Viene fornito un valore diverso da zero per il parametro `shelflife` e la pipe non è una pipe singleton.
`ORA-23322`	Privilegi insufficienti. Se esiste una pipe con lo stesso nome ed è stata creata da un utente diverso, Oracle segnala l'errore `ORA-23322`, indicando il conflitto di denominazione.

Eccezioni

Eccezione	Descrizione
`Null pipe name`	Errore di autorizzazione. Privilegi insufficienti per scrivere nella pipe. La pipa è privata e di proprietà di qualcun altro.

Contenuto correlato

Memorizza nella cache i messaggi con Singleton Pipes