Pacote DBMS_PIPE (Singleton Pipes)

O pacote DBMS_PIPE permite que duas ou mais sessões na mesma instância se comuniquem.

O Oracle Autonomous AI Database on Dedicated Exadata Infrastructure suporta a funcionalidade principal do DBMS_PIPE, conforme disponível no Oracle Database 19c, além de extensões.

Consulte DBMS_PIPE em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference para obter detalhes sobre a funcionalidade principal do DBMS_PIPE fornecida no Oracle Database.

Visão Geral do DBMS_PIPE para Pipes Singleton

A funcionalidade Pipe possui vários aplicativos em potencial: interface de serviço externo, depuração, transações independentes e alertas.

No Autonomous AI Database, o pacote DBMS_PIPE tem funcionalidade estendida para suportar pipes singleton. Consulte DBMS_PIPE em Referência de Tipos e Pacotes PL/SQL do Oracle Database 19c ou Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai para obter mais informações.

Os recursos de pipe singleton no DBMS_PIPE fornecem o seguinte:

Capacidade de armazenar em cache e recuperar uma mensagem personalizada, de até 32.767 bytes, na memória do banco de dados Oracle. O tamanho máximo da mensagem de 32.767 bytes é aplicável a todos os Pipes, incluindo Pipes Singleton. As versões anteriores do DBMS_PIPE tinham um tamanho máximo de mensagem menor.
Compartilhe a mensagem em cache em várias sessões do banco de dados com leituras simultâneas.
Métodos de invalidação de cache:
- Invalidação explícita do cache controlada pelo usuário.
- Invalidação de cache após um intervalo de tempo (shelflife) do parâmetro especificado pelo usuário (em segundos).
APIs PL/SQL declarativas e fáceis de usar para armazenamento no cache.
Suporta bancos de dados Somente Leitura e Leitura/Gravação.

Um Singleton Pipe pode ser qualquer um dos tipos DBMS_PIPE suportados:

Tubulação Implícita: Criada automaticamente quando uma mensagem é enviada com um nome de pipe desconhecido usando a função DBMS_PIPE.SEND_MESSAGE.
Tubulação Explícita: Criada usando a função DBMS_PIPE.CREATE_PIPE com um nome de pipe especificado pelo usuário.
Tubulação Pública: Acessível por qualquer usuário com permissão EXECUTE no pacote DBMS_PIPE
Pipe Privado: acessível por sessões com o mesmo usuário que o criador do pipe.

Resumo de Subprogramas DBMS_PIPE para Pipes Singleton

Esta tabela lista os subprogramas DBMS_PIPE e os descreve brevemente.

Subprograma	Descrição
Função CREATE_PIPE	Cria um tubo (necessário para tubos privados)
Função NEXT_ITEM_TYPE Referência de Tipos e Pacotes PL/SQL Oracle Database 19c Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Retorna o tipo de dados do próximo item no buffer
Procedimentos PACK_MESSAGE Pacotes e Tipos de PL/SQL do Oracle Database 19c - Referência Pacotes e Tipos de PL/SQL do Oracle Database 26ai	Compila mensagem no buffer local
Procedimento PURGE Referência de Tipos e Pacotes PL/SQL Oracle Database 19c Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Limpa o conteúdo do pipe nomeado
Função RECEIVE_MESSAGE	Copia a mensagem do pipe nomeado para o buffer local
Procedimento RESET_BUFFER Pacotes e Tipos de PL/SQL do Oracle Database 19c Pacotes e Tipos de PL/SQL do Oracle Database 26ai	Limpa o conteúdo do buffer local
Função REMOVE_PIPE Referência de Tipos e Pacotes PL/SQL Oracle Database 19c Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Remove o pipe nomeado
Função SEND_MESSAGE	Envia mensagem no pipe nomeado: Isso cria implicitamente um pipe público se o pipe nomeado não existir
Função UNIQUE_SESSION_NAME Referência de Tipos e Pacotes PL/SQL Oracle Database 19c Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Retorna um nome de sessão exclusivo
Procedimentos UNPACK_MESSAGE Pacotes e Tipos de PL/SQL do Oracle Database 19c - Referência Pacotes e Tipos de PL/SQL do Oracle Database 26ai	Acessa o próximo item no buffer

Função CREATE_PIPE

Essa função cria explicitamente um pipe público ou privado. Se o flag private for TRUE, o criador do pipe será designado como o proprietário do pipe privado.

Os pipes criados explicitamente só podem ser removidos chamando REMOVE_PIPE ou fazendo shutdown da instância.

Para criar um Singleton Pipe, defina o parâmetro singleton como TRUE. Os seguintes argumentos são aplicáveis a Singleton Pipes:

singleton: Indica que o pipe deve ser criado como um Pipe Singleton (valor padrão: FALSE).
shelflife: Opcionalmente, especifique uma expiração de prazo de validade (em segundos) da mensagem armazenada em cache no Singleton Pipe. Ele pode ser usado para invalidação implícita de mensagem no Singleton Pipe.

A mensagem shelflife no Singleton Pipe também pode ser especificada quando você envia uma mensagem de mensagem (consulte Função SEND_MESSAGE).

Sintaxe

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;

Parâmetros

Parâmetro	Descrição
`pipename`	Nome do pipe que você está criando. Você deve usar esse nome ao chamar `SEND_MESSAGE` e `RECEIVE_MESSAGE`. Esse nome deve ser exclusivo na instância. Cuidado: Não use nomes de pipe começando com `ORA$`. Elas são reservadas para uso pelos procedimentos fornecidos pela Oracle. Pipename não deve ter mais de 128 bytes e não faz distinção entre maiúsculas e minúsculas. No momento, o nome não pode conter caracteres de Suporte à Globalização.
`maxpipesize`	O tamanho máximo permitido para o pipe, em bytes. O tamanho total de todas as mensagens no pipe não pode exceder esse volume. A mensagem será bloqueada se exceder este máximo. O `maxpipesize` padrão é 66536 bytes. O `maxpipesize` de um pipe se torna parte das características do pipe e persiste durante a vida útil dele. Os chamadores de `SEND_MESSAGE` com valores maiores fazem com que `maxpipesize` seja aumentado. Os chamadores com um valor menor usam o valor maior existente. O padrão `maxpipesize` de 65536 é aplicável para todos os Pipes.
`private`	Usa o padrão, `TRUE`, para criar um pipe privado. Os pipes públicos podem ser criados implicitamente quando você chama `SEND_MESSAGE`.
`singleton`	Use `TRUE` para criar um Singleton Pipe. Valor padrão: `FALSE`
`shelflife`	Tempo de expiração em segundos de uma mensagem armazenada em cache no Singleton Pipe. Depois que o tempo `shelflife` especificado for excedido, a mensagem não poderá mais ser acessada no Pipe. O parâmetro `shelflife` só é aplicável a um Singleton Pipe. O valor padrão é `0`, o que implica que a mensagem nunca expira.

Valores de Retorno

Retornar	Descrição
`0`	Bem-Sucedida. Se o pipe já existir e o usuário que estiver tentando criá-lo estiver autorizado a usá-lo, o sistema Oracle retornará 0, indicando sucesso, e quaisquer dados já existentes no pipe permanecerão.
`6`	Falha ao converter pipe existente em pipe singleton. O pipe implícito com mais de uma mensagem existente não pode ser convertido em um Pipe Singleton. Para um pipe explícito que não seja Singleton, `DBMS_PIPE.SEND_MESSAGE` não pode enviar uma mensagem com o argumento singleton definido como `TRUE`.
`7`	Um valor diferente de zero é fornecido para o parâmetro `shelflife` e o pipe não é um pipe singleton.
`ORA-23322`	Falha devido a conflito de nomes. Se existir um pipe com o mesmo nome e tiver sido criado por outro usuário, o sistema Oracle sinalizará o erro `ORA-23322`, indicando o conflito de nomeação.

Exceções

Exceção	Descrição
`Null pipe name`	Erro de permissão: já existe um pipe com o mesmo nome e você não tem permissão para usá-lo.

Exemplo

Crie um Tubo Singleton com prazo de validade de 1 hora.

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

Função RECEIVE_MESSAGE

Esta função copia a mensagem para o buffer de mensagem local.

Sintaxe

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename      IN VARCHAR2,
   timeout       IN INTEGER      DEFAULT maxwait,
   cache_func    IN VARCHAR2     DEFAULT NULL)
RETURN INTEGER;

Parâmetros

Tabela - Parâmetros da Função RECEIVE_MESSAGE

Parâmetro Descrição

Parâmetro	Descrição
`pipename`	Nome do canal no qual você deseja receber uma mensagem. Os nomes que iniciam com `ORA$` são reservados para uso pela Oracle.
`timeout`	Tempo para esperar por uma mensagem, em segundos. Um timeout de 0 permite que você leia sem bloquear. O timeout não inclui o tempo gasto na função de cache de execução especificada no parâmetro `cache_func`. Valor padrão: é a constante `MAXWAIT`, que é definida como 86400000 (1000 dias).
`cache_func`	Nome da função de cache para armazenar automaticamente em cache uma mensagem em um Singleton Pipe. O nome da função deve ser totalmente qualificado com o esquema do proprietário: `OWNER.FUNCTION_NAME` `OWNER.PACKAGE.FUNCTION_NAME` Valor padrão: `NULL`

pipename

Nome do canal no qual você deseja receber uma mensagem.

Os nomes que iniciam com ORA$ são reservados para uso pela Oracle.

timeout

Tempo para esperar por uma mensagem, em segundos. Um timeout de 0 permite que você leia sem bloquear.

O timeout não inclui o tempo gasto na função de cache de execução especificada no parâmetro cache_func.

Valor padrão: é a constante MAXWAIT, que é definida como 86400000 (1000 dias).

cache_func

Nome da função de cache para armazenar automaticamente em cache uma mensagem em um Singleton Pipe.

O nome da função deve ser totalmente qualificado com o esquema do proprietário:

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

Valor padrão: NULL

Valores de Retorno

Tabela - Valores de Retorno da Função RECEIVE_MESSAGE

Retornar	Descrição
`0`	Bem-sucedido
`1`	Tempo esgotado. Se o pipe foi criado implicitamente e está vazio, então ele é removido.
`2`	O registro no pipe é muito grande para o buffer.
`3`	Ocorreu uma interrupção.
`8`	A função de cache só pode ser especificada ao usar um Singleton Pipe.
`ORA-23322`	O usuário tem privilégios insuficientes para ler do pipe.

Observações sobre Uso

Para receber uma mensagem de um pipe, primeiro chame RECEIVE_MESSAGE. Quando você recebe uma mensagem, ela é removida do pipe; portanto, uma mensagem só pode ser recebida uma vez. Para pipes criados implicitamente, o pipe é removido após o último registro ser removido do pipe.
Se o pipe especificado quando você chama RECEIVE_MESSAGE ainda não existir, o sistema Oracle cria implicitamente o pipe e aguarda o recebimento da mensagem. Se a mensagem não chegar dentro de um intervalo de tempo limite designado, a chamada retornará e o pipe será removido.
Depois de receber a mensagem, você deve fazer uma ou mais chamadas para UNPACK_MESSAGE para acessar os itens individuais na mensagem. O procedimento UNPACK_MESSAGE é sobrecarregado para descompactar itens do tipo DATE, NUMBER, VARCHAR2 e há dois procedimentos adicionais para descompactar itens RAW e ROWID. Se você não souber o tipo de dados que está tentando descompactar, chame NEXT_ITEM_TYPE para determinar o tipo do próximo item no buffer.

Parâmetro da Função de Cache

Os Pipes Singleton suportam a função de cache para armazenar automaticamente uma mensagem no pipe no caso dos dois cenários a seguir:

Singleton Pipe está vazio.
A mensagem no Singleton Pipe é inválida devido ao tempo decorrido de shelflife.

O nome da função deve ser totalmente qualificado com o esquema do proprietário:

OWNER.FUNCTION_NAME
OWNER.PACKAGE.FUNCTION_NAME

Para usar uma função de cache, o usuário da sessão atual que chama DBMS_PIPE.RECEIVE_MESSAGE deve ter os privilégios necessários para executar a função de cache.

Sintaxe da Função de Cache

CREATE OR REPLACE FUNCTION *cache_function_name* (
       pipename  IN VARCHAR2
) RETURN INTEGER;

Parâmetro	Tipo de dados	Descrição
`pipename`	`VARCHAR2`	Nome do Singleton Pipe.

Retornar	Descrição
0	Bem-sucedido
Diferente de zero	Valor de falha retornado de`DBMS_PIPE.RECEIVE_MESSAGE`

Defina uma função de cache para fornecer encapsulamento e abstração de complexidade das sessões de leitura do Singleton Pipe. As operações típicas dentro de uma função de cache seriam:

Crie um Pipe Singleton, para um Pipe Explícito, usando DBMS_PIPE.CREATE_PIPE.
Crie a mensagem para armazenar em cache no Singleton Pipe.
Enviar Mensagem para o Singleton Pipe, especificando opcionalmente um shelflife para a mensagem implícita.

Exceções

Exceção	Descrição
`Null pipe name`	Erro de permissão. Privilégio insuficiente para remover o registro do pipe. O cachimbo é propriedade de outra pessoa.

Exemplo

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.receive_message(pipename   => 'MY_PIPE1',
                                        timeout    => 1,
                                        cache_func => 'MY_USER.MY_CACHE_FUNC');
END;
/

Função SEND_MESSAGE

Esta função envia uma mensagem no canal nomeado.

A mensagem está contida no buffer de mensagens local, que foi preenchido com chamadas para PACK_MESSAGE. Você pode criar um pipe explicitamente usando CREATE_PIPE; caso contrário, ele será criado implicitamente.

Para criar um pipe Singleton implícito, defina o parâmetro singleton como TRUE. Os seguintes argumentos são aplicáveis a Singleton Pipes:

singleton: Indica que o pipe deve ser criado como um Pipe Singleton (valor padrão: FALSE).
shelflife: Opcionalmente, especifique uma expiração de prazo de validade da mensagem armazenada em cache no Singleton Pipe. Ele pode ser usado para invalidação implícita de mensagem no Singleton Pipe.

Este argumento é aplicável para tubos Singleton implícitos e explícitos. Um valor shelflife especificado em Função SEND_MESSAGE substitui o shelflife especificado para o Pipe Singleton Explícito em

Função CREATE_PIPE e será o padrão para todas as novas mensagens armazenadas no cache no Singleton Pipe.

Sintaxe

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;

Parâmetros

Tabela - Parâmetros da Função SEND_MESSAGE

Parâmetro	Descrição
`pipename`	Nome do pipe no qual você deseja colocar a mensagem. Se você estiver usando um pipe explícito, esse será o nome especificado quando você chamou `CREATE_PIPE`. Cuidado: Não use nomes de pipe que comecem com '`ORA$`'. Esses nomes são reservados para uso pelos procedimentos fornecidos pela Oracle. Pipename não deve ter mais de 128 bytes e não faz distinção entre maiúsculas e minúsculas. No momento, o nome não pode conter caracteres de Suporte à Globalização.
`timeout`	Tempo de espera durante a tentativa de colocar uma mensagem em um pipe, em segundos. O valor padrão é a constante `MAXWAIT`, que é definida como 86400000 (1000 dias).
`maxpipesize`	Tamanho máximo permitido para o pipe, em bytes. O tamanho total de todas as mensagens no pipe não pode exceder esse volume. A mensagem será bloqueada se exceder este máximo. O padrão é 65536 bytes. O `maxpipesize` de um pipe se torna parte das características do pipe e persiste durante a vida útil dele. Os chamadores de `SEND_MESSAGE` com valores maiores fazem com que `maxpipesize` seja aumentado. Os chamadores com um valor menor simplesmente usam o valor existente maior. A especificação de `maxpipesize` como parte do procedimento `SEND_MESSAGE` elimina a necessidade de uma chamada separada para abrir o pipe. Se você criou o pipe explicitamente, poderá usar o parâmetro `maxpipesize` opcional para substituir as especificações de tamanho do pipe de criação. O padrão `maxpipesize` de 65536 é aplicável para todos os Pipes.
`singleton`	Use `TRUE` para criar um Singleton Pipe. Valor padrão: `FALSE`
`shelflife`	Tempo de expiração em segundos de uma mensagem armazenada em cache no Singleton Pipe. Depois que o tempo `shelflife` especificado for excedido, a mensagem não poderá mais ser acessada no Pipe. O parâmetro `shelflife` só é aplicável a um Singleton Pipe. O valor padrão é `0`, o que implica que a mensagem nunca expira.

Valores de Retorno

Retornar	Descrição
`0`	Bem-Sucedida. Se o pipe já existir e o usuário que estiver tentando criá-lo estiver autorizado a usá-lo, o sistema Oracle retornará 0, indicando êxito, e quaisquer dados já existentes no pipe permanecerão. Se um usuário conectado como `SYSDBS`/`SYSOPER` recriar um pipe, o sistema Oracle retornará o status 0, mas a propriedade do pipe permanecerá inalterada.
`1`	Tempo esgotado. Este procedimento pode sofrer timeout porque não pode obter um bloqueio no pipe ou porque o pipe permanece muito cheio para ser usado. Se o pipe foi criado implicitamente e está vazio, então ele é removido.
`3`	Ocorreu uma interrupção. Se o pipe foi criado implicitamente e está vazio, ele é removido.
`6`	Falha ao converter pipe existente em pipe singleton. O pipe implícito com mais de uma mensagem existente não pode ser convertido em um Pipe Singleton. Para um pipe explícito que não seja Singleton, `DBMS_PIPE.SEND_MESSAGE` não pode enviar uma mensagem com o argumento singleton definido como `TRUE`.
`7`	Um valor diferente de zero é fornecido para o parâmetro `shelflife` e o pipe não é um pipe singleton.
`ORA-23322`	Privilégios insuficientes. Se existir um pipe com o mesmo nome e tiver sido criado por outro usuário, o sistema Oracle sinalizará o erro `ORA-23322`, indicando o conflito de nomeação.

Exceções

Exceção	Descrição
`Null pipe name`	Erro de permissão. Privilégio insuficiente para gravar no pipe. O cachimbo é privado e pertence a outra pessoa.

Conteúdo Relacionado

Armazenar Mensagens em Cache com Pipes Singleton