DBMS_PIPE Package (pip di messaggistica persistente)

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

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

Consultare DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference oppure Oracle Database 26ai PL/SQL Packages and Types Reference per informazioni dettagliate sulle funzionalità DBMS_PIPE di base fornite in Oracle Database.

Argomenti correlati

DBMS_PIPE Panoramica per i pipeline di messaggistica persistente

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

Nel database AI autonomo il pacchetto DBMS_PIPE ha esteso le funzionalità 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:

  • Supporta la capacità di inviare e recuperare messaggi molto grandi.

  • Supporta un numero elevato di messaggi pipe.

  • Supporta la condivisione dei messaggi all'interno di un unico database, su più database e tra database in aree diverse.

  • Supporta più pipe utilizzando lo stesso URI di posizione dell'area di memorizzazione degli oggetti cloud.

    La funzionalità di messaggistica persistente consente a due o più sessioni di database di comunicare con i messaggi memorizzati nell'area di memorizzazione degli oggetti cloud. Utilizzando questa funzionalità, i messaggi in una pipe possono essere resi disponibili solo per il database corrente oppure possono essere resi disponibili per più database nella stessa area o in più aree diverse.

    Una barra verticale di messaggistica persistente può essere uno qualsiasi 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.
    • Pipe 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.

Nota

Quando si inviano e ricevono messaggi in database diversi utilizzando messaggi persistenti, Oracle consiglia di chiamare DBMS_PIPE.CREATE_PIPE prima di inviare o ricevere messaggi. La creazione di una pipe esplicita con DBMS_PIPE.CREATE_PIPE garantisce la creazione di una pipe con le autorizzazioni di accesso desiderate, sia pubbliche che private (impostando il parametro PRIVATE su FALSE o utilizzando il valore predefinito TRUE).

DBMS_PIPE Limitazione

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 istanza 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

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 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.
PACK_MESSAGE Procedure

Genera il messaggio nel buffer locale.

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 su una named pipe: questo crea implicitamente una pipe pubblica se la named pipe non esiste.

SET_CREDENTIAL_NAME Procedura

Imposta la variabile credential_name utilizzata come credenziale predefinita per i messaggi memorizzati nell'area di memorizzazione degli oggetti cloud.

SET_LOCATION_URI Procedura

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

Sintassi

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

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.

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

Il 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

L'URI dell'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 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 per eseguire la funzione cache specificata con il parametro cache_func.

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

credential_name

Il 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 credenziali deve disporre dei privilegi EXECUTE e READ/WRITE dell'utente che esegue DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

URI di posizione per l'area di memorizzazione cloud utilizzata 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 in modo implicito ed è vuota, viene rimossa.

2

Il record nella pipe è troppo grande per il buffer.

3

Si è verificato un interrupt.

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.

  • I messaggi persistenti sono garantiti per essere scritti o letti da un solo processo. Ciò impedisce l'incongruenza del contenuto del messaggio a causa di scritture e letture concorrenti. Utilizzando una pipe di messaggistica persistente, DBMS_PIPE consente di attivare una sola operazione, l'invio di un messaggio o di un messaggio ricevente alla volta. Tuttavia, se un'operazione non è possibile a causa di un'operazione in corso, il processo ripete periodicamente fino al raggiungimento del valore timeout.

  • Se si utilizza Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, è possibile utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI di posizione e la credenziale devono corrispondere nel tipo indicato di seguito.

    • Se si utilizza un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare l'autenticazione delle chiavi di firma Oracle Cloud Infrastructure nativa nell'oggetto credenziali.

    • Se si utilizza il formato URI Swift per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare un'autenticazione del token di autenticazione nell'oggetto credenziali.

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.

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.

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

Il 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 credenziali deve disporre dei privilegi EXECUTE e READ/WRITE dell'utente che esegue DBMS_PIPE.SEND_MESSAGE.

location_uri

URI di posizione per l'area di memorizzazione cloud utilizzata 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 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.

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

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.

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.

Note sull'uso

  • I messaggi persistenti sono garantiti per essere scritti o letti da un solo processo. Ciò impedisce l'incongruenza del contenuto del messaggio a causa di scritture e letture concorrenti. Utilizzando una pipe di messaggistica persistente, DBMS_PIPE consente di attivare una sola operazione, l'invio di un messaggio o di un messaggio ricevente alla volta. Tuttavia, se un'operazione non è possibile a causa di un'operazione in corso, il processo ripete periodicamente fino al raggiungimento del valore timeout.

  • Se si utilizza Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, è possibile utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI di posizione e la credenziale devono corrispondere nel tipo indicato di seguito.

    • Se si utilizza un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare l'autenticazione delle chiavi di firma Oracle Cloud Infrastructure nativa nell'oggetto credenziali.

    • Se si utilizza il formato URI Swift per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare un'autenticazione del token di autenticazione nell'oggetto credenziali.

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.

SET_CREDENTIAL_NAME Procedura

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

Il nome della credenziale per accedere allo storage degli oggetti cloud.

Nota per l'uso

Se si utilizza Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, è possibile utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI di posizione e la credenziale devono corrispondere nel tipo indicato di seguito.

  • Se si utilizza un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare l'autenticazione delle chiavi di firma Oracle Cloud Infrastructure nativa nell'oggetto credenziali.

  • Se si utilizza il formato URI Swift per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare un'autenticazione del token di autenticazione nell'oggetto credenziali.

Esempio

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

SET_LOCATION_URI Procedura

Questa procedura imposta la variabile location_uri globale.

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 si utilizza Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, è possibile utilizzare gli URI nativi di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI di posizione e la credenziale devono corrispondere nel tipo indicato di seguito.

  • Se si utilizza un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare l'autenticazione delle chiavi di firma Oracle Cloud Infrastructure nativa nell'oggetto credenziali.

  • Se si utilizza il formato URI Swift per accedere a Oracle Cloud Infrastructure Object Storage, è necessario utilizzare un'autenticazione del token di autenticazione nell'oggetto credenziali.

Esempio

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