Configure API exits

You configure IBM MQ to enable API exits by changing the configuration information.

• Use the IBM MQ Explorer on Windows and Linux (x86 and x86-64 platforms).
• Use the amqmdain command on Windows.
• Use the mqs.ini and qm.ini files directly on Windows, IBM i, and UNIX and Linux systems. The mqs.ini file contains information relevant to all the queue managers on a particular node. We can find it in the following locations:
  • In the /QIBM/UserData/mqm directory on IBM i.
  • In the /var/mqm directory on UNIX and Linux.
  • In the WorkPath specified in the HKLM\SOFTWARE\IBM\WebSphere MQ key on Windows systems.

  The qm.ini file contains information relevant to a specific queue manager. There is one queue manager configuration file for each queue manager, held in the root of the directory tree occupied by the queue manager. For example, the path and the name for a configuration file for a queue manager called QMNAME is:

  On IBM i systems:

  /QIBM/UserData/mqm/qmgrs/QMNAME/qm.ini
  

  On UNIX and Linux systems:

  /var/mqm/qmgrs/QMNAME/qm.ini
  

  On Windows systems:

  C:\ProgramData\IBM\MQ\qmgrs\QMNAME\qm.ini
  

  Before editing a configuration file, back it up so that we have a copy we can revert to if the need arises.

  We can edit configuration files in either of the following ways:
  • Automatically, using commands that change the configuration of queue managers on the node.
  • Manually, using a standard text editor.

  If you set an incorrect value on a configuration file attribute, the value is ignored and an operator message is issued to indicate the problem. The effect is the same as missing out the attribute entirely.

Stanzas to configure

ApiExitCommon

Defined in mqs.ini and in the IBM MQ Explorer on the IBM MQ properties page, under Exits.

When any queue manager starts, the attributes in this stanza are read, and then overridden by the API exits defined in qm.ini.

ApiExitTemplate

Defined in mqs.ini and in the IBM MQ Explorer on the IBM MQ properties page, under Exits.

When any queue manager is created, the attributes in this stanza are copied into the newly created qm.ini file under the ApiExitLocal stanza.

ApiExitLocal

Defined in qm.ini and in the IBM MQ Explorer on the queue manager properties page, under Exits.

When the queue manager starts, API exits defined here override the defaults defined in mqs.ini.

Attributes for the stanzas

• Name the API exit using the following attribute:

  Name=ApiExit_name

  The descriptive name of the API exit passed to it in the ExitInfoName field of the MQAXP structure.

  This name must be unique, no longer than 48 characters, and contain only valid characters for the names of IBM MQ objects (for example, queue names).

• Identify the module and entry point of the API exit code to run using the following attributes:

  Function=function_name

  The name of the function entry point into the module containing the API exit code. This entry point is the MQ_INIT_EXIT function.

  The length of this field is limited to MQ_EXIT_NAME_LENGTH.

  Module=module_name

  The module containing the API exit code.

  If this field contains the full path name of the module it is used as is.

  If this field contains just the module name, the module is located using the ExitsDefaultPath attribute in the ExitPath in qm.ini.

  On platforms that support separate threaded libraries, we must provide both a non-threaded and a threaded version of the API exit module. The threaded version must have an _r suffix. The threaded version of the IBM MQ application stub implicitly appends _r to the given module name before it is loaded.

  The length of this field is limited to the maximum path length the platform supports.

• Optionally pass data with the exit using the following attribute:

  Data=data_name

  Data to be passed to the API exit in the ExitData field of the MQAXP structure.

  If we include this attribute, leading and trailing blanks are removed, the remaining string is truncated to 32 characters, and the result is passed to the exit. If we omit this attribute, the default value of 32 blanks is passed to the exit.

  The maximum length of this field is 32 characters.

• Identify the sequence of this exit in relation to other exits using the following attribute:

  Sequence=sequence_number

  The sequence in which this API exit is called relative to other API exits. An exit with a low sequence number is called before an exit with a higher sequence number. There is no need for the sequence numbering of exits to be contiguous. A sequence of 1, 2, 3 has the same result as a sequence of 7, 42, 1096. If two exits have the same sequence number, the queue manager decides which one to call first. We can tell which was called after the event by putting the time or a marker in ExitChainArea indicated by the ExitChainAreaPtr in MQAXP or by writing your own log file.

  This attribute is an unsigned numeric value.

Sample stanzas

ApiExitTemplate

This stanza defines an exit with the descriptive name OurPayrollQueueAuditor, module name auditor, and sequence number 2. A data value of 123 is passed to the exit.

ApiExitCommon

This stanza defines an exit with the descriptive name MQPoliceman, module name tmqp, and sequence number 1. The data passed is an instruction ( CheckEverything).

mqs.ini

   ApiExitTemplate:
      Name=OurPayrollQueueAuditor
      Sequence=2
      Function=EntryPoint
      Module=/usr/ABC/auditor
      Data=123
   ApiExitCommon:
      Name=MQPoliceman
      Sequence=1
      Function=EntryPoint
      Module=/usr/MQPolice/tmqp
      Data=CheckEverything

qm.ini

   ApiExitLocal:
      Name=ClientApplicationAPIchecker
      Sequence=3
      Function=EntryPoint
      Module=/usr/Dev/ClientAppChecker
      Data=9.20.176.20