Pacote DBMS_PIPE (Tubos Únicos)

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

O Oracle Autonomous Database on Dedicated Exadata Infrastructure suporta a funcionalidade DBMS_PIPE principal, 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 23ai PL/SQL Packages and Types Reference para obter detalhes sobre a funcionalidade básica do DBMS_PIPE fornecida no Oracle Database.

Tópicos Relacionados

DBMS_PIPE Visão Geral de Pipes Singleton

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

No Autonomous Database, o pacote DBMS_PIPE tem funcionalidade estendida para suportar pipes singleton. Consulte DBMS_PIPE em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 23ai PL/SQL Packages and Types Reference para obter mais informações.

Os recursos de pipe Singleton em 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 os Singleton Pipes. As versões anteriores de DBMS_PIPE tinham um tamanho máximo de mensagem menor.

  • Compartilhe a mensagem armazenada em cache em várias sessões de banco de dados com leituras simultâneas.

  • Métodos de invalidação de cache:

    • Invalidação de cache explícita controlada pelo usuário.
    • invalidação de cache após um intervalo de tempo do parâmetro especificado pelo usuário (shelflife) (em segundos).

  • APIs PL/SQL declarativas e fáceis de usar para armazenamento em cache.

  • Suporta bancos de dados Somente Leitura e Somente Leitura.

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

  • Tubo Implícito: Criado automaticamente quando uma mensagem é enviada com um nome de pipe desconhecido usando a função DBMS_PIPE.SEND_MESSAGE.
  • Tubo Explícito: Criado usando a função DBMS_PIPE.CREATE_PIPE com um nome de pipe especificado pelo usuário.
  • Tubo Público: 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.

Tabela - DBMS_PIPE Subprogramas do Pacote

Subprograma Descrição

Função CREATE_PIPE

Cria um pipe (necessário para pipes privados)
Função NEXT_ITEM_TYPE

Retorna o tipo de dados do próximo item no buffer
PACK_MESSAGE Procedimentos

Cria mensagem no buffer local
Procedimento PURGE

Limpa o conteúdo do pipe nomeado

Função RECEIVE_MESSAGE

Copia a mensagem do pipe nomeado para o buffer local
Procedimento RESET_BUFFER

Limpa o conteúdo do buffer local
Função REMOVE_PIPE

Remove o pipe nomeado

Função SEND_MESSAGE

Envia mensagem no pipe nomeado: Isso criará implicitamente um pipe público se o pipe nomeado não existir
Função UNIQUE_SESSION_NAME

Retorna um nome de sessão exclusivo
UNPACK_MESSAGE Procedimentos

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 aos Pipes Singleton:

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

Tabela - Parâmetros da Função CREATE_PIPE

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 em toda a instância.

Cuidado: Não use nomes de pipe começando com ORA$. Elas são reservadas para uso pelos procedimentos fornecidos pela Oracle. O nome do pip 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 valor. A mensagem será bloqueada se exceder esse máximo.

O maxpipesize padrão é 66536 bytes.

O maxpipesize para um tubo torna-se parte das características do tubo e persiste durante a vida útil do tubo. Os chamadores de SEND_MESSAGE com valores maiores fazem com que o maxpipesize seja aumentado. Chamadores com um valor menor usam o valor maior existente.

O maxpipesize padrão de 65536 é aplicável a 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 Pipe Singleton.

Valor padrão: FALSE

shelflife

Tempo de expiração em segundos de uma mensagem armazenada em cache no Singleton Pipe. Depois que o tempo especificado de shelflife for excedido, a mensagem não estará mais acessível no Pipe. O parâmetro shelflife só é aplicável a um Singleton Pipe.

O valor padrão é 0, que implica que a mensagem nunca expira.

Valores de Retorno

Tabela - Valores de Retorno da Função CREATE_PIPE

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 todos os dados que já estiverem no pipe permanecerão.

6

Falha ao converter o pipe existente em um único pipe.

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

Se um pipe com o mesmo nome existir e tiver sido criado por outro usuário, o sistema Oracle sinalizará o erro ORA-23322, indicando o conflito de nomenclatura.

Exceções

Tabela - Exceção da Função CREATE_PIPE

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 no buffer de mensagens 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

pipename

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

Os nomes que começam com ORA$ são reservados para uso pela Oracle.

timeout

Tempo para esperar por uma mensagem, em segundos. O 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

Armazenar em cache o nome da função para armazenar em cache automaticamente 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-sucedida

1

Tempo esgotado. Se o pipe foi criado implicitamente e estiver vazio, ele será 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 não tem privilégios suficientes para ler no 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 tubos criados implicitamente, o tubo é removido após o último registro ser removido do tubo.

Se o pipe que você especificar quando chamar RECEIVE_MESSAGE ainda não existir, o sistema Oracle criará implicitamente o pipe e aguardará para receber a 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 desembalar itens do tipo DATE, NUMBER, VARCHAR2, e há dois procedimentos adicionais para desembalar 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 de Função de Cache

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

  • O 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-sucedida
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 do leitor 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 Pipe Singleton.
  • Envie Mensagem para o Singleton Pipe, opcionalmente especificando um shelflife para a mensagem implícita.

Exceções

Tabela - Exceções de Função RECEIVE_MESSAGE

Exceção Descrição

Null pipe name

Erro de permissão. Privilégio insuficiente para remover o registro do pipe. O cachimbo é de 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 aos Pipes Singleton:

  • 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 na Função SEND_MESSAGE substitui o shelflife especificado para o Pipe Singleton Explícito na Função CREATE_PIPE e será o padrão para qualquer nova mensagem armazenada no cache no Pipe Singleton.

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 começando com 'ORA$'. Esses nomes são reservados para uso pelos procedimentos fornecidos pela Oracle. O nome do pip 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 ao tentar 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 valor. A mensagem será bloqueada se exceder esse máximo. O padrão é 65536 bytes.

O maxpipesize para um tubo torna-se parte das características do tubo e persiste durante a vida útil do tubo. Os chamadores de SEND_MESSAGE com valores maiores fazem com que o maxpipesize seja aumentado. Chamadores com um valor menor simplesmente usam o valor maior existente.

A especificação de maxpipesize como parte do procedimento SEND_MESSAGE elimina a necessidade de uma chamada separada para abrir o pipe. Se você tiver criado o pipe explicitamente, poderá usar o parâmetro maxpipesize opcional para substituir as especificações de tamanho do pipe de criação.

O maxpipesize padrão de 65536 é aplicável a todos os Pipes.

singleton

Use TRUE para criar um Pipe Singleton.

Valor padrão: FALSE

shelflife

Tempo de expiração em segundos de uma mensagem armazenada em cache no Singleton Pipe.

Depois que o tempo especificado de shelflife for excedido, a mensagem não estará mais acessível no Pipe. O parâmetro shelflife só é aplicável a um Singleton Pipe.

O valor padrão é 0, que implica que a mensagem nunca expira.

Valores de Retorno

Tabela - Valores de Retorno da Função SEND_MESSAGE

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 todos os dados que já estiverem no pipe permanecerão.

Se um usuário conectado como SYSDBS/SYSOPER recriar um pipe, a Oracle retornará o status 0, mas a propriedade do pipe permanecerá inalterada.

1

Tempo esgotado.

Este procedimento pode expirar 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 estiver vazio, ele será removido.

3

Ocorreu uma interrupção.

Se o pipe foi criado implicitamente e estiver vazio, ele será removido.

6

Falha ao converter o pipe existente em um único pipe.

  • Um 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 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 um pipe com o mesmo nome existir e tiver sido criado por outro usuário, o sistema Oracle sinalizará o erro ORA-23322, indicando o conflito de nomenclatura.

Exceções

Tabela - Exceção da Função SEND_MESSAGE

Exceção Descrição

Null pipe name

Erro de permissão. Privilégio insuficiente para gravar no pipe. O tubo é privado e pertence a outra pessoa.