Documentação do Oracle Cloud Infrastructure

Pacote DBMS_PIPE

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

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

Consulte DBMS_PIPE para obter detalhes sobre a funcionalidade principal DBMS_PIPE fornecida no Oracle Database.

Tópico principal: Referência de Pacote Fornecida pelo Autonomous Database

DBMS_PIPE Visão Geral de Pipes Singleton

A funcionalidade de 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.

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

  • Compartilhe a mensagem armazenada no cache em várias sessões do 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 Gravação.

Um Pipe Singleton 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.
  • Pipe Público: Acessível por qualquer usuário com a permissão EXECUTE no pacote DBMS_PIPE
  • Pipe Privado: Acessível por sessões com o mesmo usuário do criador do pipe.

Tópico principal: Pacote DBMS_PIPE

Resumo de Subprogramas DBMS_PIPE para Pipes Singleton

Esta tabela lista os subprogramas DBMS_PIPE e os descreve brevemente.

Tabela 6-1 Subprogramas do Pacote DBMS_PIPE

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 proprietário do pipe privado.
  • Função RECEIVE_MESSAGE
    Essa função copia a mensagem para o buffer de mensagem local.
  • Função SEND_MESSAGE
    Esta função envia uma mensagem no canal nomeado.

Tópico principal: Pacote DBMS_PIPE

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 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 Pipe Singleton, defina o parâmetro singleton como TRUE. Os seguintes argumentos são aplicáveis ao Singleton Pipes:

  • singleton: Indica que o pipe deve ser criado como um Pipe Singleton (valor padrão: FALSE).

  • shelflife: Como opção, especifique uma expiração de prazo de validade (em segundos) da mensagem armazenada no cache no Pipe Singleton. 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 6-2 Parâmetros de 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 que comecem com ORA$. Elas são reservadas para uso pelos procedimentos fornecidos pela Oracle. O nome do pipeline 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 este máximo.

O maxpipesize padrão é 66536 bytes.

O maxpipesize de um tubo se torna 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 maxpipesize seja aumentado. Os 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 shelflife especificado for excedido, a mensagem não estará mais acessível no Pipe. O parâmetro shelflife só é aplicável a um Pipe Singleton.

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

Retornar Valores

Tabela 6-3 CREATE_PIPE Valores de Retorno da Função

Retornar Descrição

0

Sucesso.

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 que já estejam no pipe permanecerão.

6

Falha ao converter o canal existente para o canal único.

  • 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 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 nomeação.

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

Exceções

Tabela 6-4 Exceção de 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 Singleton Pipe com vida útil 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 6-5 Parâmetros de Função RECEIVE_MESSAGE

Parâmetro Descrição

pipename

Nome do canal 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. 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 Pipe Singleton.

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

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Valor padrão: NULL

Retornar Valores

Tabela 6-6 RECEIVE_MESSAGE Valores de Retorno da Função

Retornar Descrição

0

Bem-sucedido

1

Expirado. Se o pipe foi criado implicitamente e está 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 Pipe Singleton.

ORA-23322

O usuário não tem privilégios suficientes para ler no pipe.

Observações de 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 depois que o último registro é removido do pipe.

Se o pipe especificado quando você chama RECEIVE_MESSAGE ainda não existir, o sistema Oracle criará implicitamente o pipe e aguardará o recebimento da mensagem. Se a mensagem não chegar dentro de um intervalo de timeout 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 está 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 da Função de Cache

O Singleton Pipes suporta a função de cache para armazenar automaticamente 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 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 ao Pipe Singleton, opcionalmente especificando um shelflife para a mensagem implícita.

Exceções

Tabela 6-7 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 é 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 mensagem 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 ao Singleton Pipes:

  • singleton: Indica que o pipe deve ser criado como um Pipe Singleton (valor padrão: FALSE).
  • shelflife: Como opção, especifique uma expiração de prazo de validade da mensagem armazenada no cache no Pipe Singleton. 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 na Função CREATE_PIPE e será o padrão para quaisquer novas mensagens armazenadas 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 6-8 Parâmetros de Função SEND_MESSAGE

Parâmetro Descrição

pipename

Nome do canal 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 por procedimentos fornecidos pela Oracle. O nome do pipeline 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 este máximo. O padrão é 65536 bytes.

O maxpipesize de um tubo se torna 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 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 shelflife especificado for excedido, a mensagem não estará mais acessível no Pipe. O parâmetro shelflife só é aplicável a um Pipe Singleton.

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

Retornar Valores

Tabela 6-9 Valores de Retorno da Função SEND_MESSAGE

Retornar Descrição

0

Com Sucesso.

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 que já estejam 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

Expirado.

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, ele será removido.

3

Ocorreu uma interrupção.

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

6

Falha ao converter o canal existente para o canal único.

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

Não há privilégios suficientes.

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

Exceções

Tabela 6-10 Exceção de 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.

DBMS_PIPE Visão Geral de Pipes de Mensagens Persistentes

A funcionalidade de 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.

Mensagens Persistentes em DBMS_PIPE:

  • Apoie 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 em bancos de dados em diferentes regiões.

  • Suporta vários pipes usando o mesmo URI de localização 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 Armazenamento de Objetos na Nuvem. O uso dessas mensagens de funcionalidade em um pipe pode ser disponibilizado apenas 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 Persistentes pode ser qualquer um dos tipos de 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.
    • Pipe Público: Acessível por qualquer usuário com a permissão EXECUTE no pacote DBMS_PIPE.
    • Pipe Privado: Acessível por sessões com o mesmo usuário do 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 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.

Consulte Selecionar um Conjunto de Caracteres para o Autonomous Database para obter mais informações.

Tópico principal: Pacote DBMS_PIPE

Resumo de Subprogramas DBMS_PIPE para Mensagens Persistentes

Esta tabela lista os subprogramas DBMS_PIPE e os descreve brevemente.

Tabela 6-11 Subprogramas do Pacote DBMS_PIPE

Subprograma Descrição

Função CREATE_PIPE

Cria um pipe (necessário para pipes privados).

Função GET_CREDENTIAL_NAME

Retorna o valor da variável credential_name global.

Função GET_LOCATION_URI

Retorna o valor da variável location_uri global que é usado como um URI de localização padrão para uso quando uma mensagem é armazenada no Armazenamento de Objetos na Nuvem.

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 criará implicitamente um pipe público se o pipe nomeado não existir.

Procedimento SET_CREDENTIAL_NAME

Define a variável credential_name usada como credencial padrão para mensagens armazenadas no Armazenamento de Objetos na Nuvem.

Procedimento SET_LOCATION_URI

Define a variável global location_uri que é usada como um URI de localização padrão para mensagens armazenadas no Armazenamento de Objetos na Nuvem.

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 proprietário do pipe privado.
  • Função GET_CREDENTIAL_NAME
    Essa função retorna o valor da variável credential_name global para uso quando as mensagens são armazenadas no Armazenamento de Objetos na Nuvem.
  • 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 localização padrão quando mensagens de pipe são armazenadas no Armazenamento de Objetos na Nuvem.
  • Função RECEIVE_MESSAGE
    Essa função copia a mensagem para o buffer de mensagem local.
  • Função SEND_MESSAGE
    Esta função envia uma mensagem no canal nomeado.
  • 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 Armazenamento de Objetos na Nuvem.
  • Procedimento SET_LOCATION_URI
    Esse procedimento define a variável location_uri global.

Tópico principal: Pacote DBMS_PIPE

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 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 6-12 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 que comecem com ORA$. Elas são reservadas para uso pelos procedimentos fornecidos pela Oracle. O nome do pipeline 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 este máximo.

O maxpipesize padrão é 66536 bytes.

O maxpipesize de um tubo se torna 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 maxpipesize seja aumentado. Os 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.

Retornar Valores

Tabela 6-13 CREATE_PIPE Valores de Retorno da Função

Retornar Descrição

0

Sucesso.

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 que já estejam no pipe permanecerão.

ORA-23322

Falha devido a conflito de nomeação.

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

Exceções

Tabela 6-14 Exceção de 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 uma particular explícita denominada 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 Armazenamento de Objetos na Nuvem.

Sintaxe

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Retornar Valores

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 URI de localização padrão quando mensagens de pipe são armazenadas no Armazenamento de Objetos na Nuvem.

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 6-15 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 começam 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 do armazenamento na 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.

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um ARN (Amazon Resource Name) ou uma conta de serviço do Google. Consulte Configurar Políticas e Atribuições para Acessar Recursos para obter mais informações sobre autenticação baseada no controlador de recursos.

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 passado tem precedência sobre o valor da variável global.

Retornar Valores

Tabela 6-16 RECEIVE_MESSAGE Valores de Retorno da Função

Retornar Descrição

0

Bem-sucedido

1

Expirado. Se o pipe foi criado implicitamente e está 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 de 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 depois que o último registro é removido do pipe.

  • Se o pipe especificado quando você chama RECEIVE_MESSAGE ainda não existir, o sistema Oracle criará implicitamente o pipe e aguardará o recebimento da mensagem. Se a mensagem não chegar dentro de um intervalo de timeout 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 está 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 6-17 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 é 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 mensagem 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 6-18 Parâmetros da Função SEND_MESSAGE

Parâmetro Descrição
credential_name

O nome da credencial do armazenamento na 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.

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um ARN (Amazon Resource Name) ou uma conta de serviço do Google. Consulte Configurar Políticas e Atribuições para Acessar Recursos para obter mais informações sobre autenticação baseada no controlador de recursos.

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 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 valor. A mensagem será bloqueada se exceder este máximo. O padrão é 65536 bytes.

O maxpipesize de um tubo se torna 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 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 canal 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 por procedimentos fornecidos pela Oracle. O nome do pipeline 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).

Retornar Valores

Tabela 6-19 Valores de Retorno da Função SEND_MESSAGE

Retornar Descrição

0

Com Sucesso.

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 que já estejam 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

Expirado.

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, ele será removido.

3

Ocorreu uma interrupção.

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

ORA-23322

Não há privilégios suficientes.

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

Observações de 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 6-20 Exceção de 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

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

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um ARN (Amazon Resource Name) ou uma conta de serviço do Google. Consulte Configurar Políticas e Atribuições para Acessar Recursos para obter mais informações sobre autenticação baseada no controlador de recursos.

Nota 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 DBMS_CLOUD Formatos de URI.

Nota 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;
/