Paquete DBMS_PIPE (tubos de mensajes persistentes)

El paquete DBMS_PIPE permite que se comuniquen dos o más sesiones en la misma instancia.

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure admite la funcionalidad principal DBMS_PIPE disponible en Oracle Database 19c, además de las extensiones.

Consulte DBMS_PIPE en Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 26ai PL/SQL Packages and Types Reference para obtener más información sobre la funcionalidad principal DBMS_PIPE proporcionada en Oracle Database.

Descripción general de DBMS_PIPE para pipelines de mensajería persistentes

La funcionalidad Pipe tiene varias aplicaciones potenciales: interfaz de servicio externo, depuración, transacciones independientes y alertas.

En la base de datos de IA autónoma, el paquete DBMS_PIPE tiene una funcionalidad ampliada para admitir canales de mensajería persistentes. Consulte DBMS_PIPE en Oracle Database 19c PL/SQL Packages and Types Reference o Oracle Database 26ai PL/SQL Packages and Types Reference para obtener más información.

Mensajes Persistentes en DBMS_PIPE:

Limitación DBMS_PIPE

El paquete DBMS_PIPE no soporta el envío de mensajes entre bases de datos que utilizan diferentes juegos de caracteres. Por ejemplo, si tiene una instancia de base de datos de IA autónoma que utiliza AL32UTF8 y otra instancia que utiliza WE8MSWIN1252, no puede enviar mensajes con DBMS_PIPE entre estas dos bases de datos. En este caso, el sistema emitirá el error ORA-12704 si intenta enviar mensajes con DBMS_PIPE entre estas dos bases de datos.

Resumen de Subprogramas DBMS_PIPE para Mensajería Persistente

En esta tabla se muestran los subprogramas DBMS_PIPE y se describen brevemente.

Subprograma Descripción
Función CREATE_PIPE Crea una tubería (necesaria para tuberías privadas).
Función GET_CREDENTIAL_NAME Devuelve el valor de variable global credential_name.
Función GET_LOCATION_URI Devuelve el valor de variable global location_uri que se utiliza como URI de ubicación por defecto para su uso cuando se almacena un mensaje en el almacén de objetos en la nube.

Función NEXT_ITEM_TYPE

 Devuelve el tipo de dato del siguiente elemento del buffer.

Procedimientos PACK_MESSAGE

 Crea un mensaje en el buffer local.
Función RECEIVE_MESSAGE Copia el mensaje del conducto con nombre en el buffer local.

Procedimiento RESET_BUFFER

 Depura el contenido del buffer local.

Función REMOVE_PIPE

 Elimina el conducto con nombre.
Función SEND_MESSAGE Envía un mensaje en un conducto con nombre: esto crea implícitamente un conducto público si el conducto con nombre no existe.
Procedimiento SET_CREDENTIAL_NAME Define la variable credential_name que se utiliza como credencial por defecto para los mensajes almacenados en el almacén de objetos en la nube.
Procedimiento SET_LOCATION_URI Define la variable global location_uri que se utiliza como URI de ubicación por defecto para los mensajes almacenados en el almacén de objetos en la nube.

Función UNIQUE_SESSION_NAME

 Devuelve un nombre de sesión único.

Procedimientos UNPACK_MESSAGE

 Accede al siguiente elemento del buffer.

Función CREATE_PIPE

Esta función crea explícitamente un conducto público o privado. Si el indicador private es TRUE, el creador del canal se asigna como propietario del canal privado.

Los pipes creados explícitamente solo se pueden eliminar llamando a REMOVE_PIPE o cerrando la instancia.

Sintaxis

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

Parámetros

parámetro Descripción
pipename

Nombre del conducto que está creando.

Debe utilizar este nombre cuando llame a SEND_MESSAGE y RECEIVE_MESSAGE. Este nombre debe ser único en la instancia.

**Precaución:** No utilice nombres de conductos que comiencen por ORA$. Estos se reservan para su uso mediante los procedimientos proporcionados por Oracle. El nombre de pipeline no debe tener más de 128 bytes y no es sensible a mayúsculas/minúsculas. En este momento, el nombre no puede contener caracteres de soporte de globalización.

maxpipesize

Tamaño máximo permitido para la conducción, en bytes.

El tamaño total de todos los mensajes del conducto no puede superar esta cantidad. El mensaje se bloquea si supera este máximo.

El valor por defecto de maxpipesize es 66536 bytes.

El maxpipesize para una tubería se convierte en una parte de las características de la tubería y persiste durante la vida útil de la tubería. Los emisores de llamadas de SEND_MESSAGE con valores más grandes hacen que se aumente maxpipesize. Los emisores de llamadas con un valor menor utilizan el valor mayor existente.

El valor por defecto maxpipesize de 65536 se aplica a todos los pipes.

private

Utiliza el valor por defecto, TRUE, para crear un conducto privado.

Las tuberías públicas se pueden crear implícitamente al llamar a SEND_MESSAGE.

Valores devueltos

Return Descripción
0

Correcto.

Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, lo que indica que se ha realizado correctamente, y cualquier dato que ya esté en el conducto permanece.
ORA-23322

Error debido a un conflicto de nomenclatura.

Si existe un conducto con el mismo nombre y lo ha creado un usuario diferente, Oracle indica el error ORA-23322, que indica el conflicto de nomenclatura.

Excepciones

Excepción Descripción
Null pipe name Error de permiso: ya existe una pleca con el mismo nombre y no puede utilizarla.

Ejemplo

Crear una privada explícita denominada MY_PIPE1

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

Función GET_CREDENTIAL_NAME

Esta función devuelve el valor de variable global credential_name para su uso cuando los mensajes se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

Valores devueltos

Valor devuelto Descripción
credential_name Nombre de la credencial para acceder a Cloud Object Storage.

Ejemplo

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

Función GET_LOCATION_URI

Esta función devuelve el valor de variable global location_uri que se puede utilizar como URI de ubicación por defecto cuando los mensajes de canal se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

Valor devuelto

Valor devuelto Descripción
location_uri URI del objeto.

Ejemplo

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

Función RECEIVE_MESSAGE

Esta función copia el mensaje en el buffer de mensajes local.

Sintaxis

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

Tabla - Parámetros de función RECEIVE_MESSAGE

parámetro Descripción
pipename

Nombre de la conducción en la que desea recibir un mensaje.

Los nombres que empiecen por ORA$ están reservados para uso de Oracle.

timeout

Tiempo de espera para un mensaje, en segundos. Un timeout de 0 le permite leer sin bloqueo.

El timeout no incluye el tiempo dedicado a ejecutar la función de caché especificada con el parámetro cache_func.

Valor predeterminado: es la constante MAXWAIT, que se define como 86400000 (1000 días).

credential_name

Nombre de credencial del almacén en la nube utilizado para almacenar mensajes.

credential_name es un argumento de paquete que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.RECEIVE_MESSAGE. El valor de parámetro transferido tiene prioridad sobre el valor de la variable global.

El objeto de credencial debe tener privilegios EXECUTE y READ/WRITE por parte del usuario que ejecuta DBMS_PIPE.RECEIVE_MESSAGE.

location_uri

URI de ubicación del almacén en la nube que se utiliza para almacenar mensajes.

location_uri es una variable global que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.RECEIVE_MESSAGE. El valor de parámetro transferido tiene prioridad sobre el valor de la variable global.

Valores devueltos

Tabla - Valores de retorno de función RECEIVE_MESSAGE

Return Descripción
0 Correcto
1 Timeout. Si la tubería se creó implícitamente y está vacía, se elimina.
2 El registro en el conducto es demasiado grande para el buffer.
3 Se produjo una interrupción.
ORA-23322 El usuario no tiene suficientes privilegios para leer desde el conducto.

Notas de uso

Excepciones

Tabla - Excepciones de función RECEIVE_MESSAGE

Excepción Descripción
Null pipe name Error de permiso. Privilegio insuficiente para eliminar el registro de la conducción. La tubería es propiedad de otra persona.

Función SEND_MESSAGE

Esta función envía un mensaje en el conducto con nombre.

El mensaje está incluido en el buffer de mensajes local, que se ha rellenado con llamadas a PACK_MESSAGE. Puede crear un conducto explícitamente mediante CREATE_PIPE; de lo contrario, se crea implícitamente.

Sintaxis

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

Tabla - Parámetros de función SEND_MESSAGE

parámetro Descripción
credential_name

Nombre de credencial del almacén en la nube utilizado para almacenar mensajes.

credential_name es un argumento de paquete que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.SEND_MESSAGE. El valor de parámetro transferido tiene prioridad sobre el valor de la variable global.

El objeto de credencial debe tener privilegios EXECUTE y READ/WRITE por parte del usuario que ejecuta DBMS_PIPE.SEND_MESSAGE.

location_uri

URI de ubicación del almacén en la nube que se utiliza para almacenar mensajes.

location_uri es una variable global que se inicializa por defecto como NULL.

Puede definir este valor antes de llamar a DBMS_PIPE.SEND_MESSAGE. El valor de parámetro transferido tiene prioridad sobre el valor de la variable global.

maxpipesize

Tamaño máximo permitido para la conducción, en bytes.

El tamaño total de todos los mensajes del conducto no puede superar esta cantidad. El mensaje se bloquea si supera este máximo. El valor por defecto es 65536 bytes.

El maxpipesize para una tubería se convierte en una parte de las características de la tubería y persiste durante la vida útil de la tubería. Los emisores de llamadas de SEND_MESSAGE con valores más grandes hacen que se aumente maxpipesize. Las personas que llaman con un valor más pequeño simplemente usan el valor existente, más grande.

Al especificar maxpipesize como parte del procedimiento SEND_MESSAGE, se elimina la necesidad de una llamada independiente para abrir el conducto. Si ha creado el conducto de forma explícita, puede utilizar el parámetro opcional maxpipesize para sustituir las especificaciones de tamaño del conducto de creación.

El valor por defecto maxpipesize de 65536 se aplica a todos los pipes.

pipename

Nombre de la conducción en la que desea colocar el mensaje.

Si utiliza un conducto explícito, este es el nombre que especificó al llamar a CREATE_PIPE.

**Precaución:** No utilice nombres de conductos que empiecen por 'ORA$'. Estos nombres están reservados para los procedimientos proporcionados por Oracle. El nombre de pipeline no debe tener más de 128 bytes y no es sensible a mayúsculas/minúsculas. En este momento, el nombre no puede contener caracteres de soporte de globalización.

timeout

Tiempo de espera al intentar colocar un mensaje en un conducto, en segundos.

El valor por defecto es la constante MAXWAIT, que se define como 86400000 (1000 días).

Valores devueltos

Tabla - Valores de retorno de función SEND_MESSAGE

Return Descripción
0

Correcto.

Si el conducto ya existe y el usuario que intenta crearlo está autorizado a utilizarlo, Oracle devuelve 0, lo que indica que se ha realizado correctamente, y cualquier dato que ya esté en el conducto permanece.

Si un usuario conectado como SYSDBS/SYSOPER vuelve a crear un canal, Oracle devuelve el estado 0, pero la propiedad del canal no cambia.

1

Timeout.

Este procedimiento puede agotar el tiempo de espera porque no puede obtener un bloqueo en el conducto o porque el conducto permanece demasiado lleno para ser utilizado. Si la tubería se creó implícitamente y está vacía, se elimina.
3

Se produjo una interrupción.

Si el conducto se creó implícitamente y está vacío, se elimina.
ORA-23322

No dispone de privilegios suficientes.

Si existe un conducto con el mismo nombre y lo ha creado un usuario diferente, Oracle indica el error ORA-23322, que indica el conflicto de nomenclatura.

Notas de uso

Excepciones

Tabla - Excepción de función SEND_MESSAGE

Excepción Descripción
Null pipe name Error de permiso. Privilegio insuficiente para escribir en el conducto. La tubería es privada y propiedad de otra persona.

Procedimiento SET_CREDENTIAL_NAME

Este procedimiento define la variable credential_name que se utiliza como credencial por defecto cuando los mensajes de canal se almacenan en el almacén de objetos en la nube.

Sintaxis

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

Parámetros

parámetro Descripción
credential_name Nombre de la credencial para acceder a Cloud Object Storage.

Notas de uso

Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

Ejemplo

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

Procedimiento SET_LOCATION_URI

Este procedimiento define la variable global location_uri.

Sintaxis

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

parámetro

parámetro Descripción
location_uri URI de archivo o de objeto. El formato del URI depende del servicio de Cloud Object Storage que utilice. Para obtener más información, consulte Formatos de URI de almacenamiento de objetos en la nube.

Notas de uso

Si utiliza Oracle Cloud Infrastructure Object Storage para almacenar mensajes, puede utilizar los URI nativos de Oracle Cloud Infrastructure o los URI de Swift. Sin embargo, el URI de ubicación y la credencial deben coincidir en el tipo de la siguiente manera:

Ejemplo

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

Contenido relacionado