DBMS_PIPE Pacchetto (Singleton Pipes)

Il pacchetto DBMS_PIPE consente la comunicazione di due o più sessioni nella stessa istanza.

Oracle Autonomous Database on Dedicated Exadata Infrastructure supporta le funzionalità DBMS_PIPE di base, disponibili su Oracle Database 19c e le estensioni.

Vedere DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 23ai PL/SQL Packages and Types Reference per informazioni dettagliate sulla funzionalità di base di DBMS_PIPE fornita in Oracle Database.

Argomenti correlati

DBMS_PIPE Panoramica per Singleton Pipes

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

Su Autonomous Database il pacchetto DBMS_PIPE ha funzionalità estese per supportare i pipe singleton. Per ulteriori informazioni, vedere DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 23ai PL/SQL Packages and Types Reference.

Le funzioni della pipe Singleton in DBMS_PIPE forniscono quanto segue:

  • 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, compresi Singleton Pipes. Le versioni precedenti di DBMS_PIPE avevano una dimensione massima dei messaggi inferiore.

  • Condividere il messaggio inserito nella cache in più sessioni di database con letture concorrenti.

  • Metodi di annullamento convalida della cache:

    • Annullamento convalida cache esplicita controllato dall'utente.
    • Annullamento della convalida della cache dopo un intervallo di tempo (shelflife) specificato dall'utente (in secondi).

  • API PL/SQL dichiarative e facili da usare per l'inserimento nella cache.

  • Supporta database sia di sola lettura che di lettura-scrittura.

Una pipe Singleton può essere uno dei tipi DBMS_PIPE supportati:

  • Pipe implicita: viene creata automaticamente quando viene inviato un messaggio con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
  • Pipe esplicita: creata utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome pipe specificato dall'utente.
  • Pip pubblica: accessibile da qualsiasi utente con autorizzazione EXECUTE sul pacchetto DBMS_PIPE
  • Pipe privata: è accessibile dalle sessioni con lo stesso utente dell'autore della pipe.

Riepilogo dei sottoprogrammi DBMS_PIPE per Singleton Pipes

La tabella seguente elenca i sottoprogrammi DBMS_PIPE e li descrive brevemente.

Tabella - Sottoprogrammi del pacchetto DBMS_PIPE

Sottoprogramma Descrizione

Funzione CREATE_PIPE

Crea un tubo (necessario per tubi privati)
Funzione NEXT_ITEM_TYPE

Restituisce il tipo di dati dell'elemento successivo nel buffer
PACK_MESSAGE Procedure

Genera il messaggio nel buffer locale
Procedura di rimozione

Rimuove il contenuto della named pipe

Funzione RECEIVE_MESSAGE

Copia il messaggio dalla named pipe nel buffer locale
RESET_BUFFER Procedura

Rimuove il contenuto del buffer locale
Funzione REMOVE_PIPE

Rimuove la pipe denominata

Funzione SEND_MESSAGE

Invia un messaggio sulla named pipe: questo crea implicitamente una pipe pubblica se la named pipe non esiste
Funzione UNIQUE_SESSION_NAME

Restituisce un nome sessione univoco
UNPACK_MESSAGE Procedure

Consente di accedere 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 pipe Singleton, 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 del periodo di validità (in secondi) del messaggio inserito nella cache nella pipe Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

    Quando si invia un messaggio, è possibile specificare anche il messaggio shelflife in Singleton Pipe (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

Tabella - Parametri funzione CREATE_PIPE

Parametro Descrizione

pipename

Nome della pipe che si sta creando.

È necessario utilizzare questo nome quando si chiamano SEND_MESSAGE e RECEIVE_MESSAGE. Tale nome deve essere univoco nell'istanza.

Attenzione: non utilizzare nomi di pipe che iniziano con ORA$. Sono riservati all'uso secondo le procedure fornite da Oracle. Il nome di pipeline non deve superare i 128 byte e non fa distinzione tra maiuscole e minuscole. Al momento, il nome non può contenere caratteri di 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 valore maxpipesize per un tubo diventa parte delle caratteristiche del tubo e persiste per la durata del tubo. I chiamanti di SEND_MESSAGE con valori maggiori causano l'aumento di maxpipesize. I chiamanti con un valore più piccolo utilizzano il valore più grande esistente.

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 pipe Singleton.

Valore predefinito: FALSE

shelflife

Tempo di scadenza in secondi di un messaggio inserito nella cache in Singleton Pipe. Una volta superata l'ora shelflife specificata, il messaggio non sarà più accessibile dalla barra verticale. Il parametro shelflife è applicabile solo a una pipe Singleton.

Il valore predefinito è 0 e indica che il messaggio non ha scadenza.

Valori restituiti

Tabella - Valori restituiti funzione CREATE_PIPE

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 i dati già presenti nella pipe rimangono.

6

Impossibile convertire una pipe esistente in una pipe singleton.

  • Una pipe implicita con più di un messaggio esistente non può essere convertita 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

Tabella - Eccezione funzione CREATE_PIPE

Eccezione Descrizione

Null pipe name

Errore di autorizzazione: una pipe con lo stesso nome esiste già e non è consentito utilizzarla.

Esempio

Creare un tubo Singleton con una 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

pipename

Nome della pipe su cui si desidera ricevere un messaggio.

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

timeout

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

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

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

cache_func

Nome 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 in modo implicito ed è vuota, viene rimossa.

2

Il record nella pipe è troppo grande per il buffer.

3

Si è verificato un interrupt.

8

La funzione cache può essere specificata solo quando si utilizza una pipe Singleton.

ORA-23322

L'utente non dispone di privilegi sufficienti per la lettura dalla pipe.

Note sull'uso

Per ricevere un messaggio da una pipe, chiamare prima RECEIVE_MESSAGE. Quando si riceve un messaggio, questo viene rimosso dalla pipe, quindi un messaggio può essere ricevuto solo una volta. Per i tubi creati in modo implicito, il tubo viene rimosso dopo che l'ultimo record è stato rimosso dal tubo.

Se la pipe specificata quando si chiama RECEIVE_MESSAGE non esiste già, Oracle crea implicitamente la pipe e attende di ricevere il messaggio. Se il messaggio non arriva entro un intervallo di timeout designato, 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 decomprimere gli elementi di tipo DATE, NUMBER, VARCHAR2 e sono disponibili due procedure aggiuntive per decomprimere 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 nel caso dei seguenti due scenari:

  • Singleton Pipe vuoto.
  • Il messaggio nella pipe Singleton non è valido a causa del tempo shelflife trascorso.

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 della funzione cache

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Parametro Tipo di dati Descrizione

pipename

 VARCHAR2

Nome della pipe Singleton.
Return Descrizione
0 Operazione riuscita
Diverso da 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:

  • Creare una pipe Singleton per una pipe esplicita utilizzando DBMS_PIPE.CREATE_PIPE.
  • Creare il messaggio da inserire nella cache nella Singleton Pipe.
  • Inviare il messaggio a Singleton Pipe, specificando facoltativamente un valore shelflife per il messaggio implicito.

Eccezioni

Tabella - Eccezioni funzione RECEIVE_MESSAGE

Eccezione Descrizione

Null pipe name

Errore di autorizzazione. Privilegi insufficienti per rimuovere il record dalla pipe. La pipa è di proprietà di qualcun altro.

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 named pipe.

Il messaggio è contenuto nel buffer dei messaggi locale, compilato 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 del periodo di validità del messaggio inserito nella cache nella pipe Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

    Questo argomento è applicabile sia per i tubi Singleton impliciti che per quelli espliciti. Un valore shelflife specificato in Funzione SEND_MESSAGE sovrascrive il valore shelflife specificato per la pipe Singleton esplicita in Funzione CREATE_PIPE e sarà il valore predefinito 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 in cui si desidera inserire il messaggio.

Se si utilizza una pipe esplicita, questo è il nome specificato quando si chiama CREATE_PIPE.

Attenzione: non utilizzare nomi pipe che iniziano con 'ORA$'. Questi nomi sono riservati all'uso secondo le procedure fornite da Oracle. Il nome di pipeline non deve superare i 128 byte e non fa distinzione tra maiuscole e minuscole. Al momento, il nome non può contenere caratteri di supporto alla globalizzazione.

timeout

Tempo di attesa durante il tentativo di inserire un messaggio in 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 valore maxpipesize per un tubo diventa parte delle caratteristiche del tubo e persiste per la durata del tubo. I chiamanti di SEND_MESSAGE con valori maggiori causano l'aumento di maxpipesize. I chiamanti con un valore più piccolo utilizzano semplicemente il valore più grande esistente.

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 maxpipesize facoltativo 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 pipe Singleton.

Valore predefinito: FALSE

shelflife

Tempo di scadenza in secondi di un messaggio inserito nella cache in Singleton Pipe.

Una volta superata l'ora shelflife specificata, il messaggio non sarà più accessibile dalla barra verticale. Il parametro shelflife è applicabile solo a una pipe Singleton.

Il valore predefinito è 0 e indica che il messaggio non ha scadenza.

Valori restituiti

Tabella - Valori restituiti funzione SEND_MESSAGE

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 i dati già presenti nella pipe rimangono.

Se un utente connesso come SYSDBS/SYSOPER crea di nuovo 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 in modo implicito ed è vuota, viene rimossa.

3

Si è verificato un interrupt.

Se la pipe è stata creata in modo implicito ed è vuota, viene rimossa.

6

Impossibile convertire una pipe esistente in una pipe singleton.

  • Una pipe implicita con più di un messaggio esistente non può essere convertita 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

Tabella - Eccezione funzione SEND_MESSAGE

Eccezione Descrizione

Null pipe name

Errore di autorizzazione. Privilegi insufficienti per scrivere nella pipe. La pipa è privata e di proprietà di qualcun altro.