Configurando Saída de API

Uma saída de API é um módulo de código, um arquivo .dll, que você mesmo fornece e que é executado imediatamente antes ou após chamadas de MQI.

Sobre Esta Tarefa

Quando o IBM® MQ recebe uma chamada de um programa para um dos pontos de entrada da API, o IBM MQ chama sua saída de API. A saída de API é executada antes ou após a execução do MQI, de acordo com a maneira em que a saída foi configurada.

Você pode configurar nenhuma, uma ou muitas saídas para serem chamadas e pode configurar a seqüência em que várias saídas são chamadas. No Windows e no Linux® (plataformas x86 e x86-64), é possível configurar as saídas de API usando IBM MQ Explorer. Os detalhes de configuração são armazenados em arquivos .ini.

  1. Configure uma saída de API no IBM MQ Explorer.
  2. Substituir uma saída de API comum por uma saída de API local.
Há três tipos de definição de saída de API:
Comum (ApiExitCommon)
Um conjunto de definições por computador. Quando o gerenciador de filas inicia, as saídas de API que estiverem definidas, se houver, são lidas e aplicadas ao gerenciador de filas. Configure saídas de API comuns no diálogo de propriedades IBM MQ. Saídas comuns são exibidas na tabela Saídas de API Locais no diálogo de propriedades de cada gerenciador de filas locais.
Gabarito (ApiExitTemplate)
Um conjunto de definições por computador. Quando um gerenciador de filas é criado, as saídas de API definidas aqui, se houver, são copiadas no gerenciador de filas recém-criado como saídas locais. Configure saídas de API de modelo no diálogo de propriedades IBM MQ.
Local (ApiExitLocal)
Um conjunto de definições por gerenciador de filas. Quando o gerenciador de filas é iniciado, as saídas de API que estiverem definidas, se houver, substituirão as saídas comuns caso seus atributos de Nome sejam os mesmos e se a substituição foi especificada. Quando uma saída de API comum é substituída, nenhum dos campos na definição comum é salvo, mesmo se o atributo opcional Dados tiver um valor designado. Configure saídas de API locais no diálogo de propriedades do gerenciador de filas.
Ao configurar saídas de API nos diálogos de propriedades do IBM MQ e do gerenciador de filas, os valores de atributo são incluídos nas sub-rotinas ApiExitCommon, ApiExitTemplate e ApiExitLocal nos arquivos de configuração ou no registro do Windows.
Tabela 1. Atributos de Saída de API
Atributo Significado Chave da sub-rotina
Nome Especifica o nome descritivo da saída de API que é transmitido para a saída de API no campo ExitInfoName da estrutura MQAXP. Esse nome deve ser exclusivo e está limitado a um comprimento de 48 caracteres, devendo conter apenas os caracteres válidos para o nome de objetos do IBM MQ, como por exemplo, nomes de filas. Nome
Tipo Especifica o tipo de saída: comum, gabarito, local ou substituição. (Não uma chave de sub-rotina separada.)
Seqüência Este atributo é um valor numérico sem sinal que define a seqüência na qual essa saída de API é chamada em comparação com outras saídas de API. Uma saída de API com um número de seqüência baixo é chamada antes de outra saída de API com um número de seqüência mais alto. A ordem na qual são chamadas as saídas de API diferentes com o mesmo número de seqüência é indefinida. É perfeitamente válido que haja intervalos nos números de seqüência das saídas de API definidas para um gerenciador de filas. Seqüência
Módulo Especifica o módulo que contém o código para a saída de API. Se esse campo contiver o nome de caminho completo do módulo, ele será utilizado dessa forma. Se esse campo contiver apenas o nome do módulo, este será localizado utilizando o mesmo método que as saídas de canal, ou seja, utilizando o valor no campo Caminho de saída padrão na página Saídas do diálogo de propriedades do gerenciador de filas. Módulo
Função Especifica o nome do ponto de entrada da função no módulo que contém o código para a saída de API. O ponto de entrada é a função MQ_INIT_EXIT. O comprimento deste campo está limitado a MQ_EXIT_NAME_LENGTH. Função
Dados Se esse atributo for especificado, os espaços em branco iniciais e finais serão removidos, o restante da cadeia será truncado em 32 caracteres e o resultado será transmitido para a saída no campo ExitData da estrutura MQAXP. Se este atributo não for especificado, o valor padrão de 32 espaços em branco será passado para a saída no campo ExitData da estrutura MQAXP. Dados

Procedimento

  • [OPÇÃO 1] Configurar uma saída de API no IBM MQ Explorer.
    1. Abra o diálogo de propriedades relevante:
    2. Na página Saídas, clique em Incluir.... O diálogo Incluir Saída de API é aberto.
    3. Digite as informações necessárias nos campos do diálogo Incluir Saída de API.
    4. Clique em OK para criar a saída e fechar o diálogo Incluir Saída de API.
    As propriedades da nova saída de API são exibidas na tabela na página Saídas.
  • [OPÇÃO 2] Substituir uma saída de API comum por uma saída de API local.

    Quando uma saída de API local é definida em um gerenciador de filas com o mesmo nome que uma saída comum, a saída comum é substituída. Isto é, a saída comum não é chamada; em vez disso, a saída local de substituição é chamada. Para impedir a substituição acidental, a interface com o usuário faz com que você execute ações deliberadas para configurar uma substituição; por exemplo, não é possível incluir uma nova saída com o mesmo nome de uma saída existente nem alterar o nome de uma saída para que seja o mesmo nome de uma saída existente. Entretanto, talvez você queira incluir uma saída de API local em um gerenciador de filas para que, em vez de utilizar a saída de API comum, seja utilizada a saída de API local. Nesse caso, é necessário substituir a saída de API comum pela local.

    1. Abra a página Saídas do diálogo de propriedades do gerenciador de filas.
    2. Clique na saída comum que deseja substituir na tabela Saídas de API Locais.
    3. Clique em Substituir.
      O diálogo Editar Saída de API é aberto com o nome da saída de API comum exibida.
    4. No diálogo Editar Saída de API, digite os detalhes da saída de API local e clique em OK para salvar as mudanças.
    Agora, a saída local substitui a saída comum que tem o mesmo nome.