Configurar salidas de API

Una salida de API es un módulo de código, un archivo .dll, que proporciona el usuario y se ejecuta inmediatamente antes o después de las llamadas MQI.

Acerca de esta tarea

Cuando IBM® MQ recibe una llamada de un programa a uno de los puntos de entrada de API, IBM MQ llama a la salida de API. La salida de API se ejecuta antes o después de ejecutar la MQI, dependiendo de cómo se haya configurado la salida.

Puede configurar que se llame a varias, a una o a ninguna salida y puede configurar la secuencia en que se llama a múltiples salidas. En Windows y Linux® (plataformas x86 y x86-64), puede configurar las salidas de API utilizando IBM MQ Explorer. Los detalles de configuración se almacenan en archivos .ini.

  1. Configurar una salida de API en IBM MQ Explorer.
  2. Alterar temporalmente una salida de API común con una salida de API local.
Existen tres tipos de definiciones de rutinas de salida de API:
Común (ApiExitCommon)
Un conjunto de definiciones por sistema. Cuando se inicia el gestor de colas, las salidas de API que se han definido, si las hay, se leen y se aplican al gestor de colas. Configure salidas de API comunes en el diálogo de propiedades de IBM MQ. Las salidas comunes se muestran en la tabla Salidas de API locales del diálogo de propiedades de cada gestor de colas local.
Plantilla (ApiExitTemplate)
Un conjunto de definiciones por sistema. Cuando se crea un gestor de colas, las salidas de API definidas, si las hay, se copian en el gestor de colas que se acaba de crear como salidas locales. Configure salidas de API de plantilla en el diálogo de propiedades de IBM MQ.
Local (ApiExitLocal)
Un conjunto de definiciones por gestor de colas. Cuando el gestor de colas se inicia, las salidas de API definidas alteran temporalmente las salidas si los atributos Nombre son los mismos y si se ha especificado la alteración temporal. Cuando se altera temporalmente una salida de API común, ninguno de los campos de la definición común se guarda, incluso si el atributo opcional Datos tiene un valor asignado. Configure salidas de API locales en el diálogo de propiedades del gestor de colas.
Cuando configure salidas de API en IBM MQ y en los diálogos de las propiedades del gestor de colas, se añadirán los valores de atributo a las secciones ApiExitCommon, ApiExitTemplate y ApiExitLocal en los archivos de configuración o el registro Windows.
Tabla 1. Atributos de salida de API
Atributo Significado Clave de stanza
Nombre Especifica el nombre descriptivo de la salida de API que se pasará a la salida de API en el campo ExitInfoName de la estructura MQAXP. Este nombre ha de ser único, está limitado a una longitud de 48 caracteres y sólo debe contener caracteres válidos para el nombre de los objetos IBM MQ, como los nombres de cola. Nombre
Tipo Especifica el tipo de salida común, plantilla, local o alteración temporal. (No una clave de stanza separada.)
Secuencia Este atributo es un valor numérico sin signo que define la secuencia con la que se llamará a esta salida de API en comparación con otras salidas de API. Una salida de API con un número de secuencia bajo se llamará antes que una salida de API con un número de secuencia superior. El orden en que se llama a las diferentes salidas de API con el mismo número de secuencia es indefinido. Es absolutamente correcto que haya lagunas en los números de secuencia de las salidas de API definidas para un gestor de colas. Secuencia
Módulo Especifica el módulo que contiene el código para la salida de API. Si este campo contiene la vía de acceso completa del módulo, se utiliza tal cual. Si este campo contiene únicamente el nombre del módulo, dicho módulo se localiza utilizando el mismo método que las salidas de canal; es decir, utilizando el valor en el campo Vía de acceso predeterminada de las salidas en la página Salidas del diálogo de propiedades del gestor de colas. Módulo
Función Especifica el nombre del punto de entrada de la función en el módulo que contiene el código para la salida de API. Este punto de entrada es la función MQ_INIT_EXIT. La longitud de este campo está limitada a MQ_EXIT_NAME_LENGTH. Función
Datos Si se especifica este atributo, los blancos de cabecera y de cola se eliminan, el resto de la serie de caracteres se trunca a 32 caracteres y el resultado se pasa a la salida del campo ExitData de la estructura MQAXP. Si este atributo no se especifica, se pasa el valor predeterminado de 32 blancos a la salida en el campo ExitData de la estructura MQAXP. Datos

Procedimiento

  • [OPCIÓN 1] Configurar una salida de API en IBM MQ Explorer.
    1. Abra el diálogo de propiedades pertinente:
    2. En la páginas Salidas, pulse Añadir.... Se abrirá el diálogo Añadir salida de API.
    3. Escriba la información necesaria en los campos del diálogo Añadir salida de API.
    4. Pulse Aceptar para crear la salida y cierre el diálogo Añadir salida de API.
    Las propiedades de la nueva salida de API pueden verse en la tabla de la página Salidas.
  • [OPCIÓN 2] Alterar temporalmente una salida de API común con una salida de API local.

    Cuando se define una salida de API local en un gestor de colas con el mismo nombre que una salida común, la salida común se altera temporalmente, Es decir, no se llama a la salida común; en su lugar se llama a la salida local que la ha alterado temporalmente. Para evitar una alteración temporal accidental, la interfaz de usuario le hará llevar a cabo acciones deliberadas para configurar una alteración temporal; por ejemplo, no podrá añadir una nueva salida con el mismo nombre que una salida ya existente ni podrá cambiar el nombre de una salida para que sea igual que el de otra ya existente.No obstante, es posible que desee añadir una salida de API local a un gestor de colas, de forma que no se utilice la salida de API común y se utilice en su lugar la salida de API local. En ese caso, necesita alterar temporalmente la salida de API común con la salida de API local.

    1. Abra la página Salidas del diálogo de propiedades del gestor de colas.
    2. Pulse en la salida común que desea alterar temporalmente en la tabla Salidas de API locales.
    3. Pulse Alterar temporalmente.
      Se abre el diálogo Editar salida de API con el nombre de la salida de API común visualizado.
    4. Escriba los detalles de la salida de API local en el diálogo Editar salida de API y pulse Aceptar para guardar los cambios.
    La salida local ahora sustituye temporalmente la salida común que tiene el mismo nombre.