Adapter Installation

Overview

This section is used to guide the user in the installation of the Oracle Utilities Network Management System Generic IBM MQ Mobile Adapter. The following are assumed to be true before the adapter is installed:

1. Oracle Utilities Network Management System is installed and functional. This means that database access has been confirmed, as well as Isis message bus communication.

2. IBM MQ is installed on a machine that is accessible to the Oracle Utilities Network Management System.

Check if the Generic IBM MQ Mobile Adapter is installed

Verify that the following files are found in their respective folders

• $NMS_BASE/bin/mdsgateway

• $NMS_BASE/bin/nms‑mds‑gateway

Configure Adapter to Run as NMS System Service

Configure the Generic IBM MQ Mobile Adapter to run as an Oracle Utilities Network Management System service by updating the $NMS_HOME/etc/system.dat file to include the Generic IBM MQ Mobile Adapter as a system service. There are 3 main sections where this service needs to be defined: the service, program and instance sections.

See the $NMS_BASE/templates/system.dat.template file for examples of how to configure the Generic IBM MQ Mobile Adapter. Search for "mdsgateway" in the file and copy those lines to $NMS_HOME/etc/system.dat file. Make sure all lines are uncommented so that they are active.

See the command line options section below for more details on available options. You must restart the system services in order to the Generic IBM MQ Mobile Adapter to properly be monitored by SMService.

Note: In setting up $NMS_HOME/etc/system.dat, it is important to note that the examples above were presented only for illustration purposes. Parameters may differ on an actual project setting. Coordinate with your Project Engineer in setting up your system configuration file. Also, take note that in the example above, it is assumed that the Generic IBM MQ Mobile Adapter will reside on the same machine where the Oracle Utilities Network Management System environment resides.

Generic IBM MQ Mobile Adapter Command Line Options

The command line for the Generic IBM MQ Mobile Adapter provides the following options:

• -debug <level>: Output debug messages to the log from the adapter and all API toolkits.

• -dl: Output level zero (fewest) debug messages from the adapter, only, to the log. (Note that this is the letter 'l').

• -d1: Output level one and lower debug messages from the adapter, only, to the log. (Note that this is the number '1').

• -d2: Output level two and lower debug messages from the adapter, only, to the log.

• -d3: Output level three and lower debug messages from the adapter, only, to the log.

• -relog <relog time in hours>: The relog period in hours. The log file continues to grow as the adapter runs. This can potentially fill up a disk. To avoid this, the adapter has the facility to close the log file, save it in the logs directory and open a new log file. This can be achieved using the "relog" high level message, and/or by specifying a relog time in this command line option. The default is 24 hours. Specifying a relog period of zero disables periodic relogging.

• -dbserver <database server name>: Specify the database server to use. The adapter can be a heavy user the database. To prevent it from having an impact on other users and to prevent other users from having an impact on it, it can be configured to use its own database server. The default is to use the normal DBService. To configure the use of its own database server, use this command line option, and make sure that an instance of DBService is running with the database server name as its –service command line option.

• -waitfor <service name>: The name of a service to wait for before beginning initialization. It is highly recommended that the adapter waits for the database server it uses. The default is DBService. If the –dbserver option is used, this option should be set to the name that the instance of DBService has been given in its process_name option. Specifying the empty string as the name disables this feature

• -maxwaitfor <time in seconds>: The maximum time to wait for the service the adapter waits for before beginning initialization. If the service does not respond within this time, the adapter exits with a fatal error message. The default is 120 (two minutes).

• -dmldir <directory path>: The path of the directory that contains the configuration files (.dml files). The full path of the directory should be specified.

Any other command line arguments are assumed to be file names of configuration files to use. They are processed in the order that they appear in the command line. If the adapter is being run as a Service, the full path name of the files should be specified.

Optionally Configure the Adapter to Run with Another Instance of DBService

In $NMS_HOME/etc/system.dat, include the MQDBService as one of the services. Use the TCDBService entries as examples of how to set this up.

Note: If using a separate DBService, you must start the Generic IBM MQ Mobile Adapter with the "-custdbsname" command line parameter and use the MQDBService name as the argument.

Configure the IBM MQ Server

1. Create a new Queue Manager named NMS_MGR.A.

2. Make NMS_MRG.A the default queue.

3. From NMS_MRG.A, create two new local queues:

• NMS.A.FROMNMS

• NMS.A.TONMS

4. Create a server connection channel (SCH1) in NMS_MGR.A. The MCA User ID is the local login userid.

5. Start the server connection channel.

6. Create a new queue manager listener service.

7. Stop the original default queue manager listener and set it to not start automatically.

8. Create a new queue manager listener for NMS_MGR.A. It should be configured to start automatically. Start the queue manager listener.

Configure the MQ Client

Set Environment Variables

The environment configuration file (nms.rc), which is a data file listing Oracle Utilities Network Management System environment settings, should have the following:

export MQSERVER=[ServerConnectionChannelName]/TCP/[MQ_Server_IP_Address or hostname]$port number$

For example:

export MQSERVER=SCH1/TCP/10.115.3.85

• If required for your environment, the configuration file must also have two variables set to locate the .TAB file for IBM MQ. The .TAB must be copied to the MQ client from the MQ server host as specified by these variables.

Examples:

export MQCHLLIB=/users/proj/MQ

export MQCHLTAB=AMQCLCHL.TAB

Testing the Connections

Once the server and client are configured, you can test the connections.

1. Test the server connection channel (amqscnxc).

2. Test putting a message (amqsputc) using the NMS.A.FROMMNS local queue.

3. Test getting a message from the server (amqsgetc) using the NMS.A.TONMS local queue.

Configure Queues for Required Data Flows

All incoming (with respect to NMS) data flows would go through the NMS.A.TONMS queue. All outgoing messages would go through the NMS.A.FROMNMS queue. Additionally, an error queue is intended for all adapter generated error messages.

These queues must be added to the DML configuration with the following parameters:

config_QueueManager_name

config_OutQueue_[id]_name

config_InQueue_[id]_name

where [id] is a unique identifier to differentiate between multiple output or input queues.