Configuring the Oracle Messaging Gateway Agent on Windows

Metalink note id : ID 188833.1

Purpose

This document will provide the reader with instructions on how to install and configure the  Messaging Gateway (MGW) Agent in a Windows environment in order to communicate with Websphere MQ.
It is assumed that the Oracle server is running at least 9.0.1.2 or above.

Scope and Application

To highlight key configuration information for the Messaging Gateway Agent running in Windows 32-bit and 64-bit (as per Note:726111.1 MGW is supported from 10.2.0.3 onwards) environments.

Configuring the Oracle Messaging Gateway Agent on Windows Platforms

Introduction 

The goal of the Oracle Message Gateway product is to propagate messages between Oracle Advanced Queues and non-Oracle messaging systems.  Propagation is performed by the gateway agent which represents a running instance of the Messaging Gateway.

Oracle Software required
1.  A Enterprise Edition install of 9.0.1 onwards.

Note that for Release 9.0.1 the Messaging Gateway software is installed as a separate product.   In 9.2 onwards the Messaging Gateway software is installed by default during a Server install.

After installation of MGW you will have a folder named: %ORACLE_HOME%\mgw, from this folder, you should have the following sub-folders: admin, classes, doc, lib, log and samples.

2.  For Release 9.2 apply the latest MGW Patch bundle as per Note 238070.1. In 10.1 onwards MGW fixes are included in the RDBMS patchset release mechanism.
Non-Oracle Messaging System Prerequisites

1.  If the Websphere MQ queue manager is running on a separate machine then you will need to install Websphere client software for Windows. The appropriate software for the Windows platform can be obtained from IBM. A queue manager must be created and running for the MGW agent to connect to. A destination queue for the propagated messages and log queues for the MGW agent must also exist.

If you are making Java bindings the Websphere queue manager will have to reside on the same machine as the Oracle database.  If you are using a client TCP/IP connection then the queue manager can reside on another machine. In this case the queue manager listener service must be up and running on a specified port (the default is 1414).  You will also need to define a Websphere channel of type Server Connection for the MGW agent to utilise. If the Websphere queue manager is running on a separate machine then you will need to install MQSeries client software on the machine on which the Oracle software is installed.

Note: A Websphere MQ server installation will already have a client installed.

2.  For the 5.2 Websphere client or Server installation you will require the Support Pac MA88: MQSeries classes for Java and MQSeries classes for Java Message Service for your Unix system. This can be obtained from IBM along with installation instructions. This comes by default with Websphere MQ 5.3 onwards.

Post-installation Tasks
Before the Messaging Gateway can run:

1. Using sqlplus, connected as SYS, run the catmgw.sql file. This loads the necessary objects for Messaging Gateway. It also creates two roles, MGW_ADMINISTRATOR_ROLE and the MGW_AGENT_ROLE.

cd %ORACLE_HOME%\mgw\admin
sqlplus /nolog
connect / as sysdba

2. Modify the following system files:

(a) Listener.ora

(b) Tnsnames.ora

(c) Mgw.ora
Most configuration problems are caused by incorrect information being specified to complete this step. Below you will find the specifications required to get the Agent running in all circumstances on Windows platforms.

Please replace parameters HOST, PORT, ORACLE_HOME, SID_NAME, GLOBAL_DBNAME,
SID with values appropriate for your environment. By default the listener.ora and tnsnames.ora are located in the %ORACLE_HOME%\network\admin folder. The mgw.ora is located in %ORACLE_HOME%\mgw\admin folder.

LISTENER.ORA entries

LISTENER =
  (DESCRIPTION =
   (ADDRESS_LIST =
    (ADDRESS =
     (PROTOCOL = TCP)
     (HOST = cmillspc2)
     (PORT = 1521)
    )
    (ADDRESS =
     (PROTOCOL = ipc)
     (key=EXTPROC)
     )
    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
   (SID_DESC=
    (SID_NAME = MGWEXTP)
    (ORACLE_HOME = )
    (PROGRAM=EXTPROC)
   )
   (SID_DESC =
    (GLOBAL_DBNAME = test)
    (ORACLE_HOME = [ORACLE_HOME])
    (SID_NAME = test)
   )
  )

NOTE: The [ORACLE_HOME] and [MQSERIES_HOME] setting should be modified to reflect the correct literal location of your Oracle and Websphere MQ home respectively.

TNSNAMES.ORA entries

EXTPROC_CONNECTION_DATA=
  (DESCRIPTION =
  (ADDRESS_LIST =
  (ADDRESS = (PROTOCOL=IPC)(KEY=EXTPROC)))
  (CONNECT_DATA = (SID=mgwextp) (PRESENTATION=RO)))  

If you require an agent_service alias then you will also need the following

AGENT_SERVICE =
 (DESCRIPTION =
 (ADDRESS_LIST=
  (ADDRESS=
  (PROTOCOL=IPC)(KEY=EXTPROC)))
  (CONNECT_DATA=
  (SID=test)(PRESENTATION=RO)))

MGW.ORA entries

9.0.1

set MGW_PRE_PATH=[ORACLE_HOME]\Apache\jdk\jre\bin\classic

set CLASSPATH=[ORACLE_HOME]\jdbc\lib\classes12.jar;[ORACLE_HOME}\Apache\jdk\jre\lib\i18n.jar;[ORACLE_HOME]Apache\jdk\jre\lib\rt.jar;[ORACLE_HOME]\sqlj\lib\runtime.jar;[ORACLE_HOME]\sqlj\lib\translator.jar;[ORACLE_HOME]\jdbc\lib\nls_charset12.jar;[ORACLE_HOME]\mgw\classes\mgw.jar;[MQSERIES_HOME]\java\lib\com.ibm.mq.jar;[MQSERIES_HOME]\java\lib\com.ibm.mqbind.jar;[MQSERIES_HOME]\java\lib\com.ibm.jms.jar;[MQSERIES_HOME]\java\lib\jms.jar;[MQSERIES_HOME]\java\lib\jndi.jar;[MQSERIES_HOME]\java\lib\jta.jar;[MQSERIES_HOME]\java\lib\connector.jar;[MQSERIES_HOME]\java\lib

9.2

set MGW_PRE_PATH=[ORACLE_HOME]\jdk\jre\bin\classic

set CLASSPATH=[ORACLE_HOME]\jdbc\lib\classes12.jar;[ORACLE_HOME]\jdk\jre\lib\i18n.jar;[ORACLE_HOME]\jdk\jre\lib\rt.jar;[ORACLE_HOME]\sqlj\lib\runtime.jar;[ORACLE_HOME]\sqlj\lib\translator.jar;[ORACLE_HOME]\jdbc\lib\nls_charset12.jar;[ORACLE_HOME]\mgw\classes\mgw.jar;[MQSERIES_HOME]\java\lib\com.ibm.mq.jar;[MQSERIES_HOME]\java\lib\com.ibm.mqbind.jar;[MQSERIES_HOME]\java\lib\com.ibm.jms.jar;[MQSERIES_HOME]\java\lib\jms.jar;[MQSERIES_HOME]\java\lib\jndi.jar;[MQSERIES_HOME]\java\lib\jta.jar;[MQSERIES_HOME]\java\lib\connector.jar;[MQSERIES_HOME]\java\lib

10.1

set MGW_PRE_PATH=[ORACLE_HOME]\jdk\jre\bin\client

set CLASSPATH=[ORACLE_HOME]\mgw\classes\mgw.jar;[ORACLE_HOME]\jdbc\lib\ojdbc14.jar.jar;[ORACLE_HOME]\jlib\orai18n.jar;[ORACLE_HOME]\jdk\jre\lib\rt.jar;[ORACLE_HOME]\sqlj\lib\runtime12.jar;[ORACLE_HOME]\oc4j\sqlj\lib\translator.jar;[ORACLE_HOME]\jlib\jta.jar;[ORACLE_HOME]\rdbms\jlib\jmscommon.jar;[ORACLE_HOME]\rdbms\jlib\aqapi13.jar;[MQSERIES_HOME]\java\lib\com.ibm.mq.jar;[MQSERIES_HOME]\java\lib\com.ibm.mqbind.jar;[MQSERIES_HOME]\java\lib\com.ibm.jms.jar;[MQSERIES_HOME]\java\lib\jms.jar;[MQSERIES_HOME]\java\lib\jndi.jar;[MQSERIES_HOME]\java\lib\jta.jar;[MQSERIES_HOME]\java\lib\connector.jar;[MQSERIES_HOME]\java\lib

10.2

set MGW_PRE_PATH=[ORACLE_HOME]\jdk\jre\bin\client

set CLASSPATH=[ORACLE_HOME]\jdbc\lib\ojdbc14.jar.jar;[ORACLE_HOME]\jlib\orai18n.jar;
[ORACLE_HOME]\jdk\jre\lib\rt.jar;[ORACLE_HOME]\sqlj\lib\runtime12.jar;[ORACLE_HOME]\oc4j\sqlj\lib\translator.jar;[ORACLE_HOME]\jlib\jta.jar;[ORACLE_HOME]\rdbms\jlib\jmscommon.jar;[ORACLE_HOME]\rdbms\jlib\aqapi13.jar;[MQSERIES_HOME]\java\lib\com.ibm.mq.jar;[MQSERIES_HOME]\java\lib\com.ibm.mqbind.jar;[MQSERIES_HOME]\java\lib\com.ibm.jms.jar;[MQSERIES_HOME]\java\lib\jms.jar;[MQSERIES_HOME]\java\lib\jndi.jar;[MQSERIES_HOME]\java\lib\jta.jar;[MQSERIES_HOME]\java\lib\connector.jar;[MQSERIES_HOME]\java\lib

11.1

set MGW_PRE_PATH=[ORACLE_HOME]\jdk\jre\bin\client

set CLASSPATH=[ORACLE_HOME]\jdbc\lib\ojdbc5.jar.jar;[ORACLE_HOME]\jlib\orai18n.jar;[ORACLE_HOME]\jdk\jre\lib\rt.jar;[ORACLE_HOME]\sqlj\lib\runtime12.jar;[ORACLE_HOME]\jlib\jta.jar;[ORACLE_HOME]\rdbms\jlib\jmscommon.jar;[ORACLE_HOME]\rdbms\jlib\aqapi.jar;[MQSERIES_HOME]\java\lib\com.ibm.mq.jar;[MQSERIES_HOME]\java\lib\com.ibm.mqbind.jar;[MQSERIES_HOME]\java\lib\com.ibm.jms.jar;[MQSERIES_HOME]\java\lib\jms.jar;[MQSERIES_HOME]\java\lib\jndi.jar;[MQSERIES_HOME]\java\lib\jta.jar;[MQSERIES_HOME]\java\lib\connector.jar;[MQSERIES_HOME]\java\lib

3.  Modify the tnsnames.ora file for the Gateway Agent's connection to the database. At present the Messaging Gateway agent must run on the same machine as the database server. You can use any protocol you prefer to connect to the database. The simplest is bequeath which means that you do not have to specify an alias in the tnsnames.ora but will have to specify ORACLE_SID in the mgw.ora.

4.  Create the MGW Administration User
To perform gateway administration work, a database user with MGW_ADMINISTRATOR_ROLE privileges must be created.

connect / as sysdba

CREATE USER <mgwadmin> IDENTIFIED BY <mgwadmin_password>;
GRANT CONNECT, RESOURCE to <mgwadmin>;
GRANT MGW_ADMINISTRATOR_ROLE to <mgwadmin>;

5.  Create the Agent User:
To establish the gateway agent's connection back to the database, a database user with MGW_AGENT_ROLE privileges must be created.

connect / as sysdba
CREATE USER <mgwagentuser> IDENTIFIED BY <mgwagentuser_password>;
GRANT CONNECT, RESOURCE to <mgwagentuser>;
GRANT MGW_AGENT_ROLE to <mgwagentuser>;

6.  Configure the gateway agent connection information.

CONNECT <mgwadmin> / <mgwadmin_password>
EXEC DBMS_MGWADM.DB_CONNECT_INFO ('<mgwagentuser>','<mgwagentuser_password>',
'<agent_service_alias>');

where <agent_service_alis> is a valid tns alias that would allow
sqlplus <mgwagentuser>/<mgwagentuser_password>@<agent_service_alias>
to complete successfully.
7.   To verify configuration confirm that you can successfully startup and shutdown of the Messaging Gateway agent via
sqlplus <mgwadmin>/<mgwadmin>
exec dbms_mgwadm.startup
select agent_status, agent_ping from mgw_gateway;
should eventually report an agent status of 'RUNNING' and agent_ping of 'REACHABLE' if the configuration steps have been completed successfully.
If this is not the case set log_level=3 in the mgw.ora and trace a failing startup. Create a Service Request and upload the generated log file. By default this will be placed in the %ORACLE_HOME\mgw\log directory. Also, upload the listener.ora, tnsnames.ora and mgw.ora for analysis.

8. Optionally set up the samples in the %ORACLE_HOME%\mgw\samples folder or configure the Oracle database and Websphere MQ Queue Manager as per your requirements.

References

NOTE:212587.1 - Configuring the Oracle Messaging Gateway Agent on Unix Platforms
NOTE:219410.1 - On what Platforms and Versions of Oracle is the Oracle Messaging Gateway available?
NOTE:238070.1 - Patch Availability for the Oracle Messaging Gateway Agent
NOTE:726111.1 - Is there a 64-bit version of the Messaging Gateway for 64-bit Microsoft Windows Server 2003?