IBM Tivoli Netcool/OMNIbus Gateway for Oracle: · PDF filevi IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide. Table 1. ... Update, Control (IDUC) processing system

IBM® Tivoli® Netcool/OMNIbus Gateway for OracleVersion 5.0

Reference GuideNovember 8, 2013

SC23-7669-08

��

IBM® Tivoli® Netcool/OMNIbus Gateway for OracleVersion 5.0

Reference GuideNovember 8, 2013

SC23-7669-08

��

NoticeBefore using this information and the product it supports, read the information in “Notices and Trademarks,” on page 53.

Edition notice

This edition (SC23-7669-08) applies to version 5.0 of the Gateway for Oracle and to all subsequent releases andmodifications until otherwise indicated in new editions.

This edition replaces SC23–7669–07.

© Copyright IBM Corporation 2007, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this guide . . . . . . . . . . . vDocument control page . . . . . . . . . . . vConventions used in this guide . . . . . . . viii

IBM Tivoli Netcool/OMNIbus Gateway forOracle . . . . . . . . . . . . . . . 1Summary . . . . . . . . . . . . . . . 2Supported Oracle versions and platforms . . . . . 3Tivoli Netcool/Reporter compatibility . . . . . . 3Obtaining the Gateway for Oracle . . . . . . . 4Audit mode and reporter mode . . . . . . . . 4FIPS mode and encryption. . . . . . . . . . 6IPv6 connectivity . . . . . . . . . . . . . 7Setting environment variables . . . . . . . . 7Oracle client libraries . . . . . . . . . . . 8Installing the gateway . . . . . . . . . . . 8

Installing probes and gateways on TivoliNetcool/OMNIbus V8.1 . . . . . . . . . 8Installing the gateway on TivoliNetcool/OMNIbus V7.3.0, V7.3.1, and V7.4.0 . . 10Installing audit and reporter mode scripts onNetcool/OMNIbus V7.3.0 or later . . . . . . 11Installing the gateway interactive command linetool . . . . . . . . . . . . . . . . 13

Configuring the Database. . . . . . . . . . 14Configuring the gateway . . . . . . . . . . 15

Properties file. . . . . . . . . . . . . 15Properties and command line options . . . . 15Audit and reporter mode properties . . . . . 29Specifying the alerts tables that the gatewaymonitors . . . . . . . . . . . . . . 30Specifying the time zone associated with events 31Map definition file . . . . . . . . . . . 31Startup command file . . . . . . . . . . 35Trusted hosts definition file . . . . . . . . 36Message log . . . . . . . . . . . . . 36Partitioning Oracle tables . . . . . . . . . 37Work areas and limits . . . . . . . . . . 38

Gateway interactive command line tool . . . . . 39Using the GICMD tool . . . . . . . . . 40Authentication . . . . . . . . . . . . 40GICMD properties file . . . . . . . . . . 41GICMD commands . . . . . . . . . . . 41

Statistics . . . . . . . . . . . . . . . 44Error messages . . . . . . . . . . . . . 46Frequently asked questions . . . . . . . . . 47Troubleshooting . . . . . . . . . . . . . 50

Appendix. Notices and Trademarks . . 53Notices . . . . . . . . . . . . . . . . 53Trademarks . . . . . . . . . . . . . . 55

© Copyright IBM Corp. 2007, 2013 iii

iv IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide

About this guide

The following sections contain important information about using this guide.

Document control pageUse this information to track changes between versions of this guide.

The IBM Tivoli Netcool/OMNIbus Gateway for Oracle documentation is providedin softcopy format only. To obtain the most recent version, visit the IBM TivoliNetcool Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/common/kc_welcome-444.html?lang=en

Table 1. Document modification history

Documentversion

Publicationdate Comments

SC23-6039-00 April 27,2007

First IBM® publication.

SC23-7669-00 June 25, 2007 Summary table updated.

Site referenced for downloading the gateway updated.

Support for the TO_STRING, TO_INTEGER, TO_DATE, andTO_TIME conversion operators added.

Support for concatenation within mapping definitionsadded.

SC23-7669-01 December 19,2007

Summary section updated. Support for IBM Tivoli®

Netcool/OMNIbus V7.2 added.

Platform support information updated.

"Backing up existing scripts" section updated.

"Map definition file" section updated.

"Technical notes" section updated.

"Troubleshooting" section updated.

© Copyright IBM Corp. 2007, 2013 v



Table 1. Document modification history (continued)

Documentversion


SC23-7669-02 July 25, 2008 Summary section updated.

Support for Linux for zSeries added.

Supported version and platforms section updated.

Gateway compliance with FIPS section added.

IPv6 connectivity section added.

Configuring the Database section modified.

Library path settings section updated.

Installation section modified.

New property Gate.FIPSMode added.

Command line options section added.

Example mapping sections updated.

Installing the Gateway for Oracle on Windows sectionadded.

vi IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide


Documentversion


SC23-7669-03 July 21, 2009 “Summary” on page 2 updated.

“Audit mode and reporter mode” on page 4 updated.

“Supported Oracle versions and platforms” on page 3updated.

Section added to discuss how the audit scripts areinstalled on UNIX and Windows platforms.

Section added to discuss how the reporter scripts areinstalled on UNIX and Windows platforms.

Section to discuss how the gateway interactive commandtool is installed on Unix or Windows platforms.

Descriptions for the following properties added to“Properties and command line options” on page 15:

v Gate.StatusTableName

v Gate.DetailsTableName

v Gate.JournalTableName

v Oracle.UsePartitioning

v Oracle.PartitioningField

v Oracle.SendTimezoneData

Section added to discuss how changes made to nominateddatabase tables can be monitored. See “Specifying thealerts tables that the gateway monitors” on page 30.

Section added to discuss the use of table partitioningwithin the Oracle database. See “Partitioning Oracletables” on page 37.

Section added to discuss the association of time zoneswith events. See “Specifying the time zone associatedwith events” on page 31.

About this guide vii


Documentversion


SC23-7669-04 November26, 2010

Requirements information updated in “Summary” onpage 2.

New section added to describe Tivoli Netcool/Reportercompatibility. See “Tivoli Netcool/Reporter compatibility”on page 3.

Audit and reporter mode information updated in “Auditmode and reporter mode” on page 4.

New section added to describe the gateway interactivecommand line (GICMD) tool. See “Gateway interactivecommand line tool” on page 39.

Information about setting environment variables updatedin “Setting environment variables” on page 7.

Database configuration information updated in“Configuring the Database” on page 14.

Work area, and hard and soft limits, information updatedin “Work areas and limits” on page 38.

SC23-7669-05 July 29, 2011 Information about operating system conventions added in“Conventions used in this guide.”

Support information updated in “Supported Oracleversions and platforms” on page 3.

Frequently asked questions (FAQ) updated in “Frequentlyasked questions” on page 47.

Troubleshooting information updated in“Troubleshooting” on page 50.

SC23-7669-06 March 02,2012

Information about using log file environment variablesupdated in “Message log” on page 36.

SC23-7669-07 November30, 2012

Guide updated for Netcool/OMNIbus V7.4.0 release.

Details about installing gateways updated. See “Installingthe gateway” on page 8.

SC23-7669-08 November 8,2013

“Audit mode and reporter mode” on page 4 updated.

“Installing audit and reporter mode scripts onNetcool/OMNIbus V7.3.0 or later” on page 11

Conventions used in this guideAll gateway guides use standard conventions for operating system-dependentenvironment variables and directory paths.

Operating system-dependent variables and paths

All gateway guides use standard conventions for specifying environment variablesand describing directory paths, depending on what operating systems the gatewayis supported on.

viii IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide

For gateways supported on UNIX and Linux operating systems, gateway guidesuse the standard UNIX conventions such as $variable for environment variables andforward slashes (/) in directory paths. For example:

$OMNIHOME/gates

For gateways supported only on Windows operating systems, gateway guides usethe standard Windows conventions such as %variable% for environment variablesand backward slashes (\) in directory paths. For example:

%OMNIHOME%\gates

For gateways supported on UNIX, Linux, and Windows operating systems,gateway guides use the standard UNIX conventions for specifying environmentvariables and describing directory paths. When using the Windows command linewith these gateways, replace the UNIX conventions used in the guide withWindows conventions. If you are using the bash shell on a Windows system, youcan use the UNIX conventions.

Note: The names of environment variables are not always the same in Windowsand UNIX environments. For example, %TEMP% in Windows environments isequivalent to $TMPDIR in UNIX and Linux environments.

Operating system-specific directory names

Where Tivoli Netcool/OMNIbus files are identified as located within an archdirectory under NCHOME or OMNIHOME, arch is a variable that represents youroperating system directory. For example:

$OMNIHOME/gates/arch/

The following table lists the directory names used for each supported operatingsystem.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

HP-UX PA-RISC-based systems hpux11

HP-UX Integrity-based systems hpux11hpia

Red Hat Linux and SUSE systems linux2x86

Linux for System z® linux2s390

Solaris systems solaris2

Windows systems win32

About this guide ix

x IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide

IBM Tivoli Netcool/OMNIbus Gateway for Oracle

The Gateway for Oracle writes selected alert details to Oracle databases.

The gateway writes to three Oracle database tables (status, journal, and details)to record all transactions that occur within alerts selected by an ObjectServerreader.

The Gateway for Oracle has the following features:v A permanent data cache that the gateway uses to resynchronize itself with the

ObjectServer.v Identification of missed inserts, deletes, and updates on restart.v Recoverable memory-resident work regions.v Optimized Netcool/OMNIbus V3.x Insert, Delete, Update, Control (IDUC)

processing system.v Statistics gathering and display.v Encrypted passwords used throughout.v Use of Oracle host (bind) arrays for faster batch data transfer.v An interactive gateway command-line tool (GICMD) for issuing data transfer

commands.

Note: The Gateway for Oracle is now deprecated. If you are starting a newdeployment, you should use instead the Gateway for JBDC.

The Gateway for Oracle is described in the following sections:v “Summary” on page 2v “Supported Oracle versions and platforms” on page 3v “Tivoli Netcool/Reporter compatibility” on page 3v “Obtaining the Gateway for Oracle” on page 4v “Audit mode and reporter mode” on page 4v “IPv6 connectivity” on page 7v “Setting environment variables” on page 7v “Oracle client libraries” on page 8v “Installing the gateway” on page 8v “Configuring the Database” on page 14v “Configuring the gateway” on page 15v “Gateway interactive command line tool” on page 39v “Statistics” on page 44v “Error messages” on page 46v “Frequently asked questions” on page 47v “Troubleshooting” on page 50

© Copyright IBM Corp. 2007, 2013 1

SummaryEach gateway works in a different way to provide an interface to the ObjectServer.Use this summary information to learn about the Gateway for Oracle.

The following table provides a summary of the gateway.

Table 3. Summary

Gateway target Oracle versions 10g and 11g

Gateway executable file name nco_g_oracle

Gateway installation package omnibus-arch-gateway-nco-g-oracle-version

Package version 5.0

Gateway supported on For details of supported operating systems, see thefollowing Release Notice on the IBM Software Supportwebsite:

https://www-304.ibm.com/support/docview.wss?uid=swg21613117

Requirements A currently supported version of IBM TivoliNetcool/OMNIbus

If you are running IBM Tivoli Netcool/OMNIbusV7.2.1, you must have Fix Pack 3 (7.2.1-TIV-NCOMNIbus-FP0003) installed.

Oracle instant client libraries for all platforms exceptAIX. For AIX, the full client is required.Note: These libraries are available from the Oracle Website at:http://www.oracle.com/technology/tech/oci/instantclient/index.html.

Licensing Electronic licensing was deprecated with the release ofIBM Tivoli Netcool V7.2.0. All IBM Tivoli Netcool V7.2.0(and later) products use the IBM software licensingprocess.

Internationalization support Not available

IP environment IPv4 and IPv6

The gateway is supported on IPv6 when running onIBM Tivoli Netcool/OMNIbus V7.3.0, 7.3.1 and 7.4.0 onSolaris, and on IBM Tivoli Netcool/OMNIbus V7.3.0,7.3.1 and 7.4.0 on all other UNIX plaftorms. Thegateway is supported on IPv6 when running on IBMTivoli Netcool/OMNIbus V7.3.0, 7.3.1 and 7.4.0 onWindows plaftorms.

Note: The supported Oracle client libraries do notsupport IPv6.

2 IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide



http://www.oracle.com/technology/tech/oci/instantclient/index.html


Table 3. Summary (continued)

Federal Information ProcessingStandards (FIPS)

IBM Tivoli Netcool/OMNIbus V7.2.1 uses the FIPS140-2 approved cryptographic provider: IBM Crypto forC (ICC) certificate 384 for cryptography. This certificateis listed on the NIST web site at http://csrc.nist.gov/cryptval/140-1/1401val2004.htm For details aboutconfiguring Netcool/OMNIbus for FIPS 140-2 mode, seeIBM Tivoli Netcool/OMNIbus Installation and DeploymentGuide (SC14-7604).

Supported Oracle versions and platformsAn Oracle client, such as the Netcool/OMNIbus Gateway for Oracle, caninteroperate with many different versions of the Oracle server using one set ofOracle client libraries.

If you have an issue with the gateway, you must be able to reproduce it using oneof the versions of the Oracle server listed in the following table against a validatedplatform before contacting IBM Software Support. Otherwise, you must raise theissue with your Oracle Support provider.

Oracle configuration features such as Real Application Clusters and Oracle ParallelServer are designed by Oracle to be application-independent. Therefore, theGateway for Oracle will work with these Oracle features.

Note: The Gateway for Oracle is compatible with both Standard and EnterpriseEditions of Oracle for all supported versions of Oracle on all supported operatingsystems. The gateway is not supported on Solaris version 7 and earlier. Thegateway supports IPv6.

Gateway connectivity has been tested on versions 10g and 11g of the Oracle serverusing Oracle client version 10.2. The gateway has been validated only against theserver versions listed in the following table:

Table 4. Supported Oracle versions and platforms

Oracle version Supported platforms

Oracle versions 10g and11g

AIX 5.2, 6.1

HP Itanium 11.23, 11.3

HP-UX 11i

Linux and Linux for zSeries, SLES 10, RHEL 4.0/RHEL 5.0

Note: When running the Gateway for Oracle on SLES 10, youmust run the nscd daemon before running the gateway.

Solaris 9, 10

Windows 2003 Server

Tivoli Netcool/Reporter compatibilityThe gateway supports IBM Tivoli Netcool/Reporter.

IBM Tivoli Netcool/OMNIbus Gateway for Oracle 3

http://csrc.nist.gov/cryptval/140-1/1401val2004.htm

http://csrc.nist.gov/cryptval/140-1/1401val2004.htm

IBM Tivoli Netcool/Reporter is an event reporting application that can be usedwith IBM Tivoli Netcool/OMNIbus and the Gateway for Oracle. The gatewaysupports full data exchange between IBM Tivoli Netcool/Reporter and Oracledatabases.

To use the gateway with IBM Tivoli Netcool/Reporter, you must install thereporter mode patch. See “Audit mode and reporter mode” for details.

Obtaining the Gateway for OracleThe gateway installation package and the patches for the related components areavailable for download from IBM.

To obtain the gateway and the patches for the related components, visit thefollowing website:

http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm.

The following packages and components are available as separate downloads:v The gateway installation package.v IBM Tivoli Netcool/Reporter.v The audit mode and reporter mode patches.v The GICMD tool.

Audit mode and reporter modeThe Gateway for Oracle can operate in one of two modes, audit mode or reportermode.

When the gateway generates events, it inserts rows into a database table, with anaction code for each event. How this is done depends on whether you are runningthe gateway in audit mode or in reporter mode.

You only need to run the gateway in reporter mode when you want to exchangedata between the gateway and IBM Tivoli Netcool/Reporter. At all other times,you will run the gateway in audit mode. In audit mode, Netcool/OMNIbus eventsare archived to the Oracle database.

In audit mode, a new row is created in the database table for every alert. Thisincreases the size of the table in the database but ensures a proper record of theexact sequence of events. Audit mode never updates or deletes existing data in thetarget database.

Inserts, updates, and deletes are mapped as follows:v Inserts insert a new row into the target table.v Updates insert a new row into the target table, with the updated data.v Deletes insert a new row into the target table. The inserted row is mostly empty,

to indicate that the row has no data.

The target database can contain multiple rows for each OMNIbus alert, dependingon the update history of the alert.

In reporter mode, the target database is updated whenever the gateway generatesan alert. This requires the target database to be configured for reporting, which


http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm


involves various triggers to generate the reporting data. Reporter mode essentiallyreplicates the source status table from the ObjectServer into the target database.

Inserts, updates, and deletes are mapped as follows:v Inserts insert a new row into the target table.v Updates update the corresponding row in the target table.v Deletes update the corresponding row in the target table, entering a timestamp

in a "deleted at" column.

The target database contains one row for each OMNIbus alert.

Running the gateway in audit or reporter mode

If you want to run the gateway in audit mode, you must install thegateway-nco-g-audit-scripts patch. If you want to run the gateway in reportingmode, you must configure the appropriate database schema and install thegateway-nco-g-reporter-scripts library. This library contains the SQL scriptsrequired to create the target database schema.

Note: You must have the database and tablespace already installed and configuredbefore running the SQL scripts.

The mode in which the gateway runs is determined by the Oracle.OracleGWTypeproperty in the properties file. For details, see “Configuring the gateway” on page15.

Audit and reporter mode patches are provided separately from the gatewayinstallation files and are available from the IBM Passport Advantage® Onlinewebsite: http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm.

Note: Configuration files and scripts for the IBM Tivoli Netcool/OMNIbus ODBCGateway are included in the patch, along with those for the Gateway for Oracle.The ODBC configuration files and scripts are not required to run the Gateway forOracle.

Audit mode patch files

Table 5 lists the configuration files and scripts provided by the audit mode patch.

Table 5. Summary of audit mode configuration files and scripts

Configuration files nco_g_oracle.props

nco_g_oracle.map

nco_g_oracle.startup.cmd

nco_g_oracle.thosts

Scripts create_tables.audit.sql

create_tables.audit_tz.sql

orainstall

oracle.update_audit.sql




Reporter mode patch files

Table 6 lists the configuration files and scripts provided by the reporter modepatch.

Table 6. Summary of reporter mode configuration files and scripts

Configuration files nco_g_oracle.props

nco_g_oracle.map

nco_g_oracle.startup.cmd

nco_g_oracle.thosts

Scripts oracle.drop_reporter.sql

oracle.reporter.sql

oracle.reporter_tz.sql

oracle.update_reporter.sql

FIPS mode and encryptionThis gateway complies with Federal Information Processing Standard 140–2 (FIPS140-2). It can be run in FIPS mode on Netcool/OMNIbus V7.2.1 and later.

You can use encryption algorithms to secure string value entries made in theproperties file, including passwords. You must use the generic Netcool/OMNIbusConfigCryptoAlg property to specify the encryption method and the genericNetcool/OMNIbus ConfigKeyFile property to specify the encryption key file,amongst a number of other required settings.

For more information about running the gateway in FIPS mode, and encryptingproperties and passwords, see Running the ObjectServer in secure mode, Running theproxy server in secure mode, and Encrypting plain text passwords in routing definitionsin the IBM Tivoli Netcool/OMNIbus Administration Guide.

Also see, Configuring FIPS 140–2 support for the server components in the IBM TivoliNetcool/OMNIbus Installation and Deployment Guide.

Also see SSL and FIPS 140-2 support in the IBM Tivoli Netcool/OMNIbus EventIntegration Facility Reference.

Also see Appendix C. WAAPI security in the IBM Tivoli Netcool/OMNIbus Web GUIAdministration API (WAAPI) User's Guide.

Note: If you run the gateway in FIPS mode, you must either use no encryption, orif you do use encryption, you must use nco_aes_crypt with the cipher (-c) optionAES_FIPS. The cipher option used here must match the option specified by theConfigCryptoAlg property. For example:

$NCHOME/omnibus/bin/nco_aes_crypt -c AES_FIPS -k key_file string_value


IPv6 connectivityThe Gateway for Oracle can connect to the ObjectServer over an IPv6 interface.

The command and status ports accept connections from the IPv6 clients.

The gateway can connect to the Oracle server over IPv6 if the Oracle librarysupports it. The supported Oracle client libraries are not IPv6 capable.

Setting environment variablesEnvironment variables are specific preset values that establish the workingenvironment of the gateway. From the environment variable specified, the gatewayreceives path information for the directories in which library files are present.

You must set the following environment variables for use with the Oracle database:v Set ORACLE_HOME using the following command:

export ORACLE_HOME=/opt/oracle

where /opt/oracle is the Oracle installation directory.v Set ORACLE_SID using the following command:

export ORACLE_SID=ORCL

In this example, ORCL is the System ID of your Oracle instance.v Set TNS_ADMIN using the following command:

export TNS_ADMIN=$ORACLE_HOME/network/admin

where $ORACLE_HOME/network/admin is the directory containing the tnsnames.orafile.

Library path settings

Before you run the gateway, you must set the library path environment variable toinclude the directory of the Oracle library used by the gateway.

Depending on the operating system you are using, set the following library pathenvironment variables:v On AIX operating systems:

– Set $LIBPATH to include the directory where the Oracle client is installed.– Set $ORACLE_HOME to the directory where the Oracle client is installed.– In some systems, you might also need to set XPG_SUS_ENV to ON.

v On HP Itanium operating systems:If 32-bit libraries are required, set $LD_LIBRARY_PATH to includeinstantclient/lib or instantclient/lib32.

v On HP-UX operating systems:If 32-bit libraries are required, set $SHLIB_PATH to include instantclient/lib orinstantclient/lib32.

v On Linux operating systems:If 32-bit libraries are required, set $LD_LIBRARY_PATH to includeinstantclient/lib or instantclient/lib32.

v On Linux for zSeries operating systems:If 32-bit libraries are required, set $LD_LIBRARY_PATH to includeinstantclient/lib or instantclient/lib32.


v On Solaris operating systems:If 32-bit libraries are required, set $LD_LIBRARY_PATH to includeinstantclient/lib or instantclient/lib32.

v On Windows operating systems:Set $PATH to include the Oracle libraries.

Oracle client librariesBefore running the Gateway for Oracle, you must install the Oracle client librariesfor version 10x.

To run the Gateway for Oracle, you must either have the libraries for Oracle clientversion 10.x or, the latest instant client installed for all platforms except AIX. ForAIX, install the full client.

You can download the libraries from the Oracle Support Site. Go to the followingWeb address:


The tnsnames.ora file contains the host and port number of the database. This fileshould be placed in the same system where the gateway is running.

Note: The Gateway for Oracle is supported only on Oracle10g clients. The Oracleinstant client version 11 is currently not supported, though Oracle 11g is supportedas a server.

Installing the gatewayThere are separate procedures for installing the gateway on each version of TivoliNetcool/OMNIbus.

Follow the procedure for the version of Tivoli Netcool/OMNIbus that your siteuses.

Installing probes and gateways on Tivoli Netcool/OMNIbusV8.1

From Netcool/OMNIbus V8.1 onwards, Netcool/OMNIbus probes and gatewayscan be installed using the IBM Installation Manager (IM). One of the key featuresof Installation Manager is that all platforms are shipped in a single ZIP file, whichmeans that you do not have to select the platform that you require; InstallationManager does it for you.

Before you can install a probe or gateway, you must have installed and configuredInstallation Manager and Netcool/OMNIbus. To install probes and gateways, youmust make sure that the Core Netcool/OMNIbus features Probe Support andGateway Support respectively are installed.

Installing probes and gateways using the Command Line Tool

To install the probe or gateway using the Command Line Tool, run the followingcommand:



installation_manager_location/eclipse/tools/imcl -c installcom.ibm.tivoli.omnibus.integrations.integration_name -repositoriesrepository_containing_required_integration -installationDirectorylocation_of_netcool_omnibus_install_you_are_installing_into

You will be prompted to agree to the terms and conditions of the license as aprerequisite for installing the integration. If you have no concerns about the licenseand want to skip the manual acceptance, add the -acceptLicense option to theinstall command to silently agree to the license.

The following is an example command used to install the SNMP Probe:

imcl -c install com.ibm.tivoli.omnibus.integrations.nco-p-mttrapd-repositories /home/my_home_dir/nco-p-mttrapd_im_package-installationDirecory /opt/IBM/tivoli/netcool

Where /home/my_home_dir/nco-p-mttrapd_im_package contains the unzippedcontents of the SNMP Probe Installation Manager package.

Note: The command line tool does not add the repository permanently to theInstallation Manager instance. If you subsequently start the Installation ManagerGUI, the repositories will not be present in the Repositories dialog box.

Uninstalling probes and gateways using the Command Line Tool

To uninstall the probe or gateway using the Command Line Tool, run thefollowing command:

installation_manager_location/eclipse/tools/imcl uninstallcom.ibm.tivoli.omnibus.integrations.integration_name -installationDirectorylocation_of_netcool_omnibus_install_you_are_uninstalling_from

The following is an example command used to uninstall the SNMP Probe:

imcl uninstall com.ibm.tivoli.omnibus.integrations.nco-p-mttrapd-installationDirecory /opt/IBM/tivoli/netcool

Installing probes and gateways using the GUI

To install the probe or gateway using the GUI, use the following steps:1. Start Installation Manager using the following command:

installer_path/IBMIM

Where installer_path is the path to the Installation Manager directory.2. Ensure that you point to the repository that contains the probe or gateway by

adding the repository using the dialog box got from the following menuactions:Files > Preferences > Repositories.

Use the button Add Repository in the dialog box to carry out this task.

Note: as a prerequisite, the contents of the IM package need to be unzippedinto a directory of your choosing. A file called repository.config will appearafter unzipping the IM package. The repository location in IM should point tothat repository.config file and NOT its containing directory.

3. Click the Install software packages icon.


4. Select the name of the probe or gateway that you want to install.5. Click Next.6. Click I accept when the Licensing panel appears.7. Highlight IBM Tivoli Netcool OMNIbus in the Package Group Name field.8. Click Next.9. Click Next.

10. Click Install.11. When the Install Packages panel appears indicating that you have

successfully installed the probe, click Finish.

Uninstalling probes and gateways using the GUI

To uninstall the probe or gateway, use the following steps:1. Start Installation Manager using the following command:

installer_path/IBMIM

Where installer_path is the path to the Installation Manager directory.2. Click the Uninstall software packages icon.3. Select the name of the probe or gateway that you want to uninstall.4. Click Next.5. Click Unisntall .6. When the Install Packages panel appears indicating that you have successfully

uninstalled the probe, click Finish.

Installing the gateway on Tivoli Netcool/OMNIbus V7.3.0,V7.3.1, and V7.4.0

For Tivoli Netcool/OMNIbus V7.3.0, V7.3.1, and V7.4.0, all gateways are installedusing the Tivoli Netcool/OMNIbus installer.

You can install the gateway using any of the following:v “The installation wizard” on page 11v A text-based installer (“Console mode” on page 11)v Settings predefined in a text file (“Silent mode” on page 11)

The installation package and patches for the gateway are supplied as archives. Thearchive management application that you use to extract the files must be able topreserve the directory structure contained in the archive on extraction.

Note: If you are installing a 32-bit gateway on a system that runs a 64-bit UNIX orLinux operating system, you will need to install additional, 32-bit operating systemlibraries. See the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide formore information.

Obtaining the installation packageTo obtain the installation package and prepare it for installation use the followingsteps:1. Download the installation package for the gateway from the Passport

Advantage Online Web site:http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

2. Make a backup of any existing configuration files that you want to retain.




3. Extract the contents of the installation package to a temporary directory.

Now use one of the installation methods to install your gateway. In each case, thegateway is installed in the following directory:

$NCHOME/omnibus/gates

The installation wizardTo install the gateway using the installation wizard:1. Run the installer for your operating system:

$NCHOME/omnibus/install/nco_install_integration

2. When the installation wizard starts, specify the extracted directory that containsthe README.txt file as the location of the gateway installation files.

3. Accept the license conditions.

Console modeTo install the gateway in console mode:1. Run the installer for your operating system:

$NCHOME/omnibus/install/nco_install_integration -i console

2. When the text-based installer starts, specify the extracted directory that containsthe README.txt file as the location of the gateway installation files.

3. Accept the license conditions.

Silent modeTo install the gateway in silent mode:1. Create a text file named reponse.txt and add the following entries:

PROBE_OR_GATE_LOCATION=README_directorypathLICENSE_ACCEPTED=true

where README_directorypath is the path to the directory containing theREADME.txt file in the extracted package.

2. Run the installer for your operating system:$NCHOME/omnibus/install/nco_install_integration -i silent -fresponse_path/response.txt

where response_path is the full path to the response.txt file.

Installing audit and reporter mode scripts onNetcool/OMNIbus V7.3.0 or later

The gateway can operate in one of two modes, audit mode or reporter mode. Inreporter mode, the gateway works with IBM Tivoli Netcool/Reporter.

If you want to run the gateway in audit mode, you must install thegateway-nco-g-audit-scripts package. If you want to run the gateway inreporting mode, you must configure the appropriate database schema and installthe gateway-nco-g-reporter-scripts library. This library contains the SQL scriptsrequired to create the target database schema.

Note: You must have the database and tablespace already installed and configuredbefore running the SQL scripts.

The mode in which the gateway runs is determined by the Oracle.OracleGWTypeproperty in the properties file. For details, see “Configuring the gateway” on page15.


You can download the audit and reporter mode scripts packages from the PassportAdvantage Online Web site:


Note: Before installing either mode package, you must have installed the gateway.After installing the mode packages, you must configure the database to work withthe audit or reporter scripts as described in “Configuring the Database” on page14.

To install the packages, use the following steps:1. Back up existing scripts and gateway configuration files.2. To run the gateway in audit mode, install the audit mode package.3. To run the gateway in reporter mode, install the reporter mode package.

Backing up existing scripts and configuration files

Before you install either mode package, make a backup of any existing scripts andgateway configuration files.

Existing audit and reporter scripts and gateway configuration files on are locatedin the following directories:v On UNIX and Linux operating systems:

– $OMNIHOME/gates/nco_g_oracle

– $OMNIHOME/gates/audit

– $OMNIHOME/gates/reporter

v On Windows operating systems:– %OMNIHOME%\gates\nco_g_oracle

– %OMNIHOME%\gates\audit

– %OMNIHOME%\gates\reporter

Installing the audit mode package

To install the audit mode package on UNIX and Linux operating systems, use thefollowing steps:1. Run the following command to start the installation wizard:


2. Choose to install the audit mode package and follow the onscreen instructionsto complete the installation.The new audit scripts are located in the $OMNIHOME/gates/audit/oracledirectory.

To install the audit mode package on Windows operating systems, use thefollowing steps:1. Open a Windows command prompt.2. Run the following command to start the installation wizard:

%OMNIHOME%\install\nco_install_integration

3. Choose to install the audit mode package and follow the onscreen instructionsto complete the installation.




The new audit scripts are located in the %OMNIHOME%\gates\audit\oracledirectory.

Installing the reporter mode package

To install the reporter mode package on UNIX and Linux operating systems, usethe following steps:1. Run the following command to start the installation wizard:


2. Choose to install the reporter mode package and follow the onscreeninstructions to complete the installation.The new reporter scripts are located in the $OMNIHOME/gates/reporter/oracledirectory.

To install the reporter mode package on Windows operating systems, use thefollowing steps:1. Open a Windows command prompt.2. Run the following command to start the installation wizard:


3. Choose to install the reporter mode package and follow the onscreeninstructions to complete the installation.The new reporter scripts are located in the %OMNIHOME%\gates\reporter\oracledirectory.

Installing the gateway interactive command line toolInstalling the gateway interactive command line tool (GICMD) provides you with aset of command line options for changing the properties of the gateway while it isrunning.

Installing the GICMD tool on UNIX and Linux operating systems

Before installing the GICMD tool, back up any existing configuration files locatedin the $OMNIHOME/gates/nco_g_icmd/cfg_examples directory.

To install the GICMD tool on UNIX and Linux operating systems, use thefollowing steps:1. Run the following command to start the installation wizard:


2. Choose to install the GICMD tool and follow the onscreen instructions tocomplete the installation.

Installing the GICMD tool on Windows operating systems

Before installing the GICMD tool, back up any existing configuration files locatedin the %OMNIHOME%\gates\nco_g_icmd\cfg_examples directory.

To install the GICMD tool on Windows operating systems, use the following steps:1. Open a Windows command prompt.2. Run the following command to start the installation wizard:



3. Choose to install the GICMD tool and follow the onscreen instructions tocomplete the installation.

Configuring the DatabaseConfiguring the database involves running the audit or reporter mode scripts forthe Oracle database.

Audit and reporter scripts create all the schema objects required to store dataprocessed by the gateway, including the tablespace, temporary tablespace, userreporter or reporter, tables (status, journal, and details), indexes, and constraints.

What script you run depends on whether you want to run the gateway in auditmode or reporter mode. See “Audit mode and reporter mode” on page 4 fordetails of how the gateway operates in each mode.

Prerequisites

Before you can run any audit or reporter script, the following conditions must bemet:1. The gateway is installed.2. If you want to run the gateway in audit mode, you have installed the audit

mode patch.3. If you want to run the gateway in reporter mode, you have installed the

reporter mode patch.4. You have a valid database user name and password, with sufficient rights to

create users and tablespaces.

Running the audit mode scripts

To run the audit scripts for Oracle, use the following steps:1. Change to the directory containing the audit scripts:

v On UNIX operating systems, the directory is $OMNIHOME/gates/audit/oracle.v On Windows operating systems, the directory is %OMNIHOME%\gates\audit\

oracle.2. Run SQLPLUS and enter the database user name and password in the form user

name/[email protected] example, system/[email protected] SQL> prompt is displayed.

3. Run the audit scripts located in the oracle directory.

Running the reporter mode scripts

To run the reporter scripts for Oracle, use the following steps:1. Change to the directory containing the reporter scripts:

v On UNIX and Linux operating systems, the directory is $OMNIHOME/gates/reporter/oracle.

v On Windows operating systems, the directory is %OMNIHOME%\gates\reporter\oracle.

2. Run SQLPLUS and enter the database user name and password in the form username/[email protected] example, system/manager@ORCL.


The SQL> prompt is displayed.3. Run the reporter scripts located in the oracle directory.

Configuring the gatewayAfter installing the Gateway for Oracle and the required patches, the gatewaymight require further configuration to work with your operating environment.

The configuration files described below are included in the audit and reportermode patches. Each patch installs a different set of configuration files. See “Auditmode and reporter mode” on page 4 for details.

The following sections describe the configuration files and how to use them:v “Properties file”v “Properties and command line options”v “Audit and reporter mode properties” on page 29v “Specifying the alerts tables that the gateway monitors” on page 30v “Specifying the time zone associated with events” on page 31v “Map definition file” on page 31v “Startup command file” on page 35v “Trusted hosts definition file” on page 36v “Message log” on page 36v “Partitioning Oracle tables” on page 37v “Work areas and limits” on page 38

Properties fileProperties define the operational environment of the gateway, such as connectiondetails and the location of the other configuration files.

The properties file is a text file that contains a set of properties and theircorresponding values.

On UNIX and Linux operating systems, the nco_g_oracle.props file is located inthe $OMNIHOME/gates/nco_g_oracle/ directory.

On Windows operating systems, the nco_g_oracle.props file is located in the%OMNIHOME%\gates\nco_g_oracle\ directory.

Properties and command line optionsYou use properties to define the operational environment of the gateway. You canoverride the default values by using the properties file.

The following table describes the properties specific to Gateway for Oracle. Formore information about generic Netcool/OMNIbus properties and command lineoptions, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.


Table 7. Properties and command line options

Property name Command line option Description

Gate.AllocateDynamicPorts boolean

-allocatedynamicportsboolean

Use this property to specify whether thegateway allocates the command andstatistics port numbers dynamically.

The default is FALSE.

Note: If this property is set to TRUE, thegateway increments by one the valuesspecified by the Gate.StatisticsPort andGate.GatewayCommandPort properties ifthe gateway is unable to connect to theports specified on startup.

Gate.DataFileBaseDir string

-datafilebasedir string Use this property to specify the locationin which the gateway stores all of itswork area regions and other associatedfiles.

The default is $OMNIHOME/var/.

Gate.DetailsTableMap string

-detailstablemap string Use this property to specify the name ofthe map that is used to map detailsentries to the specified details table in theOracle database. The specified map isdefined in the map definition file.

The default is OracleDetailsMap.

Gate.DetailsTableName string

-detailstable string Use this property to specify the name ofthe details table that the gatewaymonitors for any changes.

The default is alerts.details.

Gate.FIPSModeboolean

-fipsmode boolean Use this property to specify whether thegateway runs in FIPS mode. Whenrunning in FIPS mode, the gatewaydisables all operations that are notcompatible with FIPS. For details see,“FIPS mode and encryption” on page 6.

FALSE: The gateway does not run in FIPSmode.

TRUE: The gateway runs in FIPS mode.

The default value for this propertydepends on the Netcool/OMNIbusenvironment. If a fips.conf file exists,the Netcool/OMNIbus environment isrunning in FIPS mode, and so the defaultvalue for this property is TRUE. Otherwisethe default value is FALSE. The fips.conffile is located at $NCHOME/etc/security/fips.conf in UNIX and at%NCHOME%\ini\security\fips.conf inWindows.


Table 7. Properties and command line options (continued)


Gate.ForwardDetails boolean

-forwarddetails boolean Use this property to specify whether thegateway forwards alert details to thedetails table in the Oracle database.

The default is TRUE.

Gate.ForwardHistoricDetails boolean

-forwardhistdetailsboolean

Use this property to specify whether thegateway forwards all historic details onconverted update.


Gate.ForwardHistoricJournals boolean

-forwardhistjournalboolean

Use this property to specify whether thegateway forwards all historic journals onconverted update.


Gate.FowardJournals boolean

-forwardjournals boolean Use this property to specify whether thegateway forwards alert journals to theJournal table in the Oracle database.


Gate.ForwardStatusDel boolean

-forwardstatdel boolean Use this property to specify whether thegateway sends Status table deletes to thespecified table in the Oracle database.


Gate.ForwardStatusIns boolean

-forwardstatins boolean Use this property to specify whether thegateway sends Status table inserts to thespecified table in the Oracle database.


Gate.ForwardStatusUpd boolean

-forwardstatupd boolean Use this property to specify whether thegateway sends Status table updates to thespecified table in the Oracle database.


Gate.GatewayCommandPort integer

-gwcmdport integer Use this property to specify the port towhich the gateway listens to forinteractive clients.

The default is 4600.




Gate.IDUCFlushRate integer

-iducflushrate integer Use this property to specify the rate, inseconds, of the granularity of the reader.

If you set this property to 0, the gatewayreceives its updates at the same granularrate as the ObjectServer to which it isconnected.

If you set this property to a value greaterthan 0, the reader issues automatic IDUCflush requests to the ObjectServer withthis frequency. This enables the reader torun at a faster granularity than that of theObjectServer, thus enabling the gatewayto capture more detailed event changes insystems where the ObjectServer itself hashigh granularity settings.

The default is 0.

Gate.JournalFetchAdj integer

-journalfetchadj integer This property was deprecated withversion 5.0 of this gateway. It was used tospecify the adjustment that has to bemade against the journal fetch time limit.If set, it helped to ensure that journalswere not missed.

In heavily loaded systems, journal eventscan be created at the start of an IDUCperiod. The gateway may miss theseevents because the time frame in whichthe journal events are retrieved for eachIDUC period can become out of syncwith the IDUC window. To overcome thisproblem, this property was used toextend the time frame from which journalevents were retrieved from theObjectServer. The time frame only neededto be extended by a few seconds.

Due to improved IDUC processing, thisproperty is no longer required. It remainsin the properties file for backwardcompatibility with configuration files, buthas no effect on operation of the gatewayfrom version 5.0 onwards.

The default is 0.

Gate.JournalTableMap string

-journaltablemap string Use this property to specify the name ofthe map that is used to map journalentries to the specified journal table inthe Oracle database. The map is definedin the map definition file.

The default is OracleJournalMap.




Gate.JournalTableName string

-journaltable string Use this property to specify the name ofthe journal table that the gatewaymonitors for any changes.

The default is alerts.journal.

Gate.LogOSSqlboolean

-logossql boolean Use this property to specify whether thegateway logs all SQL commands sent tothe ObjectServer in debug mode.


Note: To change the value of thisproperty while the gateway is running,use the gateway interactive commandline tool.

Gate.LogStatisticsData boolean

-logstatisticsdataboolean

Use this property to specify whether thegateway writes statistics data to the logfile regardless of the setting of theMessageLevel property.

If the Gate.LogStatisticsData is set toFALSE, the gateway writes statistics datato the log file only when theMessageLevel property is set to debug.


Note: To change the value of thisproperty while the gateway is running,use the gateway interactive commandline tool.

Gate.MapFile string -mapfile string Use this property to specify the locationof the map definition file.

The default is $OMNIHOME/gates/nco_g_oracle/nco_g_oracle.map.

Gate.NetworkTimeout integer

-nettimeout integer Use this property to specify the length, inseconds, of the network timeout forSybase connections to the ObjectServer.

If you set this property to 0, no timeoutis enforced.

If you specify a value greater than 0 incases when gateway connects to afailover ObjectServer pair, you must usethe Gate.ServerBackup property tospecify a backup ObjectServer.

The default is 0.

Gate.NoGatewayWatch boolean

-nogwwatch boolean Use this property to stop the gatewayfrom generating GatewayWatch events.





Gate.OSReconnTimeout integer

-osreconntimeout integer Use this property to specify the time, inseconds, between reconnection pollattempts if the gateway loses theconnection to the ObjectServer.

The default is 30.

Gate.OverLoadPeriod integer

-olperiod integer Use this property to specify the gatewayoverload sample/ period number.

The default is 5.

Note: To change the value of thisproperty while the gateway is running,use the Gateway Interactive CommandLine Tool.

Gate.OverLoadThreshold integer

-olthreshold integer Use this property to specify the overloaddetection threshold for the gateway.

The default is 10.

Note: To change the value of thisproperty while the gateway is running,use the Gateway Interactive CommandLine Tool.

Gate.PropsFilestring

-propsfile string Use this property to specify the locationof the gateway properties file.

The default is $OMNIHOME/gates/nco_g_oracle/nco_g_oracle.props.

Gate.ReaderAfterIDUC string

-readerafteriduc string Use this property to specify the SQLcommand to execute on the sourceObjectServer in relation to the serials inthe current IDUC set. The followingexample shows a sample SQLcommand.’update alerts.status setPassedByGw=1’

The default is " ".

Gate.ReaderFilterstring

-readerfilter string Use this property to specify the filter thatthe gateway uses when it performs IDUCprocessing.

The gateway forwards events to theOracle database only if they match thefilter. Define the filter in the form of the[SQL condition] only, for example ’Class= 1’.

The default is " ".




Gate.ReaderFailbackEnableboolean

-readerfailbackenableboolean

Use this property to specify whether thegateway attempts to fail back to theprimary ObjectServer following anObjectServer failover.


Note: The gateway attempts to fail backwith the frequency specified by theGate.ReaderFailbackCheckTimeoutproperty.

Gate.ReaderFailbackCheckTimeout integer

-readerfailbackchecktimeout integer

Use this property to specify thefrequency, in seconds, with which hegateway attempts to fail back to theprimary ObjectServer following anObjectServer failover.

The default is 30.

Note: The gateway attempts to fail backto the primary ObjectServer only if theGate.ReaderFailbackEnable property isset to TRUE.

Gate.RegionHardLimit integer

-reghardlimit integer Use this property to specify themaximum amount of data, in MB, thatyou want to use for the work arearegions.

The default is 100.

For more information, see “Work areasand limits” on page 38.

Gate.RegionSoftLimit integer

-regsoftlimit integer Use this property to specify the amountof data, in MB, that a work area regionshould store in the memory before itactivates the offline data storage systemand swaps data in and out of the regionto disk-based files.

The default is 20.

For more information, see “Work areasand limits” on page 38.

Gate.RegionSoftLimitInc integer

-regsoftlimitinc integer Use this property to specify the soft limitincrease, in MB, of the work area region.

The default is 1.

For more information, see “Work areasand limits” on page 38.Note: To change the value of thisproperty while the gateway is running,use the Gateway Interactive CommandLine Tool.




Gate.RemoveIncompleteRegFiles boolean

-removeincompleteregionfiles boolean

Use this property to specify whether, onstartup, the gateway removes anyincomplete (and possibly corrupt) regionstorage files that remain from theprevious session.


Gate.ServerBackupstring

-serverbackup string Use this property to specify the name ofa backup ObjectServer for the gateway.

The gateway uses this property if abackup server name needs to be set upmanually, for example, in the failoveroperation of the gateway at the Sybasecommunications layer. If you set theNetworkTimeout property on Sybaseconnections to a value greater than 0, andthe connection times out, the gatewayattempts to connect to this server directly.

The default is " ".

Gate.StartupCmdFile string

-startupcmdfile string Use this property to specify the locationof the startup commands file.

The default is $OMNIHOME/gates/nco_g_oracle/nco_g_oracle.startup.cmd.

Gate.StatisticsPortinteger

-statsport integer Use this property to specify the port towhich the gateway listens for gatewaystatistics output clients.

The default is 4500.

Gate.StatisticsRateinteger

-statsrate integer Use this property to specify the rate, inseconds, at which the gateway collectssample statistics.

The default is 60.

Note: To change the value of thisproperty while the gateway is running,use the Gateway Interactive CommandLine Tool..

Gate.StatusTableMap string

-statustablemap string Use this property to specify the name ofthe map that is used to map statusentries to the specified status table in theOracle database.

The map is defined in the map definitionfile.

The default is OracleStatusMap. Thisvalue is for reporter mode.

Note: If you want to run the gateway inaudit mode, you must set this property toOracleAuditStatusMap.




Gate.StatusTableName string

-statustable string Use this property to specify the name ofthe status table that the gateway monitorsfor any changes.

The default is alerts.status.

Gate.TrustedHostsFile string

-trustedhostfile string Use this property to specify the locationof the trusted hosts definition file.

The default is $OMNIHOME/gates/nco_g_oracle/nco_g_oracle.thosts.

Help boolean -help boolean Use this property to instruct the gatewayto display application help informationon startup and exit.


MessageLevel string -messagelevel string Use this property to specify the reportinglevel of the log file messages.

The default is warn.

For more information about usingmessage log files, see “Message log” onpage 36.

MessageLog string -messagelog string Use this property to specify the path tothe message log file.

The default is $OMNIHOME/log/nco_g_oracle.log.

For more information about usingmessage log files, see “Message log” onpage 36.

Name string -name string Use this property to specify the name ofthe current gateway instance. It definesthe default location of all theconfiguration files and region file. If youwant to run multiple gateways on onemachine, you must use two differentnames.

The default is nco_g_oracle.

Oracle.ActionCodeField string

-oraactcodefield string Use this property to specify whichcolumn accepts the value of theACTION_CODE directive.

The default is ActionCode.

Note: This field is used only when thegateway is operating in audit mode fordelete processing.




Oracle.ActionTimeField string

-oraacttimefield string Use this property to specify whichcolumn accepts the value of theACTION_TIME directive.

The default is ActionTime.

Note: This field is used only when thegateway is operating in audit mode fordelete processing.

Oracle.BatchSizeinteger

-orabatchsize integer Use this property to specify themaximum size, in terms of rows, of asingle batch of data.

The value must be between 10 and 500rows.

The default is 200.

Oracle.DeleteFieldstring

-oradeletefield string Use this property to specify the contentof the alert closure/delete field in thetarget status table.

The default is DELETEDAT.

Note: Use this property only when thegateway is operating in reporter mode.

Oracle.DetailsTableName string

-oradetailstable string Use this property to specify the name ofthe details table in the Oracle database towhich the gateway writes.

The default is details.

Note: If you want to run the gateway inreporter mode, you must change thisproperty to reporter_details.

Oracle.InitializationSQLstring

-orainitsql string Use this property to specify the Oracleconnection initialization SQL thatexecutes immediately after the connectionhas been established.

Use this property to issue the Oracle SQLcommand that enables tracing, or use itto configure the session connections ofthe gateway. The following exampleshows how to set this property to enableOracle tracing:

Oracle.InitializationSQL : "altersession set sql_trace=true"

The default is " ".




Oracle.JournalTableName string

-orajournaltable string Use this property to specify the name ofthe journal table in the Oracle database towhich the gateway writes.

The default is journal.

Note: If you want to run the gateway inreporter mode, you must change thisproperty to reporter.

Oracle.OracleGWType string

-oragwtype string Use this property to specify theoperational mode of the gateway:

reporter: The gateway operates inreporter mode.

audit: The gateway operates in auditmode.

The default is reporter.

Oracle.PartitioningField string

-orapartitioningfieldstring

Use this property to specify thepartitioning field that the gateway uses inthe WHERE clause of updates.

The default is FirstOccurrence.

Note: The Oracle partitioning field isonly used if the Oracle.UsePartitioningproperty is set to TRUE and partitioninghas previously been configured withinthe Oracle database. You can only usethis property when you are running theGateway for Oracle in reporter mode.

Oracle.Passwordstring

-orapassword string Use this property to specify the passwordthat is used to authenticate the Oracledatabase connection.

This password must be encrypted withthe nco_g_crypt utility (in a non-FIPscompliant mode). For details about thisutility, see the IBM TivoliNetcool/OMNIbus Administration Guide.

The default is " ".

You must change the value of thisproperty to the output of nco_g_cryptreporter.

Note: When the gateway is running inFIPS mode, passwords encrypted usingthe nco_g_crypt utility are not allowed.In FIPS mode, the password shouldeither be in plain text or encrypted usingthe nco-aes-crypt utility.




Oracle.ReconnTimeout integer

-orareconntimeoutinteger

Use this property to specify the time (inseconds) between each reconnection pollattempt if the gateway loses theconnection to the Oracle database.

The default is 30.

Oracle.SendTimezoneData boolean

-orasendtimezonedata Use this property to change the wayObjectServer UTC date values areconverted prior to forwarding to Oracle.This is useful when the ObjectServer isrunning in a time zone that differs fromeither the Oracle database or any clientsthat view the data.

TRUE: The dates are converted to OracleTIMESTAMP WITH TIME ZONE data typecolumns in the Oracle schema, replacingthe DATE data type columns.

FALSE: The dates are not converted toOracle TIMESTAMP WITH TIME ZONE datatype columns in the Oracle schema, theyremain as DATE data type columns.


Note: The TIMESTAMP WITH TIME ZONEdata type is not compatible withNetcool/Reporter.

For additional information, see“Specifying the time zone associated withevents” on page 31.

Oracle.SerialFieldstring

-oraserialfield string Use this property to specify whichcolumn accepts the Serial value of analert.

If the serial number is not stored in thetarget table, setting this property value toNA instructs the gateway that the serialnumber is not available. The gatewaysubsequently does not attempt topopulate this field in the deleteprocessing code

The default is Serial.

Note: This required field is only usedwhen the gateway is operating in auditmode.




Oracle.ServerNameField string

-oraservnamefield string Use this property to specify differentthings depending on the mode in whichyou are running the gateway.

In reporter mode, this property specifiesthe name of the column that receives theServerName value of an alerts. This fieldmust be known explicitly for the WHEREcondition on update operations.

In audit mode, this property is used fordelete processing.

The default is ServerName.

Note: This property is required.

Oracle.ServerSerialField string

-oraservserialfieldstring

Use this property to specify differentthings depending on the mode in whichyou are running the gateway.

In reporter mode, this property specifiesthe name of the column that receives theServerSerial value of an alerts. This fieldmust be known explicitly for the WHEREcondition on update operations.

In audit mode, this property is used fordelete processing.

The default is ServerSerial.

Note: This property is required.

Oracle.SetDeletedAtToNull boolean

-orasetdeletedattonullboolean

Use this property to specify whether thegateway sets the DeletedAt field in theOracle database to NULL if it receives anupdate to an event that has already beendeleted:

FALSE: If the gateway receives an updateto an event that has already been deleted,the gateway does not update theDeletedAt field. The field remains set tothe date at which the event was deleted.

TRUE: If the gateway receives an update toan event that has already been deleted,the gateway sets the DeletedAt field toNULL.


Note: The gateway can receive updatesto deleted events if an ObjectServerresynchronization has been performed.During resynchronization, the masterObjectServer deletes all events in theslave ObjectServer and then reinsertsthem.




Oracle.StatusTableName string

-orastatustable string Use this property to specify the name ofthe status table in the Oracle database towhich the gateway writes.

The default is status.

Note: If you run the gateway in reportmode, you must change this property toreporter_status.

Oracle.UsePartitioning boolean

-orausepartitioning Use this property to specify whether thegateway uses the Oracle partitioningfunctionality. You can only use thisproperty when you are running theGateway for Oracle in reporter mode.

FALSE: The gateway does not use theOracle partitioning functionality.

TRUE: The gateway will use the Oraclepartitioning functionality if partitioninghas previously been configured withinthe Oracle database.


Note: If you set this property to TRUE, thegateway uses the field specified by theOracle.PartitioningField property inthe WHERE clause of updates. Oraclepartitioning improves the efficiency ofupdate processing.

Oracle.UserNamestring

-orausername string Use this property to specify the username that is used to authenticate thedatabase connection.

The default is username.

Note: You must change the value of thisproperty to oracle_user@sid whereoracle_user is the name of the Oracle user.

Props.CheckNamesboolean

none Use this property to instruct the gatewayto abort if any property in the propertiesfile is set to an invalid value.


Region.ProtectAllboolean

none Use this property to specify whether allwork regions are write-protected.





Sec.Password string -secpassword string Use this property to specify the passwordthat is associated with the user name thatis used to authenticate the ObjectServerconnection.

The default is " ".

Note:

This password MUST be encrypted bythe nco_g_crypt utility. For details aboutthis utility, see Netcool/OMNIbusAdministration Guide. Plain textpasswords are not accepted because thegateway assumes that all passwords areencrypted by this tool for security.

For the gateway to run, this propertymust be set, regardless of whether theObjectServer is running in secure mode.Note: When the gateway is running inFIPS mode, passwords encrypted usingthe nco_g_crypt utility are not allowed.In FIPS mode, the password shouldeither be in plain text or encrypted usingthe nco-aes-crypt utility.

Sec.UserName string -secusername string Use this property to specify the username that is used to authenticate theObjectServer connection.

The default is username.

Note: This user name is used to establishboth the IDUC connection of the readerand the subsidiary SQL commandconnection.

For the gateway to run, this propertymust be set, regardless of whether theObjectServer is running in secure mode.

Server string -server string Use this property to specify the name ofthe ObjectServer to which the gatewayconnects.

The default is NCOMS.

Version boolean -version boolean Use this property to instruct the gatewayto display information about theapplication version on startup and exit.


Audit and reporter mode propertiesTo run the gateway in reporter or audit mode, you must make settings in thegateway properties file.


Property settings for reporter mode

You use properties to specify how the gateway operates in reporter mode. You canoverride the default values by using the properties file.

The following table describes that property settings that you must make to run thegateway in reporter mode.

Table 8. Property settings for reporter mode

Property Setting Description

Oracle.OracleGWType REPORTER REPORTER is the defaultsetting for this property.

Gate.StatusTableMap OracleStatusMap OracleStatusMap is thedefault setting for thisproperty.

Oracle.DetailsTableName reporter_details You must change thisproperty toreporter_details.

Oracle.StatusTableName reporter_status You must change thisproperty to reporter_status.

Oracle.JournalTableName reporter_journal You must change thisproperty toreporter_journal.

Property settings for audit mode

You use properties to specify how the gateway operates in audit mode. You canoverride the default values by using the properties file.

The following table describes that property settings that you must make to run thegateway in audit mode.

Table 9. Property settings for audit mode

Property Setting Description

Oracle.OracleGWType AUDIT You must change thisproperty to AUDIT.

Gate.StatusTableMap OracleAuditStatusMap You must change thisproperty toOracleAuditStatusMap.

Specifying the alerts tables that the gateway monitorsYou can configure the names of the Status, Journal, and Details tables within theObjectServer so that any changes made to these specified tables are monitored bythe gateway.

Use the following properties to specify the name of the Status, Journal, and Detailstables respectively:v Gate.StatusTableName. The default name of this table is alerts.status.v Gate.JournalTableName. The default name of this table is alerts.journal.v Gate.DetailsTableName. The default name of this table is alerts.details.


Specifying the time zone associated with eventsIf the ObjectServer is running in a time zone that differs from either the Oracledatabase or any clients that view the data, the ObjectServer UTC values can beconverted to an Oracle date/time value which contains the associated time zone ofthe local host that the gateway is running on.

You do this by setting the Oracle.SendTimezoneData property to TRUE. TheObjectServer UTC values are then converted to Oracle TIMESTAMP WITH TIME ZONEdata type columns in the Oracle schema, replacing the DATE data type columns.The Oracle dates are then supplemented with the local host's time zone value. Thetime zone value is stored in either the ORACLE_GW_TZ environment variable or theoperating system's TZ environment variable.

Note: The Oracle schema must contain the TIMESTAMP WITH TIME ZONE data typesand not the DATE data types. The TIMESTAMP WITH TIME ZONE data type is notcompatible with Netcool/Reporter.

Map definition fileThe Gateway for Oracle writes to the three tables in the Oracle database: Status,Journal, and Details.

To do this, the gateway maps data to the appropriate fields in the Oracle database.The map definition file contains mappings that define how the gateway maps thisdata. The names for these mappings are determined by the OracleStatusMap,OracleJournalMap, and OracleDetailsMap properties in the properties file.

The default map definition file is:v $OMNIHOME/gates/nco_g_oracle/nco_g_oracle.map for UNIX operating systemsv %OMNIHOME%\gates\nco_g_oracle\nco_g_oracle.map for Windows operating

systems

Attention: The gateway uses the cached values of the ServerName andServerSerial attributes in the ObjectServer for updates and deletes instead ofgetting the mapped values from the Oracle database. Do not update theServerName and ServerSerial values in the default nco_g_oracle.map file suppliedwith the gateway.

Syntax

Mappings for use with the Gateway for Oracle must use the following syntax:CREATE MAPPING mappingname('OracleFieldName’ = [ ’@fieldname’ | gateway_named_attribute |simple_expression ] [ CONVERT TO type ][ , OracleFieldName = [ ’@fieldname’ | gateway_named_attribute |simple_expression ] [ON INSERT ONLY] [ CONVERT TO type ]][NOTNULL, ’@defaultfield’]...) ;

Where:v mappingname is the name of the mapping to be created.v OracleFieldName is the field name for the field to be written to in the Oracle

database.v fieldname is the name of a field in the ObjectServer alerts.status table.


v defaultfield is the name of a field in the ObjectServer alerts.status table youwant to use as a default value for a different field.

v gateway_named_attribute is one of the following attributes:– ACTION_CODE– ACTION_TIME– SERIAL– SERVER_SERIAL– SERVER_NAME– IDENTIFIER– DELETEDAT

v simple_expression expressed in Backus-Naur Form (BNF) notation is as follows:<map_expr> ::= <map_value> | <map_expr> <operator> <map_value><map_value> ::= @fieldname | static_value | gateway_named_attribute<operator> ::= + | - | / | *

Note: The only valid operator for strings is + (concatenation).

The following topics show examples mappings for running the gateway in reporteror audit mode:

Example mappings - reporter modeThis example shows the Oracle database mappings in the reporter mode.

The following example shows the mappings for the tables in the Oracle databaseto which the gateway writes when running in reporter mode:## The following maps can be used when the gateway is run in REPORTER mode# and the example TRANSFER commands in the default nco_g_oracle.startup.cmd# are required - and uncommented.#

CREATE MAPPING OracleNamesMap(

’Name’ = ’@Name’,’OwnerUID’ = ’@UID’,’OwnerGID’ = ’@GID’,’Password’ = ’@Passwd’,’Type’ = ’@Type’

);

CREATE MAPPING OracleGroupsMap(

’Name’ = ’@Name’,’OwnerGID’ = ’@GID’

);

CREATE MAPPING OracleMembersMap(

’OwnerKey’ = TO_STRING(’@UID’) + TO_STRING(’@GID’),’OwnerUID’ = ’@UID’,’OwnerGID’ = ’@GID’

);

CREATE MAPPING OracleConversionsMap(

’Conversion_Key’ = ’@KeyField’,’Column_Name’ = ’@Colname’,’Value’ = ’@Value’,’Conversion’ = ’@Conversion’


);

CREATE MAPPING OracleObjectClassesMap(

’Class’ = ’@Tag’,’Name’ = ’@Name’,’Icon’ = ’@Icon’,’Menu’ = ’@Menu’

);

Example mappings - audit modeThis example shows the mappings for the gateway when running in audit mode.

The following example shows the mapping for the tables in the Oracle database towhich the gateway writes when running in audit mode:## Example Oracle configuration for the Netcool/OMNIbus Gateway Server 3.6##CREATE MAPPING OracleStatusMap(’Identifier’ = ’@Identifier’ ON INSERT ONLY,’Serial’ = ’@Serial’ ON INSERT ONLY,’Node’ = ’@Node’ ON INSERT ONLY,’NodeAlias’ = ’@NodeAlias’ ON INSERT ONLY NOTNULL ’@Node’,’Manager’ = ’@Manager’ ON INSERT ONLY,’Agent’ = ’@Agent’ ON INSERT ONLY,’AlertGroup’ = ’@AlertGroup’ ON INSERT ONLY,’AlertKey’ = ’@AlertKey’ ON INSERT ONLY,’Summary’ = ’@Summary’,’Location’ = ’@Location’ ON INSERT ONLY,’Class’ = ’@Class’ ON INSERT ONLY,’Poll’ = ’@Poll’ ON INSERT ONLY,’Type’ = ’@Type’ ON INSERT ONLY,’Tally’ = ’@Tally’,’Severity’ = ’@Severity’,’OwnerUID’ = ’@OwnerUID’,’OwnerGID’ = ’@OwnerGID’,’Acknowledged’ = ’@Acknowledged’,’LastModified’ = ’@StateChange’ CONVERT TO DATE,’FirstOccurrence’ = ’@FirstOccurrence’ ON INSERT ONLY CONVERT TO DATE,’LastOccurrence’ = ’@LastOccurrence’ CONVERT TO DATE,’OriginalSeverity’ = ’@Severity’ ON INSERT ONLY,

# NB do not concatenate additional values for ServerName and ServerSerial !’ServerName’ = ’@ServerName’,’ServerSerial’ = ’@ServerSerial’);

CREATE MAPPING OracleAuditStatusMap(’ActionTime’ = ACTION_TIME CONVERT TO DATE,’ActionCode’ = ACTION_CODE,’Identifier’ = ’@Identifier’ ON INSERT ONLY,’Serial’ = ’@Serial’ ON INSERT ONLY,’Node’ = ’@Node’ ON INSERT ONLY,’NodeAlias’ = ’@NodeAlias’ ON INSERT ONLY NOTNULL ’@Node’,’Manager’ = ’@Manager’ ON INSERT ONLY,’Agent’ = ’@Agent’ ON INSERT ONLY,’AlertGroup’ = ’@AlertGroup’ ON INSERT ONLY,’AlertKey’ = ’@AlertKey’ ON INSERT ONLY,’Severity’ = ’@Severity’,’Summary’ = ’@Summary’,’StateChange’ = ’@StateChange’ CONVERT TO DATE,’FirstOccurrence’ = ’@FirstOccurrence’ ON INSERT ONLY CONVERT TO DATE,’LastOccurrence’ = ’@LastOccurrence’ CONVERT TO DATE,


’InternalLast’ = ’@InternalLast’ CONVERT TO DATE,’Poll’ = ’@Poll’ ON INSERT ONLY,’Type’ = ’@Type’ ON INSERT ONLY,’Tally’ = ’@Tally’,’Class’ = ’@Class’ ON INSERT ONLY,’Grade’ = ’@Grade’ ON INSERT ONLY,’Location’ = ’@Location’ ON INSERT ONLY,’OwnerUID’ = ’@OwnerUID’,’OwnerGID’ = ’@OwnerGID’,’Acknowledged’ = ’@Acknowledged’,’Flash’ = ’@Flash’ ON INSERT ONLY,

’EventId’ = ’@EventId’,’ExpireTime’ = ’@ExpireTime’,’ProcessReq’ = ’@ProcessReq’,’SuppressEscl’ = ’@SuppressEscl’,’Customer’ = ’@Customer’,’Service’ = ’@Service’,’PhysicalSlot’ = ’@PhysicalSlot’,’PhysicalPort’ = ’@PhysicalPort’,’PhysicalCard’ = ’@PhysicalCard’,’TaskList’ = ’@TaskList’,

’NmosSerial’ = ’@NmosSerial’,’NmosObjInst’ = ’@NmosObjInst’,’NmosCauseType’ = ’@NmosCauseType’,

’LocalNodeAlias’ = ’@LocalNodeAlias’,’LocalPriObj’ = ’@LocalPriObj’,’LocalSecObj’ = ’@LocalSecObj’,’LocalRootObj’ = ’@LocalRootObj’,’RemoteNodeAlias’ = ’@RemoteNodeAlias’,’RemotePriObj’ = ’@RemotePriObj’,’RemoteSecObj’ = ’@RemoteSecObj’,’RemoteRootObj’ = ’@RemoteRootObj’,

’X733EventType’ = ’@X733EventType’,’X733ProbableCause’ = ’@X733ProbableCause’,’X733SpecificProb’ = ’@X733SpecificProb’,’X733CorrNotif’ = ’@X733CorrNotif’,

# NB do not concatenate additional values for ServerName and ServerSerial !’ServerName’ = ’@ServerName’,’ServerSerial’ = ’@ServerSerial’);

CREATE MAPPING OracleJournalMap(’Serial’ = ’@Serial’,’Chrono’ = ’@Chrono’ CONVERT TO DATE,’UserID’ = ’@UID’,’Text1’ = ’@Text1’,’Text2’ = ’@Text2’,’Text3’ = ’@Text3’,’Text4’ = ’@Text4’,’Text5’ = ’@Text5’,’Text6’ = ’@Text6’,’Text7’ = ’@Text7’,’Text8’ = ’@Text8’,’Text9’ = ’@Text9’,’Text10’ = ’@Text10’,’Text11’ = ’@Text11’,’Text12’ = ’@Text12’,’Text13’ = ’@Text13’,’Text14’ = ’@Text14’,’Text15’ = ’@Text15’,’Text16’ = ’@Text16’,


# NB do not concatenate additional values for ServerName and ServerSerial !’ServerName’ = SERVER_NAME,’ServerSerial’ = SERVER_SERIAL);

CREATE MAPPING OracleDetailsMap(’Identifier’ = ’@Identifier’,’AttrVal’ = ’@AttrVal’,’Sequence’ = ’@Sequence’,’Name’ = ’@Name’,’Detail’ = ’@Detail’,# NB do not concatenate additional values for ServerName and ServerSerial !’ServerName’ = SERVER_NAME,’ServerSerial’ = SERVER_SERIAL);

Startup command fileThe startup command file contains a set of commands that the gateway executeseach time it starts. These commands allow the gateway to transfer any subsidiarytable data to a set of target tables.

You can use the following commands within the startup command file:v GET CONFIG

v SET LOG LEVEL TO

v TRANSFER

You can also issue these commands manually when the gateway is running usingthe interactive gateway command line tool.

The default startup command file is: $OMNIHOME/gates/gateway_name/gateway_name.startup.cmd

Example startup commands

This is an example of the startup commands file.

The following example shows how to use the commands from the startupcommand file.GET CONFIG;SET LOG LEVEL TO debug;TRANSFER FROM ’master.names’ TO ’reporter_users’ VIA FILTER ’Name != \’nobody\’’USING TRANSFER_MAP OracleUsersMap;#TRANSFER FROM ’master.names’ TO ’reporter_users’

VIA FILTER ’Name != \’nobody\’’USING TRANSFER_MAP OracleUsersMap;

#TRANSFER FROM ’master.names’ TO ’reporter_users’

VIA FILTER ’Name != \’nobody\’’ DELETEUSING TRANSFER_MAP OracleUsersMap;

TRANSFER FROM ’alerts.conversions’ TO ’reporter_conversions’ DELETE;

TRANSFER FROM ’alerts.conversions’ TO ’audit_conversions’VIA FILTER ’Colname != \’Severity\’’WITH DELETE VIA ’Column_Name <> \’Severity\’’USING TRANSFER_MAP OracleAuditConvMap;

TRANSFER ’master.names’ FROM writer1 TO writer2 AS ’reporter_users’USE TRANSFER_MAP wibble;


Trusted hosts definition fileThe Gateway for Oracle provides remote access to both its statistics and datatransfer operations data; it uses the trusted hosts definition file to determine whichhosts are allowed to access its ports.

The gateway has two ports to which hosts can connect: the statistics port and theinteractive command port. The trusted hosts definition file is a text file that lists allhosts that have authority to access the ports. If a host that is not included in thetrusted hosts file attempts to connect to the statistics port of the gateway, thegateway sends a GatewayWatch message to the ObjectServer.

The default trusted hosts definition file is: $OMNIHOME/gates/gateway_name/gateway_name.thosts.

Note: The statistics port is defined by the Gate.StatisticsPort property and theinteractive port is defined by the Gate.GatewayCommandPort property.

Syntax

Each line in the trusted hosts file contains the name of a host machine written ineither dotted quad format (for example, 192.131.93.3) or in human-readable hostname format (for example, darkstar.example.com). Each line takes one of thefollowing formats:v Dotted quad

nnn.nnn.nnn.nnn # Explicit IP addressnnn.nnn.[nnn-nnn].[nnn-nnn] # AnyIP address within the given rangennn.nnn.nnn.* # Any host in the given subnet

v Human-readableaname.name.name # Explicit host namename.name.* # The given host name within any domain*.name.name # Any host name within a given domain

Example trusted host definition file

The following example shows trusted hosts definitions:192.131.98.151192.131.97.*192.168.[10-25].[45-255]muse.darkstar.example.comdarkstar.*darkstar.example.com

Message logThe gateway creates a message log file to store all messages that it generates whilerunning. You can use the properties file and environment variables to specify thename and maximum size of the message log file.

You can use the MessageLog property to specify a name for the message log file.The default log file nco_g_oracle.log is located in the following directory:

$OMNIHOME/log

You can specify the maximum size of the log file using the NDE_LOGFILE_MAXSIZEenvironment variable. The default is 1024 KB. When the log file reaches thespecified maximum size, the ObjectServer archives it using the extension .log_old


and starts a new log file with the extension .log. When the new log file reachesthe maximum size, it is archived in turn and overwrites the first archived log file.

You can specify the level of message logging using the MessageLevel property. Thedefault is warn. The default logging level is sufficient to identify most configurationproblems. If you require more information about how the gateway is running, setthe MessageLevel property to debug. This option produces a lot of detailed output,resulting in large log files.

Log file environment variables

You can control the log file size and log file rotation using the followingenvironment variables:v NDE_LOGFILE_MAXSIZE sets the maximum log file size.

The following example sets the maximum log file size to 1024000 bytes (1024KB):setenv NDE_LOGFILE_MAXSIZE 1024000

v NDE_LOGFILE_ROTATION_FORMAT enforces daily log file rotation, regardless of themaximum log file size specified by NDE_LOGFILE_MAXSIZE. It also specifies theformat of the archived log file name.You can use one of the following types of parameter to set this variable: anyliteral string (for example, rotation), a POSIX timestamp format, or a UnicodeLocale Data Markup Language (LDML) timestamp format. The literal string orthe timestamp is appended to the archived log file, for example,nco_g_odbc.log_rotation.The following commands enable daily log file rotation:

Parameter Command

Literal string setenv NDE_LOGFILE_ROTATION_FORMAT \’literal_string\’

POSIXtimestamp

setenv NDE_LOGFILE_ROTATION_FORMAT %Y%m%d-%H%M

LDMLtimestamp

setenv NDE_LOGFILE_ROTATION_FORMAT yyyyMMdd-HHmm

v NDE_LOGFILE_ROTATION_TIME specifies the time at which log file rotation occurseach day.The following example causes the log file to be rotated at 00:00 hours each day:setenv NDE_LOGFILE_ROTATION_TIME 0000

For more information about using log file environment variables, see the IBM TivoliNetcool/OMNIbus Installation and Deployment Guide.

Partitioning Oracle tablesIf a single column partitioning scheme has been implemented within the Oracletarget schema, the Gateway for Oracle can be configured to make use of thispartitioning for more efficient SQL updates.

You can define an additional table column (for example, FirstOccurrence) which isthen used to restrict the part of the database that Oracle searches, rather thansearching the whole database. The gateway will use this partitioning field in theWHERE clause of updates. To specify that the gateway uses Oracle partitioning, setthe Oracle.UsePartitioning property to TRUE. To define the Oracle partitioningfield, use the Oracle.PartitioningField property.


Note: You can only use Oracle partitioning when you are running the gateway inreporter mode. See “Audit mode and reporter mode” on page 4.

Work areas and limitsWork areas are memory storage areas reserved in swap space. Hard and soft limitsdefine the amount of memory the work area region can consume.

Work areas are allocated when the gateway starts. The gateway uses the followingwork areas to perform its operations:v status_ins_workarea

v status_upd_workarea

v status_del_workarea

v journal_ins_workarea

v details_ins_workarea

v misc_workarea

Each work area uses five files: two checkpoint files, two log files, and one tab file.If the gateway is run in debug mode, the log file is populated with the varioustasks that are performed by each of these work areas.

The soft limit is the amount of memory, in MB, that can be used for work areas. Itdefines the first memory management point of the work area region. When thispoint is reached, data must be swapped out and stored on disk. If the soft limit isset too low, gateway performance might suffer. Use the Gate.RegionSoftLimitproperty to define the point at which the gateway should begin to conservememory and use disk-based storage.

With the use of large batches and data sets, the gateway can start to use diskstorage too early. This can result in poor performance due to the swapping of datato and from disk storage. If the soft limit of the region has been reached, and theminimum allocation of the batch element can not be allocated within the region,the soft limit can be increased. This will ensure that the batch element can beallocated. Use the Gate.RegionSoftLimitInc property to define the amount ofadditional swap space that should be allocated to the soft limit. The increased softlimit cannot exceed the hard limit.

The hard limit is the maximum amount of memory reserved in swap space for asingle work region. This is an upper bound that cannot be exceeded. If the hardlimit is set too high, the gateway may not start. Use the Gate.RegionHardLimitproperty to define the hard limit.

Estimating hard and soft limits

You can estimate the hard and soft work area limits required for your installationby analyzing event throughput. This is the amount of data the gateway handlesunder normal loading, within expected maximum limits and system limitations.You can collect this information by setting the Gate.LogStatisticsData property toTRUE in the properties file. This will write gateway statistics, including disk usage,to the gateway log file.

Note: To change the value of the Gate.LogStatisticsData property while thegateway is running, use the gateway interactive command line tool.


From the actual disk and memory usage, you can estimate the amounts of memoryto reserve for the work areas according to the following formulas:v Maximum disk space usage = 6*5*RegionHardLimitv Maximum memory usage = 6*RegionSoftLimit

where 6 is the number of work areas and 5 is the number of files per area.

The following rules can then be used for calculating the limits:v RegionSoftLimitInc*n = RegionSoftLimitv RegionSoftLimit*m = RegionHardLimit

where n and m are integers.

The hard and soft limit property settings should adhere to a ratio setting whereRegionHardLimit : RegionSoftLimit : RegionSoftLimitInc.

Recommended property settings

The recommended property settings for most UNIX and Linux operating systemsare as follows:v Gate.RegionHardLimit = 400 MBv Gate.RegionSoftLimit = 200 MBv Gate.RegionSoftLimitInc = 50 MB

Applying these values to the formulas above gives the following result:v Maximum disk space usage = 6*5*(RegionHardLimit=400) = 12,000 MBv Maximum memory usage = 6*(RegionSoftLimit=50) = 300 MB

The recommended property settings for Windows and HP-UX operating systemsare as follows:v Gate.RegionHardLimit = 80 MBv Gate.RegionSoftLimit = 40 MBv Gate.RegionSoftLimitInc = 20 MB

Gateway interactive command line toolThe gateway interactive command line tool (GICMD) provides you with a set ofcommand line options for changing the properties of the gateway while it isrunning.

The GICMD tool is provided separately from the gateway installation package andis available from the IBM Passport Advantage Online website:http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm.

The following table lists the available GICMD binary file and properties files.

Table 10. Summary of GICMD files

Binary nco_g_icmd

Properties files /gates/nco_g_icmd/nco_g_icmd.props

/gates/nco_g_icmd/cfg_examples/nco_g_icmd.props

The GICMD tool is further described in the following topics:




v “Using the GICMD tool”v “Authentication”v “GICMD properties file” on page 41v “GICMD commands” on page 41

Using the GICMD toolYou can send commands to the gateway using the gateway interactive command(GICMD) tool. This tool is supplied as a separate patch, and complements thefunctionality of the gateway. GICMD allows you to use a set of command lineoptions to change the properties of the gateway while it is running.

You can start the gateway interactive command tool (GICMD) using thenco_g_icmd command.

The tool is located in the following directory:v $OMNIHOME/bin on UNIX and Linux operating systemsv %OMNIHOME%\bin on Windows operating systems

The following table describes the command line options for nco_g_icmd. You canalso use any of these commands in the startup command file.

Table 11. GICMD command line options

Option Description

-help Use this command line option to display help informationabout the command line options.

-name string Use this command line option to specify the name of theclient application. This name defines the default name of theproperties file that the command line tool attempts to loadon when it starts.

-version Use this command line option to display versioninformation.

-hostname string Use this command line option to display the hostname or IPaddress of the machine that is running the gateway to whichyou want to connect.

-username string Use this command line option to display the IBM TivoliNetcool/OMNIbus user name that is used to connect to thegateway.

-password string Use this command line option to display the password ofthe user name with which you want to connect to thegateway.

-noheaders boolean Use this command line option to specify whether theGICMD tool displays any headers when it runs and displayssets of results.

-propsfile string Use this command line option to display the path to theproperties file.

-cmdport integer Use this command line option to display the port numberthat the gateway uses for its interactive command interface.

AuthenticationThe gateway authenticates the connecting user with the ObjectServer to which it isconnected.


Note: If the gateway is working in the FIPS mode, then the authentication againstthe ObjectServer is disabled, and only local (PAM) or NIS authentication isallowed.

If the ObjectServer user has a system (NIS) password, the gateway attempts to lookup that user's system password. If the gateway does not have sufficient privilegesand/or access to perform this task, the user is denied access. This tool requires aNetcool® login.

Note: If shadow encryption is not enabled on HP-UX 11, NIS authenticationcannot be used by nco_g_icmd.

GICMD properties fileThe gateway command line tool refers to a properties file that allows you tospecify the default gateway login details.

Each of the command line arguments of the GICMD tool has a correspondingproperty within this properties file. The default location of this file in the followingdirectory:

$OMNIHOME/gates/nco_g_icmd/nco_g_icmd.props

The following table shows the properties that are available for inclusion in thenco_g_icmd.props file and their default values.

Table 12. GICMD properties

Property Default value

Gate.CmdPort 4600

Gate.Hostname localhost

Headers TRUE

Help FALSE

Name nco_g_icmd

Password " "

Props.CheckNames TRUE

PropsFile $OMNIHOME/gates/nco_g_icmd/cfg_examples

UserName The user name that was used to log on.

Version FALSE

GICMD commandsThe GICMD tool supports various commands that you use to control the behaviorof the gateway during normal runtime.

The commands can also be included when you start the gateway.

The gateway interactive command line tool supports the following commands:v GET CONFIG

v SET LOG LEVEL TO

v TRANSFER

v ALTER

v ALTER STATISTICS COUNTERS RESET


GET CONFIGReturns the current configuration of the gateway in terms of the value of all of itsknown properties.

Syntax_______________________________________________________________________

GET CONFIG;__________________________________________________________________________

Sample___________________________________________________________________________

GET CONFIG;

go________________________________________________________________________

SET LOG LEVEL TOUse the SET LOG LEVEL TO to change the level of the gateway to the specifiedsetting.

Syntax___________________________________________________________________________

SET LOG LEVEL TO level;

Where level takes one of the following values:

debug

information

warning

error

fatal__________________________________________________________________________

Sample___________________________________________________________________________

SET LOG LEVEL TO debug;

go____________________________________________________________________________

TRANSFERInitiates a data transfer operation from the specified table in the ObjectServer tothe specified table in the Oracle database.

Syntax

You can transfer a partial data set using a filter condition. If the target table in theOracle database does not match the source table, a map can be specified as part ofthe transfer operation. This map must be defined within the gateway's mapdefinition file. For details about the map definition file, see “Map definition file”on page 31.


Note: The TRANSFER command is designed to be used with simple mappings thatreference only ObjectServer fields, such as @Identifier. It will not handle gatewaycache entries, such as SERVER_NAME.TRANSFER FROM sourcetable TO targettable[VIA FILTER filtertext] [WITH DELETE VIA delfiltertext][USING TRANSFER_MAP mapname] ;

Example

The following examples shows different options for using the TRANSFER command.# 1) Transfer the table from table master.names to the Oracle table# reporter_users using the filter condition ’Name != ’nobody’ and the map# OracleUsersMap.TRANSFER FROM ’master.names’ TO ’reporter_users’

VIA FILTER ’Name != \’nobody\’’USING TRANSFER_MAP OracleUsersMap;

go# 2) This is the same as example 1, but forces a deletion of any existing# data in the target table reporter_users that matches the source filter.# The delete operation is performed with the same filter condition used# to fetch the source data with. This means that all columns within the# source exist in the target with the same name.TRANSFER FROM ’master.names’ TO ’reporter_users’

VIA FILTER ’Name != \’nobody\’’ DELETEUSING TRANSFER_MAP OracleUsersMap;

go# 3) Transfer the data from the source table alerts.conversions to the# target table reporter_conversions. Delete all data in the target# table before the transfer.TRANSFER FROM ’alerts.conversions’ TO ’reporter_conversions’ DELETEUSING TRANSFER_MAP OracleUsersMap;

go4) Transfer the data from the source table alerts.conversions to the# target table audit_conversions. Use the filter condition# "Colname != ’Severity’" to select the required data. Delete the data# in the target table via the filter "Column_Name <> \’Severity’".# This capability overcomes the need for the source and target tables# to have columns with the same name.TRANSFER FROM ’alerts.conversions’ TO ’audit_conversions’

VIA FILTER ’Colname != \’Severity\’’WITH DELETE VIA ’Column_Name <> \’Severity\’’USING TRANSFER_MAP OracleAuditConvMap;

go

ALTERUse the ALTER command to modify the value of the specified property, or reset theproperty to its default value while the gateway is running.

Syntax

In the following syntax example, new_value is a valid value for the propertyspecified. If an invalid value is specified for the property, an error message isdisplayed on the GICMD console and an error message sent to the log file.

Note: The Gate.RegionSoftLimit and Gate.RegionHardLimit properties cannot bemodified or reset using the ALTER command because their values cannot bechanged while the gateway is running.ALTER property TO new_value;

ALTER property RESET;

Where property takes one of the following values:


v Gate.LogOSSql

v Gate.OverLoadPeriod

v Gate.OverLoadThreshold

v Gate.RegionSoftLimitInc

v Gate.LogStatisticsData

v Gate.StatisticsRate

ExampleALTER Gate.LogStatisticsData TO TRUE;go

ALTER Gate.StatisticsRate RESET;go

ALTER STATISTICS COUNTERS RESETUse the ALTER STATISTICS COUNTERS RESET command to reset the statistics counterwhile the gateway is running.

This command sets the number of elements in the reader to the difference betweenthe number of elements read and the number of elements written.

SyntaxALTER STATISTICS COUNTERS RESET;

ExampleALTER STATISTICS COUNTERS RESET;go

StatisticsThe Gateway for Oracle generates a set of statistics that you use to monitor theperformance of the gateway.

These statistics are maintained by each individual thread; the statistics are thencollected by the statistics calculation system at time intervals specified by theGate.StatisticsRate property. The time window between the intervals is referredto as a statistics calculation window. This means that the statistics data presentedat each statistics interval is a snapshot of the current gateway operation.

Reader statistics

The Gateway for Oracle generates a set of reader statistics that help to monitor theperformance of the gateway.

The following table describes the reader statistics that are generated by thegateway.

Table 13. Reader statistics

Value Title Description

1 Batches produced This statistic shows the number of unique individualbatches that has been prepared by the reader and sentto all writers.

2 Status insertsproduced

This statistic shows the number of insert items passedto the Status table insert writer.


Table 13. Reader statistics (continued)


3 Status updatesproduced

This statistic shows the number of update items passedto the Status table update writer.

4 Status deletesproduced

This statistic shows the number of delete items passedto the Status table delete writer.

5 Journal insertsproduced

This statistic shows the number of journal items passedto the Journal table insert writer.

6 Details insertsproduced

This statistic shows the number of details items passedto the Details table insert writer.

7 Data receive rate This statistic shows the average event rate per second.An event is defined by the reader to be anyinsert/update/delete SQL action constructed andprepared by the reader and sent to one of the writers.Its value defines the average data rate for the currentstatistics calculation period. If the statistics period is 60seconds and 60 events were prepared the averagereceive rate for the period is one event a second, even ifall of the data was prepared in just one of the secondsin the period.

Writer statistics

The Gateway for Oracle generates a set of writer statistics that help to monitor theperformance of the gateway.

The following table describes the writer statistics that are generated by thegateway.

Table 14. Writer statistics


1 Batches sent This statistic shows the number of unique individualbatches that have been received from the reader andapplied to the target table within the Oracle database.

2 Status inserts sent This statistic shows the number of rows received fromthe reader and successfully inserted into the targetStatus table.

3 Status inserts errors This statistic shows the number of rows received fromthe reader that failed to be inserted in to the targetStatus table.

4 Status updates sent This statistic shows the number of updates receivedfrom the reader and successfully applied to the targetStatus table.

5 Status updates errors This statistic shows the number of updates receivedfrom the reader that could not be applied to the targetStatus table. In reporter mode, this figure will alsoreflect the number of updates that were successfullyapplied, but did not effect any rows in the target table.

6 Status deletes sent This statistic shows the number of deletion updatesreceived from the reader and successfully applied to thetarget Status table.


Table 14. Writer statistics (continued)


7 Status deletes errors This statistic shows the number of deletion updatesreceived from the reader that could not be applied tothe target Status table. In reporter mode, this figure willalso reflect the number of updates that weresuccessfully applied, but did not affect any rows in thetarget table.

8 Journal inserts sent This statistic shows the number of journal insertsreceived from the reader and successfully inserted intothe target Journal table.

9 Journal inserts errors This statistic shows the number of journal insertsreceived from the reader which could not be insertedinto the target Journal table.

10 Details inserts sent This statistic shows the number of detail insertsreceived from the reader and successfully inserted intothe target Details table.

11 Details inserts errors This statistic shows the number of detail insertsreceived from the reader that could not be inserted intothe target Details table.

12 Data send rate This statistic provides the average event rate a second.An event is defined by the writer to be an individualinsert/update/delete SQL action received in a batchfrom the reader. Its value defines the average data sendrate for the current statistics calculation period. If thestatistics period is 60 seconds and 60 events are sent tothe Oracle database, the average send rate for theperiod is one event a second, even if all of the data wassent in just one of the seconds of the period.

General gateway statistics

The Gateway for Oracle generates some general statistics that help to monitor theperformance of the gateway.

The following table describes general gateway statistics.

Table 15. General gaeway statistics


1 Overload Value This statistic shows the amount of data that has yet tobe sent to the Oracle database expressed as a percentageof all data requiring sending. This is effectively ameasure of the gateway’s backlog. This figure iscalculated as an average over five statistic periods.

Error messagesError messages provide information about problems that have occurred during theoperations of the gateway. You can use the information that they contain to resolvesuch problems.

The following table describes the error messages that the Gateway for Oraclegenerates.


Table 16. Error messages

Error Description Action

Tried to insertnon-string data in thefield field_name

Tried to insertnon-integer data in thefield field_name

After the conversions wereapplied, the map attempted toput data of an incompatibletype in a field in Oracle; forexample, the map attemptedto put an integer into aVARCHAR2 field.

Check that you have specifiedthe correct data type in themapping section of theconfiguration file.Note: The field specified isthe name of the field in theOracle database, not in theObjectServer.

Region status_updworkarea: Insufficientspace in data segment.Attempting to take dataoffline.

There was not enoughmemory to create and sendthe current batch of events(inserts, updates, and deletes)to the Oracle database.

The gateway makes morememory available by storingother outstanding batches todisk. No action needs to betaken by the user.

Frequently asked questionsVarious questions arise as users work with the Gateway for Oracle. Answers tothese questions are provided for your reference.

The following frequently asked questions are answered in this section:v “What makes this a fast gateway?”v “To what extent does the Gateway for Oracle guarantee delivery into Oracle?”

on page 48v “If the gateway fails, do I issue a transfer when it restarts?” on page 48v “Why does the overload value in the log file rise consistently?” on page 48v “How do I know that the gateway is performing adequately?” on page 48v “What is the Overload Value?” on page 48v “Can I use send and receive rates to measure the performance of the gateway?”

on page 48v “What are the reader and writer thread statistics?” on page 49v “What does it mean when the Inserts/Updates/Deletes metrics dip?” on page 49v “Why are journal entries not updated on the database?” on page 49v “How does the gateway transfer the status of an event in a single gateway

period?” on page 49v “Why does the gateway show two connections to the primary ObjectServer, but

only one connection when it fails over to the secondary ObjectServer?” on page49

v “Why does the gateway log file contain messages about adding IDUC sequencesto the skip list?” on page 50

v “Is it possible to record the initial severity level of an alert when it isoverwritten within the gateway's IDUC period?” on page 50

What makes this a fast gateway?

The Gateway for Oracle has the following features that make it a fast gateway:v Kernel threading allows simultaneous connections and transfers to Oracle. This

allows for better use of system resources on machines with multiprocessorsupport.

v Oracle bind arrays allow for efficient batch transfers into the database.


v Enhanced IDUC to the ObjectServer makes reads efficient.

To what extent does the Gateway for Oracle guarantee deliveryinto Oracle?

After events are successfully placed into the mapped work regions, corruption ofthe memory mapped files is the only scenario that would cause data loss. Thefollowing conditions can corrupt your memory mapped files (this also applies toan ObjectServer running in region storage mode):v A bug in the gateway code.v A SIGKILL (-9) command sent to the process.v Any situation that does not result in the file system buffers being synchronized

to disk properly; for example, hardware failure.v Batches of data sent to Oracle must be acknowledged; if not the data is resent.

If the gateway fails, do I issue a transfer when it restarts?

No. This was the prescribed operation with previous gateways, but it is no longerrequired. The gateway retains a permanent cache of events it has processed. It isstored in a memory mapped file and it is used to ensure synchronization with theObjectServer in the event of a gateway failure. This ensures that all your events aresent to Oracle.

Why does the overload value in the log file rise consistently?

The reader thread has read in more events than can be processed by the writerthread. You should adjust the BatchSize property (this controls the number ofelements sent in a single batch to Oracle). By default, it is set to 200. You canadjust this up to 500. If the overload value does not decrease after you haveadjusted the batch size, you may have a problem with your connection to Oracle.

How do I know that the gateway is performing adequately?

To gauge the adequacy of the performance of the gateway, you need to understandthe statistics monitoring facility of the gateway.

What is the Overload Value?

The Overload Value is the key metric for measuring the performance of thegateway. The Overload Value measures the number of reads from the ObjectServeragainst the number of writes to Oracle.

The Overload Value is calculated as the difference between the number of eventsread and the number of events written. It is expressed as a percentage of the totalnumber of events read. The percentage is an average of five statistics-time periods.

If this value continuously grows, then your bottleneck is in the writing process toOracle.

Can I use send and receive rates to measure the performance ofthe gateway?

No. Do not rely on data send/data receive rates as a gauge of the performance ofthe gateway. These rates are intended to tell you the average number ofreads/writes per statistics collection period, but do not indicate whether the


gateway is performing adequately. For example, during a single 60 second period,the write thread may push 60 events into Oracle within any second; the data sendrate expresses this as one event per second without taking into account whetherthe events were received in a single batch or individually.

What are the reader and writer thread statistics?

The reader/writer thread statistics indicate whether the numbers for the readerbatches match the numbers for the writer batches.

What does it mean when the Inserts/Updates/Deletes metricsdip?

The Inserts/Updates/Deletes metrics should remain relatively constant. If thesenumbers dip considerably, it is possible that something else is consumingObjectServer cycles; meaning the ObjectServer is not able to devote enough time togateway reads during any single IDUC period. If you are experiencingObjectServer performance issues, these will be confirmed by a dip in the numbersfor Status Inserts/ Updates/Deletes.

Why are journal entries not updated on the database?

This is because the clocks on the system where the gateway is running and thesystem where the database is set up are not synchronized. The clocks on these twosystems should be synchronized for the journal entries to be properly inserted inthe database.

How does the gateway transfer the status of an event in a singlegateway period?

The gateway can transfer only the last status of an event in a single gatewayperiod.

For example, when an event is raised and cleared, and the Generic Clear andDelete automations run on the same event within a single 60 second granularityperiod, a single delete message is recorded on the Oracle database. The result is asingle delete message in the Oracle database.

Why does the gateway show two connections to the primaryObjectServer, but only one connection when it fails over to thesecondary ObjectServer?

When the primary ObjectServer is queried using the SQL interactive interface(nco_sql), the result shows two gateway connections. However, when thesecondary ObjectServer is queried after failover, only one gateway connection isshown.

This difference arises because of how the Miscellaneous Data Processor (MDP)operates.

The two connections shown for the primary ObjectServer are for the reader and theMDP. The reader reads alert data and the MDP is responsible for transfers,gateway watch, and authenticating users for the ObjectServer. The MDP isfrequently inactive due to the intermittent nature of it's functions.


Because the MDP is frequently inactive, it is the reader that usually detects theprimary ObjectServer failure and fails over to make the connection to thesecondary ObjectServer. The MDP does not make the second failover connectionuntil you perform an action, such as restarting the gateway or transferring thestatic table contents using the gateway interactive command line tool (nco_g_icmd).

Why does the gateway log file contain messages about addingIDUC sequences to the skip list?

The following message is logged in the gateway log file:

Thread 'InputDataProcDistThread': Adding IDUC sequence 'nxxxx' to 'Update'skip list.

Skip lists enable empty event batches to be skipped over quickly so that they donot delay the processing of subsequent batches.

The message indicates that, in a particular IDUC period, no events of a particulartype were retrieved so the batch was added to the Update skip list. For example,updates in some IDUC sequences require inserts and updates from earlier eventbatches to be processed before they can be safely processed.

Is it possible to record the initial severity level of an alert when itis overwritten within the gateway's IDUC period?

An alert or event is cleared in the ObjectServer, or the severity level is changed,before the gateway has retrieved its original details for transfer to the database.

To allow enough time for the gateway to record the initial severity level of thealert, you can adjust the value of the Gate.IDUCFlushRate property in theproperties file to a value lower than the ObjectServer's IDUC rate.

Note: You should not specify a value lower than 20 for the Gate.IDUCFlushRateproperty, especially in high-load scenarios.

In addition to changing the value of the Gate.IDUCFlushRate property, or as analternative option, you can create an extra field in the ObjectServer to store theinitial severity level of the alert. If you choose this option, after you make theappropriate changes to the ObjectServer, the map file, and the database statustable, you must remove the following directory:

$OMNIHOME/var/gateway

Removing the /var/gateway directory is necessary so that the gateway can recreateits storage area using the new parameters.

TroubleshootingIf you encounter any problems with your gateway, read this list of commonproblems and their solutions before you contact IBM Software Support.

The following issues are explained in this section:v “NSocketWait timeout” on page 51v “Oracle 10G connection fails on AIX 6.1” on page 51


NSocketWait timeout

The gateway is running normally but the following message is logged in the debuglog file:

Debug: D-UNK-000-000: IDUC_DEBUG: NSocketWait Timeout

The message indicates that the gateway has tried and failed n times to get aresponse from the reader thread that connects to the ObjectServer, where n is thevalue specified by the Gate.OSReconnTimeout property. After n attempts, the debugmessage is generated and the counter is reset.

This debug message is for information only and requires no action on your part.

Oracle 10G connection fails on AIX 6.1

When running on AIX 6.1, the reporter is unable to establish a connection to Oracle10g. The following message is generated:Unable to connect to Reporter Information PortalPlease provide the proper parameters and restart the server

This problem arises because the infosql binary needs to connect using 64-bitOracle libraries. This can be confirmed by running a middleware connection test.The test will produce the following type of output:bash-3.2# cd $INFOHOME/binbash-3.2# ./infosql INFOHOME=..Could not load program ./infosql:Dependent module/oracle/app/oracle/oracle/product/10.2.0/db_1/lib32/libclntsh.a(shr.o)could not be loaded.The module has an invalid magic number.$LIBPATH references $ORACLE_HOME/lib32

This problem can be resolved by replacing $ORACLE_HOME/lib32 with$ORACLE_HOME/lib in the $LIBPATH environment variable.



Appendix. Notices and Trademarks

This appendix contains the following sections:v Noticesv Trademarks

NoticesThis information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

© Copyright IBM Corp. 2007, 2013 53

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.


COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksIBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks ofInternational Business Machines Corporation in the United States, other countries,or both.

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-basedtrademarks are either registered trademarks or trademarks of Adobe SystemsIncorporated in the United States, other countries, or both.

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporationin the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Java™ and all Java-based trademarks are trademarks of Sun Microsystems, Inc. inthe United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Appendix. Notices and Trademarks 55


��

Printed in USA

SC23-7669-08

Documents

IBM Tivoli Netcool/OMNIbus Gateway for Oracle: · PDF filevi IBM Tivoli Netcool/OMNIbus Gateway for Oracle: Reference Guide. Table 1. ... Update, Control (IDUC) processing system