Configuring API exits

You define your API exits in new stanzas in the mqs.ini and qm.ini files (or in the Windows registry). The following sections describe these stanzas, and the attributes within them that define the exit routines and the sequence in which they run. For guidance on how to change these stanzas, see Changing the configuration information.

Stanzas in mqs.ini are:

ApiExitCommon: When any queue manager starts, the attributes in this stanza are read. However, any exit routine identified may be overridden by one of the same name in ApiExitLocal for this queue manager.
ApiExitTemplate: When any queue manager is created, the attributes in this stanza are copied into the newly created qm.ini file under the ApiExitLocal stanza.

The stanza in qm.ini is:

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

Attributes for all stanzas

All API exit stanzas share the following attributes:

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 WebSphere MQ objects (for example, queue names). See Rules for naming WebSphere MQ objects.

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_OBJECT_NAME_LENGTH.

Module=module_name

The module containing the API exit code.

If this field contains the full pathname 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)

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

Data=data_name

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

If you 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 you omit this attribute, the default value of 32 blanks is passed to the exit.

The maximum length of this field is 32 characters.

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. You 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

The mqs.ini file below contains the following 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 TivoliMQIPoliceman, module name tmqp, and sequence number 1. The data passed is an instruction (CheckEverything).

mqs.ini
 
   ApiExitTemplate:
      Name=OurPayrollQueueAuditor
      Sequence=2
      Function=EntryPoint
      Module=/opt/ABC/auditor
      Data=123
   ApiExitCommon:
      Name=TivoliMQIPoliceman
      Sequence=1
      Function=EntryPoint
      Module=/opt/TMQPolice/tmqp
      Data=CheckEverything

The qm.ini file below contains an ApiExitLocal definition of an exit with the descriptive name ClientApplicationAPIchecker, module name ClientAppChecker, and sequence number 3.

qm.ini
 
   ApiExitLocal:
      Name=ClientApplicationAPIchecker
      Sequence=3
      Function=EntryPoint
      Module=/opt/Dev/ClientAppChecker
      Data=9.20.176.20

Changing the configuration information

The WebSphere MQ configuration file, mqs.ini, contains information relevant to all the queue managers on a particular node. You can find it in the /var/mqm directory. On Windows systems, this information is stored in the registry.

A queue manager configuration file, qm.ini, 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:

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

On Windows systems, this information is stored in the registry.

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

You can edit configuration files either:

Automatically, using commands that change the configuration of queue managers on the node
Manually, using a standard text editor

On Windows systems, you can use the command amqmdain reg or use the WebSphere MQ Services configuration interface to make relevant changes to the registry. Go to the Exits tab of the Properties notebook for a queue manager to start the procedure. For details of the amqmdain command, see the WebSphere MQ System Administration Guide book.

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.)

OS/400 considerations

Once created as a service program, an exit must be referenced in the appropriate stanza in an ini file using LIBRARY/PROGRAM syntax, as in the following example:

ApiExitLocal:
 Name=Sample
 Sequence=1
 Function=EntryPoint
 Module=MYLIB/MYSRVPGM
 Data=123

On OS/400, the ini files are stored in the IFS, as follows:

/QIBM/UserData/mqm/mqs.ini
/QIBM/UserData/mqm/qmgrs/<queue-manager-name>/qm.ini

Each queue manager has its own qm.ini file in its own subdirectory.

You can use the EDTF CL command to edit these files.