DBMS_PIPE Package (pip di messaggistica persistente)
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.
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.
In Autonomous Database il pacchetto DBMS_PIPE ha 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 o Oracle Database 23ai 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 pacchettoDBMS_PIPE
. - Pipe privata: è accessibile dalle sessioni con lo stesso utente dell'autore della pipe.
- Pipe implicita: viene creata automaticamente quando viene inviato un messaggio con un nome pipe sconosciuto utilizzando la funzione
Nota
Quando si inviano e ricevono messaggi in database diversi utilizzando messaggi persistenti, Oracle consiglia di chiamareDBMS_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 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 genererà 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 |
---|---|
Crea un tubo (necessario per tubi privati). |
|
Restituisce il valore della variabile |
|
Restituisce il valore della variabile |
|
Restituisce il tipo di dati dell'elemento successivo nel buffer. |
|
Genera il messaggio nel buffer locale. |
|
Copia il messaggio dalla named pipe nel buffer locale. |
|
Rimuove il contenuto del buffer locale. |
|
Rimuove la pipe denominata. |
|
Invia un messaggio su una named pipe: questo crea implicitamente una pipe pubblica se la named pipe non esiste. |
|
Imposta la variabile |
|
Imposta la variabile |
|
Restituisce un nome sessione univoco. |
|
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 |
---|---|
|
Nome della pipe che si sta creando. È necessario utilizzare questo nome quando si chiamano Attenzione: non utilizzare nomi di pipe che iniziano con |
|
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 Il valore Il valore predefinito |
|
Utilizza il valore predefinito, I tubi pubblici possono essere creati in modo implicito quando si chiama |
Valori restituiti
Tabella - Valori restituiti funzione CREATE_PIPE
Return | Descrizione |
---|---|
|
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. |
|
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 |
Eccezioni
Tabella - Eccezione funzione CREATE_PIPE
Eccezione | Descrizione |
---|---|
|
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 |
---|---|
|
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 |
---|---|
|
Nome della pipe su cui si desidera ricevere un messaggio. I nomi che iniziano con |
|
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 Valore predefinito: è la costante |
|
Il nome della credenziale per l'area di memorizzazione cloud utilizzata per memorizzare i messaggi.
È possibile impostare questo valore prima di chiamare L'oggetto credenziali deve disporre dei privilegi |
|
URI di posizione per l'area di memorizzazione cloud utilizzata per memorizzare i messaggi.
È possibile impostare questo valore prima di chiamare |
Valori restituiti
Tabella - Valori restituiti funzione RECEIVE_MESSAGE
Return | Descrizione |
---|---|
|
Operazione riuscita |
|
Timeout. Se la pipe è stata creata in modo implicito ed è vuota, viene rimossa. |
|
Il record nella pipe è troppo grande per il buffer. |
|
Si è verificato un interrupt. |
|
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 proceduraUNPACK_MESSAGE
viene sovraccaricata per decomprimere gli elementi di tipoDATE
,NUMBER
,VARCHAR2
e sono disponibili due procedure aggiuntive per decomprimere gli elementiRAW
eROWID
. Se non si conosce il tipo di dati che si sta tentando di decomprimere, chiamareNEXT_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 valoretimeout
. -
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 |
---|---|
|
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.
È possibile impostare questo valore prima di chiamare L'oggetto credenziali deve disporre dei privilegi |
location_uri |
URI di posizione per l'area di memorizzazione cloud utilizzata per memorizzare i messaggi.
È possibile impostare questo valore prima di chiamare |
|
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 La specifica di Il valore predefinito |
|
Nome della pipe in cui si desidera inserire il messaggio. Se si utilizza una pipe esplicita, questo è il nome specificato quando si chiama Attenzione: non utilizzare nomi pipe che iniziano con ' |
|
Tempo di attesa durante il tentativo di inserire un messaggio in una pipe, in secondi. Il valore predefinito è la costante |
Valori restituiti
Tabella - Valori restituiti funzione SEND_MESSAGE
Return | Descrizione |
---|---|
|
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 |
|
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. |
|
Si è verificato un interrupt. Se la pipe è stata creata in modo implicito ed è vuota, viene rimossa. |
|
Privilegi insufficienti. Se esiste una pipe con lo stesso nome ed è stata creata da un utente diverso, Oracle segnala l'errore |
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 valoretimeout
. -
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 |
---|---|
|
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 |
---|---|
|
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;
/