Documentazione dell'infrastruttura Oracle Cloud

Pacchetto DBMS_PIPE

Il pacchetto DBMS_PIPE consente a due o più sessioni nella stessa istanza di comunicare.

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

Per informazioni dettagliate sulla funzionalità DBMS_PIPE di base fornita in Oracle Database, consultare DBMS_PIPE.

Argomento padre: Riferimento del package fornito per Autonomous Database

DBMS_PIPE Panoramica per Singleton Pipes

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

Su Autonomous Database il pacchetto DBMS_PIPE ha funzionalità estese per supportare tubi singleton.

Le funzioni della pipe Singleton in DBMS_PIPE forniscono quanto riportato di seguito.

  • 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, inclusi i tubi Singleton. Le versioni precedenti di DBMS_PIPE avevano una dimensione massima del messaggio inferiore.

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

  • Metodi di invalidamento della cache:

    • Invalidamento esplicito della cache controllato dall'utente.
    • Invalidamento della cache dopo un intervallo di tempo (in secondi) del parametro specificato dall'utente (shelflife).

  • API PL/SQL dichiarative e di facile utilizzo per l'inserimento nella cache.

  • Supporta database di sola lettura e lettura-scrittura.

Un tubo Singleton può essere uno qualsiasi dei tipi DBMS_PIPE supportati:

  • Tubo implicito: creato automaticamente quando un messaggio viene inviato con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
  • Tubo esplicito: creato utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome di pipe specificato dall'utente.
  • Public Pipe: accessibile da qualsiasi utente con autorizzazione EXECUTE sul pacchetto DBMS_PIPE
  • Tubo privato: accessibile da sessioni con lo stesso utente dell'autore della pipe.

Argomento padre: Pacchetto DBMS_PIPE

Riepilogo dei sottoprogrammi DBMS_PIPE per Singleton Pipes

Questa tabella elenca i sottoprogrammi DBMS_PIPE e li descrive brevemente.

Tabella 6-1 DBMS_PIPE Sottoprogrammi del pacchetto

Sottoprogramma Descrizione

Funzione CREATE_PIPE

Crea un tubo (necessario per tubi privati)

Funzione NEXT_ITEM_TYPE

Restituisce il tipo di dati dell'elemento successivo nel buffer

PACK_MESSAGE Procedure

Genera il messaggio nel buffer locale

Procedura di rimozione

Rimuove i contenuti della pipe denominata

Funzione RECEIVE_MESSAGE

Copia il messaggio dalla named pipe nel buffer locale

Procedura RESET_BUFFER

Rimuove i contenuti del buffer locale

Funzione REMOVE_PIPE

Rimuove la pipe denominata

Funzione SEND_MESSAGE

Invia un messaggio alla pipe denominata: questa operazione crea implicitamente una pipe pubblica se la pipe denominata non esiste

Funzione UNIQUE_SESSION_NAME

Restituisce un nome sessione univoco

UNPACK_MESSAGE Procedure

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

Argomento padre: Pacchetto DBMS_PIPE

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 Singleton Pipe, 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 della durata di conservazione (in secondi) del messaggio inserito nella cache nel tubo Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

    Il messaggio shelflife in Singleton Pipe può essere specificato anche quando si invia un messaggio (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. 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 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 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.

singleton

Utilizzare TRUE per creare una Singleton Pipe.

Valore predefinito: FALSE

shelflife

Tempo di scadenza in secondi di un messaggio inserito nella cache in Singleton Pipe. Dopo il superamento dell'ora shelflife specificata, il messaggio non sarà più accessibile dalla pipe. Il parametro shelflife è applicabile solo a una Singleton Pipe.

Il valore predefinito è 0, il che significa che il messaggio non scade mai.

Valori restituiti

Tabella 6-3 Valori restituiti dalla funzione CREATE_PIPE

Reso Descrizione

0

Riuscito.

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.

6

Impossibile convertire la pipe esistente in pipe singleton.

  • Impossibile convertire una pipe implicita con più messaggi esistenti 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: un pipe con lo stesso nome esiste già e non è consentito utilizzarlo.

Esempio

Crea un tubo Singleton con 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 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 trascorso nella funzione della cache di esecuzione specificata nel parametro cache_func.

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

cache_func

Nome della 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 dalla funzione RECEIVE_MESSAGE

Reso Descrizione

0

Operazione riuscita

1

Tempo scaduto. 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.
8

La funzione cache può essere specificata solo quando si utilizza un tubo Singleton.

ORA-23322

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

Note sull'uso

Per ricevere un messaggio da una pipe, chiamare prima RECEIVE_MESSAGE. Quando si riceve un messaggio, viene rimosso dalla pipe; quindi, un messaggio può essere ricevuto solo una volta. Per i tubi creati in modo implicito, la pipe viene rimossa dopo la rimozione dell'ultimo record dalla pipe.

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

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

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

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

pipename

 VARCHAR2

Nome del tubo Singleton.
Reso Descrizione
0 Operazione riuscita
Non 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 le seguenti:

  • Creare una tubazione Singleton per una tubazione esplicita utilizzando DBMS_PIPE.CREATE_PIPE.
  • Creare il messaggio da inserire nella cache nella tubazione Singleton.
  • Inviare un messaggio a Singleton Pipe, specificando facoltativamente un 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 pipe è di proprietà di un altro utente.

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

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 della durata di conservazione del messaggio inserito nella cache nella tubazione Singleton. Può essere utilizzato per invalidare implicitamente il messaggio in Singleton Pipe.

    Questo argomento è applicabile per tubi Singleton impliciti ed espliciti. Un valore shelflife specificato nella funzione SEND_MESSAGE sovrascrive il valore shelflife specificato per la pipe singleton esplicita nella 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 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).

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.

singleton

Utilizzare TRUE per creare una Singleton Pipe.

Valore predefinito: FALSE

shelflife

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

Dopo il superamento dell'ora shelflife specificata, il messaggio non sarà più accessibile dalla pipe. Il parametro shelflife è applicabile solo a una Singleton Pipe.

Il valore predefinito è 0, il che significa che il messaggio non scade mai.

Valori restituiti

Tabella 6-9 Valori restituiti dalla funzione SEND_MESSAGE

Reso 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

Tempo scaduto.

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.

6

Impossibile convertire la pipe esistente in pipe singleton.

  • Impossibile convertire una pipe implicita con più messaggi esistenti 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.

Panoramica DBMS_PIPE per le pipeline di messaggistica persistenti

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

In Autonomous Database il package DBMS_PIPE ha funzionalità estese per supportare i pipe di messaggistica persistenti.

Messaggi persistenti in DBMS_PIPE:

  • Supporta la possibilità di inviare e recuperare messaggi di grandi dimensioni.

  • Supporta un numero elevato di messaggi pipe.

  • Supporta la condivisione di messaggi all'interno di un singolo 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. L'utilizzo di questa funzionalità in una pipe può essere reso disponibile solo per il database corrente oppure può essere reso disponibile per più database nella stessa area o in aree diverse.

    Un pipe di messaggistica persistente può essere uno qualsiasi dei tipi DBMS_PIPE supportati:

    • Tubo implicito: creato automaticamente quando un messaggio viene inviato con un nome pipe sconosciuto utilizzando la funzione DBMS_PIPE.SEND_MESSAGE.
    • Tubo esplicito: creato utilizzando la funzione DBMS_PIPE.CREATE_PIPE con un nome di pipe specificato dall'utente.
    • Public Pipe: accessibile da qualsiasi utente con autorizzazione EXECUTE sul pacchetto DBMS_PIPE
    • Tubo privato: accessibile da 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 il numero 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, pubblica o privata (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 solleverà 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: Pacchetto DBMS_PIPE

Riepilogo dei sottoprogrammi DBMS_PIPE per la messaggistica persistente

Questa tabella elenca i sottoprogrammi DBMS_PIPE e li descrive brevemente.

Tabella 6-11 DBMS_PIPE Sottoprogrammi del pacchetto

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.

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.

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.
  • Funzione RECEIVE_MESSAGE
    Questa funzione copia il messaggio nel buffer dei messaggi locale.
  • SEND_MESSAGE Funzione
    Questa funzione invia un messaggio sulla pipe denominata.
  • SET_CREDENTIAL_NAME Procedura
    Questa procedura imposta la variabile credential_name che viene 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: Pacchetto DBMS_PIPE

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

Tabella 6-13 Valori restituiti dalla funzione CREATE_PIPE

Reso Descrizione

0

Riuscito.

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

Eccezioni

Tabella 6-14 Eccezione funzione CREATE_PIPE

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

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

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 su principal risorsa, vedere Configura criteri e ruoli per accedere alle risorse.

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

Reso Descrizione

0

Operazione riuscita

1

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

  • Per ricevere un messaggio da una pipe, chiamare prima RECEIVE_MESSAGE. Quando si riceve un messaggio, viene rimosso dalla pipe; quindi, un messaggio può essere ricevuto solo una volta. Per i tubi creati in modo implicito, la pipe viene rimossa dopo la rimozione dell'ultimo record dalla pipe.

  • Se la pipe specificata quando si chiama RECEIVE_MESSAGE non esiste già, Oracle crea la pipe in modo implicito e attende di ricevere il messaggio. Se il messaggio non arriva entro un determinato intervallo di timeout, 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 disimballare gli elementi di tipo DATE, NUMBER, VARCHAR2 e sono disponibili due procedure aggiuntive per disimballare 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 possono essere scritti o letti da un solo processo. Ciò impedisce l'incoerenza del contenuto del messaggio a causa di scritture e letture concorrenti. Utilizzando una pipe di messaggistica persistente, DBMS_PIPE consente l'attivazione di una sola operazione, ovvero l'invio di un messaggio o di un messaggio di ricezione alla volta. Tuttavia, se un'operazione non è possibile a causa di un'operazione in corso, il processo esegue un nuovo tentativo periodicamente fino al raggiungimento del valore timeout.

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

    • Se utilizzi un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, devi 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 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 6-18 Parametri della 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.

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 su principal risorsa, vedere Configura criteri e ruoli per accedere alle risorse.

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

Reso 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

Tempo scaduto.

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

Note sull'uso

  • I messaggi persistenti possono essere scritti o letti da un solo processo. Ciò impedisce l'incoerenza del contenuto del messaggio a causa di scritture e letture concorrenti. Utilizzando una pipe di messaggistica persistente, DBMS_PIPE consente l'attivazione di una sola operazione, ovvero l'invio di un messaggio o di un messaggio di ricezione alla volta. Tuttavia, se un'operazione non è possibile a causa di un'operazione in corso, il processo esegue un nuovo tentativo periodicamente fino al raggiungimento del valore timeout.

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

    • Se utilizzi un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, devi 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.

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.

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 su principal risorsa, 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 di Oracle Cloud Infrastructure o gli URI Swift. Tuttavia, l'URI della posizione e la credenziale devono corrispondere nel tipo riportato di seguito.

  • Se utilizzi un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, devi 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;
/

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

  • Se utilizzi un formato URI nativo per accedere a Oracle Cloud Infrastructure Object Storage, devi 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;
/