Package DBMS_PIPE (Pipes di messaggistica persistenti)

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 pipeline di messaggistica persistente

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

In Autonomous AI Database, il package DBMS_PIPE dispone di funzionalità estese per supportare i pipe di messaggistica persistenti. 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.

Messaggi persistenti in DBMS_PIPE:

Limitazione DBMS_PIPE

Il pacchetto DBMS_PIPE non supporta l'invio di messaggi tra database che utilizzano set di caratteri diversi. Ad esempio, se si dispone di un'istanza di Autonomous AI Database che utilizza AL32UTF8 e un'altra che utilizza WE8MSWIN1252, non è possibile inviare messaggi con DBMS_PIPE tra questi due database. In questo caso, il sistema solleverà l'errore ORA-12704 se si tenta di inviare messaggi con DBMS_PIPE tra questi due database.

Riepilogo dei sottoprogrammi DBMS_PIPE per la messaggistica persistente

Questa tabella elenca i sottoprogrammi DBMS_PIPE e li descrive brevemente.

Sottoprogramma Descrizione
Funzione CREATE_PIPE Crea un tubo (necessario per tubi privati).
Funzione GET_CREDENTIAL_NAME Restituisce il valore della variabile credential_name globale.
Funzione GET_LOCATION_URI Restituisce il valore della variabile location_uri globale utilizzato come URI di posizione predefinito da utilizzare quando un messaggio viene memorizzato nell'area di memorizzazione degli oggetti cloud.

Funzione NEXT_ITEM_TYPE

 Restituisce il tipo di dati dell'elemento successivo nel buffer.

Procedure PACK_MESSAGE

 Genera il messaggio nel buffer locale.
Funzione RECEIVE_MESSAGE Copia il messaggio dalla named pipe nel buffer locale.

Procedura RESET_BUFFER

 Rimuove il contenuto del buffer locale.

Funzione REMOVE_PIPE

 Rimuove la pipe denominata.
Funzione SEND_MESSAGE Invia un messaggio a una pipe denominata: questa operazione crea implicitamente una pipe pubblica se la pipe denominata non esiste.
Procedura SET_CREDENTIAL_NAME Imposta la variabile credential_name utilizzata come credenziale predefinita per i messaggi memorizzati nell'area di memorizzazione degli oggetti cloud.
Procedura SET_LOCATION_URI Imposta la variabile location_uri globale utilizzata come URI di posizione predefinito per i messaggi memorizzati nell'area di memorizzazione degli oggetti cloud.

Funzione UNIQUE_SESSION_NAME

 Restituisce un nome di sessione univoco.

Procedure UNPACK_MESSAGE

 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.

Sintassi

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
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 per 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.

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.
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, che indica 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

Creare un nome privato esplicito denominato MY_PIPE1

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

Funzione GET_CREDENTIAL_NAME

Questa funzione restituisce il valore della variabile credential_name globale da utilizzare quando i messaggi vengono memorizzati nell'area di memorizzazione degli oggetti cloud.

Sintassi

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valori restituiti

Valore restituito Descrizione
credential_name Nome della credenziale per accedere allo storage degli oggetti cloud.

Esempio

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

Funzione GET_LOCATION_URI

Questa funzione restituisce il valore della variabile location_uri globale che può essere utilizzato come URI di posizione predefinito quando i messaggi pipe vengono memorizzati nell'area di memorizzazione degli oggetti cloud.

Sintassi

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valore restituito

Valore restituito Descrizione
location_uri URI oggetto.

Esempio

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
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,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

Parametri

Tabella - Parametri funzione RECEIVE_MESSAGE

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 impiegato per eseguire la funzione cache specificata con il parametro cache_func.

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

credential_name

Nome della credenziale per l'area di memorizzazione cloud utilizzata per memorizzare i messaggi.

credential_name è un argomento del pacchetto inizializzato per impostazione predefinita come NULL.

È possibile impostare questo valore prima di chiamare DBMS_PIPE.RECEIVE_MESSAGE. Il valore del parametro passato ha la precedenza sul valore della variabile globale.

L'oggetto credenziale deve disporre dei privilegi EXECUTE e READ/WRITE dell'utente che esegue DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

URI di posizione per il cloud store utilizzato per memorizzare i messaggi.

location_uri è una variabile globale che per impostazione predefinita viene inizializzata come NULL.

È possibile impostare questo valore prima di chiamare DBMS_PIPE.RECEIVE_MESSAGE. Il valore del parametro passato ha la precedenza sul valore della variabile globale.

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.
ORA-23322 L'utente non dispone di privilegi sufficienti per leggere dalla pipe.

Note sull'uso

Eccezioni

Tabella - Eccezioni funzione RECEIVE_MESSAGE

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

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.

Sintassi

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

Parametri

Tabella - Parametri funzione SEND_MESSAGE

Parametro Descrizione
credential_name

Nome della credenziale per l'area di memorizzazione cloud utilizzata per memorizzare i messaggi.

credential_name è un argomento del pacchetto inizializzato per impostazione predefinita come NULL.

È possibile impostare questo valore prima di chiamare DBMS_PIPE.SEND_MESSAGE. Il valore del parametro passato ha la precedenza sul valore della variabile globale.

L'oggetto credenziale deve disporre dei privilegi EXECUTE e READ/WRITE dell'utente che esegue DBMS_PIPE.SEND_MESSAGE.

location_uri

URI di posizione per il cloud store utilizzato per memorizzare i messaggi.

location_uri è una variabile globale che per impostazione predefinita viene inizializzata come NULL.

È possibile impostare questo valore prima di chiamare DBMS_PIPE.SEND_MESSAGE. Il valore del parametro passato ha la precedenza sul valore della variabile globale.

maxpipesize

Dimensione massima consentita per la pipe, in byte.

La dimensione totale per 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.

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).

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 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.
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, che indica il conflitto di denominazione.

Note sull'uso

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.

Procedura SET_CREDENTIAL_NAME

Questa procedura imposta la variabile credential_name utilizzata come credenziale predefinita quando i messaggi pipe vengono memorizzati nell'area di memorizzazione degli oggetti cloud.

Sintassi

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parametri

Parametro Descrizione
credential_name Nome della credenziale per accedere allo storage degli oggetti cloud.

Nota per l'uso

Se utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI della posizione e la credenziale devono corrispondere nel tipo riportato di seguito.

Esempio

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

Procedura SET_LOCATION_URI

Questa procedura imposta la variabile globale location_uri.

Sintassi

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

Parametro

Parametro Descrizione
location_uri URI oggetto o file. Il formato dell'URI dipende dal servizio di storage degli oggetti cloud in uso. Per i dettagli, vedere Formati URI di storage degli oggetti cloud.

Nota per l'uso

Se utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI della posizione e la credenziale devono corrispondere nel tipo riportato di seguito.

Esempio

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/

Contenuto correlato