hp_man_j1261-90072_pdf.pdf

SNMP Developer’s Guide

HP OpenView Integration Series

Manufacturing Part Number : J1261-90072

May 2002

United States

© Copyright 2002 Hewlett-Packard Company.

Legal NoticesHewlett-Packard makes no warranty of any kind with regard to thismanual, including, but not limited to, the implied warranties ofmerchantability and fitness for a particular purpose. Hewlett-Packardshall not be held liable for errors contained herein or direct, indirect,special, incidental or consequential damages in connection with thefurnishing, performance, or use of this material.

Warranty. A copy of the specific warranty terms applicable to yourHewlett- Packard product and replacement parts can be obtained fromyour local Sales and Service Office.

Restricted Rights Legend. All rights are reserved. No part of thisdocument may be photocopied, reproduced, or translated to anotherlanguage without the prior written consent of Hewlett-PackardCompany. The information contained in this document is subject tochange without notice.

Use, duplication or disclosure by the U.S. Government is subject torestrictions as set forth in subparagraph (c) (1) (ii) of the Rights inTechnical Data and Computer Software clause at DFARS 252.227-7013for DOD agencies, and subparagraphs (c) (1) and (c) (2) of theCommercial Computer Software Restricted Rights clause at FAR52.227-19 for other agencies.

HEWLETT-PACKARD COMPANY

3404 E. Harmony Road

Fort Collins, CO 80528 U.S.A.

Use of this manual and flexible disk(s), tape cartridge(s), or CD-ROM(s)supplied for this pack is restricted to this product only. Additional copiesof the programs may be made for security and back-up purposes only.Resale of the programs in their present form or with alterations, isexpressly prohibited.

Copyright Notices. ©Copyright 1983-2002 Hewlett-Packard Company,all rights reserved.

Reproduction, adaptation, or translation of this document without priorwritten permission is prohibited, except as allowed under the copyrightlaws.

2

Contains software from AirMedia, Inc.

© Copyright 1996 AirMedia, Inc.

Trademark Notices

Java™ is a U.S. trademark of Sun Microsystems, Inc.

Microsoft® is a U.S. registered trademark of Microsoft Corporation.

Windows NT® is a U.S. registered trademark of Microsoft Corporation.

Windows® 2000 is a U.S. registered trademark of Microsoft Corporation.

Windows® and MS Windows® are U.S. registered trademarks ofMicrosoft Corporation.

Netscape™ and Netscape Navigator™ are U.S. trademarks of NetscapeCommunications Corporation.

Oracle® is a registered U.S. trademark of Oracle Corporation, RedwoodCity, California.

Oracle7™ is a trademark of Oracle Corporation, Redwood City,California.

OSF/Motif® and Open Software Foundation® are trademarks of OpenSoftware Foundation in the U.S. and other countries.

Pentium® is a U.S. registered trademark of Intel Corporation.

UNIX® is a registered trademark of The Open Group.

3

Contents

1. Introduction to the NNM Software Developer’s KitThe HP OpenView NNM Software Developer’s Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

The OVSNMP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19The WinSNMP and Microsoft MGMT API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20The SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Integration APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2. An Overview of SNMPThe SNMP Model of Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Manager and Agent Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SNMP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SNMPv1 and SNMPv2C Protocols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

The Management Information Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Extended MIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35SNMP Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3. The OVSNMP Communications APISNMPv1 and SNMPv2C Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Before Accessing the SNMPv2C Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Selecting the Interface Style and Communication Protocol . . . . . . . . . . . . . . . . . . . . 48

OVSNMP Over UDP/IP and IPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50The OVsnmpOpen() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Communication with the HP OpenView Event Subsystem . . . . . . . . . . . . . . . . . . . . 51The OVsnmpPdu Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Blocking and Nonblocking Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Retransmission Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

The SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Memory Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

The SNMP Communication API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

5

Contents

4. The NNM Event Database APIThe NNM Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81The NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5. The OVSNMP Configuration APIThe OVSNMP Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89The OVSNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Data Structures for the OVSNMP Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . 94

Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94The OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95The OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96The OVsnmpConfDest Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98The OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

6. Integrating with Logging and TracingOverview of Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

HP-UX and Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Windows Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

The OVuTL Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

7. Integrating with Process ManagementProcess Management for HP OpenView Applications . . . . . . . . . . . . . . . . . . . . . . . . . 111The OVsPMD Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 115The Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Structure of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Second Line of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Automated Backup and Pre-NNM 6.0 Applications . . . . . . . . . . . . . . . . . . . . . . . . . 123The Backup Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Three Ways of Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Evaluating An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

6

Contents

Writing Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Integration via ovwMapClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Integrating via Services (Background Processes) . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

7

Contents

8

Tables

Table 2-1. SNMP Request Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Table 2-2. SNMPv2C Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Table 2-3. Summary of the SNMPv1 and SNMPv2 SMI Definitions . . . . . . . . . . . . 32Table 2-4. ASN.1 Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Table 2-5. Outside Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Table 3-1. Protocol Operations Supported by the OVSNMP API . . . . . . . . . . . . . . . 46Table 3-2. Protocol Error Status Supported by the OVSNMP API . . . . . . . . . . . . . . 47Table 3-3. SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 56Table 3-4. OVsnmpAPI Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Table 3-5. OVSNMP Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Table 3-6. SNMP API Key Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Table 3-7. OVsnmpSession Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Table 3-8. CallBack Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Table 3-9. CallBack Command Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Table 3-10. Elements of the OVsnmpPdu Data Structure . . . . . . . . . . . . . . . . . . . . . 74Table 3-11. Elements of the OVsnmpVarBind Data Structure . . . . . . . . . . . . . . . . . 77Table 3-12. OVsnmpVarBind Union Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Table 4-1. NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Table 5-1. SNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Table 5-2. SNMP Configuration API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . 94Table 5-3. OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Table 5-4. OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Table 5-5. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Table 5-6. OVsnmpConfCntl Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Table 6-1. Functions in the OVuTL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Table 7-1. Functions in the OVsPMD API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Table 7-2. Purpose of Each Line in a Local Registration File . . . . . . . . . . . . . . . . . 117Table 7-3. First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Table 7-4. Second Line of the LRF& . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

9

Tables

10

Figures

Figure 1-1. SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Figure 2-1. Sequence of Actions in a Hypothetical SNMP Session . . . . . . . . . . . . . . 27Figure 2-2. Conceptual View of Communication Sequence with Traps . . . . . . . . . . 28Figure 2-3. The Top of the MIB Naming Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Figure 2-4. The Role of a Proxy in SNMP Communication . . . . . . . . . . . . . . . . . . . . 37Figure 3-1. OVSNMP Bilingual Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Figure 3-2. OVsnmpPDU Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Figure 5-1. OVsnmpConfWcList Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Figure 5-2. OVsnmpConfDest Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Figure 6-1. Windows Event Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Figure 7-1. Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Figure 7-2. Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Figure 7-3. Decision Tree for Script Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Figure 7-4. Decision Tree for ovwMapClose Event Integration . . . . . . . . . . . . . . . 129Figure 7-5. Decision Tree for Background Process Integration. . . . . . . . . . . . . . . . 130Figure 7-6. Backup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Figure 7-7. API integration with Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Figure 7-8. Backup via Background Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

11

Figures

12

ConventionsThe following typographical conventions are used in this manual.

Font What the Font Represents Example

Italic For book or manual titles, and formanpage names.

Refer to the OVW Developer’s Guide.

To provide emphasis. You must follow these steps.

To specify a variable that you mustsupply when entering a command.

At the prompt type: rloginyour_name where you supply yourlogin name.

Bold For glossary terms. The distinguishing attribute ofthis class...

Computer Text and items on the computerscreen.

The Root map window ...

The system replies: Press Enter

Command names Use the grep command ...

File and directory names. /usr/bin/X11

Process names. Check to see if pmd is running.

Window/dialog box names In the IP Internet map window...

ComputerBold

Text that you must enter. At the prompt, type: ovstatus .

Keycap Keyboard keys. Press Return .

[Button] Buttons on the user interface. Click [NET] . Click on the [Apply]button.

MenuItems

A menu name followed by a colon (:)means that you select the menu,then the item. When the item isfollowed by an arrow (-> ), acascading menu follows.

Select Edit:Find->Objects byComment

13

Contact Information

Technical Support Technical support information can be found on the HP OpenView WorldWide Web site at:

http://openview.hp.com/

________________________________

DocumentationFeedback

Your comments on and suggestions for the documentation help usunderstand your needs and better meet them.

You can provide feedback about documentation via the HPdocumentation site at:

http://www.docs.hp.com

Or you can fill out the form provided in electronic form with NNM:

• Windows®: install_dir \ReleaseNotes\nnm_doc_reply.txt

• UNIX: /opt/OV/ReleaseNotes/nnm_doc_reply.txt

Fill out one form per manual and email it to: [email protected]

If you encounter serious errors in the documentation that impair yourability to use NNM, please contact the HP Response Center or yoursupport representative so that your feedback can be entered intoCHARTS (the HP Change Request Tracking System).

________________________________

TrainingInformation

For information on current HP OpenView training available, see the HPOpenView World Wide Web site at:

http://openview.hp.com/

Select the support panel to obtain information about scheduled classes,training at customer sites, and class registration.

15

1 Introduction to the NNMSoftware Developer’s Kit

Chapter 1 17

Introduction to the NNM Software Developer’s Kit

This chapter introduces the SNMP component of the HP OpenViewNetwork Node Manager (NNM) Software Developer’s Kit (SDK). Itdescribes the SNMP APIs available for application development(OVSNMP and WinSNMP), and includes an illustration of the OVSNMPAPI architecture. Also included is an introduction to APIs used inapplication integration.

Chapter 118

Introduction to the NNM Software Developer’s KitThe HP OpenView NNM Software Developer’s Kit

The HP OpenView NNM Software Developer’sKitThe NNM Software Developer’s Kit is used to write applications that areintegrated with the feature set of NNM. The kit, which is shipped on aCD-ROM, provides application programming interfaces (APIs) for thefollowing:

• SNMP management

• OpenView Windows

• OpenView tracing and logging

• OpenView process control

This guide discusses the APIs for SNMP management (chapters 2, 3, and4), tracing and logging (chapter 5), and process control (chapter 6). APIsrelated to OpenView Windows are discussed in the HP OpenViewWindows Developer’s Guide.

NOTE For information about installing the SDK, see README_SNMPDEV.txt onthe SDK CD-ROM.

The OVSNMP API

The HP OpenView SNMP (OVSNMP) API provides SNMPcommunication and configuration support for HP OpenView integratedapplications. The OVSNMP API originated in the UNIX system versionof the Network Node Manager product. It has now been made availableon the Windows operating systems to provide portability forcross-platform applications.

The OVSNMP API supports both SNMP version 1 (SNMPv1) andCommunity-based SNMP Version 2 (SNMPv2C) through a commonbilingual interface.

The primary transport mechanism is SNMP over UDP/IP. However, theWindows version also supports SNMP over IPX communication.

Chapter 1 19


The OVSNMP API provides a native asynchronous event-loopprogramming model for Win32 on Windows operating systems and X11on UNIX system platforms.

For an overview of SNMP management, see Chapter 2, “An Overview ofSNMP.” For more detailed information about the OVSNMP APIs, seeChapter 3, The OVSNMP Communications API, and Chapter 5, “TheOVSNMP Configuration API.”

The WinSNMP and Microsoft MGMT API

The WinSNMP API and the Microsoft MGMT API are not included in theHP OpenView Software Developer’s Kit. However, applicationsdeveloped with the WinSNMP API or Microsoft MGMT API are fullycompatible with Network Node Manager and other applicationsdeveloped using Windows versions of the HP OpenView SoftwareDeveloper’s Kit (SDK). The OVSNMP library uses WinSNMP for SNMPnotification (trap) reception, which in turn is compatible with theMicrosoft SNMPTRAP service. Therefore, all three types of applicationscan coexist without conflict over the shared SNMP trap port.

The ACE*COMM NetPlus WinSNMP run-time library is bundled withNetwork Node Manager for use only on the installed NNM system.

For more information about the WinSNMP API, refer to the technicalspecification available in postscript form on the CD-ROM for the NNMSDK.

The SNMP API Architecture

The OpenView Event Handler or subsystem passes all HP OpenViewevents between HP OpenView applications. The Event CorrelationServices (ECS) engine is an integral part of the event subsystem. Eventcorrelation logic can be loaded into the ECS engine. This logic changesthe combination of events available for subscription from the eventsubsystem.

The OVSNMP and WinSNMP APIs are compatible with each other,which includes the ability to share (receive) notifications on the standardSNMP trap port. This compatibility enables a mixture of applications torun on the same system. However, HP OpenView events will be deliveredto OVSNMP applications only (and not to WinSNMP applications).

Chapter 120


Figure 1-1 illustrates the primary components and data flows of theOVSNMP API, and their relationships to each other and to systemservices.

Figure 1-1 SNMP API Architecture

Port162

ECSI/O

ANNO

OVsnmpEventOpen ( ", "myApp", recv, &rd,"{NO_FORWARDED,CORR{default}} .*")

Alarm Browser

Drill Down

http server

Perl script

ecsmgr

Annotationserver

ECS Correlation Services

ECS Corr. ConfigurationManagement GUIASCII

Events

OVEVENT

oveventsSNMP V1/V2 Traps

ITOnetmon

ovactiond

ovtrapd

pmd

Chapter 1 21


Integration APIs

Chapters 5 and 6 cover the activities and utilities you use to integrateyour application into the HP OpenView SNMP platform on NetworkNode Manager. Integration requires you to make some straightforwardmodifications to your code, as well as create a few special files andscripts.

There are two key areas for attention in integration:

• logging and tracing

• HP OpenView process management

It is not necessary for you to integrate in both areas. For example, youmay elect to not integrate with the logging and tracing component.However, each point of integration makes it easier for your customer totake full advantage of your product.

NOTE You must create a Local Registration File (LRF) for any agents youcreate. This is covered under process management in Chapter 6.

For further reading, see HP OpenView Integration Series: IntegrationConcepts and Managing Your Network with Network Node Manager.

Chapter 122

2 An Overview of SNMP

Chapter 2 23

An Overview of SNMP

This chapter provides an overview of the Simple Network ManagementProtocol (SNMP) as it is implemented in the HP OpenView OVSNMPAPI. The following information is provided:

• The SNMP Model of Communication, including:

— managers and agents

— SNMP messages

— SNMPv1 and SNMPv2c protocols

• The Management Information Base, including:

— object identifiers

— extended MIBs

— data representation

• A list of documents that provide more detailed information aboutSNMP and MIBs, including several RFCs (Request for Commentdocuments).

Chapter 224

An Overview of SNMPThe SNMP Model of Communication

The SNMP Model of CommunicationManaging computer networks requires an approach that simplifies thepotentially complex problems of communication and coordination. Theprevailing approach, which has been adopted by the SNMP (SimpleNetwork Management Protocol), is to treat the network as a collection ofcooperative, communicating entities. There are two basic types ofentities: management processes (managers) and managed processes(agents).

Managers

A manager is a process (or node) that is an active participant innetwork management. It solicits and interprets data about networkdevices and network traffic, and typically interacts with a user to achievethe user's intentions. Therefore, a manager can also trigger changes inan agent (see the next section) by changing the value of a variable on theagent node. Managers are frequently implemented as networkmanagement applications.

Agents

From the perspective of network management, an agent is usually apassive entity. It responds to the requests of managers, supplying andchanging the values of local variables as needed. An agent can become anactive entity by emitting unsolicited messages (called notifications ortraps) to alert managers of noteworthy local events (such as a systemreboot).

NOTE The HP OVSNMP API is intended for the development of SNMP-basednetwork management applications. It does not fully support thedevelopment of SNMP agents beyond supporting the generation of traps.

Chapter 2 25


Manager and Agent Interaction

A manager can be one of many processes on a computer. For example, amanager might try to provide data about certain gateways. It wouldmake use of the gateway agent by requesting data about throughput,retransmission rates, and other parameters. Such a manager might alsoneed to periodically reset gateway counters by communicating with thegateway agent.

An agent takes care of SNMP activity for the managed node. It can besimple or complex, depending on the device it represents. Like amanager, an agent may actually be one of many processes on a specificcomputer. On the other hand, it might be implemented in the ROM of adevice like a bridge or hub.

A device that does not directly support SNMP is said to be foreign. Aproxy is an agent that translates between SNMP and the privateprotocol of a foreign device.

Managers do not need to know any internal details about the objectmanaged by an agent. Likewise, an SNMP agent can service requestsfrom many SNMP managers. The agent does not need to know thecontext of the request, or the structure of the manager making therequest. The agent simply validates the request, services it, and entersits passive state awaiting the next request.

This division of responsibilities simplifies network managementsolutions. The concept of managers and agents provides a generalsolution to an otherwise complex problem. All devices share a commonmodel for communication, which is the model promoted in SNMP.

SNMP Messages

Requests and responses are transferred in Protocol Data Units, orPDUs. A PDU is the formal name for a message that is sent or receivedin the course of SNMP communication.

Connectionless Operation

SNMP uses a connectionless transport service for communicationbetween the SNMP manager and agent. The HP OpenView SNMP APIintroduces a session-oriented model from the application perspective.However, this implementation serves only to bind the application to theOVSNMP API for a given destination. A connectionless transport is stillused internally.

Chapter 226


The OVSNMP API supports SNMP over User DatagramProtocol/Internet Protocol (UDP/IP) on both UNIX and Windowsplatforms. The OVSNMP API on Windows also supports SNMP overInternet Packet Exchange (IPX).

Requests and Responses

Figure 2-1 illustrates a sequence of communications between a managerand an agent. Events in the diagram occur in top-to-bottom order.

Figure 2-1 Sequence of Actions in a Hypothetical SNMP Session

The diagram oversimplifies the sequence somewhat. The manager cansend the request in either blocking or non-blocking mode. The type ofmode affects the need to manage retransmissions. Also, since theimplementation of the agent is unknown, the agent's actions are generic;the manager does not care how the agent generates the response PDU.

Details about how to use the OVSNMP API to send messages and receiveresponses are in Chapter 3, The OVSNMP Communications API, and inthe online reference pages.

Manager Agent

Listen for requests

Receive request PDU

Generate response PDU

Send response PDU

Set up to send SNMP requests

Create request PDU

Add variable binding to request PDU

Send request PDU

Listen for response(retry Send if necessary)

Receive response PDU

Chapter 2 27


Notifications

In the model presented previously, the manager requests informationfrom the agent and the agent then responds. However, it is also possiblefor an agent to issue spontaneous (unsolicited) messages. Such amessage is known as a notification. In SNMPv1, notifications arereferred to as traps. In SNMPv2, a notification may be either a trap oran inform message.

The diagram shown in Figure 2-2 illustrates the communicationsequence involved with traps.

Figure 2-2 Conceptual View of Communication Sequence with Traps

Traps exist to handle special conditions. When an agent or a managerdetects a special condition, each can emit a trap message. SNMPspecifies several predefined traps, and a developer may also defineapplication-specific traps.

In practice, HP OpenView NNM uses a daemon process to manage traptraffic on an SNMP management node. This is because only onemanagement application can bind to the SNMP/UDP trap port. OnHP-UX and Solaris, the NNM ovtrapd process binds to the trap port andthen forwards traps to local applications.

On Windows operating systems, the NNM ovtrapd process uses bydefault the WinSNMP trap receptor to listen on the trap port. Thisprovides coexistence with native WinSNMP applications. However,ovtrapd can also be started with an override option to listen directly tothe trap port. In this case, the WinSNMP application would not be ableto receive notifications.

Manager Agent

Set up to receive SMP traps

Receive trap PDU

Initialize and begin operation

Detect an internally significant state

Create trap PDU

Send trap PDU

Chapter 228


SNMPv1 and SNMPv2C Protocols

There are two versions of SNMP currently in use: the original SNMPprotocol (also known as SNMPv1), and a newer version calledCommunity-based SNMPv2 (also known as SNMPv2C). SNMPv2Cprovides a growth path to more secure network management whileremaining backwards compatible with SNMPv1 wherever possible.

This section describes some of the key differences between SNMPv1 andSNMPv2C. For more complete information about the protocols, refer to:

• RFC 1157: The Simple Network Management Protocol

• RFC 1905: Protocol Operations for version 2 of the Simple NetworkManagement Protocol (SNMPv2)

SNMP Operations

The SNMPv1 specification defines the following basic operations:

Table 2-1 SNMP Request Types

Request Type Description

Set Request Writes new data to one or more of the objects managed by anagent.

Get Request Requests the value of one or more of the objects managed by anagent.

Get Next Request Requests the Object Identifier(s) and value(s) of the nextobject(s) managed by an agent.

Get Response Contains the data returned by an agent.

Trap Request Sends an unsolicited notification from an agent to a manager,indicating that an event or error has occurred on the agentsystem.

Chapter 2 29


The SNMPv2C protocol provides some new protocol operations over theoriginal SNMP protocol. These include the following:

In addition to these improved operations, SNMPv2C supports improvedexception and error reporting, and new mechanisms for defining MIBsfor SNMPv2. (MIB changes are described later in this overview.)

Table 2-2 SNMPv2C Request Types

Request Type Description

Get Bulk Request Retrieves large amounts of object information in a singlerequest/response transaction. GetBulk behaves as if manyiterations of GetNext request/responses were issued, except thatthey are all performed in a single request/response.

SNMPv2 Trap Request Sends an SNMPv2-style notification to an SNMP manager. TheSNMPv2 Trap Request has a similar purpose as the SNMPv1Trap Request, but is in a slightly different format.

Inform Request Sends an unsolicited but confirmed notification of a local event toa remote management station.

Chapter 230

An Overview of SNMPThe Management Information Base

The Management Information BaseThis section presents highlights of data representation and the conceptof a Management Information Base, or MIB.

The MIB is a general concept for expressing managed objects. A MIBcontains the definitions for a collection of standardized and non-standardized (vendor, experimental) objects. A MIB definition specifiesobjects with a standardized notation, call the Structure ofManagement Information (SMI).

The Internet MIB-II is one of many standard MIBs. The purpose of theMIB-II is to define common objects for managing TCP/IP networks.Other standard MIBs exist (or are being defined) to manage specificnetwork elements as well.1

The Internet MIB-II definition (RFC 1213) defines standardized objectsfor TCP/IP agents. To access the value of a MIB-II object, an SNMPmanager sends a request to the agent representing the desired instanceof the object. The request message contains MIB information (an objectidentifier) that lets the agent identify the specific objects. Thecorresponding response message from the agent carries the sameidentifying information.

MIBs are defined using an Internet-standard language called theStructure of Management Information (SMI). MIBs can be defined usingeither of two SMI versions: the original SMI definition, and a newerSNMPv2 SMI definition. The key differences are described in Table 2-3,“Summary of the SNMPv1 and SNMPv2 SMI Definitions.”

1. Because it is a superset of MIB-I, MIB-II only is mentioned in thisdiscussion.

Chapter 2 31


Table 2-3 Summary of the SNMPv1 and SNMPv2 SMI Definitions

SMI Definition Differences

SNMPv1 SMI Forms the basis for all existing SNMPv1-based MIBs. Defined in RFC1155: Structure and Identification of Management Information forTCP/IP-based Internets Amended in RFC 1212: Concise MIBDefinitions

SNMPv2 SMI Defined as a superset of the SNMPv1 SMI. Some SNMPv1 data typeshave been renamed:

• Counter -> Counter32

• Gauge -> Gauge32

• INTEGER -> Integer32

Extends the original SNMPv1 SMI to support these new data types:

• Counter64 (64-bit counter)

• Unsigned32 (32-bit unsigned integer). Indistinguishable fromGauge32.

• BITS (defines an enumeration of bits. Indistinguishable fromOCTET STRING.

Allows custom data types to be built by constraining the range, size,or possible values of existing data types. For example, a newenumeration could be constructed by defining a small set of possibleinteger values. The SNMPv2 SMI refers to this form of definition as a“textual convention.”

Defined in: RFC 1902: Structure of Management Information forVersion 2 of the Simple Network Management Protocol RFC 1903:Textual Conventions for Version 2 of the Simple Network ManagementProtocol (SNMPv2)RFC 1904: Conformance Statements for Version 2of the Simple Network Management Protocol (SNMPv2)

Chapter 232


Object Identifiers

For the purposes of an SNMP developer, an object identifier (OID) is adata type that precisely identifies a MIB-II object definition. An OID(often referred to as the registration ID) consists of a sequence ofnon-negative integers that describe the only path through theobject-naming hierarchy to the object. The naming hierarchy iscommonly called the naming tree.

The Naming Tree

The naming tree has the structure of a conventional tree with arbitrarybreadth and depth. The nodes are labeled with non-negative integers(each node among siblings must have a unique label).

Various organizations have administrative authority for assigning labelswithin subtrees of the naming tree. They can assign subordinate (child)nodes, and/or delegate this responsibility to still other organizations.

The root node of the naming tree has three children:

ccitt(0) The administration authority for thisbranch is the International Telegraphand Telephone ConsultativeCommittee (CCITT).

iso(1) The administration authority for thisbranch is the InternationalOrganization for Standards, and theInternational ElectrotechnicalCommittee (ISO/IEC). This is thepath under which networkingmanagement is defined.

joint-iso-ccitt(2) The administration authority for thisbranch is shared between CCITT andISO/IEC.

Chapter 2 33


Figure 2-3 The Top of the MIB Naming Tree

Every path through the naming tree ultimately terminates at a leafnode. The sequence of labels along the path (starting at the root) is theOID for the object named at the leaf.

OIDs in Practice

The convention for writing object identifiers is called dot notation. AnOID in dot notation consists of the integers of the OID in sequence, witha period (dot) between them. Thus the prefix for the OIDs in the MIB-IIis 1.3.6.1.2.1 .

Below is an example OID from the MIB-II. The full written name of thepath is shown beneath the corresponding numerical identifiers in theOID:

NOTE The derivation of these examples is taken from the RFCs noted earlier inthis chapter and in “For More Information” at the end of this chapter.

Similarly, the prefix for the OIDs in HP enterprise-specific MIBs is1.3.6.1.4.1.11.

joint-iso-ccitt(2)iso(1)ccitt(0)

root

iso.org.dod.internet.mgmt.mib.tcp.tcpAttemptFails

1.3.6.1.2.1.6.7

Chapter 234


Extended MIBs

Many agents support extended MIBs, which define objects that are notincluded in standard MIBs, such as MIB-II and enterprise-specific MIBs.Your application can query an object from an extended MIB exactly as itwould query a MIB-II object. Users should use the proper registrationauthorities when defining MIB extensions.

Data Representation

Data is exchanged between SNMP processes using the Basic EncodingRules (BER) defined for the Abstract Syntax Notation (ASN.1).

ASN.1 is a rich data description language, and gaining a fullunderstanding of it is a formidable task. Fortunately, as an SNMPdeveloper, you do not deal directly with ASN.1 or the Basic EncodingRules. The HP OpenView SNMP API takes care of the details of ASN.1encoding and decoding.

SNMP uses a few simple ASN.1 data types. Table 2-4, ASN.1 Data Types,lists the base data types that you work with in SNMP communication.The details of how you access them appear in the online reference pages.

Table 2-4 ASN.1 Data Types

Type Description

INTEGER

Integer32

A simple type consisting of positive and negative whole numbers,including zero, and is of arbitrary size up to 32 bits. However, someobjects restrict INTEGER to a range.

OCTET STRING A simple type taking zero or more octets, each octet being an orderedsequence of eight bits. The value of any octet in the string isunrestricted.

OBJECTIDENTIFIER

An array of non-negative, 32-bit integers. Each integer representsone element of the object identifier. The maximum length of anOBJECT IDENTIFIER is limited to 128 sub-identifiers.

Counter

Counter32

A type representing a non-negative integer which calculates changeand increases until it reaches a maximum value, when it then wrapsaround and starts increasing again from zero.

Chapter 2 35


Gauge

Gauge32

A type representing a non-negative integer, which may increase ordecrease, but which latches at a maximum value.

Timeticks A type representing a non-negative integer which counts the time inhundredths of a second since some event.

NetworkAddress A type representing an address from one of possibly several protocolfamilies. Currently only one protocol family, the Internet family, ispresent. This data type is deprecated in SNMPv2.

IPAddress A type representing a 32-bit Internet address. It is represented as anOCTET STRING of length 4, in network byte-order. When this ASN.1type is encoded using the ASN.1 basic encoding rules, only theprimitive encoding form shall be used.

Counter64 A type representing a non-negative, 64-bit integer which calculateschange and increases until it reaches a maximum value. It thenwraps around and starts increasing again from zero. Values canrange from 0 to 264^1.

Unsigned32 A non-negative 32-bit integer. Values can range from 0 to 232 ^1.This data type is indistinguishable from Gauge32 when encodedusing ASN.1 BER.

BITS An arbitrary set of named bit enumerations encoded as an ASN.1OCTET STRING.

Table 2-4 ASN.1 Data Types (Continued)

Type Description

Chapter 236


SNMP Proxies

The HP SNMP implementation provides special support for applicationsthat communicate with a destination agent using an SNMP proxy. Suchan application can address a message directly to the destination (foreign)agent; the SNMP API will determine which host is the proxy and sendthe message accordingly. Figure 2-4 illustrates this concept.

Figure 2-4 The Role of a Proxy in SNMP Communication

The information used to recognize proxy agents resides in the SNMPConfiguration Database. This proxy information must be configured bythe administrator of the manager. For details, see xnmsnmpconf(1) in theonline reference pages.

The Manager addresses a message to theTargetAgent. The HP SNMP API recognizesthat the agent has an SNMP proxy namedProxySys. The API routes the message toProxySys, which in turn communicates withTargetAgent in some non-SNMP protocol,then relays the response to manager, usingSNMP.

TargetAgent

Manager

ProxySys

SNMP

Foreign Protocol

Chapter 2 37

An Overview of SNMPFor More Information

For More InformationThe documents listed in Table 2-5, Outside Reading, contain moredetailed information that is beyond the scope of this guide. Thesedocuments are neither published nor sold by Hewlett-Packard.

Table 2-5 Outside Reading

Document Description

RFC 1155: Structure and Identification ofManagement Information for TCP/IP-basedInternets

K. McCloghrie and M. T. Rose, (May 1990).Contains MIB object definitions.(Obsoletes RFC 1065)

RFC 1157: A Simple Network ManagementProtocol

J. D. Case, M. Fedor, M. L. Schoffstall, andC. Davin, (May 1990). Defines SNMP.(Obsoletes RFC 1098)

RFC 1187: Bulk Table Retrieval with theSNMP

K. McCloghrie, M. T. Rose, and C. Davin,(October 1990).

RFC 1212: Concise MIB Definitions K. McCloghrie and M. T. Rose, (March1991). Describes the format for creatingMIB object files.

RFC 1213: Management Information BaseNetwork Management of TCP/IP basedinternets: MIB-II

K. McCloghrie and M. T. Rose, eds., (March1991). Defines MIB-II. (Obsoletes RFC1158; most current edition as of theprinting of this guide.)

RFC 1215: Convention for Defining Traps forUse with the SNMP

M. T. Rose, ed. (March 1991).

RFC 1901: Introduction to Community-basedSNMPv2

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996).Defines “Community-based SNMPv2.”(Experimental. Obsoletes RFC 1441)

RFC 1902: Structure of ManagementInformation for Version 2 of the SimpleNetwork Management Protocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996). MIBDefinition language for Managed Objects(Draft Standard. Obsoletes RFC 1442)

Chapter 238


RFC 1903: Textual Conventions for Version 2of the Simple Network Management Protocol(SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996). MIBDefinition language for refined data types.(Draft Standard. Obsoletes RFC 1443)

RFC 1904: Conformance Statements forVersion 2 of the Simple Network ManagementProtocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996). MIBDefinition language for Conformance andCapability definitions. (Draft Standard.Obsoletes RFC 1444)

RFC 1905: Protocol Operations for Version 2of the Simple Network Management Protocol(SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996).Defines SNMPv2 protocol. (DraftStandard. Obsoletes RFC 1448)

RFC 1906: Transport Mappings for Version 2of the Simple Network Management Protocol(SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996).Defines SNMPv2 transport mappings forIP, IPX, DDP. (Draft Standard. ObsoletesRFC 1449)

RFC 1907: Management Information Base forVersion 2 of the Simple Network ManagementProtocol (SNMPv2)

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996).Defines MIB objects that are mandatoryfor SNMP agents that support SNMPv2.(Draft Standard. Obsoletes RFC 1450)

RFC 1908: Coexistence between Version 1 andVersion 2 of the Internet-standard NetworkManagement Framework

SNMPv2 WG, J.Case, K. McCloghrie, M.T.Rose, S. Waldbusser, (January 1996).Coexistence guidelines for SNMPv1 andSNMPv2. (Draft Standard. Obsoletes RFC1452)

Table 2-5 Outside Reading (Continued)

Document Description

Chapter 2 39


Chapter 240

3 The OVSNMP CommunicationsAPI

Chapter 3 41

The OVSNMP Communications API

This chapter describes the OVSNMP Communications API. TheOVSNMP API provides all the functions and support you need to write amanager-based network management application. It is provided in theSoftware Developer’s Kit (SDK) for cross-platform portability of existingOVSNMP/UNIX system-based applications.

This chapter discusses the following:

• OVSNMP API concepts, including:

— SNMPv1 and SNMPv2C protocol support, including changes inthe API interface behavior

— OVSNMP over UDP/IP and IPX

— blocking and nonblocking programming models

— retransmission support

— memory management

• The OVSNMP Communications API routines

• The OVSNMP Communications API data structures

Chapter 342

The OVSNMP Communications APISNMPv1 and SNMPv2C Protocol Support

SNMPv1 and SNMPv2C Protocol SupportThe OVSNMP API allows you to communicate with remote systems inthe following ways:

• using the original SNMPv1 protocol

• using the newer, Community-based SNMPv2 protocol (also calledSNMPv2C)

• letting the OVSNMP API determine which version to use

If you have an existing application that uses the OVSNMPcommunications API, and do not need to communicate with remotesystems using the SNMPv2C protocol, you can simply recompile yourapplication and relink with the SNMP libraries provided in yourdeveloper kit. The OVSNMP API routines are fully backward-compatiblewith the previous OVSNMP communications API.

However, if you wish to access SNMPv2C remote systems, you mustwrite your application to specifically use the SNMPv2C API extensions.The extensions are easily accommodated by any existing applicationalready using the OVSNMP communications API.

The remainder of this section describes how you can take advantage ofthe dual support of the SNMPv1 and SNMPv2C protocols in the SNMPdeveloper’s kit.

Before Accessing the SNMPv2C Protocol

Before you access the SNMPv2C protocol, you should be aware of twotopics that will affect your implementation:

• SNMPv1 and SNMPv2C protocol runtime support

• changes in the OVSNMP API interface behavior

SNMPv1 and SNMPv2C Protocol Runtime Support

The OVSNMP Communications API contains an embeddedcommunications protocol stack that supports both the SNMPv1 andSNMPv2C protocols. This protocol stack contains the intelligence tosupport explicit requests for SNMPv1 or SNMPv2C protocol support, aswell as a bilingual mode that supports both protocol stacks.

Chapter 3 43


The bilingual mode relies on information in the SNMP configurationdatabase to determine which protocol version to use to communicatewith a particular agent. The protocol stack automatically translatesrequests made in bilingual mode to the particular protocol supported fora particular agent.

Figure 3-1 shows the relationship between the OVSNMP API and thebilingual/native protocol stack support.

Figure 3-1 OVSNMP Bilingual Stack

Changes in the OVSNMP API Interface Behavior

To support both the original SNMPv1 interface and the newer SNMPv2Cbilingual communication mode, the OVSNMP API has been enhanced tosupport a new interface behavior. The enhancements accommodate thedifferences in error return codes introduced in the SNMPv2C protocol,while still retaining source code compatibility with existing OVSNMPAPI applications.

Management Application

SNMPv1 Style API

v1 mode

SNMPv2 Style API

SNMPv1protocol

v1 bilingualmodemode

v2Cmode

SNMPv1protocol

SNMPv2Cprotocol

controlled byOVSNMP_V2API session flag

controlled byprotocol version(when theOVSNMP_V2API flag is set)

OR OR

SNMPv2 agentSNMPv1 agent

Chapter 344


You can use the OVSNMP API in its original interface style or in the newinterface style, which is called OVSNMP_V2API. If you select the newinterface style, your application can take advantage of both explicitSNMPv2C protocol support and bilingual SNMPv1/SNMPv2C protocolsupport. Your application, however, must also handle the different typesof errors that can be returned through the SNMPv2-style interface.

You may explicitly request that your application use either the SNMPv1or SNMPv2C protocol. By default, if you use the SNMPv2-style interface,the SNMP stack will use the bilingual communication mode.

The bilingual communication mode allows access to SNMP operationsthat might not initially appear to be valid for a given remote system. Forexample, you could use GetBulk Requests for a remote node thatsupports only the SNMPv1 protocol. When using bilingualcommunication mode, the SNMP run-time stack dynamically translatesrequests into SNMP operations that are valid for the particular type ofremote system involved in the communication. For example, if a remotesystem supports only the SNMPv1 protocol, a GetBulkRequest istranslated into a GetNext request.

The OVSNMP API performs the following protocol translations whencommunicating with SNMPv1 agents through the SNMPv2-styleinterface:

• SNMPv2 GetBulk operations are translated into SNMPv1 GetNextoperations.

• When transmitting SNMPv2 traps to SNMPv1 systems, the trap isfirst translated into the SNMPv1 trap format.

• If an SNMPv1 Trap Request is received and the API is operating inthe SNMPv2-style interface mode, the SNMPv1 Trap Request istranslated into the SNMPv2 Trap format.

• SNMPv2 Inform operations cannot be translated into an SNMPv1equivalent operation, and therefore cannot be sent to an SNMPv1system.

Chapter 3 45


Table 3-1, Protocol Operations Supported by the OVSNMP API, indicateswhich SNMPv1 or SNMPv2C protocol operations are supported by theOVSNMP API through the two interface styles.

If necessary, you can determine which protocols are configured in thelocal OVSNMP Configuration Database for a remote system by using theOVsnmpGetVersions function or the xnmsnmpconf -getVersionscommand. For more information about querying the protocols supportedby a remote system, see the reference page for xnmsnmpconf .

Enhanced Error Codes If you select the SNMPv2-style interface tothe OVSNMP API, you must be prepared to handle a much larger set ofpossible error codes than was possible with the SNMPv1-only interface.

Table 3-1 Protocol Operations Supported by the OVSNMP API

SNMP Operation v1-styleAPI

v2-style API

Bilingual SNMPv1 SNMPv2C

GET_REQ_MSG x x x x

GETNEXT_REQ_MSG x x x x

GETBULK_REQ_MSG x x a x

SET_REQ_MSG x x x x

RESPONSE_MSG x x x x

V1TRAP_REQ_MSG x x

V2TRAP_REQ_MSG x x

INFORM_REQ_MSG x x

Receive SNMPv1 trap inSNMPV2 trap format

x x x

Receive SNMPv2 trap orinform in SNMPv1 trapformat

x

a. When using the SNMPv2-style API with the SNMPv1 protocol version, eachGetBulk request is mapped to a single GetNext request, regardless of themaximum number of repetitions specified.

Chapter 346


Table 3-2, Protocol Error Status Supported by the OVSNMP API, showsthe errors that can be returned when using each of the OVSNMP APIinterface modes. The original SNMPv1-style interface supports only theerror codes listed under “v1-style Interface.” SNMPv1 error codes are nottranslated to SNMPv2C code. The SNMPv2C codes are more specificthan SNMPv1 codes, so there is no one-to-one translation between thetwo.

Applications using the bilingual protocol mode must be able to deal witherror codes that do not appear as SNMPv1 error codes, even if themessages originate from an SNMPv1 remote system. The bilingual modeis designed to hide the details of the lower level protocol, and to allowdevelopers to write applications that work equally well whencommunicating with SNMPv1 and SNMPv2C-compatible remotesystems.

When using the SNMPv2-style API interface, the set of possible errorsreturned is the same, regardless of the actual SNMP protocol used tocommunicate with the remote system. See Table 3-2, “Protocol ErrorStatus Supported by the OVSNMP API.”

Table 3-2 Protocol Error Status Supported by the OVSNMP API

SNMP Response Errors v1 styleInterface

v2-style Interface

Bilingual v1native

v2native

SNMP_ERR_NOERROR x x x x

SNMP_ERR_TOOBIG x x x x

SNMP_ERR_NOSUCHNAME x x x x

SNMP_ERR_BADVALUE x x x x

SNMP_ERR_GENERR x x x x

SNMP_ERR_NOACCESS x x

SNMP_ERR_WRONGTYPE x x

SNMP_ERR_WRONGLENGTH x x

SNMP_ERR_WRONGENCODING x x

SNMP_ERR_WRONGVALUE x x

Chapter 3 47


Selecting the Interface Style and CommunicationProtocol

The OVSNMP API provides straightforward access to the originalSNMPv1-style, or to the newer SNMPv2-style interface andcommunication protocol selection.

By default, a session created while using any of the session API functionsoperates with the original SNMPv1-style interface. This provides fullbackward compatibility for existing applications.

To place the OVSNMP API in the SNMPv2-style interface mode, firstcreate the session structure using any of the standard session APIroutines, such as OVsnmpOpen() .

Next, set the OVSNMP_V2API bit in the session_flags field of theOVsnmpSession structure. (The OVsnmpSession structure is describedlater in this chapter.) Thereafter, all calls to the OVSNMP API willreturn results or errors that conform to the SNMPv2-style interface.

SNMP_ERR_NOCREATION x x

SNMP_ERR_INCONSISTENTVALUE x x

SNMP_ERR_RESOURCEUNAVAILABLE x x

SNMP_ERR_COMMITFAILED x x

SNMP_ERR_UNDOFAILED x x

SNMP_ERR_AUTHORIZATIONERROR x x

SNMP_ERR_NOTWRITABLE x x

SNMP_ERR_INCONSISTENTNAME x x

Varbind Exceptions x x

Table 3-2 Protocol Error Status Supported by the OVSNMP API

SNMP Response Errors v1 styleInterface

v2-style Interface

Bilingual v1native

v2native

Chapter 348


Optionally, if you want to specify a particular communications protocolrather than use bilingual protocol support, you can set theprotocol_version field in the OVsnmpSession structure. Allcommunication from that point on will use the specified communicationprotocol. Valid choices for the protocol version are:

• SNMP_VERSION_1

• SNMP_VERSION_2C

• SNMP_USE_DEFAULT_VERSION (bilingual)

Chapter 3 49

The OVSNMP Communications APIOVSNMP Over UDP/IP and IPX

OVSNMP Over UDP/IP and IPXThe OVSNMP API supports communication with SNMP agent systemsusing either the User Datagram/Internet Protocol (UDP/IP) or Novell’sInternet Packet Exchange (IPX) protocol.

NOTE Actual SNMP transmission over IPX is supported on the Windowsoperating systems only. However, the multi-transport interface to enableboth UDP/IP and IPX can be used on all platforms to facilitatecross-platform portability.

The multi-transport interface for the OVSNMP API is nearly identical tothe UDP/IP-only interface of previous releases. Existing applicationscontinue to support SNMP over UDP/IP without any need to be modified.In addition, most of those applications, when ported to theWindowsNT/2000 operating system, will realize both UDP/IP and IPXsupport without any modification as well. Only applications thatoverride the SNMP destination on a per-request (PDU) basis must beenhanced to realize full IPX support.

The multi-transport capabilities are exported to an application in twoareas: the OVsnmpOpen() function and the OVsnmpPdu structure.

The OVsnmpOpen() Function

The OVsnmpOpen() , OVsnmpXOpen() , and OVsnmpWOpen()functions takepeername and remote_port parameters as input.

The peername is a character string that identifies the destination ofSNMP requests issued on the session. The peername can be an IPhostname, IP address (with dot notation), or an IPX address(netnum:nodenum notation).

The remote_port is a number identifying the UDP port or IPX socket ofthe SNMP agent. If SNMP_USE_DEFAULT_REMOTE_PORT is specified forremote_port , the appropriate default value is used (such as UDP/161 orIPX/36879 ).

Chapter 350


Communication with the HP OpenView EventSubsystem

The event subsystem passes all HP OpenView events between HPOpenView applications. The Event Correlation Services (ECS) engine isan integral part of the event subsystem. Event correlation logic can beloaded into the ECS engine. This logic changes the combination of eventsavailable for subscription from the event subsystem. The concepts ofevent flows and event streams distinguish the combination of eventsavailable for subscription.

An application subscribing to events must specify one of three eventflows: RAW, CORR, or ALL. The RAW event flow includes all eventsreceived by the event subsystem excluding events originating in the ECSengine. The correlated (CORR) event flow includes all events comingfrom a named event stream. The ALL event flow includes all eventsreceived by the event subsystem plus all events created inside the ECSengine.

Using OVsnmpEventOpen() or its variants, applications can establish adirect communication session with the event subsystem to send andreceive events. Through the filter parameter of OVsnmpEventOpen() , youcan specify the type of event flow (RAW, CORR, or ALL) from which toreceive HP OpenView events. In the case of CORR event flow, you canspecify the name of the ECS stream for receiving correlated events.

Each event in the event subsystem has a unique ID, (OVsnmp UUID)assigned to it. Applications can access OVsnmp UUID data throughOVsnmpEventSend() or OVsnmpExtractUUID() . OVsnmp UUID data canbe manipulated through OVsnmpUuidFromStr() or OVsnmpUuidToStr() .To identify an existing event in the event subsystem see theOVsnmpEventAck (3), OVsnmpEventDel (3), OVsnmpEventUnack (3),OVsnmpEventChange (3), OVsnmpEventChangeCat (3), andOVsnmpEventCorrelate (3) online reference pages.

Chapter 3 51


The OVsnmpPdu Structure

The second area in which multi-transport capabilities are exported toapplications is the OVsnmpPdu structure. This structure contains an“address” member that is defined by default as sockaddr_in (internetsocket).

To fully enable the multi-transport interface, insert the compilerdirective

#define OVSNMP_MULTI_TRANSPORT

into the application source code before including OVsnmp.h. Thisredefines the OVsnmpPdu address member to be a sockaddr (genericsocket) structure. The address.sa family value then determines thetype of address specified in the PDU. If this value is AF_UNSPEC, thesession peername is used as the destination. Otherwise, AF_INETindicates a UDP/IP address (sockaddr _in format); and AF_IPX indicatesan IPX address (sockaddr_in format).

Existing applications that rely on the session peername when sendingSNMP requests do not need to be modified. However, applications thatoverride the destination on a per-request (PDU) basis must be modifiedto do the following:

• Use the new multi-transport interface directive.

• Reference the OVsnmpPduaddress structure accordingly. Further, theOVsnmpPduaddress type must be the same type as that of the sessionpeername . Otherwise, the SNMP request will fail withSNMP_ERR_INVALID_HOST.

Developers of new applications are encouraged to use themulti-transport interface directive in all cases.

Chapter 352

The OVSNMP Communications APIBlocking and Nonblocking Programming Models

Blocking and Nonblocking ProgrammingModelsThe OVSNMP API lets you communicate with an SNMP agent system ineither a blocking or nonblocking mode. The choice between blocking andnonblocking mode depends on whether the application is suspendedwhile the request is being processed.

If you issue a blocking request, your application is suspended until eithera response is received or a timeout occurs. The OVSNMP APItransparently manages a number of communications behaviors, such asretransmission, on behalf of the application.

If you issue a nonblocking request, control returns to your application assoon as the request is submitted, but before a response is received. Thiscan be advantageous if the response may not return promptly, or if yourapplication needs to process other events while waiting for a response.

In nonblocking communication, the OVSNMP stack needs a mechanismfor informing your application when a response arrives. This is the roleof the callback function. Thus, when you issue a nonblocking request, youalso must supply the name of a callback function that will be invokedwhen the response is received.

Retransmission Support

OVSNMP uses either the User Datagram Protocol (UDP) or InternetPacket Exchange (IPX)1 at the transport layer. These connectionlessprotocols provide a simple but unreliable transport. A message can getlost in transmission and never arrive at its destination. Therefore,services such as SNMP may require some messages to be retransmitted.

If your application uses blocking requests, the SNMP library handlesretransmission based on the timeout and retry values established whenthe session is first opened.

If your application uses nonblocking requests, the SNMP API providesthree ways to manage retransmission:

1. OVSNMP over IPX is supported on Windows operating systemsonly.

Chapter 3 53


• manual retransmission based on the select function

• automatic retransmission using the Win32 message loop (Windowsonly)

• automatic retransmission using the X11 event loop (UNIX only)

Each of the three modes uses a variant of the OVsnmpOpen function tocreate the OVsnmpSession , plus a slightly different mechanism formanaging retransmission and determining when a response arrives.However, all other functions such as OVsnmpSend, OVsnmpCancel , andOVsnmpClose can be used with any type of OVsnmpSession .

If you use OVsnmpOpen to create the session, you must call select() towait for SNMP events to occur, such as the arrival of a response or theneed for a retransmission.

If you use the X11 or Win32 forms of nonblocking calls, you can rely onthe X11 or Win32 event-processing loop to determine when responsesarrive. With these types of nonblocking functions, retransmissions areautomatically managed for you.

The communications functions for the OVSNMP API are described inmore detail later in this chapter and in the online reference pages.

Select-based Retransmission

Event-driven, select -based applications make nonblocking requests. Asshown in the sample code fragment below, these applications create anOVsnmpSession by using OVsnmpOpen, then manage retransmissions bycalling select() and the OVsnmpGetRetryInfo and OVsnmpDoRetryfunctions (which are described later in this chapter).

session=OVsnmpOpen(targetName,...applCb,applCbData);pdu=OVsnmpCreatePdu(...);OVsnmpAddNullVarbind(...);reqId=OVsnmpSend(session,pdu); ...other application specific code...while (1){ nfds=OVsnmpGetRetryInfo(&readfds, &tval); rc=select(nfds,readfds,NULL,NULL,&tval); if (rc>0)OVsnmpRead(&readfds); OVsnmpDoRetry();}/* *Note:OVsnmpRead and OVsnmpDoRetry invoke the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */

Chapter 354


Automatic Retransmission Using the Win32 Message Loop

The OVSNMP API on Windows operating systems includes native Win32support for event-driven (nonblocking) applications. As illustrated in thesample code fragment below, you use this feature by calling theOVsnmpWOpen and OVsnmpSend functions, along with the Win32 messageloop consisting of GetMessage to DispatchMessage . TheOVsnmpGetRetryInfo and OVsnmpDoRetry functions are not used in thismode of operation.

session=OVsnmpWOpen(targetName,...applCb,applCb,applCbData);pdu=OVsnmpCreatePdu(...);OVsnmpAddNullVarbind(...);reqId=OVsnmpSend(session,pdu); ...other application specific code...while (GetMessage(&msg)){ TranslateMessage(&msg);/*For Keyboard accels*/ DispatchMessage(&msg);/* *Note:DispatchMessage() ultimately invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */

Automatic Retransmission Using X11 Event Loop (UNIX Only)

The OVsnmpAPI library includes extended support for event-drivenX11-based applications. These applications use OVsnmpXOpen andOvsnmpSend. When you use this feature, the SNMP library manages allmessage retransmissions for you using XtAppMainLoop(3) . The samplecode fragment illustrates how retransmissions are handled.

session=OVsnmpXOpen(XtCtx, target,...applCb,applCbData);pdu=OVsnmpCreatePDU(...);OVsnmpAddNullVarbind(...);reqId=OVsnmpSend(session,pdu); ..other application specific code...XtAppMainLoop(XtCtx);/* *Note:XtAppMainLoop() invokes the OVSNMP applCb *for SNMP responses, notifications and timeout conditions */

Chapter 3 55

The OVSNMP Communications APIThe SNMP Communications API Functions

The SNMP Communications API FunctionsTable 3-3, SNMP Communications API Functions, shows how theOVSNMP API functions are grouped, and the name and description ofeach OVSNMP API function.

Table 3-3 SNMP Communications API Functions

Function Name Description

SESSION MANAGEMENT FUNCTIONS

OVsnmpOpen() Establishes a logical session with the OVsnmpAPI forthe purpose of communicating with a specific remotesystem.

OVsnmpXOpen() Equivalent to OVsnmpOpen() , but prepares a logicalsession for use in an X-Windows programmingenvironment.

OVsnmpWOpen() Equivalent to OVsnmpOpen() , but prepares a logicalsession for use in a Windows operating systemprogramming environment.

OVsnmpClose() Terminates an SNMP session created by any of theOVSNMP session open functions.

OVsnmpXClose() Provided for backward compatibility of existing X11applications.

EVENT FRAMEWORK SESSION FUNCTIONS

OVsnmpEventOpen() Successor to OVsnmpTrapOpen() . Establishes a logicalsession with the OVsnmpAPI for the purpose of receivingSNMP events via the OpenView Event Framework. Itallows filters to be applied to events to reduce thenumber of events that are received.

OVsnmpXEventOpen() Equivalent to OVsnmpEventOpen() , but prepares alogical session for use in an X-Windows programmingenvironment.

Chapter 356


OVsnmpWEventOpen() Equivalent to OVsnmpEventOpen() , but prepares alogical session for use in a WindowsNT/2000 operatingsystem programming environment.

OVsnmpTrapOpen() Predecessor to the OVsnmpEventOpen() function. Thisfunction is provided for backward compatibility only. Usethe OVsnmpEventOpen() routine in the future.

OVsnmpXTrapOpen() Provided for backward compatibility of existing X11applications.

MESSAGE SETUP and MANIPULATION FUNCTIONS

OVsnmpCreatePdu() Allocates and initializes an OVsnmpPdu data structuresuitable for the specified SNMP request operation.

OVsnmpAddNullVarBind() Used in conjunction with SNMP Get, GetNext, andSNMPv2 GetBulk Requests. Allocates, initializes, andappends an OVsnmpVarBind structure for the specifiedSNMP MIB object to the SNMP Request PDU.

OVsnmpAddTypedVarBind() Used in conjunction with SNMP Set, Trap, andSNMPv2Inform Requests. Allocates, initializes, andappends an OVsnmpVarBind structure for the specifiedSNMP MIB object to the SNMP Request PDU.

OVsnmpFixPdu() Allocates and initializes a new SNMP request PDUbased on the specified response PDU. Any invalidvariable bindings are omitted from the resulting PDU.

OVsnmpCopyPdu() Creates a copy of the specified OVsnmpPdudata structureand its contained elements.

OVsnmpFreePdu() Deallocates the specified OVsnmpPdu data structure andits contained elements.

OVsnmpExtractUuid() Extract the OVsnmp UUID from an OVsnmpPdu

OVsnmpUuidFromStr() Convert a string representation of an OVsnmp UUID toits packed form.

Table 3-3 SNMP Communications API Functions (Continued)


Chapter 3 57


OVsnmpUuidToStr() Convert an OVsnmp UUID from the packed form to anASCII string.

OVsnmpOidAppend() Appends one object identifier fragments of type ObjectIDto another object identifier.

OVsnmpOidAppendN() Appends one or more object identifier fragments of typeObjectID to another object identifier.

OVsnmpOidConcat() Concatenates two object identifier fragments of typeObjectID together to produce a new object identifier.

OVsnmpOidConcatN() Concatenates two or more object identifier fragments oftype ObjectID together to produce a new object identifier.

OVsnmpOidCopy() Create a copy of an object identifier of type ObjectID.

OVsnmpOidCompare() Compare two object identifiers of type ObjectID forlexicographic ordering (less than, equal to, greater than).

OVsnmpOidFromStr() Create a new object identifier of type ObjectID from astring in dotted-numeric notation.

OVsnmpOidFromName() Create a new object identifier of type ObjectID from astring in either dotted-numeric notation, or mnemonicdescriptor (name) form as defined in the HP OpenViewloaded MIB database.

OVsnmpOidToStr() Format an object identifier of type ObjectID as a string indotted-numeric notation.

OVsnmpOidToName() Format an object identifier of type ObjectID as a stringusing the mnemonic descriptor (name) defined in the HPOpenView loaded MIB database.

OVsnmpMalloc() Allocate a block of unitialized dynamic memory.

OVsnmpCalloc() Allocate a block of dynamic memory initialized to zero.

OVsnmpRealloc() Change the size of a block of dynamically allocatedmemory.



Chapter 358


OVsnmpFree() Deallocate a block of previously allocated dynamicmemory.

COMMUNICATIONS FUNCTIONS — BLOCKING MODE

OVsnmpBlockingSend() Sends a request PDU to an SNMP agent and waits for aresponse to be received.

OVsnmpRecv() Receives an SNMP response or trap and returns theresult. If no data is available, the call is suspended untildata arrives.

COMMUNICATIONS FUNCTIONS — NONBLOCKING MODE

OVsnmpSend () Sends a request PDU to an SNMP agent, but does notwait for a response.

OVsnmpEventSend() Send a notification PDU to the OpenView Eventsubsystem. Caller can override the source address andretrieve the OVsnmp UUID of the out going event.

OVsnmpRead() Receives incoming data on pending sessions. Informationis returned via the callback function.

OVsnmpGetRetryInfo() Gets retransmission information on pending SNMPrequests for use in the select() routine.

OVsnmpDoRetry() Retransmits a pending SNMP request.

OVsnmpCancel() Cancels an SNMP request for which a response has notyet been received.

OVsnmpCallback() The application-defined function that handles responsesto non-blocking requests.

OVsnmpEventAck() Acknowledge an event in the HP OpenView EventSubsystem.

OVsnmpEventDel() Delete an event in the HP OpenView Event Subsystem.

OVsnmpEventCorrelate() Correlate two events in the HP OpenView EventSubsystem.



Chapter 3 59


OVsnmpEventUnack() Unacknowledge an alarm in the HP OpenView EventSubsystem.

OVsnmpEventChangeSev() Change the severity of an alarm HP OpenView EventSubsystem.

OVsnmpEventChangeCat() Change the category of an alarm in the HP OpenViewEvent Subsystem.

COMMUNICATIONS FUNCTIONS — X11 NONBLOCKING MODE

OVsnmpXSend() Superseded by OVsnmpSend() . It is provided forbackward compatibility of existing X11 applications.

OVsnmpXCancel() Superseded by OVsnmpCancel() . It is provided forbackward compatibility of existing X11 applications.

ERROR REPORTING FUNCTIONS

OVsnmpErrString() Obtains a pointer to an error message string thatcorresponds to the specified OVsnmpErrno error code.

SNMP_STD2OV_ERR() Translates a pdu→error_status value into anOVSNMP error code that is suitable for callingOVsnmpErrString() .

Note: This is required only if you are using the V2-styleAPI. The V1-style API allows pdu→error_status to bepassed directly.

OVUint64 ARITHMETIC FUNCTIONS

OVuint64FromStr() Converts ASCII string notation of an unsigned 64-bitinteger into OVuint64 data type.

OVuint64ToStr() Convert OVuint64 data type into ASCII string notation.

OVuint64Assign() Assigns the low and high order portions of an OVuint64value from two 32-bit values.

OVuint64Cmp() Compares two OVuint64 values for less than, equality,and greater than.



Chapter 360


Memory Management

The HP OVSNMP Communications API uses two rules of thumb formemory management:

• When you pass a data structure into a library function, it isconsumed. The memory it occupies is deallocated by the library. Forexample, the call to open a session creates an OVsnmpSession datastructure, which is later consumed by the OVsnmpClose() call.

• When you obtain a data structure from a library function, you mustdeallocate the associated memory using an OVsnmp library function.

OVuint64Shift() Performs left or right bit-shift of an OVunit64 value.

OVuint64Add() Adds two OVuint64 values and returns the sum.

OVuint64Subtract() Subtracts two OVuint64 values and returns thedifference.

OVuint64Multiply() Multiplies two OVuint64 values and returns the product.

OVuint64Divide() Divides two OVuint64 values and returns the quotient.

OVuint64CmpUInt32() Compares an unsigned 32-bit value to an OVunit64value for less than, equality, and greater than.

OVuint64AddUInt32() Adds an unsigned 32-bit value to an OVuint64 value andreturns the sum.

OVuint64SubtractUInt32() Subtracts an unsigned 32-bit value from an OVuint64value and returns the difference.

OVuint64MultiplyUInt32() Multiplies an OVuint64 value by an unsigned 32-bit andreturns the product.

OVuint64DivideUInt32() Divides an OVuint64 value by an unsigned 32-bit andreturns the quotient.



Chapter 3 61


Sometimes you may supply data to fill in a structure that the SNMPlibrary has allocated. For example, you might assign a Notification OIDor Enterprise OID to an SNMP Trap PDU. Such data must always bedynamically allocated. Otherwise, a failure occurs when the libraryattempts to deallocate statically allocated memory.

Make sure that whenever memory is allocated — whether by the SNMPlibrary or by your application — it is later deallocated. Neglecting thiscan result in a “memory leak” which gradually consumes resources untila failure occurs.

Four functions are provided for you to allocate and deallocate ancillarydata assigned to OVSNMP data structures. The are: OVsnmpMalloc() ,OVsnmpCalloc() , OVsnmpRealloc() and OVsnmpFree() . These functionsbehave the same as, and are implemented using, the underlyingoperating system malloc() , calloc() , realloc() and free()functions, respectively. The purpose of the OVSNMP API versions ofthese functions is to provide common memory allocation anddeallocation, particularly on the WindowsNT/2000 operating systemwhere the DEBUG (msvcrtd.dll ) and non-DEBUG (msvcrt.dll )versions of the C-runtime library are not compatible with each other. Thefunctions are also provide on UNIX systems for cross-platformportability.

Table 3-4, OVsnmpAPI Memory Management, summarizes the types ofdata structures allocated or deallocated by the OVSNMP API functions.Refer to the specific function description for details.

Table 3-4 OVsnmpAPI Memory Management

OVsnmpAPI Function Memory Management Performed

OVsnmpOpen()

OVsnmpXOpen()

OVsnmpWOpen()

OVsnmpTrapOpen()

OVsnmpXTrapOpen()

OVsnmpEventOpen()

OVsnmpXEventOpen()

OVsnmpWEventOpen()

Allocates returned OVsnmpSession .

Chapter 362


OVsnmpClose()

OVsnmpXClose()

Deallocates specified OVsnmpSession .

OVsnmpCreatePdu() Allocates returned OVsnmpPdu.

OVsnmpAddNullVarbind()

OVsnmpAddTypedVarbind()

Attaches allocated OVsnmpVarBind to aPDU.

OVsnmpCopyPdu() Allocates returned OVsnmpPdu (makes aduplicate of specified pdu).

OVsnmpFixPdu() Deallocates specified OVsnmpPdu. Allocatesreturned OVsnmpPdu.

OVsnmpSend()

OVsnmpXSend()

OVsnmpBlockingSend()

OVsnmpEventSend()

Conditionally deallocates specifiedOVsnmpPdu based on associated sessionFREE_Pdu flag.

If enabled, deallocates input PDU (only ifno error occurs) otherwise caller must freeinput PDU.

OVsnmpRecv() Allocates returned OVsnmpPdu; applicationmust deallocate via OVsnmpFreePdu() .

OVsnmpCallback() (application supplied) API allocated OVsnmpPdu passed as input;application must deallocate viaOVsnmpFreePdu.

OVsnmpFreePdu() Deallocates specified OVsnmpPdu.

OVsnmpMalloc()

OVsnmpCalloc()

OVsnmpRealloc()

Allocates an object ID sequence that mustbe assigned to an OVsnmpPduor deallocatedusing OVsnmpFree() .

OVsnmpFree() Deallocates specified OVsnmpPdu.

Table 3-4 OVsnmpAPI Memory Management (Continued)

OVsnmpAPI Function Memory Management Performed

Chapter 3 63

The OVSNMP Communications APIThe SNMP Communication API Data Structures

The SNMP Communication API DataStructuresThis section introduces the key data structures. See the online referencepages for specific details about other data structures. The referencepages also contain information on compiling and linking yourapplication.

NOTE HP recommends that HP-UX developers use an ANSI C compiler, suchas the HP-UX C/ANSI C compiler, for the HP 9000 Series computers. ForC++ source code, the HP Cfront C++ compiler must be used fordevelopment on HP-UX 10.X operating systems.

For HP 11.0, the HP ANSI C++ compiler must be used for C++ sourcecode. In addition, for development on HP-UX 11.0, the HP ANSI C++compiler/linker must be used to link all executables.

Microsoft Windows developers must use Microsoft Visual C++. Refer tothe Release Notes for the required version.

For Solaris 2.x HP recommends that developers use an ANSI C compilerfor C source code, for C++ source code HP recommends the use of theSPARCworks compiler suite. Refer to the Release Notes for the requiredversion.

Header Files

The header file defines many data structures that are part of theOVSNMP API. All header files are stored under a common directoryrepresented by the $OV_HEADER environment variable. See the referencepage ov.envvars for details on the $OV_HEADER environment variable.The OVsnmp header files are shown in Table 3-5, “OVSNMP HeaderFiles.”

Chapter 364


Table 3-5 OVSNMP Header Files

Header File Purpose

$OV_HEADER/OV/OVsnmp.h The main header file for OVSNMP applications. Thisfile includes all other header files (exceptOVsnmpWfns.h and OVsnmpXfns.h ) as a convenience.

$OV_HEADER/OV/OVsnmpApi.h Main function declarations, structure definitions, andcontrol definitions.

$OV_HEADER/OV/OVsnmpClnt.h More function declarations.

$OV_HEADER/OV/OVsnmpAsn1.h ASN.1 type definitions for the API. These are theASN.1 types that are supported by the OVSNMPlibrary.

$OV_HEADER/OV/OVsnmpConf.h Configuration parameter and function definitions.

$OV_HEADER/OV/OVsnmpErr.h Error value definitions.

$OV_HEADER/OV/OVsnmpWfns.h Declarations for the Microsoft Win32-specificfunctions.

$OV_HEADER/OV/OVsnmpXfns.h Declarations for the X11-specific functions in theOVSNMP library.

$OV_HEADER/OV/OVuint64.h Declarations for 64-bit integer arithmetic functions.

Chapter 3 65


Guidelines for Applications Using the SNMPv2 API

If your application uses the SNMPv2-style API, it must observe thefollowing guidelines in addition to those mentioned above:

• All PDUs passed to the API by the application must be created by theAPI; that is, the PDUs must either be returned by one of thefollowing:

— OVsnmpCreatePDU()

— OVsnmpCopyPDU()

— OVsnmpFixPDU()

— OVsnmpBlockingSend()

— OVsnmpRecv()

or passed to the nonblocking mode OVsnmpCallback() function.

• Error values derived from a PDU’s error_status field must bemapped to the OVSNMP API error code space before being passed toOVsnmpErrString() . This mapping is performed by the newlyprovided SNMP_STD2OV_ERR macro. Examples of how this macro isused can be found in $OV_MAIN_PATH/prg_samples/ovsnmp_app .

Chapter 366


Data Structures

The key data structures you will use with the OVSNMP API aredescribed in Table 3-6.

The two data structures you will use most often are the OVsnmpSessionstructure and the OVsnmpPdu structure (including its substructures).

Table 3-6 SNMP API Key Data Structures

Data StructureName

Description

OVsnmpSession Obtained by a call to OVsnmpOpen() , it identifies a particularSNMP communication session. Used as an input parameter toseveral other functions. Created by OVsnmpOpen() ; freed byOVsnmpClose() .

OVsnmpPdu Container for an SNMP message. It includes information aboutthe type of message (“Get,” “Get Next,” “GetBulk,” “Set,” “Trap,”or “Inform”), as well as the message data itself. Created byOVsnmpCreatePdu() ; freed by OVsnmpFreePdu() .

OVsnmpVarBind Elements on a linked list of variables. Each element of the listincludes an object identifier for the variable and the variable'svalue. Part of the OVsnmpPdu structure. Created byOVsnmpAddVarBind() ; freed by OVsnmpFreePdu() .

OVsnmpVal A union that can contain the value portion of an SNMP variablebinding. Part of the OVsnmpVarBind structure. Created byOVsnmpAddVarBind() ; freed by OVsnmpFreePdu() .

Chapter 3 67


The OVsnmpSession Structure

OVsnmpSession identifies a logical session between the manager and aspecific destination SNMP agent. The OVsnmpSession structure isallocated by a call to OVsnmpOpen, and is an input parameter to severalother functions. The fields are shown in Table 3-7.

Table 3-7 OVsnmpSession Fields

Field Name Type Description

community u_char The community name of the agent. Defaults to“public ,” or the value contained in the OVSNMPconfiguration database. When the session isclosed, this memory is deallocated.

community_len u_int The number of bytes in the community name.

setCommunity u_char The community name of the agent for use inSNMP set requests.

setCommunity_len u_int The number of bytes in the set community name.

sock_fd int The socket file descriptor for the session. Used toestablish the read mask for calls to select() .

(*callback)() (void *)() Points to the callback function to be invoked whena response returns from a call to OVsnmpSend() orOVsnmpXSend() , or when a notification is receivedusing OVsnmpRead() . These two send functionsare nonblocking, and the callback function is to beinvoked when the corresponding response arrives.

callback_data void * Points to application data the callback function isto receive (note the syntax of the callbackinvocation below). The memory is not accessed bythe library.

Chapter 368


protocol_version long Defines a specific SNMP protocol version to use forthis session. It is only valid when theOVSNMP_V2API bit in the session_flags field isenabled.

Valid values are:

SNMP_VERSION_1SNMP_VERSION_2CSNMP_USE_DEFAULT_VERSION

session_flags u_short A bitmask for information and control. Thefollowing values are defined:

• OVSNMP_FREE_PDU (and FREE_PDU): If set, thesend functions deallocate memory associatedwith the input OVsnmpPdu structure. Thedefault for this flag is set.

• OVSNMP_RECV_EVENTS (and RECV_TRAPS): Setthis flag if you want notifications (traps andinforms) to be passed to the callingapplication.

• The default when using OVsnmpOpen() orOVsnmpXOpen() is unset.

• The default when using OVsnmpEventOpen() ,OVsnmpXEventOpen() , OVsnmpTrapOpen() , orOVsnmpXTrapOpen() is set.

• OVSNMP_V2API: Controls the interfacesemantics of the OVsnmpAPI with regard toSNMPv1 versus SNMPv2-style operation. Thedefault for this flag is unset.

• OVSNMP_CLOSE_CALLBACK: If set, thenonblocking application callback function isinvoked for each outstanding request thatexists at the time the session is closed (viaOVsnmpClose() or OVsnmpXClose() . Thedefault for this flag is unset.

Table 3-7 OVsnmpSession Fields (Continued)


Chapter 3 69


The Callback Function

Your application determines the structure and purpose of the callbackfunction. If you use the nonblocking calls in the OVSNMP API, thecallback function defines the interaction of your application and theremote peer.

The callback function is automatically invoked when your applicationuses OVsnmpRead() to obtain the response to a nonblocking send request.In X applications, the callback is invoked automatically when theresponse arrives. The call syntax is as follows:

callback (command, session, pdu, callback_data)

If the response or notification is obtained with OVsnmpRecv instead, thecallback does not occur.

Your callback function must define the parameters in Table 3-8. Theseinput parameters are passed to the callback function. They are describedfurther in the OVsnmpPdu data structure section.

The entries in Table 3-9 define the valid values for the callbackcommand parameter.

Table 3-8 CallBack Parameters

Parameter Description

command An integer. Indicates why the callback functionwas called. See Table 3-9 for details.

session An OVsnmpSession structure. Identifies thesession with which the incoming PDU isassociated.

pdu An OVsnmpPdustructure. This is the PDU that wasreceived, or a copy of the original request PDU onsome error conditions.

callback_data Application-specific data, which is specified as thevalue passed into the OVsnmpOpen call.

Chapter 370


Table 3-9 CallBack Command Values

Command Value Note Description

GET_REQ_MSG

GETNEXT_REQ_MSG

SET_REQ_MSG

1 The pdu parameter contains the RESPONSE tothe respective type of outstanding SNMPrequest.

RESPONSE_MSG 2 The pdu parameter contains the RESPONSEto anoutstanding SNMP request.

V1TRAP_REQ_MSG 1 The pdu parameter contains unsolicited trapnotifications.

V2TRAP_REQ_MSG 2 The pdu parameter contains unsolicited trapnotifications.

INFORM_REQ_MSG 2 The pdu parameter contains an unsolicitedinform notification.

SNMP_ERR_NO_RESPONSE 1, 2 A timeout occurred without receiving aresponse. OVsnmpNoRspID (global variable)contains the outstanding request ID. structure.The pdu is NULL. The pdu is a copy of theoutstanding request.

SNMP_SYSERR_LOST_CONN 3 Indicates the connection to OpenView Eventsubsystem is disconnected. For example, thepmd process has terminated via ovstop . Thepdu is NULL.

SNMP_ERR_CLOSING_SESSION 4 Indicates the specified session is being closed byOVsnmpClose (or OVsnmpXClose) when anSNMP request is still outstanding. The pdu is acopy of the outstanding request.

Notes

(1) Occurs only if the SNMP_V2APIbit in the session_flags field is not set for the specifiedsession parameter.

(2) Occurs only if the SNMP_V2API bit in the session_flags field is set for the specifiedsession parameter.

Chapter 3 71


The OVsnmpPdu Structure

The OVsnmpPdudata structure represents the SNMP Request, Response,or Trap PDU that is sent or received by the calling application. Theinformation in this structure is encoded into and decoded from the ASN.1contents of the SNMP packet.

The OVsnmpPdu is created in one of two ways:

• Through a call to OVsnmpCreatePdu() . This is done while preparingto send a request.

• When a response or notification is received.

The SNMP send functions normally deallocate the memory associatedwith input PDU structures.1 To deallocate the PDU associated with aresponse or notification, use OVsnmpFreePdu() .

NOTE For SNMPv2 traps and informs, the OVsnmpPdu structure conveys thelogical format of the notification. The notification identifier ,timestamp and optional enterprise identifier are represented infields of the OVsnmpPdu structure. The variables list contains only the“data varbinds” for the notification. When the V2 trap or inform pdustructure is encoded into or decoded from the SNMP message, thesethree attributes are inserted into or extracted from the SNMP messagevariable-binding list.

(3) Occurs only if the specified session was created using OVsnmpEventOpen() ,OVsnmpEventXOpen() , OVsnmpTrapOpen() , or OVsnmpXTrapOpen() .

(4) Occurs only if the OVSNMP_CLOSE_CALLBACKbit in the session_flags field is set for thespecified session parameter.

Table 3-9 CallBack Command Values (Continued)

Command Value Note Description

1. Memory is not deallocated if an error occurs on the call.

Chapter 372


The fields of the OVsnmpPdu structure are shown in order in Figure 3-2.Note that this PDU has two variables. Table 3-10 describes each of theelements in the OVsnmpPdu data structure.

Figure 3-2 OVsnmpPDU Structure

*next_variable

*oid

oid_length

type

val

val_len

*integer

*string

*object_id

unio

n

*uint32

*uint64

address

command

request_id

error_status

error_index

*community

community_len

*variables

*enterprise

enterprise_length

agent_addr

generic_type

specific_type

time

SpecifictoV2 Traps& Informs

*nex_variable

*oid

oid_length

type

val

val_len

*integer

*string

*object idun

ion

*uint32

*uint64

*notify_oid

notify_oid_length

SpecifictoV1 Traps

SpecifictoV1 & V2Traps &Informs

OVsnmpPdu

OVsnmpVarBind OVsnmpVarBind

NULL

Chapter 3 73


Table 3-10 Elements of the OVsnmpPdu Data Structure


address struct

sockaddr

The address of the agent. Supportedaddress types are AF_UNSPEC (the default),AF_INET, and AF_IPX (Windows only). See“OVSNMP Over UDP/IP and IPX” onpage 50 for details.

protocol_version long Defines the specific SNMP protocol versionthat applies for this pdu . It is only valid ifthe OVSNMP_V2APImode of operation isenabled.

Valid values are:

SNMP_VERSION_1

SNMP_VERSION_2

SNMP_USE_DEFAULT_VERSION

command int The SNMP specific type of command. Mustbe one of the following:

GET_REQ_MSG

GETNEXT_REQ_MSG

SET_REQ_MSG

TRAP_REQ_MSG

GET_RSP_MSG

GETBULK_REQ_MSG

INFORM_REQ_MSG

V2TRAP_REQ_MSG

request_id int An identifier assigned by the SNMP API.This value must never be modified by yourapplication.

Chapter 374


error_status int When a response PDU is received, thisvariable contains a positive value if anerror occurred on the request. If no erroroccurred, the value is zero. This value isignored in a call to a send function.

error_index int An index into the variable list. Iferror_status shows that an erroroccurred, then error_index indicateswhich element of the list caused the error.

community u_char * When specified in a request PDU, thisvariable overrides the community name inthe session parameter for this request onlywhen a response PDU or trap PDU isreceived. This variable contains thecommunity name returned by the agent.

community_len u_int The number of bytes in the communityname.

variables OVsnmpVarBind * This is a pointer to a linked list ofvariables, each element of which is anOVsnmpVarBind data structure. Memoryreferenced by this pointer is deallocated bya call to OVsnmpFreePdu() ,OVsnmpFixPdu() , or any send function.

The following fields are specific to SNMPv1 trap and SNMPv2 trap/inform PDUs, and areinvalid for all other PDUs.

enterprise ObjectID A vendor-specific identifier that uniquelyidentifies the type of device sending thetrap. Optional for SNMPv2 traps andinforms.

enterprise_length u_int The number of elements in the object ID.The default has 11 elements.

Table 3-10 Elements of the OVsnmpPdu Data Structure (Continued)


Chapter 3 75


The OVsnmpVarBind Data Structure

The OVsnmpVarBind data structure represents a single SNMP variablebinding included in an SNMP PDU. The variable binding specifies theinformation the application wants to get from or set in the SNMP agent.Table 3-11 describes each of the elements.

agent_addr u_long The IP address of the agent that sent thetrap. Represented in Network Byte Order.For OVSNMP over IPX, this value is zero.

time u_long The time (in tenths-of-seconds) since theagent was last activated. The default is thelength of time that the application has beenrunning.

The following fields are specific to SNMPv1 trap requests, and are invalid for all otherPDUs.

generic_type int One of the SNMP-defined types of trap. SeeRFC 1157 for details.

specific_type int When generic_type indicates that anenterprise-specific trap has occurred, thevalue of specific_type contains thespecific trap. Otherwise, the value ismeaningless.

The following fields are specific to SNMPv2 Trap and Inform Requests, and are invalid forall other PDUs.

notify_oid ObjectID * Contains the snmpTrapOID variablebindings in the raw SNMPv2 Trap orInform Request message.

notify_oid_len u_int The number of elements in the object ID.

Table 3-10 Elements of the OVsnmpPdu Data Structure (Continued)


Chapter 376


Table 3-11 Elements of the OVsnmpVarBind Data Structure


next_variable OVsnmpVarBind * Points to the next element in the variablelist. NULL in last element.

oid ObjectID * The object identifier (object ID) for thisvariable.

oid_length u_int The number of elements in the object ID forthis variable.

type u_char The ASN.1 type of the variable. Must beone of the types listed in Table 2-2.

val OVsnmpVal A union containing the possible data types.The active field is indicated by type(above).

val_len u_int The number of elements in the value of thevariable. Note that this may not equal thenumber of bytes in the “val”; object IDs, forexample, consist of an array of longintegers.

Chapter 3 77


The OVsnmpVal data structure is a union of the possible data types forthe variable. The OVsnmpVal data can be any of the Union Memberslisted in Table 3-12.

To see how the OVsnmpVal data structure relates to the OVsnmpVarBinddata structure, see Figure 3-2.

Table 3-12 OVsnmpVarBind Union Members

Union Member For SNMP Type:

integer INTEGER

Octet string (array of 8-bit values) OctetString, IpAddr

object ID Object ID

unsigned 32-bit integers Counter32, Gauge32,Unsigned32, TimeTicks

unsigned 64-bit integers Counter64

Chapter 378

4 The NNM Event Database API

Chapter 4 79

The NNM Event Database API

This chapter describes the functions and data structures in the HP NNMEvent Database API. It includes descriptions of the following:

• The NNM Event Database

• NNM Event Database API functions

Chapter 480

The NNM Event Database APIThe NNM Event Database

The NNM Event DatabaseThe OVEventDb API is a set of library functions which provide readaccess to the OpenView Event Database. (see eventdb (4) for adescription of the OpenView Event Database.) It enables the callingapplication to retrieve log events and/or stream events stored in theOpenView Event Database. Applications can also get correlationinformation between events from the OpenView Event Database. Thereare four log file groups in the OpenView database.

• Event Log File Group contains all the raw events received by pmdandall the events generated by the Event Correlation engine with thefollowing exception. Events configured as IGNORE in trapd.confare not logged in the event database.OVEventDbOpenLogForReading() , OVEventDbReadNextEvent() ,and OVEventDbGetOVsnmpPdu() can access data from this file group.

• NDBM Offset File Group is a series of four New Database Managerdatabases (NDBM) which are maintained in “lock-step” with theEvent Log File Group. That is, whenever an event record is writtento an Event Log File, a corresponding NDBM event offset record iswritten to the corresponding NDBM Offset File. There is no API todirectly access this file group.

• Stream Log File Group is a series of four binary files that record theassociation of an event with an ECS event stream.OVEventDbOpenStreamForReading() , OVEventDbReadNextEvent() ,and OVEventDbGetOVsnmpPdu() can access data from this file group.

• Correlation Log File Group is a series of four binary files that recordthe association of two events within an ECS event stream. Thecorrelation log contains records of this relationship. Often, an eventis the parent of several child events. In this case, the log contains acorresponding number or records, each with the same parent eventin the association but with different child events.OVEventDbOpenCorrLogForReading() ,OVEventDbFindCorrelatedEvents() ,OVEventDbGetCorrelationTree() , and other related API functionscan access data from this file group (see the OVEventdb API listbelow).

Chapter 4 81

The NNM Event Database APIThe NNM Event Database

There are two ways to get correlated events for a given event.

• Use OVEventDbFindCorrelatedEvents() andOVEventDbEventListGetNext() to retrieve a list of events, whichare directly correlated to the parent event.

• Use OVEventDbGetCorrelationTree() and related API functions torecursively find all child events correlated to the parent event. Sinceeach child event may have children, this operation involves arecursive descent. These events are stored in a list and returned indepth first order. The operation can be lengthy, because the entirecorrelation log must be searched to find the correlations.

Chapter 482

The NNM Event Database APIThe NNM Event Database API Functions

The NNM Event Database API FunctionsThe functions in the NNM Event Database AP fall into the followingcategories: database access, freeing resources, and other datamanipulation such as correlating events, and determining tree events.

Table 4-1 NNM Event Database API Functions

Function Description

DATABASE ACCESS and QUERYING

OVEventDbOpenCorrLogforReading()Open the OpenViewEvent DatabaseCorrelation log file group for reading.

OVEventDbOpenLogforReading()Open the OpenView Event Database logfile group for reading.

OVEventDbOpenStreamforReading()Open the OpenView Event Databasestream log file group for reading.

OVEventDbReadNextCorrEntry()Retrieve the next correlation entry fromthe open database.

OVEventDbReadNextEvent()Reactivate the next event from the opendatabase.

OVEventDbClose() Close the eventdb handle.

OVEventDbIsEventCorrelated() Determine if an event is correlated or not.

OVEventDbFindCorrelatedEvents()Find a list of events that are correlatedwith a particular event.

OVEventDbGetCorrelationTree()Recursively find all child events whichare correlated under a particular event.

FREEING RESOURCES

OVEventDbFreeEvent()Free the resources associated with anOVeventHandl e.

OVEventDbFreeCorrEntry()Free the resources associated with anOVcorrEntryHandle .

Chapter 4 83


OVEventDbFreeEventList()Free the resources associated with anOVeventListHandle .

OVEventDbFreeCorrEntryList()Free the resources associated with anOVcorrEntryListHandle .

OTHER DATA MANIPULATION

OVEventDbEventListGetNext()Iterate through an event list and returnthe next event handle in the list.

OVEventDbCorrEntryListGetNext()Iterate through a correlation entry listand return the next correlation entry inthe list.

OVEventDbCorrEntryListGetNumElements()Return the number of elements in the listassociated with theOVcorrEntryListHandle .

OVEventDbGetCorrEventStatus()Return the status of a correlated eventassociated with the OVcorrEntryHandle .

OVEventDbGetParentId()Return the eventId of the parent eventassociated with a OVcorrEntryHandle .

OVEventDbGetChildId()Return the eventId of the child eventassociated with an OVcorrEntryHandle .

OVEventDbGetNumChildren()Return the number of descendent eventsthat are correlated below corrEntry.

OVEventDbGetChildEvent()Return an OVeventHandle that refers tothe child event associated with anOVcorrEntryHandle .

OVEventDbGetTreeLevel()Return the number of ancestor eventsthat are correlated above corrEntry .

OVEventDbGetOVsnmpPdu()Create an OVsnmpPdu from an eventpacket.

Table 4-1 NNM Event Database API Functions (Continued)


Chapter 484


OVEventDbEventIdtoUuid()Convert OVeventId into OVsnmpUuidformat.

OVEventDbUuidToEventId()Convert OVsnmpUuid into OVeventformat.

Table 4-1 NNM Event Database API Functions (Continued)


Chapter 4 85

The NNM Event Database APIMemory Management

Memory ManagementIf an OVEventDb API returns a handle, the calling application must freethe memory associated with the handle.

If the API has an output pointer, the calling application must free thememory associated with the output pointer.

Data Structure

Data structure handles in OVEventDb API are opaque to theapplication. You must use related API to manipulate them:

typedef void *OVeventDbHandle;

typedef void *OVeventHandle;

typedef void *OVeventListHandle;

typedef void *OVcorrEntryHandle;

typedef void *OVcorrEntryListHandle;

Chapter 486

5 The OVSNMP ConfigurationAPI

Chapter 5 87

The OVSNMP Configuration API

This chapter describes the functions and data structures in the HPOVSNMP Configuration API. It includes descriptions of the following:

• the OVSNMP Configuration database

• OVSNMP Configuration API functions

• key data structures in the OVSNMP Configuration API, includingeach element and its use

Chapter 588

The OVSNMP Configuration APIThe OVSNMP Configuration Database

The OVSNMP Configuration DatabaseThe OVSNMP configuration database is a repository on the managementstation for the configuration information that controls the behavior of anSNMP session. The configuration parameters control behaviors such as:

• the number and frequency of retries if a response is not received

• the community name to use in SNMP requests

• the port on the agent node where requests should be sent

• whether the agent is a proxy agent

• the protocol version to be used

The OVSNMP Configuration API provides programmer access to theSNMP configuration database. Three classes of configuration parametersare stored in the database:

• parameters for specific managed nodes

• parameters for wildcarded IP addresses

• parameters for a global default

Whenever the configuration parameters for a managed node arerequested, they are obtained from these three classes of storedinformation. The resulting parameters and the associated IP address ofthe destination can be cached, allowing subsequent lookups to beperformed more quickly.

Chapter 5 89

The OVSNMP Configuration APIThe OVSNMP Configuration API Functions

The OVSNMP Configuration API FunctionsThe thirty-two functions in the OVSNMP Configuration API fall into fivecategories: database access, resolution, editing, administration, andmiscellaneous.

Table 5-1 SNMP Configuration API Functions


DATABASE ACCESS

OVsnmpConfOpen() Open the SNMP configuration database for subsequentaccess.

OVsnmpConfClose() Close the SNMP configuration database.

OVsnmpConfDbName() Obtain the pathname of the SNMP configurationdatabase.

OVsnmpConfFileName() Obtain the pathname of the backwards compatibility(shadow) file that is associated with the SNMPconfiguration database.

RESOLUTION

OVsnmpConfResolveDest() Obtain the effective configuration parameters for aspecified destination agent.

OVsnmpConfFreeDest() Deallocate all memory associated with theOVsnmpConfDest structure returned byOVsnmpConfResolveDest(3).

EDITING

OVsnmpConfReadNextEntry() Sequentially read specific node records from the SNMPconfiguration database.

OVsnmpConfReadEntry() Read a specific node record from the SNMPconfiguration database.

OVsnmpConfCreateEntry() Create a new specific node record in the SNMPconfiguration database. This operation will fail if arecord already exists for the specified node.

Chapter 590


OVsnmpConfStoreEntry() Create or replace, as necessary, a specific node record inthe SNMP configuration database.

OVsnmpConfDeleteEntry() Delete a specific node record from the SNMPconfiguration database.

OVsnmpConfAllocEntry() Allocate an OVsnmpConfEntry structure.

OVsnmpConfCopyEntry() Allocate and initialize an OVsnmpConfEntry structurewith the values from the specified OVsnmpConfEntrystructure.

OVsnmpConfParseEntry() Allocate and initialize an OVsnmpConfEntry structurewith the values extracted from a configuration string inthe format of an ovsnmp.conf(4) configuration file entry.

OVsnmpConfFreeEntry() Deallocate all memory associated with the specifiedOVsnmpConfEntry structure.

OVsnmpConfReadWcList() Read the list of IP address wildcard records from theSNMP configuration database. Since the semantics ofwildcard records are partly dependent upon the order ofthe records in the database, these records can only beupdated as a single list.

OVsnmpConfStoreWcList() Create or replace, as necessary, the list of IP addresswildcard records in the SNMP configuration database.

OVsnmpConfAllocWcLis() Allocate memory for an OVsnmpConfWcList structure.This structure may then be inserted into the wildcardlist obtained using OVsnmpConfReadWcList(3).

OVsnmpConfFreeWcList() Deallocate all memory associated with the specified listof OVsnmpConfWcList structures.

OVsnmpConfReadDefault() Read the global default record from the SNMPconfiguration database.

OVsnmpConfStoreDefault() Create or replace, as necessary, the global defaultrecord in the SNMP configuration database.

Table 5-1 SNMP Configuration API Functions (Continued)


Chapter 5 91


OVsnmpConfGetVersions() Determine which SNMP protocol versions aresupported by an agent by reading the SNMPconfiguration database.

OVsnmpConfSetVersions() Store or modify the field in the SNMP configurationdatabase that indicates the SNMP protocol versions,which are supported by a particular agent.

OVsnmpConfImportFile() Replace the contents of the SNMP configurationdatabase with records extracted from configurationstrings in the specified ovsnmp.conf configuration file.

OvsnmpConfExportFile() Dump the contents of the SNMP configuration databaseto the specified ovsnmp.conf configuration file.

ADMINISTRATION

OVsnmpConfReadCntl() Read the current SNMP configuration databaseadministration record. This record contains optionswhich control run-time caching and use of the backwardcompatibility configuration file.

OVsnmpConfStoreCntl() Update the current SNMP configuration databaseadministration record. This enables you to modify theoptions which control runtime caching and use of thebackward compatibility file.

MISCELLANEOUS

OVsnmpConfDeleteCache() Remove all entries from the SNMP configurationrun-time cache. New entries accumulate in the cache asapplications call OVsnmpOpen() andOVsnmpConfResolveDest() .

OVsnmpConfReadNextDest() Sequentially read entries from the SNMP configurationrun-time cache. This function is provided fortroubleshooting only (such as dumping the contents ofthe cache for inspection.)



Chapter 592


OVsnmpConfPrintDest() Print the contents of an OVsnmpConfDest structure tostdout on UNIX systems or to the console window onWindows operating systems.

OVsnmpConfPrintEntry() Print the contents of an OVsnmpConfEntry structure tostdout on UNIX systems or to the console window onWindows operating systems.

OVsnmpConfPrintCntl() Print the contents of an OVsnmpConfCntl structure tostdout on UNIX systems or to the console window onWindows operating systems.



Chapter 5 93

The OVSNMP Configuration APIData Structures for the OVSNMP Configuration API

Data Structures for the OVSNMPConfiguration APIThis section describes key data structures, including their purposes andrelationships. Specific details about other parameters to SNMP functionsare available in the online reference pages.

Header Files

The header file defines many data structures that are part of theOVSNMP configuration API. The only header file required to use theOVSNMP configuration API functions is$OV_HEADER/OV/OVsnmpConf.h1. See Table 3-5 for a list of all headerfiles included in the OVSNMP API.

Data Structures

Table 5-2 describes the key data structures that are used with theOVSNMP Configuration API.

1. See the reference page for ov.envvars for details on theenvironment variable $OV_HEADER.

Table 5-2 SNMP Configuration API Data Structures

Data Structure Description

OVsnmpConfEntry This structure contains the parameters thatmake up an SNMP configuration record for aparticular destination in the managedenvironment. It is also used as a substructurein the OVsnmpConfWcList and OVsnmpConfDeststructures.

OVsnmpConfWcList This structure forms an element of a linked listused to represent the IP address wildcard list.

Chapter 594


The OVsnmpConfEntry Structure

The OVsnmpConfEntry structure is the principal data structure used forSNMP configuration. This structure contains the parameters that makeup the SNMP configuration record for a particular destination in themanaged environment. When used alone or in the OVsnmpConfWcListstructure with the configuration editing function, some of the fields maynot be filled in; that is, they are assigned a value that indicates usedefault. In this case the actual configuration value is determined atruntime by the OVsnmpConfResolveDest() function as part of theOVsnmpConfDest structure.

The OVsnmpConfEntry structure has the fields shown in Table 5-3:

OVsnmpConfDest This structure contains the fully-resolvedconfiguration parameters for a particulardestination in the managed environment.Additionally, it contains addressing informationwhich is determined at run time instead ofbeing stored in the configuration database.

OVsnmpConfCntl This structure contains administrative optionswhich control how run-time caching and thebackward compatibility configuration file areused by the OVSNMP API.

Table 5-2 SNMP Configuration API Data Structures (Continued)

Data Structure Description

Table 5-3 OVsnmpConfEntry Structure

Type Name Description

char * name The name of the destination for which the configurationparameters apply. This may be an IP hostname, an IPaddress, an IP address wildcard, or a non-SNMP entity thatis proxied for.

char * community The SNMP community name, which is used by the OVSNMPAPI when issuing SNMP Get and GetNext requests to thedestination. This community name is also used for SNMPSet requests if the setCommunity field is not specified.

Chapter 5 95


The OVsnmpConfWcList Structure

The OVsnmpConfWcList structure is used to create a linked list ofOVsnmpConfEntry structures that represent the IP address wildcardconfiguration. The linked list is required since the semantics of an IPaddress wildcard record depends upon the order of the records within theIP address wildcard list. When OVsnmpConfResolveDest() resolvesdefaulted configuration values, it searches the IP address wildcard list inorder to fill in those defaulted values.

char * setCommunity The SNMP community name, which is used by themanagement application when issuing SNMP Set requeststo the destination.

char * proxy The identity of a proxy for the destination. This may be anIP hostname or an IP address. If the destination is accesseddirectly, this field contains the value ofSNMP_CONF_DONT_PROXY_STRING.

int timeout The amount of time, in tenths of a second, the OVSNMP APIwill initially wait for an SNMP response before attemptingto retransmit the SNMP request to the destination.

int retry The maximum number of retransmissions the OVSNMPAPI will attempt before generating a no response conditionfor an SNMP request.

int pollInterval The frequency, in seconds, at which netmon determines thestatus of the destination node. This field is not used by theOVSNMP API.

u_short remotePort The UDP port number on the destination or proxy node (asappropriate) where the SNMP agent on that node expects toreceive SNMP requests for the destination. The standardSNMP port is 161. This field is generally used only forspecialized proxy agents which do not listen to the standardSNMP port.

Table 5-3 OVsnmpConfEntry Structure (Continued)


Chapter 596


In Figure 5-1, the fields of the OVsnmpConfWcList structure are shown inorder. Note that the configuration parameters are contained in anOVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-1 OVsnmpConfWcList Structure

Table 5-4 describes the fields in the OVsnmpConfWcList data structure:

* next

* confEntry

*name

* next

* confEntry

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

*name

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

OVsnmpConfWcList OVsnmpConfWcList

OVsnmpConfEntry OVsnmpConfEntry

NULL

Table 5-4 OVsnmpConfWcList Structure

Type Field Name Description

structSNMPconfwclist *

next A pointer to the next OVsnmpConfWcList entry inthe IP address wildcard list. The value for thisfield should be NULL for the last entry in the list.

OVsnmpConfEntry * confEntry A pointer to the OVsnmpConfEntry structure thatcontains the configuration parameters for the IPAddress wildcard entry.

Chapter 5 97


The OVsnmpConfWcList structure is returned by a call toOVsnmpConfReadWcList() and should be deallocated by a call toOVsnmpConfFreeWcList() .

The OVsnmpConfDest Structure

The OVsnmpConfDest structure contains the fully resolved configurationparameters for a particular destination in the managed environment. Itis based upon the OVsnmpConfEntry structure, and it containsaddressing information which is determined at run time instead of beingstored in the configuration database. The values assigned to theOVsnmpConfEntry portion of this structure are obtained from acombination of specific node, IP address wildcards and global defaultconfiguration records to determine an actual configuration value for eachfield.

The OVsnmpConfDest structure is returned by a call toOVsnmpConfResolveDest() and should be deallocated by a call toOVsnmpConfFreeDest() .

In Figure 5-2 the fields of the OVsnmpConfDest structure are shown inorder. The configuration parameters are contained in anOVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-2 OVsnmpConfDest Data Structure

*confEntry

isProxied

ipAddr*name

*community

*setCommunity

*proxy

timeout

retry

pollInterval

remotePort

ipAddrAge

agent name

agentAddr

OVsnmpConfDest

OVsnmpConfEntry

Chapter 598


Table 5-5 describes the fields in the OVsnmpConfDest data structure.

Table 5-5 OVsnmpConfDest Data Structure

Type Field Name Description

OVsnmpConfEntry * confEntry A pointer to the OVsnmpConfEntry structurewhich contains the fully-resolved configurationparameters for the specified destination.

short isProxied A boolean flag indicating whether or not the IPaddress for this destination is that of the actualdestination (FALSE) or that of a proxy node (TRUE).

struct sockaddr* agentAddr Pointer to the address of the SNMP agent for thisdestination. Supported address families areAF-INET and AF-IPX . By default, only AF_INET(udp/ip) destinations are returned.The SNMP_CONF_RESOLVE.ANYADDR flag must bespecified as input to OVsnmpConfResolveDest()in order for both IP and IPX destinations to bereturned. This is done for compatibility of existingIP-only applications.

u_long ipAddr The IP address of the peer entity to which SNMPrequests should be sent for the specifieddestination. This field has been replaced byagentAddr . It is retained for backwardscompatibility of existing applications. For IPagents, this value is the same as(sockaddr_in*)agentAddr → sin_addr.s_addr .For IPX agents, this value is zero.

time_t ipAddrAge The date and time when the ipAddr field was lastqueried from the IP address name server. Thisvalue is obtained from time() .

char * agentName The fully distinguished name of the nex_hopagent associated with the destination target.

Chapter 5 99


The OVsnmpConfCntl Structure

The OVsnmpConfCntl structure contains administrative options whichcontrol how run-time caching and the backward compatibilityconfiguration file is used by the OVSNMP API. Its fields are shown inTable 5-6.

Cache Flags

The cache flag in the OVsnmpConfCntl structure may be set to one of thefollowing:

• SNMP_CONF_CACHE_NONE

Run-time caching of SNMP configuration parameters and IPaddresses is disabled. The information is recomputed each time adestination is referenced.

Table 5-6 OVsnmpConfCntl Structure


int ipAddrAge The age limit, in seconds, for IP address stored in theSNMP configuration run-time cache. This value is usedby OVsnmpConfResolveDest() to determine when acached IP address must be updated by consulting thesystem’s IP address name server.

cacheFlags_t cacheFlags The level of run-time cache enabled for the SNMPconfiguration database. By default, resolvedconfiguration parameters and the IP address ofpreviously referenced destinations are cached. Thisimproves the performance of applications when thesame destination is subsequently referenced.

compat3_2_t compatFlags The level of backward compatibility for SNMP PlatformRelease 3.2 that is enabled for the SNMP configurationdatabase. This compatibility mode is disabled bydefault beginning with NNM Release 5.0.

Chapter 5100


• SNMP_CONF_CACHE_NOADDR

SNMP configuration parameters for previously referenceddestinations are maintained in the SNMP configuration run-timecache. However, the IP address of those destinations is notmaintained in the cache. The IP address is determined each time thedestination is referenced by consulting the IP address name server.

• SNMP_CONF_CACHE_ALL

Both SNMP configuration parameters and the IP address ofpreviously referenced destinations are maintained in the SNMPconfiguration run-time cache.

Compatibility Flags

The compatibility flag in the OVsnmpConfCntl structure may be set toone of the following:

• SNMP_CONF_SHADOW_NONE

The configuration file for release 3.2 backward compatibility is notmaintained. This mode of operation should only be used if allOVSNMP API-based applications installed and running on thesystem have been linked with a later release of the OVSNMP API.

• SNMP_CONF_SHADOW_32ONLY

Only the subset of entries in the SNMP configuration database,which are configured to use the default SNMP port forcommunications, are maintained in the backward compatibility file.This will optimize performance of Release 3.2-based applications.However, if the xnmsnmpconf -import command is subsequentlyused with the resulting shadow file, some information in the SNMPconfiguration database will be lost.

• SNMP_CONF_SHADOW_ALL

All entries in the SNMP configuration database are maintained inthe Release 3.2-compatible configuration file. This mode of operationensures absolute consistency between the SNMP configurationdatabase and the compatibility configuration file. However, thismode may cause unnecessary performance degradation of Release3.2-based applications if there are many proxy entries which use anon-default SNMP port configured in the SNMP configurationdatabase.

Chapter 5 101


Chapter 5102

6 Integrating with Logging andTracing

Chapter 6 103

Integrating with Logging and Tracing

Network management applications (managers and agents) are generallycomplex. Whenever unexpected behavior is seen, it is useful to havedetailed information about the state of the application, and even ahistory of what preceded the behavior. Logging and tracing are two toolsfor obtaining this kind of information. They both involve tracking statechanges in your software.

The occurrence of certain incidents can trigger a new entry in the log file.For example, an agent might enter a log message when a particularvalue is set. A key attribute of each incident is its severity, which is oneof four levels ranging from INFORMATIVE to DISASTER.

Tracing, on the other hand, is used to trace step-by-step the execution ofyour program. For example, trace messages are typically written at theentry and exit points of each function.

Chapter 6104

Integrating with Logging and TracingOverview of Logging and Tracing

Overview of Logging and Tracing

HP-UX and Solaris

Logging and tracing have different objectives:

Logging Logging is generally provided for the benefit of systemor network administrators and some sophisticated endusers. The messages you log should be understandableto this class of user. The system administrator uses thenettl utility to configure, filter, and format logmessages. Owing to its implementation, HP OpenViewlogging has practically no impact on the performance ofyour manager or agent. Therefore, logging is generallyturned on at all times.

Tracing Tracing is far more comprehensive in its intent.Tracing provides unambiguous evidence about thestate of execution at key points in the code. Tracing isintended primarily for the developer, to assist duringthe testing phase of development. It is not intended forend-customer use; the information in the tracing files istypically understood only by the developer, or bytrained field support personnel. When you turn tracingon, you should expect to experience a moderatedegradation of performance. Therefore, tracing isgenerally on only during testing and debugging.

The OVuTL API is provided to let you integrate your application with thecommon logging and tracing facility called nettl . This facility usesdaemon processes to receive log and trace data from networkapplications (including the platform itself), and to direct that data to itsappropriate destination.

For more information about the nettl subsystem, see the nettl (1M)manpage, as well as other manpages to which it refers.

Chapter 6 105

Integrating with Logging and TracingOverview of Logging and Tracing

Windows Operating Systems

On Windows operating systems, the Event Log APIs provide a way tohandle application and system logging. The Event Viewer applicationlets you view and manipulate log data.

The Event Viewer lets you filter events by category, source, type(severity), dates, computer, and event ID. You can set the log size andoverwrite options. The Event Viewer also formats and displays the data.The OVuTL API lets you integrate your application with the commonlogging and tracing facility using the Event Viewer.

The Event Viewer, shown below, is found in the Administrative Toolsprogram group. Refer to your Windows operating system documentationfor details on using the Event Viewer.

Figure 6-1 Windows Event Viewer

Chapter 6106

Integrating with Logging and TracingThe OVuTL Application Programming Interface

The OVuTL Application ProgrammingInterfaceThere are three functions in the OVuTL API:

For more information about the OVuTL API, see the OVuTL (3) referencepage in this manual. It contains important details, examples of how touse this API, and examples of how to get output.

Table 6-1 Functions in the OVuTL API


OVuTLInit() Initializes the name of the calling software and the hostname for thelogging and tracing output. You must call OVuTLInit() once only,before any calls to OVuLog() or OVuTrace() .

OVuLog() Enters a log message in the log file. By default this is$NETFMT_LOG_FILE (HP-UX and Solaris) or Event Viewer (Windows).

OVuTrace() Enters a trace message in the trace file. By default this is$NETFMT_TRC_FILE (HP-UX and Solaris) or Event Viewer (Windows).

Chapter 6 107

Integrating with Logging and TracingThe OVuTL Application Programming Interface

Chapter 6108

7 Integrating with ProcessManagement

Chapter 7 109

Integrating with Process Management

The HP OpenView platform provides a robust process managementmechanism, which coordinates the startup, shutdown, pause, andresume of the various NNM processes. This permits you to specify whichprocesses your application or process expects to find when it “wakes up,”and to control other related aspects of your interaction with NNM.

This chapter covers

• a brief overview of process management in the HP OpenViewplatforms

• the OVsPMD application programming interface (OVsPMD API)

• guidelines for constructing the first and second lines of a LocalRegistration File

• guidelines for integrating your application with NNM’s automatedbackup

NOTE The Local Registration File (LRF) is an important file for your process.This chapter discusses only the first and second line of that file, sincethese lines pertain to process management. Any additional lines in thisfile are not relevant to Network Node Manager.

Chapter 7110

Integrating with Process ManagementProcess Management for HP OpenView Applications

Process Management for HP OpenViewApplicationsFrom the perspective of a system administrator, process management onthe HP OpenView platform is largely invisible. Two commands —ovstart and ovstop — execute the startup and shutdown functions.ovstatus obtains status information for processes controlled by ovpsmd.ovpause and ovresume put NNM processes in a state that allows for safebackup and returns them to normal processing.

Behind these commands, however, is the process management daemonovspmd, as illustrated in Figure 7-1. This daemon:

• handles requests from the administrative commands noted above

• starts and stops processes as required

• pauses and resumes processes which access NNM’s databases, logfiles, and configuration files and returns these processes to normalprocessing

• monitors processes for termination

• logs startup and shutdown information to the tracing and loggingsubsystem.

ovspmd obtains information about which processes to start, and when tostart them, from the “startup” file, or SUF. The SUF is constructed by theovaddobj command, which adds startup information each time it is run,based on the Local Registration File that it reads.

Chapter 7 111


NOTE On Windows operating systems, ovspmd is a “service.” Refer to yourWindows operating system documentation for details on services.

Figure 7-1 Process Management

Figure 7-1 illustrates how the ovspmd process operates. Note that thediagram shows three kinds of processes:

Well-behaved Processes

A well-behaved process uses the OVsPMD API — thetopic of the next section — to communicate withovspmd. It sends ovspmd status information regardingsuccessful and unsuccessful initialization, normal andabnormal termination, and pause and resumeinformation if configured to do so. ovspmd considers a“well-behaved” process to have initialized successfullyonly when it explicitly reports that it has. A“well-behaved” process also exits when it receives thecommand OVS_CMD_EXIT from ovspmd. If the processfails to respond, the exit command is escalated to

Administrative Commands:

ovstart , ovstop , ovpause ,ovresume ,ovstatus

Responses

Requests

LRF ovaddobjcommand

ovsuf

ovsnmpdTracing &LoggingSubsystem

Well-behavedProcess

Well-behavedProcess

Non-well-behavedProcess

DaemonProcess

Chapter 7112


SIGTERM, and eventually to SIGKILL . It will respond toOVS_CMD_PAUSEand OVS_CMD_RESUME commands if itis configured to receive them.

The status information passed by the managed processto ovspmd is used by ovstart , ovstop , ovstatus ,ovpause or ovresume , if currently running. The lastmessage received from each managed process is saved,and forwarded, on request, to ovstatus . The messagesreceived from “well-behaved” processes are also loggedusing the nettl logging and tracing facility.

Non-well-behaved Process

ovspmd can also manage object managers that do notuse the OVsPMD API (“non-well-behaved” processes)only if they do not go into the background of their ownaccord (see OVs_DAEMON which follows). Since a“non-well-behaved” process returns no statusmessages, ovspmd considers such processes to haveinitialized successfully if the process has not exitedwithin the lrf specified timeout interval.

During shutdown, the ovspmd process sends SIGTERMto non-well- behaved processes to notify them of theneed to terminate. Non-well-behaved processes thatfail to terminate within the configured timeout are sentSIGKILL .

Daemon Process

Managed processes that go into the background cannotbe managed either with a communication channel orwith signals. ovspmd can start such a process, butcannot stop or report meaningful status about it, sinceit has neither a communication channel nor a processID for it.

However, you can run a script or program to stop thedaemon. Refer to “Field 7: Daemon Stop Command” onpage 122.

You need to decide which type of process to create.

1. If you are writing a new program, you will probably want to use theOVsPMD API and create a well-behaved process. This is by far thebest choice.

Chapter 7 113


2. If you have an existing process that does not go into the background,you can decide to not modify it, and declare it a non-well-behavedprocess. This may be expedient, but it is less than ideal. It would bebetter to take a little time to incorporate simple calls to the OVsPMDAPI and create a well-behaved process.

3. If you have an existing process that does go into the background, youcan decide to not modify it, and declare it a daemon process. This toomay be expedient, but results in a poorly integrated process.

4. If you want your process to receive pause and resume notification,your process must be well-behaved.

To decide what to do, you may want to understand something about theOVsPMD API, the topic of the next section.

Chapter 7114

Integrating with Process ManagementThe OVsPMD Application Programming Interface

The OVsPMD Application ProgrammingInterfaceTo create a well-behaved process, you need to use the OVsPMD API,which has these functions:

See the reference page for OVsPMD_API (3) for additional details. Ingeneral, use these rules to create a well-behaved process:

1. Call OVsInit() when your process begins initialization. This givesyou a socket for later communication with the ovspmd process.

2. After initialization is complete—and regardless of whether it wassuccessful or not—you must call OVsInitComplete() . A parameterto OVsInitComplete() indicates the initialization status; ifinitialization failed, your process should call OVsInitComplete()and exit (do not call OVsDone() ).

Table 7-1 Functions in the OVsPMD API


OVsInit() Indicates that the process is beginning its initializationphase. Returns a file descriptor (communication channel)for communicating with ovspmd.

OVsInitComplete() Indicates that the process has finished its initializationphase.

OVsReceive() Receives a command from ovspmd. The commands areOVS_CMD_EXIT, which indicates that your process shouldterminate, OVS_CMD_PAUSE which indicates that yourprocess should pause, and OVS_CMD_RESUME whichindicates that your process should resume.

OVsDone() Informs ovspmd that the process is terminating normally.One parameter is a text message used to indicate thereason for termination.

OVsResponse() Responds to pause and resume commands issued byovspmd.

Chapter 7 115

Integrating with Process ManagementThe OVsPMD Application Programming Interface

3. Your process’s control thread should be organized around a select()loop, waiting for input from managers or from the managed object.Select for reading on the file descriptor returned by OVsInit() .

4. When select() indicates the ovspmd file descriptor is readable, useOVsReceive() to get the command from ovspmd. OVS_CMD_EXITmeans your process should “clean up”, call OVsDone() , and exit.OVS_CMD_PAUSEmeans your process should suspend data processing.OVS_CMD_RESUME means your process can resume data processing.

5. If your process exits on its own initiative (that is, withoutinstructions from ovspmd), call OVsDone() , indicating in the messageparameter the reason for termination. This message will be loggedby ovspmd along with other exit information.

6. Never go into the background (fork and exit in the parent); the childprocess cannot be managed by ovspmd.

Chapter 7116

Integrating with Process ManagementThe Local Registration File

The Local Registration FileEach process must have an associated Local Registration File, or LRF.The LRF is a specially formatted ASCII file that serves two functions:

• The LRF declares information about the process, including:

— its name

— where its executable code is located

— how to start it.

• The LRF also declares information about the objects the processmanages. (These declarations appear in any additional lines afterthe first two in the LRF)

As a developer, it is your responsibility to provide an LRF with yourprocess. The LRF makes it possible for the HP OpenView platform tomanage your process. The LRF must contain the first two lines ofinformation, which describe the process.

Structure of the Local Registration File

Table 7-2 describes the purpose of each line in an LRF.

Table 7-2 Purpose of Each Line in a Local Registration File

Line Description

First Specifies the process name, and the pathname of itsexecutable file.

Second Specifies process management information, which isdescribed next.

Chapter 7 117


General Syntax

Each line in an LRF contains two or more fields. Each field is terminatedby a colon, including the last field. Some fields are optional; it isrecommended that you still include the colon terminator for the missingfields.

The number symbol (#) indicates the beginning of a comment, whichcontinues to the end of the line. White space (spaces, tab characters, andnewlines) is not permitted within any field, nor are any multibytecharacters. In the first two lines of the LRF, only printable ASCIIcharacters are allowed (values between decimal 32 and 126). The colon(: ), comma (, ), backslash (\ ), and number sign (#) can only appear asterminator characters, as noted above and in later syntax descriptions.

NOTE You must put a backslash in front of the colon that specifies the drivespecification on the Windows operating systems. This prevents the colonin the path from being interpreted as a field terminator.

First Line of the LRF

The first line of the LRF specifies the name and location of the process:

Field 1: Name

Specifies the name of the process being registered. You are responsiblefor ensuring the uniqueness of the process name.

For example, you could append your company’s name:

IPMgr_A.017.0_MegaCorp_International

Table 7-3 First Line of the LRF

Field Syntax Default

1: Name A character string forthe process name.

None (must bespecified).

2: Path A character string. None (must bespecified).

Chapter 7118


The name must be the same name used in the session parameter to themp_bind() function call, and is the name used when invoking ovstart ,ovstop , ovstatus , and ovisrunning .

Field 2: Path

Specifies the location of the process executable code. Specify the full(absolute) pathname. If you have set up universal path names, you canspecify the partial pathname relative to the path install_dir \BIN or$OV_BIN. Note that if a directory is not specified for the executable,install_dir \BIN or $OV_BIN is assumed.

NOTE You must put a backslash in front of the colon that specifies the drivespecification on Windows operating systems. This prevents the colon inthe path from being interpreted as a field terminator. For example,

IPMgr_A.017.0_MegaCorp_International:C\:i nstall_dir \bin\netmon:

LRF Line One Example

Following are examples of the first line of a hypothetical LRF on HP-UXor Solaris. The process executable is located in $OV_BIN/MEGA/ip_mgr .

IPMgr_A.017.0_MegaCorp_International:MEGA/ip_mgr:

If you used the absolute path on HP-UX or Solaris:

IPMgr_A.017.0_MegaCorp_International:/opt/OV/bin/MEGA/ip_mgr:

The following is an example of the first line of a hypothetical LRF onWindows. The process executable is located inC: install_dir \bin\MEGA\ip_mgr .

IPMgr_A.017.0_MegaCorp_International:C\: install_dir \bin\MEGA\ip_mgr:

Second Line of the Local Registration File

The second line of the LRF specifies process management options.

Chapter 7 119


There are seven fields in the second line of the LRF. Each field isterminated by a colon (: ). The following Table 7-4 describes each field inturn. Following the table is a complete description of each field.

Field 1: Initial Start Flag

This flag indicates whether or not the process is to be launched when theovstart command is issued without arguments. Possible values for thisfield: OVs_YES_START and OVs_NO_START.

• The OVs_YES_START flag means the process will be started by theovstart command.

• The OVs_NO_START flag means the process will not be started by theovstart command.

Processes that use OVs_NO_STARTmust be explicitly started by name(for example, ovstart process_name ).

Table 7-4 Second Line of the LRF&

Field Syntax Default

1: Initial StartFlag

A character string;optional.

OVs_NO_START

2: Dependencies A series of characterstrings, separatedby commas;optional.

None (that is, can bestarted at any time).

3: Arguments A series of characterstrings, separatedby commas;optional.

None (no argumentsrequired).

4: Behavior A character string;optional.

OVs_NON_WELL_BEHAVED

5: Timeout An integer; optional. 5 seconds.

6: Pause A character string;optional.

NOPAUSE

7: Daemon Stop A character string;optional

Empty string

Chapter 7120


Field 2: Dependencies

This is a list of process names, separated by commas, that must alreadybe running before your process can be started. ovspmd uses thisinformation to determine the order in which to start processes. Use thenames as they appear in the “Name” field of the pertinent LRFs.

Field 3: Arguments

The arguments specified in this field are passed to the process as it startsup, just as if a user had passed them from the command line. Commas orblanks can be used to separate multiple arguments in this field. Forexample, suppose the arguments field had this entry—“-i,-b,amazon: ”. This would be equivalent to “-i -b amazon ” on thecommand line.

Field 4: Behavior

This field specifies how the process will interact with ovspmd. Processescan be “well-behaved,” “non-well-behaved,” or “daemons,” as describedearlier. Possible values for this field: OVs_WELL_BEHAVED,OVs_NON_WELL_BEHAVED, and OVs_DAEMON.

Field 5: Timeout

For “well-behaved” processes, this field is used to manage evident startupfailures. There are two cases:

• Your process invokes OVsInitComplete() and returnsOVS_RSP_FAILURE in the status code parameter, but fails toterminate before the timeout expires.

• Your process invokes OVsDone() , but fails to terminate before thetimeout expires.

In either case, ovspmd terminates the process, sending it SIGTERM andif necessary, SIGKILL.

If your process is either “non-well-behaved,” or a “daemon,” ovspmd waitsuntil the timeout expires before starting any process that lists yourprocess in its “Dependencies” field. Also, after ovspmd sends your processSIGTERM, it waits until the timeout expires before sending it a SIGKILLsignal.

Chapter 7 121


This field is also used as the PAUSE timeout. It specifies the amount oftime a process has to respond to an OVS_CMD_PAUSE. If the process doesnot respond in time, the pause operation fails.

For “well-behaved” processes with Field 6 set to PAUSE, the timeout fieldis also used to manage a failure to respond to an OVs_CMD_PAUSE. Afailure to respond within the timeout is processed as a PAUSE NACK.

Field 6: Pause

For “well-behaved” processes, this field is used to register for pause andresume messages. Possible values for this field include: PAUSE andNOPAUSE. The default is NOPAUSE: specifying NOPAUSE or leaving thefield blank prevents ovspmd from sending pause and resume messages toyour process.

A process that is dependent on one or more NNM processes mustaccurately specify these dependencies in its LRF to ensure that it ispaused before and resumed after all processes on which it is dependent.For more information about backup refer to “Integration with NNMAutomated Backup” on page 123.

Field 7: Daemon Stop Command

This field can be used only for OVS daemon processes. It follows thesame rules as the PATH field in the first line. It identifies a command(script or executable) that is to be run to stop the OVS daemon process. Itmay contain optional parameters. If a specific path is not specified,\ install_dir \BIN (Windows) or $OV_BIN (UNIX) is assumed. Thecommand should return 0 for success; anything else for failure.

LRF Line Two Example

The following is an example of the second line of a hypothetical LRF:

OVs_YES_START:pmd,ovead:-v,-n:OVs_WELL_BEHAVED:15:NOPAUSE::

Chapter 7122

Integrating with Process ManagementIntegration with NNM Automated Backup

Integration with NNM Automated BackupThis section provides information about automated backup’s integrationmodel and discusses integrating with automated backup as it applies todevelopers of new applications and to developers enhancing existingapplications.

Before reading this chapter, review the description of automated backupin the Managing Your Network manual.

Topics in this section include:

• the backup model

• three ways of integrating

• decision trees for evaluating an application to determine therelevance of each way of integrating

• implementation information

NOTE Integration with backup is not required. However, while NNM is paused,ovw and other OV processes block on any received OVw and OVwDb APIcalls. Applications and services (background processes) that do notintegrate with automated backup, but that do interact withHP OpenView APIs and processes cannot communicate with NNM whilethe HP OpenView processes are paused. For this reason, you need tounderstand and possibly respond to the backup model even though youdo not intend to participate in backups.

Automated Backup and Pre-NNM 6.0 Applications

The automated backup feature in NNM is designed to be (backwards)compatible with applications that were developed for earlier versions ofNNM. There is nothing in the automated backup implementation thatbreaks existing applications. However, there is the opportunity to modifythese applications to take advantage of the automated backup featureand provide the end-user with some benefits.

Chapter 7 123


The Backup Model

This section provides an overview of the automated backup process. Fordetails refer to the ovbackup.ovpl reference page.

The backup utility, ovbackup.ovpl is intended to be integrated into apreexisting backup procedure or to have a backup procedure built aroundit. ovbackup.ovpl is a Perl script that creates a snapshot image ofHP OpenView data, assuring that synchronization between dependentdata stores is maintained. It then places the snapshot in the stagingarea, $OV_TMP/ovbackup, where it can be copied to long term backupmedia.

As Figure 7-2 shows, ovbackup.ovpl operates in two phases. Thesephases are known as the operational phase and the analytical phase. Theoperational phase is run first; its purpose is to create a snapshot of alldata that must be synchronized together. This data is called theoperational data and consists of the following databases and directories:

$OV_DB/OpenView

• $OV_DB/eventdb

• $OV_LOG

• $OV_CONF

• $OV_LRF

• $OV_REGISTRATION

• $OV_FIELDS

• $OV_SYMBOLS

Chapter 7124


Figure 7-2 Backup

To guarantee the synchronization of the operational data,ovbackup.ovpl uses ovpause to issue a pause that is sent to everyovspmd process that has registered to receive pause notifications. (Referto the ovspmd reference page for details.) After all processes have paused,ovbackup.ovp l creates a data snapshot by running any script found inthe $OV_CONF/ovbackup/checkpoint/operational directory. Becauseall processes are paused when the snapshot is created, all data containedin the snapshot is guaranteed to be synchronized. As soon as thesnapshot is created, ovresume is called, and all processes are releasedfrom the paused state.

Data CopyStage

initiatebackup

pauseprocesses

copyoperational datato staging area

resumeprocesses

copyanalytical datato staging area

copy data topermanentarchive

copy datafrompermanentarchive

Data ArchiveStage

Data RestoreStage

OperationalPhase

AnalyticalPhase

Chapter 7 125


After the operational phase has completed, the analytical phase is run.The purpose of this phase is to create a snapshot of any HP OpenViewdata that needs to be backed up, but does not need to be synchronizedwith the operational data. During the analytical phase NNM providesscripts to create a snapshot of the following data:

• snmpCollect data ($OV_DB/snmpCollect )

• NNM Data Warehouse data

After the analytical phase has ended, ovbackup will terminate. Asnapshot of the HP OpenView data is in the staging area, ready to becopied to long term backup media.

Options to ovbackup.ovpl enable an administrator to back up only theoperational data (- operational ) or only the analytical data(- analytical ).

Archiving Data

The automated backup utilities do not provide tools for archiving thedata after it is placed into the staging directory. Each site needs toprovide tools to archive the data from the staging area to backup media.

Restoring Data

The restore utility, ovrestore.ovpl , requires that

• NNM is halted (ovstop )

• the archived data has been copied to the staging area

Like ovbackup.ovpl , there are options to ovrestore.ovpl to enable theadministrator to restore only operational data or only analytical data.See the reference page for ovrestore.ovpl .

Three Ways of Integrating

The process of evaluating an application to determine how it shouldintegrate with automated backup is the same for developers of both newapplications and applications that are being updated to take advantageof the NNM 6.0 features.

There are three ways of integrating with automated backup. It may beappropriate for an application to be integrated with automated backupby using all three or only one or two of them. For other applications theremay be no benefit to integrating at all.

Chapter 7126


The three ways of integrating are script integration, ovwMapCloseintegration, and background process integration:

• Script integration is done by adding scripts to the backup scriptdirectories. It is a way for an application to get its data backed upalong with the NNM data.

• ovwMapClose integration is done by making an application’sbehavior sensitive to the OVwEventSource parameter in theovwMapClose callback. It is a way for an application to optimize itsbehavior by eliminating those actions that are necessary forresponding to a real map close but not for responding to a pausedsystem. This is what applications must do to receive PAUSEnotification.

• Background process integration (integrating via services) is done bymodifying a background process to receive and handle pause andresume notification. It is a way for a background process to changeits behavior during backup or to act as a proxy to inform otherprocesses of the paused state of the system so that those processescan change their behavior. This is how background processes orproxies receive PAUSE notification.

Evaluating An Application

To make it easy to integrate with automated backup this section providesthe information to help you determine which means of integrating arerelevant to your application. Then, you can focus on those sections of thedocumentation which provide the integration information needed byyour application, while skipping the other sections.

For each decision tree, answer the question in the diamonds based onwhat you know about the internals of your application.

When you reach the end of each decision tree you will know if that formof integration is relevant to your application. The sections referenced atthe end points of the decision trees are the parts of the documentationwhich provide additional information about how to integrate. Note thatthe three means of integrating are not mutually exclusive. For aparticular application one, two, or all three may be appropriate.

Chapter 7 127


Script Integration

Script integration is done by adding scripts to the backup scriptdirectories. It is a way for an application to get its data backed up alongwith the NNM data.

Script integration consists of providing a backup script and a recoveryscript for the application’s data. The script may be integrated into theoperational or analytical directory, depending on the relationship of theapplication’s data to the NNM operational data. If this applies to yourapplication, refer to “Writing Backup Scripts” on page 131.

Figure 7-3 Decision Tree for Script Integration

Integration Via ovwMapClose Event

This type of integration applies to applications that use the OVw APIand register with OVW via an application registration file.

ovwMapClose integration is done by making an application’s behaviorsensitive to the OVwEventSource parameter in the ovwMapClosecallback. It is a way for an application to optimize its behavior byeliminating those activities which, while necessary for responding to areal map close, are not necessary for responding to a pause.

ovwMapClose integration consists of looking at the OVwEventSource inthe ovwMapClose callback and optimizing the application’s behaviorwhen the value of the OVwEventSource indicates that the event

Does the application haveits own data store?

Investigate script integration forthe application. See Writing Backup Scripts.

There is no need for theapplication to providescripts.NO

YES

Chapter 7128


triggering the callback is a pause rather than an actual map close. If thisapplies to your application, refer to “Integration via ovwMapClose” onpage 133.

Figure 7-4 Decision Tree for ovwMapClose Event Integration

Background Process Integration

Background integration is a way for a background process to change itsbehavior during backup or to act as a proxy to inform other processes ofthe paused state of the system so that they can change their behavior.

Does the application registerfor the ovwMapClose event?

Consider ovwMapClose integration.See Integration Via ovwMapClose.

ovwMapClose integration is notrelevant to the application.NO

YES

Chapter 7 129


Background process integration consists of 1) registering to receivepause and resume notification from ovspmd when backup takes place and2) implementing the pause behavior that is appropriate for thebackground process. If this applies to your application, refer to“Integrating via Services (Background Processes)” on page 134.

Figure 7-5 Decision Tree for Background Process Integration

Does the application have abackground process thatregisters with ovspmd?

Does that backgroundprocess have dependencieson other NNM backgroundprocesses?

Does the background processaccess the application’s datastore?NO

NO

NO

YESYES

YES

Background processintegration does not apply.

Consider background processintegration. See Integrating ViaServices.

Chapter 7130


Writing Backup Scripts

If your application has its own data store, you need to supply backupscripts if you want the data backed up along with the NNM data. If yourapplication only adds data to the NNM databases, you do not need tosupply any backup scripts. As Figure 7-6 shows, you can add scripts to berun from any of four points in the ovbackup process.

Figure 7-6 Backup Scripts

The four script points include:

Data Copy Stage

initiatebackup

copyoperationaldata to stagingarea



initiaterestore

Data Archive Stage

Data Restore Stage

Ope

ratio

nal

Pha

seA

naly

tical

Pha

se

pausesystem

resumesystem restore

operationaldata

restoreanalyticaldata

analyticalscripts

post-resumescripts

operationalscripts

pre-pausescripts

ovbackup.ovplruns:

administratorruns restorescript

Chapter 7 131


• pre-pause scripts: This step is used infrequently. Scripts in$OV_CONF/ovbackup/pre_pause are run before the global pause.You might want to add a script during this step if your applicationhas an SQL database that you want to prepare before continuingwith the backup.

• operational scripts: Scripts in$OV_CONF/ovbackup/checkpoint/operational manage data thatmust remain synchronized. ovbackup.ovpl calls each script in thisdirectory in random order.

• post-resume scripts: Like the pre-pause scripts, this step is usedinfrequently. Scripts in this step are run after NNM processes areresumed.

• analytical scripts: Scripts in$OV_CONF/ovbackup/checkpoint/analytical manage data forprocesses such as snmpCollect that are able to resynchronize theirdata with the main NNM databases or that do not require their datato correlate directly with NNM databases. ovbackup.ovpl calls eachscript in this directory in random order.

When writing backup scripts for your application, the most importantdecision to make is whether to locate the scripts in the operationaldirectory or the analytical directory. The key to making this decision iswhether your data is dependent on the data in one or more of NNM’sdatabases.

NNM processes remain paused while all scripts in the$OV_CONF/ovbackup/checkpont/operational directory run. Addingscripts to this directory increases the time that NNM is unavailable tousers during backup.

If your data is dependent on the data in one or more of NNM’s topology,object, and map databases, then your backup script belongs in theoperational directory. Otherwise, locate your script in the analyticaldirectory.

The analytical step is provided for data that is not dependent on theoperational data. By locating your script in the analytical directory,you help to limit the time that the system pauses.

An example of dependent data that would have to be backed up andrestored with the NNM-dependent data is data that uses an OVW objectID as a key. In this case, you would provide a script for the operationaldirectory.

Chapter 7132


Refer to the reference pages for ovbackup.ovpl , ovpause , ovresume ,ovuispmd , ovsmpd, ovrestore.ovpl , and the backup scripts in$OV_CONF/ovbackup/checkpoint/operational and$OV_CONF/ovbackup/checkpoint/analytical for more information onbackup scripts.

Integration via ovwMapClose

As Figure 7-7 shows, applications that integrate via OVw APIs receivenotification of pause and resume operations via the ovwMapClose andovwMapOpen events.

When an OVW process receives the command to pause, it sends anovwMapClose event to those applications registered to receive map closeevents. This particular ovwMapClose event contains an OVwEventSourceparameter value of ovwEventSourcePause , to allow applications todistinguish it from other map close events.

Applications that receive an ovwMapClose event must complete anycurrent operations related to the map, and then acknowledge the mapclose event by calling OVwAckMapClose() . There are, however, somepotential performance gains for applications that choose to recognize thespecial pause condition. Specifically, applications may choose to keeptheir map-related information, rather than deleting it, and may choose toaccept the proposed closing-time value rather that engage in any specialcalculations.

When commanded to pause, ovw does not really close the map, but ratherputs the map into a stable state (for example, for a backup operation),and then makes the map unavailable for the duration of the pausedstate. ovw will not respond to API calls while paused (a process thatmakes an OVw API call to clock).

When later commanded to resume, OVW sends an ovwMapOpen event tothose applications registered to receive map open events. This map openevent contains an OVwEventSource parameter value ofovwEventSourcePause , and indicates that the formerly unavailable mapis one again available.

Chapter 7 133


Applications that choose to keep their map-related information ratherthan deleting it can simply resume operations as though the pause hadnot taken place. Other applications must reload their map information.

Figure 7-7 API integration with Backup

Integrating via Services (Background Processes)

Only well-behaved processes can integrate with pause and resume . Eachservice uses its local registration file (LRF) to indicate interest innotification for backups. A process that is dependent on one or moreNNM processes must accurately specify these dependencies in its LRF toensure that it is paused before, and resumed after, all processes on which

Data Copy Stage

initiatebackup



pausesystem

resumesystem

Integrating Application


initiaterestore

Data Archive Stage

Data Restore Stage

restoreoperationaldata

restoreanalyticaldata

Resumecommunicationwith NNM

Placeapplication inappropriate state

Acknowledgeand respond

ovwMapOpen

ovwMapClose

ovwAckMapClose

Chapter 7134


it is dependent. For more information on well-behaved processes andhow to use the LRF, refer to See “The Local Registration File” onpage 117 and to the lrf (4) reference page.

To integrate with backup you must specify PAUSEin Field 6 of the LRF sothat pause and resume messages will be sent to your service.

As Figure 7-8 shows, when ovbackup.ovpl executes ovpause , ovspmdsends notification (OVS_CMD_PAUSE) to all registered services. When yourservice receives this notification, it should stop all operations, flush datato disk if necessary, and acknowledge the pause request withOVsResponse(OVW_RSP_PAUSE_ACK, "Paused") . If your service cannotstop operations, the proper response isOVsResponse (OVW_RSP_PAUSE_NACK,"Text "). The text, which is sent toovpause , should describe the reason for the negative acknowledgment.

Figure 7-8 Backup via Background Services

Data Copy Stage

initiatebackup

pauseprocesses


resumeprocesses


well-behavedprocess

well-behavedprocess

OVS_CMD_PAUSE

OVS_RSP_PAUSE_ACK

OVS_CMD_RESUME

OVS_RSP_RESUME_ACK

Chapter 7 135


After NNM completes the dependent phase of its backup process, ovspmdsends notification (OVS_CMD_RESUME) to registered services. Your serviceshould acknowledge the resume message usingOVsResponse(OVS_RSP_RESUME_ACK "text ") .

If your service cannot resume operations, useOVsResponse(OVS_RSP_RESUME_NACK "text ")

Care should be taken when choosing a timeout value for your process. Ifthe timeout duration is too short, your process may cause the ovpausecommand to fail (and therefore cause ovbackup.ovpl to fail). If it is toolong, the system could take too long to report a valid error with yourprocess. Some of the ovw processes will have been paused already, andthe user will be unable to interact with these subsystems. Rememberthat the timeout value is specified in seconds. Also keep in mind thatsome users may have slow machines.

Chapter 7136

Index

Aagent, 25agents

daemon, 113, 121non-well-behaved, 121well-behaved, 112

API architecture, 21applications

SNMPv2 style, 66ASN.1, 35, 73, 76

data representation, 35data types, 35

Bbackground, sending your process into, 116bilingual communication mode, 45BITS, 35blocking mode, 27, 53

Ccache flags, in OVsnmpConfCntl, 100callback

function, 70parameters, 70

ccitt(0), 33communications APIs

for communications, 56for manual retransmission, 56for message setup/management, 56for session management, 56in SNMP library, 56

communications modelagent process, 25manager process, 25SNMP, 25

compatibility flags, in OVsnmpConfCntl, 101compiling and linking, 64configuration API, 89

data structures, 94header files, 94

connectionless operation, 26conventions

typographical, 13correlated events

receiving, 51Correlation Log File Group, 81Counter, 35Counter32, 35Counter64, 35

Ddata structures, 64, 67, 94

memory management, 62data types

ASN.1, 35dot notation, 34

Eenterprise-specific MIB, 35environment variables

OV_HEADER, 64error codes, 46error values

macro for mapping, 66Event Log File Group, 81extended MIB, 35

Ffile descriptor for a session, 68flags, 100, 101foreign device

definition, 26

GGauge, 35Gauge32, 35Get Bulk Request, 30Get Next Request, 29Get Request, 29Get Response, 29

Hheader files, 64, 94

Iinclude files, 64, 94inform message, 28Inform Request, 30installing the SDK, 19INTEGER, 35Integer32, 35integration

with logging, 105with process management, 111with tracing, 105

interface behavior, 45IPAddress, 35IPX protocol, 50iso(1), 33

137

Index

Jjoint-iso-ccitt(2), 33

Llinking, with library, 64location transparency and proxies, 37logging

and OVuTL API, 105description of, 105severity levels, 105

LRF, 111agent name and location, 118and ovstart, ovstop, ovstatus, and

mp_bind(), 119and Process Management, 117contents of, 117general syntax, 118line 1 syntax, 118line 2 syntax, 120mandatory, 22

MManagement Information Base, 31manager, 25manual retransmission communications

APIs, 56memory management, 61message setup/management

communications APIs, 56MIB

enterprise-specific, 35extended, 35

MIB-II, 31MIB-II object definition

OID, 33

Nnaming tree, 33

ccitt(0), 33iso(1), 33joint-iso-ccitt(2), 33

NDBM Offset File Group, 81nettl, 105NetworkAddress, 35non-blocking mode, 27, 53notifications, 25, 28NT. See Windows

OOBJECT IDENTIFIER, 35object identifier, 33, 34OCTET STRING, 35OID, 33, 34OID, dot notation, 34OV_HEADER, 64ovaddobj, and SUF, 111OVEventDb API, 81OVEventDbClose, 83OVEventDbCorrEntryListGetNext, 84OVEventDbCorrEntryListGetNumElements

, 84OVEventDbEventIdtoUuid, 85OVEventDbEventListGetNext, 82, 84OVEventDbFindCorrelatedEvents, 82, 83OVEventDbFreeCorrEntry, 83OVEventDbFreeCorrEntryList, 84OVEventDbFreeEvent, 83OVEventDbFreeEventList, 84OVEventDbGetChildEvent, 84OVEventDbGetChildId, 84OVEventDbGetCorrelationTree, 82, 83OVEventDbGetCorrEventStatus, 84OVEventDbGetNumChildren, 84OVEventDbGetOVsnmpPdu, 84OVEventDbGetParentId, 84OVEventDbGetTreeLevel, 84OVEventDbIsEventCorrelated, 83OVEventDbOpenCorrLogforReading, 83OVEventDbOpenLogforReading, 83OVEventDbOpenStreamforReading, 83OVEventDbReadNextCorrEntry, 83OVEventDbReadNextEvent, 83OVEventDbUuidToEventId, 85OVsDone(), 115OVsInit(), 115OVsInitComplete(), 115OVSNMP API, 19

enhanced error codes, 47IPX support, 50memory management, 61multitransport interface, 50on Windows, 55protocol support, 43, 48protocol translations, 45

OVSNMP API, architecture, 21OVSNMP configuration API, 89

functions, 90OVsnmpAddNullVarBind, 56OVsnmpAddTypedVarBind, 56OVsnmpBlockingSend, 56

138

Index

OVsnmpCallback, 56OVsnmpCancel, 56OVsnmpClose, 56OVsnmpConfCntl structure

cache flags, 100compatibility flags, 101description of, 100

OVsnmpConfDest structure, 98OVsnmpConfEntry structure, 95OVsnmpConfWcList structure, 96OVsnmpCopyPdu, 56OVsnmpCreatePdu, 56OVsnmpErrString, 56OVsnmpEventOpen, 56OVsnmpFixPdu, 56OVsnmpFreePdu, 56OVsnmpGetRetryInfo, 56OVsnmpOpen, 50, 56OVsnmpPdu, 72, 76, 96, 98OVsnmpPdu structure, 52, 67, 72, 76OVsnmpRead, 56OVsnmpRecv, 56, 70OVsnmpSend, 56OVsnmpSession structure, 54, 68OVsnmpTrapOpen, 56OVsnmpVal, 67, 78OVsnmpVarBind, 67OVsnmpVarBind structure, 73, 76OVsnmpWEventOpen, 56OVsnmpWOpen, 56OVsnmpXCancel, 56OVsnmpXClose, 56OVsnmpXEventOpen, 56OVsnmpXOpen, 56OVsnmpXSend, 56OVsnmpXTrapOpen, 56ovspmd

diagram, 111process management daemon, 111

OVsPMD APIfunctions in, 115rules for use, 115

OVsReceive(), 115ovstart, 111ovstatus, 111ovstop, 111ovtrapd

on UNIX, 28on Windows, 28

OVuint64Add, 56OVuint64AddUInt32, 56OVuint64Assign, 56OVuint64Cmp, 56

OVuint64CmpUInt32, 56OVuint64Divide, 56OVuint64DivideUInt32, 56OVuint64FromStr, 56OVuint64Multiply, 56OVuint64MultiplyUInt32, 56OVuint64Shift, 56OVuint64Subtract, 56OVuint64SubtractUInt32, 56OVuint64ToStr, 56OVuLog(), 107OVuTL API

functions of, 107tracing and logging, 105

OVuTrace(), 107

PPDU

description of, 26trap, 73, 76

process management, 111ovspmd, 111OVsPMD API, 115ovstart, 111ovstatus, 111ovstop, 111

protocol support, 43protocols

SNMP, 29proxy

and location transparency, 37description of, 26

Rreferences to other documents, 38retransmission communications APIs, 56retransmissions, 53, 55RFC list, 38

Sselect(), 116select(2), 68session management communications APIs,

56session, sequence of communication, 27Set Request, 29SMI, 31

SNMPv1, 31SNMP

operations, 29

139

Index

SNMP Configuration APIdata structures, 94functions in, 90header files, 94

SNMP library, communications APIfunctions in, 56

SNMP sessionsequence of actions, 27

SNMP_STD2OV_ERR, 56SNMPv1

operations, 29SNMPv1 protocol, 29, 43SNMPv2

operations, 30SNMPv2 Trap Request, 30SNMPv2C protocol, 29, 43Software Development Kit, 19startup file (SUF), 111Stream Log File Group, 81Structure of Management Information, 31structures, 94, 100

OVsnmpConfDest, 98OVsnmpConfEntry, 95OVsnmpConfWcList, 96OVsnmpPdu, 52, 72, 76OVsnmpSession, 68OVsnmpVarBind, 73, 76

TTimeticks, 35tracing

and OVuTL API, 105description of, 105

trap PDU, 73, 76Trap Request, 29trapd, 28traps, 25, 28, 73, 76

communication sequence, 28

UUDP, 26, 50User Datagram Protocol/Internet Protocol,

27

WWin32 message loop, 55Windows

IPX support, 50ported application support, 50traps, 28

WinSNMP API, 20

XX11 event loop, 55

140

hp_man_j1261-90072_pdf.pdf

Documents

Transcript of hp_man_j1261-90072_pdf.pdf