Creating eaapi.ini for the TMTM Extensible Agent and extensions

The BTM and Performance and Availability extensible extensions use an API for communicating with the extensible agent (qpea). Sometimes the default communication parameters might need to be altered to work in an environment. This is accomplished via an EAAPI initialization file.

On most platforms, this file is named eaapi.ini. On Tandem, the file name is EAAPINI. On z/OS, the DD name is EAAPIINI. The remainder of this section refers to eaapi.ini but the name required for that platform should be used.

There are two implementations of the Extensible Agent API; one using a Java Runtime Environment (JRE) and one using an executable or library compiled to run natively on the platform.

On platforms excluding z/OS, native extensions can define an eaapi.ini file in the directory where the extension executable resides. However, it can also be placed in the directory specified by MQS_HOME so all native extensions share that common eaapi.ini. If only one agent exists, it is recommended eaapi.ini is created in the MQS_HOME directory. Otherwise you must create eaapi.ini for each extension and set the values to connect to the appropriate agent.

All Java extensions are stand-alone and an eaapi.ini file should be defined for each extension in its own directory structure, as each extension usually already has one defined with values specific for that extension. Note that if an eaapi.ini is not defined for a Java extension, the MQS_HOME eaapi.ini is used if it exists.

On platforms excluding z/OS: If only one agent exists, it can share the eaapi.ini used by the extensions in the directory specified by MQS_HOME and that is recommended. If multiple agents exist, an eaapi.ini should be created in the directory where the agent executable resides. Each eaapi.ini must specify a unique port for the agent to use.

On z/OS platforms: One unique member should exist for use by the native extensions and their agent. Each member should specify a unique port for the agent to use.

The eaapi.ini file can be used to:

Configure extensions to use "localhost" to contact qpea, instead of what it gets back from gethostname.

[networksettings]
uselocalhost=true

Configure the agent to only bind to a specified IP address, and not to all addresses on the system it is running on.

[networksettings]
sock_bind_address=nnn.nnn.nnn.nnn

Configure QPEA to listen on a port other than 2612

[networksettings]
agent_listen_port=XXXX

Make BTM extensions connect to a specific agent based on the queue manager the application uses (see below).

BTM

The eaapi.ini file must reside in the directory specified by the MQS_HOME environment variable. In order to allow the BTM exit of two queue managers to use two different agents when using the same user id, eaapi.ini can contain stanza names optionally suffixed with the similar string as used for QPLog.ini and specified when calling log_init_from_ini. The base stanza would apply to all extensions and agents unless overridden by a more restrictive stanza. Note, unlike the QPLog.ini stanza, only one qualification is allowed in eaapi.ini.

[networksettings_btm]

This would apply to all BTM extensions unless overridden by a more restrictive stanza.

[networksettings_btm_myQM]

The settings are different for the agent than for the extension and therefore you need to place eaapi.ini for the agent in its installation directory. That is also true of any java extension; eaapi.ini should reside in its working directory. All the WebSphere MQ BTM extensions should use eaapi.ini from the MQS_HOME directory and if necessary, separate settings by suffixing the stanza name.

z/OS

The member on z/OS uses parenthesis () instead of brackets [] for stanza names.

1. Add a new <YOURHLQ.INSTALL.CNTL> library member with contents:
   
   (networksettings)
agent_listen_port=XXXX
2. Add an EAAPIINI DD statement that points to what you created in step 1 member to the started task JCL for QPEA, QPCFG, QPMON, and QPBTM.
   
   //EAAPIINI DD DISP=SHR,DSN=<YOURHLQ.INSTALL.CNTL>...CNTL(EAAPIINI)
3. Restart the QPEA, QPCFG, QPMON and QPBTM tasks for the agent and extensions to use the information in the new EAAPIINI member.