Configure the WebSphere MQ Non-Intrusive Agent

Supported for: Windows

This task describes how to configure the Service Virtualization IBM WebSphere MQ Non-Intrusive Agent, configure your WebSphere MQ Server, and virtualize MQ communication.


The Service Virtualization WebSphere MQ Non-Intrusive agent enables you to virtualize WebSphere MQ communication without the need for any reconfiguration of your applications under test. You need only to deploy several libraries to the MQ server and reconfigure a queue manager. No virtual queues are required.

In Standby and Learning modes, messages come untouched through the MQ server, but Service Virtualization is receiving message copies.

In Simulation mode, messages are processed by Service Virtualization while the real service is still running, but the real service does not receive any communication.

Back to top

Supported WebSphere MQ platforms

  • Solaris 5.10 x86_64, MQ Server v7.0.1.x

  • Solaris 5.10, SPARC V9, MQ

  • Windows 2008 R2 x86_64, MQ Server v7.0.1.x

  • HPE UX 11.31 Intel Itanium IA64, MQ Server v7.0.1.x

  • AIX 5.3, PowerPC Power5, MQ


  • For the most up to date information on supported versions, refer to the support matrix on the Software Support site at:
  • SV MQ API Exits are compiled against specific versions of operating systems and MQ servers. Testing was conducted on the same configurations as those on which they were compiled. Newer versions of the supported operating systems and MQ servers may or may not function properly.

    The mq-version.txt file contains the version of MQ that was used for compilation of the libraries. The file is located in the libraries folder within the Service Virtualization installation folder. For additional details, see Configure the WebSphere MQ server.

Back to top

Configure the Service Virtualization Agent

  1. Prerequisites

    Install the WebSphere MQ client.

    The WebSphere MQ Agent is not installed by default. The agent is dependent on the IBM WebSphere MQ Client or later (amqmdnet.dll library with version and its dependencies). The IBM WebSphere MQ Client full installation places the required library in the Global Assembly Cache (GAC), making the agent available. If you install the client while the Service Virtualization Server or Designer is running, you must restart the application prior to enabling the agent.

    The WebSphere MQ Agent uses the IBM WebSphere MQ Client internally. This enables you to use all diagnostic tools and logs provided by the client if you need to investigate any issues with WebSphere MQ communication between Service Virtualization and the IBM WebSphere MQ Server.

    Use the following links to download the desired WebSphere MQ client:

    MQ Client version Link

    Note: An individual IBM ID is required for the downloads.

  2. Configure the Service Virtualization agent settings

    From the main menu, select Tools > Options. On the Agents Page, select WebSphere MQ Non-Intrusive. For user interface details, see the WebSphere MQ Non-Intrusive Agent Settings.

  3. Optional: Perform additional global configuration

    You can configure additional settings using the Service Virtualization configuration files.

    1. Open the appropriate file:

      • Standalone Server configuration file:


      • Designer configuration file:


    2. You can define the following element in the appSettings section of the configuration files. This configuration element sets up global behavior for processing WebSphere MQ messages.

      • <add key="MQAgent.DefaultCharacterSet" value="0"/>

        Configures the default character set for simulated XML responses. Use this configuration if the character set is not recorded as message metadata. If the value is set to 0 the character set is not set.

Back to top

Agent limitations

  • The WebSphere MQ Non-Intrusive Agent instance can only use queues from a single Queue manager.

  • The WebSphere MQ Non-Intrusive Agent instance can only use a single TCP channel to connect to the Queue manager.

  • CCSID configuration in the WebSphere MQ Non-Intrusive Agent instance requires an application restart.

  • CCSID configuration is global for whole the application. There cannot be two agents with different CCSIDs.

Back to top

Configure the WebSphere MQ server

Note: You must have MQ administration rights to perform this configuration on the MQ server.

  1. Extract the Service Virtualization MQ API Exit libraries.

    After you install Service Virtualization, the libraries are in the following locations:

    Designer C:\Program Files\Micro Focus\Service Virtualization Designer\Tools\WebSphere MQ Extensions\
    Server C:\Program Files\Micro Focus\Service Virtualization Server\Tools\WebSphere MQ Extensions\
  2. Unzip the file and copy the appropriate Micro Focus SV MQ API Exit libraries to the following destination folders on your MQ server.

    • From <extracted root>/<solaris version>/32bit to /var/mqm/exits
    • From <extracted root>/<solaris version>/64bit to /var/mqm/exits64
    • From <extracted root>\<windows version>\32bit to C:\Program Files (x86)\IBM\WebSphere MQ\exits

    • From <extracted root>\<windows version>\64bit to C:\Program Files (x86)\IBM\WebSphere MQ\exits64

    HP UX
    • From <extracted root>/<hpux version>/32bit to /var/mqm/exits

    • From <extracted root>/<hpux version>/bit to /var/mqm/exits64

    • From <extracted root>/<AIX version>/32bit to /var/mqm/exits
    • From <extracted root>/<AIX version>/64bit to /var/mqm/exits64
  3. Enable the TCP/IP port.

    Enable your firewalls to connect from the MQ Server to the Service Virtualization Server on a port that you specify. This port must be the same port you use in the Service Virtualization WebSphere MQ Non-Intrusive Agent settings, in the Non-Intrusive Server Port field, as defined in step 2 above.

    Note: If the Service Virtualization WebSphere MQ Non-Intrusive Agent is not running and Service Virtualization Server is protected by Windows Firewall, you might experience slow performance. This is caused by the fact that the SV MQ API Exit library can not communicate with the Service Virtualization Server. This can be resolved by disabling Stealth Mode in Windows Firewall. For details, refer to Microsoft documentation.

  4. On the MQ Server, update the queue manager configuration.

    Append the following lines to your queue manager configuration file. By default, the file is located on the MQ Server in <WebSphere MQ root>/qmgrs/<your QM>/qm.ini.

    Note: The Data parameter is limited to a maximum of 32 characters.

    Solaris, HP UX, AIX:






    Data=<Service Virtualization hostname or IP>:<Service Virtualization TCP/IP port>







    Data=<Service Virtualization hostname or IP>:<Service Virtualization TCP/IP port>


    • <hostname or IP address> = Hostname, DNS, or IP address of the Service Virtualization machine, such as or

      Note: Raw IPv6 addresses are not supported. As a workaround, you can map the IP address to a hostname in the machine's hosts file , and then use the hostname in the qm.ini file.

    • <TCP port> (mandatory) = The TCP port of the Service Virtualization agent, such as 5500 or 5000.

    For additional configuration parameters, see Additional queue manager configuration options.

  5. Stop and then restart your queue manager. On a Windows system, you may need to also stop and restart the IBM MQ system service.

Back to top

Additional queue manager configuration options

You can define additional configuration parameters in the queue manager configuration file for debugging and timeout settings.

In qm.ini, configure the Data section of MQ API Exit definition in the following format (up to 32 characters):

<hostname or IP address>:<TCP port><timeout><log level>


  • <timeout> (optional) = The TCP connection timeout value, according to the table below.
  • <loglevel> (optional) = The log level of the API exit, according to the table below.

    • The logs can consume large quantities of your disk space. This feature should be enabled for debugging only, and should be turned off by default.
    • When logging is enabled, log files with the pattern sv_mqexit_*.log are created. Those files are placed in the following folders on the MQ server machine:

      • Windows: The default temp folder C:\temp.
      • UNIX: The default temp folder /tmp.

      You must assign write permissions for MUSR_ADMIN and other MQ-related user accounts in order to successfully generate log files and prevent the exit from crashing.

Back to top

Create a new virtual service

Create a new virtual service, and select the appropriate WebSphere MQ Non-Intrusive option for your messaging protocol. For user interface details, see Create New Virtual Service Wizard.

You can now virtualize any request/response queue pair from the queue manager.

Back to top