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

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

Mensagens Persistentes no DBMS_PIPE:

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

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

• Ofereça 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.

• Suporte a vários pipes usando o mesmo URI de local do Cloud Object Store.

  A funcionalidade de mensagens persistentes permite que duas ou mais sessões do banco de dados se comuniquem com mensagens armazenadas no Cloud Object Store. O uso dessas mensagens de funcionalidade em um pipe pode ser disponibilizado somente para o banco de dados atual ou pode ser disponibilizado para vários bancos de dados na mesma região ou em diferentes regiões.

  Um Pipe de Mensagens Persistente 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. 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, sejam públicas ou privadas (definindo o parâmetro PRIVATE como FALSE ou usando o valor padrão TRUE).

Limitação de DBMS_PIPE

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

Subprograma	Descrição
Função CREATE_PIPE	Cria um tubo (necessário para tubos privados).
Função GET_CREDENTIAL_NAME	Retorna o valor da variável global credential_name.
Função GET_LOCATION_URI	Retorna o valor da variável global location_uri que é usado como um URI de local padrão para uso quando uma mensagem é armazenada no Cloud Object Store.
Função NEXT_ITEM_TYPE Pacotes e Tipos PL/SQL do Oracle Database 19c - Referência 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 Referência de Tipos e Pacotes PL/SQL Oracle Database 19c Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Compila mensagem no buffer local.
Função RECEIVE_MESSAGE	Copia a mensagem do pipe nomeado para o buffer local.
Procedimento RESET_BUFFER Pacotes e Tipos PL/SQL do Oracle Database 19c - Referência Pacotes e Tipos de PL/SQL do Oracle Database 26ai	Limpa o conteúdo do buffer local.
Função REMOVE_PIPE Pacotes e Tipos de PL/SQL do Oracle Database 19c Pacotes e Tipos de PL/SQL do Oracle Database 26ai	Remove o pipe 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 uma 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 Pacotes e Tipos de PL/SQL do Oracle Database 19c - Referência Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai	Retorna um nome de sessão exclusivo.
Procedimentos UNPACK_MESSAGE Referência de Tipos e Pacotes PL/SQL Oracle Database 19c 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.

Sintaxe

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

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.
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 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 da variável global 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 para o buffer de mensagem 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 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 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 para o 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 passado 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 do 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 passado 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-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.
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.

• 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 esteja 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 será repetido periodicamente até que o valor timeout seja atingido.

• Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI de local e a credencial devem corresponder no 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 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 da 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 é 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 para o 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 passado 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 do 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 passado 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 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.
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).

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

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 esteja 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 será repetido periodicamente até que o valor timeout seja atingido.

• Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI do local e a credencial devem corresponder no 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 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 cachimbo é privado e pertence a outra pessoa.

Procedimento SET_CREDENTIAL_NAME

Este procedimento define a variável credential_name que é usada como uma 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 ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI de local e a credencial devem corresponder no 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 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 ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI do local e a credencial devem corresponder no 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 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;
/

Conteúdo Relacionado

• Usar Mensagens Persistentes com Mensagens Armazenadas no Cloud Object Store