Ecoamst

IBM Tivoli Enterprise Console
Adapters Guide
Version 3.9
SC32-1242-00
IBM Tivoli Enterprise Console
Adapters Guide
Version 3.9
SC32-1242-00
Note
Before using this information and the product it supports, read the information in Notices on page 221.
First Edition (August 2003)

This edition applies to version 3, release 9 of IBM Tivoli Enterprise Console (product number 5698-TEC) and to all
subsequent releases and modifications until otherwise indicated in new editions.
Copyright International Business Machines Corporation 2003. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this guide . . . . . . . . . . vii
Who should read this guide . . . . . . . . . vii
Publications . . . . . . . . . . . . . . vii
IBM Tivoli Enterprise Console library . . . . vii
Related publications . . . . . . . . . . viii
Accessing publications online . . . . . . . viii
Ordering publications . . . . . . . . . viii
Contacting software support . . . . . . . . . ix
Participating in newsgroups . . . . . . . . . ix
Conventions used in this guide . . . . . . . . x
Typeface conventions . . . . . . . . . . x
Operating system-dependent variables and paths x
Command line syntax . . . . . . . . . . xi
Chapter 1. Introduction to adapters . . . 1

Adapter overview . . . . . . . . . . .
How adapters on endpoints send events . . .
How adapters on managed nodes send events .
How non-TME adapters send events . . . .
Internationalization support for events. . . . .
Event information and attributes. . . . . . .
Adapter files . . . . . . . . . . . . .
Cache file . . . . . . . . . . . . .
Configuration file . . . . . . . . . . .
File location . . . . . . . . . . .
File format . . . . . . . . . . . .
Example . . . . . . . . . . . . .
Keywords . . . . . . . . . . . .
Event filtering . . . . . . . . . .
Event buffer filtering . . . . . . . .
BAROC file . . . . . . . . . . . .
Rule file . . . . . . . . . . . . .
Format file . . . . . . . . . . . .
Class definition statement file . . . . . .
Error file . . . . . . . . . . . . .
Initial files . . . . . . . . . . . . . .
Troubleshooting adapters . . . . . . . . .
Adapter startup errors . . . . . . . . .
Troubleshooting for all adapters . . . . .
Managed node adapter troubleshooting . . .
Endpoint adapter troubleshooting . . . . .
Non-TME adapter troubleshooting. . . . .
. 1
. 2
. 3
. 3
. 3
. 4
. 7
. 8
. 9
. 9
. 9
. 9
. 10
. 21
. 22
. 23
. 23
. 24
. 25
. 26
. 27
. 27
. 27
. 28
. 28
. 28
. 29
Chapter 2. Installing adapters . . . . . 31

Supported adapters. . . . . . . . . . .
Hardware and software requirements. . . . .
UNIX and Windows software requirements. .
AS/400 software requirements . . . . . .
OS/2 software requirements . . . . . . .
Installing an HP OpenView adapter on a managed
node. . . . . . . . . . . . . . . .
Installing from the Tivoli desktop . . . . .
Installing from the command line . . . . .
Installing an adapter on an endpoint . . . . .
Installing a non-TME adapter . . . . . . .
Copyright IBM Corp. 2003
.
.
.
.
.
31
32
32
32
32
.
.
.
.
.
33
33
33
33
34
Installing on UNIX operating systems . . .

Installing on Windows operating systems . .
Installing on the OS/2 operating system . . .
Installing AS/400 adapters . . . . . . . .
Installing from CD . . . . . . . . . .
Installing from CD on an AS/400 System . .
Installing with English as a secondary language
Installing the NetWare logfile adapter . . . .
Upgrading HP OpenView adapters . . . . .
Preparing to upgrade adapters . . . . . .
Backing up object databases . . . . . .
Upgrading adapters from the Tivoli desktop .
Upgrading adapters from the command line .
Upgrading adapters using the Software
Installation Service . . . . . . . . . .
Uninstalling adapters . . . . . . . . . .
Uninstalling an HP OpenView adapter on a
managed node . . . . . . . . . . .
Uninstalling an adapter on an endpoint . . .
Uninstalling a non-TME adapter . . . . .
Uninstalling on UNIX operating systems .
Uninstalling on Windows operating systems
Uninstalling on the OS/2 operating system .
Uninstalling an AS/400 adapter . . . . .
Uninstalling a NetWare logfile adapter . . .
Removing Version 3.8 enhanced adapters from
the Tivoli environment . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
35
36
37
37
37
38
39
39
40
40
40
40
41
. 41
. 41
.
.
.
.
41
41
42
42
42
. 42
. 43
. 43
. 44
Chapter 3. Adapter Configuration

Facility. . . . . . . . . . . . . . . 45
Using adapter configuration profiles . . . . . .
Adapter Configuration Facility roles . . . . . .
Setting adapter configuration profiles as managed
resources . . . . . . . . . . . . . . .
Setting adapter configuration profiles as
managed resources from the Tivoli desktop. . .
Setting adapter configuration profiles as
managed resources from the command line. . .
Creating an adapter configuration profile . . . .
Creating an adapter configuration profile from
the Tivoli desktop . . . . . . . . . . .
Creating an adapter configuration profile from
the command line . . . . . . . . . . .
Cloning an adapter configuration profile . . . .
Cloning an adapter configuration profile from the
Tivoli desktop . . . . . . . . . . . .
Cloning an adapter configuration profile from the
command line . . . . . . . . . . . .
Deleting an adapter configuration profile . . . .
Deleting an adapter configuration profile from
the Tivoli desktop . . . . . . . . . . .
Deleting an adapter configuration profile from
the command line . . . . . . . . . . .
Setting adapter configuration profile defaults . . .
Renaming a profile . . . . . . . . . . .
45
45
46
46
46
46
47
47
48
48
48
49
49
49
50
50
iii
Getting a new copy of an adapter configuration

profile . . . . . . . . . . . . . . . .
profile from the Tivoli desktop . . . . . . .
profile from the command line . . . . . . .
Setting adapter configuration profile distribution
defaults. . . . . . . . . . . . . . .
Modifying an adapter configuration profile default
policy . . . . . . . . . . . . . . . .
Modifying an adapter configuration profile
default policy from the Tivoli desktop . . . .
default policy from the command line . . . .
validation policy. . . . . . . . . . . . .
validation policy from the Tivoli desktop . . .
validation policy from the command line . . .
Distributing an adapter configuration profile . . .
Distributing an adapter configuration profile
from the Tivoli desktop . . . . . . . . .
from the command line . . . . . . . . .
Adding an adapter configuration profile record . .
Endpoint adapters . . . . . . . . . . .
Editing an adapter configuration profile record . .
Adding a configuration option to an adapter
configuration profile record . . . . . . . .
Modifying a configuration option in an adapter
Removing an environment variable from an
adapter configuration profile record . . . . .
Adding a filter definition to an adapter
Adding a filter cache definition to an adapter
Adding a prefilter definition to an adapter
Modifying a filter definition in an adapter
Modifying a filter cache definition in an adapter
Modifying a prefilter definition in an adapter
Removing a filter cache definition in an adapter
Removing a prefilter definition in an adapter
Removing a filter definition from an adapter
Adding a file to the distribution list of an
Removing a file from the distribution list of an
Modifying the adapter configuration file behavior
Modifying variable expansion behavior . . . .
Adding a before or after script to an adapter
iv
IBM Tivoli Enterprise Console: Adapters Guide
50
50
51
51
52
53
54
54
55
56
56
56
56
57
57
58
59
59
Modifying a before or after script in an adapter

Removing a before or after script from an
Enabling and disabling before and after scripts in
an adapter configuration profile record . . . .
Modifying before and after script reporting
behavior . . . . . . . . . . . . . .
Modifying the comment in an adapter
Modifying the UID and GID in an adapter
Specifying the adapter identifier name . . . .
Copying an adapter configuration profile record . .
Copying an adapter configuration profile record
Moving an adapter configuration profile record . .
Moving an adapter configuration profile Record
Deleting an adapter configuration profile record . .
Deleting an adapter configuration profile record
from the command line . . . . . . . . .
Locking and unlocking an adapter configuration
profile record . . . . . . . . . . . . . .
Locking and unlocking an adapter configuration
profile Record from the Tivoli desktop . . . .
Finding an adapter configuration profile record . .
Sorting adapter configuration profile records . . .
Sorting adapter configuration profile attributes . .
Starting the Logfile Format Editor from an adapter
configuration profile . . . . . . . . . . .
69
70
70
71
72
72
73
73
74
74
74
75
75
75
76
76
76
77
78
79
60
61
61
62
63
64
64
65
65
66
66
67
68
68
69
Chapter 4. AS/400 alert adapter . . . . 81

Adapter files . . . . . . . . . .
Configuration file . . . . . . .
Class definition statement file . . .
SELECT statement example . . .
FETCH statement example . . .
Keywords . . . . . . . . .
Configuring the AS/400 alert filters . .
Default alert filter . . . . . . .
Integrating with an existing alert filter
Starting the adapter . . . . . . .
STRTECADP . . . . . . . . .
Stopping the adapter . . . . . . .
ENDTECADP . . . . . . . .
Events Listing . . . . . . . . .
Event class structure . . . . . .
Troubleshooting the AS/400 adapter . .
Logging Events in Test Mode . . . .
TCP/IP considerations. . . . . . .
Starting an AS/400 adapter after an IPL .
Adding an autostart job to QSYSWRK
Changing the AS/400 startup program
Multiple AS/400 alert adapters . . . .
QTMETECA/POSTEMSG . . . . .
Common tasks . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
81
82
83
83
83
83
84
84
85
85
86
87
88
90
90
92
93
93
93
93
94
94
95
96
97
Chapter 5. AS/400 message adapter . . 99

Adapter Files . . . . . . . . . . .
Configuration file . . . . . . . .
Class definition statement file . . . .
SELECT statement example. . . .
FETCH statement example . . . .
MAP statement example. . . . .
Keywords . . . . . . . . .
Starting the adapter . . . . . . . .
STRTECADP . . . . . . . . .
Stopping the adapter . . . . . . . .
ENDTECADP . . . . . . . . .
Events listing . . . . . . . . . .
Event class structure . . . . . . .
Troubleshooting the AS/400 adapter . . .
Logging Events in Test Mode . . . . .
TCP/IP considerations . . . . . . .
Starting an AS/400 adapter after an IPL .
Adding an autostart job to QSYSWRK .
Changing the AS/400 startup program .
Multiple AS/400 message queues. . . .
Configuration file . . . . . . . .
Using FTP to run AS/400 commands . .
Common tasks . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
NetWare logfile adapter reference information

Adapter files . . . . . . . . . . .
Error file . . . . . . . . . . . . .
Prefiltering NetWare events. . . . . . .
Configuration file . . . . . . . . . .
Format file . . . . . . . . . . . .
Events listing . . . . . . . . . . .
Event class structure . . . . . . . .
tecadnw4.nlm . . . . . . . . . . .
load tecadnw4 . . . . . . . . . .
Troubleshooting the NetWare logfile adapter .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 6. NetWare logfile adapter
. 99
100
101
101
101
101
102
105
106
107
108
110
110
111
111
111
112
112
112
113
113
113
114
115
115
115
115
116
116
117
118
118
121
122
123
Chapter 7. OpenView adapter . . . . 125

OpenView driver . . . . . . . . . . . .
Reception of OpenView messages . . . . .
Determining the OpenView NNM version . . .
Incoming messages format . . . . . . . .
Event correlation with NNM 6 . . . . . .
Determining the OVsnmpEventOpen filter value
Testing tools . . . . . . . . . . . . .
Testing event correlation with NNM 6 . . . .
Event correlation example . . . . . . .
Adapter files . . . . . . . . . . . . .
Configuration file . . . . . . . . . . .
Class definition statement file . . . . . . .
OpenView event example . . . . . . .
Keywords . . . . . . . . . . . .
Object identifier file . . . . . . . . . .
Error file . . . . . . . . . . . . . .
LRF file . . . . . . . . . . . . . .
Starting and stopping the adapter . . . . . .
Events listing . . . . . . . . . . . . .
Event class structure . . . . . . . . . .
OpenView traps . . . . . . . . . . . .
125
125
125
126
126
127
128
128
129
129
130
131
131
132
132
133
133
133
133
134
136
SNMP traps . . . . . . . . .
OpenView traps . . . . . . .
Troubleshooting the OpenView adapter.
.
.
.
.
.
.
.
.
.
. 136
. 136
. 137
Chapter 8. OS/2 adapter . . . . . . . 139

Adapter files . . . .
Configuration file . .
Format file . . . .
Starting the adapter . .
Stopping the adapter . .
Events listing . . . .
Event class structure .
Troubleshooting the OS/2
. . .
. . .
. . .
. . .
. . .
. . .
. . .
adapter
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
139
139
140
140
141
141
141
142
Chapter 9. SNMP adapter . . . . . . 143

SNMP driver . . . . . . . . .
Reception of SNMP messages . . .
Incoming messages format . . . .
Server configuration . . . . . . .
Adapter files . . . . . . . . .
SNMP event example. . . . .
Keywords . . . . . . . .
Object identifier file . . . . . .
Error file . . . . . . . . . .
Starting and stopping the adapter . .
Cold start . . . . . . . . .
Warm start . . . . . . . . .
Stopping the adapter . . . . . .
Events listing . . . . . . . . .
Rules listing . . . . . . . . . .
SNMP traps . . . . . . . . . .
Generic traps . . . . . . . .
Enterprise-specific traps . . . . .
Creating a new SNMP trap event. . .
BAROC file changes . . . . . .
Agent-independent data . . . .
Class definition statement file changes
Object identifier file changes . . .
Troubleshooting the SNMP adapter . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
143
143
143
143
143
144
144
144
144
145
145
145
146
146
146
146
146
148
148
148
148
149
150
150
152
153
154
Chapter 10. UNIX logfile adapter . . . 155

Event server configuration . . . . .
Starting the adapter . . . . . . .
Stopping the adapter . . . . . . .
Reloading the adapter configuration . .
Running multiple UNIX logfile adapters
Adapter files . . . . . . . . .
Format file . . . . . . . . .
Error file . . . . . . . . . .
Events listing . . . . . . . . .
Default rules . . . . . . . . .
Troubleshooting the UNIX logfile adapter
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
155
155
155
156
156
157
157
158
159
159
159
159
163
164
Contents
Chapter 11. Windows event log

adapter . . . . . . . . . . . . . . 167
Adapter files . . . . . . . . . . . .
Configuration file . . . . . . . . . .
Prefiltering Windows log events . . . .
Format file . . . . . . . . . . . .
Registry variables . . . . . . . . . . .
Low memory registry variables . . . . .
Starting the adapter . . . . . . . . . .
Stopping the adapter . . . . . . . . . .
Reloading the adapter configuration . . . . .
Running multiple Windows event log adapters .
Events listing . . . . . . . . . . . .
Event class structure . . . . . . . . .
tecad_win command . . . . . . . . . .
tecad_win . . . . . . . . . . . .
Troubleshooting the Windows event log adapter
.
.
.
.
.
.
.
.
.
.
.
.
.
.
167
168
172
173
173
176
176
177
177
177
178
178
180
181
182
Appendix A. Files shipped with

adapters . . . . . . . . . . . . . 183
Activating changes made with a format file .

Generating a new class definition statement
for a TME adapter. . . . . . . . .
Generating a new class definition statement
for a non-TME adapter . . . . . . .
Appendix C. Class definition

statement file reference . . . . . . . 197
File format . . . . . . . . . . . .
Operators . . . . . . . . . . . .
Class definition statement file details . . .
SELECT statement. . . . . . . . .
FETCH statement . . . . . . . . .
MAP statement . . . . . . . . . .
MAP_DEFAULT statement . . . . . .
Example . . . . . . . . . . . .
Object identifier to name translation . . . .
Class definition statement file syntax diagrams
Format file location .

Format specifications .
Log file example . .
Windows example . .
Mappings . . . .
Additional mapping
vi
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
considerations
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
187
187
189
191
191
193
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 207
Appendix D. Logfile Format Editor
197
197
198
199
200
201
201
201
202
202
207
Configuring a format file for a logfile adapter
Appendix B. Format file reference . . 187
. . 195
file
. . 195
file
. . 195
Notices . . . . . . . . . . . . . . 221
Trademarks .
. 223
Index . . . . . . . . . . . . . . . 225
About this guide

The IBM Tivoli Enterprise Console product is a rule-based, event management
application that integrates system, network, database, and application management
to help ensure the optimal availability of an organizations IT services. The IBM
Tivoli Enterprise Console Adapters Guide describes the currently available Tivoli
Enterprise Console adapters.
Who should read this guide

This guide is for Tivoli Enterprise Console administrators who install and
configure event adapters.
You should have prior knowledge of the following software:
v The operating systems that your enterprise uses
v The Tivoli Management Framework
v Adapter operating systems; for example, if you use an OpenView adapter, you
should be familiar with Hewlett-Packard OpenView.
Publications
This section lists publications in the Tivoli Enterprise Console library and related
documents. It also describes how to access Tivoli publications online and how to
order Tivoli publications.
IBM Tivoli Enterprise Console library

The following documents are available in the Tivoli Enterprise Console library:
v IBM Tivoli Enterprise Console Adapters Guide, SC32-1242
Provides information about supported adapters, including how to install and
configure these adapters.
v IBM Tivoli Enterprise Console Command and Task Reference, SC32-1232
Provides details about IBM Tivoli Enterprise Console commands, predefined
tasks that are shipped in the task library, and the environment variables that are
available to tasks that run against an event.
v IBM Tivoli Enterprise Console Installation Guide, SC32-1233
v
v
Describes how to install, upgrade, and uninstall the IBM Tivoli Enterprise
Console product.
IBM Tivoli Enterprise Console Release Notes, SC32-1238
Provides release-specific information that is not available until just before the
product is sent to market.
IBM Tivoli Enterprise Console Rule Developers Guide, SC32-1234
Describes how to develop rules and integrate them for event correlation and
automated event management.
IBM Tivoli Enterprise Console Rule Set Reference, SC32-1282
Provides reference information about the IBM Tivoli Enterprise Console rule sets.
IBM Tivoli Enterprise Console Users Guide, SC32-1235
vii
Provides an overview of the IBM Tivoli Enterprise Console product and

describes how to configure and use the IBM Tivoli Enterprise Console product to
manage events.
v IBM Tivoli Enterprise Console Warehouse Enablement Pack: Implementation Guide,
SC32-1236
Describes how to install and configure the warehouse enablement pack for the
IBM Tivoli Enterprise Console product and describes the data flow and
structures that are used by the warehouse pack.
v Tivoli Event Integration Facility Reference, SC32-1241
Describes how to develop your own event adapters that are tailored to your
network environment and the specific needs of your enterprise. This reference
also describes how to filter events at the source.
Related publications
The Tivoli Software Glossary includes definitions for many of the technical terms
related to Tivoli software. The Tivoli Software Glossary is available, in English only,
at the following Web site:
http://www.ibm.com/software/tivoli/library/
Access the glossary by clicking the Glossary link on the left pane of the Tivoli
software library window.
Accessing publications online

The documentation CD contains the publications that are in the product library.
The format of the publications is PDF, HTML, or both. Refer to the readme file on
the CD for instructions on how to access the documentation.
IBM posts publications for this and all other Tivoli products, as they become
available and whenever they are updated, to the Tivoli Software Information
Center Web site. Access the Tivoli Software Information Center by first going to the
Tivoli software library at the following Web address:
http://www.ibm.com/software/tivoli/library/
Scroll down and click the Product manuals link. In the Tivoli Technical Product
Documents Alphabetical Listing window, click the IBM Tivoli Enterprise Console
link to access the product library at the Tivoli Information Center.
Note: If you print PDF documents on other than letter-sized paper, select the Fit to
page check box in the Adobe Acrobat Print window. This option is available
when you click File Print. Fit to page ensures that the full dimensions of a
letter-sized page print on the paper that you are using.
Ordering publications
You can order many Tivoli publications online at the following Web site:
http://www.elink.ibmlink.ibm.com/public/applications/publications/
cgibin/pbi.cgi
You can also order by telephone by calling one of these numbers:
v In the United States: 800-879-2755
v In Canada: 800-426-4968
viii
In other countries, see the following Web site for a list of telephone numbers:
http://www.ibm.com/software/tivoli/order-lit/
Contacting software support

If you have a problem with any Tivoli product, refer to the following IBM Software
Support Web site:
http://www.ibm.com/software/sysmgmt/products/support/
If you want to contact software support, see the IBM Software Support Guide at the
following Web site:
http://techsupport.services.ibm.com/guides/handbook.html
The guide provides information about how to contact IBM Software Support,
depending on the severity of your problem, and the following information:
v Registration and eligibility
v Telephone numbers and e-mail addresses, depending on the country in which
you are located
v Information you must have before contacting IBM Software Support
Participating in newsgroups
User groups provide software professionals with a forum for communicating ideas,
technical expertise, and experiences related to the product. They are located on the
Internet and are available using standard news reader programs. These groups are
primarily intended for user-to-user communication and are not a replacement for
formal support.
To access a newsgroup, use the instructions appropriate for your browser.
Use these instructions for a Microsoft Internet Explorer browser.
1. Open an Internet Explorer browser.
2.
3.
4.
5.
6.
7.
From the Tools menu, click Internet Options.

On the Internet Options window, click the Programs tab.
In the Newsgroups list, click the Down Arrow and then click Outlook Express.
Click OK.
Close your Internet Explorer browser and then open it again.
Cut and paste the newsgroup address of a product into the browser Address
field, and press Enter to open the newsgroup.
Use these instructions for a Netscape Navigator browser.

1. Open a Netscape Navigator browser.
2. From the Edit menu, click Preferences. The Preferences window is displayed.
3. In the Category view, click Mail & Newsgroups to display the Mail &
Newsgroups settings.
4. Select the Use Netscape mail as the default mail application check box.
5. Click OK.
6. Close your Netscape Navigator browser and then open it again.
About this guide
ix
7. Cut and paste the newsgroup address of a product into the browser Address
field, and press Enter to open the newsgroup.
IBM Tivoli Enterprise Console:
news://news.software.ibm.com/ibm.software.tivoli.enterprise-console
IBM Tivoli NetView for UNIX and IBM Tivoli NetView for Windows:
news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows
Conventions used in this guide

This guide uses several conventions for special terms and actions, operating
system-dependent commands and paths, and command syntax.
Typeface conventions
This guide uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
v Keywords and parameters in text
Italic
v
v
v
v
Words defined in text

Emphasis of words (words as words)
New terms in text (except in a definition list)
Variables and values you must provide
Monospace
v Examples and code examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options
Operating system-dependent variables and paths

This guide uses the UNIX convention for specifying environment variables and for
directory notation.
When using the Windows command line, replace $variable with %variable% for
environment variables and replace each forward slash (/) with a backslash (\) in
directory paths.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
Command line syntax

This document uses the following special characters to define the command syntax:
[]
Identifies an optional argument. Arguments not enclosed in brackets are

required.
...
Indicates that you can specify multiple values for the previous argument.
Indicates mutually exclusive information. You can use the argument to the
left of the separator or the argument to the right of the separator. You
cannot use both arguments in a single use of the command.
{}
Delimits a set of mutually exclusive arguments when one of the arguments

is required. If the arguments are optional, they are enclosed in brackets ([
]).
For example:
wsetsrc [S server] [l label] [n name] source
The source argument is the only required argument for the wsetsrc command. The
brackets around the other arguments indicate that these arguments are optional.
Another example is the wlsac command:
wlsac [l | f format] [key... ] profile
In this example, the l and f format arguments are mutually exclusive and
optional. The profile argument is required. The key argument is optional. Also, the
ellipsis marks (...) following the key argument indicate that you can specify
multiple key names.
Another example is the wrb import command:
wrb import {rule_pack | rule_set} ...
In this example, the rule_pack and rule_set arguments are mutually exclusive, but
one of the arguments must be specified. Also, the ellipsis marks (...) indicate that
you can specify multiple rule packs or rule sets.
About this guide
xi
xii
Chapter 1. Introduction to adapters

Event adapters are software programs that collect information, perform local
filtering, and convert relevant events into a format that can be used by the Tivoli
Enterprise Console product. Because adapters are located on or near their event
sources and can perform local filtering of events, the adapters create a minimal
amount of additional network traffic. Adapters use a minimal amount of system
resources to perform their functions.
Network management applications have become an important part of monitoring
the availability of resources in the enterprise. The Tivoli Enterprise Console
product can seamlessly integrate alarms and events from all the major network
management operating systems and can correlate them with other system,
database, and application events.
Adapters are passive collectors of all types of events from systems and
applications, including the network management applications. All of your existing
network management configuration and monitoring of events can be preserved;
these events can simply be forwarded to the event server for correlation with other
events, where automated responses can be triggered or Information Technology
(IT) staff can be notified.
Adapter overview
An adapter is a process that monitors resources so that they can be managed. These
monitored resources are called sources. A source is an application (for example, a
database) or system resource (for example, an NFS server). When an adapter
detects an event generated from a source (generally called a raw event), it formats
the event and sends it to the event server. The event server then further processes
the event.
Adapters can monitor sources in the following ways:
v An adapter can receive events from any source that actively produces them. For
example, SNMP adapters can receive traps sent by the Simple Network
Management Protocol (SNMP).
v An adapter can check an ASCII log file for raw events at configured intervals if
the source updates a log file with messages.
Adapters can send events to the event server using a Tivoli interface or a
non-Tivoli interface. Both types of interfaces send events using an ordinary TCP/IP
channel. The difference between the two interfaces is the method used to establish
the connection. A Tivoli interface establishes a connection using the oserv services
provided by Tivoli Management Framework; adapters that use this interface are
referred to as TME adapters. A non-Tivoli interface establishes connections using
standard interprocess communication mechanisms (for example, opening an IP
socket); adapters that use this interface are called non-TME adapters.
Note: If you are sending events from an adapter using a Tivoli connection to an
event server in a remote Tivoli region, the connection must allow the
adapter to send information to the remote event server. The adapter should
be on the master side of a one-way connection or, more likely, the
connection should be a two-way connection. If you are sending events from

a non-TME adapter, the type of interconnection with the Tivoli regions does
not matter.
How adapters on endpoints send events

TME adapters installed on endpoints send their events to the lcfd process, which
then sends the events to a Tivoli Enterprise Console gateway, which in turn
bundles them up and forwards them on to an event server. A Tivoli interface is
used for communication between the endpoint and the gateway. The default
service to the server used by the Tivoli Enterprise Console gateway is a
connection-oriented service to the server. A connection-oriented service means that
a connection is established when the adapter is initialized and the connection is
maintained for all events to be sent. The Tivoli Enterprise Console gateway runs on
the same managed node as the Tivoli Management Framework gateway that is
providing the endpoint gateway service. The Tivoli Enterprise Console gateway
provides the following benefits:
v Greater scalability, meaning you can manage many sources easier, with less
software running on the endpoints.
v Greatly reduces the amount of communications tasks performed by the event
server or the Tivoli management region server, as the Tivoli Enterprise Console
gateway bundles a number of events before sending them to the event server.
This improves event server performance.
v Easier deployment of adapters and updates to adapters using profiles in the
Adapter Configuration Facility.
The TME adapters currently supported for an endpoint are as follows:
v UNIX log file
v OS/2
v SNMP
v Microsoft Windows event log
You can configure these adapters to send their events to specific primary,
secondary or both event servers, and the Tivoli Enterprise Console gateway
forwards them appropriately.
v If the Tivoli Enterprise Console gateway, Tivoli Management Framework
gateway, or lcfd process is down, events are buffered at the endpoint and are
sent again when communication is restored, as follows:
If the endpoint (lcfd process) is down, events are buffered at the endpoint.
When the endpoint is restarted and logs in to the Tivoli Management
Framework gateway, events are sent as usual.
If the Tivoli Management Framework gateway is down, events are buffered at
the endpoint. Events are not forwarded until the endpoint logs back in to the
Tivoli Management Framework gateway. This delay can be as much as 5
minutes after the Tivoli Management Framework gateway is restarted but can
be configured on the endpoint.
If the Tivoli Enterprise Console gateway is down (but the lcfd process or the
Tivoli Management Framework gateway are still up), the Tivoli Enterprise
Console gateway is restarted, and events are sent as usual.
v If an event server is down (but the Tivoli Enterprise Console gateway, Tivoli
Management Framework gateway, and lcfd processes are still up), events are
buffered at the Tivoli Enterprise Console gateway. They are sent again when
communication with the server is restored.
The following figure shows an example of the Tivoli Enterprise Console product
and Tivoli Management Framework component relationships in a network with
endpoints.
Event Server
Managed
Node
Managed
Node
Tivoli Availability
Intermediate
Manager
Managed
Node
Endpoint Gateway
Tivoli Enterprise
Console Gateway
Adapter Configuration
Facility
Adapters
Endpoints
Adapters
Endpoint Gateway
Tivoli Enterprise
Console Gateway
Adapter Configuration
Facility
Adapters
Endpoints
Adapters
Figure 1. Components relationships of the Tivoli Enterprise Console product and Tivoli
Management Framework
How adapters on managed nodes send events

For network management HP OpenView adapters, the managed node adapter
sends events directly to the event server using a Tivoli interface. In other words,
the oserv of the managed node that the adapter runs on sends the event to the
oserv of the event server when these are separate nodes, which then forwards it on
to the event server process.
For the UNIX logfile, OS/2, Windows, and SNMP TME adapters, a managed node
must also be configured as an endpoint to send events to the event server.
How non-TME adapters send events

A non-TME adapter sends events directly to the event server using an IP socket.
Internationalization support for events

The defaulting encoding that the following logfile adapters use to send their events
to the event server is UTF-8 encoding:
v UNIX logfile adapter
v NetWare logfile adapter
v OS/2 logfile adapter
v Windows event log adapter
To change the default configuration of these adapters so they send events in the
encoding of the event server host instead of UTF-8, the Pre37Server and
Pre37ServerEncoding configuration file options are provided. See Keywords on

page 10 for additional information about these options.
The event server can receive events in both UTF-8 encoding or the encoding of the
event server host. The event server automatically determines the type of encoding
(UTF-8 or non-UTF-8) of an event by evaluating a particular flag in the event data.
The adapter automatically reads the format file from the appropriate directory. If
the adapter is sending events to an event server running a version earlier than the
Tivoli Enterprise Console 3.7 product, the format files in the localization directories
must remain in English. See Format file on page 24 and Appendix B, Format file
reference, on page 187 for additional information.
Tivoli Event Integration Facility provides support for creating new adapters (other
than those shipped by the Tivoli Enterprise Console product) or modifying existing
adapters to send events to the latest version of the event server. Existing adapters
shipped in a previous release of the Tivoli Enterprise Console product do not
require updating; the new event server recognizes events sent from those adapters.
See the Tivoli Event Integration Facility Reference for additional information.
When a non-TME adapter is installed, a new codeset directory is created with the
bin and etc directories under the $TECADHOME directory. If you install an adapter
with an ID, the etc and codeset directories are created under the $TECADHOME/ID
directory
Event information and attributes

Event information is formatted as a set of attributes. Each attribute is predefined
and contains a name and value. Adapters separate information into event classes,
format this information into attributes, and send this information to the event
server. The event server then processes this information.
Event classes are a classification of events; do not confuse them with the term
classes in the traditional object-oriented sense. Event classes can be subclassed to
facilitate a further breakdown of information so that more detailed rules can be
applied to the information. In essence, event classes are an agreement between the
adapter and the event server about what information the adapter sends to the
event server for a given class.
After event information is separated into attributes and the event is categorized
into an event class, the adapter sends the information to the event server for
further processing. Adapters are configured to send information that only
administrators are interested in; that is, filters are established on the local system
that specify whether to discard an event or forward it to the event server. This
minimizes any network loading that is related to enterprise monitoring.
An event class name is followed by attribute information.
An adapter supplies information in the form of attributes. An attribute has the
following format:
attribute=value
The following list describes base event attributes that can be contained in an event
sent to the event server. Base event attributes are standard for most event classes
and are defined in the highest superclass of a basic recorder of objects in C
(BAROC) file. An adapter can also contain adapter-specific or user-defined

attributes.
Table 1. Base event attributes
Attribute Name
Contents
acl
The list of authorization roles that an administrator uses to modify

the event.
adapter_host
The host on which the adapter is running.
administrator
The administrator who acknowledged or closed the event.
cause_date_
reception
The cause_date_reception attribute is used to link an effect event to

its cause event. This value is set to the value of the date_reception
attribute of the cause event.
cause_event_ handle
The cause_event_handle attribute is used to link an effect event to

its cause event. This value is set to the value of the event_handle
attribute of the cause event.
credibility
Indicates how the event was sent from the adapter. The value is 1 if
an event was sent using a communications channel provided by
Tivoli Management Framework services, as is the case for a TME
adapter. The value is zero (0) if an event was sent from a non-TME
adapter.
date
The date and time the event was generated.
date_reception
A time stamp indicating the time the event server received the
event. It is an integer representing the number of seconds since the
epoch, which is January 1, 1970. This value is also used as a
component to uniquely identify an event. An event is uniquely
identified by a combination of the values for the date_reception,
event_handle, and server_handle attributes.
duration
For closed events, the age (in seconds) of the event from when it
was received by the event server until it was closed. For all
non-closed events, the value is zero (0).
Note: If an event was closed by calling the set_event_status
predicate from within a rule, this attribute is not modified to give
the age. The value remains at zero (0).
event_handle
A number used to reference the event. An event is uniquely

identified by a combination of the values of the date_reception,
event_handle, and server_handle attributes. Events received within
the same second are assigned an incremental number for this
attribute starting at 1 and increased by 1.
fqhostname
The fully qualified host name of the system where the event
originated.
hostname
The name of the system on which the event occurred.
msg
A text summary of the event.
msg_catalog
For future support of internationalized event messages; not

currently implemented.
msg_index
The message ID used to obtain the internationalized message.
num_actions
The number of actions (tasks or programs) currently being tracked

by the event server for this event.
origin
The protocol address or host name of the source system.
repeat_count
A counter for keeping track of the number of times a duplicate type

of event has been received.
Table 1. Base event attributes (continued)

Attribute Name
Contents
server_handle
A number identifying the event server that received this event. An

event is uniquely identified by a combination of the values for the
date_reception, event_handle, and server_handle attributes.
server_path
Stores information describing the rule engines that an event has

passed through. server_path has the following definition:
server_path list_of_strings;
Each element in the list represents one rule engine that the event
has visited, and each element contains a rule engine identifier,
server number, reception ID, and event handle. The following is an
example of a list:
chair 1 12121212 3
where:
chair
The rule engine identifier
The server number
12121212
The event reception ID in server 1
3
severity
The event handle for the event in server 1
The severity of the event. The database stores the severity as a

number. This mapping is defined in the root.baroc rule base file and
is set for the event server default severities as follows:
10
UNKNOWN
20
HARMLESS
30
WARNING
40
MINOR
50
CRITICAL
60
FATAL
You can also customize the severity settings.

source
The source of the event (for example, the OpenView adapter). The
source is defined by the adapter type.
Table 1. Base event attributes (continued)

Attribute Name
Contents
status
The status of an event. It is initially set to OPEN or to a default

value specified by the event class. Possible values during an event
lifetime are as follows:
ACK
An administrator or rule has acknowledged the event.
CLOSED
An administrator or rule has fixed the problem that was
reported by the event. An event adapter can also send an
event with a status of CLOSED to indicate that a
previously received event of the specified class should
have its status changed to CLOSED; the previously
received event to be closed is the most recent duplicate of
the same event. The event being sent with a CLOSED
status is dropped and not stored in the event database.
custom_status
A status that has been added to the STATUS enumeration
for site-specific purposes. The STATUS enumeration is
defined in the root.baroc file. To add a new status, edit this
file, recompile the rule base, and restart the event server.
OPEN
The event has been received by the event server, but no

administrator or rule has acknowledged it.
RESPONSE
A rule has automatically responded to the event. This
status is assigned a rule language predicate. It is not
available from an event console.
The database stores the status as a number. This mapping is defined
in the root.baroc rule base file and is set for the event server default
status as follows: zero (0) for OPEN, 10 for RESPONSE, 20 for ACK,
30 for CLOSED.
sub_origin
A further categorization of the origin. This attribute is optional.
sub_source
A further categorization of the source. This attribute is optional.
The adapter uses the following attributes to uniquely identify an event:

v date_reception
v event_handle
v server_handle
Adapter files
An adapter uses various files for its operations. The following table provides a
brief description of the types of files that can be used. Subsequent sections describe
some of the more common files you might need to view or modify for
configuration or troubleshooting purposes. See Appendix A, Files shipped with
adapters, on page 183 for detailed information about which files are shipped with
particular adapters.
Table 2. Adapter files
File Type
Description
Basic recorder of objects in C

(BAROC)
Defines event classes to the event server; must be

part of the rule base.
Table 2. Adapter files (continued)

File Type
Description
Cache
Stores buffered events.
Class definition statement (CDS)
Defines event class definitions to the adapter.
Configuration
Defines configuration options for adapters.
Error
Defines error logging and tracing options for the

adapter.
Format
Defines the format of messages and matches them to

event classes for the UNIX logfile, NetWare logfile,
OS/2, and Windows event log adapters.
Installation script
Configures the adapter to start when the operating

system starts.
Object identifier
Defines object-identifier-to-name mappings for the

NetView/6000, OpenView, and SNMP adapters.
Registration
The registration file generated by the installation

script for NetView/6000 and OpenView.
Rules
Defines rules to the event server; must be part of the

rule base.
An adapter uses the Tivoli Management Framework TIVOLI_COMM_DIR

environment variable, if set, to determine which directory to use for its lock and
pipe files. If the variable is not set, the /tmp/.tivoli directory is used instead. For
more information about this environment variable, see the Tivoli Management
Framework Release Notes.
Cache file
Events are written to the cache file using a circular method; when the cache file
has reached the size limit set by the BufEvtMaxSize keyword, the next new event
is written to the beginning of the cache file (thus overwriting the existing data at
that location). Subsequent events continue being written in order until the end of
the file is reached again, and the process starts over from the beginning of the file.
A small header at the beginning of the file tracks where the next new event is to be
written and where the next old event is to be removed.
The format of the cache file is as follows:
maxsz: XXXXXXXXXX
head : XXXXXXXXXX
tail : XXXXXXXXXX
........................event1 event2
event3 event4 event5.................
.....................................
.....................................
.....................................
The first three lines in the cache file all have a fixed size of 18 bytes and contain
the following data:
maxsz The maximum size of the cache file.
head
The byte offset from the beginning of the file to the next event to send. A
value of zero (0) indicates an empty cache file.
tail
The byte offset from the beginning of the file to the first byte of free space
in the file.
The boundaries between events in the cache file are indicated by a ^A character at
the end of each event.
Configuration file
Most adapters come with a configuration file containing configuration options and
filters. This file is read by an adapter when it is started. By modifying this file, you
can reconfigure an adapter at anytime, without having to modify the adapter
source code. To have your configuration changes take effect, simply stop and
restart the adapter. A configuration file usually has an extension of .conf; see each
specific adapter chapter for exact file names.
File location
An adapter expects its configuration file (along with its format, CDS, and error
files) to be located in the default locations shown in the following table. For
Windows, the syntax shown is correct when running the bash interpreter.
Table 3. Location of adapter configuration files
Adapter Type
Node Type
Location
TME
Managed node
$BINDIR/TME/TEC/adapters/etc/ or
/etc/Tivoli/tecad/etc (which is a link to the TME
adapter directory)
Endpoint
$LCFROOT/bin/$INTERP/TME/TEC/adapters/etc or
/etc/Tivoli/tecad/etc (which is a link to the TME
adapter directory)
Not applicable
path/etc where the adapter was manually installed or

/etc/Tivoli/tecad/etc (which is a link to the non-TME
adapter directory)
non-TME
For information about directory structures and system variables (those beginning
with $), see the Tivoli Management Framework Planning for Deployment Guide.
File format
Each non-blank line that does not begin with the comment sign (#) is of one of the
following forms:
v To specify configuration options:
keyword=value
v To specify event filters:
Filter:Class=class_name;attribute=value;
v To specify event buffer filters:
FilterCache:Class=class_name;attribute=value;
Example
#
# Communication Parameters
#
TransportList=t1,t2_
t1Type=SOCKET
t1Channels=c1_,c2
c1_ServerLocation=host1
c1_Port=5529
c2ServerLocation=host2
c2Port=5529
t2_Type=LCF
t2_Channels=c3_
c3_ServerLocation=@EventServer
#
# Event Filters
#
Filter:Class=disk_event
Filter:Class=Su_Success;origin=126.32.2.14
Keywords
Keywords use the following format: keyword=value
Type each keyword on a separate line. Do not use blank spaces in keyword
statements unless enclosed in single quotation marks; however, you cannot use
quotation marks at all with the HPOVFilter keyword for the HP Openview
adapter. Do not use class names that are not defined in a BAROC file with
configuration options.
Note: Adapters do not issue error messages for misspelled keywords or keywords
set to a value that is not valid.
A configuration file can contain the following keywords, which are common to
most adapters.
Note: Not all keywords apply to all adapters, and some adapters have additional
keywords specific to them. See each specific adapter chapter for descriptions
of these keywords.
AdapterCdsFile=path
Specifies the full path name of the CDS file. This keyword is required if the
CDS file is not in the same directory as the configuration file.
AdapterErrorFile=path
Specifies the full path name of the error file. This keyword is required if
the error file is not in the same directory as the configuration file.
APPEND_CLASSPATH=string
Specifies the string that is appended to the CLASSPATH environment
variable before the Java-based State Correlation is called. The string is
appended using the appropriate delimiter:, semicolon (;) for Windows
systems or colon (:) for UNIX systems. The string must contain valid data
for your environment; for example, APPEND_CLASSPATH=c:
\my_product\my_java.class; d: \my_product\my_jar .jar for Windows
systems or APPEND _CLASSPATH=/my_product/my_java.class:
/my_product/my_jar.jar for UNIX systems.
For the Tivoli Enterprise Console gateway the specified string is
appeneded to the list of jar files needed for State Correlation. For an
adapter written in C, the specified string is appended to the system
environment CLASSPATH.
Note: The system environment CLASSPATH is not changed. This
CLASSPATH information is passed to Java during the State
Correlation initialization. This keyword can be specified only once in
your configuration file.
APPEND_JVMPATH=string
Specifies the string that is appended to the dynamic library path
environment variable before the Java-based state correlation is called. The
string is appended using the appropriate delimiter: semi-colon (;) for
10
Windows systems or colon (:) for UNIX systems. The string must contain
valid data for your environment; for example, APPEND_JVMPATH=
c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows
systems or APPEND_JVMPATH=
/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. This
keyword is valid only for adapters written in C and is appended to the
appropriate dynamic library path environment variable. For the
environment variable for each operating system, see the information about
library paths and directories for endpoint adapters developed with the
Event Integration Facility Java API in the Tivoli Event Integration Facility
Reference.
Note: The system dynamic library path environment variable is not
changed. This keyword can be specified only once in your
configuration file.
BufEvtMaxSize=size
Specifies the maximum size, in kilobytes, of the adapter cache file. The
default value is 64. The cache file stores events on disk when they cannot
be sent to the event server.
The BufEvtMaxSize keyword is optional.
BufEvtPath=pathname
Specifies the full path name of the adapter cache file. On endpoint
adapters, the BufEvtPath keyword uses the $TIVOLIHOME variable to
resolve differences in file locations and drive letters across various
environments. The variable uses a path relative to the endpoint installation.
The Adapter Configuration Facility defines $TIVOLIHOME on each
endpoint; you cannot change its value.
Table 4. Path name and variable for adapter cache
Operating System
Default Path
$TIVOLIHOME Value
UNIX
$TIVOLIHOME/tec/cache
/etc/Tivoli
Microsoft Windows %TIVOLIHOME%\tec\

cache.dat
%SystemRoot%\system32\
drivers\etc\Tivoli
The AS/400 adapters do not use this keyword.

This is a required keyword when the BufferEvents keyword is set to YES.
If the UseStateCorrelation keyword is set to YES, the BufEvtPath keyword
also specifies the path to store events for state correlation. Tivoli Event
Integration Facility adds the prefix _sc to the specified file name. The
prefix differentiates the adapter cache file from the event storage path for
state correlation. The default value for the path is
$TIVOLIHOME/tec/cache_sc for UNIX systems and
%TIVOLIHOME%\tec\cache_sc.dat for Windows systems.
Note: If more than one application on the same system uses Tivoli Event
Integration Facility, ensure that each application has unique values
for the path name.
BufferEvents=YES | NO
Specifies how event buffering is enabled.
YES
Stores events in the file specified by the BufEvtPath keyword.

11
NO
Does not store or buffer events.
If UseStateCorrelation=YES and BufferEvents=YES, the API also stores

events in files that are specified with the BufEvtPath keyword. The
StateCorrelationMaxFileSize and StateCorrelationTotalSize keywords
control the size and number of files.
The value is not case-sensitive. The default value is YES. This keyword is
optional.
BufferFlushRate=events_per_minute
Specifies the number of events that are sent per minute. Once the adapter
has recovered the lost connection, and there are events in the buffer, the
events are sent at this rate per minute. The default value is 0 ;
consequently all events are sent in one burst.
This keyword is optional.
ConnectionMode=connection_oriented | connection_less
Specifies the connection mode to use to connect to the Tivoli Enterprise
Console gateway or the event server. The default value is connection_less,
except for the Tivoli Enterprise Console gateway, which has
connection_oriented as the default value.
connection_oriented
A connection is established at adapter initialization and is
maintained for all events sent. A new connection is established
only if the initial connection is lost. The connection is discarded
when the adapter is stopped. This option can be abbreviated to co
or CO.
connection_less
A new connection is established and discarded for each event or
group of events that is sent.
ed_diag_config_file=filename
The filename file must be present for logging and tracing to occur. To enable
logging, specify error or warning in the filename file. To enable tracing,
specify trace0, trace1, or trace2 in the filename file. The filename file can
be either fully qualified or relative to the directory where the adapter is
running. A sample file, .ed_diag_config, is in the EIFSDK directory on the
IBM Tivoli Enterprise Console TME New Installations CD.
Each level of logging or tracing also includes all levels below it. For
example, when you specify warning logging, error logging automatically is
enabled.
Note: Be aware that increasing the level of tracing produces a large trace
output. You can configure whether or not the file is recreated on
restarts.
Filter
12
Works with the FilterMode keyword to determine how events are filtered.
An event matches a Filter statement when each attribute=value pair in the
Filter statement is identical to the corresponding attribute=value pair in the
event.
A Filter statement must contain the event class, and optionally can include
any other attribute=value pair that is defined for the event class. The format
of a filtering statement is as follows:
Filter:Class=class_name;[attribute=value;...;attribute=value]
Each statement must be on a single line. The attribute=value pair is case

sensitive.
FilterCache
Works with the FilterMode and Filter keywords to determine which events
are stored in the cache when events cannot be sent successfully to the
event server. To store events in the cache, you must set BufferEvents=YES.
An event matches a FilterCache statement when each attribute=value pair in
the FilterCache statement is identical to the corresponding attribute=value
pair in the event.
A FilterCache statement must contain the event class (class_name) and can
include any attribute=value pair that is defined for that event class. The
format of a filtering statement is as follows:
FilterCache:Class=class_name;[attribute=value;...;attribute=value]
Each statement must be on a single line. The attribute=value pair is case

sensitive. You must specify the Filter keyword, when you use the
FilterCache keyword. Additionally, the FilterCache statement must specify
the same class or subset of classes that the Filter statement specifies.
Note: When using the FilterCache keyword with endpoint adapters and
the Tivoli Enterprise Console gateway, you must set the filtering
statements at both locations to the same specifications.
FilterMode=IN | OUT
Specifies whether events that match a Filter or FilterCache statement are
sent to the event server (FilterMode=IN) or discarded (FilterMode=OUT).
The default value is OUT. The valid values are IN or OUT, without regard
for case. If you set FilterMode=IN, you must have one or more Filter and
FilterCache statements defined.
For information about how to use filtering keywords to send, cache, and
discard events, see Event filtering on page 21.
FQDomain= YES | NO | fqdomain
Specifies how the adapter should set the value of the fqhostname attribute
of events sent to the event server. This attribute is used to specify the fully
qualified host name of the originating host. Possible values for this
keyword are:
YES
The adapter attempts to determine the fully qualified host name. If

this is successful, the fqhostname attribute is set to this value; if
not, the attribute has a null value.
NO
The fqhostname attribute has a null value. This is the default value
if the FQDomain keyword is not specified.
13
fqdomain
fqdomain is appended to the host name, and the resulting string is
used as the value of the fqhostname attribute. If the host name
contains periods (meaning that it is already fully qualified),
fqdomain is not appended.
Note: This keyword is valid only for the OpenView, SNMP, UNIX log file,
and Windows event log adapters.
getport_timeout_seconds=num_seconds
Specifies the number of seconds to wait before re-sending the UDP call for
a port, if no response is heard. It re-transmits until the RPC call times out.
The default value is zero (0) seconds.
getport_timeout_usec=num_microseconds
Specifies the number of microseconds to add to the seconds specified with
the getport_timeout_seconds keyword. The default value is 50 000
microseconds.
getport_total_timeout_seconds=num_seconds
Specifies the number of seconds to wait on getting a port after making a
call to the portmapper. The default value is zero (0) seconds.
getport_total_timeout_usec=num_microseconds
Specifies the number of microseconds to add to the seconds specified with
the getport_total_timeout_seconds keyword. The default value is 50 000
microseconds.
LogFileName=pathname
Specifies the full path name of the log file for the Java API. The default
location for the file is $TIVOLIHOME/tec/eif.log.
If UseStateCorrelation=YES, the LogFileName keyword also defines the
path to store the log file for state correlation. Tivoli Event Integration
Facility adds the prefix _sc to the specified file name. The prefix
differentiates the log file for the Java API from the log file for state
correlation. The default value for the path is
$TIVOLIHOME/tec/eif_sc.log.
If you specify a non-valid path name, the API returns the following error:
LOG0014E Unable to open the handler output file <filename>.
java.io.FileNotFoundException: <filename> (The system cannot find
the path specified)

LogLevel=level
Specifies whether the Java API generates log messages or not. By default,
no messages are generated. Specify ALL to generate messages. If you
specify any other value or no value, the API does not generate messages.
MaxPacketSize=bytes
Specifies the number of bytes to be sent at the rate specified by the
BufferFlushRate keyword. The default value is zero (0), where one event is
sent at a time.
NO_UTF8_CONVERSION=YES | NO
Specifies whether Tivoli Event Integration Facility encodes event data in
14
UTF-8. When this keyword is set to YES, Tivoli Event Integration Facility
does not encode event data in UTF-8. The data is assumed to already be in
UTF-8 encoding when passed to Tivoli Event Integration Facility. It does,
however, prepend the flag indicating that the data is in UTF-8 encoding if
the flag does not exist at the beginning of the event data.
This keyword is optional. The default value for this keyword is NO.
Pre37Server=YES | NO
Specifies whether the adapter sends events in the encoding of the event
server host or in UTF-8 encoding. Event server host versions earlier than
the Tivoli Enterprise Console 3.7 product do not support UTF-8 encoding
of events. The following values are not case-sensitive:
YES
Disables UTF-8 encoding and allows the adapter to communicate

with event server host versions earlier than the Tivoli Enterprise
Console 3.7 product. When this keyword is set to YES, you must
also specify the Pre37ServerEncoding keyword.
NO
The adapter sends events in UTF-8 encoding. The default value is

NO.

Pre37ServerEncoding=language
Determines which language to use when a non-TME adapter
communicates with a non-UTF-8 event server host (versions earlier than
the Tivoli Enterprise Console 3.7 product). This keyword is active only
when the Pre37Server keyword is set to YES.
PREPEND_CLASSPATH=string
Specifies the string that is prepended to the CLASSPATH environment
variable before the Java based State Correlation is called. The string is
prepended using the appropriate delimiter: semicolon (;) for Windows
systems or colon (:) for UNIX systems. The string must contain valid data
for your environment; for example, PREPEND_CLASSPATH=c:
\my_product\my_java.class; d: \my_product\my_jar .jar for Windows
systems or PREPEND _CLASSPATH=/my_product/my_java.class:
/my_product/my_jar.jar for UNIX systems.
For the Tivoli Enterprise Console gateway the specified string is prepended
to the list of jar files needed for State Correlation. For an adapter written in
C, the specified string is prepended to the system environment
CLASSPATH.
Note: The system environment CLASSPATH is not changed. This
CLASSPATH information is passed to Java during the State
Correlation initialization. This keyword can be specified only once in
your configuration file.
PREPEND_JVMPATH=string
Specifies the string that is prepended to the dynamic library path
environment variable before the Java-based state correlation is called. The
string is prepended using the appropriate delimiter: semicolon (;) for
Windows systems or colon (:) for UNIX systems. The string must contain
valid data for your environment; for example, PREPEND_JVMPATH=
c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows
15
systems or PREPEND_JVMPATH=
/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. This
keyword is valid only for adapters written in C and is prepended to the
appropriate dynamic library path environment variable. For the
environment variable for each operating system, see the information about
library paths and directories for endpoint adapters developed with the
Event Integration Facility Java API in the Tivoli Event Integration Facility
Reference.
Note: The system dynamic library path environment variable is not
changed. This keyword can be specified only once in your
configuration file.
RetryInterval=timeout
When ConnectionMode=connection_oriented, and the connection to the
event server is lost, an adapter waits the specified number of seconds
before re-attempting to connect to the primary or secondary servers, or to
buffer the events. While the adapter is waiting for the expiration of this
interval, no new events are processed by the adapter.
This option allows an adapter to send all events to the primary event
server even if the primary event server is stopped briefly, such as when
loading a new rule base.
If you use this keyword to wait for restarting an event server, set the value
for a period of time longer than necessary for the event server to be
stopped and then restarted.
This keyword is optional. The default value is 120 seconds.
ServerLocation=host
Specifies the name of the host on which the event server or Tivoli
Enterprise Console gateway is installed. The value of this field must be one
of the formats shown in Table 5, depending on whether the adapter is a
TME adapter or a non-TME adapter, and whether the event server is part
of an interconnected Tivoli management region:
Table 5. Formats for the ServerLocation keyword
Adapter Type
Format
TME
@EventServer
TME in an interconnected
Tivoli management region
@EventServer#region_name
non-TME
host_name or IP_address. Use the dotted format

for IP_address.
For TME adapters on managed nodes and non-TME adapters, the

ServerLocation keyword can contain up to eight values, separated by
commas. The first location is the primary event server, while others are
secondary servers to be used in the order specified when the primary
server is down.
For endpoint adapters, secondary event servers, if any, are defined in the
Tivoli Enterprise Console gateway configuration file. Only specify a
primary event server in the configuration file for an endpoint adapter.
16
For a non-TME adapter, the default value is localhost. For a TME adapter
on a managed node, the default value is @EventServer. A TME adapter on
an endpoint, by default, uses the configuration on the Tivoli Enterprise
Console gateway. See the IBM Tivoli Enterprise Console Users Guide for
more information about the Tivoli Enterprise Console gateway.
For endpoint adapters, if you use an IP name or address in the
ServerLocation value, then the Tivoli Enterprise Console gateway uses that
value to send the event using non-Tivoli communication to the server.
For non-TME adapters, the ServerLocation keyword can contain the IP
name or address of the Tivoli Enterprise Console gateway if reception of
events from non-TME adapters is enabled at this gateway.
The ServerLocation keyword is optional and not used when the
TransportList keyword is specified.
Note: The ServerLocation keyword defines the path and name of the file
for logging events, instead of the event server, when used with the
TestMode keyword.
ServerPort=number
Specifies the port number on which the event server or Tivoli Enterprise
Console gateway listens for events. Set this keyword value to 0, the default
value, unless the portmapper is not available on the event server, which is
the case if the event server is running on a Microsoft Windows system or
the event server is a Tivoli Availability Intermediate Manager (see the
following note). If the port number is specified as zero (0) or it is not
specified, the port number is retrieved using the portmapper.
Note: Portmapper is not supported for reception of events from non-TME
adapters at the Tivoli Enterprise Console gateway. If your non-TME
adapter is sending events to this gateway, then you must code the
ServerPort keyword to match the value in the gwr_ReceptionPort
keyword in the Tivoli Enterprise Console gateway configuration file.
The ServerPort keyword can contain up to eight values, separated by
commas. For non-TME adapters that send events to a UNIX event server,
use the default value of 0 (only one value of 0, even if multiple UNIX
event servers are specified with the ServerLocation keyword). For
non-TME adapters that send events to a Windows event server or a Tivoli
Availability Intermediate Manager, specify one value for each event server
defined with the ServerLocation keyword.
The ServerPort keyword is optional when the event server is running on
the UNIX operating system, but mandatory when running on Windows
operating system. It is not used when the TransportList keyword is
specified.
Note: If the event server is running on Windows operating system: There is no
portmapper daemon on a Windows system that allows the adapter
to query the reception port at run time. The event server listens on a
fixed reception port (tec_recv_agent_port in .tec_config file) for
connection and adapter input. Set the ServerPort keyword to the
value of the tec_recv_agent_port entry in the .tec_config file in the
$BINDIR/TME/TEC directory. The default value is 5529. The Tivoli
17
Availability Intermediate Manager never uses the portmapper; the

Tivoli Availability Intermediate Manager server listens on a fixed
port set in the Tivoli Availability Intermediate Manager graphical
user interface.
StateCorrelationCleaningInterval=milliseconds
Specifies, in milliseconds, how often state correlation removes unnecessary
entries from its event storage files. The default value is one minute.
StateCorrelationConfigURL=pathname
Specifies the directory and file name where the configuration for state
correlation is stored. On Windows systems, an example of the path is as
follows: file:C:\work_dir\tstate\tecroot.xml. On UNIX systems, an
example of the path is as follows: file:///work_dir/tstate/tecroot.xml.
This keyword is required when the UseStateCorrelation keyword is set to
YES.
StateCorrelationMaxFileSize=kilobytes
Specifies the maximum size, in kilobytes, for each event storage file created
by state correlation. This is an approximate value, due to the variable size
of events.
StateCorrelationTotalSize=kilobytes
Specifies the maximum value, in kilobytes, allowed for the entire caching
mechanism for state correlation. This is an approximate value, due to the
variable size of events.
Note: The value must be at least double the value specified for the
StateCorrelationMaxFileSize keyword. Thus, the doubled value can
support at least two files:
v Current event cache file, persist1.out
v At least one file holding archived events, archive1.out
When calculating disk space for this cache, verify that you have a buffer of
10% of the specified values, with a minimum of 4 KB. This configuration
ensures that the cache does not run out of disk space.
When the state correlation cache reaches its limit (the value specified by
this keyword), the following occurs:
1. All subsequent events return a suspend exception to Tivoli Event
Integration Facility. In turn, Tivoli Event Integration Facility returns an
error to the application.
2. A forced cleanup of the cache is started; all removed events are
eliminated from the persistence cache.
3. Remaining events are recovered and returned to Tivoli Event
Integration Facility. Then, Tivoli Event Integration Facility forwards
those events.
4. The state correlation cache is re-initialized, and event processing
resumes.
18
TestMode=YES | NO
Specifies whether test mode is turned on or off. When TestMode=YES, the
ServerLocation keyword specifies the file to which events are logged,
instead of being sent to the event server. Valid values are YES and NO,
without regard to case. The default value is NO.
The TestMode keyword is optional.
TraceFileName=pathname
Specifies the full path name of the trace file for the Java API. The default
location of the file is $TIVOLIHOME/tec/eif.trc.
If the UseStateCorrelation keyword is set to YES, the TraceFileName
keyword also defines the path to store tracing for state correlation. Tivoli
Event Integration Facility adds the prefix to the specified file name. The
prefix differentiates the trace file for the Java API from the trace file for
state correlation. The default value for the path is
$TIVOLIHOME/tec/eif_sc.trc.
If you specify a non-valid path name, the API returns the following error:
LOG0014E Unable to open the handler output file <filename>.
java.io.FileNotFoundException: <filename> (The system cannot find
the path specified)

TraceLevel=level
Specifies whether the Java API generates trace messages or not. By default,
no messages are generated. Specify ALL to generate messages. If you
specify any other value or no value, the API does not generate messages.
TransportList=type_name,...
Specifies the user-supplied names of the transport mechanisms, separated
by commas. When a transport mechanism fails for sender applications, the
API uses the following transport mechanisms in the order specified in the
list. For receiving applications, the API creates and uses all the transport
mechanisms.
Note: This keyword is supported only for Solaris, HP, AIX, Linux, and
Windows adapters. It is not supported for other adapters.
This keyword is optional. If it is specified, the transport type and channel
for each type_name must be specified using the Type and Channels
keywords:
type_nameType=LCF | SOCKET | TME
Specifies the transport type for the transport mechanism specified
by the TransportList keyword.
This keyword is required.
The server and port for each channel_name are specified by the
ServerLocation and Port keywords.
type_nameChannels=channel_name,...
Specifies the user-supplied names of the channels for the transport
mechanism specified by the TransportList keyword, separated by
commas.
This keyword is required.
19
Depending on the Type specified (LCF, SOCKET, or TME), also use

one or more of the following keywords:
channel_namePort=number
Specifies the port number on which the transport
mechanisms server listens for the specified channel (set by
the Channel keyword). When this keyword is set to zero
(0), the portmapper is used. This keyword is required
when the Type keyword is set to SOCKET. It is optional for
endpoint adapters.
channel_namePortMapper=YES
Enables the portmapper for the specified channel. This
optional keyword is valid only when the transport type is
set to SOCKET.
channel_namePortMapperName=name
If the portmapper is enabled, specifies the name of the
portmapper. This optional keyword is valid only when the
transport type is set to SOCKET.
channel_namePortMapperNumber=rpc_id
Specifies the ID registered by the remote procedure call.
This optional keyword is valid only when the transport
type is set to SOCKET.
channel_namePortMapperVersion=version_number
If the portmapper is enabled, specifies the version of the
portmapper. This optional keyword is valid only when the
transport type is set to SOCKET.
channel_nameServerLocation=server[region]
Specifies the name of the event server and region on which
the server for transport mechanisms is located for the
specified channel. The channel is set by the Channel
keyword. This keyword is required when the Type
keyword is set to TME, LCF, or SOCKET. See Table 5 on
page 16 for valid formats of the server and region fields.
channel_nameTMEHost=hostname
For the Java API only, specifies the host name of the
managed node where the event server resides. This is a
required keyword when the Type keyword is set to TME.
channel_nameTMEPassword=password
For the Java API only, specifies the password for the Tivoli
administrator used to connect to the managed node. This
keyword is required when the Type keyword is set to TME.
channel_nameTMEPort=number
For the Java API only, specifies the port number for the
managed node. The default value for this keyword is 94.
This keyword is required when the Type keyword is set to
TME.
channel_nameTMEUserID=name
For the Java API only, specifies the Tivoli administrator for
the managed node. The required authorization role is user.
This keyword is required when the Type keyword is set to
TME.
20
UseStateCorrelation=YES | NO
Specifies if the API calls the state correlation engine. The default value is
NO. If this keyword is set to YES, the BufferEvents and BufEvtPath
keywords control state correlation.
WIDTHSTRMEANING=YES | NO
Indicates how the length modifier is interpreted, as follows:
NO
Interprets the length modifier as a truncation indication; that is, it

matches the full string and truncates the associated variable to the
length specified. This is the default value.
YES
Interprets the length modifier as in Tivoli Enterprise Console,

Version 3.6.x, that is, as an exact specification of the length of the
string to match.
Event filtering
Usually, an adapter sends all events to the event server. You can optionally specify
events that can or cannot be sent to the event server. You can do this by specifying
the event class and such information as the origin, severity, or any other
attribute=value pair that is defined for the event class. The class name specified for
an event filter entry must match a defined class name; an adapter does not
necessarily have knowledge of the class hierarchy.
Depending on how you specify the Filter and FilterMode keywords, filtered events
are either sent to the event server or discarded.
v To
1.
2.
v To
send specific events to the event server:

Set FilterMode to IN.
Create Filter statements to match the specific events that you want sent.
discard specific events:
1. Set FilterMode to OUT (the default value).

2. Create Filter statements to match the specific events that you want discarded.
v To send all events to the event server (the default behavior):
1. Set FilterMode to OUT.
2. Do not specify any Filter statements.
Note: All events are discarded when the configuration is as follows:
1. FilterMode is set to IN.
2. No Filter statements are specified.
To use non-English characters in a Filter statement, you must enter the non-English
characters in the local encodings.
Regular expressions in filters: You can also use Tcl regular expressions in
filtering statements. The format of a regular expression is re:value_fragment.
Note: Tivoli Event Integration Facility uses an exception to the Tcl regular
expression syntax. The backslash character (\) in Tivoli Event Integration
Facility indicates that the following literal character is the character to filter
for, not some special character such as a tab. For example, \t means the tab
character in Tcl, but means t in Tivoli Event Integration Facility.
The following example shows a Filter statement with a regular expression. This
filter statement matches any event whose class name begins with TEC_:
21
Filter:Class=re:TEC_.*
The following example shows a FilterCache statement with a narrower range. This
filter statement matches any event whose class name begins with TEC_ and whose
severity is CRITICAL:
FilterCache:Class=re:TEC_.*;severity=CRITICAL
For more information about Tcl regular expressions, see a Tcl users guide.
Event filter examples: The following table shows some event filter examples for a
few different adapters:
Table 6. Event filter examples
Adapter
Example
AS/400 Alert
The following entry matches all events of the

SNA_Equipment_Malfunction class from the origin 1.2.3.4:
Filter:Class=SNA_Equipment_Malfunction;origin=1.2.3.4
UNIX Logfile
The following entry matches all events of the Su_Success class from
the origin 126.32.2.14:
Filter:Class=Su_Success;origin=126.32.2.14
OpenView
The following entry matches all events of the OV_Message class from
the origin 126.32.2.14:
Filter:Class=OV_Message;origin=126.32.2.14
Windows
The following entry matches all events of the NT_Power_Failure class

from the origin 126.32.2.14:
Filter:Class=NT_Power_Failure;origin=126.32.2.14
Event buffer filtering

When an adapter is unable to connect to the event server or Tivoli Enterprise
Console gateway, it sends the events to a file if the BufferEvents keyword is set to
YES. You can filter events sent to a cache file, similar to filtering events for the
event server by using the FilterCache keyword.
There are no default event cache filters in the configuration files shipped with
adapters.
The following procedures describe how to filter events with the FilterCache and
FilterMode keywords, when the event server is unavailable:
v To cache specific events:
1. Set FilterMode to IN.
2. Set BufferEvents to YES (the default value).
3. Create Filter and FilterCache statements to match the specific events that you
want cached.
v To discard specific events:
2. Create Filter and FilterCache statements to match the specific events that you
want discarded.
v To cache all events (the default behavior):
2. Set BufferEvents to YES.
3. Do not specify any FilterCache statements.
22
Note: All events are discarded when the configuration is as follows:

1. FilterMode is set to IN.
2. No FilterCache statements are specified.
Event buffer filter examples: The following table shows some event buffer filter
examples for a few different adapters:
Table 7. Event buffer filter examples
Adapter
Example
AS/400 Alert The following entry matches all events of the SNA_Equipment_Malfunction
class from the origin 1.2.3.4:
FilterCache:Class=SNA_Equipment_Malfunction;origin=1.2.3.4
UNIX Logfile The following entry matches all events of the Su_Success class from the
origin 126.32.2.14:
FilterCache:Class=Su_Success;origin=126.32.2.14
OpenView
The following entry matches all events of the OV_Message class from the
origin 126.32.2.14:
FilterCache:Class=OV_Message;origin=126.32.2.14
Windows
The following entry matches all events of the NT_Power_Failure class from
the origin 126.32.2.14:
FilterCache:Class=NT_Power_Failure;origin=126.32.2.14
BAROC file
Each adapter comes with a BAROC file describing the classes of events the adapter
supports. This file is not used by the adapter itself, but serves as a mandatory link
between the adapter and the event server. The event server must load this file
before it is able to understand events received from the adapter. A BAROC file has
an extension of .baroc; see each specific adapter chapter for exact file names. The
format of a BAROC file is described in the IBM Tivoli Enterprise Console Rule
Developers Guide.
The following fragment shows how an event class for reporting SNMP
authentication problems could be defined in a BAROC file:
CLASS AUTHENTICATION_FAILURE ISA EVENT
DEFINES {
source:default="SNMP";
sub_source:default="NET";
auth_source:STRING;
};
END
Rule file
Some adapters come with a rule file describing the classes of events the adapter
supports. This file is not used by the adapter itself, but serves as a mandatory link
between the adapter and the event server. The event server must load this file
before it is able to understand events received from the adapter. A rule file has an
extension of .rls; see each specific adapter chapter for exact file names. The format
of a rule file is described in the IBM Tivoli Enterprise Console Rule Developers Guide.
The following fragment shows how an event class for reporting SNMP
authentication problems could be defined in a BAROC file:
23
CLASS AUTHENTICATION_FAILURE ISA EVENT

DEFINES {
source:default="NET";
sub_source:default="SNMP";
auth_source:STRING;
};
END
Format file
The UNIX logfile, NetWare logfile, OS/2, and Windows event log adapters can
extract information from system log messages, whose format and meaning can
vary widely. This capability is necessary because similar sources can produce
messages in different formats. For example, different NFS (network file system)
implementations might report the file system full error in different formats. As a
result, you might need to match different messages to the same or different event
classes. This type of matching is done with a format file.
The purposes of a format file are as follows:
v Serves as the lookup file for matching messages to event classes. When the
format file is being used for this purpose, all format specifications in the file are
compared from top to bottom. In situations where there are multiple matching
classes for a message, the last matching format specification is used. If no match
is found, the event is discarded.
v Serves as the source from which a CDS file is generated. See Class definition
statement file on page 25 for additional information.
See Appendix B, Format file reference, on page 187 for details about format files.
The following examples show sample entries from the format file used by the
Windows event log adapter.
Note: The format files for the logfile-type adapters are examples only;
customization might be required. The message text must be no longer than
1024 characters.
FORMAT NT_Base
%t %s %s %s %s %s %s %s*
hostname DEFAULT
origin DEFAULT
category $3
eventType $4
sid $5
sub_source $6
id $7
msg $8
-date1 $1
-date2 $2
date PRINTF("%s %s", date1, date2)
END
FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base
%t %s %s %s %s %s %s The server service was unable to recreate
the share %s because the directory %s no longer exists.
sharename $8
directoryname $9
END
FORMAT NT_Service_Start FOLLOWS NT_Base
%t %s %s %s %s %s %s %s* started successfully.
service $8
END
24
FORMAT NT_Service_Started FOLLOWS NT_Base

%t %s %s %s %s %s %s The %s* service was started.
service $8
END
Class definition statement file

CDS files are used by an adapter to map incoming raw events to a particular class
and to define event attributes before forwarding the event to the event server.
No alterations to this file are necessary to use an adapter unless you alter the
corresponding .fmt file (if any). If any event definition is changed in a CDS file, the
corresponding event class definition in the BAROC file might need changing as
well. Event definition content and syntax are described in the IBM Tivoli Enterprise
Console Rule Developers Guide.
See Appendix C, Class definition statement file reference, on page 197 for details
about CDS files.
The following example shows a CDS file:
#
# Default attribute values
#
MAP_DEFAULT
source = SNMP;
sub_source = NET;
# forwarding_agent = $SOURCE_ADDR;
origin = $AGENT_ADDR;
adapter_host = $ADAPTER_HOST;
END
CLASS Authentication_Failure_Cisco
SELECT
1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");
2: $TYPE = 4;
3: ATTR(=,"authAddr");
FETCH
1: IPNAME($SOURCE_ADDR);
MAP
hostname = $F1;
originating_address = $V3;
END
# For Cisco routers, because we know the interface generating the trap,
# we map linkUp traps to linkDown CLOSED events
CLASS Link_Down_Cisco
SELECT
2: $TYPE = 3;
3: ATTR(=,"ifIndex");
4: ATTR(=,"ifDescr");
5: ATTR(=,"ifType");
6: ATTR(=,"locIfReason");
FETCH
MAP
hostname = $F1;
sub_origin = $V4;
status = CLOSED;
interface_index = $V3;
interface_description = $V4;
interface_type = $V5;
reason = $V6;
END
25
Error file
It is possible to selectively activate tracing for any module of an adapter (parser,
kernel, select, fetch, map, driver, and so forth) and for any level of error tracing. A
different log file can be specified for each module/level pair. To see a continuous
flow of adapter processing with tracing, change all occurrences of /dev/null to the
same output file. Keep in mind that these tracing features can consume large
amounts of disk space.
Note: The AS/400 adapters run in batch as an AS/400 job. Every job writes
messages (completion, error, and informational) to a job log. See the AS/400
adapter chapters for more information about debugging and tracing options.
Using specifications in the error file, you can configure tracing options for an
adapter. An error file usually has an extension of .err; see each specific adapter
chapter for exact file names. An error file is located in the same directory as the
adapter configuration file (see File location on page 9 for details).
Note: The error file name can be specified in the configuration file by the
AdapterErrorFile keyword, as shown in the following example:
AdapterErrorFile=/usr/tecad/tecad_adaptername.err
If you change event definitions in the CDS or format files, you can use the error
file to confirm that the adapter works properly with the new event definitions.
To specify the exact path of the trace file, change all instances of /dev/null in the
error file a file name that you want.
Each line of the error file consists of the following information:
module_name error_level output_file
where:
module_name
Specifies the type of function to trace. Valid values are as follows:

ERROR
An error function.
UTILS
A utility function.
PARSER
A parsing function.
KERNEL
A general kernel operation.
SELECT
A selection process.
FETCH
A fetch process.
MAP
A mapping process.
DRIVER
A driver main program.
DRVSPEC
An adapter-specific driver part.
26
TECIO
An event server I/O.
error_level
Specifies the type of error to look for or the type of trace to

perform. Valid values are as follows:
MINOR
A minor error.
MAJOR
A major error (running continues).
FATAL
A fatal error (running ends).
LOW
Minimal tracing.
NORMAL
Normal tracing.
VERBOSE
Verbose tracing.
output_file
Specifies the name of the file to write output to.
Initial files
Each adapter comes with an initial set of files that provides out-of-the-box support
for a predefined set of events. The set of files is composed of the following files:
v BAROC file
v CDS file
v For the adapters on NetWare, OS/2, UNIX, and Windows: format file
By modifying these files, a system administrator can add, modify, and specialize
classes of events.
The number of different events an adapter can receive is infinite. Therefore, the
major objective of the initial files provided with an adapter is not to be exhaustive,
but essentially to support the most common type of events handled by this adapter
(for example, SNMP generic traps), as well as to provide enough examples to the
system administrator on which to build new event definitions.
The initial supported events for the adapters are described in each adapter chapter
later in this guide.
Troubleshooting adapters
The following sections list troubleshooting guidelines for the different types of
adapters.
Adapter startup errors

If the adapter fails to start, look in the /tmp directory for the tecadEH.log file. You
might be able to learn why the adapter failed from reading this file. The following
list shows examples of errors you might find in the tecadEH.log file:
tecad EH : error 2 invalid error config line: Normal
tecad EH : error 4 Init: Stat failed on error file </etc/tecad_hpov.err>
27
Troubleshooting for all adapters

1. You receive a connection error when using wpostemsg or postemsg. The error
indicates that you might be using a user ID other than Administrator or root.
Thus, your ID does not have the correct permissions to create and write the file
specified by the BufEvtPath keyword.
2. If the adapter receives the event and you can determine (through tracing or
debugging) that the event matches the correct class, use the tracing output to
verify if the event was sent to the event server, not sent, or cached. If the event
was not sent to the event server, check the adapter configuration file to see if
that class was filtered out.
3. If the event was sent to the event server, verify that the event server is actually
running. Then run the wtdumprl command to check to see if the event server
received the event but failed to parse the event correctly. Also check the current
rule base rules to see if the event was dropped. See the IBM Tivoli Enterprise
Console Command and Task Reference for more information about the wtdumprl
command.
4. Check the cache files to see if the event was cached.
Managed node adapter troubleshooting

1. Use the tracing and debugging options detailed in each chapter. This helps
determine if the adapter receives the event and how the adapter handles the
event.
2. Use Tivoli Management Framework debugging output of the odstat and wtrace
services. These services show what occurs after the adapter tries to send an
event from the managed node oserv service to the Tivoli Enterprise Console
oserv services, and they also help debug problems that occur during adapter
configuration profile distributions.
3. Use the managed node wpostemsg command from the system the adapter is
running on to see if the event arrives at the event server. See the IBM Tivoli
Enterprise Console Command and Task Reference for more information.
Endpoint adapter troubleshooting

1. Use the wep ls command to make sure that the endpoint is shown under the
Tivoli Management Framework gateway you want. See the IBM Tivoli Enterprise
Console Command and Task Reference for more information. Also make sure that
any Tivoli Management Framework gateway the endpoint can log on to has the
Adapter Configuration Facility installed.
2. Source the endpoint environment and edit the last.cfg file in $LCF_DATDIR.
Set log_threshold to 3 and then stop and restart the endpoint to enable
endpoint tracing to the lcfd.log file. Check to make sure that the endpoint
logged into an appropriate Tivoli Management Framework gateway.
3. If the endpoint has logged into a Tivoli Management Framework gateway
successfully, create and distribute the adapter configuration profile (see the IBM
Tivoli Enterprise Console Users Guide for details). Check the lcfd.log file if there
are further problems; you can also turn on tracing at the Tivoli Management
Framework gateway and look in $DBDIR/gatelog for further debugging
information.
4. If events do not arrive at the event server but are not incorrectly parsed, check
to see if the events are caching on the endpoint instead. If so, either the lcfd
process cannot communicate to the Tivoli Management Framework gateway or
28
the event server, or the lcfd process itself is down. Verify that all
communications among the event server, Tivoli Management Framework
gateway, and endpoint are working.
5. Source the endpoint environment, then use the endpoint wpostemsg command
from the system the adapter is running on to see if the event arrives at the
event server. See the IBM Tivoli Enterprise Console Command and Task Reference
for more information.
Non-TME adapter troubleshooting

Use the postemsg command from the system on which the adapter is running to
see if the event arrives at the event server. The postemsg command works in
environments where Tivoli software is not installed. Thus, this standalone
command displays error messages in English only, because the command does not
have access to the message catalogs for the language support packs. See the IBM
Tivoli Enterprise Console Command and Task Reference for more information.
29
30
Chapter 2. Installing adapters

This chapter describes how to install, upgrade, and uninstall adapters. After you
install the event server, user interface (UI) server, sample event information, event
consoles, and Adapter Configuration Facility, you can install selected adapters.
After installing and configuring adapters, you must configure event sources and
event groups to enable the event server to receive events from the adapters. See
the IBM Tivoli Enterprise Console Users Guide for information about configuring
event sources and event groups.
Notes:
1. The IBM Tivoli NetView for z/OS adapters are delivered with the Tivoli
NetView for z/OS product as part of the Event/Automation Service. For
information about installing these adapters, see the IBM Tivoli NetView for z/OS
Installation and Administration Guide.
2. The logfile_hpux10 profile type should be used for HP-UX 11 systems.
The logfile_aix4-r1 profile type should be used for the 4.2 and 4.3 versions of
the AIX operating system.
4. The following TME adapters can be installed only on an endpoint and must be
installed and configured using the Adapter Configuration Facility.
v OS/2 adapters
v SNMP adapters
v UNIX logfile adapters
3.
v Windows event log adapters

The non-TME versions of these adapters do not require the Tivoli Management
Framework and, therefore, run on any supported operating system. To install
one of these adapters on a managed node where an endpoint is not installed,
you must use the non-TME version of the adapter; another option is to install
an endpoint on the managed node.
5. NetWare can be installed only as a non-TME adapter.
6. On the Windows 2000 operating system, the logfile adapter is referred to as the
Windows event log adapter.
Supported adapters
This chapter describes how to install the following adapters.
Table 8. Supported adapters
Adapter
Install from
For more information
AS/400 alert Non-Tivoli

and message
Command line
Installing AS/400 adapters on

page 37
OpenView
Tivoli
Tivoli desktop or
command line
Installing an HP OpenView adapter on

a managed node on page 33
Non-Tivoli
Command line
Installing a non-TME adapter on

page 34
Interface
31
Table 8. Supported adapters (continued)

Adapter
Interface
Install from
For more information
OS/2
Tivoli
Tivoli desktop
Installing an adapter on an endpoint

on page 33
Non-Tivoli
Command line

page 34
Tivoli
Tivoli desktop

on page 33
Non-Tivoli
Command line

page 34
Tivoli desktop

on page 33
Non-Tivoli
Command line

page 34
Tivoli
Tivoli desktop

on page 33
Non-Tivoli
Command line

page 34
SNMP
UNIX logfile Tivoli
Windows
Hardware and software requirements

For the disk space requirements for adapters that are shipped with the Tivoli
Enterprise Console product, refer to the IBM Tivoli Enterprise Console Installation
Guide.
The adapter should be installed on the host that contains the system resource or
application to monitor. You might need to install more than one adapter on a host.
UNIX and Windows software requirements

Before you can install a TME adapter on a managed node using the Tivoli desktop,
you must have version 3.6.3 or later of the Tivoli Management Framework
installed on the host on which you want to install the adapter.
To install a TME adapter on an endpoint, you must use the Adapter Configuration
Facility from the Tivoli desktop.
AS/400 software requirements

The following AS/400 program temporary fixes (PTFs) are the minimum required.
You can install PTFs that supersede these. See http://www.ibm.com for the most
current information on supported versions of the OS/400 system.
Table 9. AS/400 software requirements
OS/400 Version
Minimum PTFs Required
V4R3M0
5769SS1 SF49876, 5769SS1 SF49877
OS/2 software requirements

Before you can install an OS/2 adapter on a host, OS/2 Warp 4.0 or 4.5 must be
running on the host. The TME endpoint version of the OS/2 adapter must be
installed with the Adapter Configuration Facility.
32
Installing an HP OpenView adapter on a managed node

You can install an HP OpenView adapter from the Tivoli desktop or from the
command line.
Notes:
1. You can also install the HP OpenView adapter using the Tivoli Enterprise
Console installation wizard; for detailed information, see the Tivoli Enterprise
Console Installation Guide.
2. To successfully send events to the event server from a managed node, the HP
OpenView adapter requires an administrator login ID with a resource role of
user for the EventServer resource.
3. To install, upgrade, or uninstall components in a Tivoli environment, you must
be a Tivoli root Administrator with all available roles. For more information on
how to become a Tivoli root Administrator, see the Tivoli Management Framework
Users Guide.
Installing from the Tivoli desktop

Complete the following steps to install an HP OpenView adapter on a managed
node from the Tivoli desktop provided with the Tivoli Management Framework
product services:
1. From the Desktop menu, click Install > Install Product.
2. Click Select Media.
3. Select the location where the Tivoli Enterprise Console media is located (for
example, the path where the installation image is located).
4. Click Set Media & Close. A list of Tivoli Enterprise Console components
appears.
5. In the Select Product to Install scrolling list, select the HP OpenView adapter.
6. Click the managed nodes where you want to install the components.
7. Click Install & Close.
Installing from the command line

You can use the winstall command to install an HP OpenView adapter on a
managed node from the command line, as follows:
winstall -c /cdmount -i HPOV.IND node
where:
-c /cdmount
Specifies the path to the installation image.
HPOV.IND
Specifies the product index file for the HP OpenView adapter component.
node
Indicates the managed node on which the component is to be installed.

The endpoint adapters (OS/2, SNMP, UNIX logfile, and Windows) are packaged
with the Adapter Configuration Facility. You must use the Adapter Configuration
Facility to install these adapters on endpoints. The endpoint adapters are installed
by creating an adapter configuration profile that adds entries for the adapters you
33
want to install, and distributing the adapter configuration profile to a list of

endpoint subscribers, similar in process to any profile distribution using the Tivoli
desktop.
Note: Ensure that, for the endpoint adapters, you only distribute their profiles to
the endpoint label.
The Adapter Configuration Facility must be installed on the same managed node as
the endpoint gateway so that adapters and adapter-related files can be distributed
to the endpoints. Therefore, it is important to install the Adapter Configuration
Facility on every managed node that is configured as an endpoint gateway
throughout a Tivoli region. The steps in this section assume you have the Adapter
Configuration Facility installed on the managed nodes providing the endpoint
gateway service for the endpoints where you want to install an adapter.
Follow these general steps to install an adapter on an endpoint:
1. An adapter configuration profile must be a managed resource type. Set ACP as
a managed resource in the Set Managed Resources window for the policy
region where you will be installing the adapters.
2. Create a profile manager, specifying the Dataless Endpoint Mode option.
3. Within the profile manager:
a. Create a profile.
b. Name the profile and specify ACP as the profile type.
c. In the adapter configuration profile, add an entry for each adapter to install
on the endpoints.
Note: Some logfile adapters are operating system-specific (for example,
tecad_logfile_hpux10 and tecad_logfile_solaris2). If your endpoints
are running on multiple operating systems, for example, some
running on HP-UX 11 and some running in a Solaris Operating
Environment (hereinafter referred to as Solaris), and you want to
monitor the system log files for the endpoints, you must create an
adapter configuration profile for each operating system and distribute
them to the appropriate endpoints.
4. After selecting the adapter to install from the Add Adapter Configuration
window, you are placed in edit mode so that you can change default settings
for the adapter if you want. If you are going to install an additional adapter
using this adapter configuration profile, add another entry for the additional
adapter and repeat this step.
5. Create endpoint subscribers for the adapter configuration profile.
6. Distribute the adapter configuration profile to the subscribing endpoints. The
adapters defined in the adapter configuration profile will be installed and
started on the subscribing endpoints.
Installing a non-TME adapter

The following sections describe how to install a nonTME adapter using the
command line. For CD installation, ensure that the IBM Tivoli Enterprise Console
Non-TME Installations CD has been mounted on the /cdrom (or applicable)
directory or drive.
Note: BAROC files and rule bases are installed as part of the event server
installation procedure. They are not covered in these sections.
34
Installing on UNIX operating systems

To install a non-TME adapter on a UNIX system, use the following steps:
1. Create an installation directory (for example, /usr/tecad).
Note: If you have previously installed other adapters, you should install all
adapters in the same directory. The following example uses /usr/tecad
as the installation directory.
2. Change directories to the installation directory you created and make that
directory the default directory.
3. Untar the non-TME adapter from the CD using the following command:
tar -xvf /PLATFORM/FILENAME.TAR
where:
PLATFORM
The operating system of the host specified in uppercase letters. Some
valid values are AIX4-R1, HPUX10, LINUX-IX86, LINUX-S390, and
SOLARIS2.
FILENAME
The adapter file name, which can be one of the following values:
Adapter
FILENAME
HP OpenView
HPOV
SNMP
SNMP
UNIX logfile
LOGFILE
4. Ensure that you are logged in as the root user and use the following steps to
configure the adapter so that it starts along with the host. This command runs
the installation script for an adapter.
a. Change directories to /usr/tecad/bin and set the $TECADHOME
environment variable to /usr/tecad.
Note: If you specify an alternate location to install the binaries, you must
manually set the $TECADHOME variable as shown in step 4a and
manually copy the binary files into the same directory you specified
in the Install Directory field during the installation process.
b. Run the following command:
tecad_filename.cfg[ID]
where ID is an optional identifier for the adapter and filename can have the
following values:
Adapter
filename
HP OpenView
hpov
SNMP
snmp
UNIX logfile
logfile
c. Answer the questions asked by the script. This command also automatically
starts the adapter on the host.
35
Note: The HP OpenView installation script registers the HP OpenView

adapter with HP OpenView local registration file. The HP OpenView
adapter automatically starts when the other HP OpenView daemons
are started.
5. Ensure that the configuration file for your adapter is properly configured for
your operational environment. The configuration options are described in
Chapter 10, UNIX logfile adapter, on page 155.
Installing on Windows operating systems

To install a non-TME adapter on Windows system, use the following steps:
1. Run the following command:
/W32_IX86/install_dir/setup.exe
where install_dir is the installation directory on the CD and can be one of the
following values:
Adapter
install_dir
HP OpenView
InstallHPOV
SNMP
InstallSNMP
Windows
InstallWin
Note: You can use InstallShield silent install feature to install the adapter in the
background without user input. To do so, edit the InstallWin/SETUP.ISS
(Windows) response file, for example, which provides installation
information that the installer would typically query a user for during the
install.
First, edit the following lines in the SETUP.ISS file as necessary:
Default Setting
Change
[AskDestPath-0]
szPath=C:\TECWIN (Windows
2000)
TECWIN to the destination directory, if

necessary
[AskText-0]
szText=localhost
localhost to the name of the host where

events are to be delivered
[AskText-1]
szText=0
0 to the port number where the server has

been configured to listen for events
Then run setup /s from the InstallWin (Windows) directory to silently

install the adapter. For more information on InstallShield and the
SETUP.ISS file, go to:
http://www.installshield.com
2. Make sure that the configuration file for your adapter is properly configured
for your operational environment. The configuration options are described in
Chapter 11, Windows event log adapter, on page 167.
Note: The non-TME adapters dynamically resolve the protocol address for the
event server if the protocol address changed after the adapter started. In
this instance, you are not required to restart the adapter.
36
Installing on the OS/2 operating system

To install a non-TME adapter on an OS/2 system, use the following steps:
1. Create an installation directory (for example, c:\tecad). If you have previously
installed other adapters, you should install all adapters in the same directory.
This example procedure uses c:\tecad as the installation directory.
2. Change directories to the installation directory.
3. Run the following command from an OS/2 window:
drive:\install.exe
4. In the Instructions window, select Continue.

5. In the Install window, select OK.
6. In the Installed-directories window, specify a different installation directory for
the adapter-related files if the default is not satisfactory. If the specified
directory does not exist, it is created.
7. Select Install.
8. In the Tivoli TEC Install Options window, type information for the following
fields:
TEC Server Name
The name of the event server.
TEC Server Port
The port number for the event server.
Options
Optional command-line parameters for the tecadini.sh

program; for example, you could specify various debugging
parameters.
9. Select OK.
The adapter is installed and automatically started. You do not need to reboot
the system to start it. The CONFIG.SYS file is modified to automatically start
the adapter whenever the system is rebooted.
10. Make sure that the configuration file for your adapter is properly configured
for your operational environment. The configuration options are described in
Chapter 8, OS/2 adapter, on page 139.
Note: The non-TME adapters dynamically resolve the protocol address for the
event server if the protocol address changed after the adapter started. In this
instance, you are not required to restart the adapter.
Installing AS/400 adapters

You can install the AS/400 adapters from the Tivoli desktop or from the IBM Tivoli
Enterprise Console Non-TME Installations CD.
Installing from CD
The AS/400 adapters are shipped on the IBM Tivoli Enterprise Console Non-TME
Installations CD in the form of AS/400 save files (*SAVF). To install these files on
an AS/400, use the following steps:
1. Create save files on the AS/400 system with the following commands:
CRTSAVF FILE(QUSRSYS/ATMETEC)
CRTSAVF FILE(QUSRSYS/filename)
37
where filename is one of the following files:

Adapter
filename
Alert
ATMETEC2
Message
ATMETEC1
2. FTP the ATMETEC and filename files in the AS400 directory on the CD to the
QUSRSYS library on the AS/400 system, using the following commands:
ftp AS400.my.domain
bin
put /AS400/ATMETEC QUSRSYS/ATMETEC
put /AS400/filename QUSRSYS/filename
quit
where filename is one of the following files:

Adapter
filename
Alert
ATMETEC2
Message
ATMETEC1
3. On the AS/400 system, install the adapter using the following AS/400
commands:
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \
OPTION(*BASE) SAVF(QUSRSYS/ATMETEC)
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \
OPTION(x) SAVF(QUSRSYS/filename)
where x and filename are one of the following values:

Adapter
filename
Alert
ATMETEC2
Message
ATMETEC1
Installing from CD on an AS/400 System

If the AS/400 system is running the OS/400 V3R6M0 operating system, the
AS/400 adapters can be installed directly onto the AS/400 system by loading the
IBM Tivoli Enterprise Console Non-TME Installations CD onto the AS/400
CD-ROM drive and issuing the following commands:
RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(*BASE)
RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(x)
where x is one of the following values:
38
Adapter
Alert
Message
Installing with English as a secondary language

If your AS/400 system has a primary language other than English (2924), and you
have the English secondary language installed on your system, you can install the
AS/400 adapters.
To install the AS/400 adapter into the English secondary language library, use the
following commands:
RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(*BASE) LNG(2924)
RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(x) LNG(2924)

Adapter
Alert
Message
Note: The secondary language library QTECA02924 is automatically added to your

library list so that you can access the AS/400 adapter commands.
Installing the NetWare logfile adapter

Use the following steps to install the NetWare logfile adapter (non-TME adapter)
from a Windows NetWare client.
1. Log in to the NetWare server on which the adapter will be installed from a
Windows client system. To perform the installation, you must have write access
to the root of the SYS volume on the server. Typically, the installation should be
carried out by User Administration. The installation must be done from the
Windows system from which you logged into the NetWare system.
2. Insert the IBM Tivoli Enterprise Console Non-TME Installations CD into the
CD-ROM drive, and run the following command from a Windows system:
drive:\NW4\InstallNW4\setup.exe
3.
4.
5.
6.
You can also run this command by double-clicking on the setup.exe program in
the \NW4\InstallNW4 directory.
At the Welcome window, select Next.
Enter the host name of the NetWare server on which to install the adapter.
Select Next.
A dialog box presents the option of automatically editing the AUTOEXEC.NCF
file to start the adapter each time the NetWare server boots. Select either Yes or
No. If you select Yes, specify the directory in which the AUTOEXEC.NCF file
resides at the next window.
The setup program installs the necessary components.
7. Enter the TCP/IP host name and port number of the Tivoli Enterprise Console
server to which the adapter is to send events. The port number is needed only
if the Tivoli Enterprise Console server is running on a Windows system.
8. Select OK.
9. When the installation process is complete, select OK.
39
Upgrading HP OpenView adapters

When you upgrade a previous release of the HP OpenView adapter component of
the Tivoli Enterprise Console product, you install the upgrade image for the
adapter component. You can upgrade the adapter component using either the
Software Installation Service, the Tivoli desktop, or the command line.You can also
upgrade the HP OpenView adapter using the Tivoli Enterprise Console installation
wizard; for detailed information, see the Tivoli Enterprise Console Installation Guide.
Note: To install, upgrade, or uninstall components in a Tivoli environment, you
must be a Tivoli root Administrator with all available roles. For more
information on how to become a Tivoli root Administrator, see the Tivoli
Management Framework Users Guide.
Preparing to upgrade adapters

After installing the Tivoli Enterprise Console product, but before upgrading the HP
OpenView adapter, you must follow these steps:
1. Back up the affected object databases; see Backing up object databases.
2. Ensure that you are running the appropriate version of the Tivoli Management
Framework product on all hosts for which you are upgrading adapters.
3. Ensure that all Tivoli Enterprise Console product considerations are fulfilled.
Backing up object databases

Before installing, upgrading, or uninstalling any Tivoli Enterprise Console
components, you should back up the Tivoli object databases for all affected
computers in your Tivoli region. This backup enables you to return to a known
working state. Having a backup is useful if you encounter problems while
installing the Tivoli Enterprise Console product.
From the Tivoli desktop, select Desktop > Backup to perform a backup of the
object database for the Tivoli region server and managed nodes. You can also use
the wbkupdb command.
For example, to back up the object database for all managed nodes in a Tivoli
region, to the user-defined file /usr/backups/TMR1.bk, run the following
command:
wbkupdb -d /usr/backups/TMR1.bk
For more information on this command, see the Tivoli Management Framework
Reference Manual.
Upgrading adapters from the Tivoli desktop

You can upgrade the HP OpenView adapter component of the Tivoli Enterprise
Console product from the Tivoli desktop as follows:
1. On the Desktop menu, click Install >Install Patch.
2. Click Select Media.
3. Select the location where the Tivoli Enterprise Console media is located (for
example, the path where the upgrade image is located).
4. Click Set Media & Close. A list of components that are available for upgrading
appears.
5. Select the HP OpenView adapter component.
40
6. Select the managed nodes where you want to upgrade the HP OpenView
adapter.
7. Click Install & Close.
Upgrading adapters from the command line

You can also upgrade the HP OpenView adapter component of the Tivoli
Enterprise Console product from the command line using the wpatch command as
follows:
wpatch -c /cdmount -i HPOV_UPG node
where:
-c /cdmount
Specifies the path to the upgrade image.
HPOV_UPG
Specifies the product index file for the HP OpenView adapter component.
node
Indicates the managed node on which the component is to be upgraded.
Upgrading adapters using the Software Installation Service

You can upgrade any Tivoli product or Tivoli Enterprise Console adapter
component using the Tivoli Software Installation Service. See the IBM Tivoli
Enterprise Console Installation Guide for more information. You must first import the
upgrade images into the installation repository, and select which systems will be
upgraded with which components.
Uninstalling adapters
Although you can install selected adapters through the standard Tivoli installation
mechanisms, such as the Tivoli desktop, command line, and the Software
Installation Service, you must uninstall them using different methods. The
following sections describe how to uninstall the different kinds of adapters and
how to remove Tivoli Enterprise Console Version 3.8 enhanced adapters from the
Tivoli environment.
Uninstalling an HP OpenView adapter on a managed node

HP OpenView adapters have an uninstall script that you can run from the
command line on the system where the adapter is installed. From the managed
node, run this remove script to uninstall the adapter:
$BINDIR/TME/TEC/adapters/bin/tecad-remove-hpov.sh
Uninstalling an adapter on an endpoint

Endpoint adapters are uninstalled by deleting entries for them in the adapter
configuration profile and then distributing that profile to the appropriate targets.
You must use the Adapter Configuration Facility to uninstall a TME adapter on an
endpoint. If you remove an endpoint manually, subsequent distributions of the
adapter configuration profile might not reinstall the adapter. For step-by-step
procedures for using the Adapter Configuration Facility, see Chapter 3, Adapter
Configuration Facility, on page 45. The following steps describe the general tasks
for uninstalling a TME adapter.
1. From the adapter configuration profile that was used to install the adapter (or
an exact copy), delete the entry for the adapter you want to uninstall from the
endpoint.
41
2. Distribute the adapter configuration profile to the endpoint. For more

information about distributing the adapter configuration profile to an endpoint,
see Distributing an adapter configuration profile on page 56.
Uninstalling a non-TME adapter

The following sections describe how to uninstall a non-TME adapter on UNIX,
Windows, and OS/2 systems.
Uninstalling on UNIX operating systems

The non-TME adapters listed in the following table have an uninstall script you
can run from the command line on the system where the adapter is installed.
For other non-TME adapters on UNIX systems that do not currently have an
uninstall script, after stopping the adapter you can delete the files that were
restored from the tar file during the installation process.
Adapter
Script
Logfile (generic)
install_path/bin/tecad-remove-logfile.sh
OpenView
install_path/bin/tecad-remove-hpov.sh
SNMP
install_path/bin/tecad-remove-snmp.sh
Uninstalling on Windows operating systems

To uninstall an adapter on a Windows system, run the Uninstall Shield program
from the Tivoli program group.
Uninstalling on the OS/2 operating system

To uninstall an adapter on an OS/2 system, use the following steps:
1. If the system has not been rebooted since the adapter has been installed, go to
the install_dir\os2-ix86\bin directory; otherwise, the uninstall procedure can be
run from any directory.
2. From an OS/2 window, run the following command:
tec_uninstal
3. From the Installation and Maintenance window, select the adapter from the list
of installed products.
4.
5.
6.
7.
From
From
From
From
the
the
the
the
Action menu, select Delete.

Delete confirmation window, select Delete.
Installation and Maintenance window, select OK.
File menu in the Installation and Maintenance window, select Exit.
Most of the adapter-related files are now deleted. Some are deleted upon reboot of
the system. There might still be some that were not deleted upon reboot of the
system. This is due to file operations performed when installing the adapter to the
OS/2 system. Check for the following files on the OS/2 system and manually
delete them if necessary to complete the uninstall procedure:
v install_directory\os2-ix86\etc\tecados2.baroc
v install_directory\os2-ix86\etc\tecados2.conf
v install_directory\os2-ix86\bin\gen_message.exe
v install_directory\os2-ix86\bin\tec_uninstal.cmd
42
Uninstalling an AS/400 adapter

Perform the following steps to uninstall an AS/400 adapter:
1. On the AS/400 system, remove the adapter using the AS/400 command:
DLTLICPGM LICPGM(1TMETEC) OPTION(x)

Adapter
Alert
Message
The AS/400 adapter is deleted. If no other adapters are installed on the AS/400
system, you can also use the following command:
DLTLICPGM LICPGM(1TMETEC) OPTION(*ALL) RLS(*ALL)
Note: You might have to pull the QTECA02924 library from your library list
before the delete command deletes the base product.
2. Configuration files were copied into QUSRSYS during the installation of the
adapter. If you no longer need them, you need to manually delete them by
using the following commands:
Alert adapter:
DLTF FILE(QUSRSYS/CFG_ALERT)
Message adapter:
DLTF FILE(QUSRSYS/CFG_MSG)
3. Configuration files were copied into the IFS directory

/QIBM/UserData/Tivoli/TEC/directory_name. Remove the directory
directory_name and all of its subdirectories. directory_name can be one of the
following values:
Adapter
directory_name
Alert
ALERT
Message
MSGQ
Alert and Message
tis
4. If there are no other adapters installed on the system, then delete the directory
/QIBM/UserData/Tivoli/TEC and all of its subdirectories.
Uninstalling a NetWare logfile adapter

To uninstall a NetWare logfile adapter, complete the following steps:
1. Log in to the NetWare server from the same client you used for the installation.
2. From the Add/Remove Programs window in the Control Panel, select the
Tivoli Logfile Adapter for NetWare option and click the Add/Remove button.
3. If you selected the automatic startup option for the adapter, remove the
one-line entry that starts the adapter from the AUTOEXEC.NCF file.
43
Removing Version 3.8 enhanced adapters from the Tivoli

environment
To uninstall a Tivoli Enterprise Console 3.8 enhanced adapter, run this script from
the managed node:
/TME/TEC/tecad-enh-remove.sh
This script removes:

v All enh directories and files
v The enh objects from the oserv database
v Any profiles that were using the enhanced adapter, if any remain
44
Chapter 3. Adapter Configuration Facility

The Adapter Configuration Facility provides a graphical user interface that you can
use to configure, customize, and distribute event adapters in a Tivoli environment.
Rather than editing the actual adapter configuration files, you can create adapter
configuration profiles. You can then create a record for each adapter and configure
and customize the behavior for each adapter. Next, you can distribute the
customized configuration files and executable files to specified endpoints. The
Adapter Configuration Facility is required to configure and install TME adapters
on endpoints.
Using adapter configuration profiles

You can distribute an adapter configuration profile to any Tivoli managed node or
endpoint. However, depending on the type of adapter being configured, a
particular set of adapter configuration files or other adapter details might apply
only to certain operating system types. For example, a configuration record for a
third-party adapter that relays events from a database server can be distributed to
any host, and the configuration files are written according to the data in the record.
However, if the adapter itself is constructed such that event classes generated from
AIX operating systems differ from those generated on Solaris operating systems,
the filter definitions in the record might not be effective if deposited on a system
they were not intended for.
The simplest way to handle this issue is to maintain separate profile subscription
lists and separate profiles for configuration records of such adapters. This keeps
the distinction between endpoints visible and reduces the chance for incorrect
distribution. Among Tivoli-supplied adapters, the logfile adapter is one with clear
system dependencies, because log files that record similar information might differ
significantly in format from operating system to operating system. For this type of
configuration and similar adapters, we recommend management through separate
profiles.
Note: The job of tracking separate profiles can be made more convenient by
grouping related profiles together in simple collections. The hierarchy of
policy regions and profile managers can then be bypassed when navigating
from profile to profile on the desktop.
Adapter Configuration Facility roles

The following Tivoli authorization roles are associated with the Adapter
Configuration Facility activities:
ACF_glopol
Used by an administrator to set the global adapter policy.
ACF_polmod
Used by an administrator to edit profile policy and create new profiles.
ACF_rwdist
Used by an administrator to edit and distribute adapter configuration
profiles.
45
ACF_readonly
Used by an administrator to view adapter configuration profiles, but the
administrator cannot create, edit, or distribute the adapter configuration
profiles.
You can set these Tivoli management region and resource roles for an
administrator from the Tivoli Management Framework Administrators dialog box.
Setting adapter configuration profiles as managed resources

Each policy region maintains a list of managed resource types that are valid or
defined for that specific policy region. You must add adapter configuration profiles
as managed resources before you can use a policy region to manage adapter
configuration profiles.
Note: This procedure is performed only once per policy region.
The following table lists the context and authorization role required to perform this
task.
Activity
Context
Required Role
Set policy region managed

resources for an adapter
configuration profile
Policy region
senior
You can perform this task from the desktop or from the command line.

from the Tivoli desktop
1. Right-click the policy region icon and select Managed Resources from the
context menu. The Adapter Configuration Facility displays the Set Managed
Resources dialog box.
2. Select the ACP managed resource from the Available Resources scrolling list
and click the left arrow button to move the selected managed resources to the
Current Resources scrolling list.
3. Click the Set & Close button to add the directory profile as a resource and
close the dialog box.

from the command line
For more information about using the command line to add managed resources for
a policy region, see the Tivoli Management Framework Reference Manual entry for the
wsetpr command.
Creating an adapter configuration profile

When you create an adapter configuration profile, the initial profile is empty; it
does not contain any records. It does, however, contain a set of default and
validation policies.
task.
46
Activity
Context
Required Role
Create an adapter
Profile manager
senior
You can create a directory profile from the desktop or the command line.
Creating an adapter configuration profile from the Tivoli

desktop
Perform the following steps to create an adapter configuration profile from the
Tivoli desktop. You must have previously created the policy region and profile
manager in which the directory profile is to reside. For more information about
policy regions and profile managers, see the Tivoli Management Framework Users
Guide.
Note: If you have not already assigned managed resource roles to the policy
region that is to contain the profile you want to create, assign these roles
now. For more information, see Setting adapter configuration profiles as
managed resources on page 46.
1. Double-click the icon for the policy region in which you want to manage your
profile. This opens the Policy Region window.
2. Create a profile manager by selecting Create > Profile Manager from the
Create pull-down menu. The Create Profile Manager dialog displays.
3. Type the profile manager name in the Name/Icon Label text box.
4.
5.
6.
7.
Note: You must select the Dataless Endpoint Mode check box if you want to
manage any endpoints.
Double-click a profile manager icon to display the Profile Manager window.
Select Profile from the Create pull-down menu. The Adapter Configuration
Facility displays the Create Profile dialog box.
Enter a name for the profile in the Name/Icon Label text box. Each adapter
configuration profile must have a unique name within a Tivoli region.
Select the ACP option from the Type scrolling list. If you have installed other
Tivoli products, other options might be displayed in the Type scrolling list.
8. Click the Create & Close button to create the profile and return to the Profile
Manager window. The Adapter Configuration Facility creates the adapter
configuration profile and displays the profile icon in the Profile Manager
window.
Creating an adapter configuration profile from the command

line
The following example creates an adapter configuration profile from the command
line interface:
wcrtprf @ProfileManager:ACPM1 ACP Profile1
where:
ACPM1
Specifies the name of the profile manager. You can use the wlookup
command to return a list of available profile managers.
ACP
Specifies the type of profile being created.

47
Profile1
Specifies the name of the new adapter configuration profile.
For more information about the wcrtprf and wlookup commands, see the Tivoli
Management Framework Reference Manual.
Cloning an adapter configuration profile

When you clone an adapter configuration profile, you create a new profile that
duplicates the default and validation policies associated with the original profile.
However, it does not include the adapter configuration records of the original
profile. The Adapter Configuration Facility does not permit two profiles of the
same type in the same profile manager to contain the same records.
task.
Activity
Context
Required Role
Clone an adapter
Profile manager
senior
You can clone an adapter configuration profile from the desktop or the command
line.
Cloning an adapter configuration profile from the Tivoli

desktop
Perform the following steps to clone an adapter configuration profile from the
Tivoli desktop:
1. From a policy region, double-click a profile manager icon to display the Profile
Manager window.
2. Click the icon for the adapter configuration profile you want to clone.
3. Select the Profiles:Clone option from the Edit menu in the Profile Manager
window to copy the original profile and display the Clone Profile dialog box.
4. Enter a new name for the profile in the Name/Icon Label text box. Each
adapter configuration profile must have a unique name within a Tivoli region.
In this example dialog, the Name/Icon Label is Profile2.
5. Select the profile to clone from the Clone to Profile Manager scrolling list.
6. Click the Clone & Close button to create the new profile and return to the
Profile Manager window. The Profile2 adapter configuration profile icon
displays in the Profile Manager window.
Cloning an adapter configuration profile from the command

line
The following example command clones an adapter configuration profile from the
command line:
wcrtprf -c @ACP:Profile1 @ACPM1:ACP Profile3
where:
-c @ACP:Profile1
Specifies the Profile1 adapter configuration profile as the source profile that
is to be cloned to create the new profile.
48
ACPM1
Specifies the name of the profile manager.
ACP
Specifies the type of profile being cloned.
Profile3
Specifies the name of the new adapter configuration profile.
For more information about the wcrtprf command, see to the Tivoli Management
Framework Reference Manual.
Deleting an adapter configuration profile

When you delete an adapter configuration profile, you remove the profile and all
its records from the profile manager. This action also removes the associated copy
of the profile for each subscriber. You can delete only a top-level profile. You
cannot delete a descendant of a profile.
Note: Deleting a profile does not delete information in system files.
task.
Activity
Context
Required Role
Delete an adapter
Profile manager
senior
Deleting an adapter configuration profile from the Tivoli

desktop
Perform the following steps to delete an adapter configuration profile from the
Tivoli desktop:
Manager window.
2. Select the icon for the adapter configuration profile you want to delete.
3. Select the Profiles:Delete option from the Edit menu in the Profile Manager
window to display the Delete Profiles dialog box.
Note: You can click the Cancel button to stop the operation.
4. Click the Delete button to delete the profile and remove the icon from the
Profile Manager window.
Deleting an adapter configuration profile from the command

line
The following example command deletes an adapter configuration profile from the
command line:
wdel @ACP:Profile2
where:
@ACP:Profile2
Specifies the Profile2 adapter configuration profile.
For more information about the wdel command, see the Tivoli Management
49
Setting adapter configuration profile defaults

You can control the default settings that an adapter configuration profile uses
when the Adapter Configuration Facility distributes a profile. The default settings
determine which distribution settings are initially selected. An administrator with
the proper authorization role can override the default settings. Defaults are set on
a per-profile basis. The default options for each profile can be different from those
of other profiles. You can perform the following modifications to a profile:
v Rename an adapter configuration profile
v Set distribution defaults
v Modify an adapter configuration profile default policy
v Modify an adapter configuration profile default validation policy
Renaming a profile
You can rename an adapter configuration profile only from the desktop.
task.
Activity
Context
Required Role
Rename an adapter
Adapter configuration profile admin
Perform the following steps to rename a profile from the Tivoli desktop:
Manager window.
2. Double-click the adapter configuration profile icon to display the Adapter
Configuration Profile window.
3. Enter the new name for the profile.
4. Click the Set New Name button.
Getting a new copy of an adapter configuration profile

You can get a new copy of a profile from the profile manager that is one level
down in the subscription hierarchy. This operation is making request to the
subscribed-to profile manager for distribution to a single subscriber.
task.
Activity
Context
Required Role
Get a new copy of an adapter Adapter configuration profile senior

Getting a new copy of an adapter configuration profile from

the Tivoli desktop
Perform the following steps to retrieve an adapter configuration profile copy from
another profile from the Tivoli desktop:
1. From a profile manager, double-click an icon for a profile manager subscriber
to display the Profile Manager window.
50
2. Double-click an adapter configuration profile icon to display the Adapter

3. Select the Get New Copy option from the Profile menu. The Adapter
Configuration Facility displays the Get Subscription Copy dialog box.
4. Click the Preserve profile record modifications made in profile manager radio
button to retrieve the profile, but keep the values in the current profile. Use this
option when your profile has differences you want to keep after retrieving the
new profile copy.
Click the Make profile records an EXACT COPY of the retrieved profile
records radio button to retrieve the profile and overwrite any values in the
current profile. Use this option when you do not want to keep the local
changes to the current profile.
5. To retrieve the profile at a later time, click the Schedule button to display the
Add Scheduled Job dialog box.
For more information about the Tivoli scheduling facility, see the Tivoli
Management Framework Users Guide.
6. Click the Get Copy & Close button to immediately retrieve copies of the
profile records into the current profile and then close the dialog box.
Getting a new copy of an adapter configuration profile from

the command line
The following example command retrieves a copy of a profile from another profile
manager from the command line:
wgetprf -l maintain @ProfileManager:ACPsub
where:
l maintain
Retains any local modifications in subscribers copies of the profile.
ACPsub
Specifies the name of the subscriber to receive new profile copy.
For information about using the command line to retrieve profile information from
another profile, see the Tivoli Management Framework Reference Manual entry for the
wgetprf command.
Setting adapter configuration profile distribution defaults

You can set the adapter configuration profile distribution file defaults for a profile.
task.
Activity
Context
Required Role
Set distribution defaults
Adapter
admin
Perform the following steps to set distribution defaults for a profile from the Tivoli
desktop:
Manager window.
51
3. Select Distribution Defaults from the Profile menu. The Adapter

Configuration Facility displays the Set Distribution Defaults dialog box.
4. Select one of the Distribute To options based on the following descriptions:
v Next level of subscribers
Distributes the profile only to the subscribers named in the Distribute To
These Subscribers scrolling list of the Distribute Profile dialog box.
This selection distributes the profile only to the subscribers of the profile
manager. It does not distribute to lower-level subscribers. If a profile
manager with subscribers resides at the next-lower level, you might need to
perform the distribution process from profile managers at more than one
level to reach all the profile endpoints.
Note: The Adapter Configuration Facility does not update the files on an
endpoint if you perform a single-level distribution from a profile
manager to an endpoint. To update the data files on the endpoints,
you must either distribute the adapter configuration profile to the
endpoint itself, or distribute the profile to all levels of subscribers.
v All levels of subscribers
Distributes the profile to all subscribers and all subscribers subscribers.
Select this option if you want to distribute a profile in which your managed
node is the only subscriber.
5. Select one of the Distribution Will options based on the following descriptions:
v Preserve modifications in subscribers copy of the profile
Keeps entries that are in the subscribers profile, even though they are not in
the profile being distributed.
v Make subscribers profile an EXACT COPY of this profile
Overwrites the profile for the subscriber with an exact copy of the profile
being distributed.
6. Click the Set & Close button to set the distribution defaults and dismiss the
dialog box.
Modifying an adapter configuration profile default policy

Default policies define the default values to be used when an adapter
configuration profile record is added or edited. An adapter configuration profile
contains a default policy for each attribute of an adapter configuration record.
Although default policy can be defined for each attribute, the Adapter
Configuration Facility does not necessarily assign default values for all attributes.
You can create a default policy if you want a different attribute to always have a
default value. The three types of default policies are as follows:
Script Runs shell scripts. You can use only attributes as arguments for a script.
Constant
Sets an attribute to a specified value.
None
Indicates the attribute does not have a default setting.
If you define a default policy for an attribute to be of type Script, the Adapter
Configuration Facility ensures all the arguments for the script are defined before it
runs the script.
52
If you add or edit a default policy script, you must make sure that all the
arguments in that script have a default policy defined. If you create a situation in
which two arguments require values from each other, the default policy fails, and
you cannot add new records.
task.
Activity
Context
Required Role
Modify an adapter
configuration profile default
policy
Adapter configuration profile senior
You can set default policy from the desktop or the command line.
Modifying an adapter configuration profile default policy from

the Tivoli desktop
Perform the following steps to set default policy in an adapter configuration profile
from the Tivoli desktop:
Manager window.
3. Select the Default Policies option from the Edit menu to display the Edit
Default Policies dialog box.
4. Select an attribute from the Attributes scrolling list.
5. Verify that the Subscribers can edit setting is correct for this attribute.
v Select No to prevent subscribers from editing their local copy of this default
policy.
v Select Yes to allow subscribers to edit their local copy of this default policy.
(This option is the default.)
6. Select a type from the Default Type drop-down list. You can choose None,
Constant, or Script.
If you select None, there is no default policy.
If you select Constant, the Edit Default Policies dialog displays a Value text
box, as shown in the previous dialog box. You must type a constant value in
the Value text box.
If you select Script as the Default Type, the Edit Script Arguments and Edit
Script Body buttons are displayed as shown in the following dialog box.
Complete the following steps:
a. Click the Edit Script Arguments button to display the Policy Script
Arguments dialog box.
b. Select the record attributes from the Attributes scrolling list that you want
to use as script arguments.
c. Click the right arrow button to move the attributes into the Script
Arguments scrolling list.
You can change the order in which an argument is passed by selecting the
argument and clicking the up or down arrow button to move the argument
to a particular position.
53
d. Click the Set & Close button to add the new arguments and return to the
Edit Default Policies dialog box.
a. Click the Edit Script Body button in the Edit Default Policies dialog to
display the Edit Policy Script dialog box.
b. Enter or edit the body of the script.
c. Click the Set & Close button to save the script to the database and return to
the Edit Default Policies dialog box.
Repeat this procedure for each of the record attributes that you want to edit.
Modifying an adapter configuration profile default policy from

the command line
The following example command sets a constant-valued default policy:
wputpol -d -c STATIC @ACP:Profile1 comment
where:
d
Specifies the default policy is being set.
c STATIC
Sets the policy to the constant STATIC.
@ACP:Profile1
comment
Specifies the attribute that is to have the new policy.
For more information about the wputpol command, see the Tivoli Management
Modifying an adapter configuration profile validation policy

You can set validation policy for one or more of the attributes in an adapter
configuration profile. You can also enable or disable validation for all attributes.
Validation runs when you populate or distribute a profile, add a new entry, or
explicitly request validation. The Adapter Configuration Facility uses validation to
verify that a profile entry is compliant with established policy and prevents you
from creating an entry that does not meet specific criteria. Validation policy can be
enabled or disabled on a per-attribute basis within a profile. Therefore, it is
possible to disable validation on one or more attributes and add new entries that
are not subject to the validation check.
task.
Activity
Context
Required Role
Modify an adapter
validation policy
Adapter configuration profile senior
You can set or edit validation policy from the desktop or the command line.
54

from the Tivoli desktop
Perform the following steps to modify an adapter configuration profile validation
policy from the Tivoli desktop:
Manager window.
3. Select the Validation Policies option from the Edit menu to display the Edit
Validation Policies dialog box.
4. If you want to disable validation for all attributes, click the Disabled radio
button. Otherwise, make sure the Enabled radio button is selected.
5. Select an attribute from the Attributes scrolling list.
6. Verify that the Subscribers can edit setting is correct for this attribute.
v Select No to prevent subscribers from editing their local copy of this
validation policy.
v Select Yes to allow subscribers to edit their local copy of this validation
policy. (This option is the default.)
7. Select a type from the Default Type drop-down list. You can choose None,
Constant, Script, or Regular Expression.
If you select None, there is no validation policy.
If you select Constant or Regular Expression, the Edit Default Policies dialog
displays a Value text box. Enter a constant value in the Value text box. When
constant policy is used, validation passes only if the attribute value matches the
constant provided.
If you select Script, the Edit Default Policies dialog displays the Edit Script
Arguments and Edit Script Body buttons.
Perform the following steps to determine the order in which the script
arguments are displayed from the Tivoli desktop:
a. Click the Edit Script Arguments button on the Edit Default Policies dialog
to display the Policy Script Arguments dialog box. Use this dialog to
determine the order of the script arguments.
b. Select the record attributes from the Attributes scrolling list that you want
to use as script arguments.
c. Click the right arrow button to move the attributes into the Script
Arguments scrolling list.
You can change the order in which an argument is called by selecting the
argument and clicking on the up or down arrow button to move the
argument to a particular position.
d. Click the Set & Close button to add the new arguments and return to the
Edit Default Policies dialog box.
e. Click the Edit Script Body button in the Edit Default Policies dialog to
display the Edit Policy Script dialog box.
f. Enter or edit the body of the script.
g. Click the Set & Close button to save the script to the database and return to
the Edit Default Policies dialog box.
Repeat this procedure for each of the record attributes.
55

from the command line
The following example command sets validation policy to none:
wputpol -v -n @ACP:Profile1 comment
where:
v
Specifies the validation policy is being set.
Sets the policy to none.
@ACP:Profile1
comment
Specifies the attribute that is to have the new policy.
For more information about the wputpol command, see the Tivoli Management

To easily configure and customize multiple event adapters, you can distribute an
adapter configuration profile to its subscribers.
task.
Activity
Context
Required Role
Distribute an adapter
You can distribute an adapter configuration profile from the desktop or the
command line.
Distributing an adapter configuration profile from the Tivoli

desktop
Perform the following steps to distribute an adapter configuration profile from the
Tivoli desktop:
1. From a policy region, select the Distribute option from the context menu of a
profile manager icon. The Adapter Configuration Facility displays the
Distribute Profiles dialog box.
2. Click the Distribute Now button to distribute the profiles immediately.
OR
Click the Schedule button to schedule a profile distribution. See the Tivoli
Management Framework Users Guide for information about using the Tivoli
Scheduler.
Distributing an adapter configuration profile from the

command line
The following example command distributes an adapter configuration profile:
wdistrib @ACP:Profile1
56
where:
Profile1
Specifies the name of the profile.
Note: When distributing adapter configuration profiles with the wdistrib
command, the l maintain option is typically used to maintain local
modifications for adapter configurations.
An optional mode is available to distribute specified profiles only. The l
over_all_no_merge option eliminates the need to reinstall adapter
configurations in profiles that are not explicitly requested. This option
should be used whenever adapter configuration profiles are distributed and
you want to force the reinstallation of specific adapter configurations.
For more information about wdistrib command options, see the Tivoli Management
Adding an adapter configuration profile record

Before you can use an adapter configuration profile to configure and customize a
particular event adapter, you must create a record for the event adapter.
Endpoint adapters
Endpoint adapters, which include the OS/2 adapter, SNMP adapter, UNIX logfile
adapter, and Windows event log adapter, must use the Adapter Configuration
Facility to distribute their binaries to their respective endpoints.
To configure the UNIX logfile adapter, you must distribute to the appropriate
operating system type. The Adapter Configuration Facility provides additional
UNIX logfile adapter types in the format of tecad_logfile_interp_type to coincide
with each supported operating system, as shown in the following table.
Adapter Type
Operating System
tecad_logfile_aix4-r1
AIX 4
tecad_logfile_solaris2
Solaris 2
tecad_logfile_hpux10
HPUX 11
Additionally, the tecad_logfile adapter type is provided; however, you must edit
the profile record and replace TARGTYPE (in the Adapter Configuration Facility
Edit Profile dialog) with the correct operating system type for the system to which
you are distributing the adapter and profile. If you do not provide the correct
operating system type, you get an error message similar to this:
File /AP/2/usr/local/Tivoli/bin/generic_unix/TME/ACF_REP/
tecad_logfile_TARGTYPE.fmt not a regular file
The tecad_logfile adapter type is not a recommended choice and is provided for
use with custom adapter types.
Note: The TME version of the UNIX logfile, OS/2, SNMP, and Windows event log
adapters can be installed only on an endpoint. To install one of these
adapters on a managed node that does not have an endpoint installed, you
must use the non-TME version, or make the managed node an endpoint
also.
57
task.
Activity
Context
Required Role
Add an adapter configuration Adapter configuration profile senior

profile record
This task can be performed only from the desktop.

Perform the following steps to add an adapter configuration profile record from
the Tivoli desktop:
Manager window.
3. Click the Add Entry button. The Adapter Configuration Facility displays the
Add Adapter Configuration dialog box.
4. Select the adapter type from the scrolling list.
5. Click the Select & Close button. The Adapter Configuration Facility displays
the Edit Adapter dialog box.
See Editing an adapter configuration profile record for information about
editing adapter configuration profile record entries.
6. Click the Save & Close button to save the new record. The Adapter
Configuration Facility closes the Edit Adapter dialog and displays the new
record in the Adapter Configuration Profile window.
Editing an adapter configuration profile record

You can perform the following editing operations on adapter configuration
profiles:
v
v
v
v
v
Add, modify, or remove a configuration option

Add, modify, or remove a filter definition
Add or remove a file from the distribution list
Modify the delete configuration file behavior
Add or remove a before or after script
v Enable or disable a before or after script

v Modify before and after script reporting behavior
v Modify the comment
v Modify the UID and GID
v Modify the adapter identifier name
When editing an adapter configuration profile record, you might find two
environment variables within a profile record: $TECADHOME and
$TIVOLIHOME. $TECADHOME represents the directory just above the location
the adapter binaries are stored; $TECADHOME/bin for managed nodes and
endpoints. $TIVOLIHOME represents the directory where the environment scripts
and oserv.rc binary files for the managed node are installed.
If you specify an alternate location to install the binaries, the following
customization is required:
58
v You must manually set the $TECADHOME variable.

v You must manually copy the binary files into the same directory you specified in
the Install Directory field during the installation process.
Adding a configuration option to an adapter configuration

profile record
You can add a configuration option to a record. These environment variables are
passed to the subscribers of the profile. For example, if you want to specify a
maximum event size of 4096 bytes, you can set the environment variable
EventMaxSize=4096.
Note: The terms environment variable and configuration options are synonymous
in an Adapter Configuration Facility context.
task.
Activity
Context
Required Role
Add a configuration option

to an adapter configuration
profile record

Perform the following steps to add a configuration option to an adapter
configuration profile record from the Tivoli desktop:
2. Click the record to be edited.
3. Click the Edit Entry button to display the Edit Adapter dialog box.
4. Click the Environment radio button.
5. Select the new environment variable from the Unset Variables scrolling list by
double-clicking. The new environment variable displays in the first text box
above the Current EIF Environment scrolling list.
6. Enter the value for the new environment variable in the right-hand text box.
7. Click the check button to display the new environment variable in the scrolling
list.
8. Repeat steps 57 for each new environment variable that you want to add.
9. Click the Save & Close button to save the new environment variable and close
the Edit Adapter dialog box.
Modifying a configuration option in an adapter configuration

profile record
You can modify the value of an existing environment variable in a record.
task.
59
Activity
Context
Required Role
Modify an environment
variable in an adapter
configuration profile record

Perform the following steps to modify an environment variable in an adapter
2. Select the record to be edited.
4. Click the Environment radio button. The Adapter Configuration Facility
displays a dialog box.
5. In the Current EIF Environment scrolling list, double-click the environment
variable to be edited. The environment variable and its current value are
displayed in the text boxes.
6. Enter the new value for the environment variable in the right-hand text box.
7. Click the check button. The Adapter Configuration Facility displays your
changes in the Current EIF Environment scrolling list.
8. Click the Save & Close button. The Adapter Configuration Facility saves the
new value for the environment variable and closes the Edit Adapter dialog box.
Removing an environment variable from an adapter

You can remove an environment variable from a record.
task.
Activity
Context
Required Role
Remove an environment
variable from an adapter

Perform the following steps to remove an environment variable from an adapter
configuration profile from the Tivoli desktop:
2. Click the record to be edited.
4. Click the Environment radio button to display a dialog box.
5. From the Current EIF Environment scrolling list, select the environment
variable to be deleted.
6. Click the trash can button to delete the environment variable.
60
7. Click the Save & Close button to save your change and close the Edit Adapter
dialog box.
Adding a filter definition to an adapter configuration profile

record
You can add filter definitions to a record. Filtering at the adapter level can help
reduce unnecessary network traffic.
task.
Activity
Context
Required Role
Add a filter definition to an

adapter configuration profile
record

Perform the following steps to add a filter definition to an adapter configuration
profile record from the Tivoli desktop:
3. Click the Edit Entry button to display the Edit Adapter dialog box. If not
already selected, click the Filters radio button to display the Select Event Class
dialog box.
4. Click the New Filter button to display the Select Event Class dialog box.
5. Select the rule base from the Available Rule Bases scrolling list and click the
right arrow button.
6. Select the event class from the Event Classes scrolling list.
7. Click the Select & Close button to close the Select Event Class dialog and
display the new filter in the scrolling list in the Edit Adapter dialog box.
8. Select the filter from the right-hand scrolling list by double-clicking, or select
and click the up arrow button.
9. From the left-hand scrolling list, select the variable value for which you want
to add a filter and click the right arrow button.
10. Enter the value for the variable in the right-hand text box and click the check
button. The new filter displays.
11. Repeat steps 9 and 10 for each variable for which you want to specify a value.
12. Click the Save & Close button to save your changes and close the Edit
Adapter dialog box.
Adding a filter cache definition to an adapter configuration

profile record
You can add filter cache definitions to a record. Filtering which events to cache at
the adapter level can help reduce unnecessary network traffic.
task.
61
Activity
Context
Required Role
Add a filter cache definition

profile record

Perform the following steps to add a filter cache definition to an adapter
4. Click the FilterCache radio button.
5. Click the New FilterCache button to display the Select Event Class dialog box.
6. Select the rule base event class from the Select Event Class dialog box.
7. Click the Select & Close button to close the Select Event Class dialog and
display the new filter in the scrolling list in the Edit Adapter dialog box.
8. Select the filter from the right-hand scrolling list by double-clicking, or select
9. From the left-hand scrolling list, select the variable value for which you want
to add to the filter and click the right arrow button.
10. Type the value for the variable in the right-hand text box and click the check
button. The new filter displays.
11. Repeat steps 9 and 10 for each variable for which you want to specify a value.
Adapter dialog box.
Adding a prefilter definition to an adapter configuration profile

record
You can add prefilter definitions to a record. Use prefiltering to define which
events the adapter processes. Filtering at the adapter level can help reduce
unnecessary network traffic. This option is available only for Windows event log
adapters.
task.
Activity
Context
Required Role
Add a prefilter definition to

an adapter configuration
profile record

Perform the following steps to add a prefilter definition to an adapter
62

4. Click the PreFilters radio button to display the prefiltering fields in the Edit
Adapter dialog box.
5. Select the New Prefilter button to display the Select Log dialog box.
6. Select the log from the Available Log Specifications scrolling list or click the
right-arrow button to move the selected log to the Selected Log pane.
Note: DNS, Directory, and FRS logs are applicable only to the tecad_win
profile, which is for the Windows event log adapter.
7. Click the Select & Close button to close the Select Log dialog and display the
new prefilter in the scrolling list in the Edit Adapter dialog box.
8. Select the log from the right-hand scrolling list by double-clicking, or select
9. From the left-hand scrolling list, select the attribute (EventId, EventType, or
Source) for which you want to add a prefilter and click the right arrow
button.
10. Enter the preferred value for the variable in the right-hand text box and click
the check button. The new prefilter displays.
11. Repeat steps 9 and 10 for each attribute for which you want to specify a value.
Adapter dialog box.
Modifying a filter definition in an adapter configuration profile

record
You can modify an existing filter definition in a record.
task.
Activity
Context
Required Role
Modify a filter definition in

profile record

Perform the following steps to modify a filter definition in an adapter
3. Click the Edit Entry button to display the Edit Adapter dialog and click the
Filters radio button.
4. In the scrolling list, double-click the variable.
5. Enter the new filter value for the variable in the right-hand text box and click
the check button to update the dialog with the new value.
6. Click the Save & Close button to save your changes and close the Edit Adapter
dialog box.
63
Modifying a filter cache definition in an adapter configuration

profile record
You can modify an existing filter cache definition in a record.
task.
Activity
Context
Required Role
Modify a filter cache

definition in an adapter

Perform the following steps to modify a filter cache definition in an adapter
6. Enter the new filter cache value for the variable in the right-hand text box and
click the Check button to update the dialog with the new value.
dialog box.
Modifying a prefilter definition in an adapter configuration

profile record
You can modify an existing prefilter definition in a record.
task.
Activity
Context
Required Role
Modify a prefilter definition

in an adapter configuration
profile record

Perform the following steps to modify a prefilter definition in an adapter
3. Click the PreFilters radio button to display the dialog box.
5. Enter the new prefilter value for the attribute in the right-hand text box and
click the Check button to update the dialog with the new value.
64
dialog box.
Removing a filter cache definition in an adapter configuration

profile record
You can remove an existing filter cache definition in a record.
task.
Activity
Context
Required Role
Remove a filter cache

definition in an adapter

Perform the following steps to remove a filter cache definition in an adapter
5. In the scrolling list, select the filter to be removed.
6. Click the trash can button to remove the filter from the scrolling list.
dialog box.
Removing a prefilter definition in an adapter configuration

profile record
You can remove an existing prefilter definition in a record.
task.
Activity
Context
Required Role
Remove a prefilter definition

in an adapter configuration
profile record

Perform the following steps to remove a prefilter definition in an adapter
4. Click the PreFilters radio button.
65
5. In the scrolling list, select the prefilter to be removed.

6. Click the trash can button to remove the prefilter from the scrolling list.
dialog box.
Removing a filter definition from an adapter configuration

profile record
You can remove a filter definition from a record.
task.
Activity
Context
Required Role
Remove a filter definition

from an adapter

Perform the following steps to remove a filter definition from an adapter
1. Double-click an v icon to display the Adapter Configuration Profile window.
3. Click the Edit Entry button to display the Edit Adapter dialog box. Click the
Filters radio button.
4. From the scrolling list, select the filter to be removed.
5. Click the trash can button to remove the filter from the scrolling list.
dialog box.
Adding a file to the distribution list of an adapter

You can add a file to the distribution list of a record.
task.
Activity
Context
Required Role
Add a file to the distribution

list of an adapter

Note: If you do not specify an absolute path name, the target file is placed in the
directory specified by the target directory specified on the adapter
configuration profile selection panel.
Perform the following steps to add a file to the distribution list of an adapter
66

4. Click the Distribution radio button.
5. Enter the destination file name in the left-hand text box.
Note: If you do not specify an absolute path name, the target file is placed in
the directory specified by the target directory.
6. Enter the source file name in the right-hand text box.
7. Click the check button.
dialog box.
Note: The Adapter Configuration Facility has the ability to use localized format
files with Adapter Configuration Facility 3.7.1. The default action is that
all localized format files are distributed to the
$TECADHOME/etc/language_identifier directory of the adapter. Each
language is represented by a different set of characters used as the
directory name. The format file is copied to the language directory for
use with the adapter. All files are currently in English, but can be
localized to one of the supported languages. If you do not wish to
distribute all localized format files for an adapter, use the instructions
below for removing a file from the distribution list of an adapter
configuration profile record.
Removing a file from the distribution list of an adapter

You can remove a file from the distribution list of a record.
task.
Activity
Context
Required Role
Remove a file from the

distribution list of an adapter
Adapter configuration profile
admin

Perform the following steps to remove a file from the distribution list of an adapter
5. From the scrolling list, select the file to be deleted.
6. Click the trash can button to delete the file from the distribution list.
dialog box.
67
Modifying the adapter configuration file behavior

You can modify the endpoint behavior of a record.
task.
Activity
Context
Required Role
Modify the adapter

configuration file behavior

Perform the following steps to modify the configuration file behavior from the
Tivoli desktop:
5. Select Remove files from the when record is deleted drop-down list to delete
files at the endpoints when the corresponding files are removed from the
profile.
OR
Select Keep files from the when record is deleted drop-down list to retain files
at the endpoints when the corresponding files are removed from the profile.
6. Click the Save & Close button. The Adapter Configuration Facility saves your
changes and closes the Edit Adapter dialog box.
Modifying variable expansion behavior

You can modify the variable expansion behavior of a record.
task.
Activity
Context
Required Role
Modify variable expansion

behavior

Perform the following steps to modify the variable expansion behavior of a record
from the Tivoli desktop:
4. Click the General radio button.
5. You can specify which variables should be expanded at the profile endpoints
by using the left and right arrow buttons to move entries between the Expand
at Endpoints scrolling list and the Leave Alone scrolling list.
68
dialog box.
Adding a before or after script to an adapter configuration

profile record
To easily specify actions that should be taken before or after files are distributed,
you can add a before or after script to a record. In addition, check the default
supplied actions and paths to ensure that they are correct for your systems.
task.
Activity
Context
Required Role
Add a before or after script

profile record

Perform the following steps to add a before or after script to an adapter
4. Click the Actions radio button.
5. Enter the script in the Before file distribution scrolling list or in the After file
distribution scrolling list. This script can contain anything that can be
interpreted by the shell. The Adapter Configuration Facility adds the script to
the scrolling list.
dialog box.
Modifying a before or after script in an adapter configuration

profile record
You can change a before or after script. The following table lists the context and
authorization role required to perform this task.
Activity
Context
Required Role
Modify a before or after

script to an adapter
Each adapter configuration record can be configured to perform actions on

subscribing endpoints upon distribution. Actions can be enabled or disabled.
Whether or not an action is performed is determined by the setting of the control
on the upper right corner of the Actions attribute group.
69
Actions can be performed both before and after configuration files are written.
Actions performed before file distribution can halt an event adapter and possibly
remove the contents of a configuration directory. Actions performed after file
distribution can restart the adapter.
The following options are available when an action fails: the endpoint code can
ignore failures, report failures (using a notice logged to the Adapter Configuration
Facility notice group), or stop the distribution by throwing an exception. Only one
option can be applied to each record.
For information about commands, such as the wsetaddflt command, which can be
used to set actions, see the IBM Tivoli Enterprise Console Command and Task
Reference. Internally, you can use the wdepset command to perform different
actions for different interp types. You can also write your own actions and include
interp checking within the action.
Removing a before or after script from an adapter

You can remove a before or after script from a record.
task.
Activity
Context
Required Role
Remove a before or after

script from an adapter
Adapter configuration profile
admin

Perform the following steps to remove a before or after script from an adapter
5. Place the cursor in the Before file distribution scrolling list or the After file
distribution scrolling list and backspace over the script to be removed.
6. Click the Save & Close button and save your changes and close the Edit
Adapter dialog box.
Enabling and disabling before and after scripts in an adapter

You can specify whether before and after scripts should be run when files are
distributed.
task.
70
Activity
Context
Required Role
Enable or disable before and

after scripts in an adapter

Perform the following steps to enable or disable before and after scripts in an
adapter configuration profile record from the Tivoli desktop:
5. Select enabled from the Actions are pull-down menu to enable before and after
scripts.
OR
Select disabled from the Actions are option menu to disable before and after
scripts.
dialog box.
Modifying before and after script reporting behavior

You can modify the reporting behavior of before and after scripts.
task.
Activity
Context
Required Role
Modify before and after

script reporting behavior

Perform the following steps to modify the reporting behavior of before and after
scripts from the Tivoli desktop:
5. Select ignore & continue from the When actions fail drop-down list to ignore
errors during the running of before and after scripts.
OR
Select report & continue from the When actions fail drop-down list to report
errors during the running of before and after scripts.
OR
Select abort distribution from the When actions fail drop-down list to stop the
distribution if errors occur during the running of before or after scripts.
71
dialog box.
Modifying the comment in an adapter configuration profile

record
You can modify the comment field of a record.
task.
Activity
Context
Required Role
Modify the comment in an

record

Perform the following steps to modify the comment in an adapter configuration
profile record from the Tivoli desktop:
5. Enter your comments in the Comments scrolling list.
dialog box.
Modifying the UID and GID in an adapter configuration profile

record
You can modify the user ID (UID) and group ID (GID) that a record uses.
task.
Activity
Context
Required Role
Modify the UID and GID in

profile record

Perform the following steps to modify the UID and GID in an adapter
5. Enter the UID in the User text box.
72
6. Enter the GID in the Group text box.

dialog box.
Specifying the adapter identifier name

Use an adapter identifier name to run multiple instances of an adapter. For
example, you might want to run specific logfile adapter instances for individual
applications that are installed on a particular system. You can specify an adapter
identifier name for the following adapter types: tecad_logfile_aix4-r1,
tecad_logfile_hpux10, tecad_logfile_linux_ix86, tecad_logfile_linux-ppc,
tecad_logfile_linux-s390, tecad_logfile_solaris2, and tecad_win.
task.
Activity
Context
Required Role
Modify the adapter identifier

name

Perform the following steps to modify the adapter identifier in an adapter
5. Click the Identifier check box.
6. Enter the identifier name in the Identifier Name text box.
dialog box.
Copying an adapter configuration profile record

You can copy adapter configuration profile records from one adapter configuration
profile to another. The profiles must be in different profile managers.
task.
Activity
Context
Required Role
Copy an adapter
You can copy an adapter configuration profile record from the desktop or the
command line.
73
Copying an adapter configuration profile record from the

Tivoli desktop
Perform the following steps to copy an adapter configuration profile record from
the Tivoli desktop:
Manager window.
3. Select the record or records you want to copy.
Note: You can select multiple records by selecting one record and dragging the
mouse pointer up or down the profile entries, by pressing the Ctrl key
and selecting multiple records, or by using the Find Record dialog box.
For information about using the Find Record dialog, see Finding an
adapter configuration profile record on page 76.
4. Select Copy Entries from the Edit menu to display the Copy Profile Records
dialog box.
5. Select the profile manager that contains the target adapter configuration profile
you want to copy the entry to from the Available Profile Managers scrolling
list.
The adapter configuration profiles that are in the ACPM1 profile manager are
shown in the Available Profiles scrolling list.
6. Select a target profile from the Available Profiles scrolling list.
7. Click the right arrow button to move the selection to the Target Profiles
scrolling list.
8. Click the Copy & Close button to copy the record and close the Copy Profile
Records dialog box.
Moving an adapter configuration profile record

Moving an adapter configuration profile record deletes the record from the source
profile and adds it to the target profile. The target and source profiles can be in the
same or in different profile managers.
task.
Activity
Context
Required Role
Move an adapter
You can move an adapter configuration profile from the desktop or the command
line.
Moving an adapter configuration profile Record from the Tivoli

desktop
Perform the following steps to move an adapter configuration profile record from
the Tivoli desktop:
Manager window.
74

3. Select the adapter configuration profile record you want to move.
4. Select Move Entries from the Edit menu to display the Move Records dialog
box.
5. Select the profile manager that contains the target adapter configuration profile
you want to move the entry to from the list of Available Profile Managers. The
adapter configuration profiles that are in the ACPM1 profile manager are
shown in the Available Profiles scrolling list.
6. Select the target profile from the Available Profiles scrolling list.
7. Click the Move & Close button to move the adapter configuration profile
record to the target and close the Move Records dialog box.

If you no longer need an adapter configuration profile record, you can delete it
from the adapter configuration profile. The Adapter Configuration Facility removes
the record from all copies of the profile.
task.
Activity
Context
Required Role
Delete an adapter
You can delete an adapter configuration profile record from the desktop or the
command line.
Deleting an adapter configuration profile record from the

Tivoli desktop
Perform the following steps to delete an adapter configuration profile record from
the Tivoli desktop:
Manager window.
3. Select the adapter configuration profile record you want to delete and click the
Delete Entries button.
Deleting an adapter configuration profile record from the

command line
The following example command deletes an adapter configuration profile record
from the command line:
wdelac rec_num ACPM1:Profile1
where:
rec_num
Specifies one or more record numbers to delete from the profile, separated
by spaces.
75
ACPM1:Profile1
Specifies the name of the adapter configuration profile.
For more information about the wdelac command, see the Tivoli Management
Locking and unlocking an adapter configuration profile record

Locking an adapter configuration profile record prevents subscribers from editing
or deleting the record. You must distribute the adapter configuration profile for the
lock to take effect. Subscribers cannot edit or delete a record until you unlock the
record and distribute the profile again.
You can lock all the records in a top-level profile to help ensure that the copies of
the profile are always similar. Since you cannot lock an entire profile, it is possible
for an administrator to add a record to a lower-level profile copy.
task.
Activity
Context
Required Role
Lock or unlock an adapter

Locking and unlocking an adapter configuration profile

Record from the Tivoli desktop
Perform the following steps to lock or unlock an adapter configuration profile
record from the Tivoli desktop:
Manager window.
3. Select the adapter configuration profile records you want to lock or unlock.
4. Select Lock Entries from the Edit menu to lock the records, or select Unlock
Entries from the Edit menu to unlock the records.
Finding an adapter configuration profile record

You can find and highlight adapter configuration profile records based on criteria
you set for searching within a profile. The find record feature is most useful when
you have numerous records in an adapter configuration profile.
task.
Activity
Context
Find an adapter
Adapter configuration profile user
76
Required Role
Perform the following steps to find an adapter configuration profile record from
the Tivoli desktop:
Manager window.
3. Select Find from the View menu to display the Find Records dialog box.
4. Select the field to search from the Attributes scrolling list.
5. Select one of the following types of searches:
v Contains
Specifies that the records found contain a string value.
v Exact match
Specifies that the records found exactly match the search criteria.
v Greater than
Specifies that the value of the chosen attribute for the records found be
greater than the value of the search criteria.
v Less than
Specifies that the value of the chosen attribute for the records found be less
than the value of the search criteria.
6. Enter a value for the search criteria. The search criteria can be any valid value
for the selected attribute. A completed Find Records dialog is displayed.
7. Click Find First to select the first instance of a record that meets the criteria.
OR
Click Find Next to select the next instance of a record that meets the criteria.
OR
Click Find All to select all of the records that meet the criteria.
The Adapter Configuration Facility displays the Adapter Configuration Profile
window with the records that meet the specified criteria selected.
Perform the following steps to narrow a record search from the Tivoli desktop:
a. From the Adapter Configuration Profile window, select Show Selected
Records to eliminate the deselected records from view. (The records are still
in the profile, but they are not displayed.)
b. Enter additional search criteria in the Find Records dialog box.
c. Click the Find First, Find Next, or Find All button to select the records that
meet the search criteria.
d. Repeat steps a through c until you display only a few records.
e. Click Close in the Find Record dialog to close the dialog and return to the
Adapter Configuration Profile window.
You can edit or delete or perform similar operations on the selected records.
Sorting adapter configuration profile records

You can sort records so that the records are easier to maintain and modify.
77
task.
Activity
Context
Required Role
Sort adapter configuration

profile records

Perform the following steps to sort adapter configuration profile records from the
Tivoli desktop:
Manager window.
3. Select Sort > Records from the View menu to display the Sort Records dialog
box.
4. Select the attribute you wish to sort by from the Sort By scrolling list.
5. Select the attribute that you want to use as the record label from the Record
Label Field scrolling list.
6. If you want to sort the adapter configuration profile records in alphanumeric
order, click the Descending Sort radio button. Otherwise, click the Ascending
Sort radio button to sort the records in reverse alphanumeric order.
7. Click the Sort & Close button to sort and label the entries.
Sorting adapter configuration profile attributes

You can set which attributes are displayed and the order in which they are
displayed in the Adapter Configuration Profile window.
task.
Activity
Context
Required Role
Sort adapter configuration

profile attributes

Perform the following steps to sort the attributes of an adapter configuration
profile from the Tivoli desktop:
Manager window.
3. Select Sort > Attributes from the View menu to display the Display
Attributes dialog box.
4. Use the right arrow button to move the attributes you do not want to display
from the Attributes Displayed scrolling list to the Attributes Not Displayed
scrolling list.
78
5. Select an attribute from the Attributes Displayed scrolling list and use the up
or down arrow button to move it to the position in which it is to be displayed
in the Adapter Configuration Profile window.
Repeat this step until all the attributes are listed in the order you want them
displayed.
6. Click Sort & Close to sort and display the attributes in the Adapter
Configuration Profile window and close the Display Attributes dialog box.
When you close the Adapter Configuration Profile window or click the Show
All button, the results of the sort are cleared. The records themselves are
unchanged.
Starting the Logfile Format Editor from an adapter configuration profile

You can start the Logfile Format Editor from a logfile or Windows adapter
configuration profile.
task.
Activity
Context
Required Role
Start Logfile Format Editor

from an adapter

Perform the following steps to start the Logfile Format Editor from an adapter
configuration profile from the Tivoli desktop:
1. Select a record from an adapter configuration profile.
3. Click the Logfile Format Editor button to display the IBM Tivoli Enterprise
Console Logfile Format Editor window. See Appendix D, Logfile Format
Editor, on page 207 for information about using the Logfile Format Editor.
79
80
Chapter 4. AS/400 alert adapter

The AS/400 alert adapter forwards events from an AS/400 system to the event
server. The adapter can be registered with the startup configuration of the AS/400
so that the adapter is started with all the other applications when the system is
started.
The AS/400 alert adapter is a program that performs the following actions:
v Monitors AS/400 alert filters (using data queues) for alerts
v Extracts information from the alerts
v Creates IBM Tivoli Enterprise Console events, using a class definition statement
(CDS) file
v Filters IBM Tivoli Enterprise Console events that are not important, using a
configuration file
v Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP
sockets) that runs user-created rules against these events
AS/400 alert events can be gathered from any alert filter, or from the supplied
default filter. Multiple AS/400 alert adapters can be running at the same time, each
monitoring a different filter.
A few of the benefits are as follows:
v Consolidates alert monitoring
v Integrates with existing AS/400 alert filters already defined to your specific
business rules
v Filters out SNA (Systems Network Architecture) alerts that are not important
and notifies the Tivoli operators only when something critical happens
v Automatically acts on events using customer defined rules and tasks (using the
event server)
v Centrally configures adapter files that can be sent to the remote AS/400 systems
Adapter files
The AS/400 alert adapter package consists of the following files:
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR
The configuration file
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR
The CDS file
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBR
The BAROC file
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBR
The rules file
Make a backup copy of the CFG_ALERT file before modifying the contents of any
of the members.
A backup copy of this file also resides in the CFG_ALERT file in library
QTMETECA02.
81
The AS/400 adapter package also consists of the following commands, which are
copied into QSYS upon installation of the product:
STRTECADP
Starts an AS/400 adapter.
ENDTECADP
Ends an AS/400 adapter.
Before starting the event server and an AS/400 alert adapter, check the
configuration file to determine if it defines the preferred adapter behavior.
Configuration file
The configuration file for the AS/400 alert adapter defines the behavior of the
adapter, which runs as a job on the AS/400.
A configuration file is created during the installation of the AS/400 alert adapter.
The name of this file is
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR. This file must
specify either ServerLocation or TransportList. All other keywords have default
values that are used if values are not specified.
The configuration file can contain the common keywords described in
Configuration file on page 9, as well as the following adapter-specific keywords:
AdapterType
Specifies the type of resource to be monitored. The default value is

MSGQ if this keyword is not defined, meaning that the adapter
monitors a message queue. The value provided in the
configuration file is ALERT.
AdapterCdsFile
Specifies the CDS file to be used for the AS/400 alert adapter. This
file can reside in either the QSYS or IFS name space, but the path
must be specified in IFS notation, for example:
/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR
The default path is as follows:

/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR
BufEvtPath
Specifies the path and name of the buffer file for the AS/400 alert
adapter. The default path is /etc/Tivoli/tec, and the default buffer
file name is the value specified for the adapter name on the
AS/400 command (STRTECADP), used to start the adapter.
Note: If an AS/400 alert adapter attempts to open a buffer file that
is in use by another adapter, the adapter (which runs as a
batch job) attempting to open the file ends.
Filter
The name of the AS/400 alert filter to be monitored. The default

value is QTMETECA02/QYAAFTR.
FilterDataQueue
The specific data queue that the adapter is to monitor for incoming
alerts. If the alert filter is registered with the system, this keyword
is required and the data queue must be created by the user before
the AS/400 alert adapter is started. This keyword is optional if the
alert filter defined by the Filter keyword is not registered with the
system, or if the Filter keyword is not specified.
82
JobDescription
Specifies an AS/400 job description that is to be used when
starting the adapter. The default value is QGPL/QDFTJOBD.
LanguageID
Specifies the AS/400 language ID in which alerts are to be sent to

the event server. If a value is specified for this keyword, the
AS/400 secondary language must be installed for that language ID.
The default value for this keyword is ENU.
ProcessExistingAlerts
Specifies whether to send existing alerts on the data queue defined
by the FilterDataQueue keyword. NO sends any new alerts sent to
the data queue. YES sends the next alert received on the data
queue. This can cause the adapter to send previously sent alerts
again and create duplicate events sent to the event server. The
default value is NO.
ServerCCSID Specifies the coded character set identifier (CCSID) of the event
server. This is in case the event server has a special code page or
graphic character set that needs to be supported. The default value
is 00819.

The CDS file defines how events are constructed from information sent by the
AS/400 alert adapter. It is described in detail in Class definition statement file on
page 25.
SELECT statement example

SELECT
1:ATTR(=,$ALERT_CDPT),VALUE(PREFIX, "10"); # 10xx codepoints
Here, $ALERT_CDPT is a custom keyword set by the adapter. These keywords can
be used to write shorthand notation for SELECT statements. The following is
equivalent to the previous example:
SELECT
1:$ALERT_CDPT=10";
FETCH statement example

FETCH
1:SUBSTR($V1, 0, 3);
This FETCH statement sets variable $F1 to the substring of $V1, which is a
variable, starting at character 0 for a length of 3 characters.
Keywords
To customize events, the AS/400 alert adapter supports the following keywords in
class definition statements. Evaluation of these keywords is faster because access of
them is direct. Event definition content and syntax are described in the IBM Tivoli
Enterprise Console Rule Developers Guide.
$ACTIONS
Recommended actions to be taken for the alert.
$ACTION_CODE
The legacy action code for non-generic alerts (alert subvector X'91').
$ADAPTER_CORREL
Unique alert identifier used to extract the alert from the alert
database on the AS/400 system.
83
$ADAPTER_HOST
The protocol address of the host where the adapter is running.
$ADAPTER_HOST_SNANODE
The netID.nau name of the host where the adapter is running.
$ALERT_CDPT
The alert code point that provides an index into predefined text
describing the alert condition.
$ALERT_ID
The unique ID describing the alert.
$ARCH_TYPE Defines the alert type, either NONGENERIC_ALERT (alert

subvector X'91') or GENERIC_ALERT (alert subvector x92).
$BLOCK_ID
The legacy block ID for non-generic alerts (alert subvector X'91').
$CAUSES
Alert causes collected from alert subvectors X'93', X'94', X'95', X'96',
and X'97'.
$DATE
$DETAILED_DATA
Product specific detail data from alert subvector X'98'.
$EVENT_CORREL
Alert correlation data from alert subvector X'47'.
$EVENT_TYPE
A value indicating the severity of the alert condition (for example,
PERMANENT, TEMPORARY, or IMPENDING PROBLEM).
$HOSTNAME
The netID.nau name of the host where the alert originated.
$INCIDENT_CORREL
Alert correlation data from alert subvector X'4A'.
$MSG
The alert code point text and the first probable cause text for the
alert.
$ORIGIN
The hierarchy list of the alert origin.
$PRODUCT_ID
The hardware and software identifier from alert subvector X'10'.
$SELF_DEF_MSG
The general message text from alert subvector X'31'.
$SEVERITY
The severity of the event.
$SOURCE
The source of the event. The source is defined by the adapter type
AS400_ALERT.
$SUB_ORIGIN
The last member in the hierarchy list of the alert origin.
Configuring the AS/400 alert filters

Default alert filter
The AS/400 alert adapter creates a default alert filter, QTMETECA02/QYAAFTR,
at installation time. This filter consists of a selection entry that maps all alerts to
the group QTECALERT. The corresponding action entry for QTECALERT is also
provided. When the AS/400 alert adapter is started, a data queue is created and
84
the QTECALERT action entry is updated with the data queue name so incoming
alert information can be monitored by the adapter.
If you use the default filter provided, copy it into library QUSRSYS and modify it
there.
Integrating with an existing alert filter

You might have alert filters that are already in use on your AS/400 system. These
filters have been set up with the appropriate selection and action entries to filter
alerts of interest and route them to predefined groups.
The Filter keyword in the configuration file is used to indicate the name of the
filter that the AS/400 alert adapter is to monitor. If a value for this keyword is not
specified, the default filter (QTMETECA02/QYAAFTR) is used.
The FilterDataQueue keyword in the configuration file is used to indicate the name
of the data queue that the adapter is to monitor. The adapter assumes that this
data queue has been created properly and has been incorporated into the
appropriate action entries data queue list for the filter defined by the Filter
keyword. To update an action entry, use the CHGALRACNE (Change Alert Action
Entry) command. Create the data queue with the Create Data Queue (CRTDTAQ)
command as follows:
CRTDTAQ DTAQ(library/name) TYPE(*STD) MAXLEN(592)
FORCE(*NO) SEQ(*FIFO)
Note: If the data queue is not created according to the previous specifications, the
adapter will not start. Also, if the AS/400 alert adapter is not running, the
system still sends alert information to this data queue. If the data queue is
filled to capacity, the filter might be automatically deregistered by the
system. To prevent this problem, have the adapter automatically started by a
startup program when the system is started (see Starting the adapter on
page 85).
The AS/400 Network Attributes define the filter that is registered with the system.
If the specified alert filter is registered with the system, then the FilterDataQueue
keyword is required. If the filter is not registered with the system and the
FilterDataQueue keyword is not specified, then a data queue is created and
associated with the QTECALERT group in that filter. Use the Change Network
Attributes (CHGNETA) command if you want to register the filter on the AS/400
system.
Starting the adapter

The AS/400 adapter includes the STRTECADP command that you can use to start
an adapter. You can also automatically start the adapter; see Starting an AS/400
adapter after an IPL on page 93. The command is described on the following
pages.
85
STRTECADP
Syntax
STRTECADP EVTADP(name) CFGFILE(filename)
Description
The AS/400 adapter runs as a batch job. The STRTECADP command starts an
AS/400 adapter.
Authorization:
QSYSOPR
*USE
PUBLIC
*EXCLUDE
Note: To grant other users authority to this command, use the following
commands on the AS/400 system:
GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA02/STARTALERT) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMRRGF) OBJECTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMDRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)
Arguments:
EVTADP(name)
Specifies a name for the adapter being started. This name is used on the
ENDTECADP AS/400 command. It can be any valid AS/400 job name;
however, each adapter running on the AS/400 system must have a unique
name.
CFGFILE(filename)
Specifies the full path name of the configuration file, in IFS format, to be
used.
The following command starts an AS/400 alert adapter using the default
configuration file.
STRTECADP EVTADP(ALERTADP)
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR)
The following command starts the AS/400 alert adapter with the
/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file.
STRTECADP EVTADP(MYADP)
CFGFILE(/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR)
86
Stopping the adapter

The AS/400 adapter includes the ENDTECADP command that you can use to stop
adapters individually or to stop all started adapters. The command is described on
the following pages.
87
ENDTECADP
Stops the AS/400 adapter.
Syntax
ENDTECADP EVTADP(name | *ALL) [OPTION(*CNTRLD | *IMMED)]
[DELAY(seconds)]
Description
The AS/400 adapter runs as a batch job. The ENDTECADP command stops an
AS/400 adapter.
Authorization:
QSYSOPR
*USE
PUBLIC
*EXCLUDE
Note: To grant other users authority to this command, use the following
commands on the AS/400 system:
GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments:
EVTADP
OPTION
Specifies the name of the adapter to stop. The following options

can be specified:
name
Specifies the name of the adapter being stopped. This file

name matches the name specified on the STRTECADP
command.
*ALL
If *ALL is specified, then all adapters of all types are

stopped.
Specifies the way the adapter stops. The following options can be
specified:
*CNTRLD
The adapter ends in a controlled manner. This lets the
application program perform end-of-job processing.
*IMMED
The adapter is ended immediately.
Stopping the adapter immediately does not allow the
adapter to perform cleanup routines and is not
recommended.
DELAY(seconds)
Specifies the amount of time in seconds allowed for the adapter to
complete its cleanup processing during a controlled end. This
parameter is not used if *IMMED is specified for the OPTION
parameter. If the cleanup is not completed before the end of the
delay time, the adapter is ended immediately.
Examples
The following command stops the AS/400 alert adapter, started with the adapter
name ALERTADP.
88
ENDTECADP EVTADP(ALERTADP)
The following command stops the AS/400 alert adapter, started with the adapter
name MYCFG, in a controlled manner with a delay time of 60 seconds.
ENDTECADP EVTADP(MYCFG) OPTION(*CNTRLD) DELAY(60)
89
Events Listing
The following shows the class names and severities of all events defined for the
AS/400 alert adapter. You can use it to get a sense of how AS/400 alert events are
mapped to IBM Tivoli Enterprise Console events and to determine if you want to
make any changes. The events are defined in the tecad_snaevent.baroc file on the
event server.
See the IBM Tivoli Enterprise Console Rule Developers Guide for more information
about customizing the BAROC file.
Event class structure

Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The AS/400 alert event classes follow a simple hierarchy.
The attribute value for source is AS400_MSGQ. The following events are defined
in the sample BAROC file provided with this product:
Table 10. Event class structure
Event Class
AS400_TEC_ALERT_ADAPTER
(based on AS/400
alert type)
SNA_Event
CRITICAL
SNA_1xxx_Hardware
CRITICAL
SNA_Equipment_Malfunction
CRITICAL
SNA_Input_Device_Error
CRITICAL
SNA_Output_Device_Error
CRITICAL
SNA_Input_Output_Device_Error
CRITICAL
SNA_Loss_Of_Electrical_Power
CRITICAL
SNA_Loss_Of_Equipment_Cooling_Or_ Heating
CRITICAL
SNA_Subsystem_Failure
CRITICAL
SNA_Hardware
CRITICAL
SNA_2xxx_Software
CRITICAL
SNA_Software_Program_Abnormally_ Terminated
CRITICAL
SNA_Software_Program_Error
CRITICAL
SNA_Software_Operation_Failure
CRITICAL
SNA_Software
CRITICAL
SNA_3xxx_Communications
90
Default Event
Severity
CRITICAL
SNA_Communication_Protocol_Error
CRITICAL
SNA_SNA_Protocol_Error
CRITICAL
SNA_LAN_Error
CRITICAL
SNA_Link_Error
CRITICAL
SNA_ISDN_Error
CRITICAL
SNA_Local_Connection_Error
CRITICAL
SNA_Link_Connection_Error
CRITICAL
SNA_BBNS_Communications_Error
CRITICAL
SNA_Communications
CRITICAL
Table 10. Event class structure (continued)

Default Event
Severity
Event Class
SNA_4xxx_Performance
CRITICAL
SNA_Performance_Degraded
CRITICAL
SNA_Performance
CRITICAL
SNA_5xxx_Congestion
CRITICAL
SNA_Congestion
CRITICAL
SNA_Configurable_Capacity_Limit_Reached
CRITICAL
SNA_Congestion_Other
CRITICAL
SNA_6xxx_Microcode
CRITICAL
SNA_Microcode_Program_Abnormally_ Terminated
CRITICAL
SNA_Microcode_Program_Error
CRITICAL
SNA_Microcode_Program_Mismatch
CRITICAL
SNA_Microcode
CRITICAL
SNA_7xxx_Operator
CRITICAL
SNA_Operator_Procedural_Error
CRITICAL
SNA_Operator
CRITICAL
SNA_8xxx_Specification
CRITICAL
SNA_Configuration_Or_Customization_Error
CRITICAL
SNA_Specification
CRITICAL
SNA_9xxx_Intervention_Required
CRITICAL
SNA_Operator_Intervention_Required
CRITICAL
SNA_Stock_Low
CRITICAL
SNA_Stock_Exhausted
CRITICAL
SNA_Depository_Full
CRITICAL
SNA_Intervention_Required
CRITICAL
SNA_Axxx_Problem_Resolved
SNA_Problem_Resolved
SNA_Bxxx_Notification
CRITICAL
CRITICAL
CRITICAL
SNA_Operator_Notification
CRITICAL
SNA_Environmental_Problem
CRITICAL
SNA_Resent_Alert_With_Updated_Information
CRITICAL
SNA_Notification
CRITICAL
SNA_Cxxx_Security
CRITICAL
SNA_Security_Event
CRITICAL
SNA_Security
CRITICAL
SNA_Exxx_Non_IBM_Codepoint
CRITICAL
SNA_Fxxx_Undetermined
CRITICAL
SNA_Undetermined_Error
CRITICAL
SNA_NonGeneric_Undetermined
CRITICAL
SNA_Reserved_By_IBM
CRITICAL
91
You can set the severity of an AS/400 alert event on the event console as follows,
based on the AS/400 alert type field specified in the message description:
Alert Type
Default Severity
01 (permanent loss of availability)
CRITICAL
04 (operator intervention required)
CRITICAL
09 (unavailable network component)
CRITICAL
0E (security problem)
CRITICAL
10 (permanently affected resource)
CRITICAL
03 (performance degradation)
WARNING
0A (notification: loss impending)
WARNING
0C (installation consistency)
WARNING
0D (operational procedural error)
WARNING
0F (delayed condition)
WARNING
11 (impending problem)
WARNING
14 (bypassed loss of availability)
WARNING
16 (monitored situation event)
WARNING
0B (environmental problem)
MINOR
12 (unknown)
UNKNOWN
02 (temporary loss of availability)
HARMLESS
05 (reserved)
HARMLESS
06 (reserved)
HARMLESS
07 (reserved)
HARMLESS
08 (reserved)
HARMLESS
13 (retired)
HARMLESS
other values
HARMLESS
Troubleshooting the AS/400 adapter

If a problem occurs with the AS/400 adapter, you can perform problem
determination by investigating the job the adapter is running in. Each time you
start an AS/400 adapter, a batch job is started. You can view the adapter job by
issuing the following command:
WRKJOB JOB(name)
where name is the name of the adapter job that matches the name specified on the
STRTECADP command. This displays the Work with Job dialog.
Note: Several adapter jobs might have existed on your AS/400 system with the
same name as the current adapter job. In this case, you are first presented
with a list of jobs to choose from. Select the most recent job from the list.
From the Work with Job dialog, you can select option 10 to display the job log, or
if the job has ended (selecting option 10 tells you so), you can view the job log that
was generated by selecting option 4.
Examine the job log for messages indicating the error that occurred and follow the
corrective action specified. For further assistance, contact Customer Support.
92
Logging Events in Test Mode

The file to which events are logged in test mode (instead of being sent to an event
server) is created with a record length of 240 bytes if it does not exist. Because an
event written to this file does not wrap to a new line if it is longer than 240 bytes,
it is truncated. To avoid truncation, create the file ahead of time using the CRTPF
or CRTSRCPF commands and specify a large enough record length to
accommodate your events. To utilize this file, ensure that it is specified for the
ServerLocation keyword. For additional information, see Keywords on page 10.
Also, be sure that you use the proper format, ABCLIB/TECMSGS
(library/file_name). If the file does not exist, it is created automatically.
TCP/IP considerations
Ensure that the event server and the AS/400 are configured in your network Name
Server, and that the AS/400 is configured to resolve to the Name Server.
If you do not use a Name Server in your network, make sure that an entry exists
on the AS/400 in the TCP/IP host table for both the event server and the AS/400
system. Use the following commands to do this:
ADDTCPHTE INTNETADR(event server protocol address)
HOSTNAME((event server host name))
TEXT(Tivoli Enterprise Console event server)
ADDTCPHTE INTNETADR(AS/400 protocol address)
HOSTNAME((AS/400 host name)) TEXT(AS/400)
Starting an AS/400 adapter after an IPL

There are two methods that can be used to start an AS/400 alert adapter
automatically after an initial program load (IPL), as follows:
v Adding an autostart job to a job queue
v Modifying the AS/400 startup program to call the STRTECADP command

1. Create a Control Language (CL) program that calls the STRTECADP
command, for example:
a. Edit a source file member to add CL statements:
STRSEU QGPL/QCLSRC STRADPCL
b. Enter the following in the source file member. You can have a STRTECADP
command for each adapter you would like to start:
PGM
STRTECADP EVTADP(NEWFILTER) +
ENDPGM
Note: Ensure that the TCP/IP service is started on the AS/400 system
before starting an adapter.
c. Create the program using the previous source program:
CRTCLPGM
PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)
2. Create a job description that calls the previous program and use QSYSNOMAX
as the job queue:
93
CRTJOBD JOBD(QGPL/STARTADP)
JOBQ(QSYSNOMAX)
TEXT(Start TEC adapter after IPL.)
RQSDTA(CALL QGPL/STRADPCL)
3. Add an auto start job entry in QSYSWRK using the previous job description:
ADDAJE SBSD(QSYSWRK)
JOB(TECAMSGQ)
JOBD(QGPL/STARTADP)
This program runs at the start of QSYSWRK subsystem and ends quickly after
doing the STRTECADP command.

The system value QSTRUPPGM (startup program) contains the name of the
program to run after IPL. This program can be modified to add the starting of
adapters.
1. Retrieve the code in the startup program:
RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
SRCMBR(program-name)
2. Modify the source:

PGM
DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)
DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)
QSYS/STRSBS SBSD(QCMN)
STRTCP
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QSERVER)
STRTECADP EVTADP(ALERTADP)+
DONE:
RETURN
CHGVAR VAR(&CPYR) VALUE(&CPYR)
ENDPGM
3. Create the program and put it in the QSYS library:

CRTCLPGM PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
Note: The startup program runs under user profile QPGMR. The default
setting is that QPGMR does not have authority to the AS/400 alert
adapter commands and programs. You must either grant QPGMR
authority to the commands and programs (Starting the adapter on
page 85) or have the startup program adopt QSECOFR authority and be
owned by QSECOFR.
Multiple AS/400 alert adapters

To support another AS/400 alert adapter to monitor a different alert filter or
another data queue within the same filter, create the following additional files:
v Configuration file: Specifies the filter to monitor and data queue to monitor.
v CDS file: Defines new classes to match the alerts being monitored.
v BAROC file: Required if new classes are identified in the CDS file.
v Rules file: Required if new rules are added.
94
Configuration file
To create the configuration file, perform the following steps:
1. Copy the adapter files using the following commands:
CPYF FROMFILE(QUSRSYS/CFG_ALERT)
TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)
TOMBR(*FROMMBR) CRTFILE(*YES)
2. Update the configuration file to show the keywords pointing to the new
objects, as follows:
AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR
Filter=mylib/myfilter
FilterDataQueue=mylib/mydtaqueue
3. Update the CDS and the BAROC files to include any new classes and filters.
4. Update the rules file to include any new rules.
5. On the event server, import the BAROC file into the rule base; then, compile
and load the rule base.
6. Start the adapter using the new adapter files as follows:
STRTECADP EVTADP(MYEVTADP)
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR)
95
QTMETECA/POSTEMSG
Posts an event to the event server. See the IBM Tivoli Enterprise Console Command
and Task Reference for more details about this command.
Syntax
QTMETECA/POSTEMSG { S<server> | f<config_file> } [r<severity>]
[m<message>] [<slot_name=value>, ...] <class> <source>
Note: There cannot be a space between the option letter and the option value.
Examples
Call QTMETECA/POSTEMSG PARM(Sserver_name rHARMLESS
mThis is a message AS400_MSG LOGFILE)
Call QTMETECA/POSTEMSG
PARM(f/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR
rFATAL mThis is a message AS400_MSG LOGFILE)
96
Common tasks
Use these commands to perform common tasks related to the AS/400 alert adapter.
v To load the AS/400 alert and message adapters with English as a primary
language:
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC)
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1)
SAVF(QUSRSYS /ATMETEC1)
v To load the AS/400 message and alert adapters with English as a secondary
language:
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC)
LNG(2924) SAVF(QUSRSYS/ATMETEC1)
v To delete all AS/400 adapters from the AS/400 system:

DLTLICPGM LICPGM(1TMETEC)
v To delete only the AS/400 alert adapter from the AS/400 system:
DLTLICPGM LICPGM(1TMETEC) OPTION(2)
Delete the alert adapter (lib QTMETECA02)
v To start the AS/400 alert adapter:

STRTECADP EVTADP(ALRNAME) CFGFILE(QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR)
v To stop the adapter:

ENDTECADP EVTADP(ADPNAME)
97
98
Chapter 5. AS/400 message adapter

The AS/400 message adapter forwards events from an AS/400 system to the event
server. It can be registered with the startup configuration of the AS/400 system so
that the adapter is started with all the other applications when the AS/400 system
is started. See Starting an AS/400 adapter after an IPL on page 112 for
instructions on starting the adapter automatically with the AS/400 system.
The AS/400 message adapter is a program that performs the following actions:
v Reads messages from a message queue on an AS/400 system
v Extracts information from the message
v Creates IBM Tivoli Enterprise Console classes, using a class definition statement
(CDS) file
v Filters IBM Tivoli Enterprise Console events that are not important, using a
configuration file
v Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP
sockets) that runs user-created rules against these events
AS/400 message events can be gathered from any non-program message queue,
including the system operator message queue QSYSOPR. Multiple AS/400 message
adapters can be running at the same time. One AS/400 message adapter can
monitor the system operator message queue while another is monitoring an
application message queue.
A few of the benefits of the AS/400 message adapter are as follows:
v Consolidates the system operator message console, QSYSOPR, for all the AS/400
systems in your enterprise
v Monitors applications that use message queues
v Filters out messages that are not important and only notifies the Tivoli operators
when something critical happens
v Automatically acts on events using customer-defined rules and tasks (using the
event server)
v Centrally configures adapter files that can be sent to remote AS/400 systems
Adapter Files
The AS/400 adapter package consists of the following files:
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR
The configuration file.
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR
The CDS file.
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGBRC.MBR
The BAROC file. This file is located on the event server with the
name of as400msg.baroc. It is automatically compiled into the
active rule base when the event server is installed.
Make a backup copy of the CFG_MSG file if you intend to modify the contents of
any of the members.
99
A backup copy of each of these files also resides in the CFG_MSG file in library
QTMETECA01.
Before starting the event server and an AS/400 message adapter, check the
configuration file to determine if it defines the preferred adapter behavior.
Configuration file
The configuration file for the AS/400 message adapter defines the behavior of the
adapter, which runs as a job on the AS/400 system.
A configuration file is created during the installation of the AS/400 message
adapter. The name of this file is
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR. The configuration file
can contain the keywords described in Configuration file on page 9, as well as
the following custom keywords:
AdapterType
Specifies the type of resource to be monitored. The default value is

MSGQ, meaning that the adapter monitors a message queue.
AdapterCdsFile
Specifies the CDS file to be used for the AS/400 message adapter.
This file can reside in either the QSYS or IFS name space, but the
path must be specified in IFS notation, for example:
/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR
The default path is as follows:

/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR
BufEvtPath
Specifies the path and name of the buffer file for the AS/400
message adapter. The default path is /etc/Tivoli/tec, and the
default buffer file name is the value specified for the adapter name
on the AS/400 command (STRTECADP), used to start the adapter.
Note: If an AS/400 message adapter attempts to open a buffer file
that is in use by another adapter, the adapter (which runs as
a batch job) attempting to open the file ends.
JobDescription
Specifies an AS/400 job description that is to be used when
starting the adapter. The default value is QGPL/QDFTJOBD.
LanguageID
Specifies the AS/400 language ID in which the AS/400 messages

are to be sent to the event server. The default value for this
keyword is ENU. If a value is specified for this keyword, the
AS/400 secondary language must be installed for that language ID.
MsgQueue
Specifies the AS/400 message queue to poll. The complete name

needs to be specified. The message queue must exist when the
adapter is started. If the message queue is cleared while the
adapter is active, the adapter starts with new messages that are
written after the message queue was cleared. The value of this field
must be in the following format:
mylib/mymsgq
The default value is QSYS/QSYSOPR.
PollInterval
100
Specifies the amount of time in seconds to return to a suspended
state between checking for new events that have been placed on
the message queue. The default value is 20. The following example
shows the format:
PollInterval=60
ProcessExistingMsgs
Specifies whether the AS/400 messages adapter resets back to the
first message on the message queue when starting. NO sends any
new messages to the message queue. YES sends the first message
on the message queue. This could cause the adapter to resend
previously sent messages and create duplicate events sent to the
event server. The default value is NO.
ServerCCSID Specifies the coded character set identifier (CCSID) of the event
server. This is in case the event server has a special code page or
graphic character set that needs to be supported. The default value
is 0819.

The file /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGCDS.MBR defines how
events are constructed from information sent by the AS/400 message adapter. It is
described in detail in Class definition statement file on page 25.
SELECT statement example

SELECT
1:ATTR(=,$MSG_ID), VALUE(=,CPI5933);
Here, $MSG_ID is a custom keyword set by the adapter. These keywords can be
used to write shorthand notation for SELECT statements. The following is
equivalent to the previous example:
SELECT
1:$MSG_ID=CPI5933;
For the $MSG_ID keyword, multiple low:high pairs can be specified with spaces as
separators. An example is as follows:
SELECT
1:$MSG_ID=CPF 0100:02FF 1000:1FFF 5600:56FF;
FETCH statement example

FETCH
1:SUBSTR($V1, 0, 3);
This FETCH statement sets variable $F1 to the substring of $V1, which is a
variable, starting at character 0 for a length of 3 characters.
MAP statement example

CLASS PerformanceInvestigator
SELECT
1:$MSG_ID=PNV *:*;
FETCH
1:SUBSTR($V1, 0, 3);
2:SUBSTR($V1, 3, 4);
MAP
my_field=PRINTF("attribute=%s has prefix=%s and id=%s", $V1,
$F1, $F2);
status=OPEN
END
101
Keywords
To customize events, the AS/400 message adapter supports the following
keywords in class definition statements. Evaluation of these keywords is faster
because access of them is direct. Event definition content and syntax are described
in the IBM Tivoli Enterprise Console Rule Developers Guide.
$ADAPTER_HOST
The protocol address of the host where the adapter is running.
$ALERT_OPTION
If and when an SNA alert is created and sent for the message. If a
message is received, the value is one of the following values:
*DEFER
An alert is sent after local problem analysis.
*IMMED
An alert is sent immediately when the message is sent to
the QHST message queue.
*NO
No alert is sent.
*UNATTEND
An alert is sent immediately when the system is running in
unattended mode (when the value of the alert status
network attribute, ALRSTS, is *UNATTEND).
$DATE
$DATA_CCSID_CONVERT_STATUS
The following are possible values returned:
0
No conversion was needed because the CCSID of the

replacement data or impromptu message text matched the
CCSID you wanted the data or text converted to.
No conversion occurred because either the data was 65535

or the CCSID you wanted the data converted to was 65535.
No conversion occurred because you did not supply

enough space for the data.
The data was converted to the CCSID specified using the

best fit conversion tables.
A conversion error occurred using the best fit conversion

tables, so a default conversion was attempted. This
completed without error.
An error occurred on both the best fit and default

conversions. The data was not converted.
$DATA_CCSID_RETURNED
The CCSID of the replacement data or impromptu message text is
returned. If an impromptu message is received, this is the CCSID
of the impromptu message text. When replacement data is
received, this is the CCSID of the replacement data fields defined
as convertible character (*CCHAR) in the message description. All
other replacement data is not converted before it is returned. If a
conversion error occurs or the CCSID you requested the data to be
converted to is 65535, the CCSID of the data or text is returned. If
replacement data is being returned and there is no *CCHAR
102
replacement data, 65535 is returned. Otherwise, the CCSID you

wanted the data converted to is returned.
$HOSTNAME
The name of the system on which the event occurred.
$MSG
The default message used.
$MSG_FILE_NAME
The name of the message file containing the message received.
$MSG_FILE_LIBRARY
The name of the library containing the message file. For the actual
library used when the message is sent, use the
$MSG_LIBRARY_USED keyword.
$MSG_HELP
The message help for the message received. If an immediate

message is received, this field is blank.
$MSG_ID
Indicates the AS/400 message identifier.
$MSG_KEY
The key to the message received.
$MSG_LIBRARY_USED
The name of the library used to send the message. Because the
library can contain override instructions, this is not necessarily the
library in which the message actually resides.
$MSG_SEVERITY
Specifies the severity. A two-digit value ranging from 0 through 99.
The higher the value, the more severe or important the condition.
$MSG_TYPE
$ORIGIN
The message type of the message received. The possible values and
their meanings are as follows:
01
Completion
02
Diagnostic
04
Informational
05
Inquiry
06
Sender copy
08
Request
10
Request with prompting
14
Notify
15
Escape
21
Reply, not validity checked
22
Reply, validity checked
23
Reply, message default used
24
Reply, system default used
25
Reply, from system reply list
The protocol address of the source system.
$SEND_DATE
The date on which the message was sent, in CYYMMDD (century,
year, month, day) format.
103
$SEND_JOB
The name of the job in which the message being received was sent.
$SEND_JOB_NUMBER
The job number of the job in which the message being received
was sent.
$SEND_PROGRAM_NAME
The program name or Integrated Language Environment (ILE)
program name that contains the procedure sending the message.
$SEND_TIME
The time at which the message being received was sent, in
HHMMSS (hour, minute, second) format.
$SEND_USER_PROFILE
The name of the user profile that sent the message being received.
$SEVERITY
The severity of the event.
$SOURCE
The source of the event. The source is defined by the adapter type
(AS400_MSGQ).
$SUB_ORIGIN
A further categorization of the origin.
$SUB_SOURCE
A further categorization of the source.
$TEXT_CCSID_CONVERT_STATUS
The following are possible values returned:
0
No conversion was needed because the CCSID of the

message or message help text matched the CCSID you
wanted the message or message help text converted to.
No conversion occurred because either the message or

message help text was 65535 or the CCSID you wanted the
message or message help text converted to was 65535.
No conversion occurred because you did not supply

enough space for the message or message help.
The message or message help text was converted to the

CCSID specified using the best fit conversion tables.
A conversion error occurred using the best fit conversion

tables, so a default conversion was attempted. This
completed without error.
An error occurred on both the best fit and default

conversions. The data was not converted.
$TEXT_CCSID_RETURNED
The CCSID of the text in the message and message help fields is
returned. The inserted replacement data might not be the same
CCSID. Refer to the $DATA_CCSID_RETURNED keyword for
more details. If a conversion error occurs or the CCSID you
requested the text to be converted to is 65535, the CCSID that the
message description is stored in is returned. Otherwise, the CCSID
you wanted your text converted to is returned. If you do not want
the text converted before it is returned to you but you do want to
know the CCSID that the message description is stored in, specify
65535 on the coded character set identifier parameter. The CCSID
104
that the message description is stored in is returned in the CCSID

of message and message help output field.
$ARG1 $ARG8
Used to identify message replacement text or values.

The AS/400 message adapter includes the STRTECADP command that you can
use to start an adapter. The command is described on the following pages.
105
STRTECADP
Syntax
STRTECADP EVTADP(name) CFGFILE(filename)
Description
The AS/400 adapters run as a batch job. The STRTECADP command starts an
AS/400 adapter.
Authorization:
QSYSOPR
*USE
PUBLIC
*EXCLUDE
To grant other users authority to this command, use the following commands on
the AS/400:
GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA01/STARTMSGAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments:
EVTADP(name)
Specifies a name for the adapter being started. This name is used
on the End TEC Adapter (ENDTECADP) AS/400 command. It can
be any valid AS/400 job name; however, each adapter running on
the AS/400 system must have a unique name.
CFGFILE(filename)
Specifies the full path name of the configuration file, in IFS format,
to be used.
Examples
The following command starts an AS/400 message adapter using the default
configuration file. The default configuration file monitors the system operator
message queue, QSYSOPR:
STRTECADP EVTADP(SYSOPR)
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR)
The following command starts the AS/400 message adapter with the
/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file. The
configuration file could be set up to monitor an application specific message
queue:
STRTECADP EVTADP(MYAPP)
CFGFILE(/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR)
106

The AS/400 adapter includes the ENDTECADP command that you can use to stop
adapters individually or to stop all started adapters. The command is described on
the following pages.
107
ENDTECADP
Stops the AS/400 adapter.
Syntax
ENDTECADP EVTADP(name | *ALL) [OPTION(*CNTRLD | *IMMED)]
[DELAY(seconds)]
Description
The AS/400 adapters run as a batch job. The ENDTECADP command stops an
AS/400 adapter.
Authorization:
QSYSOPR
*USE
PUBLIC
*EXCLUDE
To grant other users authority to this command, use the following commands on
the AS/400:
GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments:
EVTADP
Specifies the name of the adapter to stop. The following options can be
specified:
name
Specifies the name of the adapter being stopped. This name

matches the name specified on the Start TEC Event Adapter
command.
*ALL
If *ALL is specified, then all adapters of all types are stopped.
OPTION
Specifies the way the adapter stops. The following options can be specified:
*CNTRLD
The adapter ends in a controlled manner. This lets the application
program perform end-of-job processing.
*IMMED
The adapter is ended immediately.
Note: Stopping the adapter immediately does not allow the
adapter to perform cleanup routines and is not
recommended.
DELAY(seconds)
Specifies the amount of time in seconds allowed for the adapter to
complete its cleanup processing during a controlled end. This parameter is
not used if *IMMED is specified for the OPTION parameter. If the cleanup
is not completed before the end of the delay time, the adapter is ended
immediately.
108
Examples
The following command stops the AS/400 message adapter, started with the
adapter name SYSOPR, which was started to monitor the QSYSOPR message
queue:
ENDTECADP EVTADP(SYSOPR)
The following command stops the AS/400 message adapter, started with the
adapter name MYAPP, in a controlled manner that was set up to monitor an
application-specific message queue:
ENDTECADP EVTADP(MYAPP) OPTION(*CNTRLD) DELAY(60)
109
Events listing
The following shows the class names and severities of all events defined for the
AS/400 message adapter. You can use it to get a sense of how AS/400 messages
are mapped to IBM Tivoli Enterprise Console events and to determine if you want
to make any changes. The events are defined in the as400msg.baroc file on the
event server.

defaults from the parent. The AS/400 message event classes follow a simple
hierarchy. The AS/400 message adapter fills in the following attribute defaults. The
attributes are used in event group filters.
source AS400_MSGQ
sub_source
Fully qualified message queue name.
origin Protocol address of the system.
hostname
Name of the system from the host name table.
date
Date and time the message was sent.
msg
First level message text with replacement values.
The following events are defined in the sample BAROC file provided with this
product:
Table 11. Events defined in the sample BAROC file
Event Class
Default Severity
AS400_TEC_MSGQ_ADAPTER
(Based on the AS/400 message

severity)
00-19 HARMLESS
20-29 WARNING
30-39 MINOR
40-59 CRITICAL
60-99 FATAL
AS400_MSG_BASE
(Based on the AS/400 message

severity)
00-19 HARMLESS
20-29 WARNING
30-39 MINOR
40-59 CRITICAL
60-99 FATAL
AS400_MSG
AS400_Writer_Started
AS400_Writer_Ended_Normal
AS400_Device_No_Longer_Communicating
AS400_Controller_Failed
AS400_Controller_NotReplying
110
Table 11. Events defined in the sample BAROC file (continued)

Event Class
Default Severity
AS400_Network_Session_Unavailable
AS400_Controller_Contacted_Line
AS400_Controller_Off_or_NotRecognized
AS400_Unable_Auto_VaryOn
Troubleshooting the AS/400 adapter

If a problem occurs with the AS/400 adapter, you can perform problem
determination by investigating the job the adapter is running in. Each time you
start an AS/400 adapter, a batch job is started. You can view the adapter job by
issuing the following command:
WRKJOB JOB(name)
Where name is the name of the adapter job that matches the name specified on the
STRTECADP command. This displays the Work with Job dialog.
Note: Several adapter jobs might have existed on your AS/400 with the same
name as the current adapter job. In this case, you are first presented with a
list of jobs to choose from. Select the most recent job from the list.
From the Work with Job dialog, you can select option 10 to display the job log, or
if the job has ended (selecting option 10 tells you so), you can view the job log that
was generated by selecting option 4.
Examine the job log for messages indicating the error that occurred and follow the
corrective action specified. For further assistance, contact Customer Support.
Logging Events in Test Mode

The file to which events are logged in test mode (instead of being sent to an event
server) is created with a record length of 240 bytes if it does not exist. Because an
event written to this file does not wrap to a new line if it is longer than 240 bytes,
it is truncated. To avoid truncation, create the file ahead of time using the CRTPF
or CRTSRCPF commands and specify a large enough record length to
accommodate your events. To utilize this file, ensure it is specified for the
ServerLocation keyword. For additional information, see Keywords on page 10.
Also, be sure that you use the proper format, ABCLIB/TECMSGS
(library/file_name). If the file does not exist, it is created automatically.
TCP/IP considerations
Ensure that the event server and the AS/400 system are configured in your
network Name Server, and that the AS/400 system is configured to resolve to the
Name Server.
If you do not use a Name Server in your network, make sure that an entry exists
on the AS/400 system in the TCP/IP host table for both the event server and the
AS/400 system. Use the following commands to do this:
111
ADDTCPHTE INTNETADR(event server protocol address)

HOSTNAME((event server host name))
TEXT(Tivoli Enterprise Console event server)
ADDTCPHTE INTNETADR(AS/400 protocol address)
HOSTNAME((AS/400 host name)) TEXT(AS/400)
Starting an AS/400 adapter after an IPL

Two methods can be used to automatically start an AS/400 message adapter after
an IPL:
v Adding an autostart job to a job queue
v Modifying the AS/400 startup program to call the STRTECADP command

1. Create a CL program that calls the STRTECADP command, for example:
a. Edit a source file member to add CL statements:
STRSEU QGPL/QCLSRC STRADPCL
b. Enter the following in the source file member. You can have a STRTECADP
command for each adapter you would like to start:
PGM
STRTECADP EVTADP(SYSOPR) +
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR)
ENDPGM
Note: Ensure that TCP/IP service is started on the AS/400 system before
starting a message adapter.
c. Create the program using the previous source member:
CRTCLPGM
PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)
2. Create a job description that calls the previous program and use QSYSNOMAX
as the Job Queue:
CRTJOBD JOBD(QGPL/STARTADP)
JOBQ(QSYSNOMAX)
TEXT(Start TEC adapter after IPL.)
RQSDTA(CALL QGPL/STRADPCL)
3. Add an auto-start job entry in QSYSWRK using the previous job description:
ADDAJE SBSD(QSYSWRK) JOB(TECAMSGQ) JOBD(QGPL/STARTADP)
This program runs at the start of QSYSWRK subsystem and ends quickly after
doing the STRTECADP command.

The system value QSTRUPPGM (startup program) contains the name of the
program to run after IPL. This program can be modified to add the starting of
adapters.
1. Retrieve the code in the startup program:
RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
2. Modify the source:

PGM
DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)
DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)
QSYS/STRSBS SBSD(QCMN)
STRTCP
112
QSYS/STRSBS SBSD(QSERVER)
STRTECADP EVTADP(SYSOPR)+
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR)
DONE:
RETURN
CHGVAR VAR(&CPYR) VALUE(&CPYR)
ENDPGM
3. Create the program and put it in the QSYS library:

CRTCLPGM PGM(QSYS/program-name)
SRCFILE(QGPL/QCLSRC) SRCMBR(program-name)
Note: The startup program runs under user profile QPGMR. The default
setting is that QPGMR does not have authority to change the AS/400
message adapter commands and programs. You must either grant
QPGMR authority to change the commands and programs (see Starting
the adapter on page 105) or have the startup program adopt QSECOFR
authority and be owned by QSECOFR.
Multiple AS/400 message queues

To support another AS/400 message queue, create the following additional files:
v Configuration file: specifies a different message queue for the MsgQueue
keyword and any new filters
v CDS file: defines new classes to match the messages being monitored
v BAROC file: required if new classes are identified in the CDS file
Configuration file
To create the configuration file, perform the following steps:
1. Copy the adapter files using the following commands:
CPYF FROMFILE(QUSRSYS/CFG_MSG)
TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)
TOMBR(*FROMMBR) CRTFILE(*YES)
2. Update the configuration file to show the keywords pointing to the new objects
as follows:
AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCDS.MBR
MsgQueue=QUSRSYS/MYMSGQ
3. Update the CDS and the BAROC files to include any new classes and filters.
4. On the event server, import the BAROC file into the rule base; then, compile
and load the rule base.
5. Start the adapter using the new configuration files as follows:
STRTECADP EVTADP(MYEVTADP)
CFGFILE(/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR)
Using FTP to run AS/400 commands

You can run AS/400 commands from an FTP session. This can be useful for
replying to inquiry messages. The following is an example of how to use FTP to
remotely respond to an AS/400 inquiry message based on the message key that is
part of the event string:
quote "RCMD SNDRPY MSGKEY(X00022A00) MSGQ(QSYSOPR) RPY(The reply) RMV(*NO)
113
Common tasks
Use these commands to perform common tasks related to the AS/400 alert adapter.
v To load the AS/400 alert and message adapters with English as a primary
language:
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC)
v To load the AS/400 message and alert adapters with English as a secondary
language:
RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC)
v To delete all AS/400 adapters from the AS/400 system:

DLTLICPGM LICPGM(1TMETEC)
v To delete only the AS/400 message adapter from the AS/400 system:
DLTLICPGM LICPGM(1TMETEC) OPTION(1)
Delete the message adapter (lib QTMETECA01)
v To start the AS/400 message adapter:

STRTECADP EVTADP(ADPNAME) CFGFILE(QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR)
v To stop the adapter:

ENDTECADP EVTADP(ADPNAME)
114

The following sections contain reference information about the NetWare logfile
adapter.
NetWare logfile adapter reference information

The logfile adapter for NetWare forwards events from a NetWare server to the
event server. The NetWare logfile adapter can be registered with the startup
configuration of the NetWare server so that the logfile adapter is started when the
NetWare server is started.
NetWare server events are gathered from any ASCII log file residing on the
NetWare server, such as the SYS:SYSTEM\SYS$LOG.ERR file.
The NetWare logfile adapter is a NetWare Loadable Module (NLM) process that
reads events generated on a NetWare server, formats them according to
specifications in the format file, and forwards them to the event server for further
processing.
The NetWare logfile adapter can run silently, without its own screen, or it can run
in the debugging mode that displays screen messages for diagnostic purposes.
Adapter files
The NetWare server adapter package consists of the following files:
tecadnw4.nlm
The adapter service executable file
tecadnw4.cnf
The configuration file
tecadnw4.cds
The class definition statement (CDS) file
tecadnw4.brc
The BAROC file
postmsg.nlm
The command line interface program to send an event to the event server
nwgencds.nlm
The command line interface program to generate a CDS file from a format
file
tecadnw4.err
The error file
Before starting the server, ensure that the configuration file defines the preferred
adapter behavior.
Error file
Use the error file to configure debugging and tracing options. This file is described
in detail in Error file on page 26.
115
Prefiltering NetWare events

You can improve the performance of the NetWare logfile adapter by filtering
events, so that only important events are processed. This is called prefiltering and
applies only to events logged to the SYS$LOG.ERR file.
To use the prefiltering mechanism, you specify the prefilter statements in the
configuration file using a format similar to that used for adapter filters. The
prefiltering statements (PreFilter and PreFilterMode) are described in
Configuration file on page 116.
You must stop and restart the adapter for any changes to take effect.
The following attributes define prefilter statements:
Source
Specifies the source or module that logged the event to the NetWare server
log file. You can specify up to 16 sources. Multiple sources must be
separated by commas. Examples include SERVER, DS, TIMESYNC, and
UPS.
EventId
Specifies the message number assigned by NetWare. You can specify up to
16 message numbers. Message numbers must be separated by commas.
EventId is unique for each source.
Severity
Specifies the NetWare-defined severity of the event. You can specify up to
16 severities. Multiple severities must be separated by commas.
Locus Specifies the NetWare-defined locus. You can specify up to 16 loci. Multiple
loci must be separated by commas.
Class
Specifies the NetWare-defined class. You can specify up to 16 classes.

Multiple classes must be separated by commas.
The following are examples of prefiltering statements:

PreFilter:Source=SERVER;EventId=10,20,30;
PreFilter:Source=DS; Severity=11;Class=5;
Configuration file
The configuration file defines the behavior of the NetWare logfile adapter. This file
can contain the common keywords listed in Configuration file on page 9, as well
as the following adapter-specific keywords:
LogSources
Specifies the ASCII log files to poll for messages. The complete path to
each file must be specified, and file names must be separated by commas;
no spaces or other separators can be used. A logfile source need not exist
when the adapter is started; it is polled when it is created.
If a file is truncated while the adapter is active, the adapter automatically
sets its internal pointer to the new end of the file and continues processing
all new messages that are written after the file was truncated. If during the
polling interval the file is overwritten, removed, or recreated with more
lines than the previous poll, only the number of lines greater than the
116
previous line count is read. For example, the file has one line. After the
poll interval elapses, the file is overwritten with two lines. Only the second
line is read on the next polling.
The default file that the adapter polls is the SYS:SYTEM\SYS$LOG.ERR
file. Additional files can be specified with the LogSources keyword.
PollInterval
Specifies the frequency, in seconds, to poll each log file listed in the
LogSources keyword for new messages. The default value is 120 seconds.
PreFilter
An event matches a PreFilter statement when each attribute=value
specification in the PreFilter statement matches a message in the log file. A
PreFilter statement must contain at least the log file specification, and can
contain up to three additional specifications: event ID, event type, and
event source. The order of the attributes in the statement does not matter.
You can specify multiple values for each attribute by separating each with
a comma.
Each PreFilter statement must be on and contained in a single line, no
greater than 512 characters.
The PreFilter keyword is optional. All NetWare server log events are sent
to the adapter if prefilters are not specified.
PreFilterMode
Specifies whether NetWare server log events that match a PreFilter
statement are sent (PreFilterMode=IN) or ignored (PreFilterMode=OUT).
Valid values are IN, in, OUT, or out. The default value is OUT.
The PreFilterMode keyword is optional; if PreFilterMode is not specified,
only events that do not match any PreFilter statements are sent to the
adapter.
If you set PreFilterMode=IN, make sure you have one or more PreFilter
statements defined as well.
Stop and restart the adapter for any changes to take effect.
Format file
The format file contains message format descriptions and their mapping to BAROC
events. The message fields of a NetWare server event are matched against the
format descriptions in this file and when a match succeeds, the corresponding IBM
Tivoli Enterprise Console event is generated by the adapter. The format file
contains predefined mappings for some common NetWare server events and can
be customized to add new messages.
A standard NetWare server event from the SYS$LOG.ERR file is written to an
ASCII message in the following sequence. Consult the appropriate NetWare
manuals for the meanings:
v The date (month-day-year) and time; for example: 7-25-98 1:33:57 am
v Module version-ID; for example: SERVER-4.11-25
v Severity, locus, and class; for example: Severity=10 Locus=1 Class=5
Note: The meanings of severity and class are not the same as those pertaining to
the IBM Tivoli Enterprise Console product.
v The message text
117
The following example shows a formatted IBM Tivoli Enterprise Console event
derived from an error message issued by the NetWare Directory Service (DS):
7-16-98 5:08:46 pm:DS-5.73-12 Severity=10 Locus=2 Class=5
Synthetic Time is being issued on partition NOVELL_TREE.
For details about format files, see Format file on page 24.
Events listing
The tables in the next section show the class names and severities of all events
defined for the NetWare logfile adapter. You can use this information to get a sense
of how NetWare events are mapped to IBM Tivoli Enterprise Console events and
to determine whether you want to make any changes. The events are defined in
the BAROC file, which must be imported into the rule base. See the IBM Tivoli
Enterprise Console Rule Developers Guide for more information about customizing
the BAROC file.

defaults from the parent. The NetWare server event classes follow a simple
hierarchy. The adapter fills in the following attribute default values, as shown in
the following table. The attributes are used in event group filters.
Table 12. Default attribute values for event group filters
Attribute
Default Value
source
NW4
sub_source
NW4
When an event from the SYS$LOG.ERR file is sent, the sub_source attribute is set
to the module that logged the event (for example, DS or SERVER). The default
event classes define the following attributes:
nw_msg_version
This is the version of the module (sub_source) that is logging the message,
for example, 4.10, 1.0, and so on.
nw_msg_id
This is an integer value specifying the message ID. A message ID is unique
within each sub_source.
alert_severity
Specified as an integer from zero (0) to 6, this value indicates the severity
level defined by NetWare. The mapping between the NetWare
alert_severity and Tivoli Enterprise Console severity level is defined in
the following table.
118
Alert Severity
Definition
Severity Level
0 (Informational)
Counters or gauges reached

thresholds.
HARMLESS
1 (Warning)
Configuration errors, and so

on. No damage.
WARNING
2 (Recoverable)
Hot Fix, and so on.

Workaround made.
MINOR
Alert Severity
Definition
Severity Level
3 (Critical)
Disk Mirror failure, and so

on. Fix attempted.
CRITICAL
4 (Fatal)
Resource fatally affected;

shutdown.
FATAL
5 (Operation Aborted)
The operation cannot

complete.
FATAL
6 (Non OS unrecoverable)
The operation cannot

complete.
FATAL
alert_locus
Specified as an integer from zero (0) to 20, this value indicates the location
of the alert, as defined in the following table:
Alert_locus
NetWare Definition
Unknown
Memory
File system
Disks
Lanboards
Comstacks
TTS
Bindery
Station
10
Router
11
Locks
12
Kernel
13
UPS
14
Service Protocol
15
SFTIII
16
Resource Tracking
17
NLM
18
OS Information
19
Cache
20
Domain
alert_class
Specified as an integer from zero (0) to 21, this value indicates the NetWare
alert classes as defined in the following table:
Alert_class
NetWare Definition
Unknown
Out of resource
Temporary situation
Authorization failure
Internal error
119
Alert_class
NetWare Definition
Hardware failure
System failure
Request error
Not found
Bad format
10
Locked
11
Media failure
12
Item exists
13
Station failure
14
Limit exceeded
15
Configuration error
16
Limit almost exceeded
17
Security audit information
18
Disk information
19
General information
20
File compression
21
Protection violation
The following NetWare events are defined in the BAROC file:

Table 13. NetWare events
Event Class
Default Severity
NW4_Base
UNKNOWN
NW4_SysLog_Base
120
UNKNOWN
NW4_ClassUnknown
UNKNOWN
NW4_OutOfResource
UNKNOWN
NW4_TempSituation
UNKNOWN
NW4_AuthorizationFailure
UNKNOWN
NW4_InternalError
UNKNOWN
NW4_HardwareFailure
UNKNOWN
NW4_SystemFailure
UNKNOWN
NW4_RequestError
UNKNOWN
NW4_NotFound
UNKNOWN
NW4_BadFormat
UNKNOWN
NW4_Locked
UNKNOWN
NW4_MediaFailure
UNKNOWN
NW4_ItemExists
UNKNOWN
NW4_StationFailure
UNKNOWN
NW4_LimitExceeded
UNKNOWN
NW4_ConfigurationError
UNKNOWN
NW4_LimitAlmostExceeded
UNKNOWN
Table 13. NetWare events (continued)

Event Class
Default Severity
NW4_SecurityAuditInfo
UNKNOWN
NW4_DiskInformation
UNKNOWN
NW4_GeneralInformation
UNKNOWN
NW4_FileCompression
UNKNOWN
NW4_ProtectionViolation
UNKNOWN
NW4_AppMessage
UNKNOWN
NW4_NLM_Loading
UNKNOWN
NW4_NLM_Unloaded
UNKNOWN
NW4_NLM_NotLoaded
UNKNOWN
NW4_Abend
UNKNOWN
tecadnw4.nlm
The NLM, tecadnw4.nlm, is the NetWare logfile adapter. The commands for
loading and unloading the NLM are described on the following pages.
121
load tecadnw4
Starts the NetWare logfile adapter in non-service mode.
Syntax
load tecadnw4 [c ConfigFile] [d]
Description
Loading tecadnw4.nlm starts the adapter. To stop the adapter, run the following
from the command line:
unload tecadnw4
Authorization: None is required.

Arguments:
c ConfigFile
Specifies the configuration file for the NetWare logfile adapter. If a value is
not specified, the TECADNW4.CNF file in the current directory is used. If
the c argument is used, you can optionally specify a full path name for
the configuration file; otherwise, the default configuration file,
SYS:ETC\TIVOLI\TECAD\ETC\ TECADNW4.CNF, is used.
d
Shows verbose diagnostic information in the NLM screen as events are

gathered and transmitted. Press the Alt+Esc or Ctl+Esc keys to switch to
other NLMs screens or to return to the console.
Note: Without the d option, the adapter displays the initial startup
messages on its screen but closes it upon completion of initialization,
and the adapter name is not displayed in the list of NLMs when the
Ctrl+Esc keys are pressed.
Examples
The following command starts the NetWare logfile adapter in debug mode:
load tecadnw4 -d
The following command starts the NetWare logfile adapter with the myconf.cnf
configuration file:
load tecadnw4 -c sys:etc\tmp\myconf.cnf
122
Troubleshooting the NetWare logfile adapter

Perform the following steps to troubleshoot the NetWare logfile adapter:
1. Stop the NetWare logfile adapter that is currently running by unloading
tecadnw4.nlm:
unload tecadnw4
2. Start the adapter in debug mode:

load tecadnw4 -d -c Config_File
3. Generate some events and see if the adapter receives them.

As events arrive, the adapter prints messages to the screen indicating the class
and the attribute values in the class.
4. As messages are displayed, run the wtdumprl command on the event server
and verify that the messages are displayed or saved in the reception log. If not,
the events were not received by the event server or there is a problem with the
event server reception process.
5. Check the adapter configuration file to verify that TransportList (or
ServerLocation and ServerPort) is properly defined. If the event class is in any
filter entry in the configuration file, and FilterMode=OUT, the event is not sent
to the event server.
6. If the reception log has a PARSING_FAILED error, the BAROC definition of the
class does not match the event that is being received from the adapter. Usually
the error messages pinpoint the problem.
7. If the previous steps do not indicate any problems and you do not see the new
events in the event console, there might be a problem with the event group
filters. Make sure the class filters match the classes defined in the BAROC files.
8. Change all /dev/null entries in the .err file to the file name you want. Stop
and restart the adapter, send an event through, and then look in the trace file to
see what processing was done on the event.
123
124
Chapter 7. OpenView adapter

The IBM Tivoli Enterprise Console adapter for the Hewlett-Packard OpenView (HP
OpenView) product forwards events from OpenView to the event server. The
adapter is registered with the startup configuration of the OpenView operating
system using ovaddobj, so it is started along with all the other applications that
use the operating system. The OpenView ovspmd process manages the adapter
and forwards all preferred events to the event server.
This chapter explains how to configure and start the OpenView adapter.
OpenView driver
The OpenView adapter collects OpenView trap messages that have been sent by
OpenView trap daemon (ovtrapd) and processed by the ovspmd daemon. The
adapter translates the trap messages into the appropriate Tivoli Enterprise Console
class based on the entry that the trap matches in the CDS file.
Reception of OpenView messages

To receive events generated by the OpenView Network Node Manager (NNM) and
any events from all possible OpenView agents, the OpenView adapter registers
itself into the NNM SUF startup file using the ovaddobj command. The ovspmd
daemon reads SUF at startup and manages all the registered processes it finds,
then receives events from the ovtrapd process and forwards the specified events to
the appropriate registered applications (such as the OpenView adapter).
The OpenView adapter must run as a well-behaved daemon process using the
OVsPMD API (application programming interface) functions provided with
OpenView. The OVsPMD API functions are used by object managers (agents) that
must run as background processes in the OpenView program to be managed by
ovspmd, the process management daemon. The adapter interacts with ovspmd
using the SNMP API functions provided with OpenView NNM. This involves the
following steps:
v In NNM 5, calling OVsnmpTrapOpen to establish a logical session with the
OVsnmpAPI to receive SNMP events through the OpenView Event Framework.
v In NNM 6, calling OVsnmpEventOpen to establish a logical session with the
OVsnmpAPI to receive SNMP events through the OpenView Event Framework.
v Calling OVsinit to get a socket for communication with the ovspmd process.
v Calling OVslnitComplete to notify at the end of the initialization, the status of
the initialization process.
v Calling OVsReceive to receive commands from the ovspmd process.
v Calling OVsDone to notify ovspmd that the adapter is being shut down.
Determining the OpenView NNM version

To determine which version of OpenView NNM you are running, use the
following command:
$OV_BIN/ovnnmversion
125
Incoming messages format

Messages received from the ovtrapd process consist of SNMP Trap-PDUs as
defined in RFC 1157 (SNMPv l).
OpenView-specific events are defined as enterprise-specific traps and have the
following content:
enterprise
1.3.6.1.4.1.11.2.17 for OpenView events
agent-addr
SNMP agent or proxy agent address
generic-trap
6
specific-trap
Number in the range 33554432 through 2147483647
time-stamp
0
variable-bindings
The adapter also receives SNMP traps because the ovtrapd process is
monitoring for any traps sent to port 162. The following list shows some of
the specifics for OpenView events:
1.
2.
3.
4.
5.
6.
Descr:
ObjId:
Type:
Descr:
ObjId:
Type:
Descr:
ObjId:
Type:
Descr:
ObjId:
Type:
Descr:
ObjId:
Type:
Descr:
ObjId:
Type:
OpenView Source ID number

1.3.6.1.4.1.11.2.17.2.1.0
INTEGER
OpenView Source Name
1.3.6.1.4.1.11.2.17.2.2.0
OCTET_STRING
OpenView Optional Object Id for event source
1.3.6.1.4.1.11.2.17.2.3.0
OCTET_STRING
Optional data
1.3.6.1.4.1.11.2.17.2.4.0
OCTET_STRING
Optional severity
1.3.6.1.4.l.11.2.17.2.5.0
OCTET_STRING
Optional category
1.3.6 1.4.1.11.2.17.2.6.0
OCTET_STRING
Event correlation with NNM 6

You can configure the adapter to open a session with ovspmd so that ovspmd
forwards only the correlated events you want to the adapter. This reduces the
workload on the adapter in proportion to the number of events discarded by the
NNM circuit settings and therefore not forwarded to the adapter. If you are
running NNM 5 or earlier, the adapter calls OVsnmpTrapOpen to open a session;
with NNM 6 or later, the adapter calls OVsnmpEventOpen. Only
OVsnmpEventOpen provides for event correlation of the events before they are
forwarded to the adapter.
OVsnmpEventOpen contains a filter parameter that defines which events the
application receives from ovspmd. A filter value of NULL or the empty string ()
126
prevents the adapter from receiving any events and makes the session a send-only
session; therefore, this is not a recommended configuration. See the manual page
for OVsnmpEventOpen for more information.
The configuration file keyword HPOVFilter passes the filter value you specify to
OVsnmpEventOpen. HPOVFilter specifies what kind of events are forwarded to
the adapter from ovspmd and contains the value that is used for the filter
parameter when calling the OVsnmpEventOpen API. If you have NNM 6 and
HPOVFilter is not specified or is commented out, the default setting is for the
adapter receives all events. For more information about HPOVFilter, see
Configuration file on page 130.
Determining the OVsnmpEventOpen filter value

The following examples show two ways to see how the value in HPOVFilter is
passed to OVsnmpEventOpen.
v Example 1: NNM input event tracing is turned on and adapter tracing is turned
off.
Look in the file $OV_LOG/ecs/<ecs-instance#>/ecsin.evt# and do a find on
previous tecad_hpov from the bottom of the file. The following example is
similar to what you can see (the filter in this example is {CORR{default}} .*):
Trap-PDU {
enterprise {1 3 6 1 4 1 11 2 17 1},
agent-addr internet : "\x92T$\057",
generic-trap 6,
specific-trap 59179056,
time-stamp 0,
variable-bindings {
{
name {1 3 6 1 4 1 11 2 17 2 1 0},
value simple : number : 14
},
{
name {1 3 6 1 4 1 11 2 17 2 7 0},
value simple : string : \
"{CORR{default}} .*"
},
{
name {1 3 6 1 4 1 11 2 17 2 9 0},
value application-wide : address : internet : "\x92T$\057"
},
{
name {1 3 6 1 4 1 11 2 17 2 8 0},
value simple : string : "tecad_hpov"
},
{
name {1 3 6 1 4 1 11 2 17 2 10 0},
value simple : number : 14128
}
}
}
% ber:Trap-PDU:
v Example 2: Adapter tracing is turned on by specifying output files in the .err file
instead of /dev/null.
You can find the NNM version and the specified filter value in the messages
displayed when you start the adapter. The messages are similar to the following
example:
Initializing T/EC interface ...
T/EC interface initialization complete
Initializing driver ...
Initializing SNMP driver ...
Running as a WellBehavedDaemon
127
Enter in TECAD_OVsInit...
HP NNM version running is: HP OpenView ov library \
NNM Release B.06.10 @(#) PATCH PSOV_XXXXX, YYMMDD Oct 17 1999
Stream filtering set to: {CORR{default}} .*
Testing tools
To test the OpenView adapter, it is necessary to have OpenView installed on the
same system on which the adapter is running. Testing of the adapter behavior can
be achieved only by starting all daemon processes of OpenView and by sending
SNMP trap events to the ovtrapd process. Note that SNMP trap events can be
generated by sending SNMP traps to ovtrapd using the same testing tool as for the
SNMP adapter.
With OpenView, it is also possible to simulate events occurring by using
smnptrap(1), ovevent, or by using specific commands such as:
v OV_Set_status_Color (specific trap number 58916871)
v OV_Message (specific trap number 58916872)
v OV_Popup_Message (specific trap number 58916873)
v OV_Bell_Message (specific trap number 58916874)
v OV_Highlight_Source (specific trap number 58916875)
An example using snmptrap(1) for creating a message and ringing a bell from
node Bad_Node is presented as follows:
snmptrap hostname \
1.3.6.1.4.1.11.2.17.1 ""6
1.3.6.1.4.1.11.2.17.2.1.0
1.3.6.1.4.1.11.2.17.2.2.0
1.3.6.1.4.1.11.2.17.2.4.0
58916874"" \
Integer 14 \
OctetString "Bad_Node" \
OctetString "Bell Message"
Testing event correlation with NNM 6

Stream and circuit tracing can help you see which events are to be forwarded to
the adapter. A stream with an output policy forwards any event unless you enable
at least one circuit on the stream to discard a type of event. A stream with a
discard policy forwards an event only if you enable a circuit on the stream that
outputs that type of event. An output file lists the forwarded events. For example,
when a stream has an output policy, you can determine what events that the
stream sent to the adapter by reading the events listed in the stream output file.
For complete details on streams and circuits, see the HP OpenView NNM
documentation.
The following lists show some of the commands you can use with streams and
circuits:
v To find details about the event correlation engine, use the following command:
ecsmgr -info
v To find details about event arrivals for the circuits and streams, use the
following command: ecsmgr -stats
v To turn on tracing to see the OpenView events received, use the following
command: ecsmgr -log_events input on
This trace file is located in $OV_LOG/ecs/<ecs-instance#>/ecsin.evt#
v To turn on tracing to see the OpenView stream events received, use the
following command:
ecsmgr -log_events stream <stream-name> on
128
The trace files for the stream output events are located in $OV_LOG/ecs/<ecsinstance#>/<stream-name>_sout.evt#
The trace files for the discarded stream events are located in
$OV_LOG/ecs/<ecs-instance#>/<stream-name>_sdis.evt#
The following example turns on stream event tracing for a stream named
default:
ecsmgr -log_events stream default on
v To turn on tracing to see the OpenView circuit events received, use the following
command:
ecsmgr -log_events circuit <circuit-name> on
The trace files for the circuit output events are located in $OV_LOG/ecs/<ecsinstance#>/<circuit-name>_cout.evt#
The trace files for the discarded circuit events are located in
$OV_LOG/ecs/<ecs-instance#>/<circuit-name>_cdis.evt#
The following example turns on circuit event tracing for a stream named
PairWise:
ecsmgr -log_events circuit PairWise on
Event correlation example

The following event passes through circuits named PairWise and ConnectorDown.
When the HPOVFilter value passed to OVsnmpEventOpen is .*, the event is
forwarded to the adapter because the stream default is not being used. If the
HPOVFilter value is {CORR{default}} .*, you can see the event only in the circuit
discard trace file.
snmptrap <boxname> "1.3.6.1.4.1.11.2.17.1" 146.84.36.175 6 40000084 0 \
1.3.6.1.4.1.11.2.17.2.1.0 integer 7 \
1.3.6.1.4.1.11.2.17.2.2.0 octetstringascii "snmp trap for connector down"
Note: You must watch the circuit and stream trace files to see when this event is
discarded. This event sometimes is sent to the adapter instead. Keep the
message text changing slightly so that you can identify a specific event.
Also, send multiple events until the discard trace file for the stream default
shows the event is discarded, which indicates that the event was not sent to
the adapter.
The following event is sent to the adapter when HPOVFilter is set to
{CORR{default}} .*:
/opt/OV/bin/ovevent -s Major -c "Error Events" "" \
.1.3.6.1.4.1.11.2.17.1.0.58916872 \
.1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \
.1.3.6.1.4.1.11.2.17.2.2.0 OctetString "user@host" \
.1.3.6.1.4.1.11.2.17.2.4.0 OctetString "major error message"
Adapter files
The OpenView adapter package consists of the following files in the following
directories:
v $TECADHOME/bin
tecad_hpov.cfg
The installation configuration script.
129
tecad_hpov
The adapter executable file.
tecad_hpov.sh
The adapter shell script to set the environment and call the adapter
executable file.
v $TECADHOME/etc
tecad_hpov.baroc
The adapter BAROC file to define the classes to the rule base.
tecad_ov.baroc
An additional BAROC file that precedes tecad_hpov.baroc in the
rulebase definitions to define the enumerations that tecad_hpov.baroc
uses.
tecad_hpov.cds
The class definition statement (CDS) file. This file defines the adapter
class definitions.
tecad_hpov.conf
The configuration file. This file defines the adapter startup configuration.
tecad_hpov.err
The error file. This file indicates where to write adapter trace messages.
tecad_hpov.lrf
The registration file. This file is generated by the installation
configuration script and placed in the $OV_LRF directory. For UNIX, the
directory is usually /opt/OV/share/lrf. For Microsoft Windows systems,
the directory is usually c:/Openview/LRF/tecad_hpov.lrf.
tecad_hpov.oid
The object identifier file. This file matches object identifiers to variable
names.
ov_default.rls
The default rule file for the OpenView adapter used in the rule base.
Before starting the adapter, check each adapter file to ensure that they define the
preferred adapter behavior.
Configuration file
The configuration file of the OpenView adapter defines the behavior of the adapter,
which runs as a server daemon. The configuration file can have common keywords
described in Configuration file on page 9, as well as the following
adapter-specific keywords:
AdapterSpecificFile=path
Specifies the full path name of the object identifier file. This keyword is
required if the object identifier file is not in the same directory as the
configuration file.
HPOVFilter=filter
Specifies the events the adapter receives from OpenView NNM 6. This
value is ignored with OpenView NNM 5. The adapter can accept up to
4096 bytes for this parameter; you must specify the value in one
continuous line of input with no intervening line returns. Do not enclose
the value in quotation marks; if you enclose the value in quotation marks
and turn on adapter tracing, the trace file displays the following error:
130
Stream filtering set to: "{CORR{default}} .*"

Enter in TECAD_OVsInit...
Unable to initialize SNMP session system error: Invalid event \
filter (Filter parameter (""{CORR{default}}.*"") event \
specification must be "" or start with a .)
Unable to initialize SNMP session system error: Bad file number
Enter in TECAD_OVsInitComplete...
can not initialize specific driver
The adapter also fails to initialize, and ovspmd sends the following
message:
# ovstart tecad_hpov
object manager name:
state:
PID:
last message:
system \
error:
Bad file
exit status:
tecad_hpov
FAILED
12901
Unable to initialize SNMP session
number
-
Turn on adapter tracing when you change the value for HPOVFilter to
make sure that the value was specified correctly or to see the errors
generated by it.
See the manual page for OVsnmpEventOpen for details on HPOVFilter
and the filter parameter.
WellBehavedDaemon
Specifies whether the adapter runs as an OpenView well-behaved daemon.
This value should always be TRUE.

The CDS file defines how events are constructed from the information that is sent
by OpenView. It is described in detail in Class definition statement file on
page 25 and in Appendix C, Class definition statement file reference, on page 197.
Errors in the .cds file definitions cause the adapter to not start successfully, which
often causes the adapter to exit with an exit (1). Therefore, change one definition
at a time and restart the adapter after each change to ensure that the new
definition works. If you make many changes before restarting the adapter, it is
more difficult to troubleshoot any problems; turning on adapter tracing helps you
locate the errors.
OpenView event example

The class definition in the following example is taken from the .cds file:
CLASS_OV_IF_FAULT
SELECT
1:ATTR(=,ENTERPRISE),VALUE(PREFIX, \
"1.3.6.1.4.1.11.2.17.1");
2:$SPECIFIC=40000000;
3:ATTR(=, "openViewSourceName");
4:ATTR(=, openViewData3");
5:ATTR(=, "openViewData4");
MAP
origin=$V3;
sub_origin=$V4;
severity=WARNING;
OV_status=2; # Marginal
131
Keywords
The OpenView adapter supports the use of the following keywords in class
definition statements. These keywords can be useful if you want to customize
events.
$COMMUNITY
Specifies the trap community string.
$ENTERPRISE
Specifies the enterprise object identifier of the object generating the
trap.
$SOURCE_TIME
Specifies the value of sysUpTime of the object generating the trap.
$TYPE
Specifies the generic trap type number (0-6).
$SPECIFIC
Specifies the enterprise-specific trap type number.
$SOURCE_ADDR
Specifies the address of the object sending the trap.
$AGENT_ADDR
Specifies the address of the object generating the trap.
$VARBIND
Specifies a list of all non-fixed attributes.
$VB_NUM_VARS
Specifies the number of elements in $VARBIND.
$ADAPTER_HOST
The name of the host system where the adapter runs.
The following example shows how you can use the keywords:
FETCH
SELECT
1: ATTR(=, $ENTERPRISE);
Built-in variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.

To access the individual elements of $VARBIND, use the VB_# variables, where # is
a number greater than 0. For example, if $VARBIND has three elements, you can
use VB_1, VB_2, and VB_3 as variables to access the data. The following example
performs string functions on the elements of $VARBIND.
ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")
Because $VARBIND is a list of strings, if it contains more than one element,

performing a string function like CONTAINS against $VARBIND causes the
adapter to stop unexpectedly.
Object identifier file

The object identifier file maps object identifiers used by SNMP to names. No
changes are necessary before the adapter is run.
Each line of this file has the following form:
"name"
"object_identifier"
For example
"sysUpTime"
132
"1.3.6.1.2.1.1.3"
"ifIndex"
"whyReload"
"1.3.6.1.2.1.2.2.1.1"
"1.3.6.1.4.1.9.2.1.2"
Note: Object identifiers must occur in increasing order.

You can use the names that are mapped to object identifiers in the CDS file.
Error file
Use the error file to configure debugging and tracing options. This file is described
in detail in Error file on page 26.
LRF file
The .lrf file registers the application when the NNM application starts up. The .lrf
file is created and registered automatically when the adapter is installed. For
details on the syntax of the file, see the OpenView NNM documentation.
If you need to make changes to the tecad_hpov.lrf file, follow these steps:
1. Stop the adapter.
2. Change the .lrf file as needed and save it.
3. Register the change with NNM by using $OV_BIN/ovaddobj
$OV_LRF/tecad_hpov.lrf.
4. Restart the adapter.
If the tecad_hpov.lrf file has errors, the adapter might not start successfully.
Starting and stopping the adapter

If you have configured the host start-up file correctly, the adapter always starts
when the OpenView operating system starts up. You can also start an adapter
manually. When the adapter starts up, it gets new bindings, reads its adapter files,
and restarts the daemon.
Use the following commands to start and stop the adapter. You can access the
OpenView NNM environment variables by sourcing the NNM environment using
the ov.envvars.sh file in the /bin directory in the OpenView NNM installation
directory.
. /opt/OV/bin/ov.evvars.sh
# source the unix/bash environment
/opt/OV/bin/ov.envvars.bat
# source the MS-DOS environment
$OV_BIN/ovstop tecad_hpov
# stop the OpenView adapter
$OV_BIN/ovstart tecad_hpov
# start the OpenView adapter
Events listing
The following table shows the class names and severities of all events defined for
the OpenView adapter. You can use it to get a sense of how OpenView events are
mapped to Tivoli Enterprise Console events and to determine if you want to make
any changes. The events are defined in the BAROC file. See the IBM Tivoli
Enterprise Console Rule Developers Guide for more information about customizing
the BAROC file.
133

Event classes are defined hierarchically, with child classes inheriting default
attribute values from the parent. The OpenView event classes follow a simple
hierarchy.
The adapter fills in the following attribute default values. The attributes are used
in event group filters.
source
HPOV
sub_source
NET
origin
hostIPaddress where the event originated
hostname
hostname where the event originated
adapter_host
Host on which the adapter runs
forwarding_agent
Proxy agent that forwarded the event to the adapter
Additional information is provided where possible by using OpenView category
and status codes. See the ENUMERATION statements at the beginning of the
BAROC file for details.
The following table shows events defined in the BAROC file.
Table 14. OpenView events
Event Class
OV_Event
134
Default Severity
WARNING
OV_Bad_Subnet_Mask
WARNING
OV_CMIS_Event
WARNING
OV_Change_Polling_Period
WARNING
OV_Chg_IF_Segment
WARNING
OV_Connection_Added
WARNING
OV_Connection_Deleted
WARNING
OV_DataCollectThresh
WARNING
OV_DataCollect_Rearm
HARMLESS
OV_Error
WARNING
OV_Fatal_Error
FATAL
OV_Forw_Status_Chg
MINOR
OV_IF_Added
WARNING
OV_IF_Deleted
WARNING
OV_IF_Descr_Chg
MINOR
OV_IF_Fault
WARNING
OV_IF_Down
FATAL
OV_IF_Flags_Chg
WARNING
Table 14. OpenView events (continued)

Event Class
Default Severity
OV_IF_Type_Change
MINOR
OV_Manage_IF
WARNING
OV_Manage_Network
WARNING
OV_Manage_Node
WARNING
OV_Manage_Segment
WARNING
OV_Network_Added
HARMLESS
OV_Network_Deleted
WARNING
OV_Network_Fault
WARNING
OV_Network_Critical
CRITICAL
OV_Network_Marginal
WARNING
OV_Network_Normal
HARMLESS
OV_Network_Flg_Chg
WARNING
OV_No_SNMP_Reply
CRITICAL
OV_Node_Added
WARNING
OV_Node_Deleted
WARNING
OV_Node_Fault
FATAL
OV_Node_Down
WARNING
OV_Node_Marginal
WARNING
OV_Node_Flags_Chg
WARNING
OV_Object_ID_Chg
MINOR
OV_Phys_Addr_Chg
MINOR
OV_Phys_Addr_Mismatch
MINOR
OV_Segment_Added
HARMLESS
OV_Segment_Deleted
WARNING
OV_Segment_Fault
WARNING
OV_Segment_Critical
CRITICAL
OV_Segment_Marginal
WARNING
OV_Segment_Normal
HARMLESS
OV_Segment_Flag_Chg
WARNING
OV_Subnet_Mask_Chg
MINOR
OV_Sys_Contact_Chg
HARMLESS
OV_Sys_Descr_Chg
HARMLESS
OV_Sys_Location_Chg
HARMLESS
OV_Sys_Name_Chg
HARMLESS
OV_Unmanage_IF
WARNING
OV_Unmanage_Network
WARNING
OV_Unmanage_Node
WARNING
OV_Unmanage_Segment
WARNING
HPOV_Event
OV_ARP_Chg_New_Phys_Addr
WARNING
WARNING
135
Table 14. OpenView events (continued)

Event Class
Default Severity
OV_ARP_Phys_Chg_Same_Src
WARNING
OV_AppUngracefulExit
WARNING
OV_Application_Alert
WARNING
OV_Application_Down
WARNING
OV_Application_Up
WARNING
OV_Bad_Forw_To_Host
WARNING
OV_Bad_Phys_Address
WARNING
OV_ConnectionUnknown
WARNING
OV_Connection_Down
FATAL
OV_DataCollect_Check
WARNING
OV_IF_Disconnected
WARNING
OV_IF_IP_Addr_Chg
WARNING
OV_IF_Unknown
WARNING
OV_Map_Change
WARNING
OV_Network_IPAddrChg
WARNING
OV_Network_Name_Chg
WARNING
OV_Network_SubMskChg
WARNING
OV_Network_Unknown
WARNING
OV_Node_SupportsSNMP
WARNING
OV_Node_Unknown
WARNING
OV_Segment_Unknown
WARNING
OV_Trap_PDU_Error
WARNING
OpenView traps
SNMP traps
All SNMP generic traps and enterprise-specific traps supported by the SNMP
adapter are also supported by the OpenView adapter.
OpenView traps
OpenView events are SNMP traps, and their content has been described within
OpenView driver on page 125.
The specific-trap is the number identifying the sub-type of the trap. For OpenView
events, the following list is used:
136
50462720
Warnings
50790400
Node Marginal
50790401
Segment Normal
50790402
Segment Marginal
50790403
Network Normal
50790404
Network Marginal
50790405
Segment Added
50790406
Segment Deleted
50790407
Network Added
50790408
Network Deleted
50790409
Connection Added
50790410
Connection Deleted
50790411
Change Polling Period
50790412
Forced Poll
50790418
Manage Node
50790419
Unmanage Node
50790420
Manage Segment
50790421
Unmanage Segment
All OpenView events are supported by the OpenView adapter.
Troubleshooting the OpenView adapter

Perform the following steps to troubleshoot the OpenView adapter:
1. Make sure that the tecad_hpov.lrf entry is correct and has been registered with
OpenView using the ovaddobj command.
2. If the adapter does not start, look for errors in the .lrf, .oid, and .cds files.
3. If the adapter stops unexpectedly, look for data that is not valid being passed
in a trap or functions. For example, PREFIX is called on a list of strings value
instead of a string value.
5. Look in /tmp/hpov_start.err for possible startup errors from the tecad_hpov.sh
script.
137
138
Chapter 8. OS/2 adapter

The Tivoli Enterprise Console adapter for OS/2 forwards events from an OS/2
system to the event server. The adapter is registered with the startup configuration
of OS/2 so that the adapter is started with all the other applications that are
automatically started when OS/2 is started.
The adapter is an OS/2 process that reads events generated by an OS/2 system
and forwards them to an event server for further processing.
OS/2 events are gathered from the First Failure Support Technology (FFST)
system, and from ASCII log files residing on the OS/2 system. The adapter
translates a certain type of FFST events into IBM Tivoli Enterprise Console events
and sends them to the event server. There are three types of FFST events: DET1,
DET2, and DET4. DET1 events represent error conditions and are the only type
sent to the event server. Entries in the ASCII log files are formatted according to
the format file.
This chapter describes how to configure and start the OS/2 adapter.
Adapter files
The OS/2 adapter package consists of the following files:
readme
The readme file.
tecadcfg.cmd
The startup configuration script.
tecadini.sh
The script to start or stop the adapter.
tecadrm.sh
The TME adapter uninstall script.
tec_uninstal.cmd
The non-TME adapter uninstall batch file.
install.exe
The adapter installation assist executable file.
tecados2.exe
tecados2.conf
tecados2.fmt
The format file.
tecados2.cds
The class definition statement (CDS) file.
tecados2.baroc The BAROC file.

tecados2.err
The error file.
Configuration file
The configuration file defines the behavior of the adapter. This file can contain the
common keywords described in Configuration file on page 9, as well as the
following adapter-specific keywords:
LogSources
Specifies the ASCII log files to monitor for messages. The complete path to
each file must be specified, and file names must be separated by commas;
no spaces or other separators can be used. A log file source need not exist
when the adapter is started; it is monitored when it is created.
139
If a file truncates while the adapter is active, the adapter automatically

resets its internal pointer to the beginning of the file. If during the polling
interval the file is overwritten, removed, or recreated with more lines than
the previous poll, only the number of lines greater than the previous line
count is read. For example, the file has one line. After the poll interval
elapses, the file is overwritten with two lines. Only the second line is read
on the next polling.
UnmatchLog
Specifies a file to log discarded events that cannot be parsed into an IBM
Tivoli Enterprise Console event class by the adapter. The discarded events
can then be analyzed to determine if modifications are needed to the
adapter format file.
Format file
The format file contains message format descriptions and their mapping to BAROC
events. The message fields of an OS/2 event are matched against the format
descriptions in this file and when a match succeeds, the corresponding IBM Tivoli
Enterprise Console event is generated by the adapter. The format file contains
predefined mappings for some common OS/2 events and can be customized to
add any new messages.
The OS/2 adapter extracts the following information from an FFST event:
v Date of the event
v Name of the host that issued the event
v Process name associated with the event
v Severity of the event
v Probe ID
v Module name
v Message text
For details about format files, see Format file on page 24 and Appendix B,
Format file reference, on page 187.

The default action is for the adapter to be started when OS/2 is started. To
manually start the adapter, perform the following steps from the OS/2 desktop:
1. Open the System folder.
2. Open the Startup folder.
3. Double-click the TEC Adapter icon.
Note: The endpoint version of the adapter is started when the adapter
configuration profile is distributed using the Adapter Configuration Facility.
Non-TME adapters are started during adapter installation.
You can also manually start the adapter by entering the following command
sequence from the OS/2 command line:
sh %LCF_BINDER%/../TME/TEC/ADAPTERS/BIN/tecadini.sh start
140

You can manually stop the endpoint adapter by sourcing the endpoint
environment, and then entering the following command sequence from the OS/2
command line:
sh %LCF_BINDIR%/../TME/TEC/ADAPTERS/BIN/tecadini.sh stop
You can manually stop the non-TME adapter from the OS/2 command line with
the following command sequence:
%INSTALL_DIR%\BIN\WOS2KILL.EXE -a
Events listing
the OS/2 adapter. You can use it to get a sense of how OS/2 events are mapped to
Tivoli Enterprise Console events and to determine if you want to make any
changes. The events are defined in the BAROC file.
about customizing a BAROC file.

defaults from the parent. The OS/2 event classes follow a simple hierarchy.
source OS2
sub_source
OS2
The following events are defined in the BAROC file:
Table 15. OS/2 events
Event Class
Default Severity
OS2_Base
4 (WARNING)
OS2_FFST_Base
4 (WARNING)
The severity is set using numeric values in the format file, which you can modify
to set the severity of a specific message. The following table shows the numeric
values and their literal values:
Numeric Value
Literal Value
FATAL
CRITICAL
MINOR
WARNING
UNKNOWN
HARMLESS
Chapter 8. OS/2 adapter
141
Troubleshooting the OS/2 adapter

Perform the following steps to troubleshoot the OS/2 adapter:
1. Stop the OS/2 adapter that is currently running. See Stopping the adapter on
page 141 for details.
2. Add a LogSources=c:\check.txt entry in the configuration file.
3. Start the adapter as described in Starting the adapter on page 140.
4. Add a few lines to c:\check.txt.
5. Run the wtdumprl command on the event server and verify that the messages
are actually showing up in the reception log. If not, the events were not
received by the event server or there is a problem with the event server
reception process. Check the adapter configuration file to verify that
TransportList (or ServerLocation and ServerPort) is properly defined. If the
event class is in any filter entry in the configuration file, the event is not sent to
the server. The administrator who started the adapter must have the required
roles if running the TME version of the adapter. For a TME adapter, running
the odstat command can offer some clues as to what could have failed.
the error messages pinpoint the problem. If the previous steps do not indicate
any problems and you do not see the new events in the Tivoli Enterprise
Console product, there might be a problem with the event group filters. Make
sure the class filters match the classes in the BAROC file.
7. Change all /dev/null entries in the .err file to the file name you want. Stop and
restart the adapter, send an event through, and then look in the trace file to see
what processing was done on the event.
142
Chapter 9. SNMP adapter

The Simple Network Management Protocol (SNMP) adapter for the IBM Tivoli
Enterprise Console product forwards events from SNMP traps to the event server.
This chapter explains how to configure and start the SNMP adapter.
SNMP driver
The SNMP adapter serves the function of collecting SNMP trap messages directly
from the SNMP trap socket of a host and translating SNMP traps into appropriate
IBM Tivoli Enterprise Console class instances.
The SNMP manipulation routines make use of SNMP Research SNMP libraries.
Reception of SNMP messages

The SNMP adapter receives SNMP traps by listening directly on socket udp/162 of
the host it runs on.
Incoming messages format

Messages received on the udp/162 socket consist only of SNMP Trap-PDUs as
defined in RFC 1157 (SNMPv1). Other types of messages are discarded.
Server configuration
Since the SNMP trap adapter listens on UDP socket 162 for incoming SNMP traps,
it must be run as root. Also, UDP socket 162 must not already be in use by another
SNMP manager, such as the trapd daemon for IBM NetView for AIX or the SNMP
trap daemon itself.
Adapter files
The SNMP adapter package consists of the following files:
tecad_snmp.cfg
The installation script.
tecad_snmp
tecad_snmp.baroc
The BAROC file.
tecad_snmp.cds
The class definition statement (CDS) file.
tecad_snmp.conf
tecad_snmp.err
The error file.
tecad_snmp.oid
The object identifier file.
init.tecad_snmp
The adapter startup and shutdown script.
143
Before starting the adapter, check each adapter file to determine if it defines the
behavior you want from the adapter.
Configuration file
The configuration file defines the behavior of the adapter, which runs as a server
daemon. The configuration file can have the common keywords described in
Configuration file on page 9, as well as the following adapter-specific keywords:
AdapterSpecificFile=path
Specifies the full path name of the object identifier file. This
keyword is required if the object identifier file is not in the same
directory as the configuration file.
SNMP_PORT Specifies the port where the adapter listens for SNMP requests.
SNMP_TRAP Specifies the port where the adapter listens for SNMP traps. Only
change this value if the producers of events are configured to send
to the alternate port.

The CDS file defines how events are constructed from information sent by SNMP.
It is described in detail in Class definition statement file on page 25 and in
Appendix C, Class definition statement file reference, on page 197.
SNMP event example

CLASS Port_Segmenting_CBT
SELECT
1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, "1.3.6.1.4.1.52") ;
2:$SPECIFIC=258 ;
3:ATTR(=,"boardIndex") ;
4:ATTR(=,"portIndex") ;
FETCH
1:IPNAME($SOURCE_ADDR) ;
MAP
hostname=$F1 ;
boardIndex=$V3 ;
portIndex=$V4 ;
sub_origin=PRINTF("board %s, port %s", $V3, $V4) ;
status=CLOSED ;
END
Keywords
To customize events, use the following keywords in class definition statements.
Event definition content and syntax are described in the IBM Tivoli Enterprise
Console Rule Developers Guide.
$COMMUNITY
Specifies the trap community string.
$ENTERPRISE
Specifies the enterprise object identifier of the object generating the
trap.
$SOURCE_TIME
Specifies the value of sysUpTime of the object generating the trap.
$TYPE
Specifies the generic trap type number (0-6).
$SPECIFIC
Specifies the enterprise-specific trap type number.
$SOURCE_ADDR
Specifies the address of the object sending the trap.
144
$AGENT_ADDR
Specifies the address of the object generating the trap.
$VARBIND
Specifies a list of all non-fixed attributes.
$VB_NUM_VARS
Specifies the number of elements in $VARBIND.
$ADAPTER_HOST
The name of the host system where the adapter runs.
Built-in variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.
To access the individual elements of $VARBIND, use the VB_# variables, where # is
a number greater than zero (0). For example, if $VARBIND has three elements, you
can use VB_1, VB_2, and VB_3 as variables to access the data. The following
example performs string functions on the elements of $VARBIND:
ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")
Because $VARBIND is a list of strings, if it contains more than one element,

performing a string function like CONTAINS against $VARBIND causes the
adapter to end unexpectedly.
Object identifier file

The object identifier file maps object identifiers used by SNMP to names. No
changes are necessary before the adapter is run.
Each line of this file has the following form:
"name"
"object_identifier"
For example
"sysUpTime"
"1.3.6.1.2.1.1.3"
"ifIndex"
"1.3.6.1.2.1.2.2.1.1"
"whyReload"
"1.3.6.1.4.1.9.2.1.2"
Note: Object identifiers must be shown in increasing order.

You can use the names that are mapped to object identifiers in the CDS file.
Error file
Use the error file to configure debugging and tracing options. The error file is
described in detail in Error file on page 26.
Starting and stopping the adapter

The default action is for the adapter to always be started when the host starts. You
can also cold start or warm start an adapter manually. A cold start causes the
adapter to get new bindings, read its adapter files, and restart the daemons. A
warm start causes the server only to re-read its adapter files.
Unless explicitly defined in the configuration file, the adapter searches for the CDS,
error, and object identifier files in the same directory as the configuration file.
145
Cold start
The endpoint adapter is automatically started as a step in the adapter installation
process when the adapter configuration profile is distributed using the Adapter
Configuration Facility.
Manually start the adapter on the endpoint with the following command:
init.tecad_snmp start
Warm start
You can restart a running adapter. Doing so is useful when you have changed one
of the adapter files and want to have it read in without bringing the adapter or
host down completely.
Use one of the following kill commands to force the adapter to restart:
# kill -HUP process_number
OR
# kill -1 process_number

You can configure each adapter configuration record to perform actions on
subscribing endpoints upon distribution. You can configure actions that are to be
performed both before and after configuration files are written. Actions performed
before file distribution can stop an event adapter and possibly remove the contents
of a configuration directory. Actions performed after file distribution can restart the
adapter.
You can automatically stop the endpoint adapter by distributing an adapter
configuration profile that has the adapter start command removed from the
after-file-distribution actions. See Chapter 3, Adapter Configuration Facility, on
page 45 for additional information.
Manually stop the adapter on the endpoint with the following command:
init.tecad_snmp stop
Events listing
the SNMP adapter. You can use it to get a sense of how SNMP traps are mapped
to Tivoli Enterprise Console events and to determine if you want to make any
changes. The events are defined in the BAROC file.

defaults from the parent. The SNMP event classes follow a simple hierarchy.
The adapter fills in the following attribute defaults. The attributes are used in
event group filters.
source
SNMP
146
sub_source
NET
origin
hostIPaddress where the event originated
hostname
adapter_host
Host on which the adapter runs
forwarding_agent
Proxy agent that forwarded the event to the adapter
Additional information is provided where possible by using interface type and
TCP connection status codes. See the ENUMERATION statements at the beginning
of the BAROC file for details.
The following events are examples of the ones defined in the BAROC file:
Table 16. SNMP events
Event Class
Event Severity
SNMP_Trap
WARNING
Generic_SNMP_Trap
WARNING
Cold_Start
WARNING
Cold_Start_Cisco
WARNING
Warm_Start
WARNING
Link_Down
FATAL
Link_Down_Cisco
WARNING
Link_Up
HARMLESS
Authentication_Failure
WARNING
Authentication_Failure_Cisco
EGP_Neighbor_Loss
EGP_Neighbor_Loss_Cisco
WARNING
CRITICAL
WARNING
Specific_SNMP_Trap
WARNING
CBT_Trap
WARNING
Port_Segmenting_CBT
WARNING
Port_Link_Down_CBT
WARNING
Source_Address_New_CBT
WARNING
Source_Address_Timeout_CBT
WARNING
Board_Removal_CBT
WARNING
Board_Insertion_CBT
WARNING
Active_Port_In_Redundant_Circuit_Failed_
CBT
WARNING
Redundant_Port_Activated_CBT
WARNING
Redundant_Port_Test_Failed_CBT
WARNING
Device_Traffic_Threshold_Exceeded_CBT
WARNING
Device_Error_Threshold_Exceeded_CBT
WARNING
147
Table 16. SNMP events (continued)

Event Class
Event Severity
Device_Collision_Threshold_Exceeded_CBT
WARNING
Board_Traffic_Threshold_Exceeded_CBT
WARNING
Board_Error_Threshold_Exceeded_CBT
WARNING
Board_Collision_Threshold_Exceeded_CBT
WARNING
Port_Traffic_Threshold_Exceeded_CBT
WARNING
Port_Error_Threshold_Exceeded_CBT
WARNING
Port_Collision_Threshold_Exceeded_CBT
WARNING
Port_Type_Changed_CBT
WARNING
Lock_Status_Changed_CBT
WARNING
Port_Security_Violation_CBT
WARNING
Port_Violation_Reset_CBT
WARNING
Env_Temperature_CBT
WARNING
Cisco_Trap
WARNING
Reload_Cisco
WARNING
TCP_Connection_Close_Cisco
HARMLESS
The tecad_snmp.baroc file contains a complete listing of events including NetWare,

Cisco, Cabeltron, and generic traps. Refer to the BAROC file for details.
Rules listing
There are no default rules for the SNMP adapter.
SNMP traps
Generic traps
All SNMP generic traps (Cold_Start, Warm_Start, Link_Down, Link_Up,
Authentication_Failure, Egp_Neighbor_Loss) are mapped to distinct event classes.
These generic SNMP event classes can be specialized to incorporate additional
information provided by some equipment. For instance, when a Cisco router issues
an Authentication_Failure trap, it provides an additional variable in the varbind
list that gives the protocol address of the device sending the badly authenticated
SNMP request. For Link_Down traps, Cisco routers provide additional information
describing which interface is going down and why it is going down. Since the
content of the varbind list is not specified in the SNMP standard, it can vary from
one equipment to the next. This can impact the way event classes and subclasses
are defined.
Enterprise-specific traps
By definition, enterprise-specific traps vary from one equipment vendor to the
next.
Enterprise-specific traps can be handled by supporting Cisco routers
enterprise-specific traps, as follows:
0
148
Reload
tcpConnectionClose
Additionally, enterprise-specific traps can be handled by supporting Cabletron

hubs, as follows:
257
PortSegmenting
258
PortUnsegmenting
259
PortLinkUp
260
PortLinkDown
261
NewSourceAddress
262
SourceAddressTimeout
263
BoardRemoval
264
BoardInsertion
265
ActivePortInRedundantCircuitFailed
266
RedundantPortActivated
267
RedundantPortTesfFailed
268
DeviceTrafficThresholdExceeded
269
DeviceErrorThresholdExceeded
270
DeviceCollisionThresholdExceeded
271
BoardTrafficThresholdExceeded
272
BoardErrorThresholdExceeded
273
BoardCollisionThresholdExceeded
273
BoardCollisionThresholdExceeded
274
PortTrafficThresholdExceeded
275
PortErrorThresholdExceeded
276
PortCollisionThresholdExceeded
277
PortTypeChanged
278
LockSTATUSChanged
279
PortSecurityViolation
280
PortViolationReset
281
EnvTempWarm
282
EnvTempHot
283
EnvVoltageLow
Creating a new SNMP trap event

To create a new SNMP trap event using an SNMP Management Information Base
(MIB) file, change the following files:
v tecad_snmp.baroc
v tecad_snmp.cds
v tecad_snmp.oid
149
This section describes traps from the LANAlert FSA for NetWare 3.x. Traps from
other agents are similar.
BAROC file changes

From this partial MIB file, create a lanalertFSA-NW3-s1 event in the
tecad_snmp.baroc file.
-- LANAlert Forwarding Gateway MIB (partial)
-- NCI 27 June 1995
LANAlert-AFG-Trap DEFINITIONS ::=
BEGIN
IMPORTS
enterprises
FROM RFC1155-SMI
OBJECT-TYPE
FROM RFC-1212
TRAP-TYPE
FROM RFC1215;
-- Network Computing Inc.
nci OBJECT IDENTIFIER ::= { enterprises 768 }
-- LANAlert alert packets
lanalert OBJECT IDENTIFIER ::= { nci 2 }
-- Agent-independent data items
lanalert-data OBJECT IDENTIFIER ::= { lanalert 2 }
-- (NOTE: Some MIB processors have problems with the definition
-- of lanalertFSA-NW2; this can be commented out if no
-- NetWare 2.x File Server Agents are in use.)
lanalert-agent OBJECT IDENTIFIER ::= { lanalert 3 }
lanalertFSA-NW2 OBJECT IDENTIFIER ::= { lanalert-agent 0 }
lanalertFSA-NW3o OBJECT IDENTIFIER ::= { lanalert-agent 1 }
lanalertNA OBJECT IDENTIFIER ::= { lanalert-agent 2 }
lanalertFSA-NW4o OBJECT IDENTIFIER ::= { lanalert-agent 3 }
lanalertAFG OBJECT IDENTIFIER ::= { lanalert-agent 4 }
lanalertFSA-NT OBJECT IDENTIFIER ::= { lanalert-agent 6 }
lanalertSNMPMon OBJECT IDENTIFIER ::= { lanalert-agent 7 }
lanalertMS OBJECT IDENTIFIER ::= { lanalert-agent 10 }
Agent-independent data
LANAlert alerts are assigned one of five priorities, from 1 (highest) through 5
(lowest). The following values are used for the specific-trap field of AFG Trap
protocol data units (PDU) to represent the various priorities on set-alert and
clear-alert messages. Pre-2.4.0 Management Servers do not identify the alert
priority when sending clears, so the value clear-unknown is used as the
specific-trap number in this case. Otherwise, one of the values clear-1 through
clear-5 is used to communicate the priority of a clear-alert message.
LANAlertPriority ::= INTEGER {
set-1(1),
set-2(2),
set-3(3),
set-4(4),
set-5(5),
clear-unknown(6),
clear-1(7),
clear-2(8),
clear-3(9),
clear-4(10),
clear-5(11)
agentName OBJECT-TYPE
SYNTAX DisplayString (SIZE (1..15))
ACCESS not-accessible
150
STATUS mandatory
DESCRIPTION
"The name of an agent reporting to a management server."
::= { lanalert-data 1 }
nodeName OBJECT-TYPE
STATUS mandatory
DESCRIPTION
"The name of a node on the monitored network."
:= { lanalert-data 2 }
eventID OBJECT-TYPE
SYNTAX INTEGER (0..4294967295)
STATUS mandatory
DESCRIPTION
"A number designating a monitored condition."
thresholdID OBJECT-TYPE
SYNTAX INTEGER (1..4294967295)
STATUS optional
DESCRIPTION
"A number designating a threshold set on a
monitored condition."
alertText OBJECT-TYPE
STATUS mandatory
DESCRIPTION
"A string describing an alert condition."
managementServerName OBJECT-TYPE
STATUS mandatory
DESCRIPTION
"The name of a LANAlert management server."
nodeAddressIPX OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (12))
STATUS optional
DESCRIPTION
"The IPX network address of a node."
nodeAddressAppleTalk OBJECT-TYPE
STATUS optional
DESCRIPTION
"The AppleTalk network address of a node."
nodeAddressIP OBJECT-TYPE
STATUS optional
DESCRIPTION
"The IP network address of a node."
alertType OBJECT-TYPE
SYNTAX INTEGER {
thresholdAlert(1),
151
changeAlert(2),
resettableAlert(3)
}
STATUS mandatory
DESCRIPTION
"The type of LANAlert alert packet.
Threshold alerts are generated when a condition crosses a preconfigured threshold,

and are cleared by the agent when the condition crosses the preconfigured reset
value.
Change alerts are generated when a condition changes state. These types of alerts
are forwarded to any consoles and gateways that are currently attached to the
agent management server. Change alerts cannot be cleared, since neither the agent
or the management server maintains information about the alert (other than
logging the alert). Console operators dismiss change alerts locally.
Resettable alerts are generated when a condition changes in a predefined manner.
Resettable alerts can be cleared by a console operator, or by the agent itself for
some alerts.
lanalertFSA-NW3-s1 TRAP-TYPE
ENTERPRISE lanalertFSA-NW3
VARIABLES { managementServerName,
nodeName,
eventID,
alertText
DESCRIPTION
"The LANAlert File Server Agent on NetWare 3.x has
set a priority 1 alert."
:= 1 -- set-1
Class definition statement file changes

The following is the entry for lanalertFSA-NW3-s1 in the tecad_snmp.cds file:
CLASS lanalertFSA-NW3-s1
SELECT
1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, "1.3.6.1.4.1.768.2");
2:$SPECIFIC=1;
3:ATTR(=,"managementServerName");
4:ATTR(=,"nodeName");
5:ATTR(=,"eventID");
6:ATTR(=,"alertText");
MAP
managementServerName=$V3;
nodeName=$V4;
eventID=$V5;
alertText=$V6;
msg=PRINTF("The LANAlert File Server Agent on %s has set
a priority 1 alert.",$V4);
END
The first line is the attribute or trap name. The first attribute (1:
ATTR(=,$ENTERPRISE) VALUE(PREFIX, "1.3.6.1.4.1.768.2") ;) specifies that this is
an enterprise trap. The OID prefix is derived from the trap definition; trap
lanalertFSA-NW3-s1 is of type ENTERPRISE lanalertFSA-NW3.
The enterprise OID prefix is 1.3.6.1.4.1 as specified in RFC1155-SMI, plus the
appropriate object identifiers. From the following lines in the MIB file, the prefix
can be expanded to 1.3.6.1.4.1.768.2:
nci
152
OBJECT IDENTIFIER ::= { enterprises 768 }
lanalert
OBJECT IDENTIFIER ::= { nci 2 }
The specific trap number is just a sequential numbering of trap definitions as

defined in the MIB definition for lanalertFSA-NW3-s1 TRAP-TYPE. In this case
lanalertFSA-NW3-s1 is the first and is denoted as follows:
2:$SPECIFIC=1;
The other attributes are derived from the trap expected object types. The definition
for lanalertFSA-NW3-s1 states that it contains the following information:
VARIABLES { managementServerName,
nodeName,
eventID,
alertText }
These are denoted in the tecad_snmp.cds file as follows:

3:ATTR(=,"managementServerName");
4:ATTR(=,"nodeName");
5:ATTR(=,"eventID");
6:ATTR(=,"alertText");
You would add the following entry to the tecad_snmp.cds file to map the trap
variables to adapter variables:
MAP
managementServerName=$V3;
nodeName=$V4;
eventID=$V5;
alertText=$V6;
msg=PRINTF("The LANAlert File Server Agent on %s has set
a priority 1 alert.",$V4);
These variable values are then mapped to event attributes defined in the
tecad_snmp.baroc file. For example, the BAROC class definition for the
lanalertFSA-NW3-s1 event is as follows:
TEC_CLASS :
LANAlert_Trap ISA Specific_SNMP_Trap
DEFINES {
source:default="LANA";
sub_source:default="NET";
severity:default="WARNING";
trapTime:INT32;
specificTrap:INT32;
managementServerName:STRING;
nodeName:STRING;
eventID:INT32;
alertText:STRING;
};
END
TEC_CLASS :
lanalertFSA-NW3-s1 ISA LANAlert_Trap;
END
Object identifier file changes

The entry in the tecad_snmp.oid file for this trap is composed of the enterprise
prefix plus the appropriate object identifiers (OID) plus the variable attribute OID.
For example,
#nci
lanalert
lanalert-data
nodeName
1.3.6.1.4.1.768
1.3.6.1.4.1.768.2
1.3.6.1.4.1.768.2.2
1.3.6.1.4.1.768.2.2.2
153
eventID
alertText
managementServerName
1.3.6.1.4.1.768.2.2.3
1.3.6.1.4.1.768.2.2.5
1.3.6.1.4.1.768.2.2.6
Troubleshooting the SNMP adapter

1. Make sure that no other processes such as SNMP or ovtrapd are already
listening on port 162. Use netstat a | grep 162 to see if this port is in use. The
first process to start up gets the port and the other processes that follow never
receive events from that port.
2. Use the following command to cold start the SNMP adapter:
tecad_snmp [d] [c configuration_file]
The following are the arguments for the tecad_snmp command:
d
Starts the adapter in debug mode. This argument prevents the daemon
from forking itself.
c configuration_file
Specifies the location of the configuration file.
If c is not specified, then the adapter searches
$TECADHOME/etc/tecad_snmp.conf if the environment variable
TECADHOME is set, or /etc/Tivoli/tecad/etc/tecad_snmp.conf for the
configuration file.
3. Use snmptrap or the Tivoli Distributed Monitoring wsnmptrap commands to
send events to the adapter for testing.
154
Chapter 10. UNIX logfile adapter

The TME UNIX logfile adapter receives raw log file information from the UNIX
syslogd daemon, formats it, and sends it to the Tivoli Enterprise Console gateway.
The Tivoli Enterprise Console gateway then sends the information to the event
server. The non-TME UNIX logfile adapter sends information directly to the event
server.
The UNIX logfile adapter adds entries into the /etc/syslog.conf file to enable the
adapter to monitor events that the syslogd daemon writes to various log files. The
adapter can also be configured to monitor any ASCII log file for information that is
important to the operation of your enterprise.
This chapter explains how to configure and start the UNIX logfile adapter.
Event server configuration

At the event server, the BAROC file and rule set file must be imported into a rule
base and then compiled. This rule base must then be loaded and made the active
rule base. See the IBM Tivoli Enterprise Console Rule Developers Guide for additional
information about the steps to do these tasks.
Note: The Default rule base, as shipped, is already configured using the BAROC
file and default rule file for the UNIX logfile adapter.

Use the init.tecad_logfile start [adapterID] command in the background to
manually start the adapter. Always use this command to ensure that the syslogd
daemon is properly configured to send messages to the adapter.
In most situations, the start-up process takes 40 seconds, at which time the syslogd
daemon is refreshed. If you want to give the adapter additional seconds to
complete its startup, specify the tstartup_time option for the init.tecad_logfile start
command. There cannot be a space between the option letter and the option value.
This option is useful if the adapter does not receive events because the syslogd
daemon is not properly refreshed.
Note: The endpoint adapter is automatically started as a step in the adapter
installation process when the adapter configuration profile is distributed
using the Adapter Configuration Facility.

before file distribution can stop an event adapter and possibly remove the contents
adapter.
155

To manually stop the adapter, use the init.tecad_logfile stop [adapterID] command.
This command ensures that the syslogd daemon is correctly configured to stop
sending messages to the adapter. If the adapter is stopped with any other method,
the syslogd daemon might exit because the adapter is no longer listening on the
named pipe that the syslogd daemon is writing to.
Reloading the adapter configuration

To reload the adapter configuration and format files, issue the following command:
kill -HUP pid
where pid is the process ID of the adapter. Use this command if you want to
change the adapter configuration without having to stop and restart the adapter.
For example, you might want to temporarily add (and later remove) filters or
entries in the format file when the system goes into maintenance mode. After you
have made the necessary changes to the configuration and format files, issue this
command to dynamically update the adapter configuration.
Running multiple UNIX logfile adapters

You can run multiple instances of the UNIX logfile adapter on a single system. It is
recommended that additional adapters be run as non-TME adapters. To monitor
different log files, each instance of the adapter must have its own configuration,
format, class definition statement (CDS), and error files. If the adapters use event
buffering (set using the BufferEvents keyword, which has a default value of YES),
the adapters must also have their own cache files.
If you want to stop an adapter when multiple log files are running, you must
specify the name of the adapter to stop. If you do not specify the adapter to stop,
the default adapter without a name is stopped.
The syntax for the init.tecad_logfile command is as follows:
init.tecad_logfile [s] {start | stop} [adapterID] &
If the s flag (skip syslog) is specified, the adapter does not monitor the syslogd
daemon.
If the s flag is not specified, use & so that the command runs in the background
while returning a command prompt to your session. Otherwise, because an
adapter started without the s option forks a child process to run the adapter, the
process does not return to the command line until the child process ends.
Note: If you start the adapter with the s flag, you can also use the s flag when
you stop the adapter to avoid reconfiguring the syslogd daemon. You can
also stop the adapter without the s flag and it still works. However, do not
stop an adapter with the s flag if you did not start it with the s flag.
If the s flag is not specified, the UNIX logfile adapter startup script uses a UNIX
pipe to monitor the syslogd daemon and the syslogd daemon is configured to
write to the pipe, and the UNIX logfile adapter reads from that pipe. When the
156
adapter ends, the startup script reconfigures the syslogd daemon to stop writing to
the pipe before stopping the UNIX logfile adapter.
The following command starts a UNIX logfile adapter called syslog that monitors
all syslog messages:
init.tecad_logfile start syslog &
Adapter files
The UNIX logfile adapter package consists of the following files:
tecad_logfile.cfg
The installation script.
init.tecad_logfile
The adapter startup and shutdown script. Never stop the adapter
using signals. Use this script to ensure that the syslogd daemon
remains running and functional.
tecad_logfile
The executable file of the adapter that receives the log information
and transforms it into events.
logfile_gencds
The executable file that converts a format file to a CDS file.
tecad_logfile.baroc
The BAROC file.
tecad_logfile.cds
The CDS file. This file is created by running logfile_gencds on the
format file.
tecad_logfile.conf
tecad_logfile.err
The error file.
tecad_logfile.fmt
The format file.
log_default.rls
The default rule file.
Before you start the event server and UNIX logfile adapter, check each adapter file
to determine if it defines the behavior you want from the adapter.
Configuration file
The configuration file defines the behavior of the adapter. The configuration file
can have the common keywords described in Configuration file on page 9, as
well as the following custom keywords:
LogSources
Specifies the log files to poll. The complete path to each file must be
specified, and file names must be separated by commas. Within each file
name, you can also use an asterisk (*) to represent any sequence of
characters, or a question mark (?) to represent any single character. For
example, mylog* would result in polling all log files whose names begin
with mylog, while mylog??? would result in polling all log files whose
157
names consist of mylog followed by exactly three characters. These

wildcard characters are supported only within the file name; the path must
be explicitly specified.
A log source need not exist when the adapter is started; it is polled when it
is created.
Each line in the file must end with a newline character. If a file truncates
while the adapter is active, the adapter automatically resets its internal
pointer to the beginning of the file. If during the polling interval the file is
overwritten, removed, or recreated with more lines than the previous poll,
only the number of lines greater than the previous line count is read. For
example, the file has one line. After the poll interval elapses, the file is
overwritten with two lines. Only the second line is read on the next
polling.
Note: The maximum number of lines that can be concatenated to a log file
is 16 384.
NewLogBasedOn
Specifies whether a log file should be treated as new when the time stamp
of the file changes but the size remains the same. When a file is treated as
new, the adapter re-sends every event contained in the file. The possible
value is:
mtime | MTIME
The file is treated as new if the modification time stamp changes.
This keyword is optional. If NewLogBasedOn is not specified, a preexisting
log file is treated as new only if its size decreases.
PollInterval
Specifies the frequency, in seconds, to poll each file listed in the
LogSources field for new messages. The default value is 120 seconds.
ProcessPriorityClass
Specifies the process priority for the adapter. You can adjust this value to
improve system performance if the adapter processes large volumes of
events and is using too many processor resources. The possible values are:
A
Very low priority (20)
B
Low priority (10)
C
Typical priority (0)
D
Above typical priority (-5)
E
High priority (-10)
F
Very high priority (-20)
The default value is C (typical priority).
UnmatchLog
Specifies a file to log discarded events that cannot be parsed into a Tivoli
Enterprise Console event class by the adapter. The discarded events can
then be analyzed to determine if modifications are needed to the adapter
format file.
Format file
The format file is described in detail in Format file on page 24.
158

The CDS file defines how an adapter constructs events. This file is derived from
the format file using the logfile_gencds program. In general, you should never
have to edit this file to add new mappings. The CDS file is described in detail in
Class definition statement file on page 25 and in Appendix C, Class definition
statement file reference, on page 197.
Error file
The error file is described in detail in Error file on page 26.
Events listing
the UNIX logfile adapter. You can use the table to get a sense of how log file
events are mapped to Tivoli Enterprise Console events and to determine if you
want to make any changes. The events are defined in the BAROC file. See the IBM
Tivoli Enterprise Console Rule Developers Guide for more information about
customizing BAROC files.

defaults from the parent.
The adapter fills in the following attribute defaults. The attributes are used in
event group filters.
v source: LOGFILE
v origin: hostIPaddress
v hostname: hostname
The following events are defined for the UNIX logfile adapter in the
tecad_logfile.baroc file.
Table 17. UNIX logfile adapter events
Event Class
Default Severity
Logfile_Base
WARNING
Logfile_Automounter
HARMLESS
Logfile_Amd
WARNING
Amd_Mounted
WARNING
Amd_Unmounted
WARNING
Logfile_Automount
WARNING
Logfile_Bootpd
WARNING
Logfile_Comsat
WARNING
Logfile_Cron
HARMLESS
Logfile_Date
HARMLESS
Logfile_Date_Set
Logfile_Ebbackupd
Ebbackupd_Waiting
Logfile_Ebcatcomp
WARNING
WARNING
WARNING
WARNING
159
Table 17. UNIX logfile adapter events (continued)

Event Class
Default Severity
Logfile_Fsck
WARNING
Logfile_Ftp
WARNING
Logfile_Ftpd
WARNING
Logfile_Gated
WARNING
Logfile_Getty
WARNING
Logfile_Halt
WARNING
Logfile_Idi
HARMLESS
Logfile_Inetd
WARNING
Logfile_Init
WARNING
Logfile_Innd
WARNING
Logfile_Kernel
WARNING
File_Write_Error
File_System_Full
MINOR
NFS_Write_Error
WARNING
Sendsig_Err
CRITICAL
Kernel_Panic
FATAL
NFS_No_Response
WARNING
NFS_OK
HARMLESS
Silo_Overflow
MINOR
Logfile_Login
WARNING
Root_Login
Root_Login_Failure
Root_Login_Failure_From
Root_Login_Success
Root_Login_Success_From
MINOR
WARNING
WARNING
WARNING
WARNING
Repeated_Login_Failure
WARNING
Repeated_Login_Failure_From
WARNING
Logfile_Lpd
160
MINOR
WARNING
Logfile_Lpd_Get_Hostname
WARNING
Logfile_Lpd_Lost_Connection
WARNING
Logfile_Lpd_No_File
WARNING
Logfile_Mosaic
WARNING
Logfile_Mountd
WARNING
Logfile_Named
WARNING
Logfile_Nfsd
WARNING
Logfile_Nnrpd
WARNING
Logfile_Oserv
WARNING

Event Class
Default Severity
Oserv_Panic
CRITICAL
Oserv_Graceful_Exit
HARMLESS
Oserv_System_Error
MINOR
Oserv_Fork_Failed
CRITICAL
Oserv_Exec_Failed
MINOR
Oserv_Comm_Error
Oserv_IPC_Dispatch_Failed
WARNING
MINOR
Oserv_Security
WARNING
Oserv_Tmgr
WARNING
Oserv_Event_Method_Failed
MINOR
Logfile_Passwd
WARNING
Logfile_Pcnfsd
WARNING
Logfile_Printer
WARNING
Printer_Connection_Abort
WARNING
Printer_Error_Cleared
HARMLESS
Printer_Door_Open
WARNING
Printer_Offline
WARNING
Printer_Output_Full
WARNING
Printer_Page_Punt
WARNING
Printer_Paper_Jam
WARNING
Printer_Paper_Out
WARNING
Printer_Powerup
WARNING
Printer_Toner_Low
WARNING
Logfile_Rarpd
WARNING
Logfile_Reboot
HARMLESS
Logfile_Rexecd
WARNING
Logfile_Rftp
WARNING
Logfile_Rlogind
WARNING
Logfile_Routed
WARNING
Logfile_Rquotad
WARNING
Logfile_Rshd
WARNING
Logfile_Rstatd
WARNING
Logfile_Rtelnet
WARNING
Logfile_Rwhod
WARNING
Logfile_Sendmail
HARMLESS
Sendmail_Loopback
WARNING
Sendmail_No_Space
MINOR
Logfile_Snmpd
WARNING
Logfile_Sockd
WARNING
161

Event Class
Default Severity
Sockd_Connected
HARMLESS
Sockd_Terminated
WARNING
Sockd_Transfer
WARNING
Logfile_Strerr
HARMLESS
Logfile_Su
WARNING
Su_Failure
WARNING
Su_Success
WARNING
Logfile_Syslogd
WARNING
Syslogd_Nospace
Logfile_Talkd
WARNING
Logfile_Telnetd
WARNING
Logfile_Tftpd
WARNING
Logfile_Xntpd
WARNING
Xntpd_Clock_Reset
WARNING
Xntpd_Ntpdate
WARNING
Logfile_YP
HARMLESS
Logfile_Ypbind
WARNING
Logfile_Ypchfn
WARNING
Logfile_Ypchsh
WARNING
Logfile_Yppasswd
WARNING
NIS_No_Response
WARNING
NIS_OK
HARMLESS
No_Permission
WARNING
No_Resources
CRITICAL
No_Disk_Space
File_System_Full
WARNING
MINOR
LOCAL_File_System_Full
WARNING
NFS_File_System_Full
WARNING
SWAP_File_System_Full
WARNING
Sendmail_No_Space
MINOR
Syslogd_Nospace
MINOR
No_Memory
WARNING
No_Proc_Attributes
WARNING
Server_No_Response
WARNING
NFS_No_Response
WARNING
NIS_No_Response
WARNING
Server_OK
162
MINOR
HARMLESS
NFS_OK
HARMLESS
NIS_OK
HARMLESS
Default rules
The UNIX logfile adapter has a set of default rules that can be installed to enhance
event server operation. Rules can enable the server to perform functions such as
deleting events and sending e-mail to alert administrators of an unresolved
problem. The rules are contained in the log_default.rls file and perform the
following functions:
v Duplicate events of the following classes are filtered out and the first event
repeat count is increased:
Printer_Paper_Out
Printer_Toner_Low
Printer_Offline
Printer_Output_Full
Printer_Paper_Jam
Printer_Door_Open
v Printer assistance can be called for when a printer condition persists for a period
of time greater than 90 seconds. If any of the following conditions persist for
that period of time, an e-mail message is sent to the e-mail alias tec_print to
request assistance with the printer condition. (The tec_print alias must be added
to the e-mail alias file before the messages can be delivered.)
Printer_Paper_Out
Printer_Toner_Low
Printer_Offline
Printer_Output_Full
Printer_Paper_Jam
Printer_Door_Open
v When a printer condition is cleared, the event server automatically closes the
event that indicated a problem. If e-mail was sent out notifying the
administrators of the printer problem, the server sends e-mail indicating the
condition has cleared up.
v The Su_Success and Su_Failure events indicate that a user attempted to use the
su command. If a Su_Success event is received within 90 seconds of the
Su_Failure event, the server assumes that the Su_Failure was a mistake and
downgrades the event to HARMLESS and closes the Su_Failure event. The rules
ensure that these two events are related by checking that they occurred on the
same host, the user attempting this was the same, and the user that they were
trying to change to was the same.
v Some of the log file events are relevant for a short amount of time. The
administrators also do not want to be burdened with closing these events
manually. A rule is provided that closes the following event classes after one
hour. You can edit this rule to change the time or the list of classes. Refer to the
IBM Tivoli Enterprise Console Rule Builders Guide for information about editing
rules.
Logfile_Amd
Logfile_Cron
Logfile_Oserv
Logfile_Date_Set
The event server also comes with some additional rules that you can install. The
$BINDIR/TME/TEC/contrib/rules/security directory contains the
security_default.rls file, which provides the following behavior to the event server:
163
v When a host reports a repeated login failure attempt at least two times in a row,
e-mail is sent to the e-mail alias tec_security notifying the administrators of the
attempted security breach. (The tec_security alias must be added to the e-mail
alias file before the messages can be delivered.)
v A rule is included that closes the following event classes after one hour:
Repeated_Login_Failure
Repeated_Login_Failure_From
Root_Login_Success_From
Troubleshooting the UNIX logfile adapter

Perform the following steps to troubleshoot the UNIX logfile adapter:
1. Stop any UNIX logfile adapters that are currently running:
init.tecad_logfile stop
2. Start the adapter in debug mode.

init.tecad_logfile -d start
3. Generate some messages to determine if the adapter receives them. You can
send e-mail, perform an su, or perform any action that results in a write to
syslog. Alternatively, you can use the logger program to generate messages:
logger -t oserv -i execve failed: path: errno 13
This generates an Oserv_Exec_Failed event. The message written by logger

should match one of the format specifications in the tecad_logfile.fmt file.
4. When events arrive, the adapter prints messages to the screen indicating the
class and the attribute values in the class.
matched CREATED_PROFILE_MANAGER name is Profile1
If you do not see any messages, the adapter is not receiving events from the
log file.
Verify that the syslogd daemon is running and is writing any new messages to
the system log files in /var/adm or its equivalent, or to the system console,
depending on how syslog.conf has been configured to write out messages. For
testing purposes, you can temporarily add the following line to syslog.conf:
*.info <Tab> <filename>
This enables all messages to be written to a file so you can see what messages
have arrived. This file grows large quickly, so make this a temporary change
only. You need to refresh the syslogd daemon each time you change syslog.conf
to put these changes into effect.
5. If you see the messages, the adapter is receiving events and processing them.
Run the wtdumprl command on the event server and verify that the messages
received by event server or there is a problem with the event server reception
process. Check the adapter configuration file to verify that ServerLocation and
ServerPort are properly defined. Also check the parameters used in the start
command to ensure that the ID provided is the same one used to configure the
adapter. If the event class is in any filter entry in the configuration file, it is not
sent to event server. The administrator who started the adapter must have the
required roles if you are running the TME version of the adapter. For a TME
adapter, running the odstat command can offer some clues as to what failed.
164
7. If the previous steps do not indicate any problem and you do not see the new
events in the Tivoli Enterprise Console product, there might be a problem with
the event group filters. Make sure the class filters match the classes in the
BAROC files.
165
166
Chapter 11. Windows event log adapter

The adapter for the Microsoft Windows event log forwards events from a Windows
system to the event server. It is registered with the startup configuration of a
Windows 2000 system so that the adapter is started with all the other applications
that are automatically started when the Windows system is started.
The adapter is a WIN32 process that reads events generated on a Windows 2000
system, formats them according to the specification in the format file, and forwards
them using Winsock TCP/IP to an event server for further processing.
Events are gathered from up to six Windows event logs (System, Application,
Security, DNS server, File Replication service, and Directory service) maintained by
the Windows Event Manager, and from any other ASCII log files residing on the
Windows 2000 system. The Windows event log adapter tracks the messages read
from the Windows event logs using up to six registry variables that contain the
most recent highest message read for the System, Application, Security, DNS
server, File Replication service, and Directory service logs, whether the Windows
event log adapter is running continuously or is restarted. You can alter this
behavior using the appropriate switches when the Windows event log adapter is
started.
Two versions of the Windows event log adapter are provided. One is built as a
Windows service, while the other is a WIN32 process that is a command line
interface version. Usually, you should run the Windows service version, because it
runs even when no user is logged in. The command line interface can be used to
help you view console messages for diagnostic purposes. Other than the
service-related differences, both versions perform identically.
This chapter describes how to configure and start the Windows event log adapter.
Adapter files
The Windows event log adapter package consists of the following files:
README
The readme file.
tecinstl_win.cmd
The adapter installation batch file.
instlsrv.exe
The adapter installation assist executable file.
tecadwins.exe
The adapter service executable file.
tecad_win.exe
The adapter non-service executable file.
tecad_win.conf
tecad_win.fmt
The format file.
tecad_win.cds The class definition statement (CDS) file.
167
tecad_win.baroc
The BAROC file.
postemsg.exe
The command line interface program to send an event to an event

server.
tecad_win.err
The error file.
Before starting the event server, check the configuration file to determine if it
defines the preferred adapter behavior.
Configuration file
The configuration file defines the behavior of the adapter. This file can contain the
common keywords described in Configuration file on page 9, as well as the
following adapter-specific keywords:
BufferMaxSize=n
Specifies the number of events buffered in the adapter. If the
adapter is operating under extreme loads, use this keyword to
control the amount of memory used by the adapter. If this is not
specified, the default value is 16384.
HostnameIsAdapterHost
Specifies whether the host name attribute for Windows event log
events is set to the host on which the adapter is running (the
default) or the host where the event originated.
If set to NO or no, the host name attribute is set to the
COMPUTER field from the Windows event log.
Note: This applies only to events from the Windows event log, not
those generated from log files specified in LogSources. Those
events always have the host name attribute set to the host
on which the adapter is running.
The COMPUTER name returned from the Windows event log
might not be the same as the ManagedNode name (which is
case-sensitive) of the host where the event originated. You must
take this into consideration if you run tasks or programs from the
Tivoli Enterprise Console product or the rule base, because they
might use the host name attribute to determine where they run.
LanguageID
Sets the language event log messages to be formatted in English or

the native language. Valid values are as follows:
ENGLISH
Messages are formatted in English.
DEFAULT
The adapter attempts to format event log messages in the
default language based on the local value set in Windows.
If the adapter cannot use the default language, it uses
English. The value DEFAULT can be used only in
languages that have 8-bit wide characters.
The format file is in English. The Windows event logs are in your
native language. If your native language is not English, you must
rewrite the format file in your native language.
LogSources
168
Specifies the ASCII log files to poll for messages. The complete
path to each file must be specified, and file names must be
separated by commas. Within each file name, you can also use an
asterisk (*) to represent any sequence of characters, or a question
mark (?) to represent any single character. For example, mylog*
results in polling all log files whose names begin with mylog, while
mylog??? results in polling all log files whose names consist of
mylog followed by exactly three characters. These wildcard
characters are supported only within the file name; the path must
be explicitly specified.
A log file source need not exist when the adapter is started; it is
polled when it is created.
Each line in the file must end with a newline character. If a file
truncates while the adapter is active, the adapter automatically
resets its internal pointer to the beginning of the file. If during the
polling interval the file is overwritten, removed, or recreated with
more lines than the previous poll, only the number of lines greater
than the previous line count is read. For example, the file has one
line. After the poll interval elapses, the file is overwritten with two
lines. Only the second line is read on the next polling.
NewLogBasedOn
Specifies whether a log file should be treated as new when the
time stamp of the file changes but the size remains the same. When
a file is treated as new, the adapter re-sends every event contained
in the file. The possible values are:
ctime | CTIME
The file is treated as new if the creation time stamp
changes.
mtime | MTIME
The file is treated as new if the modification time stamp
changes.
cmtime | CMTIME
The file is treated as new if the creation or modification
time stamp changes.
This keyword is optional. If NewLogBasedOn is not specified, a
preexisting log file is treated as new only if its size decreases.
NumEventsToCatchUp
Specifies which event in the Windows event logs that the adapter
starts with. This option provides some flexibility if the source being
monitored is new or the adapter has been stopped for an extended
period of time. Valid values are as follows:
0
Start with the next event in the logs. This is the default
value.
Start with the oldest event in the logs.
n represents any number other than zero (0) or 1. Start

with the nth event from the most current event in the logs;
that is, start n events back from the most current event in
the logs. If n is greater than the number of events that are
available, all the events that are available are processed.
169
PollInterval
Specifies the frequency, in seconds, to poll each log file listed in the
LogSources keyword for new messages. The default value is 120
seconds.
If you have upgraded a Windows event log adapter from a
previous release and you have a value set for PollingInterval in the
Windows registry, you must specify the PollInterval keyword in
the adapter configuration file with the same value used in the
Windows registry.
PreFilter
Specifies how events in a Windows event log are filtered before

adapter processing. PreFilter statements are used by PreFilterMode
when determining which events are sent from an event log to the
adapter. An event matches a PreFilter statement when each
attribute=value specification in the PreFilter statement matches an
event in the event log. A PreFilter statement must contain at least
the log specification and can contain up to three additional
specifications, which are all optional: event ID, event type, and
event source. The order of the attributes in the statement does not
matter.
The basic format of the PreFilter statement is as follows:
PreFilter:Log=log_name;EventId=value; EventType=value;Source=value;
You can specify multiple values for each attribute by separating

each with a comma.
Each PreFilter statement must be on a single line.
The PreFilter keyword is optional. All Windows log events are sent
to the adapter if prefilters are not specified and PreFilterMode=OUT.
For additional information about prefiltering Windows log events,
see Prefiltering Windows log events on page 172.
PreFilterMode
Specifies whether Windows log events that match a PreFilter
statement are sent (PreFilterMode=IN) or ignored
(PreFilterMode=OUT). Valid values are IN, in, OUT, or out. The
default value is OUT.
The PreFilterMode keyword is optional; if PreFilterMode is not
specified, only events that do not match any PreFilter statements
are sent to the adapter.
Note: If you set PreFilterMode=IN, make sure you have one or
more PreFilter statements defined as well.
For additional information about prefiltering Windows event log
events, see Prefiltering Windows log events on page 172.
ProcessDisablePriorityBoost
Specifies whether the priority boost should be disabled for the
adapter process. You can use this option to improve system
performance if the adapter processes large volumes of events and
is using too many processor resources. If this option is set to
TRUE, the priority boost is disabled. The default value is FALSE.
170
ProcessPriorityClass
Specifies the process priority for the adapter. You can adjust this
value to to improve system performance if the adapter processes
large volumes of events and is using too many processor resources.
The possible values are:
A
IdlePriority
B
BelowNormalPriority
C
NormalPriority
D
AboveNormalPriority
E
HighPriority
F
RealTimePriority
The default value is C (NormalPriority).
SpaceReplacement
When SpaceReplacement is FALSE, any spaces in the security ID
and subsource fields of the event log messages are left unchanged.
When SpaceReplacement is TRUE, any spaces in the security ID
and subsource fields of the event log messages are replaced with
underscores (_). Set SpaceReplacement to TRUE if the format file
expects the security ID and subsource fields to be a single word
(that is, uses a %s format specification for them). The adapter is
configured for a setting of TRUE. If SpaceReplacement is not set to
TRUE, the default value is FALSE.
UnmatchLog
Specifies a file to log discarded events that cannot be parsed into a

Tivoli Enterprise Console event class by the adapter. The discarded
events can then be analyzed to determine if modifications are
needed to the adapter format file.
WINEVENTLOGS
Controls which Windows Event Logs are monitored; also controls
the service version and overrides the command line interface.
The WINEVENTLOGS statement is a comma-delimited list with no
spaces that can contain the following values: Application, Directory
(Directory service), DNS, FRS, Security, System, All, and None.
In the following WINEVENTLOGS statement, the System, Security,
and File Replication service event logs are monitored and all others
are ignored:
WINEVENTLOGS=System,Security,FRS
In the following statement, all event logs are monitored:

WINEVENTLOGS=All
If a statement contains one or more event logs as well as the All or

None option, the All or None option is used and the list of event
logs is ignored. In the following example, all event logs are
monitored even though specific event logs are also listed:
WINEVENTLOGS=DNS,Directory,All
If a statement contains both the All and None options, the None
option overrides all other options. In the following example, no
event logs are monitored:
WINEVENTLOGS=Application,All,FRS,Directory,None
171
After changing the WINEVENTLOGS statement in the

tecad_win.conf file, you must restart the adapter for the changes to
take effect.
Prefiltering Windows log events

You can improve Windows event log adapter performance by filtering events in
the Windows event logs so only those events that are of importance to
administrators are processed by the adapter. This type of filtering is called
prefiltering because it specifies selection criteria based on the raw Windows event
record rather than the formatted Tivoli Enterprise Console event. The prefiltering is
performed before the event is formatted into a Tivoli Enterprise Console event and
subjected to any filtering specified with the Filter or FilterCache configuration file
keywords.
Like other adapter filtering, prefiltering is specified in the adapter configuration
file using a similar syntax. The prefiltering statements, PreFilter and PreFilterMode,
are described in Configuration file on page 168.
As with any modification to an adapter configuration file, you must stop and
restart the adapter for the changes to take effect.
There are four attributes of the Windows event logs that you can use in defining
prefilter statements. They are described in the following list:
Log
Specifies one or more of the Windows event logs to prefilter. Valid values
are System, Security, Application, DNS Server, File Replication Service,
Directory Service, or any combination of these separated by commas. The
default value is all these event logs.
EventId
Specifies the event number assigned by Windows. You can specify up to
sixteen event numbers. Multiple event numbers must be separated by
commas.
Source
The source that logged the event to the Windows event log. You can
specify up to sixteen sources. Multiple sources must be separated by
commas.
EventType
The classification of the event assigned by Windows. Valid values are as
follows:
v Error
v
v
v
v
v
Warning
Information
AuditSuccess
AuditFailure
Unknown
The following examples show prefiltering statements. The first statement is on

multiple lines due to space restrictions.
PreFilter:Log=Application;Source=MyApp;EventId=1000,2000, \
3000;EventType=Warning,Information;
PreFilter:Log=Security;
PreFilter:Log=Application;Source=TECWinAdapter;
172
Format file
The format file contains message format descriptions and their mappings to
BAROC events. The message fields of a Windows event are matched against the
format descriptions in this file and when a match succeeds, the corresponding
Tivoli Enterprise Console event is generated by the adapter. The format file
contains predefined mappings for some common Windows events and can be
customized to add any new messages.
A Windows event is written to an ASCII message in the following sequence:
v The date expressed as month, day, time, and year.
v The event category, expressed as an integer.
v The event type (Error, Warning, Information, AuditSuccess, AuditFailure,
Unknown).
v The Windows security ID; any spaces in this field are replaced by an underscore
if the proper registry variable is set.
v The Windows source; any spaces in this field are replaced by an underscore if
the proper registry variable is set.
v The Windows event identifier.
v The message text.
The subfields, except the message text field, are derived from the event header in
the Windows event object. The output message after formatting is bound against a
format description. A formatted error message from the Windows service control
manager can look like the following example:
Jan 15 15:06:19 1998 0 Error N/A Service_Control_Manager 7024 \
The UPS service terminated with service-specific error 2481.
For details about format files, see Format file on page 24 and Appendix B,
Format file reference, on page 187.
Registry variables
Registry variables are used to control the operation of the Windows event log
adapter. Changes made to registry variables take effect immediately; there is no
need to stop and restart the adapter. Use the registry editor (regedt32) provided by
Windows to view and modify registry variables.
Note: It is not necessary to modify the registry variables for the Windows event
log adapter to function. The registry variables are automatically set to the
correct default values when the Windows event log adapter is installed.
All of the registry variables for the Windows event log adapter are located in the
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
\TECWinAdapter directory. The following are the adapter registry variables:
Note: When you change the registry entries for any registry variable with a name
ending with EventsProcessedTimeStamp, you must also change the registry
entries for the corresponding registry variable with a name ending with
EventsProcessed. For example, if you change the registry entry for
ApplicationEventsProcessedTimeStamp, you must also change
ApplicationEventsProcessed.
173
If both values are not changed, the adapter ends unexpectedly, the
PollingInterval criteria are met, and a message similar to the following is
sent:
msg=TECWinAdapter shuts down.Error: older event on \
ApplicationEventsProcessed : (1,920433843) vs last processed \
event(1,923673952).;
To prevent this, stop the adapter and then make the necessary registry
changes. When you restart the adapter, a consistency check updates the
registry entry for the appropriate variable ending with EventsProcessed to
match the correct value based on the corresponding variable ending with
EventsProcessedTimeStamp.
ApplicationEventsProcessed
Contains the highest event number in the Windows Application Log that
the adapter has processed. The adapter uses this variable to keep track of
how many events it has read and sent to the event server so that the
adapter can start at the next event the next time it polls the log. You can
lower the ApplicationEventsProcessed variable if you want an event to be
read and processed again. To process all messages in the Application Log,
set the ApplicationEventsProcessed variable to 1.
ApplicationEventsProcessedTimeStamp
Contains the time stamp for the corresponding event identified by the
value of the ApplicationEventsProcessed variable.
DirectoryEventsProcessed
Contains the highest event number in the Windows active directory server
log that the adapter has processed. The adapter uses this variable to keep
track of how many events it has read and sent to the event server so that
the adapter can start at the next event the next time it polls the log. You
can lower the DirectoryEventsProcessed variable if you want an event to
be read and processed again. To process all messages in the Directory
Service Log, set the DirectoryEventsProcessed variable to 1.
DirectoryEventsProcessedTimeStamp
value of the DirectoryEventsProcessed variable.
DNSEventsProcessed
Contains the highest event number in the Windows DNS Server Log that
the adapter has processed. The adapter uses this variable to keep track of
how many events it has read and sent to the event server so that the
lower the DNSEventsProcessed variable if you want an event to be read
and processed again. To process all messages in the DNS Server Log, set
the DNSEventsProcessed variable to 1.
DNSEventsProcessedTimeStamp
value of the DNSEventsProcessed variable.
FileReplicationEventsProcessed
Contains the highest event number in the Windows File Replication service
event log that the adapter has processed. The adapter uses this variable to
keep track of how many File Replication service log events it has read and
sent to the event server so that the adapter can start at the next event the
next time it polls the log. You can lower the FileReplicationEventsProcessed
variable if you want an event to be read and processed again. To process
174
all messages in the File Replication service log, set the

FileReplicationEventsProcessed variable to 1.
FileReplicationEventsProcessedTimeStamp
value of the FileReplicationEventsProcessed variable.
PollingInterval
The adapter polls the Windows event logs for new events at intervals
when it does not receive any events automatically. The PollingInterval
variable specifies the upper frequency limit, in seconds, to poll the
Windows event logs. The default value is 120 seconds.
Polling begins at 5 seconds. If a new event is detected, the next polling
frequency begins at 5 seconds again. If no event is detected from a poll, the
polling interval is doubled, until the upper limit is reached. After the
upper limit is reached, the polling frequency remains at that interval until
a new event is detected; then, it is reset to 5 seconds.
Note: If there are buffered events, but no incoming events, the time still
doubles until the set PollingInterval time. To avoid this, set
PollingInterval to a lower number. The PollingInterval setting is in
the registry in HKEY_LOCAL_MACHINE\SYSTEM\
CurrentControlSet\Services\TECWinAdapter\. This is not set as a
default value and must be added to the registry to alter the default
value of 120 seconds.
SecurityEventsProcessed
Contains the highest event number in the Windows Security Log that the
adapter has processed. The adapter uses this variable to keep track of how
many events it has read and sent to the event server so that the adapter
can start at the next event the next time it polls the log. You can lower the
SecurityEventsProcessed variable if you want an event to be read and
processed again. To process all messages in the Security Log, set the
SecurityEventsProcessed variable to 1.
SecurityEventsProcessedTimeStamp
value of the SecurityEventsProcessed variable.
SystemEventsProcessed
Contains the highest event number in the Windows event log that the
adapter has processed. The adapter uses this variable to keep track of how
many log events it has read and sent to the event server so that the
lower the SystemEventsProcessed variable if you want an event to be read
and processed again. To process all messages in the event log, set the
SystemEventsProcessed variable to 1.
SystemEventsProcessedTimeStamp
value of the SystemEventsProcessed variable.
TECInstallPath
Specifies the directory that contains the Windows event log adapter
executable files and run-time files. This variable is usually set to
drive:\adapter_dir, where drive and adapter_dir are the drive and directory,
respectively, that contain the adapter executable files and run-time files.
Change the TECInstallPath variable only if you move the adapter
executable files and run-time files after you have installed the adapter.
175
Low memory registry variables

When enabled, this feature checks the amount of available memory before the
Windows event log adapter attempts to send an event. If the amount of free
memory is extremely low, the Windows event log adapter returns to a suspended
state until more memory is available, which prevents the adapter from failing.
However, because of the amount of resources this consumes, enable this feature
only when available memory is so low that the adapter is failing and you have no
other way to solve the problem.
To enable this feature, you must set at least one of following registry variables in
the \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
TECWinadapter\ registry path:
yellow_alert_limit
When free memory is below this level, the adapter sends a warning that
indicates the adapter might return to a suspended state until more memory
is available and lists the amount of free memory. The default value is 40
Mb.
red_alert_limit
When free memory is below this level, the adapter sends a warning and
lists the amount of free memory, then returns to a suspended state for 1
minute. After 1 minute, the adapter checks free memory again; if free
memory is still below this level, the adapter returns to a suspended state
for another minute and repeats until free memory is higher than this value.
The default value is 20 Mb.
emergency_memsize
This is the amount of memory the adapter keeps in reserve for low
memory situations. When the red_alert_limit is reached, the adapter frees
this memory to make sure there is enough memory available to send the
red_alert_limit warning. The default value is 2 Mb.
Any values that you do not set use the default values when you enable this
feature. The adapter checks these values only at startup.

The default action is that the adapter is always started when Windows is started. If
you are using the Windows service version of the Windows event log adapter, you
can use the Windows tools to operate the adapter. For example, you can start and
stop the adapter using Windows Control Panel Services. You can also manually
start the adapter from the command line with the net start
TECWinAdapter[_adapter_identifier] command where adapter_identifier is the
adapter identifier; for example, manually start an adapter that has no identifier
using this command:
net start TECWinAdapter
or, for an adapter with an identifier of toserver1, manually start it using this
command:
net start TECWinAdapter_toserver1
Note: The endpoint adapter is automatically started as a step in the adapter

installation process when the adapter configuration profile is distributed
using the Adapter Configuration Facility.
176

before file distribution can halt an event adapter and possibly remove the contents
adapter.
You can manually stop the adapter from the command line with the net stop
adapter identifier; for example, manually stop an adapter that has no identifier
using this command:
net stop TECWinAdapter
or, for an adapter with an identifier of toserver1, manually stop it using this
command:
net stop TECWinAdapter_toserver1
Reloading the adapter configuration

To reload the adapter configuration and format files, use the wsighup command. If
you are running the service version of the adapter, issue this command:
wsighup service_adapter_name
where service_adapter_name is the service name of the adapter. If you are running
the command-line version of the adapter, issue this command:
wsighup service_adapter_name pid
where service_adapter_name is the service name of the adapter and pid is the process
ID of the adapter.
Use this command if you want to change the adapter configuration without having
to stop and restart the adapter. For example, you might want to temporarily add
(and later remove) filters or entries in the format file when the system goes into
maintenance mode. After you have made the necessary changes to the
configuration and format files, issue this command to dynamically update the
adapter configuration.
Running multiple Windows event log adapters

You can run multiple instances of the Windows event log adapter on a single
system. It is recommended that additional adapters be run as non-TME adapters.
To monitor different log files, each instance of the adapter must have its own
configuration, format, class definition statement (CDS), and error files. If the
adapters use event buffering (set using the BufferEvents keyword, which has a
default value of YES), the adapters must also have their own cache files.
If you want to stop an adapter when multiple log files are running, you must
specify the name of the adapter to stop with the net stop
177

adapter identifier. If you do not specify the adapter to stop, the default adapter
without a name is stopped.
Events listing
the Windows event log adapter. You can use it to get a sense of how Windows
events are mapped to Tivoli Enterprise Console events and to determine if you
want to make any changes. The events are defined in the BAROC file.

defaults from the parent. The Windows event classes follow a simple hierarchy.
source NT
sub_source
NT
hostname
The following events are defined in BAROC file:
Table 18. Windows event log adapter events
Event Class
Severity
NT_Base
NT_Base_Event
NT_Diskfull
WARNING
NT_Share_Dir_Missing
WARNING
NT_Service_Start
WARNING
NT_Service_Stop
WARNING
NT_Out_Of_Paper
WARNING
NT_Printer_Out_Of_Paper
WARNING
NT_Low_Virtual_Memory
WARNING
NT_Security_Db_Not_In_Sync
WARNING
NT_Registry_Bad_DB
WARNING
NT_NCNB_Error
WARNING
NT_Parity_Error
WARNING
NT_Power_Failure
WARNING
NT_Thread_Create_Fail
WARNING
NT_Semaph_Create_Fail
WARNING
NT_Monitor_Start
WARNING
NT_TCPService_Fail
178
Table 18. Windows event log adapter events (continued)

Event Class
Severity
NT_Master_Browser_Conflict
NT_Document_Print_Success
NT_Document_Print_Deleted
NT_Internal_Error_In_The_DHCP_Server
NT_Performance_Alert
NT_Capacity_Alert
NT_Performance_Monitor
NT_Trustee_Relationship_Failed
NT_Service_Started
NT_Service_Terminated
NT_Printer_Error
NT_Printer_Was_Set
NT_Printer_Was_Created
NT_Printer_Pending_Deletion
NT_Security_Database
NT_Security_Database_Error
NT_Insight_Agent_Disk_Alert
NT_DHCP_Rejected_Allocation_Request
NT_Domain_Not_Contactable
NT_WINS_Alert
NT_WINS_Server_Alert
NT_Master_Browser
NT_Trustee_Relationship
NT_Timeserv_Worked
NT_Timeserv_Failed_1
NT_License_Service_No_License_Available
NT_License_Service_Out_Of_Licenses
NT_Restore
NT_Backup
NT_Replicator_Did_Not_Send_Update
NT_Replicator_System_Error
NT_Replicator
NT_Tivoli_Courier
NT_Tivoli_TEC_Adapter
NT_Tivoli_TEC_Adapter_Error_Sending_Alert
179
Table 18. Windows event log adapter events (continued)

Event Class
Severity
NT_Sophos_Sweep
NT_SNMP
NT_Insight_Manager_Error
NT_Insight_Manager
NT_Privileged_Service_Called
NT_Trusted_Process_Logon_Success
NT_Logon_Successful
NT_Logon_Failure
NT_User_Logoff
NT_Log_Clear_Successful
NT_Account_Management_Success
NT_Group_Management_Change_Success
NT_Global_Group_Changed
NT_Local_Group_Member_Removed
NT_Account_Password_Change_Success
NT_Server_Start
NT_Application_Error
NT_Table_Reached_Maximum_Size
NT_Handle_Closed
NT_Object_Open
NT_Audit_Policy_Change
NT_Duplicate_Name
WARNING
tecad_win command
The Windows event log adapter includes the tecad_win command, which you can
use to start the adapter in non-service mode. The command description is on the
following pages.
180
tecad_win
Starts the Windows event log adapter in non-service mode.
Syntax
tecad_win.exe [d] [c ConfigFile] [L none | EventLog ...] [i ID]
Description
The tecad_win command starts the Windows event log adapter in non-service
mode. You can use the non-service mode for diagnostic purposes or to view event
messages in a Windows console window. The Windows service mode adapter must
be stopped before the non-service mode adapter is started. To stop the service
mode adapter, run the following from the command line:
net stop TECWinAdapter
Before starting the non-service adapter, set the TECADHOME environment

variable.
Authorization: none
Arguments:
c ConfigFile
Specifies the configuration file for the Windows event log adapter. If a
value is not specified, the tecad_win.conf file in the current directory is
used. If the c argument is used, you can optionally specify a full path
name for the configuration file; otherwise, one of the appropriate
directories specified in File location on page 9 is used.
d
Shows debug information as events are gathered and transmitted. This

argument also selects a verbosity level of 1.
Note: When running a non-TME version of the Windows event log
adapter in this mode, make sure that no other adapters of the same
source are running at the same time.
i ID
Specifies the identifier for the adapter. The ID is used to specify the
directory containing the configuration and format files. It also enables
multiple adapters to be run.
Specifies which Windows event logs, if any, to monitor.

none
Specifies that no Windows event logs are monitored.
EventLog ...
Specifies which Windows event logs are monitored. Values are
ApplicationLog, DirectoryLog, DNSServerLog, FileReplicationLog,
SecurityLog, and SystemLog. When specifying more than one
event log, separate the entries with a space.
The following command starts the Windows event log adapter in diagnostic mode:
tecad_win d
The following command starts the Windows event log adapter with the
myconfile.conf configuration file:
tecad_win c myconfile.conf
Note: The .conf file must be in the /etc directory where the adapter is installed.
181
Troubleshooting the Windows event log adapter

Perform the following steps to troubleshoot the Windows event log adapter:
1. Stop the Windows event log adapter that is currently running by pressing the
Esc key in the command window session that is running the Windows event
log adapter. Pressing the Ctrl+c key combination in the command window
session that is running the Windows event log adapter also stops the adapter.
2. Start the adapter in debug mode:
tecad_win -d -c Config_File
3. Generate test events and see if the adapter receives them. Do this by starting
and stopping a service that logs to the Windows Event Manager. For example,
you can use the Windows Control Panel Services to stop the FTP Server and
then start it. This adds an event entry in the Windows Security Log that is
picked up by the Windows event log adapter.
Another effective way to generate and monitor Windows events is to run the
Windows User Manager application (located in the Administrative Tools
folder). Select Audit from the Policies menu and choose from the different
activities that Windows can monitor. You want these items to be audited and
then picked up by the Windows event log adapter.
Yet another method is to set up an alert in Windows Performance Monitor
(located in the Administrative Tools folder) to go off every 30 seconds when
the processor usage is less than 100%.
4. When events arrive, the adapter prints messages to the screen indicating the
class and the attribute values in the class.
If you do not see any messages, the adapter is not receiving events from the
Windows event logs.
5.
6.
7.
8.
182
For example, you should see a message that the FTP server has registered as a
trusted login process. If you do not see this message, run the Windows User
Manager application (located in the Administrative Tools folder), select Audit
from the Policies menu and choose Restart, Shutdown, and System events to
be audited for Success and Failure. Then stop and restart the Windows FTP
server as described in steps 1 and 2.
If you see the messages, the adapter is receiving events and processing them.
Run the wtdumprl command on the event server and verify that the messages
received by the event server or there is a problem with the event server
reception process. Check the adapter configuration file to verify that
TransportList (or ServerLocation and ServerPort) is properly defined. If the
event class is in any filter entry in the configuration file, the event is not sent to
the event server. The administrator who started the adapter must have the
required roles if you are running the TME version of the adapter. For a TME
adapter, running the odstat command can offer some clues as to what failed.
If the reception log has a PARSING_FAILED error, the BAROC definition of the
If the previous steps do not indicate any problem and you do not see the new
events in the Tivoli Enterprise Console product, there might be a problem with
the event group filters. Make sure the class filters match the classes in the
BAROC files.
Change all /dev/null entries in the .err file to the file name you want. Stop
Appendix A. Files shipped with adapters

Notes:
1. The IBM NetView for OS/390 adapters are delivered with Tivoli NetView for
OS/390 as part of the Event/Automation Service. Although these adapters are
shipped as part of that product, the BAROC files and rule files for them are
shipped with the Tivoli Enterprise Console product. For information about
additional files shipped with these adapters, see the Tivoli NetView for OS/390
documentation.
The following table lists some of the files used with the shipped adapters. An x
indicates the file is used by an adapter.
Table 19. Files shipped with adapters
File
Extension
AS/400 Alert
AS/400 Message
NetWare
OpenView
OS/2
SNMP
UNIX Log File
Windows Event Log
Adapter
BAROC
.baroc
Class definition statement

(CDS)
.cds
Configuration
.conf
Error
.err
Format
.fmt
Installation script
.cfg
Object identifier
.oid
Registration
.lrf
Rules
.rls
1. The AS/400 adapters use a .mbr extension.

2. The OS/2 adapter actually uses a command file (.cmd) for performing this function.
3. A rules file is not shipped with the AS/400 message adapter. You can create a rules file
if needed.
The following table lists the file names for some of the more significant files used
for the IBM Tivoli Enterprise Console adapters:
183
Table 20. Adapter files

Adapter
Extension
File Name
AS/400 alert
.baroc
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/
ALRBRC.MBR
tecad_snaevent.baroc (on event server)
.cds
ALRCDS.MBR
.conf
ALRCFG.MBR
.rls
ALRRLS.MBR
tecad_snaevent.rls (on the event server)
.baroc
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/
MSGBRC.MBR
as400msg.baroc (on the event server)
.cds
MSGCDS.MBR
.conf
MSGCFG.MBR
.brc
tecadnw4.brc
.cds
tecadnw4.cds
.cnf
tecadnw4.cnf
.err
tecadnw4.err
.fmt
tecadnw4.fmt
.baroc
tecad_hpov.baroc
.cds
tecad_hpov.cds
.cfg
tecad_hpov.cfg
.conf
tecad_hpov.conf
.err
tecad_hpov.err
.oid
tecad_hpov.oid
.rls
ov_default.rls
.baroc
tecados2.baroc
.cds
tecados2.cds
.cmd
tecados2.cmd
.conf
tecados2.conf
.err
tecados2.err
.fmt
tecados2.fmt
.baroc
tecad_snmp.baroc
.cds
tecad_snmp.cds
.cfg
tecad_snmp.cfg
.conf
tecad_snmp.conf
.err
tecad_snmp.err
.oid
tecad_snmp.oid
AS/400 message
NetWare
OpenView
OS/2
SNMP
184
Table 20. Adapter files (continued)

Adapter
Extension
File Name
UNIX log file
.baroc
tecad_logfile.baroc
.cds
tecad_logfile.cds
.cfg
tecad_logfile.cfg
.conf
tecad_logfile.conf
.err
tecad_logfile.err
.fmt
tecad_logfile.fmt
.rls
log_default.rls
.baroc
tecad_win.baroc
.cds
tecad_win.cds
.conf
tecad_win.conf
.err
tecad_win.err
.fmt
tecad_win.fmt
Microsoft Windows
event log
Appendix A. Files shipped with adapters
185
186
Appendix B. Format file reference

This appendix contains details about format files.
The format file usually has an extension of .fmt; see each specific adapter chapter
for exact file names. To use non-English characters in a format string, you must
enter the non-English characters in the local encodings.
Notes:
1. Although this section describes the manual text editing of a format file and the
file organization, you can accomplish the same results for TME adapters with
the Logfile Format Editor of the Adapter Configuration Facility. See the IBM
Tivoli Enterprise Console Users Guide for information about using the Logfile
Format Editor.
2. The UNIX logfile adapter, NetWare logfile, and OS/2 adapter format files are in
English only. The Microsoft Windows event log format file is in English and
localized into a sample file for the Tivoli supported languages. If you have a
source that issues events in a non-English language and you are monitoring
that source with an adapter that uses a format file, and the format file has not
been localized, you must localize the format file in that language.
Format file location

An English-language format file is located in each of the language subdirectories
that are in the same directory as the adapter configuration file. The language
subdirectories are as follows:
Table 21. Format file location
Language
Subdirectory
English
/C
German
/de
Spanish
/es
French
/fr
Italian
/it
Japanese
/ja
Korean
/ko
Brazilian Portuguese
/pt_BR
Simplified Chinese
/zh_CN
Traditional Chinese
/zh_TW
See File location on page 9 for more details.
Format specifications
The format file is made up of one or more format specifications. A format
specification has the following parts:
v Format header
187
The keyword FORMAT followed by the event class name. This is optionally
followed by the FOLLOWS keyword and a previously defined class name, as
shown in the following example:
Note: A format specification with the same class name can be defined more than
once. Be careful of using multiply-defined format specification class
names with the FOLLOWS keyword. Because there is no way to specify
which actual format specification is intended, the last one defined in the
file that matches the class name is used.
v Format content
A format string optionally followed by a list of mappings, as shown in the
following example:
sharename $8
directoryname $9
v The END keyword completes the format specification.

The format header, format string, each mapping, and the END keyword must each
begin on a new line, as shown in the following example:
sharename $8
directoryname $9
END
The FOLLOWS relationship enables specific format specifications to be built from

generic format specifications using inheritance. When format B follows format A, B
inherits all of the mappings (but not the format string) from A. Format B can
define any additional mappings, but any mappings redefined by B are not
inherited from A; that is, format B can override inherited mappings by redefining
them.
System log messages typically have a common format consisting of a time stamp, a
host name, and event text. These system log message components are represented
in a format string using a component-specifier notation very similar to the
printf() notation used in the C programming language. The following format
string describes the entire class of system log messages produced by the UNIX
syslogd daemon:
%t %s %s*
System log messages are tokenized into constants and white space. A constant is
any consecutive string of non-white spaces. The component specifiers enable the
constants and white space to be grouped into more complex tokens when trying to
match a format string with a specific message. The component specifiers always
end in a constant and not white space. The component specifiers are as follows:
v %[length]s
Matches one constant in the message. The optional length is a decimal number
of any size and indicates that the constant is to be truncated to the length if the
constant actual length is greater than the specifier length.
v %[length]s*
188
Matches zero or more constants in the system log message. The optional length
is a decimal number of any size and indicates that any of the accumulated
constants is to be truncated to the length if the constant actual length is greater
than the specifier length.
v %[length]s+
Matches one or more constants in the message. The optional length is a decimal
number of any size and allows any of the accumulated constants to be truncated
to the length if the constant actual length is greater than the specifier length.
v %t
Matches a time stamp of the following form:
month date time
v %n
Matches a carriage return in the message. Use this specification to match
messages that span multiple lines.
Log file example

The following successful su message from a system log is an example of matching
a system log message to the generic format specification mentioned in the
preceding section:
Sep 13 12:17:11 elcap su: su root succeeded for tjones on /dev/ttyp0
The component specifiers and matches are as follows:

%t
Sep 13 12:17:11
%s
elcap
%s*
su: su root succeeded for tjones on /dev/ttyp0
The system log message contains some constant parts and some variable parts. The
constant parts of the system log message are the same for any successful su
message. The constant parts are as follows:
v su: su
v succeeded for
v on
The variable parts of the example system log message are as follows:
v Sep 13 12:17:11
v elcap
v root
v tjones
v /dev/ttyp0
The following example shows how the variable data differs in another successful
su message:
Sep 29 14:57:28 aspen su: su root succeeded for jsmith on /dev/ttypd
The general format specification %t %s %s* can be specialized for the Su_Success
event class as follows:
%t %s su: su %s succeeded for %s on %s
189
Using the system log message from the preceding September 29 example, the
component specifiers and matches are as follows:
%t
Sep 29 14:57:28
%s
aspen
su: su
su: su
%s
root
succeeded for
succeeded for
%s
jsmith
on
on
%s
/dev/ttypd
The white space characters that separate the words of a system log message must
also be present in the format string. A single space character (that is, one blank) in
the format string matches any number of white space characters in the message.
For example, if the space between the colon (:) and the quotation mark () is
deleted in the preceding specialized format string, as shown in the following
example, the system log message would no longer match it.
%t %s su:su %s succeeded for %s on %s
Care should be taken when using the arbitrary length repeater component
specifiers (%s* and *s+). The following format string does not make much sense:
This is not a good format %s* %s*
The first %s* matches everything through the end of the message, and the second
%s* never matches anything. Although it might seem that this does not matter, the
importance is described in Mappings on page 191.
The following format string, however, is meaningful:
This is a good format %s* : %s*
The first %s* matches everything up to the first colon (:), and the second %s* now
matches everything through the end of the message.
The format string must also reflect whether white space precedes a constant or
component specifier. In the following example, both messages match a format
string of %s*company_xyz because they are preceded by zero (0) or more constants
and no white space.
company_xyz is logging messages
Acompany_xyz is logging messages
However, the following example requires a format string with a space after the %s*
component specifier, as in %s* company_xyz, because it is preceded by white space
and does not match the previous format string.
the company_xyz is logging messages
From the preceding examples, you can see that you can specialize a generic format
string to match a more specific event by either replacing component specifiers with
constants or by restricting the arbitrary length repeater specifiers to a fixed length,
using constants to complete the specifier.
190
Windows example
The following example is a Windows message:
Jan 15 15:06:19 1998 0 Error N/A Service_Control_Manager 7024 \
The UPS service terminated with service-specific error 2481.
The variable parts are the time stamp (Jan 15 15:06:19 1998), possibly the security
ID (N/A), the event ID (7024), the service name (UPS), and the error code (2481).
Another system log message uses the same general format, as shown in the
following example:
Sep 29 14:57:28 1998 0 Error N/A Service_Control_Manager 7025 \
The SNMP service terminated with service-specific error 2482.
The constant parts of a system log message are defined by simply embedding them
in the format string itself. The variable parts are defined using the component
specifier. The format string for the preceding September 29 example could be
written as follows:
%t %s %s Error %s Service_Control_Manager %s The %s \
service terminated with service-specific error %s.
The white space characters that separate the words of a system log message must
also be present in the format string. A single space character (that is, one blank) in
the format string matches any number of white space characters in the message.
Care should be taken when using the arbitrary length repeater component
specifiers (%s* and *s+). The following format specification does not make much
sense:
This is not a good format %s* %s*
The first %s* matches everything through the end of the message, and the second
%s* never matches anything. Although it might seem that this does not matter, the
importance is described in Mappings on page 191.
The following format string, however, is meaningful:
This is a good format %s* : %s*
The first %s* matches everything up to the first colon (:), and the second %s* now
matches everything through the end of the message.
Mappings
The logfile adapters translate system log messages into event class instances
containing attribute name=value pairs. The event is then sent to the event server. An
associated BAROC file containing class definitions at the event server is used to
validate the incoming event before processing the event further.
For the logfile adapters, the event class for a system log message is determined at
the source by matching a system log message to a format string in the format file.
After a class is determined by this matching, values must be assigned to the
attributes. Attribute values can come from a variety of sources, such as from the
system log message itself, from default values provided by the adapter, or from
mappings within the format specification of a class in the format file. This section
describes how the mappings in a format specification assign values to attributes.
191
The mapping part of a format specification consists of zero or more lines that
contain a BAROC file attribute name followed by a value specifier. The value
specifiers can be one of the following types:
$i
Where i indicates the position of a component specifier in a format string.

Each component specifier is numbered from 1 to the maximum number of
component specifiers in the format string. For example, in the specialized
format specification for the Su_Success event shown following, the third
%s component specifier (in bold) would be referred to in any mappings as
$4.
%t %s su: su %s succeeded for %s on %s
The value of a $i value specifier (also referred to as a variable) is the

portion of the system log message that was consumed by the component
specifier.
string constant
The value of the attribute is the specified string. If the string is a single
constant, it can be specified without surrounding double quotation marks
(" "); otherwise, double quotation marks must be used.
PRINTF statement
Creates more complex attribute values from other attribute values. The
PRINTF statement consists of the keyword PRINTF followed by a printf()
C-style format string and one or more attribute names. The format string
supports only the %s component specifier. The values of the attributes that
are used in the PRINTF statement must also have been derived from either
a $i value specification or a constant string value specification (they cannot
be derived from another PRINTF statement). The value of the argument
attributes is used to compose a new constant string according to the format
string. This new constant string becomes the value of the attribute.
The following example shows how the msg attribute is assigned the
constant string value of date set by mfoster. User ID mfoster was
derived from the value assigned to the set_by attribute.
msg PRINTF("date set by %s", set_by)
DEFAULT keyword
Indicates the adapter uses its internal logic to assign a value to the
indicated attribute. For example, the UNIX syslogd messages contain the
host name where the message was logged; the adapter can use this name
to derive the origin attribute (the protocol address or host name of the
originating host).
Note: Adding new DEFAULT mappings also requires changes to an
adapter source code to add new logic for obtaining attribute values.
Because DEFAULT is a keyword, a constant mapping whose value is the
string DEFAULT must be specified in double quotation marks (" ").
FILENAME keyword
Indicates the fully qualified file name (including path) of the log file
containing the message. In cases where you are using a single adapter to
monitor multiple log files, you can use this key word to populate an event
attribute with the file name to identify the source of the event. If the
message comes from the system log, then mapping is set to "EventLog" for
Windows adapters and "SysLogD" for UNIX logfile adapters.
192
LABEL keyword
Indicates the type of system on which the adapter is running, which
provides better control over the hostname attribute coming from the
adapter. For a managed node, the value is the managed node name; in an
endpoint, it is the endpoint name, which is listed in last.cfg as
lcs.machine_name. In a non-TME adapter, the value is the host name of the
system.
Additional mapping considerations

Specify only one mapping for each BAROC file attribute.
A mapping can be inherited from a more generic format specification (using the
FOLLOWS keyword) or can be explicitly defined on the format specification that
directly matches the message.
Because the adapter does not access the BAROC file, which resides on the event
server, care must be taken to make sure that the format specifications agree with
the corresponding BAROC file definitions. If an attribute name is misspelled in a
mapping, the adapter does not report an error but does send the event to the event
server as usual; however, the event is discarded by the event server because it does
not exactly match a class definition.
There can be attributes in the system log message that do not directly correspond
to any BAROC file attributes because the adapter might need to use these values
to compose PRINTF style constant strings for assigning to attributes. This type of
data needs to be assigned to temporary attributes that do not get sent to the event
server, but are used in the PRINTF statement. Temporary attributes are designated
with a hyphen (-) immediately preceding the attribute name in a mapping.
To illustrate the use of mappings in format specifications, a sample from the
default tecad_logfile.fmt file is shown following with a few additions.
FORMAT Logfile_Base
%t %s %s*
date $1
hostname $2
msg $3
origin DEFAULT
END
/* login */
// NOTE -- anything enclosed in /* and */ pairs is considered to
// be a comment. These comments can extend across multiple lines.
// Anything following a // is also considered to be a comment;
// this comment only extends to the end of the line.
FORMAT Logfile_Login FOLLOWS Logfile_Base
%t %s login: %s*
sub_source login
END
FORMAT Root_Login FOLLOWS Logfile_Login
%t %s login: ROOT LOGIN %s*
END
FORMAT Root_Login_Success FOLLOWS Root_Login
%t %s login: ROOT LOGIN %s
on_tty $3
msg PRINTF("root login %s", on_tty)
END
193
FORMAT Root_Login_Success_From FOLLOWS Root_Login_Success

%t %s login: ROOT LOGIN %s FROM %s
from_host $4
-extra ", with extra stuff!"
msg PRINTF("root login from %s%s", from_host, extra)
END
Now, assume that the following system log message is received by the logfile
adapter:
Dec 10 09:45:06 sawmill login: ROOT LOGIN ttyp6 FROM oak
The logfile adapter attempts to match this system log message to the most specific
format specification. In this case, the event matches the Root_Login_Success_From
format specification. The event created by the logfile adapter therefore has an event
class of Root_Login_Success_From. The following mappings then take place:
Mapping Assignments
Source of Mapping
$1="Dec 10 09:45:06"
From the %t component specification
$2="sawmill"
From the first %s component specification
$3="ttyp6"
From the second %s component specification
$4="oak"
From the third %s component specification
date="Dec 10 09:45:06"
From $1
hostname="sawmill"
From $2
origin= 9.37.43.12"
From the default value of the origin

attribute, as derived by the logfile adapter
sub_source="login"
From the constant string
on_tty="ttyp6"
From $3
from_host="oak"
From $4
-extra=", with extra stuff!"
From the constant string
msg="root login from oak, with extra

stuff!"
From the PRINTF statement
The following list describes how values were assigned:

v The date and hostname attributes were inherited from the Logfile_Base class
(through the Logfile_Login, Root_Login, and Root_Login_Success classes).
v The origin attribute was also inherited from the Logfile_Base class, and was
assigned the adapter default.
v The msg attribute was not inherited from the Logfile_Base class, because it was
overridden by the Root_Login_Success_From class.
v The sub_source attribute was inherited from the constant string defined in the
Logfile_Login class.
v The on_tty attribute was inherited from the Root_Login_Success class.
v The from_host attribute was explicitly defined on the Root_Login_Success_From
class.
v The extra attribute was defined as a temporary attribute. It is not forwarded to
the event server as a part of this event.
There are a couple of other interesting items to note from this example:
v In the PRINTF value specification for the msg attribute in the
Root_Login_Success_From class, two %s conversions are specified without any
194
intervening white space. This enables the final msg attribute value to be created
without any space between the string oak and the comma.
v In the Root_Login format specification, there are no explicit mappings; all
mappings are inherited. This allows class name specialization without changing
any attribute values. Any event that matches the Logfile_Login class has the
same attributes and values as those that match the Root_Login class, but the
class name is different.
v Variables are resolved from the matching format specification, even if they are
inherited. For example, if the msg attribute had not been overridden with the
PRINTF statement in the Root_Login_Success_From class, its value would have
been ttyp6. This is because the msg attribute is inherited as the third component
specification in the event, even though the third component in the originating
class (Logfile_Base) would have yielded the value sawmill login: ROOT LOGIN
ttyp6 FROM oak.
Activating changes made with a format file

If you have made changes to a format file, you must generate a new class
definition statement (CDS) file that contains those changes.
Generating a new class definition statement file for a TME

adapter
To generate a new CDS file for a TME adapter, simply distribute a profile
containing the changed format file to the appropriate endpoints. The shipped
default profile contains the appropriate commands to automatically perform the
following actions:
2. Generate a new CDS file from the distributed format file.
3. Restart the adapter.
These commands can be viewed for the profile being distributed by selecting
Actions in the Edit Adapter window of the Adapter Configuration Facility.
Generating a new class definition statement file for a non-TME

adapter
To generate a new CDS file for a non-TME adapter, you must perform the
following tasks:
NetWare logfile
See tecadnw4.nlm on page 121.
OS/2
See Stopping the adapter on page 141.
UNIX logfile
Windows event log
2. Generate a new CDS file using the following commands. The logfile_gencds,
nw4gencds.nlm, os2gncds.exe, and win_gencds.exe programs are located in
the bin subdirectory of the directory where you installed the adapter. The
format file is in the appropriate language subdirectory in the etc directory
195
where you installed the adapter (see Format file location on page 187 for the
appropriate language subdirectory). Specify the appropriate path to create the
new CDS file in the etc directory.
OS/2
os2gncds /language/tecados2.fmt tecados2.cds
UNIX logfile
logfile_gencds /language/tecad_logfile.fmt > tecad_logfile.cds
Windows event log

win_gencds /language/tecad_win.fmt tecad_win.cds
3. Restart the adapter:

NetWare logfile
See tecadnw4.nlm on page 121.
OS/2
See Starting the adapter on page 140.
UNIX logfile
Windows event log
196
Appendix C. Class definition statement file reference

A class definition statement (CDS) file specifies SELECT, FETCH, and MAP
statements for all event classes supported by adapters that utilize a CDS file. This
provided file is required for most adapters and has the same format for all
adapters that use it. A CDS file has an extension of .cds; see each adapter chapter
for exact file names.
File format
Most of the CDS file is composed of class definition statements. A CDS file has the
following format:
MAP_DEFAULT
map_default_clause
END
CLASS class_name
SELECT
select_clause ...
FETCH
fetch_clause
...
MAP
map_clause
END
Comment lines begin with a number sign (#). For syntax reference information in
BNF notation, see Class definition statement file syntax diagrams on page 202.
Operators
Various operators are used in class definition statements, as follows:
v The PREFIX and SUFFIX operators are valid only for string attribute names,
values, or keys.
v The CONTAINS operator is valid only on string values.
v The not equals (!=), greater than (>), greater than or equals (>=), less than (<),
and less than or equals (<=) operators are applicable only to integer values; they
are not implemented for integer keys.
The following is an example of the use of the operators. In this example, the code
is for an AS/400 message adapter:
CLASS AS400_MSG
SELECT
1: ATTR(=,$MSG), VALUE(PREFIX,"Job");
2: ATTR(=,$MSG), VALUE(CONTAINS,"for User");
3: ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate.");
FETCH
1: SUBSTR($MSG,4,8)
2: SUBSTR($MSG,22,8)
MAP
$severity = CRITICAL;
$msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2);
END
Table 22 on page 198 describes each statement in the example:

197
Table 22. Explanation of operators in example code

Code
Explanation
SELECT
A match occurs when any message arriving

with the Class=AS400_MSG, where the first
part of the message field equals Job.
ATTR(=,$MSG), VALUE(PREFIX,"Job");
SELECT
ATTR(=,$MSG), VALUE(CONTAINS,"for User");
SELECT
ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate.");
FETCH
A match occurs when the message field

contains for User anywhere within the
message text.
To match, the end of the message field must be
the text You must investigate. The case of the
message must be exactly as shown in the
example.
This part of the FETCH statement pulls
characters from the message field. It starts at
character 5, because it is zero-based. It pulls a
total of eight characters. For example, the
message is Job 12345678 for User stephens
has stopped. You must investigate. The
statement pulls 12345678 for the first line of the
FETCH statement. The second line pulls the
text stephens.
SUBSTR($MSG,4,8)
SUBSTR($MSG,22,8)
MAP
$severity = CRITICAL;
$msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2);
The severity attribute is set to CRITICAL. It

prints using the two items that were pulled
with the FETCH statement.
Class definition statement file details

For each class of event supported by an adapter, one or more class definition
statements are present in the CDS file. These statements define which incoming
event maps to a particular class and how the attributes of the formatted event
instance going to the event server are filled with values. The class definition
statements are described as follows:
SELECT
Specifies the criteria an incoming event must satisfy to match a class.
FETCH
Retrieves data from the incoming event that is necessary to fill the attribute
values.
MAP
Specifies how to fill attribute values for an event instance from data
retrieved by FETCH statements.
Class definition statements are evaluated in the order they occur in the CDS file.
An incoming event is mapped to the class specified by the first class definition
statement whose SELECT statement is evaluated successfully.
When more than one class definition statement is provided for a particular class of
event, the class definition statement with the most restrictive SELECT statement is
placed before the less restrictive statements in the CDS file. Locating the most
restrictive class definition statement first for a same-named class provides for
better performance of the adapter.
If the class name equals *DISCARD*, any incoming event matching the SELECT
statement is discarded. Note that an event is also discarded if it does not match
any class definition statement. However, if a particular type of incoming event
must always be discarded (for example, routine events that are of no importance to
administrators), it is more efficient to define a *DISCARD* class definition statement
198
and locate it at the beginning of the CDS file, rather than let the adapter evaluate
all class definition statements and finally discard the event.
SELECT statement
There is one SELECT statement for each class definition statement. SELECT
statements have the following general format, where n is the identification number
of a clause within a SELECT statement:
SELECT
n:
ATTR(a_op, a_op_value),
KEY(k_op, k_op_value),
VALUE(v_op, v_op_value);
The ATTR part is mandatory and specifies a condition on the attribute name. The
KEY and VALUE parts are optional and respectively specify a condition on the
attribute key and attribute value. a_op, k_op, and v_op are available operators to
express conditions over the attribute name, key, or value (=, !=, <, <=, >, >=,
PREFIX, SUFFIX, CONTAINS). a_op_value, k_op_value, and v_op_value specify the
comparison value.
In order for a SELECT statement to be evaluated successfully, the following
conditions must be met as follows:
v The incoming event must contain an attribute whose name matches the ATTR
part. If the match is not unique (that is, several attributes can match the ATTR
part), only the first match is used. It is the key and value of this attribute that is
referred to in the rest of the statement. For example:
ATTR(=,"ifDescr")
means that the incoming event must contain an attribute named ifDescr.
v If a KEY part is present, the key of the attribute selected during the previous
step must match the condition expressed by the KEY() expression. For example:
KEY(!=,1)
means that attribute ifDescr must have a key with a value other than 1.
Note: AS/400 adapters do not support KEY parts in CDS files.
v If a VALUE part is present, the value of the attribute must match the condition
expressed by the VALUE expression. For example:
VALUE(PREFIX,"Serial")
means that the value of attribute ifDescr must begin with Serial (for example,
Serial1).
Using the previous examples, the complete clause of the SELECT statement reads
as follows:
SELECT
1:
ATTR(=,"ifDescr"), KEY(!=,1),
VALUE(PREFIX,"Serial");
SELECT statements and their associated clauses are evaluated in the order they
occur in the CDS file. If all the clauses of a SELECT statement are evaluated
successfully, the incoming event matches the corresponding class.
After an event is matched with a class because of successful SELECT statement
evaluation, processing continues with the FETCH statement, unless the class
is *DISCARD*, in which case the event is discarded. If the evaluation of a SELECT
199
statement fails, the kernel tries to match the event with the SELECT statement of
the next class. If the incoming event cannot be matched with any class, it is
discarded.
Each time a SELECT statement is evaluated successfully, the adapter kernel layer
creates three temporary pseudo-variables: $Nn, $Kn, $Vn (where n is the
identification number of a clause in the SELECT statement). These variables
contain the name, key, and value of the attribute specified in the clause,
respectively. The pseudo-variables can then be used in any following SELECT,
FETCH, or MAP statement.
The default setting is that the attribute name specified in an ATTR() expression is a
string, and the attribute matching this name is searched for sequentially in the
incoming event. For most adapters, every incoming event contains a minimum set
of mandatory fields. For this reason, each adapter supports built-in keywords that
can be used to reference these mandatory attributes and thereby directly access
their values. These keywords have the format $attribute_name. Examples of
keywords supported by the SNMP adapter are: $AGENT_ADDRESS,
$COMMUNITY, $ENTERPRISE, $TYPE, and $SPECIFIC. These keywords refer to
the mandatory fields of an SNMP Trap-PDU. Each adapter can also define global
variables, such as RECEPTION TIME, SVARBIND, and so forth.
Using the $ notation, a clause for SNMP authentication failure traps can be written
as follows:
1:
ATTR(=,$TYPE),VALUE(=,4);
This notation is not simpler than the format shown in the previous example,
ATTR(=, "type"), but evaluation is faster because it results in direct access to the
variable instead of a linear search.
The syntax shown in the preceding example is generic, and as such, it can be
rather verbose for commonly used criteria. Several shortcuts are provided to
alleviate the notation. For example, the previous example can be written as follows:
1:$TYPE=4;
Output from the class selection process is the name of the event class, a table of
pseudo-variables $Nn, $Kn, $Vn, and all adapter-specific variables (for example,
$TYPE, $VARBIND, and so forth).
FETCH statement
The FETCH statement of a class definition statement enables manipulation and
modification to the attribute names, keys, and values retrieved by the SELECT
statement for the incoming event. Sometimes it is necessary to perform tasks such
as extracting a substring from an attribute value, adding two values, and so forth.
There can be one or more clauses within a FETCH statement. Each clause has the
following format:
n:expression;
where n is the identification number of a clause within a FETCH statement and
expression is an expression specifying the value to assign the pseudo-variable $Fn.
Pseudo-variables are the output from a clause of a FETCH statement. This
expression can make reference to any pseudo-variable defined by the adapter,
200
which could have been created from the SELECT statement or from a previous
clause within the FETCH statement for the class.
An example of a FETCH statement is as follows:
FETCH
1:SUBSTR ($V2, 1, 5 );
MAP statement
The MAP statement of a class definition statement assigns values to the attributes
of the event class instance.
There can be one or more clauses in a MAP statement. Each clause has one of the
following two formats:
attribute_name=variable;
attribute_name=PRINTF(format_string,var1,...);
An example of a MAP statement is as follows:
MAP
origin=$AGENT-ADDRESS;
msg=PRINTF("Link %s is DOWN",$V3);
The output from a MAP statement is a list of attribute name=value pairs that is
used to generate the outgoing event for the event server.
MAP_DEFAULT statement
Some attributes, like source and sub_source, could have a constant value for all the
events generated by an adapter type. To not repeat identical clauses for MAP
statements in all class definition statements for an adapter, the CDS file can contain
a MAP_DEFAULT statement. The MAP_DEFAULT statement specifies default
values for the mandatory attribute name=value pairs. The following example
illustrates a MAP_DEFAULT statement:
MAP_DEFAULT
source = SNMP;
sub_source = NET;
# forwarding_agent = $SOURCE_ADDR;
origin = $AGENT_ADDR;
adapter_host = $ADAPTER_HOST;
END
Example
The following example shows a CDS file:
#
# Default attribute values
#
MAP_DEFAULT
source=NET;
sub_source=SNMP-TRAP;
origin=$SOURCE_ADDR;
END
CLASS Authentication_Failure_Cisco
SELECT
2: $TYPE = 4;
3: ATTR(=,"authAddr");
FETCH
201
MAP
hostname = $F1;
originating_address = $V3;
END
# For Cisco routers, because we know the interface generating the trap,
# we map linkUp traps to linkDown CLOSED events
CLASS Link_Down_Cisco
SELECT
2: $TYPE = 3;
3: ATTR(=,"ifIndex");
4: ATTR(=,"ifDescr");
5: ATTR(=,"ifType");
6: ATTR(=,"locIfReason");
FETCH
MAP
hostname = $F1;
sub_origin = $V4;
status = CLOSED;
interface_index = $V3;
interface_description = $V4;
interface_type = $V5;
reason = $V6;
END
Object identifier to name translation

The selection of an attribute is based on its name. With adapters that receive
SNMP trap messages, the standard way of naming attributes is to use object
identifiers (OIDs). For example, SNMP variable ifDescr is named 1.3.6.1.2.1.2.2.1.2.
Using SNMP object identifiers in SELECT statements is not very convenient.
Additionally, because the SNMP variable ifDescr is part of a table, it is indexed by
the interface number. If the interface number is 2, the received object identifier is
1.3.6.1.2.1.2.2.1.2.2. Without some knowledge of the Management Information Base
(MIB), the SNMP adapter has no way to translate an object identifier into a more
understandable name, or to extract key parts from an object identifier.
An object identifier file (tecad_adaptername.oid) for SNMP-based adapters contains
OID-to-name mappings for some SNMP variables. You can add or modify this file
as needed. The format of an object identifier file is:
name object_identifier
For example:
"authAddr"
"ifDescr"
"1.3.6.1.4.1.9.2.1.5"
"1.3.6.1.2.1.2.2.1.2"
Class definition statement file syntax diagrams

This section describes the syntax for statements that can be used within a CDS file.
The syntax is shown in BNF-like notation where the vertical bar (|) character
represents alternatives, and optional parts are contained within braces ({}).
*
* FILE CONTENT
*/
<file> ::= <statements> | /* empty */
<statements> ::=
<statement>
| <statement> <statements>
202
<statement> ::=
<mapdefault_statement>
| <class_statement>
/*
* MAP_DEFAULT STATEMENT
*/
<mapdefault_statement> ::=
MAP DEFAULT
<mapdef_statements>
END
<mapdef_statements> ::=
<mapdef_statement>
| <mapdef_statement> <mapdef_statements>
<mapdef_Statement> ::=
<attribute_name> = <constant> ;
| <attribute_name> = <keyword> ;
<attribute_name> ::+ <atom>
/*
* CLASS STATEMENT
*/
<class_statement> ::=
CLASS <class_name>
{ SELECT
<select_statements>
{ FETCH
<fetch_statements>
{
MAP
<map_statements>
END
}
}
}
<class_name> ::+
*DISCARD*
| <atom>
/*
* SELECT STATEMENT
*/
<select_statements> ::=
<select_statement>
| <select_statement> <select_statements>
<select_statement> ::=
<number>
: <attr_decl>
{
, <key_decl>
}
{
, <value_decl>
}
;
| <number>
: <keyword> = <v_op_val> ;"
| <number>
: <constant> = <v_op_val> ;
<attr_decl> ::=
ATTR ( <a_op> , <a_op_val> )
<key_decl ::=
KEY ( <k_op> , <v_op_val> )
<a_op> ::=
=
| PREFIX
| SUFFIX
| EXISTS
<a_op_val> ::=
<constant>
| <keyword>
| <name_var>
| <key_var>
| <value_var>
203
<k_op> ::=
=
| !=
| >
| >=
| <
| <=
| PREFIX
| SUFFIX
| EXISTS
<k_op_val> ::=
<constant>
| <keyword>
| <name_var>
| <key_var>
| <value_var>
<v_op> ::=
=
| !=
| >
| >=
| <
| <=
| PREFIX
| SUFFIX
| EXISTS
<v_op_val> ::=
<constant>
| <keyword>
| <name_var>
| <key_var>
| <value_var>
/*
* FETCH STATEMENT
*/
<fetch statements> ::=
<fetch_statement>
| <fetch_statement> <fetch_statements>
<fetch_statement> ::= <number> : <fetch_expr> ;
<fetch_expr> ::=
<fetch_value>
| <substr_expr>
<fetch value> ::=
<constant>
| <keyword>
| <name_var>
| ckey_var>
| <value_var>
| <fetch_var>
<substr_expr> ::=
SUBSTR ( <fetch_expr> .
<fetch_expr> ,
<fetch_expr> )
/*
* MAP STATEMENT
*/
<map_statements> ::=
<map_statement>
| <map_statement> <map_statements>
204
<map_statement> ::=
<attribute_name> = <map value> ;
| <attribute_name> = PRINTF ( <string> ,
<map_args> ) ;
<map_args> ::=
<map_value>
| <map_value> , <map args>
<map value> ::=
<constant>
| <keyword>
| <name_var>
| <value_var>
| <fetch_var>
/*
* VARIOUS
*/
<constant> ::=
<string>
<number>
e.g. hello, "hello"

12
<keyword> ::= $<atom>

<name_var> ::= $N<number>
<key_var> ::= $K<number>
e.g. $TARGET
e.g. $N12
e.g. $K12
<value_var> ::= $V<number>
e.g. $V5
<fetch_var> ::= $F<number>
e.g. $F2
<string> ::=<quoted_string>
| <atom>
<quoted_string> ::=
<atom> ::=
e.g. "sun", "a ""dog"" !"

e.g. target, C3000, LINKD_DOWN, in-out
205
206

The Tivoli Enterprise Console Logfile Format Editor is used to add new format
definitions of event messages and their mapping to Tivoli Enterprise Console
events for the Tivoli logfile event adapter and Windows adapters.
The format file of the logfile adapter and the rule base that supplies the BAROC
classes must reside on the local host. In general, all rule bases should reside on the
Tivoli Enterprise Console server. The Logfile Format Editor is included with the
Tivoli Enterprise Console server.
Configuring a format file for a logfile adapter

task.
Activity
Context
Required Role
Configure a logfile adapter
Event server
user
You can perform this task only from the Tivoli desktop.
Use the following steps to configure format file for a logfile adapter:
1. Select Configure Logfile from the context menu on the icon for the event
server. The Tivoli Enterprise Console product displays the Logfile Format
Editor window.
207
2. Select Open Format from the File menu to display the Select Format File
dialog box.
3. Enter the absolute path name of the directory that contains the logfile format
file in the Path Name text box. The logfile adapter format file is typically a
copy of the tecad_logfile.fmt file that resides in the adapter configuration files.
Note: Only one logfile format file can be edited at a time. There is typically
one logfile format file for each system and interpreter type (operating
system).
For information about using file browser dialogs, see the Tivoli Management
Framework Users Guide.
4. Click the Set Path button.
5. Select the logfile format file from the Files scrolling list.
6. Click the Set & Close button to open the specified logfile adapter format file
for editing and close the Select Format File dialog box.
208
7. Select the rule base you want to use from the Open Classes option of the File
menu.
Note: The Open Format and Open Classes menu items are not active for the
remainder of an editing session, because these files are only consulted
initially.
8. Select Open Logfile from the File menu to display the Select Log File dialog
box.
9. Specify the directory that contains the log file to read messages from in the
Path Name text box. You can optionally specify the host name where the file
resides by specifying the host name followed by a colon (:), then the file
name.
10. Select the log file from the Files scrolling list.
11. Click the Set Path button.
12. Click the Set & Close button to display a window similar to the following
example.
Note: The Open Logfile option of the File menu remains active throughout
an editing session. You can begin editing another logfile adapter format
file at any time.
13. From the Logfile Messages to be matched scrolling list, select the logfile
message to be matched. The following is an example of the dialog that is
209
displayed.
The event that the selected message would generate is displayed in the This
message matches scrolling text box. The Tivoli Enterprise Console product
automatically updates this information in the following steps.
Note: If the selected message does not map to an existing event, the following
message is displayed:
Message not bound
The Logfile Format Editor displays the current format string in the Message
being formatted scrolling text box. This string is the actual message with
variable components replaced by one of the following specifiers:
%s
Specifies a variable string.
%t
Specifies a variable date of the form 'MMM DD hh:mm:ss', for

example,Jun 26 10:23:02.
%s+
Specifies one or more variable strings that are separated by spaces.
%s*
Specifies zero or more strings separated by white space.
%n
Specifies a new line (CR). This applies only to the following adapters:
tecad_logfile_aix4-r1, tecad_logfile_hpux10, tecad_logfile_linux_ix86,
tecad_logfile_linux-ppc, tecad_logfile_linux-s390, tecad_logfile_solaris2,
and tecad_win.
Note: New line refers to a carriage return or a line feed as opposed to
the entire next line.
210
14. Click the Clear button to display the selected message in the Message being
formatted scrolling text box.
15. Select a portion of the message in the Message being formatted scrolling text
box by holding the left mouse button and dragging over a portion of the
message. The message portion that should be selected varies from message to
211
message. In the following example, the date portion is selected.
Note: If you accidentally select any unwanted spaces before or after the
preferred text, click the Clear button and repeat this step.
16. Click the Date button if the selected message text is a date.
OR
Click the String button if the selected message text is composed of one or
more strings.
OR
Click the FString button if the selected message text is a fixed-length string.
For example, if the specifier %2s%3s%4s %3s* the %4s+ is used, the string he
was here but the bird flew away produces the following attribute values:
v a = he
v b = was
v c = here
v d = but
v e = bird flew away
In the following example, the Date button was clicked. Notice that the
selected (date) portion of the message text has been replaced with a %t in the
212
Message being formatted scrolling text box.
17. Repeat steps 15 and 16 for the entire message text. After you have selected
and formatted all the message text, the message being formatted should be
composed of all %s or %t representations.
18. Click the Commit button to commit the message format.
19. Repeat steps 1 18 for each logfile message that is to be matched.
20. Click the Select Class button. The Logfile Format Editor displays the Select
Class window.
The Logfile Format Editor displays the defined event classes in the Available
List scrolling list.
21. Select the event class that the message is to be mapped to from the Available
List scrolling list.
213
OR
Select New Class from the Class menu to create a new BAROC class. The
Select BAROC file dialog is displayed.

a. Select the file that is to contain the new class from the Files scrolling list.
Note: When the event server starts, it reads the files in the order of the
files in the rule_base_directory/TEC_CLASSES/.load_classes file. If
you are defining a subclass of a parent class, be sure to save the
subclass in the file where the parent class is defined, or in a file that
is read after the file where the parent class is defined.
214
b. Click the Set & Close button to display the Edit Event Class window.
c. Enter the name for the new class in the Class Name text box.
d. Click the Add button to add a new attribute. The following is an example
of the dialog that is displayed:
215
a. Select the attribute name in the Attribute Name text field and press the
Enter key.
b. Select the attribute type from the Attribute Type drop-down list. The
attribute type can be String or Integer.
c. Select the default value for the attribute in the Default Value text box and
press the Enter key.
d. Select Yes from the Duplicate detection drop-down list to enable detection
of duplicate events.
OR
Select No from the Duplicate detection drop-down list to disable detection
of duplicate events.
e. Click the Set & Close button to save your changes and display the Select
Class dialog box.
f. Repeat steps be for each preferred attribute.
22. Click the Set & Close button to close the Select Class dialog and display the
selected event class in the Logfile Format Editor.
23. Click the Assign Attributes button to display the Assign Attribute Values
dialog box.
The current attribute mappings in the scrolling list are displayed at the top of
the dialog box. The map type for each attribute is listed in the Map Type
column. The map type is one of the following types:
None
Specifies that the attribute has no mapping defined; the adapter does
not set a value for the attribute. The event server can still assign a
default value to the attribute when the event is received.
Default
Specifies that the value of the attribute is computed by the logfile
adapter, possibly by using other attributes. Currently, only the origin
and hostname attributes can be set to Default. The origin address is
216
computed from the host name using the getbyhostname function. The
default host name is the host where the adapter is running.
Constant
Specifies that the value of the attribute is a constant string.
Variable
Specifies that the value of the attribute is a variable component of the
message.
Custom
Specifies that the value of the attribute is the output of a C printf-style
statement. Other attributes can be combined to form a composite
string.
24. From the scrolling list at the top of the dialog, select the attribute to be edited.
The current map values for the attribute are displayed in the Edit Assignment
group box.
25. Select the map type from the Map Type drop-down list.
Note: Selecting a map type of None deletes an attribute mapping. Changing a
map type from None to another map type creates a new attribute
mapping.
If you select a map type of Constant, a dialog similar to the following
example is displayed:
Enter the attribute value in the Enter a String text box. Type a value between
the double quotation marks and press the Enter key.
217
If you select a map type of Variable, a dialog similar to the following example
is displayed:
Select the preferred variable from the Select a Variable scrolling list.
If you select a map type of Custom, a dialog similar to the following example
is displayed:
218
a. Enter a printf-style format string in the Enter a Custom Message text box
and press the Return key. Only %s conversions are supported, and there
must be at least one %s conversion.
b. From the Available Attributes scrolling list, you must select an attribute as
the argument for each %s conversion. You can use the left and right arrow
buttons to move attribute arguments between the Available Attributes
scrolling list and the Selected Attributes scrolling list. You can use the up
arrow and down arrow buttons to reorder the attribute arguments in the
Selected Attributes scrolling list.
26. Click the Set & Close button to save your changes and close the Assign
Attribute Values dialog box.
27. Select Save from the File menu of the Logfile Format Editor window.
28. To distribute the format changes made in the previous step to an endpoint,
distribute the adapter configuration profile entry for this adapter using an
exact copy. Distribute the copy to the subscribing endpoints. For non-TME
adapters, run the logfile_gencds program for your adapter type to update the
cds file for the adapter with the changes made to the format file. When
complete, restart the adapter for the changes to become effective.
219
220
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 users 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 give 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, 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 might 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.
221
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
2Z4A/101
11400 Burnet Road
Austin, TX 78758 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 document 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 measurement 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 IBMs future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
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
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. You may copy,
modify, and distribute these sample programs in any form without payment to
222
IBM for the purposes of developing, using, marketing, or distributing application

programs conforming to IBMs application programming interfaces.
If you are viewing this information in softcopy form, the photographs and color
illustrations might not appear.
Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both: AIX, AS/400, FFST, First
Failure Support Technology, IBM, the IBM logo, Integrated Language Environment,
NetView, OS/2, OS/390, OS/400, Tivoli, the Tivoli logo, Tivoli Enterprise Console,
TME, and z/OS.
Microsoft, Windows, and Windows NT are registered trademarks of Microsoft
Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. 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, and service names may be trademarks or service marks
of others.
Notices
223
224
Index
Special characters
.baroc file
See BAROC files 23
.cfg file
See installation script 8
.conf file
See configuration file 9
.ed_diag_config file 12
.err file
See error file 26
.oid file
See object identifier file 8
.rls file
See rules file 8
$LCF_DATDIR 28
$TECADHOME 4
$VARBIND, built-in variables for
%s 210
' (single quotation mark) 10
132
A
acl attribute 5
Adapter Configuration Facility 11
advantages of 2
described 45
endpoints 45
profiles 45
role
ACF_glopol 45
ACF_polmod 45
ACF_readonly 46, 48, 49
ACF_rwdist 45
ACP 47
ACPM1 47
Profile1 48
adding
before or after scripts to records 69
environment variables to records 59
files to distribution lists of records 66
filter definitions to records 61
records 57
cloning 48
copying 50
copying records 73
creating 46
deleting 49
deleting records 75
disabling before or after scripts in records 70
distributing 56
editing records 58
enabling before or after scripts in records 70
finding records 76
locking records 76
modifying
before or after scripts to records 69
comments in records 72
default policy 52
environment variables in records 59
adapter configuration profile (continued)

modifying (continued)
filter definitions in records 63
UID and GID in records 72
validation policy 54
moving records 74
removing
before or after scripts from records 70
environment variables from records 60
files from distribution lists of records 67
filter definitions from records 66
setting as a managed resource 46
setting distribution defaults 50
sorting attributes 78
sorting records 77
specifying
adapter identifier name 73
unlocking records 76
adapter_host attribute 5
adapter, HP OpenView
installing from the command line 33
installing from the Tivoli desktop 33
uninstalling on managed node 41
upgrading from the command line 41
AdapterCdsFile keyword 10
AdapterErrorFile keyword 10
adapters
buffer filter 22
description 1
files, list 7
installing from the command line 33
installing non-TME 34
installing on endpoint 33
installing on managed node 33
locations, files 9
non-TME 1
sending events to the event server 1
startup errors 27
Tivoli Enterprise Console 3.8 enhanced, removing 44
TME 1
troubleshooting 28, 29
uninstalling HP Openview on managed node 41
uninstalling non-TME 42
uninstalling on endpoints 41
upgrading from the command line 41
adding
adapter configuration profile record 57
before or after scripts to adapter configuration profile
records 69
environment variables to adapter configuration profile
records 59
files to distribution lists of adapter configuration profile
records 66
filter definitions to adapter configuration profile
records 61
administrator attribute 5
administrators 5
alert code point, AS/400 84
alert filter, AS/400 84
ALRBRC.MBR 81
225
ALRCDS.MBR 81
ALRCFG.MBR 81
ALRRLS.MBR 81
APPEND_CLASSPATH keyword 10
APPEND_JVMPATH keyword 10
AS/400 alert adapter
alert filter 84
BAROC file 90
buffer files 82
CDS file 83
code pages 83
configuration file 82
configuring filters 84
deregistered filters 85
described 81
ENDTECADP command 88
event listing 92
existing alert filters 85
FETCH examples 83
files 81, 184
graphic character set 83
job queue 93
keywords, CDS file 83
message queues 82
multiple adapters 94
Name Server 93
POSTEMSG command 96
QTMETECA command 96
registering filters 85
routing alerts 85
save files 37
SELECT examples 83
severity levels, events 90
starting 85, 93
stopping 87
STRTECADP command 86
TCP/IP considerations 93
test mode and events 93
troubleshooting 92
uninstalling the adapter 43
AS/400 message adapter
attribute defaults 110
CDS file 101
commands 113
described 99
event listing 110
files 99, 184
FTP session 113
message queues 113
Name Server 111
save files 37
start up program, changing 112
starting 105, 112
stopping 107
TCP/IP considerations 111
test mode and events 111
troubleshooting 111
uninstalling the adapter 43
as400msg.baroc file 110
ASCII log files 1
attributes
acl 5
adapter configuration profile, sorting
adapter_host 5
adapter-specific
AS/400 message adapter 110
226
attributes (continued)
adapter-specific (continued)
NetWare adapter 118
OpenView adapter 127, 130, 134
OS/2 adapter 141
SNMP adapter 147
UNIX logfile adapter 159
Windows event log adapter 178
administrator 5
base event 4
cause_date_reception 5
cause_event_handle 5
credibility 5
date 5
date_reception 5
event_handle 5
format 4
fqhostname 5
hostname 5
list of 5
msg 5
msg_catalog 5
msg_index 5
num_actions 5
origin 5
overview 4
repeat_count 5
server_handle 6
server_path 6
severity 6
source 6
status 7
sub_origin 7
sub_source 7
78
backing up
object database 40
backup
servers 16
backup copies
CFG_ALERT 81
CFG_MSG 100
BAROC files
adapter-specific
AS/400 alert adapter 90
NetWare adapter 118
OpenView adapter 133
OS/2 adapter 141
SNMP adapter 146
attributes list 4
class names in configuration files 10
description 23
example 23
root.baroc 6, 7
superclass 4
base event attributes 4
before or after script
adding to adapter configuration profile records 69
disabling in adapter configuration profile records 70
enabling in adapter configuration profile records 70
modifying to adapter configuration profile records 69
removing from adapter configuration profile records 70
blank spaces 10
books
see publications viii
BufEvtMaxSize keyword 8, 11
BufEvtPath keyword 11
buffer file 82
buffer files 11
buffer files, AS/400 100
buffer filters 22
BufferEvents keyword 11, 22
BufferFlushRate keyword 12
C
cache
endpoint adapters 11
filtering 13
keywords 11, 12
path 11
rate to send events 12, 14
cache, event
description 8
file format 8
size 11
cause events 5
cause_date_reception attribute 5
cause_event_handle attribute 5
CCSID 83, 101, 102
CDS file keywords
$ACTION_CODE 83
$ACTIONS 83
$ADAPTER_CORREL 83
$ADAPTER_HOST 84
$ADAPTER_HOST_SNANODE 84
$ALERT_CDPT 84
$ALERT_ID 84
$ARCH_TYPE 84
$BLOCK_ID 84
$CAUSES 84
$DATE 84
$DETAILED_DATA 84
$EVENT_CORREL 84
$EVENT_TYPE 84
$HOSTNAME 84
$INCIDENT_CORREL 84
$MSG 84
$ORIGIN 84
$PRODUCT_ID 84
$SELF_DEF_MSG 84
$SEVERITY 84
$SOURCE 84
$SUB_ORIGIN 84
$ADAPTER_HOST 102
$ALERT_OPTION 102
$ARG1 - $ARG8 105
$DATA_CCSID_CONVERT_STATUS
$DATA_CCSID_RETURNED 102
$DATE 102
$HOSTNAME 103
$MSG 103
$MSG_FILE_LIBRARY 103
$MSG_FILE_NAME 103
$MSG_HELP 103
$MSG_ID 103
$MSG_KEY 103
102
CDS file keywords (continued)

AS/400 message adapter (continued)
$MSG_LIBRARY_USED 103
$MSG_SEVERITY 103
$MSG_TYPE 103
$ORIGIN 103
$SEND_DATE 103
$SEND_JOB 104
$SEND_JOB_NUMBER 104
$SEND_PROGRAM_NAME 104
$SEND_TIME 104
$SEND_USER_PROFILE 104
$SEVERITY 104
$SOURCE 104
$SUB_ORIGIN 104
$SUB_SOURCE 104
$TEXT_CCSID_RETURNED 104
OpenView adapter
$ADAPTER_HOST 132
$AGENT_ADDR 132
$COMMUNITY 132
$ENTERPRISE 132
$SOURCE_TIME 132
$SPECIFIC 132
$TYPE 132
$VARBIND 132
$VARBIND variables 132
$VB_NUM_VARS 132
SNMP adapter
$ADAPTER_HOST 145
$AGENT_ADDR 145
$COMMUNITY 144
$ENTERPRISE 144
$SOURCE_ADDR 132, 144
$SOURCE_TIME 144
$SPECIFIC 144
$TYPE 144
$VARBIND 145
$VB_NUM_VARS 145
CDS files
adapter-specific
OpenView adapter 131, 132
SNMP adapter 144
example 25
format files 24
location 9, 10
overview 25
syntax 202
CFG_ALERT file 81
CFG_MSG file 100
Change Alert Action Entry command 85
Change Network Attributes command 85
Channels keyword 19
CHGALRACNE command 85
CHGNETA command 85
circuit tracing, OpenView adapter 128
class definition statement
FETCH statement 200
MAP statement 201
MAP_DEFAULT statement 201
SELECT statement 199
class name
Index
227
class name (continued)

NetWare adapter 118
OS/2 adapter 141
SNMP adapter 146
class, description 4
cloning, adapter configuration profile 48
code pages
AS/400 101
coded character set identifier 83, 101
codeset directory 4
cold start
SNMP adapter 154
commands
AS/400 113
odstat 164
syntax xi
wbkupdb 40
wcrtprf 47, 48, 49
wdel 49
wdelac 76
wdeldir 75
wdistrib 56, 57
wep ls 28
wgetprf 51
winstall 33
wlookup 47, 48
wpatch 41
wputpol 54, 56
wsetpr 46
wtdumprl 164
comments, modifying in adapter configuration profile
records 72
condition, printer 163
configuration file keywords
AdapterCdsFile 82
AdapterType 82
BufEvtName 82, 100
Filter 82, 85
FilterDataQueue 82, 85
JobDescription 83
LanguageID 83
ProcessExistingAlerts 83
ServerCCSID 83
AdapterCdsFile 100
AdapterType 100
JobDescription 100
LanguageID 100
MsgQueue 100
PollInterval 100
ProcessExistingMsgs 101
ServerCCSID 101
common
AdapterCdsFile 10
AdapterErrorFile 10
APPEND_CLASSPATH 10
APPEND_JVMPATH 10
BufEvtMaxSize 11
BufEvtPath 11
BufferEvents 11
BufferFlushRate 12
228
configuration file keywords (continued)

common (continued)
Channels 19
ConnectionMode 12
ed_diag_config_file 12
Filter 12
FilterCache 13
FilterMode 13
FQHostname 13
getport_timeout_seconds 14
getport_timeout_usec 14
getport_total_timeout_ usec 14
getport_total_timeout_seconds 14
LogFileName 14
LogLevel 14
MaxPacketSize 14
NO_UTF8_CONVERSION 14
Port 20
Pre37Server 3, 15
Pre37ServerEncoding 4, 15
PREPEND_CLASSPATH 15
PREPEND_JVMPATH 15
RetryInterval 16
ServerLocation 16, 20
ServerPort 17
StateCorrelationCleaningInterval 18
StateCorrelationConfigPath 18
StateCorrelationMaxFileSize 18
StateCorrelationTotalSize 18
TestMode 19
TraceFileName 19
TraceLevel 19
TransportList 19
UseStateCorrelation 21
WIDTHSTRMEANING 21
NetWare adapter
Log Sources 116
PollInterval 117
PreFilter 117
PreFilterMode 117
OpenView adapter
AdapterSpecificFile 130
HPOVFilter 130
WellBehavedDaemon 131
OS/2 adapter
LogSources 139
UnmatchLog 140
SNMP adapter
AdapterSpecificFile 144
SNMP_PORT 144
SNMP_TRAP 144
UNIX logfile adapter
LogSources 157
NewLogBasedOn 158
PollInterval 158
ProcessPriorityClass 158
UnmatchLog 158
Windows event log adapter
BufferMaxSize 168
HostnameIsAdapterHost 168
LanguageID 168
LogSources 168
NewLogBasedOn 169
NumEventsToCatchUp 169
PollInterval 170
PreFilter 170
PreFilterMode 170
configuration file keywords (continued)

Windows event log adapter (continued)
ProcessDisablePriorityBoost 170
ProcessPriorityClass 171
SpaceReplacement 171
UnmatchLog 171
WINEVENTLOGS 171
configuration files
adapter-specific
AS/400 message adapter 100, 113
OS/2 adapter 139
SNMP adapter 144
adapter, modifying behavior 68
example 9
format 9
location 9
configuring adapters
logfile 207
NetWare adapter 116
OS/2 adapter 139
SNMP adapter 144
ConnectionMode keyword 12
connections
connection-oriented 2
keywords 12, 16
retry 16
using interprocess communication mechanisms
using oserv services 1
conventions
command syntax xi
typeface x
copying
adapter configuration profile record 73
adapter configuration profiles 50
Create Data Queue command 85
creating
adapter configuration profile 46
credibility attribute 5
CRTDTAQ command 85
CRTPF command 111
CRTSRCPF command 111
customer support
see software support ix
D
daemon, portmapper 17, 20
daemons
syslogd 155
date attribute 5
date_reception attribute 5
date, events 5
debugging
See troubleshooting 26
deleting
adapter configuration profile records
directory names, notation x
75
disabling
before or after scripts in adapter configuration profile
records 70
before scripts in adapter configuration profile records 70
distributing an adapter configuration profile 56
distribution defaults, setting adapter configuration profile 50
duplicate events 5
duration attribute 5
ed_diag_config_file keyword 12
editing, adapter configuration profile record 58
effect events 5
eif.log file 14
enabling
before or after scripts in adapter configuration profile
records 70
encoding, UTF-8 3, 14, 15, 21, 187
endpoint adapters
cache 11
endpoint gateway
See gateway, Tivoli Management Framework 2
endpoints
Adapter Configuration Facility requirement 45
description 2
getting events to the event server from 2
installing adapters on 33
modifying behavior of 68
TME adapters for 2
uninstalling adapters on 41
ENDTECADP command, AS/400 alert adapter 88
ENDTECADP command, AS/400 message adapter 108
English, as secondary language for AS/400 39
environment variables
modifying in adapter configuration profile records 59
notation x
TIVOLI_COMM_DIR 8
error files
adapter-specific
NetWare adapter 115
OS/2 adapter 139
SNMP adapter 145
description 26
location 9, 10
error messages 10
event classes
names 10
event correlation
example 129
OpenView NNM 6 126
testing with OpenView NNM 6 128
event server
getting events to, from a managed node 3
getting events to, from a non-TME adapter 3
getting events to, from an endpoint 2
performance 2
primary and secondary 2
remote, sending events to 1
sending events to 1
event servers
connections, when stopped or started 16
Index
229
event servers (continued)

port number 17
event tracing 26
event_handle attribute 5
events
attributes 4
buffer 22
buffer file 11
cause 5
class 4
date 5
duplicates 5
effect 5
filter 21
getting to the event server from a managed node 3
getting to the event server from a non-TME adapter 3
internationalization support 3
list 159
sending to the event server 1
status 7
time 5
expressions, for filtering 21
F
failures, systems 22
FETCH statement
description 200
examples 83, 101
files
.ed_diag_config 12
adapter-specific
NetWare adapter 115
OS/2 adapter 139
SNMP adapter 143
Windows event log adapter 167, 177
adapters 7
ALRBRC.MBR 81
ALRCDS.MBR 81
ALRCFG.MBR 81
ALRRLS.MBR 81
as400msg.baroc 99
BAROC 10, 23
buffer 11
cache 8
CDS 25
eif.log 14
error 26
for logging and tracing 12
format 24
init.tecad_logfile
description 157
syntax for using 156
init.tecad_snmp 143
initial 27
install.exe 139
installation script 8
log_default.rls 157, 163
logfile_gencds 157, 159
mail alias 163
MSGBRC.MBR 99
MSGCDS.MBR 99
MSGCFG.MBR 99
230
files (continued)
nwgencds.nlm 115
object identifier 8
ov_default.rls 130
postmsg.nlm 115
readme, OS/2 139
registration 8
rules 8, 23
security_default.rls 163
tec_uninstal.cmd 139
tecad_hpov 130
tecad_hpov.baroc 130
tecad_hpov.cds 130, 133
tecad_hpov.cfg 129
tecad_hpov.conf 130
tecad_hpov.err 130, 133
tecad_hpov.lrf 130, 133
tecad_hpov.oid 130
tecad_hpov.sh 130
tecad_logfile 157
tecad_logfile.baroc 157, 159
tecad_logfile.cds 157, 159
tecad_logfile.cfg 157
tecad_logfile.conf 157
tecad_logfile.err 157, 159
tecad_logfile.fmt 157, 158, 159, 164
tecad_snaevent.baroc 90
tecad_snmp 143
tecad_snmp.baroc 143
tecad_snmp.cds 143
tecad_snmp.cfg 143
tecad_snmp.conf 143
tecad_snmp.err 143, 145
tecad_snmp.oid 143
tecad_win.baroc 168
tecad_win.conf 167
tecad_win.err 168
tecad_win.exe 167
tecad_win.fmt 167, 173
tecadcfg.cmd 139
tecadini.sh 139
tecadnw4.brc 115
tecadnw4.cds 115
tecadnw4.cnf 115
tecadnw4.err 115
tecadnw4.nlm 115
tecados2.baroc 139
tecados2.cds 139
tecados2.conf 139
tecados2.err 139
tecados2.exe 139
tecados2.fmt 139
tecadrm.sh 139
tecadwins.exe 167
tecinst_win.cmd 167
filter definition
modifying in adapter configuration profile records 63
Filter keyword 12
FilterCache keyword 13
filtering events
buffer 22
cache 13, 22
examples 22, 23
keywords 12, 13
overview 21
filtering events (continued)

prefilter 116, 172
regular expressions 21
system failures 22
FilterMode keyword 13
finding adapter configuration profile records
format files
activating changes to 195
adapter-specific
NetWare adapter 117
OS/2 adapter 140
UNIX logfile adapter 158, 189
Windows event log adapter 173, 191
described 187
description 24
example 24
modifying 187
specifications 187
fqhostname attribute 5
FQHostname keyword 13
FTP session, AS/400 113
installing adapters (continued)

non-TME 34
winstall command 33
instances of UNIX logfile adapter, running multiple
instances of Windows event log adapter, running
multiple 177
interfaces
non-Tivoli 1
Tivoli 1
internationalization
filtering events 21
format files, encoding 187
messages and postemsg 29
support for events 3
UTF-8 encoding 3, 14, 15
interprocess communication mechanisms 1
IP sockets 1, 3
76
J
job queue, AS/400 alert adapter
G
gatelog file 28
gateway, IBM Tivoli Enterprise Console
endpoints and events 2
gateway, Tivoli Enterprise Console
description 2
gateway, Tivoli Management Framework 2
gateways, IBM Tivoli Enterprise Console
connections 12
getport_timeout_seconds keyword 14
getport_timeout_usec keyword 14
getport_total_timeout_ usec keyword 14
getport_total_timeout_seconds keyword 14
GID, modifying in adapter configuration profile records
graphic character set
AS/400 101
H
hardware requirements, installation
hostname attribute 5
hosts, for adapters 5
HP OpenView adapter
See OpenView adapter 125
HPOVFilter attribute 127
32
I
init.tecad_logfile 157
command syntax 156
init.tecad_snmp 143
initial files 27
install.exe 139
installation requirements
hardware 32
software 32
installation script 8
installing adapters
adapter files 35
endpoint adapter 33
English as secondary language, AS/400
NetWare logfile adapter 39
156
93
K
keywords
See CDS file keywords 82
See configuration file keywords
82
72
lanalert entry, SNMP adapter 152

language
English as secondary for AS/400 39
primary, AS/400 39
language support packs and postemsg 29
last.cfg file 28
LCF transport type 19
lcfd process 2, 28
lcfd.log file 28
list events 159
localization directories 4
locking, adapter configuration profile records 76
log files, ASCII 1
log_default.rls 157
logfile adapter
configuring 207
operating system-specific adapter types 57
Logfile Format Editor 207
logfile_gencds 157, 219
LogFileName keyword 14
LogLevel keyword 14
logs
messages 14
39
mail alias
tec_print 163
tec_security 164
managed node, installing HP Openview adapter on 33
managed node, uninstalling HP OpenView adapter on 41
managed nodes
events sent to event server 3
uninstalling HP OpenView adapters 41
Index
231
managed resources, setting adapter configuration profiles

as 46
manuals
see publications viii
MAP statement
description 201
examples 101
map type 216
MAP_DEFAULT statement 201
mappings, format file 191, 195
MaxPacketSize keyword 14
maxsz, cache 8
message logs 12, 14
message queues, AS/400 82, 100
messages, events 5
modifying
adapter configuration file behavior 68
adapter configuration profile default policy 52
adapter configuration profile validation policy 54
before or after scripts to adapter configuration profile
records 69
comments in adapter configuration profile records 72
environment variables in adapter configuration profile
records 59
filter definitions in adapter configuration profile
records 63
UID and GID in adapter configuration profile records 72
variable expansion behavior 68
moving, adapter configuration profile records 74
msg attribute 5
msg_catalog attribute 5
msg_index attribute 5
MSGBRC.MBR 99
MSGCDS.MBR 99
MSGCFG.MBR 99
multiple instances, UNIX logfile adapter 156
multiple instances, Windows event log adapter 177
N
Name Server
NetWare adapter
BAROC file 118
error file 115
event listing 118
files 115, 184
loading (starting) 122
prefiltering events 116
troubleshooting 123
unloading (stopping) 123
network traffic 1
newsgroups ix
NO_UTF8_CONVERSION keyword
non-TME adapters
description 1
event delivery 3
installing 34
troubleshooting 29
uninstalling 42
notation
environment variables x
path names x
typeface x
232
num_actions attribute
nwgencds.nlm 115
O
object database
backing up 40
object identifier (OID) files
description 8
tecad_hpov.oid, OpenView adapter 132
tecad_snmp.oid, SNMP adapter 145
online publications, accessing viii
OpenView adapter
BAROC file 133
CDS file 132
circuit tracing 128
cold start 133
described 125
error file 133
event correlation with NNM 6 126, 128
event listing 133
files 129, 184
ovspmd process 125
ovtrapd process 125
starting 133
stopping 133
stream tracing 128
testing tool 128
traps 136
troubleshooting 137
OpenView NNM version, determining 125
ordering publications viii
origin attribute 5
OS/2 adapter
BAROC file 141
class name 141
described 139
error file 139
files 184
format file 140
starting 140
stopping 141
troubleshooting 142
oserv 1, 3
ov_default.rls 130
OVsnmpEventOpen filter value 127
ovspmd process, OpenView adapter 125
ovtrapd process 125
P
14
path names, notation x

performance, event server 2
Port keyword 20
port number, for event server
portmapper daemon 17, 20
ports
port mapper 14
re-sending UDP calls 14
postemsg command 29, 96
postmsg.nlm 115
Pre37Server keyword 3, 15
17
Pre37ServerEncoding keyword 4, 15
prefiltering events
NetWare adapter 116
PREPEND_CLASSPATH keyword 15
PREPEND_JVMPATH keyword 15
printer condition 163
profiles
Adapter Configuration Facility 45
See adapter configuration profile 46
publications
accessing online viii
ordering viii
Q
QPGMR 94
QSECOFR 94
QSTRUPPGM 94
QSYS 94
QSYSOPR 99
QSYSWRK 93
QTECALERT 84, 85
QTMETECA command 96
QTMETECA02 library 81
R
readme, OS/2 139
record
adding
before or after scripts to an adapter configuration
profile 69
environment variables to an adapter configuration
profile 59
files to distribution lists for an adapter configuration
profile 66
filter definitions to an adapter configuration profile 61
copying an adapter configuration profile 73
deleting an adapter configuration profile 75
editing an adapter configuration profile 58
enabling and disabling before and scripts in an adapter
configuration profile 70
finding an adapter configuration profile 76
modifying
before or after scripts to an adapter configuration
profile 69
environment variable in an adapter configuration
profile 59
filter definitions in an adapter configuration profile 63
GID in an adapter configuration profile 72
UID in an adapter configuration profile 72
moving an adapter configuration profile 74
removing
before or after scripts from an adapter configuration
profile 70
environment variables from an adapter configuration
profile 60
files from an adapter configuration profile 67
filter definitions from an adapter configuration
profile 66
sorting adapter configuration profile records 77
specifying
reference information, NetWare adapter 115
registration files
description 8
registry variables
ApplicationEventsProcessed 174
ApplicationEventsProcessedTimeStamp 174
DirectorEventsProcessed 174
DirectorEventsProcessedTimeStamp 174
DNSEventsProcessed 174
DNSEventsProcessedTimeStamp 174
FileReplicationEventsProcessed 174
FileReplicationEventsProcessedTimeStamp 175
PollingInterval 175
SecurityEventsProcessed 175
SecurityEventsProcessedTimeStamp 175
SystemEventsProcessed 175
SystemEventsProcessedTimeStamp 175
TECInstallPath 175
regular expressions, for filtering 21
removing
before or after scripts from adapter configuration profile
records 70
environment variables from adapter configuration profile
records 60
files from distribution lists of adapter configuration profile
records 67
filter definitions from adapter configuration profile
records 66
repeat_count attribute 5
RetryInterval keyword 16
roles, authorization 5
root.baroc file 6, 7
rules
description 8, 23
engine 6
example 23
SNMP adapter 148
S
secondary language, AS/400 83, 100
SELECT statement
description 199
examples 83, 101
server configuration, UNIX logfile adapter 155
server_handle attribute 6
server_path attribute 6
ServerLocation keyword 16, 20, 82
ServerPort keyword 17
services, oserv 1
setting
adapter configuration profile distribution defaults 50
adapter configuration profiles as managed resources 46
severities, event
adapter-specific
NetWare adapter 118
OS/2 adapter 141
SNMP adapter 146
attribute 6
severity attribute 6
single quotation mark 10
Index
233
slot
See attribute 4
SNA alerts 81
SNMP adapter
BAROC file 146
CDS file 144
cold start 154
default rules 148
described 143
error file 145
event listing 147
files 143, 184
lanalert entry 152
object identifier (OID) file 145
restarting 146
starting 145, 146
stopping 145, 146
trapd daemon 143
traps 148
troubleshooting 154
warm start 146
SOCKET transport type 19
sockets 1, 3, 19
software requirements, installation 32
software support, contacting ix
sorting
adapter configuration profile attributes 78
adapter configuration profile records 77
source
attribute 6
description 1
spaces, blank 10
specifying adapter identifier name 73
starting adapters
AS/400 alert adapter 85, 93
AS/400 message adapter 105, 112
errors 27
OS/2 adapter 140
SNMP adapter 145
state correlation
cache 11, 18
cleanup 18
keywords 14
XML 18
StateCorrelationCleaningInterval keyword 18
StateCorrelationConfigPath keyword 18
StateCorrelationMaxFileSize keyword 18
StateCorrelationTotalSize keyword 18
statements
FETCH 200
MAP 201
MAP_DEFAULT 201
SELECT 199
status attribute 7
stopping adapters
OS/2 adapter 141
SNMP adapter 146
234
stopping adapters (continued)

stream tracing, OpenView adapter 128
STRTECADP command 86, 106
sub_origin attribute 7
sub_source attribute 7
subvectors 84
summary, events 5
superclass, BAROC file 4
syntax
init.tecad_logfile command 156
syntax for commands xi
syntax, CDS file 202
syslogd daemon 155
system failures 22
T
Tcl expressions, for filtering 21
TCP/IP
host table 93, 111
tec_recv_agent_port entry 17
tec_uninstal.cmd 139
tecad_hpov 130
tecad_hpov.baroc 130
tecad_hpov.cds 130, 131
tecad_hpov.cfg 129
tecad_hpov.conf 130
tecad_hpov.err 130
tecad_hpov.lrf 130
tecad_hpov.oid 130
tecad_hpov.sh 130
tecad_logfile 157
tecad_logfile.baroc 157
tecad_logfile.cds 157
tecad_logfile.cfg 157
tecad_logfile.conf 157
tecad_logfile.fmt 157
tecad_logfile.fmt file 208
tecad_snaevent.baroc file 90
tecad_snmp 143
tecad_snmp.baroc 143, 147, 149
tecad_snmp.cds 143, 144, 152
tecad_snmp.cfg 143
tecad_snmp.conf 143
tecad_snmp.err 143
tecad_snmp.oid 143
tecadcfg.cmd 139
tecadini.sh 139
tecadnw4.brc 115
tecadnw4.cds 115
tecadnw4.cnf 115
tecadnw4.err 115
tecadnw4.nlm 115, 121
tecados2.baroc 139
tecados2.cds 139
tecados2.conf 139
tecados2.err 139
tecados2.exe 139
tecados2.fmt 139
tecadrm.sh 139
testing tool, OpenView adapter 128
TestMode keyword 19, 93, 111
time, events 5
Tivoli Availability Intermediate Manager 17

Tivoli Enterprise Console, description 1
Tivoli Event Integration Facility 4
Tivoli Management Framework 5
Tivoli Software Information Center viii
TIVOLI_COMM_DIR 8
TIVOLIHOME variable 11, 14
TME adapters
description 1
event delivery 3
for endpoints 2
TME transport type 19
trace logs 12, 19
TraceFileName keyword 19
TraceLevel keyword 19
tracing
circuit, OpenView adapter 128
event 26
stream, OpenView adapter 128
traffic, network 1
transport type 19
TransportList keyword 19
trapd daemon, SNMP adapter 143
traps
SNMP adapter 148
troubleshooting
all adapters 28
description 26
endpoint adapters 28
managed node adapters 28
NetWare adapter 115, 123
non-TME adapters 29
OpenView adapter 133, 137
OS/2 adapter 142
SNMP adapter 154
typeface conventions x
U
UDP calls 14
UID, modifying in adapter configuration profile records 72
uninstalling adapters
AS/400 adapters 43
non-TME 42
on endpoint 41
OpenView adapters on managed node 41
Tivoli Enterprise Console 3.8 enhanced, removing 44
UNIX log file adapter
files 185
UNIX logfile adapter
BAROC file 159
CDS file 159
configuring the adapter 157
default rules 163
description 155
error file 159
files 157
format file 158, 189
server configuration 155
UNIX logfile adapter (continued)

starting 155
stopping 156
troubleshooting 164
unlocking, adapter configuration profile records
upgrading adapters
wpatch command 41
UseStateCorrelation keyword 21
UTF-8 encoding 3, 14, 15, 21, 187
76
V
variable expansion, modifying behavior of
variables
built-in for $VARBIND 132
environment
notation for x
TIVOLI_COMM_DIR 8
TIVOLIHOME 11, 14
68
W
warm start, SNMP adapter 146
wbkupdb 40
wcrtprf 49
wdelac 76
wdistrib 57
wep ls command 28
wgetprf 51
WIDTHSTRMEANING keyword 21
Windows event log adapter
BAROC file 178
Control Panel Services Applet 176
described 167
error file 168
event listing 178
files 167, 185
format file 167, 191
prefiltering log events 172
registry variables 173
spaces, replaced with underscores 171
stopping 177
TCP/IP 167
tecad_win command 180
troubleshooting the adapter 182
winstall command 33
wlookup 47
wpatch command 41
wpostemsg command 29
wputpol 54
wsetpr 46
Index
235
236

Program Number: 5698-TEC
Printed in U.S.A.
SC32-1242-00

Ecoamst

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Ecoamst

Hochgeladen von

Copyright:

Verfügbare Formate

IBM Tivoli Enterprise Console

IBM Tivoli Enterprise Console

First Edition (August 2003)

Chapter 1. Introduction to adapters . . . 1

Chapter 2. Installing adapters . . . . . 31

Installing on UNIX operating systems . . .

Chapter 3. Adapter Configuration

Getting a new copy of an adapter configuration

IBM Tivoli Enterprise Console: Adapters Guide

Modifying a before or after script in an adapter

Chapter 4. AS/400 alert adapter . . . . 81

Chapter 5. AS/400 message adapter . . 99

NetWare logfile adapter reference information

Chapter 6. NetWare logfile adapter

Chapter 7. OpenView adapter . . . . 125

Chapter 8. OS/2 adapter . . . . . . . 139

Chapter 9. SNMP adapter . . . . . . 143

Chapter 10. UNIX logfile adapter . . . 155

Chapter 11. Windows event log

Appendix A. Files shipped with

Activating changes made with a format file .

Appendix C. Class definition

Format file location .

IBM Tivoli Enterprise Console: Adapters Guide

Appendix D. Logfile Format Editor

Configuring a format file for a logfile adapter

Appendix B. Format file reference . . 187

About this guide

Who should read this guide

IBM Tivoli Enterprise Console library

Copyright IBM Corp. 2003

Provides an overview of the IBM Tivoli Enterprise Console product and

Accessing publications online

IBM Tivoli Enterprise Console: Adapters Guide

Contacting software support

From the Tools menu, click Internet Options.

Use these instructions for a Netscape Navigator browser.

About this guide

Conventions used in this guide

Words defined in text

Operating system-dependent variables and paths

IBM Tivoli Enterprise Console: Adapters Guide

Command line syntax

Identifies an optional argument. Arguments not enclosed in brackets are

Delimits a set of mutually exclusive arguments when one of the arguments

About this guide

IBM Tivoli Enterprise Console: Adapters Guide

Chapter 1. Introduction to adapters

Copyright IBM Corp. 2003

connection should be a two-way connection. If you are sending events from

How adapters on endpoints send events

IBM Tivoli Enterprise Console: Adapters Guide

How adapters on managed nodes send events

How non-TME adapters send events

Internationalization support for events

Pre37ServerEncoding configuration file options are provided. See Keywords on

Event information and attributes

IBM Tivoli Enterprise Console: Adapters Guide

(BAROC) file. An adapter can also contain adapter-specific or user-defined

The list of authorization roles that an administrator uses to modify

The host on which the adapter is running.

The administrator who acknowledged or closed the event.

The cause_date_reception attribute is used to link an effect event to