IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW ...

Tivoli® Netcool/OMNIbus Gateway for OMNIbus to TDW 

Version 0.0.4207 

Reference Guide 

April 11, 2008 

�� 

SC23-9606-00

Tivoli® Netcool/OMNIbus Gateway for OMNIbus to TDW 

Version 0.0.4207 

Reference Guide 

April 11, 2008 

�� 

SC23-9606-00

Note 

Before using this information and the product it supports, read the information in “Notices” on page 29. 

Edition notice 

This edition applies to version 0.0.4207 of IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW 

(SC23-9606-00) and to all subsequent releases and modifications until otherwise indicated in new editions. 

© Copyright International Business Machines Corporation 1996, 2008. All rights reserved. 

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract 

with IBM Corp.

Contents 

Document control page . . . . . . . . v 

Chapter 1. IBM Tivoli Netcool/OMNIbus 

Gateway for OMNIbus to TDW . . . . . 1 

Summary . . . . . . . . . . . . . . .1 

Netcool/OMNIbus Gateway for OMNIbus to TDW 

information flow . . . . . . . . . . . . .1 

ODBC Gateway writer . . . . . . . . . . .2 

Chapter 2. Installing the gateway . . . . 5 

Installing the gateway on UNIX . . . . . . . .5 

Installing the gateway on Windows . . . . . . .5 

Chapter 3. Configuring the Gateway for 

OMNIbus to TDW . . . . . . . . . . . 7 

Common gateway properties . . . . . . . . .7 

Hash table cache . . . . . . . . . . . .8 

Error handling . . . . . . . . . . . . .9 

Process Agent control . . . . . . . . . .9 

TDW and ODBC writer properties . . . . . . .9 

Buffer size . . . . . . . . . . . . . .12 

Chapter 4. Gateway for OMNIbus to 

TDW mapping . . . . . . . . . . . . 15 

Mapping attributes . . . . . . . . . . . .16 

Example mapping . . . . . . . . . . . .16 

Chapter 5. Startup command file . . . 19 

SET PROPERTY . . . . . . . . . . . . .19 

GET PROPERTY . . . . . . . . . . . . .19 

SHOW PROPS . . . . . . . . . . . . .19 

GET CONFIG . . . . . . . . . . . . .20 

TRANSFER . . . . . . . . . . . . . .20 

FAILOVER SYNCH . . . . . . . . . . . .20 

Chapter 6. Table definition replication 

file . . . . . . . . . . . . . . . . 23 

Example table definition replication file . . . . .24 

Chapter 7. Running the gateway . . . . 27 

Running the gateway on UNIX . . . . . . . .27 

Running the gateway on Windows . . . . . .27 

Running the gateway on Windows service . . .27 

Notices . . . . . . . . . . . . . . 29 

Trademarks . . . . . . . . . . . . . .31 

© Copyright IBM Corp. 1996, 2008 iii

iv IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW: Reference Guide

Document control page 

Use this information to track changes between versions of this guide. 

The Gateway for OMNIbus to TDW documentation is provided in softcopy format 

only. To obtain the most recent version, visit the IBM ® 

Tivoli ® 

Information Center: 

http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp 

Table 1. Document modification history 

Document 

version 

Publication 

date 

Comments 

00 April 11, 2008 First IBM publication. 

© Copyright IBM Corp. 1996, 2008 v

vi IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW: Reference Guide

Chapter 1. IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus 

to TDW 

Summary 

The Gateway for OMNIbus to TDW is used to forward events generated by the 

Netcool/OMNIbus ObjectServer to Tivoli Data Warehouse (TDW). 

The Gateway for OMNIbus to TDW consists of an ObjectServer Gateway reader 

that obtains events from Netcool ® /OMNIbus, an ObjectServer Gateway gateway 

mapper that maps data to the required tables within TDW, and an ODBC Gateway 

writer that writes that data to TDW. 

The following table provides a summary of the Gateway for OMNIbus to TDW. 

Table 2. Summary of the Gateway for OMNIbus 

Gateway target Tivoli Data Warehouse version 2.1 

Gateway executable filename nco_g_tdw 

Patch number 0.0 

Gateway supported on Solaris, AIX ® , HP-UX, Linux ® , Windows ® 

Note: The Gateway for OMNIbus to TDW is not 

supported on HP-UX 11.11 running on dual processors. 

Configuration files $OMNIHOME/etc/NCO_GATE.props 

Requirements Tivoli Netcool/OMNIbus V7.0, V7.1, or V7.2. 

common-libngtk-1_3 common-libngobjserv-1_6 (required 

on UNIX ® 

only) 

common-libodbc-drivers-0_0 

Licensing Electronic licensing is no longer implemented in IBM 

Tivoli Netcool products. All IBM Tivoli Netcool 

products now use the IBM software licensing process. 

Remote connectivity Yes 

Failover or failback functionality Not available 

Netcool/OMNIbus Gateway for OMNIbus to TDW information flow 

The Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW is a uni-directional 

gateway that forwards events generated by Netcool/OMNIbus ObjectServer to 

TDW. 

The gateway uses various Netcool/OMNIbus components to collect and transform 

event data and the generic ODBC Gateway writer to write data to TDW. The 

following diagram shows the flow of information from Netcool/OMNIbus 

to 

TDW. 

© Copyright IBM Corp. 1996, 2008 1

Netcool/OMNIbus 

ObjectServer 

ODBC Gateway writer 

1 2 3 

ObjectServer 

Gateway 

Reader 

ObjectServer 


Mapper 

Table 3. Information flow callout descriptions 

Callout identifier Description 

ODBC 


Writer 

TDW 

V2.1 

Figure 1. Gateway for OMNIbus to TDW information flow 

▌1▐ The Netcool/OMNIbus ObjectServer Gateway reader obtains event 

changes from the ObjectServer using an IDUC connection. 

▌2▐ The Gateway for OMNIbus to TDW mapper maps data to the 

required destination tables in TDW. 

▌3▐ The ODBC Gateway takes the mapped Netcool/OMNIbus event 

data from which it creates SQL statements to send to TDW. These 

SQL statements populate the TDW with the details of the 

Netcool/OMNIbus events. 

The Gateway for OMNIbus to TDW uses a generic ODBC Gateway writer to 

popluate the TDW database. 

The following diagram shows how the generic ODBC Gateway acquires mapped 

events from Netcool/OMNIbus and sends them on to TDW. 

2 IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW: Reference Guide

1 2 

ObjectServer 


Mapper 

Full Batches 

Table 4. ODBC Gateway data processing callout descriptions 

Callout identifier Description 

3 

WriterTbl 

InsertHdl 

SQL Generator 

WriterTbl 

UpdateHdl 

Inserts Updates Deletes 

Flush Events 

Post Process 

5 4 

Figure 2. Data processing by the ODBC Gateway 

WriterTbl 

DeleteHdl 

ODBC 

Execute 

TDW 

Database 

▌1▐ The ODBC Gateway receives mapped inserts, updates, and deletes 

for each reader IDUC period. 

▌2▐ The writer builds batches of array-parameterized ODBC insert, 

update, and delete statements using the appropriate writer callback 

handler. 

▌3▐ If the number of batched statements exceeds the maximum batch 

size specified by the Gate.WRITER.BufferSize property, the ODBC 

Gateway flushes them to TDW. 

▌4▐ After each IDUC, a post processing handler flushes the SQL 

statements. 

▌5▐ ODBC connection errors and store-and-forward processing are 

handled during the flush phase. 

Chapter 1. IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW 3


Chapter 2. Installing the gateway 

The Gateway for OMNIbus to TDW can be installed on both UNIX and Windows 

platforms. 

This section contains the following topics: 

v “Installing the gateway on UNIX” 

v “Installing the gateway on Windows” 

Installing the gateway on UNIX 

Perform the following steps to install the Gateway for OMNIbus to TDW on UNIX. 

1. Back up the existing configuration files in the $OMNIHOME/gates/tivoli_tdw 

directory. 

These files will be overwritten by the new installation. 

2. Extract the installation file omnibus-3.6-arch-gateway-nco-g-tivoli-tdw-0_0.tar.Z 

to the $OMNIHOME/install directory. 

3. Run the patch utility script in the $OMNIHOME/install directory using the 

following command: 

$OMNIHOME/install/nco_patch -install 

4. Copy the example configuration file $OMNIHOME/gates/tivoli_tdw/ 

NCO_GATE.props to the $OMNIHOME/etc directory. 

5. Edit the configuration file to suit your environment: Specify the DNS name for 

the ODBC connection, the user name, and password, and make any other 

changes appropriate to your system. 

6. Create the NCO_GATE server in the interfaces file using nco_xigen. 

For details about using nco_xigen, see the IBM Tivoli Netcool/OMNIbus 

Administration Guide, (SC23-6371). 

Note: The database creation scripts for Netcool/Reporter are provided in the 

gateway-nco_g_reporter-scripts patch. They are not included in this gateway. If you 

want the database creation scripts for Netcool/Reporter, you must also install the 

gateway-nco_g_reporter-scripts patch. After installing this patch, you can find the 

current versions of the example configuration files and database creation scripts in 

the $OMNIHOME/gates/odbc. If you have the gateway-nco_g_reporter-scripts 

installed, the current versions of the database creation scripts for Netcool/Reporter 

are in the $OMNIHOME/gates/reporter/odbc. 

Installing the gateway on Windows 

Perform the following steps to install the Gateway for OMNIbus to TDW on 

Windows. 

1. Back up the existing configuration files in the following directories: 

%OMNIHOME%\gates\tivoli-tdw-0 and %OMNIHOME%\gates\reporter. 

These files will be overwritten by the new installation. 

2. Open the omnibus-3.6-wnt-gateway-nco-g-tivoli-tdw-0_0.tar.Z patch file using a 

file archive application. 

3. Extract the files into the %OMNIHOME% directory. 


4. Copy the example configuration file %OMNIHOME%\gates\tivoli_tdw\ 

NCO_GATE.props to the %OMNIHOME%\etc directory. 

5. Edit the configuration file to suit your environment: Specify the DNS name for 

the ODBC connection, the user name, and password, and make any other 

changes appropriate to your system. 

6. Create the NCO_GATE server in the interfaces file using Server Editor. 

For details about using Server Editor, see the IBM Tivoli Netcool/OMNIbus 

Administration Guide, (SC23-6371). 


Chapter 3. Configuring the Gateway for OMNIbus to TDW 

The gateway is configured using a properties file. This is a text file that contains a 

set of properties and their corresponding values. These properties define the 

operational environment of the gateway, such as connection details and the 

location of the other configuration files. 

To run the gateway on UNIX, enter the following command on the command line: 

nco_g_tdw 

The default location for the properties file is: 

$OMNIHOME/etc/NCO_GATE.props 

The default properties file must be copied to the $OMNIHOME/etc folder. 

This section contains the following topics: 

v “Common gateway properties” 

Common gateway properties 

v “TDW and ODBC writer properties” on page 9 

You can configure Gateway for OMNIbus to TDW by using properties defined in a 

properties file. 

For information about Netcool/OMNIbus properties and interprocess 

communication (IPC) properties, see the IBM Netcool/OMNIbus Probe and Gateway 

Guide (SC23-6387). The following table describes the common gateway properties. 

Table 5. Common gateway properties and command line options 

Property name Command line option Description 

Gate. 

CacheHashTblSize 

integer 

-chashtblsize integer Use this property to specify the size (in 

elements) that the gateway allocates for 

the hash table cache. 

The default is 5023. 

Gate.MapFile string -mapfile string Use this property to specify the 

location of the map definition file. 

Gate.StartupCmdFile 

string 

Gate.Transfer. 

FailoverSyncRate 

integer 

The default is $OMNIHOME/gates/ 

tivoli_tdw/tivoli_tdw.map . 

-startupcmdfile string Use this property to specify the 

location of the startup command file. 

The default is $OMNIHOME/ 

tivoli_tdw/tivoli_tdw.startup.cmd. 

-fsyncrate integer Use this property to specify the rate (in 

seconds) of the failover 

synchronization. 



Table 5. Common gateway properties and command line options (continued) 


Gate.NGtkDebug 

boolean 

-ngtkdebug boolean Use this property to specify whether 

the NGTK library should log debug 

messages. 

The default is TRUE. 

Note: You can specify which debug 

messages are included in the debug log 

file using the Gate.Mapper.Debug, 

Gate.Reader.Debug and 

Gate.Writer.Debug properties. 

Gate.PAAware integer -paaware integer Use this property to specify whether 

the gateway is Process Agent (PA) 

aware. 

Gate.PAAwareName 

string 

The default is 0 (not PA aware). 

Note: This property is maintained by 

the PA server and is included in the 

properties file for information only. 

-paname string Use this property to specify the name 

of the Process Agent controlling the 

gateway. 

The default is ″ ″. 

Note: This property is maintained by 

the PA server and is included in the 

properties file for information only. 

Hash table cache 

The gateway uses a hash table cache to store details of tables that require 

transferring to TDW. 

The main function of the cache is to facilitate journal and details table insert 

operations. When a journal or detail is forwarded for insertion into TDW, the 

gateway writer needs to know the corresponding status serial in the TDW. This 

information is found in the cache. It is also used for any other tables specified 

using the table replication definition table. 

The cache aids performance optimization by providing the gateway with an 

in-memory summarized view of the contents of the TDW to which it is linked. 

This means that the gateway does not have to query TDW to check for the 

existence of an event, or the Serial value or Tally value of an event; it can check 

the cache of the TDW instead. 

You can control the size of the hash table cache by using the 

Gate.CacheHashTblSize property. By default, the size of the hash table cache is 

5023 elements (or rows). This can be increased if the status table has a large 

number of rows (for example, in excess of 20,000). 

Note: To maximize efficiency, you should specify a prime number for the 

Gate.CacheHashTblSize property. 


Error handling 

You can troubleshoot problems with the gateway by consulting error messages. To 

help you do this, the gateway has configurable error handling. 

Error handling is provided by the Netcool/OMNIbus Gateway Toolkit (NGTK) 

library. To specify that the NGTK library logs debug messages, set the 

Gate.NGtkDebug property to TRUE. 

You can specify which debug messages are included in the debug files by using 

the Gate.Mapper.Debug, Gate.Reader.Debug, and Gate.Writer.Debug properties; 

these can be set to TRUE or FALSE as appropriate. 

Process Agent control 

You can control how the gateway runs by using Process Agent control. 

The gateway can be run under Process Agent (PA) control. The Gate.PAAware 

property indicates whether the gateway is PA aware. The Gate.PAAwareName 

property indicates which PA is running the gateway. 

These properties are maintained automatically by the PA server and provide 

information only. Do not change these properties manually. 

TDW and ODBC writer properties 

You specify how the Gateway for OMNIbus to TDW writes data to TDW using the 

writer properties defined in the properties file. 

The following table describes the writer properties. 

Table 6. Writer properties and command line options 


Gate.WRITER. 

Buffersize integer 

Gate.WRITER. 

DateFormat string 

Gate.WRITER. Debug 

boolean 

-writerbufsize integer Use this property to specify the 

number of entries that the gateway 

stores in the buffer before flushing, if 

buffering is enabled. This property can 

be used to fine-tune the efficiency of 

the gateway. 


Note: The gateway flushes the buffer 

when the end of a batch of SQL 

statements has been reached regardless 

of the buffer size. 

-writerdateformat string User this property to specify the format 

of the timestamp used by the target 

database. 


-writerdebug boolean Use this property to specify whether 

the gateway includes gateway writer 

debug messages in the debug log. 

The default is TRUE. 

Chapter 3. Configuring the Gateway for OMNIbus to TDW 9

Table 6. Writer properties and command line options (continued) 


Gate.WRITER. 

Description string 

Gate.WRITER. 

TblReplicate DefFile 

string 

Gate.WRITER. 

ODBCDSN string 

Gate.WRITER. 

ODBCUser string 

Gate.WRITER. 

ODBCPassword string 

Gate.WRITER. 

ODBCIniFile string 

Gate.WRITER. 

StatusTable string 

Gate.READER.Details 

TableName string 

Gate.READER.Failback 

Enabled boolean 

-writerdescription string Use this property to specify the 

application description for the writer 

connection. This description is used in 

triggers and allows you to determine 

which component of the gateway 

attempted to perform an action. 

-writertblreplicate 

deffile string 


Use this property to specify the table 

replication definition file that the 

gateway uses to replicate any 

additional tables from 

Netcool/OMNIbus in TDW. 

The default is $OMNIHOME/gates/ 

tivoli_tdw/tivoli_tdw.reader.tblrep.def. 

-writerodbcdsn string Use this property to specify the DSN 

name of the ODBC connection. 


-writerusername string Use this property to specify the user 

name that is used to authenticate the 

ODBC database. This user name is 

used to establish both the writer’s 

IDUC connection and the subsidiary 

SQL command connection. 


-writerpassword string Use this property to specify the 

password associated with the user that 

is specified by the 

Gate.WRITER.Username property. 


-writerodbcini string Use this property to specify the 

location of the DataDirect ODBC.ini 

file. 


-writerstatustable string Use this property to specify the name 

of the status table to which the ODBC 

Gateway writes within TDW. 

-readerdetailstblname 

string 

-readerfailbackenabled 

boolean 

10 IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW: Reference Guide 

The default is db.status. 

Use this property to specify the name 

of the details table that the gateway 

reads. 

The default is alerts.details. 

Use this property to specify failback for 

this gateway. 

The default is TRUE.



Gate.READER.Failback 

Timeout integer 

Gate.READER.IDUC 

FlushRate integer 

Gate.READER.Journal 


Gate.READER. 

LogOSSql boolean 

-readerfailbacktimeout 

integer 

-readeriducflushrate 

integer 

-readerjournaltblname 

string 

Use this property to specify the time 

(in seconds) that the gateway allows 

before entering failback mode. 


Use this property to specify the rate (in 

seconds) of the granularity of the 

reader. 

If you set this property to 0, the reader 

gets its updates at the same granular 

rate as that of the ObjectServer to 

which it is connected. 


Attention: If you set this property to 

a value greater than 0, the reader issues 

automatic IDUC flush requests to the 

ObjectServer with this frequency. This 

enables the reader to run at a faster 

granularity than that of the 

ObjectServer, thus enabling the 

gateway to capture more detailed event 

changes in systems where the 

ObjectServer itself has high granularity 

settings. 


of the journal table that the gateway 

reads. 

The default is alerts.journal. 

-readerlogossql boolean Use this property to specify whether 

the gateway logs all SQL commands 

sent to the ObjectServer in debug 

mode. 

The default is FALSE. 




Gate.READER. 

Password string 

Gate.READER. 

ReconnectTimeout 

integer 

Gate.READER.Server 

string 

Gate.READER.Status 


-readerpassword string Use this property to specify the 

password associated with the user 

specified by the 

Gate.READER.Username property. 

-readerreconntimeout 

integer 


If the ObjectServer to which the 

gateway writes alerts is running on 

Netcool/OMNIbus v7, 7.1, or 7.2, this 

password must be encrypted by the 

nco_g_crypt utility. 



Netcool/OMNIbus v3.6 without PAM 

enabled, this password must be 

encrypted by the nco_crypt utility. 



Netcool/OMNIbus v3.6 with PAM 

enabled, no password encryption is 

required. 

For details about the encryption 

utilities, see the IBM Tivoli 

Netcool/OMNIbus Administration Guide 

(SC23-6371). 

Use this property to specify the time 

(in seconds) between each reconnection 

poll attempt that the gateway makes if 

the connection to the ObjectServer is 

lost. 


-readerserver string Use this property to specify the name 

of the ObjectServer from which the 

gateway reads alerts. 

-readerstatustblname 

string 

The default is NCOMS. 


of the status table that the gateway 

reads. 

The default is alerts.status. 

Buffer size 

The buffer size controls the number of entries that the gateway stores in its buffer 

before flushing them to TDW. 

To set the buffer size, use the Gate.WRITER.Buffersize property. This property can 

be adjusted to fine-tune the efficiency of the gateway. 

The optimum value for the buffer size depends upon the average event size and 

the speed of the network. The default value has proved to be efficient for many 


installations. To determine the most efficient setting for your system, compare the 

timing figures for resynchronization operations performed using different settings 

for this property. 



Chapter 4. Gateway for OMNIbus to TDW mapping 

The gateway can replicate any table in the Netcool/OMNIbus ObjectServer. To do 

this, the gateway maps data to the appropriate fields in the ObjectServer using a 

map definition file. 

If you want to replicate user related system tables (for example, SecurityUsers, 

SecurityGroups, SecurityRoles, SecurityRoleGrants, and SecurityGroupMembers), 

you must also include details of these mappings in this file. The path of the map 

definition file is determined by the Gate.Mapfile property in the properties file. 

The following map definition file conversion functions can be used in the map 

definition file: 

v TO_STRING ( ) 

v TO_INTEGER ( ) 

v TO_TIME ( ) 

Syntax 

Mappings for use with the ObjectServer writer must adhere to the following 

syntax: 

CREATE MAPPING mappingname ( ’ dest_fieldname’ = ( ’@src_fieldname’ | 

simple_expression | attribute ) [ ON INSERT ONLY ] [ CONVERT TO type ] 

[ NOT NULL (’@src_fieldname’)] [ , ’dest_fieldname’ = ( ’@src_fieldname’ | 

simple_expression | attribute ) [ ON INSERT ONLY ] [ CONVERT TO type ] 

[ NOT NULL (’@src_fieldname’)] ] ... ) ; 

Where: 

v mappingname is the name of the mapping to be created. 

v dest_fieldname is the name of the field to be written in the destination 

ObjectServer. 

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

v simple_expression is an integer or a set of integers and operators. 

v attribute is an attribute name. 

The optional ON INSERT ONLY controls the updating of the field during the life 

of the alert; when omitted, the field is updated when any change in the state of the 

alert occurs. When included, the field is created once for the alert, but is never 

updated. 

Tip: The ON INSERT ONLY option only applies when setting the value of 

variables. 

The optional CONVERT TO type enables the mapping to define a forced 

conversion for situations where a source field may not match the type of the 

destination field. The type can be INTEGER, STRING, or DATE. 

The optional NOT NULL indicates that the mapping is only performed if the 

source field is not null; that is, has a value set for it. 


Mapping attributes 

Example mapping 

You use attribute names to include additional data in mapping definitions. You can 

specify two types of attribute: cache value access attributes or dynamic attributes. 

Cache value access attributes 

The gateway uses cache value attributes to access values that are stored in the 

cross-reference cache. The following table describes the cache value attributes that 

can be used in mapping definitions. 

Table 7. Cache value access attributes 

Attribute name Description 

STATUS.SERIAL Cached serial number for the status table row that is 

associated with the current journal or details table 

row. 

STATUS.SERVER_SERIAL Cached server serial number for the status table row 

that is associated with the current journal or details 

table row. 

STATUS.SERVER_NAME Cached server name for the status table row that is 


row. 

STATUS.IDENTIFIER Cached identifier for the status table row that is 


row. 

JOURNAL.SERIAL Cached serial number of the journal table row. 

DETAILS.IDENTIFIER Cached identifier of the details table row. 

Dynamic attributes 

Dynamic attributes enable the gateway to access dynamic values that are 

automatically generated by the gateway. The following table describes the dynamic 

attributes that can be used in mapping definitions. 

Table 8. Dynamic attributes 

Attribute name Description 

ACTION_CODE This attribute displays a single character string that 

specifies the type of operation performed. Valid 

values are: 

v I: Insert 

v U: Update 

v D : Delete 

ACTION_TIME This attribute displays the time in UTC that the 

action occurred. 

DELETEDAT This attribute displays the date on which the row 

was deleted, if applicable. 

Mappings define how the gateway replicates tables by assigning data to 

appropriate fields in the ObjectServer. 


The following example shows the mappings for the ObjectServer alerts.status table 

into which the gateway writes: 

CREATE MAPPING StatusMap 

( 

’identifier’ = ’@Identifier’, 

’server_identifier’ = ’@ServerName’ + " " + TO_STRING(’@ServerSerial’), 

’sub_source’ = ’@AlertKey’ ON INSERT ONLY, 

’sub_origin’ = ’@AlertGroup’ ON INSERT ONLY, 

’msg’ = ’@Summary’ ON INSERT ONLY, 

’origin’ = ’@Node’ ON INSERT ONLY, 

’node_alias’ = ’@NodeAlias’ ON INSERT ONLY 

NOTNULL ’@Node’, 

’manager’ = ’@Manager’ ON INSERT ONLY, 

’source’ = ’@Agent’ ON INSERT ONLY, 

’severity’ = ’@Severity’, 

’date’ = ’@LastOccurrence’ ON INSERT ONLY, 

’omnibus_last_modified_time’ = ’@InternalLast’ ON INSERT ONLY ); 

Chapter 4. Gateway for OMNIbus to TDW mapping 17


Chapter 5. Startup command file 

SET PROPERTY 

GET PROPERTY 

SHOW PROPS 

The startup command file contains a set of commands that the gateway performs 

automatically each time it starts. 

After the gateway has started, you can use the nco_sql command to issue the 

commands manually. For details about nco_sql, see the IBM Tivoli Netcool/OMNIbus 

Administration Guide (SC23-6371). 

You can include the following commands in the startup command file: 

v “SET PROPERTY” 

v “GET PROPERTY” 

v “SHOW PROPS” 

v “GET CONFIG” on page 20 

v “TRANSFER” on page 20 

v “FAILOVER SYNCH” on page 20 

Use the SET PROPERTY command to set the value of a property in the properties 

file. 

Syntax 

SET PROPERTY ’string’ TO value ; 

Example 

SET PROPERTY ’Gate.Reader.Debug’ TO FALSE ; 

Use the GET PROPERTY command to return the value of a specified property 

from the gateway properties file. 

Syntax 

GET PROPERTY ’string’ ; 

Example 

GET PROPERTY ’Gate.Reader.Debug’ ; 

Use the SHOW PROPS command to display the current configuration of the 

gateway by listing all properties and their values. 

Syntax 

SHOW PROPS ; 


GET CONFIG 

TRANSFER 

Example 

SHOW PROPS ; 

go 

Use the GET CONFIG command to display the current configuration of the 

gateway by listing all properties and their values. 

GET CONFIG is identical to the SHOW PROPS command; it may be removed from 

later versions of the ObjectServer gateway. 

Syntax 

GET CONFIG ; 

Example 

GET CONFIG ; 

go 

Use the TRANSFER command to initiate a data transfer operation between tables 

in the two ObjectServers. 

You can use a filter condition to transfer a partial table. If the target table does not 

match the source table, a map can be specified as part of the transfer operation. 

This map must be defined in the map definition file of the gateway. 

Syntax 

FAILOVER SYNCH 

TRANSFER FROM sourcetable TO targettable 

[VIA FILTER filtertext] [WITH DELETE VIA delfiltertext] 

[USING TRANSFER_MAP mapname] ; 

Example 

In the following example, all records with the name nobody are deleted from the 

table resync.names and replaced with the corresponding records in the table 

master.names. 

TRANSFER FROM ’master.names’ TO ’resync.names’ 

VIA FILTER ’Name != \’nobody\’’ 

DELETE ; 

Use the FAILOVER SYNCH command to synchronize data between primary and 

backup ObjectServers. The command specifies which master tables are transferred 

during the data transfer operation. 

For information about ObjectServer failover, see the IBM Tivoli Netcool/OMNIbus 

Administration Guide (SC23-6371). 

Syntax 

FAILOVER_SYNC [ ADD ’TABLENAME’ TO | REMOVE ’TABLENAME’ 

FROM ] WRITERNAME ; 


Example 

FAILOVER_SYNC ADD ’master.names’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.groups’TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.members’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.permissions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.profiles’TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.actions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.action_access’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.menus’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.menu_defs’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.menu_items’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.prompt_defs’TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.conversions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.col_visuals’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.colors’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objclass’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objmenus’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objmenuitems’TO ObjectServerA; 

Chapter 5. Startup command file 21


Chapter 6. Table definition replication file 

The table replication definition file defines the tables in the source ObjectServer 

that the gateway replicates in TDW. 

The table definition file is specified using the Gate.WRITER.TblReplicateDefFile 

property. 

Example 

REPLICATE ALL | (INSERTS, UPDATES, DELETES) 

FROM TABLE sourcetable 

USING MAP mapname 

[FILTER WITH filter_clause] 

[INTO targettable] 

[ORDER BY column_name [ASC|DESC], ... ] 

[WITH NORESYNC] 

[RESYNC DELETE FILTER delete_filter_clause] 

[SET UPDTOINS CHECK TO {ENABLED|DISABLED|FORCED}] 

[AFTER IDUC DO command] ; 

Where: 

v sourcetable is the table to be replicated in TDW. 

v mapname is the map definition that defines the table. 

v column_name is the column by which the rows returned to the gateway from the 

ObjectServer are ordered. 

v filter_clause defines the filter the gateway uses to select rows for replicating. By 

default, filtering is inclusive. That is, the filter sends only those events that 

match the filter definition. However, you can specify that the filter sends events 

that do not match the filter definition by preceding the equals sign (=) with an 

exclamation mark (!). For example, the following filter clause sends all events 

whose severity is not set to 5: FILTER with ’Severity !=5’. 

v propertyname is the property the gateway uses to filter the table data (only rows 

that satisfy the filter are replicated). 

v propertyvalue is argument to be used in the filter. 

v targettable is the name of the table in which to replicate the data. 

v delete_filter_clause defines the resynchronization delete filter that the gateway 

issues to TDW. 

The optional WITH NORESYNC option allows you to specify tables that should 

not be resynchronized. 

The optional ORDER BY option allows you to specify the order in which the rows 

are returned to the gateway from the ObjectServer. ASC specifies that the rows are 

sorted in ascending order; DESC specifies descending order. If you specify neither 

ASC nor DESC, the rows are sorted in ascending order. 

You can define multiple columns for sorting by specifying a comma-separated list; 

for example: 

ORDER BY ’Serial DESC, StateChange ASC’ 


The optional RESYNC DELETE FILTER option is used when the fields in the target 

and source tables are not an exact match. This option allows you to define a 

resynchronization deletion filter that specifies which fields to remove before 

insertion into the target table. 

The optional SET UPDTOINS CHECK TO option allows you to configure the 

update-to-insert functionality. ENABLED (the default setting) instructs the gateway 

to perform normal update-to-insert conversions - when an update is received from 

the source ObjectServer for a given table, and the row that has been updated does 

not exist within TDW, the gateway converts the update to an insert, so that the 

row is repopulated within TDW. If the row does exist within TDW, the gateway 

updates the existing row with the update from the source ObjectServer; DISABLED 

instructs the gateway to always send an update to TDW for each update received 

from the source ObjectServer - any update sent to TDW for rows that do not exist 

are dropped as they will affect no rows within TDW; FORCED instructs the 

gateway to convert all updates from the source ObjectServer to an insert on TDW - 

if the row already exists within TDW, a de-duplication action is performed by 

TDW - this effectively makes the gateway behave like a probe. 

The optional AFTER IDUC DO option allows you to specify a column and 

associated value that the gateway applies to all rows that have been inserted, 

updated, or deleted. 

Example table definition replication file 

The table replication definition file defines how the ObjectServer gateway replicates 

tables between the source and target ObjectServers. Use this example to familiarize 

yourself with how the file works. 

The following example shows a table replication definition file: 

REPLICATE INSERT, DELETE FROM TABLE ’alerts.status’ 

USING MAP ’StatusMap’ 

ORDER BY ’Serial ASC’ 

FILTER WITH ’Severity=!5’ 

SET UPDTOINS CHECK TO FORCED 

AFTER IDUC DO ’Location=\’PASSED BY GW\’’; 

REPLICATE ALL FROM TABLE ’alerts.journal’ 

USING MAP ’JournalMap’; 

REPLICATE ALL FROM TABLE ’alerts.details’ 

USING MAP ’DetailsMap’; 

############################################################################## 

# NOTE: If replication of the user related system tables is required, uncomment 

# the replication definitions below. The associated maps will also need to be 

# uncommented. 

############################################################################## 

# REPLICATE ALL FROM TABLE ’security.users’ 

# USING MAP ’SecurityUsersMap’ 

# INTO ’transfer.users’; 

# 

# REPLICATE ALL FROM TABLE ’security.groups’ 

# USING MAP ’SecurityGroupsMap’ 

# INTO ’transfer.groups’; 

# 

# REPLICATE ALL FROM TABLE ’security.roles’ 

# USING MAP ’SecurityRolesMap’ 

# INTO ’transfer.roles’; 


# 

# REPLICATE ALL FROM TABLE ’security.role_grants’ 

# USING MAP ’SecurityRoleGrantsMap’ 

# INTO ’transfer.role_grants’; 

# 

# REPLICATE ALL FROM TABLE ’security.group_members’ 

# USING MAP ’SecurityGroupMembersMap’ 

# INTO ’transfer.group_members’; 

Chapter 6. Table definition replication file 25


Chapter 7. Running the gateway 

Running the gateway on UNIX 

This section describes how to run the Gateway for OMNIbus to TDW. 

Perform the following steps to run the Gatway for OMNIbus to TDW on UNIX. 

To run the gateway on UNIX, run the following command: 

$OMNIHOME/bin/nco_g_tdw 

or use the -config command line option as follows: 

$OMNIHOME/bin/nco_g_tdw -config /path/config_filename 

Where path is the location of the configuration file and config_filename is the 

name of the configuration file. 

Running the gateway on Windows 

Perform the following steps to run the Gateway for OMNIbus to TDW on 

Windows. 

To run the gateway on Windows, run the following command: 

%\OMNIHOME%\bin\nco_g_tdw.exe 

or use the -config command line option as follows: 

%\OMNIHOME%\bin\nco_g_tdw.exe -config\path\config_filename 

Where path is the location of the configuration file and config_filename is the 

name of the configuration file. 

Running the gateway on Windows service 

To run the gateway as a Windows service, use the following steps: 

1. Run the following command to register the gateway as a service within the 

Service Control Manager:nco_g_tdw.exe -install 

2. If you are running the gateway on the same machine as the ObjectServer, use 

the following command to register its dependency upon the ObjectServer 

service: nco_g_tdw.exe -install -depend NCOObjectServer 

3. Select the following option from the Start menu: Control Panel → 

Administrative Tools → Services. The Services window is displayed. 

4. Highlight Gateway for OMNIbus to TDW in the list of available services. 

5. Click on Start. 

Removing the gateway service 

To remove the gateway service, use the following steps: 

1. Stop the service using the Services window. 

2. Run the following command: nco_g_tdw.exe -remove. 



Notices 

This 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 in 

other countries. Consult your local IBM representative for information on the 

products and services currently available in your area. Any reference to an IBM 

product, program, or service is not intended to state or imply that only that IBM 

product, program, or service may be used. Any functionally equivalent product, 

program, or service that does not infringe any IBM intellectual property right may 

be used instead. However, it is the user’s responsibility to evaluate and verify the 

operation of any non-IBM product, program, or service. 

IBM may have patents or pending patent applications covering subject matter 

described in this document. The furnishing of this document does not grant you 

any license to these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 

IBM Corporation 

North Castle Drive 

Armonk, NY 10504-1785 

U.S.A. 

For license inquiries regarding double-byte (DBCS) information, contact the IBM 

Intellectual Property Department in your country or send inquiries, in writing, to: 

IBM World Trade Asia Corporation 

Licensing 2-31 Roppongi 3-chome, Minato-ku 

Tokyo 106-0032, Japan 

The following paragraph does not apply to the United Kingdom or any other 

country where such provisions are inconsistent with local law: 

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 

PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS 

FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or 

implied warranties in certain transactions, therefore, this statement may not apply 

to you. 

This information could include technical inaccuracies or typographical errors. 

Changes are periodically made to the information herein; these changes will be 

incorporated in new editions of the publication. IBM may make improvements 

and/or changes in the product(s) and/or the program(s) described in this 

publication at any time without notice. 

Any references in this information to non-IBM Web sites are provided for 

convenience only and do not in any manner serve as an endorsement of those Web 

sites. The materials at those Web sites are not part of the materials for this IBM 

product 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 it 

believes appropriate without incurring any obligation to you. 


Licensees of this program who wish to have information about it for the purpose 

of enabling: (i) the exchange of information between independently created 

programs and other programs (including this one) and (ii) the mutual use of the 

information which has been exchanged, should contact: 

IBM Corporation 

Software Interoperability Coordinator, Department 49XA 

3605 Highway 52 N 

Rochester, MN 55901 

U.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 material 

available for it are provided by IBM under terms of the IBM Customer Agreement, 

IBM International Program License Agreement, or any equivalent agreement 

between us. 

Any performance data contained herein was determined in a controlled 

environment. Therefore, the results obtained in other operating environments may 

vary significantly. Some measurements may have been made on development-level 

systems and there is no guarantee that these measurements will be the same on 

generally available systems. Furthermore, some measurements may have been 

estimated through extrapolation. Actual results may vary. Users of this document 

should verify the applicable data for their specific environment. 

Information concerning non-IBM products was obtained from the suppliers of 

those products, their published announcements or other publicly available sources. 

IBM has not tested those products and cannot confirm the accuracy of 

performance, compatibility or any other claims related to non-IBM products. 

Questions on the capabilities of non-IBM products should be addressed to the 

suppliers of those products. 

All statements regarding IBM’s future direction or intent are subject to change or 

withdrawal without notice, and represent goals and objectives only. 

All IBM prices shown are IBM’s suggested retail prices, are current and are subject 

to change without notice. Dealer prices may vary. 

This information is for planning purposes only. The information herein is subject to 

change before the products described become available. 

This information contains examples of data and reports used in daily business 

operations. To illustrate them as completely as possible, the examples include the 

names of individuals, companies, brands, and products. All of these names are 

fictitious and any similarity to the names and addresses used by an actual business 

enterprise is entirely coincidental. 

COPYRIGHT LICENSE: 

This information contains sample application programs in source language, which 

illustrate programming techniques on various operating platforms. You may copy, 

modify, and distribute these sample programs in any form without payment to 

IBM, for the purposes of developing, using, marketing or distributing application 

programs conforming to the application programming interface for the operating 


Trademarks 

platform for which the sample programs are written. These examples have not 

been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or 

imply reliability, serviceability, or function of these programs. 

Each copy or any portion of these sample programs or any derivative work, must 

include 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 rights 

reserved. 

If you are viewing this information softcopy, the photographs and color 

illustrations may not appear. 

IBM, the IBM logo, ibm.com ® , AIX, Tivoli, and Netcool are trademarks of 

International Business Machines Corporation in the United States, other countries, 

or both. 

Adobe ® , Acrobat, Portable Document Format (PDF), PostScript ® , and all 

Adobe-based trademarks are either registered trademarks or trademarks of Adobe 

Systems Incorporated in the United States, other countries, or both. 

Intel ® , Intel Inside ® 

(logos), MMX, and Pentium ® 

are trademarks of Intel 

Corporation in the United States, other countries, or both. 

Microsoft ® , Windows, Windows NT ® , and the Windows logo are trademarks of 

Microsoft Corporation in the United States, other countries, or both. 

and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in 

the United States, other countries, or both. 

Java 

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

both. 

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

countries. 

Other company, product, or service names may be trademarks or service marks of 

others. 

Notices 31


�� 

Printed in USA 

SC23-9606-00

IBM Tivoli Netcool/OMNIbus Gateway for OMNIbus to TDW ...

Create successful ePaper yourself

Delete template?

Save as template?