Pacote DBMS_PIPE (Pipes de Mensagens Persistentes)

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 dos Pipes de Mensagens Persistentes

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 de mensagens persistentes. 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.

Mensagens Persistentes em DBMS_PIPE:

  • Suporta a capacidade de enviar e recuperar mensagens muito grandes.

  • Suporta um grande número de mensagens de pipe.

  • Suporte ao compartilhamento de mensagens em um único banco de dados, em vários bancos de dados e entre bancos de dados em diferentes regiões.

  • Suporta vários pipes usando o mesmo URI de local do Armazenamento de Objetos na Nuvem.

    A funcionalidade de mensagens persistentes permite que duas ou mais sessões de banco de dados se comuniquem com mensagens armazenadas no Armazenamento de Objetos na Nuvem. Usando essa funcionalidade, as mensagens em um pipe podem ser disponibilizadas apenas para o banco de dados atual ou podem ser disponibilizadas para vários bancos de dados na mesma região ou em diferentes regiões.

    Um Pipe de Mensagens Persistentes 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.

Observação:

Ao enviar e receber mensagens em diferentes bancos de dados usando mensagens persistentes, a Oracle recomenda que você chame DBMS_PIPE.CREATE_PIPE antes de enviar ou receber mensagens. A criação de um pipe explícito com DBMS_PIPE.CREATE_PIPE garante que um pipe seja criado com as permissões de acesso desejadas, públicas ou privadas (definindo o parâmetro PRIVATE como FALSE ou usando o valor padrão TRUE).

DBMS_PIPE Limitação

O pacote DBMS_PIPE não suporta o envio de mensagens entre bancos de dados que usam conjuntos de caracteres diferentes. Por exemplo, se você tiver uma instância do Autonomous Database que use AL32UTF8 e outra instância que use WE8MSWIN1252, não poderá enviar mensagens com DBMS_PIPE entre esses dois bancos de dados. Nesse caso, o sistema gerará o erro ORA-12704 se você tentar enviar mensagens com DBMS_PIPE entre esses dois bancos de dados.

Resumo de Subprogramas DBMS_PIPE para Mensagens Persistentes

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 GET_CREDENTIAL_NAME

Retorna o valor global da variável credential_name.

Função GET_LOCATION_URI

Retorna o valor da variável location_uri global que é usado como um URI de local padrão para uso quando uma mensagem é armazenada no Cloud Object Store.

Função NEXT_ITEM_TYPE

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

Cria mensagem no buffer local.

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

Função SEND_MESSAGE

Envia mensagem em um pipe nomeado: Isso cria implicitamente um pipe público se o pipe nomeado não existir.

Procedimento SET_CREDENTIAL_NAME

Define a variável credential_name que é usada como credencial padrão para mensagens armazenadas no Cloud Object Store.

Procedimento SET_LOCATION_URI

Define a variável location_uri global que é usada como um URI de local padrão para mensagens armazenadas no Cloud Object Store.

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.

Sintaxe

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
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.

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.

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 privado explícito chamado MY_PIPE1

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

Função GET_CREDENTIAL_NAME

Essa função retorna o valor global da variável credential_name para uso quando as mensagens são armazenadas no Cloud Object Store.

Sintaxe

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valores de Retorno

Valor de Retorno Descrição

credential_name

O nome da credencial para acessar o Cloud Object Storage.

Exemplo

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

Função GET_LOCATION_URI

Essa função retorna o valor da variável location_uri global que pode ser usado como um URI de local padrão quando mensagens de pipe são armazenadas no Cloud Object Store.

Sintaxe

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valor de Retorno

Valor de Retorno Descrição
location_uri

O URI do objeto.

Exemplo

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
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,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
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 execução da função de cache especificada com o parâmetro cache_func.

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

credential_name

O nome da credencial do armazenamento em nuvem usado para armazenar mensagens.

O credential_name é um argumento de pacote que, por padrão, é inicializado como NULL.

Você pode definir esse valor antes de chamar DBMS_PIPE.RECEIVE_MESSAGE. O valor do parâmetro informado tem precedência sobre o valor da variável global.

O objeto de credencial deve ter privilégios EXECUTE e READ/WRITE pelo usuário que está executando DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

O URI de local do armazenamento na nuvem usado para armazenar mensagens.

O location_uri é uma variável global que, por padrão, é inicializada como NULL.

Você pode definir esse valor antes de chamar DBMS_PIPE.RECEIVE_MESSAGE. O valor do parâmetro informado tem precedência sobre o valor da variável global.

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.

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.

  • As mensagens persistentes são garantidas para serem escritas ou lidas por exatamente um processo. Isso evita a inconsistência do conteúdo da mensagem devido a gravações e leituras simultâneas. Usando um pipe de mensagens persistente, DBMS_PIPE permite que apenas uma operação, enviando uma mensagem ou uma mensagem de recebimento, fique ativa em um determinado momento. No entanto, se uma operação não for possível devido a uma operação em andamento, o processo repetirá periodicamente até que o valor timeout seja atingido.

  • Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

    • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

    • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

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.

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.

Sintaxe

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

Parâmetros

Tabela - Parâmetros da Função SEND_MESSAGE

Parâmetro Descrição
credential_name

O nome da credencial do armazenamento em nuvem usado para armazenar mensagens.

O credential_name é um argumento de pacote que, por padrão, é inicializado como NULL.

Você pode definir esse valor antes de chamar DBMS_PIPE.SEND_MESSAGE. O valor do parâmetro informado tem precedência sobre o valor da variável global.

O objeto de credencial deve ter privilégios EXECUTE e READ/WRITE pelo usuário que está executando DBMS_PIPE.SEND_MESSAGE.

location_uri

O URI de local do armazenamento na nuvem usado para armazenar mensagens.

O location_uri é uma variável global que, por padrão, é inicializada como NULL.

Você pode definir esse valor antes de chamar DBMS_PIPE.SEND_MESSAGE. O valor do parâmetro informado tem precedência sobre o valor da variável global.

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.

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

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.

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.

Observações sobre Uso

  • As mensagens persistentes são garantidas para serem escritas ou lidas por exatamente um processo. Isso evita a inconsistência do conteúdo da mensagem devido a gravações e leituras simultâneas. Usando um pipe de mensagens persistente, DBMS_PIPE permite que apenas uma operação, enviando uma mensagem ou uma mensagem de recebimento, fique ativa em um determinado momento. No entanto, se uma operação não for possível devido a uma operação em andamento, o processo repetirá periodicamente até que o valor timeout seja atingido.

  • Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

    • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

    • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

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.

Procedimento SET_CREDENTIAL_NAME

Este procedimento define a variável credential_name que é usada como credencial padrão quando mensagens de pipe são armazenadas no Cloud Object Store.

Sintaxe

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parâmetros

Parâmetro Descrição

credential_name

O nome da credencial para acessar o Cloud Object Storage.

Observações de Uso

Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

  • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

  • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

Exemplo

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

Procedimento SET_LOCATION_URI

Este procedimento define a variável global location_uri.

Sintaxe

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

Parâmetro

Parâmetro Descrição
location_uri

URI do objeto ou do arquivo. O formato do URI depende do serviço Cloud Object Storage que você está usando. Para obter detalhes, consulte Formatos de URI do Cloud Object Storage.

Observações de Uso

Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

  • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

  • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

Exemplo

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/