tivoli event integration facility:...

Tivoli Event Integration Facility

ReferenceVersion 3.9

SC32-1241-00

��

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

First Edition (August 2003)

This edition applies to version 3, release 9, of IBM Tivoli Enterprise Console (product number 5698-TEC) and to allsubsequent 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 Contractwith IBM Corp.

Contents

About this guide . . . . . . . . . . . vWho should read this guide . . . . . . . . . vPublications . . . . . . . . . . . . . . v

IBM Tivoli Enterprise Console library . . . . . viPrerequisite publications . . . . . . . . . viRelated publications . . . . . . . . . . viAccessing publications online . . . . . . . viiOrdering publications . . . . . . . . . . vii

Contacting software support . . . . . . . . viiParticipating in newsgroups . . . . . . . . viiiConventions used in this guide . . . . . . . viii

Typeface conventions . . . . . . . . . . viiiOperating system-dependent variables and paths ix

Chapter 1. Overview of the Tivoli EventIntegration Facility . . . . . . . . . . 1Overview of concepts . . . . . . . . . . . 1

Events . . . . . . . . . . . . . . . 2Adapters . . . . . . . . . . . . . . 3Event classes . . . . . . . . . . . . . 4Configuration files . . . . . . . . . . . 4Event server . . . . . . . . . . . . . 5Event filtering . . . . . . . . . . . . . 5Rules . . . . . . . . . . . . . . . . 6

Use of the Java API and the C API . . . . . . . 6Summary of creating event sources . . . . . . . 6

Chapter 2. Installing the Tivoli EventIntegration Facility . . . . . . . . . . 7Preparing for installation . . . . . . . . . . 7Installing . . . . . . . . . . . . . . . 7Migrating adapters based on 3.7.1 or previous EventIntegration Facility . . . . . . . . . . . . 8

Adapters created with the C API . . . . . . 8Adapters created with the Java API. . . . . . 8

Chapter 3. Event transport . . . . . . 11Event delivery methods . . . . . . . . . . 11

Connection options . . . . . . . . . . . 11Transport options . . . . . . . . . . . 11Shell script and test options . . . . . . . . 12

Event reception for applications . . . . . . . 12Sending events through firewalls . . . . . . . 13Event delivery when systems fail . . . . . . . 13

Activating the cache . . . . . . . . . . 14Configuring backup servers to deliver events . . 14Using the portmapper keywords . . . . . . 16Configuring a reception application built withthe C API . . . . . . . . . . . . . . 16

Chapter 4. Building an adapter . . . . 19Identifying events to monitor . . . . . . . . 20Defining the source. . . . . . . . . . . . 20Defining event classes . . . . . . . . . . . 21

Selecting event delivery methods . . . . . . . 21Programming the adapter . . . . . . . . . 21

Upgrading existing adapters. . . . . . . . 22Configuration file APIs . . . . . . . . . 23Communications APIs . . . . . . . . . . 23Data transfer APIs . . . . . . . . . . . 23Sample adapter code . . . . . . . . . . 23Special considerations for Windows . . . . . 23Compiling the adapter. . . . . . . . . . 24Compiling the adapter built with the C API . . 25Compiling the adapter built with the Java API . 25Linking the adapter built with the C API . . . 25

Installing, configuring, and testing the adapter . . 27Running adapters built with the Event IntegrationFacility Java API. . . . . . . . . . . . . 28Configuring adapters for international environments 28

Chapter 5. Filtering events at thesource . . . . . . . . . . . . . . . 31Filtering with configuration files . . . . . . . 31

Filtering events when systems fail . . . . . . 32Example . . . . . . . . . . . . . . 32Regular expressions in filters . . . . . . . 32

Filtering with state correlation . . . . . . . . 33Activating state machines. . . . . . . . . 33

Chapter 6. Troubleshooting . . . . . . 35Message logs . . . . . . . . . . . . . . 35Trace logs . . . . . . . . . . . . . . . 35Performance and availability . . . . . . . . 36

Event reception connection parameters . . . . 36Common problems and scenarios . . . . . . . 36

Building and running adapters . . . . . . . 37Making connections to the event server . . . . 38Sending events . . . . . . . . . . . . 38

Appendix A. Application programminginterfaces . . . . . . . . . . . . . 41C language API . . . . . . . . . . . . . 41

tec_agent_getenv . . . . . . . . . . . 42tec_agent_init. . . . . . . . . . . . . 43tec_create_EIF_handle . . . . . . . . . . 44tec_create_handle . . . . . . . . . . . 45tec_create_handle_c. . . . . . . . . . . 46tec_create_handle_r . . . . . . . . . . . 48tec_destroy_handle . . . . . . . . . . . 49tec_errno . . . . . . . . . . . . . . 50tec_get_event . . . . . . . . . . . . . 51tec_put_event. . . . . . . . . . . . . 52tec_register_callback . . . . . . . . . . 53

Utilities for the C API . . . . . . . . . . . 54ed_scan_get_n . . . . . . . . . . . . 55ed_scan_n . . . . . . . . . . . . . . 56ed_sleep . . . . . . . . . . . . . . 57

Java language API . . . . . . . . . . . . 58

© Copyright IBM Corp. 2003 iii

disconnect . . . . . . . . . . . . . . 59getConfigVal . . . . . . . . . . . . . 60onMessage . . . . . . . . . . . . . 61receiveEvent . . . . . . . . . . . . . 62registerListener . . . . . . . . . . . . 63sendEvent . . . . . . . . . . . . . . 64TECAgent . . . . . . . . . . . . . . 65TECEvent . . . . . . . . . . . . . . 66

Appendix B. Keywords forconfiguration files . . . . . . . . . . 67

Keywords . . . . . . . . . . . . . . . 67

Notices . . . . . . . . . . . . . . 79Trademarks . . . . . . . . . . . . . . 81

Index . . . . . . . . . . . . . . . 83

iv Tivoli Event Integration Facility: Reference

About this guide

The Tivoli® Event Integration Facility is an event distribution and integration pointfor the event console. With the Tivoli Event Integration Facility toolkit you canbuild event adapters and integrate them into the IBM® Tivoli Enterprise Console®

environment.

IBM Tivoli Enterprise Console adapters are the integration link. Adapters collectevents, perform local filtering, translate relevant events to the proper format for theevent console, and forward these events to the event server.

A variety of adapters for systems, Tivoli software applications, and third-partyapplications are available. To monitor a source (such as a third-party or customapplication) that is not supported by an existing adapter, you can use Tivoli EventIntegration Facility to create an adapter for the source.

The Tivoli Event Integration Facility contains:v An event application programming interface (API) library for use with the Java™

and C programming languagesv A debugging function that checks event syntax and sends events to a filev The ability to exploit state correlation at Event Integration Facility sender

You can use Tivoli Event Integration Facility to do the following tasks::v Specify the event information to send to the event server for processing.v Create an adapter to filter, translate, and then forward event information to the

event server.v Filter and correlate events near the source by using state correlation.v Create an application that can receive events.

Who should read this guideThis guide explains the concepts to effectively develop new adapters or modifyexisting ones. This book is for developers who have programming knowledge andneed to create custom adapters and use Tivoli Event Integration Facility withintheir applications. This book is also useful for IBM Tivoli Enterprise Consoleadministrators who modify configuration files and configure state correlation.

Readers should be familiar with the following software:v Java or C programming languagesv UNIX®, Microsoft® Windows®, or other target operating systemsv Tivoli Management Framework

Note: For information about Tivoli Event Integration Facility for OS/390®

OpenEdition®, please contact IBM Customer support for Tivoli products.

PublicationsThis section lists publications in the IBM Tivoli Enterprise Console library and anyother related documents. It also describes how to access Tivoli publications onlineand how to make comments on Tivoli publications.

© Copyright IBM Corp. 2003 v

IBM Tivoli Enterprise Console libraryThe following documents are available in the IBM Tivoli Enterprise Console library:v IBM Tivoli Enterprise Console Adapters Guide, SC32–1242

Provides information about supported adapters, including how to install andconfigure these adapters.

v IBM Tivoli Enterprise Console Installation Guide, SC32–1233Describes how to install, upgrade, and uninstall the IBM Tivoli EnterpriseConsole product.

v IBM Tivoli Enterprise Console Command and Task Reference, SC32–1232Provides details about IBM Tivoli Enterprise Console commands, predefinedtasks shipped in the task library, and the environment variables that areavailable to tasks that run against an event.

v IBM Tivoli Enterprise Console Rule Developer’s Guide, SC32–1234Describes how to develop rules and integrate them for event correlation andautomated event management.

v IBM Tivoli Enterprise Console User’s Guide, SC32–1235Provides an overview of the IBM Tivoli Enterprise Console product anddescribes how to configure and use the IBM Tivoli Enterprise Console product tomanage events.

v IBM Tivoli Enterprise Console Warehouse Enablement Pack: Implementation Guide,SC32–1236Describes how to install and configure the warehouse enablement pack for theIBM Tivoli Enterprise Console product and describes the data flow andstructures that are used by the warehouse pack.

v IBM Tivoli Event Console Release Notes®, SC32–1238Provides release-specific information that is not available until just before theproduct is sent to market.

v IBM Tivoli Enterprise Console Rule Set Reference, SC32–1282Provides reference information about the IBM Tivoli Enterprise Console rule sets.

Prerequisite publicationsYou should be familiar with the following documentation before using Tivoli EventIntegration Facility:v Tivoli Management Framework Planning for Deployment Guide

Introduces the Tivoli environment and provides detailed information about thedesktop, managed nodes, administrators, policy regions, profiles, notices, tasks,and scheduling.

v Tivoli Management Framework User’s Guide

Describes the concepts and procedures for using Tivoli Management Frameworkservices. It provides instructions for performing tasks from the Tivoli desktopand from the command line.

Related publicationsThe Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,at the following Tivoli software library Web site:

http://www.ibm.com/software/tivoli/library/

vi Tivoli Event Integration Facility: Reference


Access the glossary by clicking the Glossary link on the left pane of the Tivolisoftware library window.

Accessing publications onlineThe 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 onthe CD for instructions on how to access the documentation.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Software InformationCenter Web site. Access the Tivoli Software Information Center by first going to theTivoli software library at the following Web address:


Scroll down and click the Product manuals link. In the Tivoli Technical ProductDocuments Alphabetical Listing window, click the <Your Product Library Name>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 topage check box in the Adobe Acrobat Print window. This option is availablewhen you click File → Print. Fit to page ensures that the full dimensions of aletter-sized page print on the paper that you are using.

Ordering publicationsYou 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-2755v In Canada: 800-426-4968

In other countries, see the following Web site for a list of telephone numbers:

http://www.ibm.com/software/tivoli/order-lit/

Contacting software supportIf you have a problem with any Tivoli product, refer to the following IBM SoftwareSupport Web site:

http://www.ibm.com/software/sysmgmt/products/support/

If you want to contact software support, see the IBM Software Support Guide at thefollowing 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

About this guide vii




http://www.ibm.com/software/tivoli/order-lit/

http://www.tivoli.com/support/handbook/

http://techsupport.services.ibm.com/guides/handbook.html

v Telephone numbers and e-mail addresses, depending on the country in whichyou are located

v Information you must have before contacting IBM Software Support

Participating in newsgroupsUser groups provide software professionals with a forum for communicating ideas,technical expertise, and experiences related to the product. They are located on theInternet and are available using standard news reader programs. These groups areprimarily intended for user-to-user communication and are not a replacement forformal 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. From the Tools menu, click Internet Options.3. On the Internet Options window, click the Programs tab.4. In the Newsgroups list, click the Down Arrow and then click Outlook Express.5. Click OK.6. Close your Internet Explorer browser and then open it again.7. 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.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 guideThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface conventionsThis guide uses the following typeface conventions:

Bold

viii Tivoli Event Integration Facility: Reference

news://news.software.ibm.com/ibm.software.tivoli.enterprise-console

news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows

v Lowercase commands and mixed case commands that are otherwisedifficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip:, and Operating system considerations:)

v Column headings in a tablev Keywords and parameters in text

Italic

v Citations (titles of books, diskettes, and CDs)v Words defined in textv Emphasis of words (words as words)v Letters as lettersv New terms in text (except in a definition list)v Variables and values you must provide

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

Operating system-dependent variables and pathsThis guide uses the UNIX convention for specifying environment variables and fordirectory notation.

When using the Windows command line, replace $variable with %variable% forenvironment variables and replace each forward slash (/) with a backslash ( \) indirectory paths.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

This guide also uses the backslash character (\) convention at the end of a line ofexample text to indicate that the text shown on the following line has wrappeddue to space restrictions of the page. In this case, the example should beinterpreted as being on one line.

About this guide ix

x Tivoli Event Integration Facility: Reference

Chapter 1. Overview of the Tivoli Event Integration Facility

Tivoli Event Integration Facility is a toolkit that expands the types of events andsystem information that you can monitor. Event adapters monitor managedresources and send events to the IBM Tivoli Enterprise Console or otherapplications. You can use the Tivoli Event Integration Facility to develop your ownadapters, tailored to your network environment and your specific needs. With theTivoli Event Integration Facility, you can also create an event listener, an applicationthat receives events. You can place event listeners in your managed environmentwhere you need to distribute events to other management applications.Additionally, the Tivoli Event Integration Facility helps you filter events near theirsource, reducing event traffic on the network and the event server.

This chapter contains the following topics:v Overview of conceptsv Use of the Java API and the C APIv Summary of creating event sources

Overview of conceptsThe central unit of information is the event. An event is any significant change inthe state of a system resource or application. Events can be generated for problemsand for successful completions of tasks. Events provide many different types ofinformation, such as a host being down, someone unsuccessfully trying to log in toa host as an administrator, or a hard drive being nearly full. Events can also begenerated to clear other events.

Adapters are processes that monitor managed sources. A source is an application ora system resource. When an adapter receives information from its source, theadapter formats the information and forwards it to the event server.

An event server is a central server that handles all events collected by thedistributed adapters. The event server creates an entry for each incoming event.Then, it evaluates that event against a set of rules to determine if it can respond toor modify the event automatically. Rules describe the actions that are performedwhen the event server receives a particular system event. In addition, there can beIBM Tivoli Enterprise Console gateways that collect events from adapters that runon endpoints. The gateways then forward the events to the event server. In somecases, you can customize other applications to receive events from the event server.

© Copyright IBM Corp. 2003 1

Figure 1 depicts the event flow from adapters through the Tivoli Event IntegrationFacility to the event server and other applications:

The following sections describe in more detail each of the main concepts for theTivoli Event Integration Facility.

EventsAn event begins as an error message, a trap, or a similar piece of information thatis displayed or written to a file.

The information provided in an event is dependent on the source. Some sourcesprovide detailed information about an event, while other sources are brief in theirdescriptions. An adapter converts all events into a format that provides consistencyin information: such as the source, location, date, and time of an event.

Some events, such as traps, contain data that you cannot read. In these cases, theadapter must translate the data into a format that you can read so that theinformation can be further processed. Some sources, such as a system log file, doprovide data that you can read without machine translation.

Adapters translate event information into a set of attributes. Each attribute ispredefined by the adapter and contains the attribute name and the attribute value.The adapter places the appropriate information in each attribute, then sends theevent to the event server. See the IBM Tivoli Enterprise Console Adapters Guide for alist of base event attributes that can be contained in an event sent to the eventserver.

Eventserver

Applications

TECgateway

EIF

EIFSource

Managednode

adapter

EIF

Source

Non-TMEadapter

EIF

Source

Endpointadapter

EIF

Events

Events

EventsEvents

Events

Events

Figure 1. Flow of events from sources

2 Tivoli Event Integration Facility: Reference

Figure 2 illustrates how an event evolves:

The following example shows how log-file information is translated into events. Inthis example, a failed attempt to run the su root command on the host oak iswritten to the system log file. You can read the resulting format:Nov 7 08:51:42 oak su: ‘su root’ failed for don on /dev/ttyp0

The adapter then translates the log-file information into an event as follows:Su_Failure:source=LOGFILE;origin=oak;date=”Nov 7 08:51:42 ”;host=oak;sub_source=login;from_user=don;tty=/dev/ttyp0to_user=root;END

See the IBM Tivoli Enterprise Console User’s Guide for detailed information aboutevents.

AdaptersAdapters monitor sources. A source is an application (for example, a database) or asystem resource (for example, available disk space).

To monitor a source such as a third-party or custom application, you must use theTivoli Event Integration Facility to create an adapter and event classes for eachnew source.

Adapters monitor sources in the following ways:v An adapter can receive messages from a source that actively produces messages.

For example, adapters can receive messages that are sent by Tivoli softwareapplications.

v An adapter can check a file at configurable intervals if the source updates a file.v An adapter can poll a system resource or system condition at configurable

intervals, and then interpret and forward the resulting information to the eventserver.

Adapter types are either TME® or non-TME, depending on what mechanisms areused to send events to the event server. From a programmer’s perspective, thedevelopment of an adapter is identical for both the TME and non-TME versions;the function calls are the same. However, there are different libraries that you mustlink to the adapter, depending on which type of adapter you decide to build.

TME adapters are adapters that send events to the event server by using TivoliManagement Framework services. There are two types of TME adapters: endpointadapters and managed node adapters.

event:native format

event:Tivoli format

To event serverSystem

Resource orApplication

EventAdapter

Figure 2. Evolution of an event

Chapter 1. Overview of the Tivoli Event Integration Facility 3

Non-TME adapters use standard interprocess communication mechanisms and donot require Tivoli Management Framework.

In most cases, create endpoint adapters, because of the reduced disk space thatTivoli Management Framework requires on endpoints. In general, do not buildmanaged node adapters; libraries for building managed node versions aremaintained and distributed primarily for backward compatibility. In someenvironments, it is necessary to create a non-TME adapter. For example, if theadapter needs to run on a system that is not supported by Tivoli ManagementFramework, the non-TME adapter is required.

When an adapter receives information from its source, the adapter formats theinformation and forwards it to the event server, depending upon the version of theadapter:v Non-TME adapters and managed node adapters send events directly to the

event server.v Endpoint versions of adapters send events to an IBM Tivoli Enterprise Console

gateway, which then forwards the events to the event server.v Non-TME adapters can either send directly to the TEC server or the TEC

gateway.

Event classesAdapters separate information into event classes. They format the information intomessages that represent specific instances of event classes. Then, they send theinformation to the event server. The event server processes the information, alongwith information received from other adapters.

Event classes are classifications of events; do not confuse them with Tivoli objects.Event classes can be divided into subclasses to facilitate a further breakdown ofinformation so that more detailed rules can be applied to the event information.Essentially, event classes are an agreement between the adapter and the eventserver about what information the adapter sends to the event server.

Event classes are defined in event class definition files. The base event classdefinition file (root.baroc) is located in the$BINDIR/TME/TEC/default_rb/TEC_CLASSES directory. Additionally, otherevent classes are subclasses of the base event class. For event classes, you cancreate Basic Recorder of Objects in C (BAROC) files and specify the event server toload those files.

You can have multiple BAROC files on an event server. When you develop a newadapter, define in the BAROC files the types of events that the adapter can send tothe event server.

See the IBM Tivoli Enterprise Console Rule Developer’s Guide for a detailed discussionof BAROC files.

Configuration filesYou can control the behavior of an adapter using the configuration file. Aconfiguration file enables you to specify configuration parameters such as thefollowing:v What information must be sent to the event serverv The connection interface used by the adapter


v The host on which the event server is locatedv Event filtering to be performed by the adapterv Any information that is unique to a particular adapter

After information is separated into event classes, the adapter sends the informationto the event server for further processing. You can use the configuration file tocontrol the information that the adapter sends to the event server. This minimizesany network loading related to enterprise monitoring.

You do not need to modify multiple instances of an adapter to run in differentenvironments. You only have to modify the configuration files. For moreinformation, see Appendix B, “Keywords for configuration files”, on page 67.

Event serverThe adapter does not typically provide values for all attributes of a particularevent; some attribute values are provided by the event server.

The event server validates incoming events. If an event is valid, the event serverassigns a unique identification (ID) and time stamp and stores it in an eventdatabase. The event server processes each incoming transaction before processingthe next transaction.

The example event described on page 3 appears as follows after it is processed bythe event server:Su_Failure;server_handle=1;date_reception=784408852;event_handle=1;source=LOG;sub_source=login;origin=oak;sub_origin=’’;hostname=’’;last_modified_time=’Nov 07, 1994 08:51:42’;adapter_host=’’;status=OPEN;administrator=’’;acl=[admin];severity=WARNING;date=’Nov 07, 1994 08:51:42’;duration=0;msg=’’;msg_catalog=’’;msg_index=0;num_actions=1;credibility=0;repeat_count=0;cause_date_reception=0;cause_event_handle=0;from_user=don;to_user=root;END

Event filteringFiltering reduces complexity for console operators and improves response times forcomplex system errors. There are two ways to filter events with the Tivoli EventIntegration Facility, either with filter statements in the configuration file or withstate correlation. State correlation allows you to filter events at the source or theIBM Tivoli Enterprise Console gateway.,

Chapter 1. Overview of the Tivoli Event Integration Facility 5

See Chapter 5, “Filtering events at the source”, on page 31 for details about eventfiltering with configuration files and state correlation.

RulesIf you develop a new adapter, you might want to write new rules specificallygeared toward enhancing the usefulness of the adapter events. The event serveruses rules to specify and control automatic responses to events throughout anenterprise.

See the IBM Tivoli Enterprise Console Rule Developer’s Guide for information aboutmodifying existing rules and creating new rules.

Use of the Java API and the C APITivoli Event Integration Facility provides two development environments to createadapters: the Java and the C programming languages. Depending on theenvironment you want to monitor, you select the appropriate applicationprogramming interface (API). The interfaces are functionally the same.

Summary of creating event sourcesTivoli Event Integration Facility enables the process of creating new adapters. Thearchitecture differs for each adapter, depending on the information to be collected.But, the mechanism used to deliver events to the event server is the same. Creatingan adapter involves the following steps:v Event identificationv Source definitionv Event classificationv New event class definitionsv Event delivery interface specificationv Adapter development and testingv Adapter installation and configuration

See Chapter 4, “Building an adapter”, on page 19 for detailed information to createan event source.


Chapter 2. Installing the Tivoli Event Integration Facility

This chapter describes how to install the Tivoli Event Integration Facility. See theTivoli Event Integration Facility Release Notes for the latest information and systemrequirements.

This chapter contains the following topics:v Preparing for installationv Installingv Migrating adapters based on 3.7.1 or previous Event Integration Facility

Preparing for installationThe following list summarizes the preparations for the installation::v Read the Tivoli Event Integration Facility Release Notes for the latest information on

requirements, enhancements, and other important product details.v Check hardware and software requirements.

InstallingPutting operating specific platform specific directories on your system has beensimplified with the new standalone installation process. Although the EventIntegration Facility is now packaged differently, the function has not changed.What was an installable component is now packaged in the EIFSDK directorylocated on the IBM Tivoli Enterprise Console TME New Installations CD.

The directory structures are as follows::

bin Contains the CLI executables postemsg, wpostemsg, postzmsg andwpostzmsg for each interp type.

contribContains compiled sample programs.

default_smContains samples for using State Based Correlation.

includeContains header files (.h) for building adapters. These are common acrossall interps.

jars Contains all the jar files necesary to use the Java based Event IntegrationFacility API and State Based Correlation.

javadocContains the javadoc for the Java based Event Integration Facility API.

lib Contains, for each interp type, the libraries needed for linking an adapter.Includes libraries for endpoint, managed node and non-TME adapters.

samplesContains sample adapter source code.

Note: It is recommended that you unzip the files to a separate directory instead ofyour Tivoli installation directory.


Migrating adapters based on 3.7.1 or previous Event IntegrationFacility

Custom adapters created with a previous version of the Tivoli Event IntegrationFacility must be migrated to benefit from the enhanced functionality of the latestversion of Tivoli Event Integration Facility. By migrating, you get the latestmaintenance fixes and product enhancements.

Depending on if the adapter was created with the C API or with the Java API, themigration is different. The following sections provide instructions for both APIs.

Note: For information about the interoperability of adapters that were built usingVersion 3.7.1 of Tivoli Event Integration Facility, see the Tivoli EventIntegration Facility Release Notes.

For more information about creating adapters, see Chapter 4, “Building anadapter”, on page 19.

Adapters created with the C APIHere’s what’s new for creating adapters with the C API:1. The header file tec_eif.h has been removed and replaced with tec_eeif.h.2. The following libraries (libtec.a, libteceif.a, and libtecgw.a) have been replaced

with (libteceeiffwk.a, libteceeif.a, and libteceeifgw.a).3. There are new TransportList keywords for the .conf file that can replace the

ServerLocation/ServerPort keywords.

Note: For more information on programming adapters, refer to “Upgradingexisting adapters” on page 22.

Adapters created with the Java APIHere’s what’s new for creating adapters with the Java API:1. The package name changed from com.tivoli.tec.eif.* to

com.tivoli.tec.event_delivery.*2. The exception class name changed from EIFExeception to EDException.3. The TECAgent class constants for SEND_SUCCESS and SEND_BUFFERED

have been removed. The new return codes are:v SEND_FAILURE (-1)v SEND_FILTERED (0)v nnn (a number indicating the number of bytes sent or buffered)

4. When formatting an event, you need to add single quotation marks (’) aroundslot values that contain special characters such as slash or equal symbols. If theslot value contains a single quotation mark, another single quotation markmust be added.

5. The Tivoli Event Console Event Integration Facility jar file was renamed inTivoli Event Console 3.8 from eif.jar to evd.jar

6. The Tivoli Event Console agent instantiation for 3.7 and 3.8, respectively, are asfollows:v theTecAgent=new TECAgent (sr, TECAgent.COMM_NONTME)v theTecAgent=new TECAgent (sr, TECAgent.SENDER_MODE, false)


Note: The valid agent types are SENDER_MODE and RECEIVER_MODE.COM_NONTME is no longer valid. The third parameter is booleantype, which means one way. This is used for TME adapters onmanaged nodes. It designates whether calls to sendEvent()returnexceptions to the caller; a value of zero (0) means that exceptions willbe returned to the caller.

7. Link with the libraries as documented in theChapter 4, “Building an adapter”,on page 19.

8. There are new TransportList keywords for the .conf file that can replace theServerLocation/ServerPort keywords.

Chapter 2. Installing the Tivoli Event Integration Facility 9

Chapter 3. Event transport

Tivoli Event Integration Facility provides several methods for sending informationto the event server. The system on which an adapter is run must provide aTCP/IP-based interprocess communication facility.

This chapter contains the following topics:v Event delivery methodsv Event reception for applicationsv Sending events through firewallsv Event delivery when systems fail

Event delivery methodsEvents are delivered by an interprocess communication mechanism. To specify thedelivery methods for adapters and applications using the Tivoli Event IntegrationFacility, modify the configuration file and link to the applicable library. To delivertest events directly from a command prompt, use the command line interface (see“Shell script and test options” on page 12).

Connection optionsThe connection options are either connection-oriented or connectionless. Insituations where you want to send many events, use the connection-orientedoption. In situations where you want to send few events over a period of time, usethe connectionless option.

You can write a single adapter and use it with a connection-oriented or aconnectionless delivery method. You can specify either delivery method bymodifying the configuration file.

The default setting for the connection option is connectionless. SpecifyConnectionMode=CO in the configuration file to have event deliveryconnection-oriented. The connection-oriented method keeps the channel to theevent server open. This is clear to the application and improves the performancewhen you are sending many events.

Transport optionsThe transport options for connections are either TME or non-TME. TMEconnections use Tivoli Management Framework to establish connections. Non-TMEconnections use standard TCP/IP to establish connections.

To specify the transport option, use one of the libraries listed in Table 1:

Table 1. Transport types and related libraries

Transport Type Adapter Type Library

TME connections:

LCF transport

Endpoint adapter libteceeifgw.a


Table 1. Transport types and related libraries (continued)

Transport Type Adapter Type Library

TME connections:

TME transport

Managed node adapter libteceeiffwk.a

Non-TME connections Non-TME adapter libteceeif.a

For security reasons, run in the TME mode if possible. For more information aboutthe libraries, see “Linking the adapter built with the C API” on page 25.

Shell script and test optionsCLI commands and a Java class are available for sending events using TME andnon-TME communications. The same Java class, com.tivoli.tec.event_delivery.TECAgent, can be used for both TME and non-TME communications. Thewpostzmsg command is used for TME communicatons. The postzmsg command isused for non-TME communications. There are two versions of the wpostzmsgcommand, one that is run in a Tivoli managed node environment and one that isrun in a Tivoli endpoint environment. Ensure that you are always using thewpostzmsg command that matches your environment.

Posting events can be good for:v Using shell scripts to develop adaptersv Testing after the following:

– creation of new event groups and assignments– rules editing– other changes in the way a server processes events

v Troubleshooting event delivery problems after installing a new adapter

When using a user ID other than Administrator or root, ensure that you have thecorrect permissions for creating the file specified by the BufEvtPath keyword (aswell as the default value when the keyword is not specified).

In the EIFSDK directory, located on the IBM Tivoli Enterprise Console TME NewInstallations CD, the following commands can be found in these directories:Managed Node wpostzmsg: $BINDIR/binEndpoint wpostzmsg: $LCF_BINDIR/../binpostzmsg: $BINDIR/bin and $LCF_BINDIR/../binTECAgent: $BINDIR/../generic_unix/TME/TEC and $LCF_BINDER/../../generic_unix/TME/TEC

The syntax for the wpostzmsg command, the postzmsg command, and thecom.tivoli.tec.event_delivery.TECAgent class is described in the IBM TivoliEnterprise Console Command and Task Reference.

Event reception for applicationsIn addition to sending events, the Tivoli Event Integration Facility enables otherapplications to receive (listen for) events.

The Tivoli Event Integration Facility can instantiate one or more event listeners.Each event listener can have one or more channels. This allows information to flowfrom multiple sources. You can specify multiple channels, and the event listenerlistens to all of those channels. For more information about controlling channels,see the TransportList keyword in “Keywords” on page 67.


The polling mechanism enables the application to retrieve events synchronously, byusing the get method of the API. With the non-polling mechanism, the applicationregisters a listener or callback and receives events asynchronously.

Additionally, the Tivoli Event Integration Facility uses a cache for event reception.If the application has a listener, Tivoli Event Integration Facility also registers alistener to the cache. Then it notifies the application and passes the event to theapplication listener. If the application does not use a listener, the application mustrequest the retrieval of the next event.

For more information about the cache, see “Activating the cache” on page 14 and“Keywords” on page 67.

The following is an example of a configuration file that enables the application toreceive events using sockets:BufferEvents=YESBufEvtPath=/tmp/eif_socket_recv.cache

TransportList=t1

t1Type=SOCKETt1Channels=t_t_ServerLocation=myserver.comt_Port=5151

Sending events through firewallsYou can send events through firewalls depending on your environment andorganizational restrictions regarding firewall security.

To send events through firewalls, use Tivoli Management Framework FirewallSecurity Toolbox. It collects events from TME and non-TME adapters and sendsthem across the firewall using a proxy. To obtain Tivoli Management FrameworkFirewall Security Toolbox and its documentation, contact Customer Support.

In non-Tivoli environments, to send events through firewalls, you configure yourfirewall to allow arbitrary TCP/IP connections on the port specified for youradapter. Ensure that the firewall allows inbound communication from thecomputer system hosting the adapter. See “Keywords” on page 67 for informationabout the ServerPort keyword.

Event delivery when systems failTo ensure that events are delivered after system failures, the Tivoli EventIntegration Facility provides a cache on the adapter or the application receivingevents. This repository stores events and removes those events from the cachewhen they are delivered. Moreover, the Tivoli Event Integration Facility ensuresthat the same event is not delivered more than once.

The following steps configure your environment for the reliable delivery of events:1. Activate the cache. See “Activating the cache” on page 14 for more information.2. Specify alternate servers to deliver events. See “Configuring backup servers to

deliver events” on page 14 for more information.

You can also avoid delivery failure by simply specifying a list of servers. If oneserver fails, then one of the backup servers delivers events. See “Configuringbackup servers to deliver events” on page 14.

Chapter 3. Event transport 13

Activating the cacheBy default, the cache stores events. You control the configuration of the cache withkeywords in the configuration file:

Table 2. Keywords for configuring the cache

Configuration of the Cache Keywords

Activation of the cache BufferEvents

Rate to send events BufferFlushRateMaxPacketSize

Size of the cache BufEvtMaxSize

You can configure the cache in more than one way:v Store events in memory only with the BufferEvents keyword.v Save these buffered events to a permanent file with the BufferEvents keyword

set to YES. Also, the BufEvtPath keyword specifies the location of the permanentfile.

The second configuration ensures that no events are lost during a system failure.

The following example from a configuration file demonstrates the use of cachekeywords:BufferEvents=YESBufEvtPath=./bufferMaxPacketSize=130BufferFlushRate=96ConnectionMode=CO

When connections to the event server fail, events wait in the cache. The TivoliEvent Integration Facility attempts to reconnect to each of the backup servers inturn. If no servers are available after all retries, the API caches the events until aconnection is made. See “Configuring backup servers to deliver events” for moreinformation about backup servers.

When enabling recovery features, it is important to determine the importance ofperformance and reliability. In some environments, the use of the cache candegrade performance depending on its configuration. Thus, you can bypass eventcaching, by setting the BufferEvents keyword to NO.

Configuring backup servers to deliver eventsDepending on whether the adapter is the TME or non-TME version, you specifyhow to contact backup servers differently. For TME adapters, you specify thetransport channel to be the Tivoli management region server and optionally theregion name. For non-TME adapters, you can only specify the transport channel tobe the server name and the port number. In the second case, the configuration usesTCP sockets to deliver events.

Additionally for TME adapters, you can have a variety of channels to createalternate paths to the servers. Thus in addition to TME connections, you also canspecify a channel to be the server name and port number, which uses TCP socketsto deliver events. Do not use both the TME and LCF transport types in the sameconfiguration file.

When using the TME transport type as the primary connection to the event server,specify either of the following transport types for backup connections:


v TME

v SOCKET

For example, the event server is not available, and thus the channels specified forthe primary TME transport are not available. Consequently, another TME transportcan make the connection to other event servers running in different Tivolimanagement regions.

When using the LCF transport type as the primary connection to the event server,the SOCKET transport type is the only valid type for backup connections. It isunnecessary to specify additional LCF transport types, because the endpointadapter already has preset connections based on the endpoint installation andconfiguration. For the same reason, it is unnecessary to specify multiple channelsfor the LCF transport type. For information about how events get to the eventserver from an endpoint, see the IBM Tivoli Enterprise Console Adapters Guide. Forthe LCF transport type, you can instead create backup connections for the gatewayto the event server, by specifying the ServerLocation and ServerPort keywords inthe gateway configuration file.

To configure backup servers, modify the configuration file as follows:1. Create names for connections you want to make to the backup servers. Use the

TransportList keyword to create this list.2. Specify either a TME, LCF, or a SOCKET connection for each of the items in

this list. Use the Type keyword to do this.3. Optionally, specify multiple channels as alternate paths for each type of

transport, using the ServerLocation keyword.

In the following example for the C API, there are two types of transportconnections: TME, named t1, and SOCKET, named t2. The channels for the TMEtype are named c1 and c2; the channels for the SOCKET type are named c3 andc4. For the TME type, c1 specifies the name of the Tivoli management regionserver; c2 also specifies the region name. For the SOCKET type, the channel c3specifies the server name to be host1 and the port to be 1234.TransportList=t1,t2t1Type=TMEt1Channels=c1,c2c1ServerLocation=@EventServer#xyz-region# additional keywords required when running the Java APIc1TMEHost=xyzc1TMEUserID=Administratorc1TMEPassword=pwd# end of additional Java API keywordsc2ServerLocation=@EventServer#abc-region# additional keywords required when running the Java APIc2TMEHost=abcc2TMEUserID=rootc2TMEPassword=root_pwdc2TMEPort=94# end of additional Java API keywordst2Type=SOCKETt2Channels=c3,c4c3ServerLocation=host1c3Port=1234c4ServerLocation=host2c4Port=5678

Note: The C API ignores the Java API keywords: TMEHost, TMEUserID,TMEPassword, and TMEPort.


Using the portmapper keywordsThe keywords for the portmapper channel enable the following:v The receiver applications can register multiple ports under various portmapper

program names.v The sending applications can access those registered names.

When the channel_namePortMapper keyword is set to YES, it forces the specifiedport to be registered with the portmapper for a receiver application. Thus, itignores the specified port in favor of the portmapper to obtain the correct port forsender code. The API ignores any other value for channel_namePortMapper.

The default values for the channel_namePortMapperName,channel_namePortMapperNumber, and channel_namePortMapperVersionkeywords are the ones used by the event server. If these keywords are not presentin the configuration file for the sender application and the portmapper isrequested, a connection to the event server is attempted. In a receiver application,the port is only registered if the port is set to zero (0). In this case, the defaultvalues are used.

If a port is set to zero (0), the Tivoli Event Integration Facility uses thechannel_namePortMapperName, channel_namePortMapperNumber, andchannel_namePortMapperVersion keywords. If any of their values are notspecified, their default values are used.

If a port is set to a value greater than zero, the portmapper is only used if thechannel_namePortMapper keyword is set to YES. In this case, the specified port isignored for the sender side but used for the receiver side. Thechannel_namePortMapper keyword allows the port used for portmapper to bespecified. Thus, a port set to zero (0) will pick any available port. On the receiveside, it is advantageous to use the portmapper so that sending applications canconnect to the receiver by means of the portmapper.

For more information about the portmapper keywords, see Appendix B,“Keywords for configuration files”, on page 67.

Configuring a reception application built with the C APIA reception application built with the C API can be configured with the followingkeywords in the configuration file:

ActiveConnections=nnThe number of active connections that the reception process should handle.The number of possible connections range from 2 - 10000. A number lessthan the minimum value sets the value to the minimum value unless thatnumber is zero which means unlimited connections.. A number greaterthan the maximum value sets the value to the maximum value. Notspecifying a value, yields the default value of 128.

Applies to the C API only.

ActiveConnectionsSafety=nnThe percentage of ActiveConnections that the number of actualconnections must be reduced to before connections can be processed again.This is a threshold value. Setting ActiveConnections limits the numbers ofactive connections handled by the C Event Integration Facility receptionprocess. For example, if ActiveConnections equals 20 and theActiveConnectionsSafety equals 80 , the reception process stops accepting


connections when there are 20 connections. The percent can range from 10- 90. New connections resume when the number of active connections isreduced to 16 (80% of 20) or less. The default value is 80 and is only usedwhen ActiveConnections has been specified. A number less than theminimum value sets the value to the minimum value. A number greaterthan the maximum value sets the value to the maximum value.


ConnectionsQueued=nnThe approximate number of queued connections that the reception processwill handle. The server socket queues up connections that are waiting to beaccepted by the reception process. Connection attempts fail after this limithas been exceeded. Use this option to limit the number of connections thatcan be queued. The actual number of connections queued can be slightlymore than or less than the value of ConnectionsQueued. The default is1000. The range of values can be between 1 - 1000. A number less than theminimum value sets the value to the minimum value. A number greaterthan the maximum value sets the value to the maximum value.



Chapter 4. Building an adapter

This chapter describes how to build an adapter. The following are the basic tasks:1. Identify events to monitor. See page 20.2. Define the event source. See page 20.3. Define the event classes. See page 21.4. Select the method for event delivery. See page 21.5. Program the event adapter. See page 21.6. Install, configure, and test the event adapter. See page 27.

There are several adapter files. In addition to the header file or Java package, thefollowing are files related to the adapter:

.conf fileThe configuration file controls filtering and buffering of events. It alsocontrols communications. This file is located with the adapter and IBMTivoli Enterprise Console gateway.

.baroc fileThe Basic Recorder of Objects in C (BAROC) file validates if events are in avalid format based on their event class definitions. This file is located onthe event server.

.rls fileThe rule file applies custom rules to events for filtering, tasks, and otheractions. Some rule files are installed on the event server by default. Youcan optionally specify other rules.

.xml fileThe XML file defines the state machines for state correlation. This file islocated on the adapter, but also can be present on the IBM TivoliEnterprise Console gateway. This file is optional.


Figure 3 shows the relationship of adapter files and event processing:

For a detailed description of adapter files, see the IBM Tivoli Enterprise ConsoleAdapters Guide.

Identifying events to monitorBefore you create an adapter, you must decide what types of events you need tomonitor. Review the following to help you identify significant events:v Users of IT resourcesv Service level agreementsv Network requirements for down-time and up-timev Application and network dependencies (for example, databases, e-commerce

Web sites, wide area networks, and so forth)v Performance requirementsv Important servers and network resources

After creating a list of significant events, use this list to define the source.

Defining the sourceThe method used to retrieve event information is resource-dependent. When youdevelop a new adapter, you must determine how to gather information about themonitored resource. You also must determine a method for identifying theinformation that you want to send to the event server. For example, the necessary

Eventconsoles

Monitored source

Event server

.baroc file

.xml file

Events

Adapter

EventsEventsEvents

Other applicationsEvent

database

.rls file

.conf file

Figure 3. Role of adapter files in event processing


information about a resource can be gathered from a system log file. Then thisinformation must be formatted, and optionally filtered, before being sent to theevent server.

Defining event classesMuch of the work involved in creating an adapter is determining the event classesfor the information that you want to monitor. Make event definitions as specific aspossible. This helps when you write rules to handle the events.

The IBM Tivoli Enterprise Console provides a set of default event classes. Deriveyour event subclasses from the default classes. See the IBM Tivoli Enterprise ConsoleAdapters Guide for a listing of the default classes hierarchy. Event class names mustbe unique.

The event string is adapter-dependent. You can have as many as required pairs ofattributes and values. However, you must define the pairs in the BAROC file. Thefollowing code fragment illustrates the assembly of an event string:"MY_EVENT_CLASS;

source=_ANY_DEFINED_SOURCE;

application=myAppl1;

origin=9.179.1.234;

msg=Hello World;

END\n\001"

In the code fragment, MY_EVENT_CLASS must be defined in the BAROC file. Also,source and application are application-specific.

See the IBM Tivoli Enterprise Console Rule Developer’s Guide for more informationabout event classes and BAROC files.

Selecting event delivery methodsWhile building an adapter, you also need to decide which event delivery methodthe adapter uses to communicate with the event server. The options are thefollowing:v TME or non-TMEv Connection-oriented or connectionless

See “Event delivery methods” on page 11 for details about those methods and howto specify them.

Programming the adapterTo program your adapter, do the following:v Implement the interfaces and the preferred settings for the configuration file. For

more information about these settings, see “Keywords” on page 67.v Decide where to define attribute values: in the configuration file or the adapter

codev Compile the adapterv Link the adapter

Build the example program as both a TME adapter and as a non-TME adapter toensure that your build environment is properly set up. Even if you do not plan to

Chapter 4. Building an adapter 21

deploy non-TME adapters, do the test builds as non-TME adapters until your codeis working properly and is ready for release. Non-TME adapters are easier todebug: the only difference between non-TME and TME adapters is the libraries (nocode changes). After the non-TME adapter works properly, change to the TMElibraries and build a TME adapter. Also, change the ServerLocation keyword in theconfiguration file. Any problems that occur with the new TME adapter aregenerally Tivoli authorization issues.

Tivoli Event Integration Facility provides a C API and a Java API to communicatewith the event server. The APIs perform the tasks listed in Table 3:

Table 3. APIs and their behaviors

Tasks Java API C API

Access configuration filesand read keyword data

TECAgentgetConfigVal

tec_agent_inittec_agent_getenv

Establish and closecommunications with theevent server

TECAgentdisconnect

tec_create_handletec_destroy_handle

Send and receive events sendEventreceiveEventregisterListeneronMessage

tec_put_eventtec_get_eventtec_register_callbacktec_event_callback

The following sections describe how to use the functions and methods to handlethe configuration files, communications, and data transfer. For API syntax andexamples, see Appendix A, “Application programming interfaces”, on page 41.

Note: Building non-TME and endpoint adapters is not supported on HPUX,however, building managed node adapters is supported on HPUX.

Upgrading existing adaptersTo convert from 3.7.1 or earlier versions of Tivoli Enterprise Console to 3.8 or laterversions, link your programs based on the information provided in the Libraryconversion names table.

Table 4. Library conversion names

3.7.1 and earlier versions 3.8 and later versions Function

libteceif.a libteceeif.a non-TME adapters

libtec.a libteceeiffwk.a managed node adapters

libtecgw.a libteceeifgw.a endpoint adapters

A set of three stub libraries are provided with the Event Integration Facility toolkitwhich can help port your adapters. These libraries can be linked with your code todetermine if your adapter, built using the Event Integration Facility, is currentlyusing dated function that is no longer available in Enhanced Event IntegrationFacility. The stub library names are:v libtecceeif_stub.a (for non-TME adapters)v libteceeiffwk_stub.a (for managed node adapters)v libteceeifgw_stub.a (for endpoint adapters)

Relink your Event Integration Facility adaper code with the stub libraries. If youreceive an undefined symbol error message, it means that the Event Integration


Facility function that you have been using is no longer supported. Please refer toAppendix A, “Application programming interfaces”, on page 41 for a list ofsupported APIs. Update your code and compile and link again. Porting adaptersmight require you to link additional libraries. See “Linking the adapter built withthe C API” on page 25 for information on the libraries that are needed to buildyour programs.

Note: Building non-TME and endpoint adapters is not supported on HPUX,however, building managed node adapters is supported on HPUX.

Configuration file APIsThe first task performed by the APIs is accessing information from theconfiguration files. To enable the tec_agent_getenv function or getConfigValmethod, you first call the initialization API (tec_agent_init or TECAgent). Theinitialization API reads in configuration information that is used by all subsequentfunctions or methods.

For more information, see “Keywords” on page 67.

Communications APIsThe communications APIs provide a mechanism to communicate with the eventserver. The handle is specified when sending an event.

Regardless of the type of transport mechanism, use a single call totec_create_handle or TECAgent to establish communications with the server. Thefollowing code example instantiates TECAgent, passing as parameters theconfiguration file, the delivery mode, and the error-reporting mechanism:public TECAgent(reader configStream, int deliveryMode, int oneway)

Call the tec_destroy_handle function or disconnect method when you no longerwant to communicate with the event server. This call is optional; the channelautomatically disconnects when the adapter exits.

Data transfer APIsData is transferred to the event server by assembling an event string. Thetec_put_event function or sendEvent method sends the string to the event server.

Sample adapter codeSample adapter code for the C and Java languages can be found in the EIFSDKdirectory located on the IBM Tivoli Enterprise Console TME New Installations CD.

Special considerations for WindowsAn adapter built for Microsoft Windows platforms must initialize the Winsockbefore calling tec_create_handle.

The following is an example of this:#ifdef WIN32#include <winsock.h>

WSADATA wsaData;

if ((rc = WSAStartup(MAKEWORD(1, 1), &wsaData)) != 0) {printf("error %d starting winsock.dll\n", rc);exit(1);

}


elseprintf("Winsock initialized successfully...\n");

#endif

An application must call the WSAStartup function to initialize Winsock, regardlessof which version of Winsock is being used. WSAStartup initialized Winsock2.dlland a WSADATA structure that contains the details of the Winsockimplementation. When an application or DLL has finished using Winsock2.dll, itmust call WSACleanup to enable Ws2.dll to free any resources for the application.For every call to WSAStartup, there must be a call to WSACleanup.

If successful, WSAStartup returns 0. After WSAStartup returns, an applicationcannot call WSAGETLastError to determine the error value.

Compiling the adapterAdapters can be built using either the C or Java API. Adapters built using theEvent Integration Facility are not thread-safe and cannot be multithreaded.


Compiling the adapter built with the C APITo compile a source file that uses the Event Integration Facility C API you need toinclude the tec_eeif.h header file. When compiling the sample adapter onWindows, you must specify the PC flag as a compiler argument, to avoidcompile-time errors.

To link the sample adapter, you must use the NODEFAULTLIB:LIBC.LIB optionwhen linking the adapter on Windows. This allows the linker to avoid conflictswith the default libraries.

If there are mutliple wsock32.lib files, you must use the FORCE:MULTIPLE optionwhen compiling the Windows adapter. This forces the compiler to pick one file toeliminate compile-time errors. In conjunction with the FORCE:MULTIPLE option,the INCREMENTAL:NO option must also be used.

The following example shows how to complile and link a sample adapter usingthe options mentioned above:unsecure: adapter.c \$ (CC) -nologo -Ze -W3 -MD -DUNSECURE -D_WIN32 -DWIN32 -DPC \-Ic:/Tivoli/include/w32-ix86/TME/TEC -Id:/msdev/include -FosampleAdapter.obj -c sampleAdapter.c \slashes link -subsystem:console -L. -Ld:/msdev/lib -Lc:/Tivoli/lib/w32-ix86 \-out:sampleAdapter.exe sampleAdapter.obj msvcrt.lib libteceeif.a \libsunrpc.a -NODEFAULTLIB:LIBC.LIB -INCREMENTAL:NO -FORCE:MULTIPLE wsock32.lib

Compiling the adapter built with the Java APITo compile a Java source that uses the Event Integration Facility Java API, importevd.jar into your source file and ensure that evd.jar and log.jar are available on thecompilation class path.

Linking the adapter built with the C APIThe following tables list the libraries required to link endpoint adapters (Table 5),managed node adapters (Table 6 on page 26), and non-TME adapters (Table 7 onpage 26) developed with the C API.

Table 5. Libraries required for endpoint adapters developed with Event Integration Facility CAPI

Required Libraries Provided by Notes

libteceeifgw.a Tivoli Event IntegrationFacility

None.

libcpl.a

libdes.a

libmrt.a

Tivoli ManagementFramework

Tivoli Application DevelopmentEnvironment is also required to setthese libraries.

libdl.a Operating system Not on Windows and HPUX.

libpthreads.a Operating system For adapters on AIX®.

libpthread.a Operating system For adapters on Linux.

libnsl.a

libsocket.a

libthread.a

Operating system For adapters on the SolarisOperating Environment.

libsunrpc.a Tivoli Event IntegrationFacility

For adapters on Windows.


Table 5. Libraries required for endpoint adapters developed with Event Integration Facility CAPI (continued)


Standard C libraries Operating system Or other libraries that your adapterrequires.

Table 6. Libraries required for managed node adapters developed with Event IntegrationFacility C API


libteceeiffwk.a Tivoli Event IntegrationFacility

None.

libas.a

libms.a

librim.a

libtas.a

libthreads.a

libtmf.a

libui.a

Tivoli ManagementFramework

Tivoli Application DevelopmentEnvironment is also required toset these libraries.

libdl.a Operating system Not on Windows and HPUX.

libpthreads.a Operating system For adapters on AIX.


libnsl.a

libsocket.a

libthread.a




Standard C libraries Operating system Or other libraries that youradapter requires.

Table 7. Libraries for non-TME adapters developed with Event Integration Facility C API

Libraries Provided by Notes

libteceeif.a Tivoli Event IntegrationFacility

None.

libdl.a Operating system Not on Windows andHPUX.

libpthreads.a Operating system For adapters on AIX.


libnsl.a

libsocket.a

libthread.a





Table 7. Libraries for non-TME adapters developed with Event Integration Facility CAPI (continued)

Libraries Provided by Notes

Standard C libraries Operating system Or other libraries that youradapter requires.

Installing, configuring, and testing the adapter

After assembling all the files for the adapter, you need to install, configure, andtest the adapter. An environment suitable for an adapter must be established beforerunning the adapter. There are two main environments: TME and non-TME. TheTME environment can be further divided into a Managed Node environment andand endpoint environment. Adapters built for a Managed Node environment mustrun in a TME managed Node environment created by running the setup_env.sh orsetup_env.cmd scripts. Adapters built for the endpoint environment must run inan endpoint environment created by running the lcf_env.sh or lcf_env.cmd scripts.

A Managed node adapter can send events using one or two types of transports,TME or non-TME. To configure the adapter to send events using TME, set thetransport type to TME. To configure the adapter to send events using non-TME,set the transport type to SOCKET. A managed node adapter cannot send to aTivoli Enterprise Console gateway using endpoint communications.

An endpoint adapter can send events using one of two types of transports, TME ornon-TME. To configure the adapter to send using TME, set the transport type toLCF, which sends the event to a Tivoli Enterprise Console gateway via a TMEgateway. To configure the adapter to send events using non-TME, set the transporttype to SOCKET. An endpoint adapter cannot send to a Tivoli Enterprise ConsoleServer directly using TME managed node communications.

A non-TME adapter can send events using non-TME transport. To configure theadapter to send events using non-TME, set the transport type to SOCKET. Anon-TME adapter cannot send to a Tivoli Enterprise Console Server directly usingTME managed node communications and it cannot send to a Tivoli EnterpriseConsole gateway using endpoint communications.

After installing the adapter, you can also add other features to the adapter. Forexample, you can modify the adapter to enable the following features:v Event filtering, see “Filtering with configuration files” on page 31 and “Filtering

with state correlation” on page 33v Event caching for failure and recovery, see “Event delivery when systems fail”

on page 13v Rules, see the IBM Tivoli Enterprise Console Rule Developer’s Guide

Before installing your new adapter in a production environment, test at aminimum the following functionality:v Does the adapter successfully install?v Are events mapped to the appropriate event classes?v Are events arriving and displaying on the console, if applicable?v Are events correctly filtered?


Running adapters built with the Event Integration Facility Java APIThe Event Integration Facility Java API depends on other classes to accomplish itstasks. In addition to setting up the appropriate environment using the setup_envor lcf_env commands, you must add the path to the Java executable file to yourlibrary path environment variable.

The following tables list the Java jar files and libraries required to run an adapterthat is built using the Event Integration Facility Java API.

To run an adapter that uses the Java Event Integration Facility API, you must addthe required libraries in Table 8 to your CLASSPATH environment:

Table 8. Libraries required for adapters developed with the Event Integration Facility JavaAPI


evd.jar

log.jar

Tivoli Event Integration Facility None.

jcf.jar

ibmjsse.jar

jsafe.zip

Tivoli Event Integration Facility For managed nodeadapters only.

xerces-3.2.1.jar

zce.jar

Tivoli Event Integration Facility For state correlationonly.

For endpoint adapters, you must add the directories shown in Table 9 to yourlibrary path as required by the operating system:

Table 9. Llibrary paths and directories for endpoint adapters developed with the EventIntegration Facility Java APIOperating System and Library Environment Variable Directory

AIX: libteclcf.a LIBPATH <eifsdk>/lib/aix4-r1

HP-UX: libteclcf.sl SHLIB_PATH <eifsdk>/lib//hpux10

Linux: libteclcf.so LD_LIBRARY_PATH <eifsdk>/lib/linux-ix86

—OR—

<eifsdk>/lib/linux-s390

Solaris Operating Environment:libteclcf.so

LD_LIBRARY_PATHJ <eifsdk>/lib/solaris2

Windows: teclcf.dll PATH <eifsdk>\lib\w32-ix86\eifdll

Note: <eifsdk> is located either on the IBM Tivoli Enterprise Console TME NewInstallations CD or in the directory where you placed it.

Configuring adapters for international environmentsThe event server can receive events in both UTF-8 encoding or the encoding of theevent 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.

Use the Pre37Server and Pre37ServerEncoding keywords to send events in theencoding of the event server host instead of UTF-8. For double-byte character set


languages, use the NO_UTF8_CONVERSION keyword to keep additional UTF-8conversion from occurring. See “Keywords” on page 67 for additional information.

For non-TME adapters, use UTF-8 encoding to send events to the event server.

If the adapter is sending events to an event server host running a version earlierthan Tivoli Enterprise Console 3.7, the format files in localization directories mustremain in English.


Chapter 5. Filtering events at the source

One of the problems associated with event management is working with the highvolume of events that devices can generate. For instance, a router, has droppedbelow a key performance threshold (the amount of time to return a ping, forexample). The router is set to generate an event every 30 seconds until an operatorhas found and addressed the underlying problem. Meanwhile, redundant eventsflood the event console, impacting the problem-solving process.

Tivoli Event Integration Facility addresses this problem with two powerfultechniques for analyzing, summarizing, and distributing the incoming eventinformation: filtering with configuration files and state correlation. By usingconfiguration files on adapters and gateways, you can filter based on matches toevent classes. State correlation provides preliminary analysis and filtering of eventsnear the event sources which helps to eliminate the unnecessary flow of events upto the higher layers. It also applies intelligent filtering rules to reduce the numberof events that are sent to the event server. When properly defined, configurationfiles and state correlation optimize event management by minimizing the numberof events that each operator must monitor.

There are two methods provided by the Event Integration Facility to filter events atthe adapter level:v Configuration file: provides filtering based on matches to event classes. This is

the simpler and limited option in terms of capabilities.v State correlation: state correlation can be enabled and used at the Event

Integration Facility in the adapter to provide more sophisticated filtering andcorrelation capabilities as close as possible to the event sources.

Filtering with configuration filesNormally, an adapter sends all events to the event server. You can optionally listthe events that the adapter can or cannot send to the event server by using theFilter and FilterCache keywords. Similarly, you can modify the configuration fileon the IBM Tivoli Enterprise Console gateway to filter events.

The configuration file can contain as many filter entries as needed. You specify theevent class and information such as the origin, severity, or any other attribute andvalue pair that is defined for the event class.

Depending on how you specify the Filter and FilterMode keywords, filteredevents are either sent to the event server or discarded.v To send specific events to the event server:

1. Set FilterMode to IN.2. Create Filter statements to match the specific events that you want sent.

v To 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.

For filter syntax, see Appendix B, “Keywords for configuration files”, on page 67.

Filtering events when systems failWhen an adapter is unable to connect to the event server or IBM Tivoli EnterpriseConsole gateway, it sends the events to a file if the BufferEvents keyword is set toYES. You can filter events sent to a cache file, similar to filtering events for theevent server by using the FilterCache keyword.

The following procedures describe how to filter events with the FilterCache andFilterMode 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:

1. Set FilterMode to OUT.2. Create Filter and FilterCache statements to match the specific events that

you want discarded.v To cache all events (the default behavior):

1. Set FilterMode to OUT.2. Set BufferEvents to YES.3. Do not specify any FilterCache statements.

Note: All events are discarded when the configuration is as follows:1. FilterMode is set to IN.2. No FilterCache statements are specified.

For more information about how to use the BufferEvents keyword, see “Activatingthe cache” on page 14.

ExampleThe following example shows two filters. The first filter suppresses all events withthe class disk_event. The second filter suppresses all events with the classSu_Success from the IP address 126.32.2.14.## Event Filters#Filter:Class=disk_eventFilter:Class=Su_Success;origin=126.32.2.14

Regular expressions in filtersYou can also use Tcl regular expressions in filtering statements. The format of aregular expression is re:’value_fragment’.


Note: The Tivoli Event Integration Facility uses an exception to the Tcl regularexpression syntax. The backslash character (\) in the Tivoli Event IntegrationFacility indicates that the following literal character is the character to filterfor, not some special character such as a tab. For example, \t means the tabcharacter in Tcl, but means t in Tivoli Event Integration Facility.

The following example shows a Filter statement with a regular expression. Thisfilter statement matches all events with a class name that starts with TEC_

Filter:Class=re:’TEC_.*’

The following example shows a FilterCache statement with a narrower range. Thisfilter statement matches all events with a class name that starts with TEC_ and has aseverity of critical:FilterCache:Class=re:’TEC_.*’;severity=CRITICAL

For more information about Tcl regular expressions, see a Tcl user’s guide.

Filtering with state correlationState correlation monitors information from incoming events and associates thisinformation with user-defined patterns. State correlation analyzes the incomingevents for user-defined states to suppress duplicate events, identify eventthresholds, and collect or group similar events.

You can use state correlation with your custom adapters or IBM Tivoli EnterpriseConsole gateways. When using state correlation with a gateway, you can enhanceyour filtering by correlating events across multiple adapters. For more informationabout IBM Tivoli Enterprise Console gateways, see the IBM Tivoli Enterprise ConsoleUser’s Guide.

Note: State correlation does not work with managed node adapters built with theC API. Instead, use an endpoint adapter or a non-TME adapter.

State correlation helps minimize event traffic by identifying similar events andconsolidating their information into summary events where possible. Those eventsthat cannot be included in a summary are single events. The event server thenreceives these summary events, as well as the single events. Accordingly, the eventserver does not receive the redundant, individual events for each summary.

For information about writing rules for state correlation, see the IBM TivoliEnterprise Console Rule Developer’s Guide.

Activating state machinesBefore you activate the state machine, ensure that you have written your rulesbased on the information described in the IBM Tivoli Enterprise Console RuleDeveloper’s Guide.

Follow this procedure to run a state machine:1. Modify the state correlation keywords in the configuration file. The following

code fragment illustrates the use of the appropriate keywords:UseStateCorrelation=YES# for Windows NT onlyStateCorrelationConfigURL=file:C:\tmp\test.xml# for all other INTERPs# StateCorrelationConfigURL=file:///tmp/test.xml

Chapter 5. Filtering events at the source 33

2. To run state correlation on an adapter, place both the XML and DTD files in thepath specified in step 1.

3. Add the following files to the CLASSPATH environment variable:v zce.jarv log.jarv xerces-3.2.1.jarv evd.jar

For adapters that are built using the C API, add the following directories toyour library path as required by the operating system:

Table 10. Library paths and directories for adapters built with the C API

Operating System andLibrary Environment Variable Directories

AIX: libjvm.a LIBPATH /InstallDir/bin/aix4-r1/TME/TEC/jre/bin/classic

/InstallDir/bin/aix4-r1/TME/TEC/jre/bin

HP-UX: libjvm.sl SHLIB_PATH /InstallDir/bin/hpux10/TME/TEC/jre/lib/PA_RISC/classic

/InstallDir/bin/hpux10/TME/TEC/jre/lib/PA_RISC/

Linux: libjvm.so LD_LIBRARY_PATH /InstallDir/bin/linux-ix86/TME/TEC/jre/bin/classic

/InstallDir/bin/linux-ix86/TME/TEC/jre/bin

Solaris OperatingEnvironment: libjvm.so

LD_LIBRARY_PATH /InstallDir/bin/solaris2/TME/TEC/jre/lib/sparc

Windows: libjvm.dll PATH \InstallDir\bin\TME\TEC\jre\bin\classic

4. Restart the adapter, as required by the operating system, to initialize stateinformation.

After the state machine is running, you can test whether state correlation isproperly filtering events in the following ways:v If you have written rules to generate event summaries, ensure that the event

server is receiving the event summaries.v If you have written rules to suppress events, ensure that suppressed events do

not arrive at the event server.


Chapter 6. Troubleshooting

This chapter explains how to troubleshoot problems that can arise installing andusing the Tivoli Event Integration Facility. The logs and tracing utilities can helpyou determine the source of problems when they occur. Before systems even fail,you can configure the API to insure the delivery of events. Additionally, you canimprove the performance of event delivery with API configurations.

This chapter contains the following topics:v Message logsv Trace logsv Performance and availabilityv Common problems and scenarios

Message logsIn problem-solving situations, you need to understand how to interpret messagesand what actions you can take to resolve a problem. This section describes themessage log files so that you can troubleshoot problems in your environment.

To generate log messages for the Java API, you specify keywords in theconfiguration file. Use the LogLevel and LogFileName keywords to specify theamount and destination of messages.

For the C API, you specify the ed_diag_config_file keyword. See “Keywords” onpage 67 for more information about how to set the keywords.

Trace logsTrace logs assist you in determining why a problem is occurring. Trace loggingcaptures information about the operating environment when the Tivoli EventIntegration Facility fails to operate as intended. Customer Support personnel usethe information captured by trace loggers to trace a problem to its source or todetermine why an error occurred. These tools are not enabled by default. Becausetrace messages are intended for Customer Support, they are generally written to afile that can be viewed for later examination.

To generate trace messages for the Java API, you specify keywords in theconfiguration file. Use the TraceLevel and TraceFileName keywords to specify theamount and destination of tracing. These keywords also control tracing for statecorrelation.

For the C API, you specify the ed_diag_config_file keyword. See “Keywords” onpage 67 for more information about how to set the keywords

For additional information about trace logs, contact Customer Support.


Performance and availabilityTivoli Event Integration Facility provides the ability to control its performance andavailability for event processing.

To prevent overloading with event delivery, you can do the following:v Add timers for event deliveryv Specify the maximum number of events in the cache

When using timers, the Tivoli Event Integration Facility notifies the event receiverthat there are cached events. This occurs when the timer expires or when themaximum number of events is exceeded. Thus, the receiver can process the wholecache contents at once. See “Activating the cache” on page 14 for more informationabout configuring the cache.

Additionally, you can increase the availability of events by setting up backupservers. See “Configuring backup servers to deliver events” on page 14 for moreinformation.

Event reception connection parametersThe reception process creates a server socket that listens on a specified port. Thelistening process marks a connection-mode socket as accepting connections andlimits the number of outstanding connections in the queue of the listening socketto the value specified by the ConnectionsQueued value. The implementation mightinclude incomplete connections in the queue subject to the queue limit.Implementations can limit the length of the queued listening socket by specifyingConnectionsQueued.

TCP/IP will allow data to be sent and the connection closed by the sender beforethe receiving application can receive the data. The reception process eventuallyaccepts the connection and processes the data. ConnectionsQueued allows thesetypes of connections to be limited. Connection attempts are refused when TCP/IPcan no longer queue up connections.

The number of active connections handled by the reception process can be limitedby the ActiveConnections keyword. This prevents the reception process fromaccumulating too many connections that consume system resources.

If all of the initial connections are ConnectionOriented and the ActiveConnectionshave been reached, then no more connections are accepted by the receptionprocess. However, connections are still being considered by the TCP/IP up to theamount of ConnectionsQueued has been reached and if all ActiveConnections areconnection oriented then the state remains unchanged until the number of activeconnections is reduced to the amount specified by the percentage ofActiveConnections through the use of ActiveConnectionsSafety.

Note: The connections that were handled by TCP/IP (ConnectionsQueued) arediscarded when the program ends. The connections that are in theActiveConnections list are all closed and any data, residing on theconnections, is discarded.

Common problems and scenariosThe following are some common problems and scenarios you might encounterwhile using the Tivoli Event Integration Facility.


Building and running adaptersThe following scenarios can occur when there are problems building, compiling,and running the adapter:v I am having difficulty building a new TME adapter.

Cause: There could be problems with the code or the build environment.Remedy: Perform™ both of the following actions:– Build the program as both a TME adapter and as a non-TME adapter to

ensure that your build environment is properly set up.– Do the test builds as non-TME adapters until your code is working properly

and is ready for release. Non-TME adapters are easier to debug: the onlydifference between non-TME and TME adapters is the libraries (no codechanges).

v My endpoint adapter cannot access the libraries for the Tivoli Event IntegrationFacility.Cause: The endpoint adapter must have the system variables set to properlyaccess the libraries.Remedy: Set the system variables with the lcf_env.sh or lcf_env.cmd scripts.

v My Microsoft Windows NT® adapter has compile-time errors.Cause: There are multiple wsock32.lib files.Remedy: Use the FORCE:MULTIPLE option when compiling the Windows NTadapter. This forces the compiler to pick one file. See “Compiling the adapter”on page 24 for an example.

v I changed the configuration file, but my changes do not take effect.Cause: There could be improperly specified statements in the configuration file.

Chapter 6. Troubleshooting 37

Remedy: Review the following for the changed keywords:– Check for typos in the spelling of keywords.– Ensure that any blank spaces are enclosed in single quotation marks.– Verify that all class names in the configuration file are defined in the BAROC

file.v I received a LOG0014E error.

Cause: The system cannot find the file specified by the LogFileName keyword.Remedy: Correct the path name specified by the LogFileName keyword.

Making connections to the event serverThe following scenarios can occur when there are problems connecting to the eventserver:v I received a connection error when I use wpostzmsg or postzmsg. Or, I received

a file path error for the BufEvtPath keyword when using TECAgent.Cause: The error indicates that you might be using a user ID other thanAdministrator or root. Thus, your ID does not have the correct permissions tocreate and write the file specified by the BufEvtPath keyword.Remedy: Ensure that you have the correct permissions for creating the filespecified by the BufEvtPath keyword.

v My new TME adapter cannot contact the event server.Cause: There are Tivoli authorization issues.Remedy: Verify the TransportList or ServerLocation keywords in theconfiguration file.

Sending eventsThe following scenario can occur when there are problems sending events to theevent server:v My adapter is not sending all the events to the event server.

Cause: There is either a communication problem between the adapter and theevent server, or there is a problem internal to the adapter code.Remedy: Send events to a file instead of directly to the event server. Then, verifythe event delivery. The following steps describe how to do this:1. Set the TestMode keyword to YES in the adapter configuration file.2. Specify the file to receive the events with the ServerLocation keyword.3. Restart the adapter.4. Review the file specified by the ServerLocation keyword and check to see if

all the events appear there.

If all events appear in the file, then there is a communication problem with theevent server. Send the same events with the wpostzmsg command to verify thatthe event server can receive events. If the event server is able to receive theevents from the command, then check the communications between the adapterand the event server.

On the other hand, if the events are missing from the file, then there is probleminternal to the adapter. Check the adapter code.

Note: When you complete testing of the adapter, reset the TestMode keyword,so that events are sent to the event server and no longer directed to a file.


v I am using the wpostzmsg or postzmsg commands to send events, but they arenot arriving at the event server.Cause: The events are being sent to the cache on the adapter or gateway,because of one of the following situations:– A portmapper is in use on the sending side, but a portmapper is not in use

on the event server. For Windows systems, there is no portmapper daemon.– A non-valid port, host name, or event server was specified.

Remedy: Resolve the non-valid name or port issues.

Chapter 6. Troubleshooting 39

Appendix A. Application programming interfaces

The APIs for Tivoli Event Integration Facility are described in this section. Definedby C language functions and Java methods, the API helps you to build a customadapter or an application that receives events.

C language APIIn order to build a custom adapter in the C language, you must have a C compiler.The C language API is provided in library files. The API is described in thefollowing subsections:v tec_agent_getenvv tec_agent_initv tec_create_EIF_handlev tec_create_handlev tec_create_handle_cv tec_create_handle_rv tec_destroy_handlev tec_errnov tec_get_eventv tec_put_eventv tec_register_callback


tec_agent_getenv

Retrieves the value of the variable contained in the configuration file.

Synopsischar *tec_agent_getenv(char *keyword)

Argumentskeyword

The keyword variable to retrieve.

Examples#include "tec_eeif.h"char *serverLoc=tec_agent_getenv("ServerLocation")

Return CodesReturns a pointer to a string which is the value of the variable. Do not free thispointer. Returns a NULL if the keyword does not appear in the configuration file.


tec_agent_init

An initialization function that reads the configuration file and caches theinformation.

Note: The tec_agent_init function is the first function called to initialize the TivoliEvent Integration Facility module. Only call the tec_agent_init functiononce for each adapter, and call it before any of the other functions.

Synopsisint tec_agent_init(char *cfgfile)

Argumentscfgfile The full path to the configuration file.

Examples#include "tec_eeif.h"tec_agent_init(“config”);

Return CodesReturns 0 if successful.

Appendix A. Application programming interfaces 43

tec_create_EIF_handle

Establishes a handle for sending events to the event server or receiving eventsfrom a source with the first argument specifying a configuration file. A handle iscreated using the configuration information specified in the configuration file.Similar to tec_create_handle.

Synopsistec_handle_t tec_create_EIF_handle(char *cfgfile, int oneway,delivery_mode mode)


onewayUsed for managed node adapters only, and is used to designate whethercalls to tec_put_event returns exceptions to the caller in the event offailure. A value of one (1) means that exceptions, if any, are not returned tothe caller of tec_put_event because the caller does not wait for a responsefrom the oserv process. A value of zero (0) means that exceptions arereturned to the caller because the caller waits for the oserv process toreturn the success or failure of the method.

mode The possible values are the following:v submissionv reception

Use the submission mode when the handle is used for transmitting. Usethe reception mode when the handle is used for receiving.

Examples#include "tec_eeif.h"if((th =tec_create_EIF_handle("config",0,submission))==NULL){

fprintf(stderr,"%s:tec_create_handle failed errno=%d \n ",progname,tec_errno);

exit(1);}

Return CodesA handle to an internal data structure. The handle is used in calls to other APIfunctions.


tec_create_handle

Establishes a handle for sending events to the event server.

Synopsistec_handle_t tec_create_handle(char *location, unsigned short port, int oneway,tec_delivery_type type)

Argumentslocation

The host name or host protocol address of the event server for a non-TMEversion of Tivoli Event Integration Facility, or @EventServer[#region_name]for a TME version.


port The port the event server listens on for non-TME versions.

type The possible values are the following:v connection_lessv connection_orientedv use_default

The use_default value reads the setting from the configuration file for theConnectionMode keyword and sets up a connectionless handle if theConnectionMode keyword is not specified.

Examples#include "tec_eeif.h"if((th = tec_create_handle(tec_server, port, oneway, type)) == NULL) {

fprintf(stderr, “%s: tec_create_handle failed errno=%d\n”,progname, tec_errno);

exit(1);

}

Return CodesA handle to an internal data structure. The handle is used in calls totec_put_event. If the location is NULL, the configuration file ServerLocation entryis used to derive the location. If the port is zero, the ServerPort entry is used, ifany; or else the portmapper is queried for the port on which the event serverlistens.


tec_create_handle_c

Establishes a handle for sending events to the event server or receiving eventsfrom a source with the first argument specifying a configuration file. A handle iscreated using the configuration information specified in the configuration file.Similar to tec_create_handle.

Synopsistec_handle_t tec_create_handle_c (char *cfgfile,char *location, unsigned short port, intoneway, tec_delivery_type type, delivery_mode mode)


locationThe host name or host protocol address of the event server for a non-TMEversion of Tivoli Event Integration Facility, or @EventServer[#region_name]for a TME version.

mode The possible values are the following:v submissionv reception

Use the submission mode when the handle is used for transmitting. Usethe reception mode when the handle is used for receiving.





Examples#include "tec_eeif.h"if((th=tec_create_handle_c("config","tecserver.com",5529,0,connection_less,submission))

==NULL){fprintf(stderr,"%s:tec_create_handle failed errno=%d \n ",

progname,tec_errno);exit(1);

}

Return CodesA handle to an internal data structure. The handle is used in calls totec_put_event. If the location is NULL, the configuration file ServerLocation entry


is used to derive the location. If the port is zero, the ServerPort entry is used, ifany; or else the portmapper is queried for the port on which the event serverlistens.


tec_create_handle_r

Establishes a handle for sending events to the event server with the first argumentspecifying a configuration file. A handle is created using the configurationinformation specified in the configuration file. Similar to tec_create_handle.

Synopsistec_handle_t tec_create_handle_r (char *cfgfile,char *location, unsigned short port, intoneway, tec_delivery_type type)


locationThe host name or host protocol address of the event server for a non-TMEversion of Tivoli Event Integration Facility, or @EventServer[#region_name]for a TME version.





Examples#include "tec_eeif.h"th = tec_create_handle_r(“config”,“localhost”,1234, 0, use_default)) == NULL) */

Return CodesA handle to an internal data structure. The handle is used in calls totec_put_event. If the location is NULL, the configuration file ServerLocation entryis used to derive the location. If the port is zero, the ServerPort entry is used, ifany; or else the portmapper is queried for the port on which the event serverlistens.


tec_destroy_handle

Destroys the handle to the event server created by tec_create_handle,tec_create_handle_c, tec_create_EIF_handle, and tec_create_handle_r and closesany established connections.

Synopsisvoid tec_destroy_handle (tec_handle_t th)

Argumentsth The tec handle returned from a call to a create_handle function.

Examples#include "tec_eeif.h"tec_destroy_handle(th);


tec_errno

When a function returns an error, tec_errno is set to the appropriate error code.

Synopsisextern int tec_errno


tec_get_event

Allows an application to receive events. It receives events from the configuredtransport, on demand. The data returned can contain more than one event. Use theed_scan_n utility to determine the number of events. The memory allocated for theevent must be freed.

Synopsislong tec_get_event (tec_handle_t th, unsigned char ** event_message);

Argumentsth The event server handle returned from a call to a create_handle function.

event_messageContains the event data of the message received from a transport.

Examples#include "tec_eeif.h"char *event;long event_len;int rc;

event=NULL;event_len = tec_get_event(th, &event);if (event && event_len){n =ed_scan_n (event,event_len);}if (event)

free(event)

Return CodesReturns the length of the event message. Returns 0 (zero) when no events areavailable.


tec_put_event

Sends an event to the event server.

Synopsislong tec_put_event (tec_handle_t th, char *event)

Argumentsevent The character string representing the event.

th The event server handle returned from a call to a create_handle function.

Examples#include "tec_eeif.h"if ( tec_put_event(th, event_string) == -1 {

fprintf(stderr, “%s: tec_put_event failed, errno=%d\n”,progname, tec_errno);

exit(1);

}

Return CodesReturns the number of bytes sent to the event server, other applications listeningfor events, or the cache file. A zero return means the event is filtered out. Anegative return indicates an error.


tec_register_callback

Allows an application to receive events through an upcall. The application registersa callback, passing as a parameter the method that handles the received events.The syntax for tec_event_callback is as follows:int (*tec_event_callback)(tec_handle_t h, unsigned char *msg, long _msg_len);

The data returned can contain more than one event. Use the ed_scan_n utility todetermine the number of events returned. The memory allocated for the eventmust be freed.

The tec_event_callback function returns –1 or zero (0). A zero indicates that therewere no errors and that the event has been processed. A –1 indicates that there wasa problem processing the event and to not remove it from the cache if one isconfigured.

Synopsisvoid tec_register_callback(tec_handle_t th, tec_event_callback *fn)

Argumentsth The event server handle returned from a call to a create_handle function.

fn The function to be called when the event arrives.

Examples#include "tec_eeif.h"int on_message (tec_handle_t th, unsigned char *event, long event_len){long n;if (event && event_len){

int i;char *ev;long len;long idx = 1;

n =ed_scan_n (event,event_len);for(i =0;i <n;i++,idx++){

ev =(char *)ed_scan_get_n ((char *)event, idx, event_len, &len);free (ev);

}}return 0;}

tec_register_callback(th,on_message)


Utilities for the C APIThe following are the utilities for the C API. They are described in the followingsubsections.v ed_scan_get_nv ed_scan_nv ed_sleep


ed_scan_get_n

Events received through the reception API can contain more than one event. Usethis function to get the nth event from the packet.

Synopsischar * ed_scan_get_n (char *packet,long index,long packet_len, long *result_len);

Argumentspacket The pointer returned by tec_get_event or passed to the callback when

tec_register_callback is used.

index The nth element in the packet starting at 1.

Packet_lenThe maximum length of the packet to search.

Result_lenContains the resulting length of the packet.

Examples#include "tec_eeif.h"char *packagechar *ev;int i;long n,len,idx=1;

package=tec_get_event(th);

n = ed_scan_n (package, strlen (package));for (i = 0; i < n; i++, idx++){ev =(char *) ed_scan_get_n ((char *) package, idx, strlen (package),&len);free (ev);}

Return CodesReturns a pointer to a newly allocated buffer containing the requested event. Thispointer must be freed.


ed_scan_n

Events received through the reception API can contain more than one event. Usethis function to determine the number of events contained in the packet.

Synopsislong ed_scan_n (char *packet, long packet_len );

Argumentspacket The pointer returned by tec_get_event or passed to the callback when

tec_register_callback is used.

Packet_lenThe maximum length of the packet to search.

Examples#include "tec_eeif.h"char *packagechar *ev;int i;long n,len,idx=1;

package=tec_get_event(th);

n = ed_scan_n (package, strlen (package));for (i = 0; i < n; i++, idx++){ev =(char *) ed_scan_get_n ((char *) package, idx, strlen (package),&len);free (ev);}

Return CodesReturns the number of events; zero (0) if none are found; –1 when an error occurs.


ed_sleep

Pauses running for the specified duration; allows threads to switch. This utility iscalled by managed node adapters in the main loop to release the execution of theinternal threads.

Synopsisint ed_sleep (long seconds, long millis);

Argumentsmillis Specifies the amount of milliseconds.

secondsSpecifies the amount of seconds.

Examples#include "tec_eeif.h"/* pause for 3.5 seconds */ed_sleep (3, 500);

/* sleep duration is zero but yields briefly so other threads can run */ed_sleep (0, 0);

Return CodesReturns zero (0).


Java language APIIn order to build an adapter in Java, you must have the Java 1.3.1 compiler. TheJava API is provided in Jar files. The API is described in the following subsections:v disconnectv getConfigValv onMessagev receiveEventv registerListenerv sendEventv TECAgentv TECEvent


disconnect

Closes any open connection to the event server.

Synopsisdisconnect()

Examplespublic synchronized void disconnect()


getConfigVal

Retrieves the value of a variable contained in the configuration file.

SynopsisgetConfigVal (String key)

Argumentskey Specifies the configuration keyword label.

Examplespublic String getConfigVal(String key)

Return CodesReturns the string value associated with key in the configuration file used toinitialize TECAgent. If key is not in the configuration file, null is returned. Forkeywords such as Filter, which have multiple values, only the last value specifiedin the configuration files is returned.


onMessage

Handles the events received asynchronously from the API.

SynopsisonMessage (String event)

Argumentsevent A string contained in the event, which is returned to the application.

Examplespublic void onMessage( String event )

Return CodesThe application returns true if the received event was processed with success,indicating to the API to remove the event from the cache or persistent log, or bothto avoid resending the event in the future.

The application returns false if the event was not processed with success, indicatingto the API to resend the event to the event server for further processing. In thiscase, the event is not removed from the cache or persistent log, or both.


receiveEvent

Enables an application to receive events synchronously. Receives events from allthe event servers specified in the configuration file used to initialize TECAgent. Seealso the registerListener method.

SynopsisString receiveEvent()

Examplespublic synchronized String receiveEvent()

Return CodesReturns event data that was received by this API. The delimiterTECEvent.TECAD_EVENT_END_CHAR (A) separates the events returned in thisstring.


registerListener

Registers the calling application as a listener, enabling the asynchronous receptionof events. You must pass an object that implements the IEventProcessing interfaceas a parameter. See also the receiveEvent method.

SynopsisregisterListener (IEventProcessing)

ArgumentsIEventProcessing

The application class that implements the IEventProcessing callback.

Examplespublic void registerListener (IEventProcessing)


sendEvent

Sends events to the event servers specified in the configuration file used toinitialize TECAgent. You must pass a serialized TECEvent as a parameter. If theBufferEvents=YES keyword is specified, the events are cached and persistentbefore they are sent.

SynopsissendEvent (String event)

Argumentsevent Event data to be sent to the event server. If event is non-null, it must be at

least TECEvent.MIN_EVENT_LEN characters long, or sendEvent returnsimmediately with an error.

Examplespublic synchronized int sendEvent(String event)

Return CodesReturns the number of bytes sent to the event server, other applications listeningfor events, or the cache file. A zero return means the event is filtered out. Anegative return indicates an error.

When using state correlation, the return code is the number of bytes sent to statecorrelation rather than the number of bytes sent to the event server, otherapplications listening for events, or the cache file.


TECAgent

Accesses the configuration file and sets the transport mechanism. It is the top-levelobject that enables the sending and receiving of events to and from the eventserver.

SynopsisTECAgent (Reader configStream, int deliveryMode, boolean oneway)

ArgumentsconfigStream

Object that reads the configuration keywords.

deliveryModeSpecifies the delivery mode. The values are SENDER_MODE andRECEIVE_MODE.

onewayUsed for connections to TME adapters on managed nodes. Designateswhether calls to sendEvent() returns exceptions to the caller in the event offailure. A value of one (1) means that exceptions are not returned to thecaller; a value of zero (0) means that exceptions are returned to the caller.

Examplespublic TECAgent(Reader configStream, int deliveryMode,

boolean oneway)

Return CodesAn exception is raised if the TECAgent cannot be created.


TECEvent

Encapsulates the code for parsing event definitions into a class name andattribute=value pairs.

SynopsisTECEvent()

init(String event)

Argumentsevent The event string to be parsed. Here are some examples of valid event

strings:v Class1;msg=’text.’;hostname=artemis;source=TEC;ENDv Class2;ENDv Class3;msg=theMessage;END

Examplespublic boolean init(String event);

Return CodesThe return code for the init() call is true when the event string is parsedsuccessfully and false if it is not.


Appendix B. Keywords for configuration files

This appendix provides reference information about keywords for configurationfiles.

KeywordsKeywords use the following format: keyword=value

Type each keyword on a separate line. Do not use blank spaces in keywordstatements unless enclosed in single quotation marks. Do not use class names thatare not defined in a BAROC file with configuration options.

Note: Adapters do not issue error messages for misspelled keywords or keywordsset to a value that is not valid.

A configuration file can contain the following keywords, which are common tomost adapters.

Note: Not all keywords apply to all adapters, and some adapters have additionalkeywords specific to them. See the Tivoli Enterprise Console Adapters Guide fordescriptions of these keywords.

AdapterCdsFile=pathSpecifies the full path name of the CDS file. This keyword is required if theCDS file is not in the same directory as the configuration file.

AdapterErrorFile=pathSpecifies the full path name of the error file. This keyword is required ifthe error file is not in the same directory as the configuration file.

APPEND_CLASSPATH=string

Specifies the string that is appended to the CLASSPATH environmentvariable before the Java-based State Correlation is called. The string isappended using the appropriate delimiter:, semicolon (;) for Windowssystems or colon (:) for UNIX systems. The string must contain valid datafor your environment; for example, APPEND_CLASSPATH=c:\my_product\my_java.class; d: \my_product\my_jar .jar for Windowssystems 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 isappeneded to the list of jar files needed for State Correlation. For anadapter written in C, the specified string is appended to the systemenvironment CLASSPATH.

Note: The system environment CLASSPATH is not changed. ThisCLASSPATH information is passed to Java during the StateCorrelation initialization. This keyword can be specified only once inyour configuration file.

APPEND_JVMPATH=stringSpecifies the string that is appended to the dynamic library pathenvironment variable before the Java-based state correlation is called. Thestring is appended using the appropriate delimiter: semi-colon (;) for


Windows systems or colon (:) for UNIX systems. The string must containvalid data for your environment; for example, APPEND_JVMPATH=c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windowssystems or APPEND_JVMPATH=/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. Thiskeyword is valid only for adapters written in C and is appended to theappropriate dynamic library path environment variable. For theenvironment variable for each operating system, see Table 9 on page 28.

Note: The system dynamic library path environment variable is notchanged. This keyword can be specified only once in yourconfiguration file.

BufEvtMaxSize=sizeSpecifies the maximum size, in kilobytes, of the adapter cache file. Thedefault value is 64. The cache file stores events on disk when they cannotbe sent to the event server.

The BufEvtMaxSize keyword is optional.

BufEvtPath=pathnameSpecifies the full path name of the adapter cache file. On endpointadapters, the BufEvtPath keyword uses the $TIVOLIHOME variable toresolve differences in file locations and drive letters across variousenvironments. The variable uses a path relative to the endpoint installation.The Adapter Configuration Facility defines $TIVOLIHOME on eachendpoint; you cannot change its value.

Table 11. 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 keywordalso specifies the path to store events for state correlation. Tivoli EventIntegration Facility adds the prefix _sc to the specified file name. Theprefix differentiates the adapter cache file from the event storage path forstate 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 EventIntegration Facility, ensure that each application has unique valuesfor the path name.

BufferEvents=YES | NOSpecifies how event buffering is enabled.

YES Stores events in the file specified by the BufEvtPath keyword.

NO Does not store or buffer events.


If UseStateCorrelation=YES and BufferEvents=YES, the API also storesevents in files that are specified with the BufEvtPath keyword. TheStateCorrelationMaxFileSize and StateCorrelationTotalSize keywordscontrol the size and number of files.

The value is not case-sensitive. The default value is YES. This keyword isoptional.

BufferFlushRate=events_per_minuteSpecifies the number of events that are sent per minute. Once the adapterhas recovered the lost connection, and there are events in the buffer, theevents 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_lessSpecifies the connection mode to use to connect to the Tivoli EnterpriseConsole gateway or the event server. The default value is connection_less,except for the Tivoli Enterprise Console gateway, which hasconnection_oriented as the default value.

connection_orientedA connection is established at adapter initialization and ismaintained for all events sent. A new connection is establishedonly if the initial connection is lost. The connection is discardedwhen the adapter is stopped. This option can be abbreviated to coor CO.

connection_lessA new connection is established and discarded for each event orgroup of events that is sent.


ed_diag_config_file=filenameThe filename file must be present for logging and tracing to occur. To enablelogging, specify error or warning in the filename file. To enable tracing,specify trace0, trace1, or trace2 in the filename file. The filename file canbe either fully qualified or relative to the directory where the adapter isrunning. A sample file, .ed_diag_config, is in the EIFSDK directory on theIBM Tivoli Enterprise Console TME New Installations CD.

Each level of logging or tracing also includes all levels below it. Forexample, when you specify warning logging, error logging automatically isenabled.

Note: Be aware that increasing the level of tracing produces a large traceoutput. You can configure whether or not the file is recreated onrestarts.


Filter Works with the FilterMode keyword to determine how events are filtered.An event matches a Filter statement when each attribute=value pair in theFilter statement is identical to the corresponding attribute=value pair in theevent.

Appendix B. Keywords for configuration files 69

A Filter statement must contain the event class, and optionally can includeany other attribute=value pair that is defined for the event class. The formatof 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 casesensitive.


FilterCacheWorks with the FilterMode and Filter keywords to determine which eventsare stored in the cache when events cannot be sent successfully to theevent server. To store events in the cache, you must set BufferEvents=YES.An event matches a FilterCache statement when each attribute=value pair inthe FilterCache statement is identical to the corresponding attribute=valuepair in the event.

A FilterCache statement must contain the event class (class_name) and caninclude any attribute=value pair that is defined for that event class. Theformat 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 casesensitive. You must specify the Filter keyword, when you use theFilterCache keyword. Additionally, the FilterCache statement must specifythe same class or subset of classes that the Filter statement specifies.


Note: When using the FilterCache keyword with endpoint adapters andthe Tivoli Enterprise Console gateway, you must set the filteringstatements at both locations to the same specifications.

FilterMode=IN | OUTSpecifies whether events that match a Filter or FilterCache statement aresent to the event server (FilterMode=IN) or discarded (FilterMode=OUT).The default value is OUT. The valid values are IN or OUT, without regardfor case. If you set FilterMode=IN, you must have one or more Filter andFilterCache statements defined.

For information about how to use filtering keywords to send, cache, anddiscard events, see “Filtering with configuration files” on page 31.


FQDomain= YES | NO | fqdomainSpecifies how the adapter should set the value of the fqhostname attributeof events sent to the event server. This attribute is used to specify the fullyqualified host name of the originating host. Possible values for thiskeyword are:

YES The adapter attempts to determine the fully qualified host name. Ifthis is successful, the fqhostname attribute is set to this value; ifnot, the attribute has a null value.

NO The fqhostname attribute has a null value. This is the default valueif the FQDomain keyword is not specified.


fqdomainfqdomain is appended to the host name, and the resulting string isused as the value of the fqhostname attribute. If the host namecontains 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_secondsSpecifies the number of seconds to wait before re-sending the UDP call fora 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_microsecondsSpecifies the number of microseconds to add to the seconds specified withthe getport_timeout_seconds keyword. The default value is 50 000microseconds.

getport_total_timeout_seconds=num_secondsSpecifies the number of seconds to wait on getting a port after making acall to the portmapper. The default value is zero (0) seconds.

getport_total_timeout_usec=num_microsecondsSpecifies the number of microseconds to add to the seconds specified withthe getport_total_timeout_seconds keyword. The default value is 50 000microseconds.

LogFileName=pathnameSpecifies the full path name of the log file for the Java API. The defaultlocation for the file is $TIVOLIHOME/tec/eif.log.

If UseStateCorrelation=YES, the LogFileName keyword also defines thepath to store the log file for state correlation. Tivoli Event IntegrationFacility adds the prefix _sc to the specified file name. The prefixdifferentiates the log file for the Java API from the log file for statecorrelation. 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 findthe path specified)


LogLevel=levelSpecifies whether the Java API generates log messages or not. By default,no messages are generated. Specify ALL to generate messages. If youspecify any other value or no value, the API does not generate messages.


MaxPacketSize=bytesSpecifies the number of bytes to be sent at the rate specified by theBufferFlushRate keyword. The default value is zero (0), where one event issent at a time.


NO_UTF8_CONVERSION=YES | NOSpecifies whether Tivoli Event Integration Facility encodes event data in


UTF-8. When this keyword is set to YES, Tivoli Event Integration Facilitydoes not encode event data in UTF-8. The data is assumed to already be inUTF-8 encoding when passed to Tivoli Event Integration Facility. It does,however, prepend the flag indicating that the data is in UTF-8 encoding ifthe 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 eventserver host or in UTF-8 encoding. Event server host versions earlier thanthe Tivoli Enterprise Console 3.7 product do not support UTF-8 encodingof events. The following values are not case-sensitive:

YES Disables UTF-8 encoding and allows the adapter to communicatewith event server host versions earlier than the Tivoli EnterpriseConsole 3.7 product. When this keyword is set to YES, you mustalso specify the Pre37ServerEncoding keyword.

NO The adapter sends events in UTF-8 encoding. The default value isNO.


Pre37ServerEncoding=language

Determines which language to use when a non-TME adaptercommunicates with a non-UTF-8 event server host (versions earlier thanthe Tivoli Enterprise Console 3.7 product). This keyword is active onlywhen the Pre37Server keyword is set to YES.


PREPEND_CLASSPATH=string

Specifies the string that is prepended to the CLASSPATH environmentvariable before the Java based State Correlation is called. The string isprepended using the appropriate delimiter: semicolon (;) for Windowssystems or colon (:) for UNIX systems. The string must contain valid datafor your environment; for example, PREPEND_CLASSPATH=c:\my_product\my_java.class; d: \my_product\my_jar .jar for Windowssystems 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 prependedto the list of jar files needed for State Correlation. For an adapter written inC, the specified string is prepended to the system environmentCLASSPATH.

Note: The system environment CLASSPATH is not changed. ThisCLASSPATH information is passed to Java during the StateCorrelation initialization. This keyword can be specified only once inyour configuration file.

PREPEND_JVMPATH=stringSpecifies the string that is prepended to the dynamic library pathenvironment variable before the Java-based state correlation is called. Thestring is prepended using the appropriate delimiter: semicolon (;) forWindows systems or colon (:) for UNIX systems. The string must containvalid data for your environment; for example, PREPEND_JVMPATH=c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows


systems or PREPEND_JVMPATH=/my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. Thiskeyword is valid only for adapters written in C and is prepended to theappropriate dynamic library path environment variable. For theenvironment variable for each operating system, see Table 9 on page 28.

Note: The system dynamic library path environment variable is notchanged. This keyword can be specified only once in yourconfiguration file.

RetryInterval=timeout

When ConnectionMode=connection_oriented, and the connection to theevent server is lost, an adapter waits the specified number of secondsbefore re-attempting to connect to the primary or secondary servers, or tobuffer the events. While the adapter is waiting for the expiration of thisinterval, no new events are processed by the adapter.

This option allows an adapter to send all events to the primary eventserver even if the primary event server is stopped briefly, such as whenloading a new rule base.

If you use this keyword to wait for restarting an event server, set the valuefor a period of time longer than necessary for the event server to bestopped and then restarted.

This keyword is optional. The default value is 120 seconds.

ServerLocation=hostSpecifies the name of the host on which the event server or TivoliEnterprise Console gateway is installed. The value of this field must be oneof the formats shown in Table 12, depending on whether the adapter is aTME adapter or a non-TME adapter, and whether the event server is partof an interconnected Tivoli management region:

Table 12. Formats for the ServerLocation keyword

Adapter Type Format

TME @EventServer

TME in an interconnectedTivoli management region

@EventServer#region_name

non-TME host_name or IP_address. Use the dotted formatfor IP_address.

For TME adapters on managed nodes and non-TME adapters, theServerLocation keyword can contain up to eight values, separated bycommas. The first location is the primary event server, while others aresecondary servers to be used in the order specified when the primaryserver is down.

For endpoint adapters, secondary event servers, if any, are defined in theTivoli Enterprise Console gateway configuration file. Only specify aprimary event server in the configuration file for an endpoint adapter.

For a non-TME adapter, the default value is localhost. For a TME adapteron a managed node, the default value is @EventServer. A TME adapter onan endpoint, by default, uses the configuration on the Tivoli Enterprise


Console gateway. See the IBM Tivoli Enterprise Console User’s Guide for moreinformation about the Tivoli Enterprise Console gateway.

For endpoint adapters, if you use an IP name or address in theServerLocation value, then the Tivoli Enterprise Console gateway uses thatvalue to send the event using non-Tivoli communication to the server.

For non-TME adapters, the ServerLocation keyword can contain the IPname or address of the Tivoli Enterprise Console gateway if reception ofevents from non-TME adapters is enabled at this gateway.

The ServerLocation keyword is optional and not used when theTransportList keyword is specified.

Note: The ServerLocation keyword defines the path and name of the filefor logging events, instead of the event server, when used with theTestMode keyword.

ServerPort=numberSpecifies the port number on which the event server or Tivoli EnterpriseConsole gateway listens for events. Set this keyword value to 0, the defaultvalue, unless the portmapper is not available on the event server, which isthe case if the event server is running on a Microsoft Windows system orthe event server is a Tivoli Availability Intermediate Manager (see thefollowing note). If the port number is specified as zero (0) or it is notspecified, the port number is retrieved using the portmapper.

Note: Portmapper is not supported for reception of events from non-TMEadapters at the Tivoli Enterprise Console gateway. If your non-TMEadapter is sending events to this gateway, then you must code theServerPort keyword to match the value in the gwr_ReceptionPortkeyword in the Tivoli Enterprise Console gateway configuration file.

The ServerPort keyword can contain up to eight values, separated bycommas. 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 UNIXevent servers are specified with the ServerLocation keyword). Fornon-TME adapters that send events to a Windows event server or a TivoliAvailability Intermediate Manager, specify one value for each event serverdefined with the ServerLocation keyword.

The ServerPort keyword is optional when the event server is running onthe UNIX operating system, but mandatory when running on Windowsoperating system. It is not used when the TransportList keyword isspecified.

Note: If the event server is running on Windows operating system: There is noportmapper daemon on a Windows system that allows the adapterto query the reception port at run time. The event server listens on afixed reception port (tec_recv_agent_port in .tec_config file) forconnection and adapter input. Set the ServerPort keyword to thevalue of the tec_recv_agent_port entry in the .tec_config file in the$BINDIR/TME/TEC directory. The default value is 5529. The TivoliAvailability Intermediate Manager never uses the portmapper; the


Tivoli Availability Intermediate Manager server listens on a fixedport set in the Tivoli Availability Intermediate Manager graphicaluser interface.

StateCorrelationCleaningInterval=millisecondsSpecifies, in milliseconds, how often state correlation removes unnecessaryentries from its event storage files. The default value is one minute.


StateCorrelationConfigURL=pathnameSpecifies the directory and file name where the configuration for statecorrelation is stored. On Windows systems, an example of the path is asfollows: file:C:\work_dir\tstate\tecroot.xml. On UNIX systems, anexample of the path is as follows: file:///work_dir/tstate/tecroot.xml.

This keyword is required when the UseStateCorrelation keyword is set toYES.

StateCorrelationMaxFileSize=kilobytesSpecifies the maximum size, in kilobytes, for each event storage file createdby state correlation. This is an approximate value, due to the variable sizeof events.


StateCorrelationTotalSize=kilobytesSpecifies the maximum value, in kilobytes, allowed for the entire cachingmechanism for state correlation. This is an approximate value, due to thevariable size of events.

Note: The value must be at least double the value specified for theStateCorrelationMaxFileSize keyword. Thus, the doubled value cansupport at least two files:v Current event cache file, persist1.outv At least one file holding archived events, archive1.out

When calculating disk space for this cache, verify that you have a buffer of10% of the specified values, with a minimum of 4 KB. This configurationensures that the cache does not run out of disk space.

When the state correlation cache reaches its limit (the value specified bythis keyword), the following occurs:1. All subsequent events return a suspend exception to Tivoli Event

Integration Facility. In turn, Tivoli Event Integration Facility returns anerror to the application.

2. A forced cleanup of the cache is started; all removed events areeliminated from the persistence cache.

3. Remaining events are recovered and returned to Tivoli EventIntegration Facility. Then, Tivoli Event Integration Facility forwardsthose events.

4. The state correlation cache is re-initialized, and event processingresumes.


TestMode=YES | NOSpecifies 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=pathnameSpecifies the full path name of the trace file for the Java API. The defaultlocation of the file is $TIVOLIHOME/tec/eif.trc.

If the UseStateCorrelation keyword is set to YES, the TraceFileNamekeyword also defines the path to store tracing for state correlation. TivoliEvent Integration Facility adds the prefix to the specified file name. Theprefix differentiates the trace file for the Java API from the trace file forstate 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 findthe path specified)


TraceLevel=levelSpecifies whether the Java API generates trace messages or not. By default,no messages are generated. Specify ALL to generate messages. If youspecify any other value or no value, the API does not generate messages.


TransportList=type_name,...Specifies the user-supplied names of the transport mechanisms, separatedby commas. When a transport mechanism fails for sender applications, theAPI uses the following transport mechanisms in the order specified in thelist. For receiving applications, the API creates and uses all the transportmechanisms.

Note: This keyword is supported only for Solaris, HP, AIX, Linux, andWindows adapters. It is not supported for other adapters.

This keyword is optional. If it is specified, the transport type and channelfor each type_name must be specified using the Type and Channelskeywords:

type_nameType=LCF | SOCKET | TMESpecifies the transport type for the transport mechanism specifiedby the TransportList keyword.

This keyword is required.

The server and port for each channel_name are specified by theServerLocation and Port keywords.

type_nameChannels=channel_name,...Specifies the user-supplied names of the channels for the transportmechanism specified by the TransportList keyword, separated bycommas.

This keyword is required.

Depending on the Type specified (LCF, SOCKET, or TME), also useone or more of the following keywords:


channel_namePort=numberSpecifies the port number on which the transportmechanisms server listens for the specified channel (set bythe Channel keyword). When this keyword is set to zero(0), the portmapper is used. This keyword is requiredwhen the Type keyword is set to SOCKET. It is optional forendpoint adapters.

channel_namePortMapper=YESEnables the portmapper for the specified channel. Thisoptional keyword is valid only when the transport type isset to SOCKET.

channel_namePortMapperName=nameIf the portmapper is enabled, specifies the name of theportmapper. This optional keyword is valid only when thetransport type is set to SOCKET.

channel_namePortMapperNumber=rpc_idSpecifies the ID registered by the remote procedure call.This optional keyword is valid only when the transporttype is set to SOCKET.

channel_namePortMapperVersion=version_numberIf the portmapper is enabled, specifies the version of theportmapper. This optional keyword is valid only when thetransport type is set to SOCKET.

channel_nameServerLocation=server[region]Specifies the name of the event server and region on whichthe server for transport mechanisms is located for thespecified channel. The channel is set by the Channelkeyword. This keyword is required when the Typekeyword is set to TME, LCF, or SOCKET. See Table 12 onpage 73 for valid formats of the server and region fields.

channel_nameTMEHost=hostnameFor the Java API only, specifies the host name of themanaged node where the event server resides. This is arequired keyword when the Type keyword is set to TME.

channel_nameTMEPassword=passwordFor the Java API only, specifies the password for the Tivoliadministrator used to connect to the managed node. Thiskeyword is required when the Type keyword is set to TME.

channel_nameTMEPort=numberFor the Java API only, specifies the port number for themanaged node. The default value for this keyword is 94.This keyword is required when the Type keyword is set toTME.

channel_nameTMEUserID=nameFor the Java API only, specifies the Tivoli administrator forthe managed node. The required authorization role is user.This keyword is required when the Type keyword is set toTME.


UseStateCorrelation=YES | NOSpecifies if the API calls the state correlation engine. The default value isNO. If this keyword is set to YES, the BufferEvents and BufEvtPathkeywords control state correlation.


WIDTHSTRMEANING=YES | NOIndicates how the length modifier is interpreted, as follows:

NO Interprets the length modifier as a truncation indication; that is, itmatches the full string and truncates the associated variable to thelength 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 thestring to match.


Notices

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

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

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

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

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, 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 beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

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


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

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

IBM 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 materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

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

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

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

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

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


modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not appear.

TrademarksThe following terms are trademarks of International Business MachinesCorporation in the United States, other countries, or both:

AIX OS/390 Tivoli Enterprise ConsoleIBM Tivoli TMEIBM Logo Tivoli LogoOpenEdition Tivoli Enterprise™

Microsoft, Windows, and Windows NT are registered trademarks of MicrosoftCorporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks 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 othercountries.

Other company, product, and service names may be trademarks or service marksof others.

Notices 81

Index

Special characters.baroc files

See BAROC files 19.conf files

See configuration files 19.ed_diag_config file 69.rls files

See rules 19.xml files

See XML files 19' (single quotation mark) 67

Aactivating the cache 14ActiveConnections keyword 16ActiveConnectionsSafety keyword 16adapter built with the C API, Compiling

the 25adapter built with the Java API,

Compiling the 25Adapter Configuration Facility 68AdapterCdsFile keyword 67AdapterErrorFile keyword 67adapters

buildingAPIs 41configuration 27event classes 21event delivery 21event identification 20installation 27overview 19programming 21summary 6testing 27

described 1endpoint

LCF_BINDIR 27libraries 25state correlation 33system variables, setting 25transport options 11

event flow 2example code 23files, list 19linking to required libraries 25managed node

libraries 26, 28state correlation 33transport options 12

monitoring sources 3non-TME 4, 12, 26overview 3required libraries 25TME 3, 28

adapters built with the Event IntegrationFacility Java API, Running 28

adapters, Building non-TME andendpoint 21, 22

APPEND_CLASSPATH keyword 67APPEND_JVMPATH keyword 67application built with the C API,

Configuring a reception 16attributes

overview 2authorization roles

adapters 22availability, events 36

Bbackup

servers 14, 36, 73BAROC files

class names in configuration files 67described 4, 19event strings, creating 21

Basic Recorder of Objects in C (BAROC)See BAROC files 4

blank spaces 67books

see publications v, viiBufEvtMaxSize keyword 14, 68BufEvtPath keyword 12, 38, 68buffer files 32, 68BufferEvents keyword 14, 32, 68BufferFlushRate keyword 14, 69building adapters 21, 41Building non-TME and endpoint

adapters 21, 22built with the C API, Configuring a

reception application 16

CC API, Compiling the adapter built with

the 25C API, Configuring a reception

application built with the 16C API, overview 6cache

activating 14description 13endpoint adapters 68event reception 13filtering 32, 70keywords 68, 69overview 14path 68rate to send events 14, 69, 71size 14, 36

cache, eventsize 68

callsSee functions 42

CDS fileslocation 67

Channels keyword 76channels, event delivery 14

class namesEDException 8EIFException 8

classes, eventsSee event classes 4

CLASSPATH environment variable 34com.tivoli.tec.eif.* file 8com.tivoli.tec.event_directory.* file 8commands

postzmsg 12wpostzmsg 12

communicationsAPIs 22, 23with event servers 23

compiling adapters 24configuration files

APIs 22, 23described 19example, cache 14example, event delivery 15keywords 67overview 31

connection parameters, Eventreception 36

ConnectionMode keyword 69connections

connection-oriented delivery 11connectionless delivery 11keywords 69, 73non-TME 11options 11retry 73TME 11

ConnectionsQueued 17consoles, events 20conventions

typeface viiicorrelation, state

See state correlation 33customer support

see software support vii

Ddaemon, portmapper 16, 74, 77data transfer functions 23databases

event 20DBCS 28debugging

See troubleshooting 35definitions, events 21directory names, notation ixdirectory structures under EIFSDK: bin,

contrib, default_sm, include, jars,javadoc, lib, samples 7

discarding events 31disconnect function 23, 59double-byte characters 28dropping events 31


Eed_diag_config_file keyword 69ed_scan_get_n utility 55ed_scan_n utility 56ed_sleep utility 57eif.log file 71EIFSDK 7encoding, UTF-8 28, 71, 72endpoint adapters

cache 68event flow 2libraries 25state correlation 33transport options 11where to run from 27

entries, filters 31environment variables

CLASSPATH 34environment variables, notation ixerror files

location 67error messages 67evd.jar file 28, 34event classes

default classes 21defining 21described 21filtering 31hierarchy 21names 21, 67

event consoles 20event database 20event delivery

backup servers 14channels 14configuration files, example 15connection options 11overloading 36overview 11selecting methods 21test options 12timers 36transport options 11

Event Integration Facility 22Event Integration Facility Java API,

Running adapters built with the 28event listener 12Event reception connection

parameters 36event servers

backups 36connections, when stopped or

started 73described 1, 5event flow 2files 20list of backups 13port number 74

eventsavailability 36buffer file 68child 33class definition, base 4definitions 21delivery methods 11described 1filtering 5

events (continued)firewalls 13flow 2, 20identification 5internal class representation

(BAROC) 4listener 1monitoring 20orphan 33reception 1, 12strings 21summary 33translated 3

expressions, for filtering 32

Ffailure, system 13failures, systems 32files

.ed_diag_config 69BAROC 4, 67buffer 68com.tivoli.tec.eif.* 8com.tivoli.tec.event_delivery.* 8configuration 67eif.log 71evd.jar 28event class definition 4for logging and tracing 69format 29libraries 25log.jar 28root.baroc 4

Filter keyword 31, 69FilterCache keyword 31, 70filtering events

cache 70cache files 32configuration files 31discarding events 31entries, filter 31example 32keywords 69, 70regular expressions 32state correlation 31, 33summary 5system failures 32testing 34

FilterMode keyword 70firewalls, sending events 13flow of events 2, 20format files 29FQHostname keyword 70functions

communications 23data transfer 23disconnect 59getConfigVal 60onMessage 61overview 22receiveEvent 62registerListener 63sendEvent 64tec_agent_getenv 42tec_agent_init 43tec_create_EIF_handle 44

functions (continued)tec_create_handle 45tec_create_handle_c 46tec_create_handle_r 48tec_destroy_handle 49tec_errno 50tec_get_event 51tec_put_event 52tec_register_callback 53TECAgent 65TECEvent 66

Ggateways, IBM Tivoli Enterprise Console

backup transports 15configuration files 19, 31connections 69event flow 1, 2filtering events 31, 33state correlation 33XML files 19

getConfigVal function 60getport_timeout_seconds keyword 71getport_timeout_usec keyword 71getport_total_timeout_ usec keyword 71getport_total_timeout_seconds

keyword 71

Hhardware requirements 7header files

in adapter code 19tec_eeif.h 8tec_eif.h 8

hierarchies, event classes 21HPUX, not supported 21, 22

Iibmjsse.jar file 28identification, event 5initialization APIs 23initialize Winsock, WSAStartup

WSASCleanup 24install process, standalone 7installation

migration 8overview 7preparing for 7

installing 7internationalization

overview 28UTF-8 encoding 28, 71, 72

interoperability 8

Jjar files

evd.jar 34Java API, Compiling the adapter built

with the 25Java API, overview 6


Java API, Running adapters built withthe Event Integration Facility 28

Java packages 19jcf.jar file 28JNI 28jsafe.zip file 28

Kkeywords, configuration files 4, 67

Llanguages, double-byte characters 28LCF transport type 11, 14, 15, 76LD_LIBRARY_PATH variable 28LD_LIBRARY_PATHJ variable 28libas.a library 26libcpl.a library 25libdes.a library 25libdl.a library 25, 26libjvm.a file 34libjvm.dll file 34libjvm.sl file 34libjvm.so file 34libmrt.a library 25libnsl.a library 25, 26LIBPATH variable 28libpthread.a library 26libpthreads.a library 25, 26libraries, stub 22librim.a library 26libsocket.a library 25, 26libsunrpc.a library 25, 26libtas.a library 26libteceeif.a library 12, 26libteceeiffwk.a library 12, 26libteceeifgw.a library 11libteceif.a library 12libteceifgw.a library 25libteclcf.a library 28libteclcf.sl library 28libteclcf.so library 28libthread.a library 25, 26libthreads.a library 26libtmf.a library 26libui.a library 26linking adapter to libraries 25listener, events 1, 12localization directories 29log.jar file 28, 34LogFileName keyword 35, 71LogLevel keyword 35, 71logs

messages 35, 71trace 35

Mmanaged node adapters

event flow 2libraries 26, 28state correlation 33transport options 12

manualssee publications v, vii

MaxPacketSize keyword 14, 71message logs 35, 69, 71migrating adapters 8monitoring

events 20sources by adapters 3

multithreaded 24

Nnames, event classes 21newsgroups viiiNO_UTF8_CONVERSION keyword 71non-polling, event reception 13non-TME adapters

described 4event flow 2libraries 26transport options 12

non-TME connections 11notation

environment variables ixpath names ixtypeface ix

Oonline publications

accessing viionMessage function 61ordering publications viiOS/390 OpenEdition voverloading, event delivery 36

Ppackages, Java 19PATH environment variable 28path names, notation ixperformance, configuration 14performance, configuring 11, 14, 36permissions, wpostzmsg and

TECAgent 38permissions, wpostzmsg and Tivoli

Enterprise Console Agent 12polling, event reception 13Port keyword 77port number, for event server 74portmapper daemon 16, 74, 77ports

port mapper 71re-sending UDP calls 71

postzmsg command 12Pre37Server keyword 28, 72Pre37ServerEncoding keyword 28, 72PREPEND_CLASSPATH keyword 72PREPEND_JVMPATH keyword 72prerequisites 7problem determination

See troubleshooting 35programming adapters 21proxy, firewall 13publications v

accessing online viiordering vii

RreceiveEvent function 62RECEIVER_MODE 9receiving events

APIs 22described 12

recovery, systems 13regions, Tivoli management 15registerListener function 63regular expressions, for filtering 32reliability 14requirements, system 7RetryInterval keyword 73return codes 8roles, authorization

adapters 22root.baroc (base BAROC file) 4rules

IBM Tivoli Enterprise Consoledescribed 19overview 6

Ssample, adapter code 23security, transport 12SENDER_MODE 9sendEvent function 64sending events

APIs 22methods 11rate from cache 14tests 11, 12

ServerLocation keyword 15, 73, 77ServerPort keyword 74SHLIB_PATH variable 28single quotation mark 67SOCKET transport type 14, 76sockets 14, 15, 76software requirements 7software support

contacting viisources

described 3, 20monitoring by adapters 3

spaces, blank 67standalone install process 7state correlation

cache 68, 75cleanup 75keywords 71libraries 28log.jar file 34overview 31, 33running state machines 33testing 34tracing 35xerces-3.2.1.jar file 34XML 75zce.jar file 34

state machinesrunning 33

StateCorrelationCleaningIntervalkeyword 75

StateCorrelationConfigPath keyword 75StateCorrelationMaxFileSize keyword 75

Index 85

StateCorrelationTotalSize keyword 75strings, event 21stub libraries 22system failures 13, 32system requirements 7

TTcl expressions, for filtering 32TCP sockets 14tec_agent_getenv function 42tec_agent_init function 43tec_create_EIF_handle function 44tec_create_handle function 45tec_create_handle_c function 46tec_create_handle_r function 48tec_destroy_handle function 49tec_eeif.h header file 8tec_eif.h header file 8tec_errno function 50tec_get_event function 51tec_put_event function 52tec_recv_agent_port entry 74tec_register_callback function 53TECAgent class constants 8TECAgent function 65TECEvent function 66teclcf.dll library 28testing

adapters 27builds 22event filtering 34sending events 11, 12state correlation 34

TestMode keyword 75theTECAgent=new

sr, TECAgent.SENDER_MODE,false 8

threads 24timers

event delivery 36Tivoli Application Development

Environment 25, 26Tivoli Availability Intermediate

Manager 74Tivoli Management Framework

events requiring 3Firewall Security Toolbox 13libraries 25, 26

Tivoli management regions 15Tivoli Software Information Center viiTIVOLIHOME variable 68, 71TME adapters 3, 28TME connections 11TME transport type 12, 14, 76trace logs 35, 69, 76TraceFileName keyword 35, 76TraceLevel keyword 35, 76transport

LCF 11, 15options 11SOCKET 14TME 12, 14types 14

transport type 76TransportList keyword 12, 15, 76

troubleshootingadapter code 22message logs 35overview 35scenarios, common 36trace logs 35

tuning, performance 36Type keyword 15typeface conventions viii

UUDP calls 71Upgrading Existing Adapters 22UseStateCorrelation keyword 78UTF-8 encoding 71, 72utilities

ed_scan_get_n 55ed_scan_n 56ed_sleep 57trace and log 35

Vvariables

CLASSPATH 34LD_LIBRARY_PATH 28LD_LIBRARY_PATHJ 28LIBPATH 28PATH 28SHLIB_PATH 28TIVOLIHOME 68, 71

variables, notation for ix

WWIDTHSTRMEANING keyword 78Windows, Special considerations for 23winsockets 23wpostzmsg command 12

Xxerces-3.2.1.jar file 28, 34XML files 19

Zzce.jar file 28, 34


��

Program Number: 5698-TEC

Printed in U.S.A.

SC32-1241-00