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 do DBMS_PIPE conforme disponível no Oracle Database 19c, além de extensões.

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

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

DBMS_PIPE Visão Geral de Tubos Singleton

A funcionalidade Pipe possui 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 oferecer suporte a pipes singleton.

Os recursos de pipe singleton no DBMS_PIPE fornecem o seguinte:

  • Capacidade de armazenar em cache e recuperar uma mensagem personalizada, de até 32.767 bytes, na memória do banco de dados Oracle. O tamanho máximo da mensagem de 32.767 bytes é aplicável a todos os Pipes, incluindo Pipes Singleton. As versões anteriores do DBMS_PIPE tinham um tamanho máximo de mensagem menor.

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

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

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

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

  • Suporta bancos de dados Somente Leitura e Leitura/Gravação.

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

  • Tubo Implícito: Criado 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.

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 tubo (necessário para tubos privados)

Função NEXT_ITEM_TYPE

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

PACK_MESSAGE Procedimentos

Compila 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

RESET_BUFFER Procedimento

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

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

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

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

  • shelflife: Opcionalmente, especifique uma expiração de prazo de validade (em segundos) da mensagem armazenada em cache no Singleton Pipe. Ele pode ser usado para invalidação implícita de mensagem no Singleton Pipe.

    A mensagem shelflife no Singleton Pipe também pode ser especificada quando você envia uma mensagem de mensagem (consulte a 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 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 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.

singleton

Use TRUE para criar um Singleton Pipe.

Valor padrão: FALSE

shelflife

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

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

Valores de Retorno

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

Retornar Descrição

0

Bem-sucedido.

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.

6

Falha ao converter pipe existente em pipe singleton.

  • O pipe implícito com mais de uma mensagem existente não pode ser convertido em um Pipe Singleton.
  • Para um pipe explícito que não seja Singleton, DBMS_PIPE.SEND_MESSAGE não pode enviar uma mensagem com o argumento singleton definido como TRUE.

7

Um valor diferente de zero é fornecido para o parâmetro shelflife e o pipe não é um pipe singleton.

ORA-23322

Falha devido a conflito de nomes.

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

Exceções

Tabela 6-4 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 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 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 função de cache de execução especificada no parâmetro cache_func.

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

cache_func

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

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

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

Valor padrão: NULL

Valores de Retorno

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

Retornar Descrição

0

Sucesso

1

Tempo limite atingido. Se o pipe foi criado implicitamente e está vazio, então ele é removido.

2

O registro no pipe é muito grande para o buffer.

3

Ocorreu uma interrupção.
8

A função de cache só pode ser especificada ao usar um Singleton Pipe.

ORA-23322

O usuário tem privilégios insuficientes para ler do pipe.

Observações 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 após o último registro ser removido do pipe.

Se o pipe especificado quando você chama RECEIVE_MESSAGE ainda não existir, o sistema Oracle cria implicitamente o pipe e aguarda o recebimento da mensagem. Se a mensagem não chegar dentro de um intervalo de tempo limite designado, a chamada retornará e o pipe será removido.

Depois de receber a mensagem, você deve fazer uma ou mais chamadas para UNPACK_MESSAGE para acessar os itens individuais na mensagem. O procedimento UNPACK_MESSAGE é sobrecarregado para descompactar itens do tipo DATE, NUMBER, VARCHAR2 e há dois procedimentos adicionais para descompactar itens RAW e ROWID. Se você não souber o tipo de dados que está tentando descompactar, chame NEXT_ITEM_TYPE para determinar o tipo do próximo item no buffer.

Parâmetro da Função de Cache

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

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

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

  • OWNER.FUNCTION_NAME
  • OWNER.PACKAGE.FUNCTION_NAME

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

Sintaxe da Função de Cache

CREATE OR REPLACE FUNCTION cache_function_name (
       pipename  IN VARCHAR2
) RETURN INTEGER;
Parâmetro Tipo de Dados Descrição

pipename

 VARCHAR2

Nome do Singleton Pipe.
Retornar Descrição
0 Sucesso
Diferente de zero Valor de falha retornado de DBMS_PIPE.RECEIVE_MESSAGE

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

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

Exceções

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 é propriedade de outra pessoa.

Exemplo

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

Função SEND_MESSAGE

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

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

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

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

    Este argumento é aplicável para tubos Singleton implícitos e explícitos. Um valor shelflife especificado 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 todas as novas mensagens armazenadas 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 6-8 Parâmetros da Função SEND_MESSAGE

Parâmetro Descrição

pipename

Nome do pipe no qual você deseja colocar a mensagem.

Se você estiver usando um pipe explícito, esse será o nome especificado quando você chamou CREATE_PIPE.

Cuidado: Não use nomes de pipe que comecem com 'ORA$'. Esses nomes são reservados para uso pelos procedimentos fornecidos pela Oracle. Pipename não deve ter mais de 128 bytes e não faz distinção entre maiúsculas e minúsculas. No momento, o nome não pode conter caracteres de Suporte à Globalização.

timeout

Tempo de espera durante a tentativa de colocar uma mensagem em um pipe, em segundos.

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

maxpipesize

Tamanho máximo permitido para o pipe, em bytes.

O tamanho total de todas as mensagens no pipe não pode exceder esse volume. A mensagem será bloqueada se exceder este máximo. O padrão é 65536 bytes.

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

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

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

singleton

Use TRUE para criar um Singleton Pipe.

Valor padrão: FALSE

shelflife

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

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

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

Valores de Retorno

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

Retornar Descrição

0

Êxito.

Se o pipe já existir e o usuário que estiver tentando criá-lo estiver autorizado a usá-lo, o sistema Oracle retornará 0, indicando êxito, e quaisquer dados já existentes no pipe permanecerão.

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

1

Tempo limite atingido.

Este procedimento pode sofrer timeout porque não pode obter um bloqueio no pipe ou porque o pipe permanece muito cheio para ser usado. Se o pipe foi criado implicitamente e está vazio, então ele é removido.

3

Ocorreu uma interrupção.

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

6

Falha ao converter pipe existente em pipe singleton.

  • O pipe implícito com mais de uma mensagem existente não pode ser convertido em um Pipe Singleton.
  • Para um pipe explícito que não seja Singleton, DBMS_PIPE.SEND_MESSAGE não pode enviar uma mensagem com o argumento singleton definido como TRUE.

7

Um valor diferente de zero é fornecido para o parâmetro shelflife e o pipe não é um pipe singleton.

ORA-23322

Privilégios insuficientes.

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

Exceções

Tabela 6-10 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.

DBMS_PIPE Visão Geral de 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 Database, o pacote DBMS_PIPE tem funcionalidade estendida para suportar pipes de mensagens persistentes.

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:

    • Tubo Implícito: Criado 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 o 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).

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.

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

Tópico principal: Pacote DBMS_PIPE

Resumo dos 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 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

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

PACK_MESSAGE Procedimentos

Compila mensagem no buffer local.

Função RECEIVE_MESSAGE

Copia a mensagem do pipe nomeado para o buffer local.

RESET_BUFFER Procedimento

Limpa o conteúdo do buffer local.

Função REMOVE_PIPE

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.

SET_CREDENTIAL_NAME Procedimento

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

SET_LOCATION_URI Procedimento

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.
  • 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 Cloud Object Store.
  • 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.
  • Função RECEIVE_MESSAGE
    Essa função copia a mensagem para o buffer de mensagens local.
  • Função SEND_MESSAGE
    Essa função envia uma mensagem no pipe nomeado.
  • 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.
  • SET_LOCATION_URI Procedimento
    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 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 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 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

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

Retornar Descrição

0

Bem-sucedido.

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

Tabela 6-14 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 nome privado explícito 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 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 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.

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um Amazon Resource Name (ARN) 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 em controlador de recursos.

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 6-16 Valores de Retorno da Função RECEIVE_MESSAGE

Retornar Descrição

0

Sucesso

1

Tempo limite atingido. 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 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 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 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 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 é 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 6-18 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.

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um Amazon Resource Name (ARN) 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 em controlador de recursos.

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 6-19 Valores de Retorno da Função SEND_MESSAGE

Retornar Descrição

0

Êxito.

Se o pipe já existir e o usuário que estiver tentando criá-lo estiver autorizado a usá-lo, o sistema Oracle retornará 0, indicando êxito, e quaisquer dados já existentes no pipe permanecerão.

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

1

Tempo limite atingido.

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

SET_CREDENTIAL_NAME Procedimento

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.

O valor credential_name pode ser um controlador de recursos do OCI, um controlador de serviços do Azure, um Amazon Resource Name (ARN) 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 em controlador de recursos.

Observação do 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.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

SET_LOCATION_URI Procedimento

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 do Cloud Object Storage que você estiver usando. Para obter detalhes, consulte DBMS_CLOUD Formatos de URI.

Observação do 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;
/