Nodo Filter

Este tema contiene las siguientes secciones:

Finalidad

Utilice el nodo Filter para direccionar un mensaje en función de su contenido. Defina la ruta codificando una expresión de filtro en ESQL. Puede incluir elementos del mensaje de entrada o de las propiedades del mensaje en la expresión de filtro. También puede utilizar datos mantenidos en una base de datos externa completar la expresión. El terminal de salida al que se direcciona el mensaje depende de si la expresión tiene el valor verdadero, falso o desconocido.

Conecte los terminales que abarquen todas las situaciones que deberían resultar del filtro; si el nodo propaga el mensaje a un terminal que no está conectado, el mensaje se descarta aún cuando sea transaccional.

Este nodo acepta sentencias ESQL de la misma forma que los nodos Compute y Database. La última sentencia ejecutada debe ser una sentencia RETURN <expresión> cuya expresión sea igual a un valor booleano. Este valor booleano determina a qué terminal se direcciona el mensaje. En muchos casos, el algoritmo de direccionamiento es una simple comparación de los valores de campos de mensajes. La comparación la describe la expresión y la única sentencia es la sentencia RETURN. Si codifica RETURN sin una expresión (RETURN;) o con una expresión NULL, el nodo propaga el mensaje a un terminal desconocido.

Si el flujo de mensajes requiere opciones de direccionamiento más complejas, puede utilizar los nodos RouteToLabel y Label.

El nodo Filter se representa en el área de trabajo por el icono siguiente:

Icono de nodo Filter

Utilización de este nodo en un flujo de mensajes

Consulte los ejemplos siguientes para ver ejemplos de cómo puede utilizar este nodo:

Suponga que se ha llevado a cabo un examen en línea con 10 preguntas tipo test. Cada mensaje que entra tiene un nombre y una dirección de candidato seguido de una serie de respuestas. Se comprueba cada respuesta y, si es correcta, se incrementa en 1 el campo SCORE. Después de comprobar todas las respuestas, se comprueba el campo SCORE para ver si es mayor que 5. Si lo es, el nodo Filter propaga el mensaje al flujo que maneja la entrada de candidato satisfactoria; de lo contrario, el mensaje se filtra en el proceso de rechazo y se crea un mensaje de rechazo.

Configuración del nodo Filter

Después de transferir una instancia del nodo Filter a un flujo de mensajes, puede configurarla. Pulse el botón derecho del ratón en el nodo en la vista de editor y pulse Propiedades. Se visualizan las propiedades básicas de nodo.

Todas las propiedades obligatorias para las que se debe entrar un valor (las que no tienen definido un valor por omisión) se marcan con un asterisco en el diálogo de propiedades.

Configure el nodo Filter como se describe a continuación:

  1. Especifique en Origen de datos el nombre por el que se conoce la base de datos adecuada en el sistema en el que se va a ejecutar este flujo de mensajes. El intermediario se conecta a esta base de datos con la información de ID de usuario y contraseña que se ha especificado en el mandato mqsicreatebroker, mqsichangebroker o mqsisetdbparms.

    En sistemas z/OS, el intermediario utiliza el ID de tarea iniciada por el intermediario.

  2. En Expresión de filtro, identifique el módulo dentro de un archivo ESQL que contiene las sentencias ESQL que el nodo ejecuta. Si desea que el nombre de nodo incluya uno o más espacios, indíquelo entre comillas en la propiedad Expresión de filtro.

    Codifique las sentencias ESQL para personalizar el funcionamiento del nodo Filter en un archivo ESQL asociado con el flujo de mensajes en el que se ha incluido esta instancia del nodo Filter. El archivo ESQL, que por omisión se denomina <nombre_flujo_mensajes>.esql, contiene ESQL para cada nodo en el flujo de mensajes que lo requiere. Cada porción de código relacionada con un nodo específico se denomina módulo.

    Si todavía no existe un archivo ESQL para este flujo de mensajes, pulse el botón derecho del ratón en el nodo Filter y pulse Abrir ESQL. Esto crea y abre un nuevo archivo ESQL en la vista del editor ESQL.

    Si el archivo ya existe, pulse el botón Examinar junto la propiedad Expresión de filtro. Aparece el diálogo Selección de módulo, que mostrará los módulos disponibles del nodo Filter definidos en los archivos ESQL a los que puede acceder este flujo de mensajes (los archivos ESQL pueden definirse en otros proyectos dependientes). Seleccione el módulo adecuado y pulse Aceptar. Si no hay disponible ningún módulo adecuado, la lista está vacía.

    Si el módulo que se especifica no existe, dicho módulo se crea automáticamente y el editor coloca el archivo para que lo muestre. Si el archivo y el módulo ya existen, el editor coloca el archivo además de mostrar y resaltar el módulo correcto.

    Si lo prefiere, puede abrir el archivo ESQL adecuado en el navegador de recursos y seleccionar este nodo en la vista de esquema.

    Si se crea u esqueleto del módulo para este nodo en un nuevo archivo ESQL o en uno existente, éste está compuesto del siguiente WSQL. El nombre de módulo por omisión se muestra en este ejemplo:


    CREATE FILTER MODULE <nombre_flujo>_Filter
           CREATE FUNCTION Main() RETURNS BOOLEAN
           BEGIN
                   RETURN TRUE;
           END;
    END MODULE;

    Si crea su propio módulo ESQL, debe crear exactamente este esqueleto. Puede actualizar el nombre por omisión, aunque debe asegurarse de que el nombre que se especifica coincida con el nombre de la propiedad de nodo correspondiente Expresión de filtro.

    Añada su propio código ESQL para personalizar este nodo después de la sentencia BEGIN y antes de la sentencia RETURN. Si la expresión de la sentencia RETURN no es TRUE o FALSE, su valor se resuelve para determinar el terminal al que se propaga el mensaje. Si la expresión resuelve en NULL o se codifica RETURN;, o se omite la sentencia RETURN, el nodo propaga el mensaje al terminal desconocido.

    También puede pulsar Archivo > Nuevo > Archivo ESQL de flujo de mensajes para crear un archivo ESQL.

    En este módulo puede utilizar todas las sentencias ESQL, incluidas SET, WHILE, DECLARE e IF, pero (a diferencia del nodo Compute) el nodo Filter propaga el mensaje que recibe en su terminal de entrada a su terminal de salida sin modificar. Esto significa que, al igual que el nodo Database, sólo hay un mensaje al que hacer referencia en un nodo Filter.

    Puesto que no puede modificar ninguna parte de ningún mensaje, la sentencia de asignación (la sentencia SET, no la cláusula SET de la sentencia SET) sólo puede asignar valores a variables temporales. El ámbito de acciones que se pueden realizar con una sentencia de asignación es por lo tanto limitado.

  3. Seleccione el valor Transacción en el menú desplegable. Los valores son:
    • Automático (el valor por omisión). El flujo de mensajes, del que forma parte el nodo Filter, se confirma si es satisfactorio. Es decir, se llevan a cabo las acciones definidas en el módulo ESQL y el mensaje continúa a través del flujo de mensajes. Si el flujo de mensajes no se ejecuta correctamente, se restituye. Por lo tanto, si selecciona Automático significa que la capacidad para confirmar o restituir la acción del nodo Filter en la base de datos depende de si todo el flujo de mensajes ha sido correcto o ha generado un error.
    • Confirmar. Si desea confirmar todas las acciones no confirmadas ejecutadas en este flujo de mensajes en la base de datos conectada a este nodo, sin tener en cuenta si el flujo de mensajes en conjunto se ejecutó o no satisfactoriamente, seleccione Confirmar. Los cambios realizados en la base de datos se confirman incluso si el flujo de mensajes falla.
  4. Seleccione Básico en el navegador del diálogo de propiedades y establezca o desmarque los dos recuadros de selección:
    • Si desea que los mensajes de aviso de base de datos se procesen como errores y que el nodo propague el mensaje de salida hasta el terminal de anomalías, seleccione el recuadro Tratar los avisos como errores. Al principio el recuadro está sin seleccionar.

      Al seleccionar el recuadro, el nodo trata como errores todos los códigos de retorno positivos procedentes de la base de datos base y genera excepciones de la misma forma que lo hace para los errores negativos o más graves.

      Si no selecciona este recuadro, el nodo procesa los avisos como si fueran códigos de retornos normales y no genera ninguna excepción. El aviso más significativo generado es no encontrado, que puede manejarse como un código de retorno normal de forma segura en la mayoría de las circunstancias.

    • Si desea que el intermediario genere una excepción cuando se detecte un error en la base de datos, seleccione el recuadro Generar excepción cuando se produce un error en la base de datos. Al principio el recuadro está seleccionado.

      Si deselecciona el recuadro, debe incluir ESQL para comprobar si hay algún error en la base de datos que pueda devolverse después de realizar la llamada de la base de datos (puede utilizar SQLCODE y SQLSTATE para hacerlo). Si se ha producido un error, deberá manejar el error en el flujo de mensajes para garantizar la integridad del intermediario y de la base de datos: el error se ignora si no lo maneja a través de su propio proceso, porque ha elegido no invocar el manejo de errores por omisión que realiza el intermediario. Por ejemplo, puede incluir la sentencia ESQL THROW para generar una excepción en este nodo, o puede utilizar el nodo Throw para generar una excepción propia más adelante.

  5. Seleccione Descripción en el navegador del diálogo de propiedades para entrar una descripción breve, una descripción larga o ambas.
  6. Pulse Aplicar para realizar los cambios en el nodo Filter sin cerrar el diálogo de propiedades. Pulse Aceptar para aplicar los cambios y cerrar el diálogo de propiedades.

    Pulse Cancelar para cerrar el diálogo y descartar todos los cambios realizados en las propiedades.

Terminales y propiedades

Los terminales de nodo Filter se describen en la tabla siguiente.

Terminal Descripción
Terminal de entrada Terminal de entrada que acepta un mensaje para que el nodo lo procese.
Terminal de anomalías Terminal de salida al que se direcciona el mensaje si se detecta una anomalía durante un cálculo.
Desconocido El terminal de salida al que se direcciona el terminal de salida si la expresión de filtro especificada es igual a desconocido o nulo.
Falso Terminal de salida al que se direcciona el mensaje si la expresión de filtro especificada es igual a false.
Verdadero Terminal de salida al que se direcciona el mensaje si la expresión de filtro especificaba es igual a true.

En las siguientes tablas se describen las propiedades del nodo; la columna con la cabecera O indica si la propiedad es obligatoria (marcada con un asterisco en el diálogo de propiedades si se debe entrar un valor cuando no se ha definido ningún valor por omisión), la columna con la cabecera C indica si la propiedad es configurable (se puede cambiar el valor cuando se añade el flujo de mensajes al archivo bar para difundirlo).

Las propiedades básicas del nodo Filter se describen en la siguiente tabla.

Propiedad O C Valor por omisión Descripción
Origen de datos No   Nombre de origen de datos ODBC de la base de datos en la que residen las tablas a las que se hacen referencia en el ESQL asociado a este nodo (que se identifica por la propiedad Expresión de filtro.
Transacción No Automático Modalidad de transacción para el nodo. Puede ser Automático o Confirmar.
Expresión de filtro No Filtro Nombre del módulo dentro del recurso ESQL (archivo) que contiene las sentencias que deben ejecutarse contra el mensaje que se recibe en el nodo.
Tratar los avisos como errores No Sin seleccionar Trata los avisos SQL como errores. Si selecciona el recuadro, se lleva a cabo la acción.
Generar excepción cuando se produce un error en la base de datos No Seleccionada Los errores de base de datos pueden provocar que el intermediario genere una excepción. Si selecciona el recuadro, se lleva a cabo la acción.

Las propiedades de descripción del nodo Filter se describen en la siguiente tabla.

Propiedad O C Valor por omisión Descripción
Descripción corta No No   Breve descripción del nodo.
Descripción larga No No   Texto que describe la utilidad del nodo en el flujo de mensajes.

Conceptos relacionados
Flujos de mensajes
Flujos de mensajes, correlaciones y ESQL

Tareas relacionadas
Configuración de DB2
Cómo decidir los nodos que utilizar
Configuración de flujos de mensajes coordinados
Manejo de errores en flujos de mensajes
Configuración de ESQL dentro de nodos
Edición de propiedades configurables

Referencia relacionada
Mandato mqsichangebroker
Mandato mqsicreatebroker
Mandato mqsisetdbparms
Nodo Compute
Nodo Database
Nodo Label
Nodo RouteToLabel
Sentencia RETURN