Documentazione di Oracle Cloud Infrastructure

Pacchetto DBMS_PIPE

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

Oracle Autonomous Database supporta la funzionalità DBMS_PIPE di base, disponibile in Oracle Database 19c, oltre alle estensioni.

Per i dettagli sulla funzionalità DBMS_PIPE di base fornita in Oracle Database, vedere DBMS_PIPE.

Argomento padre: riferimento al package fornito da Autonomous Database

DBMS_PIPE Panoramica per Singleton Pipes

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

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 creato automaticamente quando viene inviato un messaggio con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
  • Pipe esplicita: viene creato utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome pipe specificato dall'utente.
  • Public Pipe: accessibile da qualsiasi utente con autorizzazione EXECUTE sul pacchetto DBMS_PIPE
  • Pipe privata: è accessibile dalle sessioni con lo stesso utente dell'autore della pipe.

Argomento padre: DBMS_PIPE Package

Riepilogo dei sottoprogrammi DBMS_PIPE per Singleton Pipes

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

Tabella 6-1 DBMS_PIPE Sottoprogrammi del pacchetto

Programma secondario 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
  • CREATE_PIPE Funzione
    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.
  • RECEIVE_MESSAGE Funzione
    Questa funzione copia il messaggio nel buffer dei messaggi locale.
  • SEND_MESSAGE Funzione
    Questa funzione invia un messaggio sulla named pipe.

Argomento padre: DBMS_PIPE Package

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 6-2 Parametri della 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 6-3 Valori restituiti funzione CREATE_PIPE

Restituito descrizione;

0

Completata.

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 6-4 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 6-5 Parametri della 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 6-6 Valori restituiti funzione RECEIVE_MESSAGE

Restituito descrizione;

0

Riusciti

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 per 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.
Restituito descrizione;
0 Riusciti
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 6-7 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 6-8 Parametri della 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 6-9 Valori restituiti dalla funzione SEND_MESSAGE

Restituito 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 6-10 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.

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.

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 creato automaticamente quando viene inviato un messaggio con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
    • Pipe esplicita: viene creato utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome pipe specificato dall'utente.
    • Public Pipe: 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 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 genererà l'errore ORA-12704 se si tenta di inviare messaggi con DBMS_PIPE tra questi due database.

Per ulteriori informazioni, vedere Scegliere un set di caratteri per Autonomous Database.

Argomento padre: DBMS_PIPE Package

Riepilogo dei sottoprogrammi DBMS_PIPE per la messaggistica persistente

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

Tabella 6-11 DBMS_PIPE Sottoprogrammi del pacchetto

Programma secondario 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.
  • CREATE_PIPE Funzione
    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.
  • GET_CREDENTIAL_NAME Funzione
    Questa funzione restituisce il valore della variabile credential_name globale da utilizzare quando i messaggi vengono memorizzati nell'area di memorizzazione degli oggetti cloud.
  • GET_LOCATION_URI Funzione
    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.
  • RECEIVE_MESSAGE Funzione
    Questa funzione copia il messaggio nel buffer dei messaggi locale.
  • SEND_MESSAGE Funzione
    Questa funzione invia un messaggio sulla named pipe.
  • 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.
  • SET_LOCATION_URI Procedura
    Questa procedura imposta la variabile location_uri globale.

Argomento padre: DBMS_PIPE Package

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 6-12 Parametri della 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 6-13 Valori restituiti dalla funzione CREATE_PIPE

Restituito descrizione;

0

Completata.

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 6-14 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 restituzioni 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 restituzioni

Valore restituzioni 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 6-15 Parametri della 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.

Il valore credential_name può essere un principal risorsa OCI, un principal servizio Azure, un nome risorsa Amazon (ARN) o un account servizio Google. Per ulteriori informazioni sull'autenticazione basata sul principal delle risorse, vedere Configura criteri e ruoli per accedere alle risorse.

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 6-16 Valori restituiti dalla funzione RECEIVE_MESSAGE

Restituito descrizione;

0

Riusciti

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 per 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 utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi 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 native 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 6-17 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 6-18 Parametri della 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.

Il valore credential_name può essere un principal risorsa OCI, un principal servizio Azure, un nome risorsa Amazon (ARN) o un account servizio Google. Per ulteriori informazioni sull'autenticazione basata sul principal delle risorse, vedere Configura criteri e ruoli per accedere alle risorse.

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 6-19 Valori restituiti dalla funzione SEND_MESSAGE

Restituito 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 per 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 utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi 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 native 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 6-20 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.

Il valore credential_name può essere un principal risorsa OCI, un principal servizio Azure, un nome risorsa Amazon (ARN) o un account servizio Google. Per ulteriori informazioni sull'autenticazione basata sul principal delle risorse, vedere Configura criteri e ruoli per accedere alle risorse.

Nota per l'uso

Se utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi 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 native 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 DBMS_CLOUD Formati URI.

Nota per l'uso

Se utilizzi Oracle Cloud Infrastructure Object Storage per memorizzare i messaggi, puoi utilizzare gli URI nativi 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 native 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;
/