SNMP Developer’s Guide

HP OpenView Integration Series

Manufacturing Part Number : J1261-90072

May 2002

United States
© Copyright 2002 Hewlett-Packard Company.
 Legal Notices
Hewlett-Packard makes no warranty of any kind with regard to this
manual, including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose. Hewlett-Packard
shall not be held liable for errors contained herein or direct, indirect,
special, incidental or consequential damages in connection with the
furnishing, performance, or use of this material.
Warranty. A copy of the specific warranty terms applicable to your
Hewlett- Packard product and replacement parts can be obtained from
your local Sales and Service Office.
Restricted Rights Legend. All rights are reserved. No part of this
document may be photocopied, reproduced, or translated to another
language without the prior written consent of Hewlett-Packard
Company. The information contained in this document is subject to
change without notice.
Use, duplication or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013
for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the
Commercial Computer Software Restricted Rights clause at FAR
52.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 copies
of the programs may be made for security and back-up purposes only.
Resale of the programs in their present form or with alterations, is
expressly prohibited.
Copyright Notices. ©Copyright 1983-2002 Hewlett-Packard Company,
all rights reserved.
Reproduction, adaptation, or translation of this document without prior
written permission is prohibited, except as allowed under the copyright
laws.

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 of
Microsoft Corporation.
Netscape™ and Netscape Navigator™ are U.S. trademarks of Netscape
Communications Corporation.
Oracle® is a registered U.S. trademark of Oracle Corporation, Redwood
City, California.
Oracle7™ is a trademark of Oracle Corporation, Redwood City,
California.
OSF/Motif® and Open Software Foundation® are trademarks of Open
Software 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
4
 Contents
1. Introduction to the NNM Software Developer’s Kit
The HP OpenView NNM Software Developer’s Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
The OVSNMP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
The WinSNMP and Microsoft MGMT API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
The SNMP API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Integration APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2. An Overview of SNMP
The SNMP Model of Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Manager and Agent Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SNMP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SNMPv1 and SNMPv2C Protocols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
The Management Information Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Extended MIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Data Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
SNMP Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3. The OVSNMP Communications API

SNMPv1 and SNMPv2C Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Before Accessing the SNMPv2C Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Selecting the Interface Style and Communication Protocol . . . . . . . . . . . . . . . . . . . . 48
OVSNMP Over UDP/IP and IPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The OVsnmpOpen() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Communication with the HP OpenView Event Subsystem . . . . . . . . . . . . . . . . . . . . 51
The OVsnmpPdu Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Blocking and Nonblocking Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Retransmission Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
The SNMP Communications API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Memory Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
The SNMP Communication API Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

5
Contents
4. The NNM Event Database API
The NNM Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
The NNM Event Database API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5. The OVSNMP Configuration API

The OVSNMP Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
The OVSNMP Configuration API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Data Structures for the OVSNMP Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . 94
Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
The OVsnmpConfEntry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
The OVsnmpConfWcList Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
The OVsnmpConfDest Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
The OVsnmpConfCntl Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

6. Integrating with Logging and Tracing

Overview of Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
HP-UX and Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Windows Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
The OVuTL Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

7. Integrating with Process Management

Process Management for HP OpenView Applications . . . . . . . . . . . . . . . . . . . . . . . . . 111
The OVsPMD Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
The Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Structure of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
First Line of the LRF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Second Line of the Local Registration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Integration with NNM Automated Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Automated Backup and Pre-NNM 6.0 Applications . . . . . . . . . . . . . . . . . . . . . . . . . 123
The Backup Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Three Ways of Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Evaluating An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

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

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

7
Contents

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

9
Tables

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

11
Figures

12
 Conventions
The following typographical conventions are used in this manual.

Font What the Font Represents Example

Italic For book or manual titles, and for Refer to the OVW Developer’s Guide.
manpage names.

To provide emphasis. You must follow these steps.

To specify a variable that you must At the prompt type: rlogin

supply when entering a command. your_name where you supply your
login name.

Bold For glossary terms. The distinguishing attribute of

this class...

Computer Text and items on the computer The Root map window ...
screen.
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...

Computer Text that you must enter. At the prompt, type: ovstatus.
Bold
Keycap Keyboard keys. Press Return.

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

Menu A menu name followed by a colon (:) Select Edit:Find->Objects by

Items means that you select the menu, Comment
then the item. When the item is
followed by an arrow (->), a
cascading menu follows.

13
14
 Contact Information
Technical Support Technical support information can be found on the HP OpenView World
Wide Web site at:
http://openview.hp.com/
________________________________

Documentation Your comments on and suggestions for the documentation help us

Feedback understand your needs and better meet them.
You can provide feedback about documentation via the HP
documentation 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: ovdoc@fc.hp.com
If you encounter serious errors in the documentation that impair your
ability to use NNM, please contact the HP Response Center or your
support representative so that your feedback can be entered into
CHARTS (the HP Change Request Tracking System).
________________________________

Training For information on current HP OpenView training available, see the HP

Information OpenView 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
16
1 Introduction to the NNM
Software Developer’s Kit

Chapter 1 17
Introduction to the NNM Software Developer’s Kit

This chapter introduces the SNMP component of the HP OpenView

Network Node Manager (NNM) Software Developer’s Kit (SDK). It
describes the SNMP APIs available for application development
(OVSNMP and WinSNMP), and includes an illustration of the OVSNMP
API architecture. Also included is an introduction to APIs used in
application integration.

18 Chapter 1
 Introduction to the NNM Software Developer’s Kit
The HP OpenView NNM Software Developer’s Kit

The HP OpenView NNM Software Developer’s

Kit
The NNM Software Developer’s Kit is used to write applications that are
integrated with the feature set of NNM. The kit, which is shipped on a
CD-ROM, provides application programming interfaces (APIs) for the
following:

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

NOTE For information about installing the SDK, see README_SNMPDEV.txt on

the SDK CD-ROM.

The OVSNMP API

The HP OpenView SNMP (OVSNMP) API provides SNMP
communication and configuration support for HP OpenView integrated
applications. The OVSNMP API originated in the UNIX system version
of the Network Node Manager product. It has now been made available
on the Windows operating systems to provide portability for
cross-platform applications.
The OVSNMP API supports both SNMP version 1 (SNMPv1) and
Community-based SNMP Version 2 (SNMPv2C) through a common
bilingual interface.
The primary transport mechanism is SNMP over UDP/IP. However, the
Windows version also supports SNMP over IPX communication.

Chapter 1 19
Introduction to the NNM Software Developer’s Kit
The HP OpenView NNM Software Developer’s Kit

The OVSNMP API provides a native asynchronous event-loop

programming model for Win32 on Windows operating systems and X11
on UNIX system platforms.
For an overview of SNMP management, see Chapter 2, “An Overview of
SNMP.” For more detailed information about the OVSNMP APIs, see
Chapter 3, The OVSNMP Communications API, and Chapter 5, “The
OVSNMP Configuration API.”

The WinSNMP and Microsoft MGMT API

The WinSNMP API and the Microsoft MGMT API are not included in the
HP OpenView Software Developer’s Kit. However, applications
developed with the WinSNMP API or Microsoft MGMT API are fully
compatible with Network Node Manager and other applications
developed using Windows versions of the HP OpenView Software
Developer’s Kit (SDK). The OVSNMP library uses WinSNMP for SNMP
notification (trap) reception, which in turn is compatible with the
Microsoft SNMPTRAP service. Therefore, all three types of applications
can coexist without conflict over the shared SNMP trap port.
The ACE*COMM NetPlus WinSNMP run-time library is bundled with
Network Node Manager for use only on the installed NNM system.
For more information about the WinSNMP API, refer to the technical
specification available in postscript form on the CD-ROM for the NNM
SDK.

The SNMP API Architecture

The OpenView Event Handler or subsystem passes all HP OpenView
events between HP OpenView applications. The Event Correlation
Services (ECS) engine is an integral part of the event subsystem. Event
correlation logic can be loaded into the ECS engine. This logic changes
the combination of events available for subscription from the event
subsystem.
The OVSNMP and WinSNMP APIs are compatible with each other,
which includes the ability to share (receive) notifications on the standard
SNMP trap port. This compatibility enables a mixture of applications to
run on the same system. However, HP OpenView events will be delivered
to OVSNMP applications only (and not to WinSNMP applications).

20 Chapter 1
 Introduction to the NNM Software Developer’s Kit
The HP OpenView NNM Software Developer’s Kit

Figure 1-1 illustrates the primary components and data flows of the
OVSNMP API, and their relationships to each other and to system
services.

Figure 1-1 SNMP API Architecture

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

netmon ITO

ovactiond

Alarm Browser

Annotation
server
OVEVENT
ovtrapd ANNO Drill Down
ECS ecsmgr
Port pmd I/O
162 Perl script

http server
ovevents
SNMP V1/V2 Traps

ECS Correlation Services

ECS Corr. Configuration
ASCII Management GUI
Events

Chapter 1 21
Introduction to the NNM Software Developer’s Kit
The HP OpenView NNM Software Developer’s Kit

Integration APIs
Chapters 5 and 6 cover the activities and utilities you use to integrate
your application into the HP OpenView SNMP platform on Network
Node Manager. Integration requires you to make some straightforward
modifications to your code, as well as create a few special files and
scripts.
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, you
may elect to not integrate with the logging and tracing component.
However, each point of integration makes it easier for your customer to
take full advantage of your product.

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

For further reading, see HP OpenView Integration Series: Integration

Concepts and Managing Your Network with Network Node Manager.

22 Chapter 1
2 An Overview of SNMP

Chapter 2 23
An Overview of SNMP

This chapter provides an overview of the Simple Network Management

Protocol (SNMP) as it is implemented in the HP OpenView OVSNMP
API. 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 about

SNMP and MIBs, including several RFCs (Request for Comment
documents).

24 Chapter 2
 An Overview of SNMP
The SNMP Model of Communication

The SNMP Model of Communication

Managing computer networks requires an approach that simplifies the
potentially complex problems of communication and coordination. The
prevailing approach, which has been adopted by the SNMP (Simple
Network Management Protocol), is to treat the network as a collection of
cooperative, communicating entities. There are two basic types of
entities: management processes (managers) and managed processes
(agents).

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

Agents
From the perspective of network management, an agent is usually a
passive entity. It responds to the requests of managers, supplying and
changing the values of local variables as needed. An agent can become an
active entity by emitting unsolicited messages (called notifications or
traps) to alert managers of noteworthy local events (such as a system
reboot).

NOTE The HP OVSNMP API is intended for the development of SNMP-based

network management applications. It does not fully support the
development of SNMP agents beyond supporting the generation of traps.

Chapter 2 25
An Overview of SNMP
The SNMP Model of Communication

Manager and Agent Interaction

A manager can be one of many processes on a computer. For example, a
manager might try to provide data about certain gateways. It would
make use of the gateway agent by requesting data about throughput,
retransmission rates, and other parameters. Such a manager might also
need to periodically reset gateway counters by communicating with the
gateway agent.
An agent takes care of SNMP activity for the managed node. It can be
simple or complex, depending on the device it represents. Like a
manager, an agent may actually be one of many processes on a specific
computer. On the other hand, it might be implemented in the ROM of a
device like a bridge or hub.
A device that does not directly support SNMP is said to be foreign. A
proxy is an agent that translates between SNMP and the private
protocol of a foreign device.
Managers do not need to know any internal details about the object
managed by an agent. Likewise, an SNMP agent can service requests
from many SNMP managers. The agent does not need to know the
context of the request, or the structure of the manager making the
request. The agent simply validates the request, services it, and enters
its passive state awaiting the next request.
This division of responsibilities simplifies network management
solutions. The concept of managers and agents provides a general
solution to an otherwise complex problem. All devices share a common
model for communication, which is the model promoted in SNMP.

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

Connectionless Operation
SNMP uses a connectionless transport service for communication
between the SNMP manager and agent. The HP OpenView SNMP API
introduces a session-oriented model from the application perspective.
However, this implementation serves only to bind the application to the
OVSNMP API for a given destination. A connectionless transport is still
used internally.

26 Chapter 2
 An Overview of SNMP
The SNMP Model of Communication

The OVSNMP API supports SNMP over User Datagram

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

Requests and Responses

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

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

Manager Agent

Listen for requests

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 request PDU

Generate response PDU
Send response PDU
Receive response PDU

The diagram oversimplifies the sequence somewhat. The manager can

send the request in either blocking or non-blocking mode. The type of
mode affects the need to manage retransmissions. Also, since the
implementation 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 receive
responses are in Chapter 3, The OVSNMP Communications API, and in
the online reference pages.

Chapter 2 27
An Overview of SNMP
The SNMP Model of Communication

Notifications
In the model presented previously, the manager requests information
from the agent and the agent then responds. However, it is also possible
for an agent to issue spontaneous (unsolicited) messages. Such a
message is known as a notification. In SNMPv1, notifications are
referred to as traps. In SNMPv2, a notification may be either a trap or
an inform message.
The diagram shown in Figure 2-2 illustrates the communication
sequence involved with traps.

Figure 2-2 Conceptual View of Communication Sequence with Traps

Manager Agent

Set up to receive SMP traps Initialize and begin operation

Detect an internally significant state
Create trap PDU
Send trap PDU

Receive trap PDU

Traps exist to handle special conditions. When an agent or a manager

detects a special condition, each can emit a trap message. SNMP
specifies several predefined traps, and a developer may also define
application-specific traps.
In practice, HP OpenView NNM uses a daemon process to manage trap
traffic on an SNMP management node. This is because only one
management application can bind to the SNMP/UDP trap port. On
HP-UX and Solaris, the NNM ovtrapd process binds to the trap port and
then forwards traps to local applications.
On Windows operating systems, the NNM ovtrapd process uses by
default the WinSNMP trap receptor to listen on the trap port. This
provides coexistence with native WinSNMP applications. However,
ovtrapd can also be started with an override option to listen directly to
the trap port. In this case, the WinSNMP application would not be able
to receive notifications.

28 Chapter 2
 An Overview of SNMP
The SNMP Model of Communication

SNMPv1 and SNMPv2C Protocols

There are two versions of SNMP currently in use: the original SNMP
protocol (also known as SNMPv1), and a newer version called
Community-based SNMPv2 (also known as SNMPv2C). SNMPv2C
provides a growth path to more secure network management while
remaining backwards compatible with SNMPv1 wherever possible.
This section describes some of the key differences between SNMPv1 and
SNMPv2C. 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 Network
Management 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 an
agent.

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

Get Next Request Requests the Object Identifier(s) and value(s) of the next
object(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 agent
system.

Chapter 2 29
An Overview of SNMP
The SNMP Model of Communication

The SNMPv2C protocol provides some new protocol operations over the
original SNMP protocol. These include the following:
Table 2-2 SNMPv2C Request Types

Request Type Description

Get Bulk Request Retrieves large amounts of object information in a single

request/response transaction. GetBulk behaves as if many
iterations of GetNext request/responses were issued, except that
they are all performed in a single request/response.

SNMPv2 Trap Request Sends an SNMPv2-style notification to an SNMP manager. The

SNMPv2 Trap Request has a similar purpose as the SNMPv1
Trap Request, but is in a slightly different format.

Inform Request Sends an unsolicited but confirmed notification of a local event to

a remote management station.

In addition to these improved operations, SNMPv2C supports improved

exception and error reporting, and new mechanisms for defining MIBs
for SNMPv2. (MIB changes are described later in this overview.)

30 Chapter 2
 An Overview of SNMP
The Management Information Base

The Management Information Base

This section presents highlights of data representation and the concept
of a Management Information Base, or MIB.
The MIB is a general concept for expressing managed objects. A MIB
contains the definitions for a collection of standardized and non-
standardized (vendor, experimental) objects. A MIB definition specifies
objects with a standardized notation, call the Structure of
Management Information (SMI).
The Internet MIB-II is one of many standard MIBs. The purpose of the
MIB-II is to define common objects for managing TCP/IP networks.
Other standard MIBs exist (or are being defined) to manage specific
network elements as well.1
The Internet MIB-II definition (RFC 1213) defines standardized objects
for TCP/IP agents. To access the value of a MIB-II object, an SNMP
manager sends a request to the agent representing the desired instance
of the object. The request message contains MIB information (an object
identifier) that lets the agent identify the specific objects. The
corresponding response message from the agent carries the same
identifying information.
MIBs are defined using an Internet-standard language called the
Structure of Management Information (SMI). MIBs can be defined using
either of two SMI versions: the original SMI definition, and a newer
SNMPv2 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 this

discussion.

Chapter 2 31
An Overview of SNMP
The Management Information Base

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 RFC
1155: Structure and Identification of Management Information for
TCP/IP-based Internets Amended in RFC 1212: Concise MIB
Definitions

SNMPv2 SMI Defined as a superset of the SNMPv1 SMI. Some SNMPv1 data types
have 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 from
Gauge32.
• BITS (defines an enumeration of bits. Indistinguishable from
OCTET STRING.
Allows custom data types to be built by constraining the range, size,
or possible values of existing data types. For example, a new
enumeration could be constructed by defining a small set of possible
integer values. The SNMPv2 SMI refers to this form of definition as a
“textual convention.”
Defined in: RFC 1902: Structure of Management Information for
Version 2 of the Simple Network Management Protocol RFC 1903:
Textual Conventions for Version 2 of the Simple Network Management
Protocol (SNMPv2)RFC 1904: Conformance Statements for Version 2
of the Simple Network Management Protocol (SNMPv2)

32 Chapter 2
 An Overview of SNMP
The Management Information Base

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

The Naming Tree

The naming tree has the structure of a conventional tree with arbitrary
breadth 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 labels
within 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 this
branch is the International Telegraph
and Telephone Consultative
Committee (CCITT).
iso(1) The administration authority for this
branch is the International
Organization for Standards, and the
International Electrotechnical
Committee (ISO/IEC). This is the
path under which networking
management is defined.
joint-iso-ccitt(2) The administration authority for this
branch is shared between CCITT and
ISO/IEC.

Chapter 2 33
An Overview of SNMP
The Management Information Base

Figure 2-3 The Top of the MIB Naming Tree

root

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

Every path through the naming tree ultimately terminates at a leaf

node. The sequence of labels along the path (starting at the root) is the
OID for the object named at the leaf.

OIDs in Practice
The convention for writing object identifiers is called dot notation. An
OID in dot notation consists of the integers of the OID in sequence, with
a period (dot) between them. Thus the prefix for the OIDs in the MIB-II
is 1.3.6.1.2.1.
Below is an example OID from the MIB-II. The full written name of the
path is shown beneath the corresponding numerical identifiers in the
OID:

1.3.6.1.2.1.6.7

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

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

Similarly, the prefix for the OIDs in HP enterprise-specific MIBs is

1.3.6.1.4.1.11.

34 Chapter 2
 An Overview of SNMP
The Management Information Base

Extended MIBs
Many agents support extended MIBs, which define objects that are not
included in standard MIBs, such as MIB-II and enterprise-specific MIBs.
Your application can query an object from an extended MIB exactly as it
would query a MIB-II object. Users should use the proper registration
authorities when defining MIB extensions.

Data Representation
Data is exchanged between SNMP processes using the Basic Encoding
Rules (BER) defined for the Abstract Syntax Notation (ASN.1).
ASN.1 is a rich data description language, and gaining a full
understanding of it is a formidable task. Fortunately, as an SNMP
developer, you do not deal directly with ASN.1 or the Basic Encoding
Rules. The HP OpenView SNMP API takes care of the details of ASN.1
encoding 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 A simple type consisting of positive and negative whole numbers,

including zero, and is of arbitrary size up to 32 bits. However, some
Integer32
objects restrict INTEGER to a range.

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

OBJECT An array of non-negative, 32-bit integers. Each integer represents

IDENTIFIER one element of the object identifier. The maximum length of an
OBJECT IDENTIFIER is limited to 128 sub-identifiers.

Counter A type representing a non-negative integer which calculates change

and increases until it reaches a maximum value, when it then wraps
Counter32
around and starts increasing again from zero.

Chapter 2 35
An Overview of SNMP
The Management Information Base

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

Type Description

Gauge A type representing a non-negative integer, which may increase or

decrease, but which latches at a maximum value.
Gauge32

Timeticks A type representing a non-negative integer which counts the time in

hundredths of a second since some event.

NetworkAddress A type representing an address from one of possibly several protocol

families. Currently only one protocol family, the Internet family, is
present. This data type is deprecated in SNMPv2.

IPAddress A type representing a 32-bit Internet address. It is represented as an

OCTET STRING of length 4, in network byte-order. When this ASN.1
type is encoded using the ASN.1 basic encoding rules, only the
primitive encoding form shall be used.

Counter64 A type representing a non-negative, 64-bit integer which calculates

change and increases until it reaches a maximum value. It then
wraps around and starts increasing again from zero. Values can
range 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 encoded
using ASN.1 BER.

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

OCTET STRING.

36 Chapter 2
 An Overview of SNMP
The Management Information Base

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

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

The Manager addresses a message to the

Manager TargetAgent. The HP SNMP API recognizes
that the agent has an SNMP proxy named
ProxySys. The API routes the message to
SNMP ProxySys, which in turn communicates with
TargetAgent in some non-SNMP protocol,
then relays the response to manager, using
SNMP.
ProxySys

Foreign Protocol TargetAgent

The information used to recognize proxy agents resides in the SNMP

Configuration Database. This proxy information must be configured by
the administrator of the manager. For details, see xnmsnmpconf(1) in the
online reference pages.

Chapter 2 37
An Overview of SNMP
For More Information

For More Information

The documents listed in Table 2-5, Outside Reading, contain more
detailed information that is beyond the scope of this guide. These
documents are neither published nor sold by Hewlett-Packard.
Table 2-5 Outside Reading

Document Description

RFC 1155: Structure and Identification of K. McCloghrie and M. T. Rose, (May 1990).
Management Information for TCP/IP-based Contains MIB object definitions.
Internets (Obsoletes RFC 1065)

RFC 1157: A Simple Network Management J. D. Case, M. Fedor, M. L. Schoffstall, and

Protocol C. Davin, (May 1990). Defines SNMP.
(Obsoletes RFC 1098)
RFC 1187: Bulk Table Retrieval with the K. McCloghrie, M. T. Rose, and C. Davin,
SNMP (October 1990).

RFC 1212: Concise MIB Definitions K. McCloghrie and M. T. Rose, (March

1991). Describes the format for creating
MIB object files.

RFC 1213: Management Information Base K. McCloghrie and M. T. Rose, eds., (March
Network Management of TCP/IP based 1991). Defines MIB-II. (Obsoletes RFC
internets: MIB-II 1158; most current edition as of the
printing of this guide.)

RFC 1215: Convention for Defining Traps for M. T. Rose, ed. (March 1991).
Use with the SNMP

RFC 1901: Introduction to Community-based SNMPv2 WG, J.Case, K. McCloghrie, M.T.

SNMPv2 Rose, S. Waldbusser, (January 1996).
Defines “Community-based SNMPv2.”
(Experimental. Obsoletes RFC 1441)

RFC 1902: Structure of Management SNMPv2 WG, J.Case, K. McCloghrie, M.T.

Information for Version 2 of the Simple Rose, S. Waldbusser, (January 1996). MIB
Network Management Protocol (SNMPv2) Definition language for Managed Objects
(Draft Standard. Obsoletes RFC 1442)

38 Chapter 2
 An Overview of SNMP
For More Information

Table 2-5 Outside Reading (Continued)

Document Description

RFC 1903: Textual Conventions for Version 2 SNMPv2 WG, J.Case, K. McCloghrie, M.T.
of the Simple Network Management Protocol Rose, S. Waldbusser, (January 1996). MIB
(SNMPv2) Definition language for refined data types.
(Draft Standard. Obsoletes RFC 1443)

RFC 1904: Conformance Statements for SNMPv2 WG, J.Case, K. McCloghrie, M.T.
Version 2 of the Simple Network Management Rose, S. Waldbusser, (January 1996). MIB
Protocol (SNMPv2) Definition language for Conformance and
Capability definitions. (Draft Standard.
Obsoletes RFC 1444)

RFC 1905: Protocol Operations for Version 2 SNMPv2 WG, J.Case, K. McCloghrie, M.T.
of the Simple Network Management Protocol Rose, S. Waldbusser, (January 1996).
(SNMPv2) Defines SNMPv2 protocol. (Draft
Standard. Obsoletes RFC 1448)

RFC 1906: Transport Mappings for Version 2 SNMPv2 WG, J.Case, K. McCloghrie, M.T.
of the Simple Network Management Protocol Rose, S. Waldbusser, (January 1996).
(SNMPv2) Defines SNMPv2 transport mappings for
IP, IPX, DDP. (Draft Standard. Obsoletes
RFC 1449)

RFC 1907: Management Information Base for SNMPv2 WG, J.Case, K. McCloghrie, M.T.
Version 2 of the Simple Network Management Rose, S. Waldbusser, (January 1996).
Protocol (SNMPv2) Defines MIB objects that are mandatory
for SNMP agents that support SNMPv2.
(Draft Standard. Obsoletes RFC 1450)

RFC 1908: Coexistence between Version 1 and SNMPv2 WG, J.Case, K. McCloghrie, M.T.
Version 2 of the Internet-standard Network Rose, S. Waldbusser, (January 1996).
Management Framework Coexistence guidelines for SNMPv1 and
SNMPv2. (Draft Standard. Obsoletes RFC
1452)

Chapter 2 39
An Overview of SNMP
For More Information

40 Chapter 2
3 The OVSNMP Communications
API

Chapter 3 41
The OVSNMP Communications API

This chapter describes the OVSNMP Communications API. The

OVSNMP API provides all the functions and support you need to write a
manager-based network management application. It is provided in the
Software Developer’s Kit (SDK) for cross-platform portability of existing
OVSNMP/UNIX system-based applications.
This chapter discusses the following:

• OVSNMP API concepts, including:

— SNMPv1 and SNMPv2C protocol support, including changes in

the 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

42 Chapter 3
 The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

SNMPv1 and SNMPv2C Protocol Support

The OVSNMP API allows you to communicate with remote systems in
the following ways:

• using the original SNMPv1 protocol

• using the newer, Community-based SNMPv2 protocol (also called
SNMPv2C)
• letting the OVSNMP API determine which version to use
If you have an existing application that uses the OVSNMP
communications API, and do not need to communicate with remote
systems using the SNMPv2C protocol, you can simply recompile your
application and relink with the SNMP libraries provided in your
developer kit. The OVSNMP API routines are fully backward-compatible
with the previous OVSNMP communications API.
However, if you wish to access SNMPv2C remote systems, you must
write your application to specifically use the SNMPv2C API extensions.
The extensions are easily accommodated by any existing application
already using the OVSNMP communications API.
The remainder of this section describes how you can take advantage of
the dual support of the SNMPv1 and SNMPv2C protocols in the SNMP
developer’s kit.

Before Accessing the SNMPv2C Protocol

Before you access the SNMPv2C protocol, you should be aware of two
topics 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 embedded
communications protocol stack that supports both the SNMPv1 and
SNMPv2C protocols. This protocol stack contains the intelligence to
support explicit requests for SNMPv1 or SNMPv2C protocol support, as
well as a bilingual mode that supports both protocol stacks.

Chapter 3 43
The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

The bilingual mode relies on information in the SNMP configuration

database to determine which protocol version to use to communicate
with a particular agent. The protocol stack automatically translates
requests made in bilingual mode to the particular protocol supported for
a particular agent.
Figure 3-1 shows the relationship between the OVSNMP API and the
bilingual/native protocol stack support.

Figure 3-1 OVSNMP Bilingual Stack

Management Application

OR
OR
controlled by
SNMPv1 Style API SNMPv2 Style API OVSNMP_V2
API session flag
v1 mode v1 bilingual v2C
mode mode mode controlled by
protocol version
(when the
OVSNMP_V2
SNMPv1
protocol API flag is set)
SNMPv1 SNMPv2C
protocol protocol

SNMPv1 agent SNMPv2 agent

Changes in the OVSNMP API Interface Behavior

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

44 Chapter 3
 The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

You can use the OVSNMP API in its original interface style or in the new
interface style, which is called OVSNMP_V2API. If you select the new
interface style, your application can take advantage of both explicit
SNMPv2C protocol support and bilingual SNMPv1/SNMPv2C protocol
support. Your application, however, must also handle the different types
of errors that can be returned through the SNMPv2-style interface.
You may explicitly request that your application use either the SNMPv1
or 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 operations
that might not initially appear to be valid for a given remote system. For
example, you could use GetBulk Requests for a remote node that
supports only the SNMPv1 protocol. When using bilingual
communication mode, the SNMP run-time stack dynamically translates
requests into SNMP operations that are valid for the particular type of
remote system involved in the communication. For example, if a remote
system supports only the SNMPv1 protocol, a GetBulkRequest is
translated into a GetNext request.
The OVSNMP API performs the following protocol translations when
communicating with SNMPv1 agents through the SNMPv2-style
interface:

• SNMPv2 GetBulk operations are translated into SNMPv1 GetNext

operations.
• When transmitting SNMPv2 traps to SNMPv1 systems, the trap is
first translated into the SNMPv1 trap format.
• If an SNMPv1 Trap Request is received and the API is operating in
the SNMPv2-style interface mode, the SNMPv1 Trap Request is
translated into the SNMPv2 Trap format.
• SNMPv2 Inform operations cannot be translated into an SNMPv1
equivalent operation, and therefore cannot be sent to an SNMPv1
system.

Chapter 3 45
The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

Table 3-1, Protocol Operations Supported by the OVSNMP API, indicates

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

v2-style API
v1-style
SNMP Operation
API
Bilingual SNMPv1 SNMPv2C

GET_REQ_MSG x x x x

GETNEXT_REQ_MSG x x x x

GETBULK_REQ_MSG x xa 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 in x x x

SNMPV2 trap format

Receive SNMPv2 trap or x

inform in SNMPv1 trap
format

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

If necessary, you can determine which protocols are configured in the

local OVSNMP Configuration Database for a remote system by using the
OVsnmpGetVersions function or the xnmsnmpconf -getVersions
command. For more information about querying the protocols supported
by a remote system, see the reference page for xnmsnmpconf.

Enhanced Error Codes If you select the SNMPv2-style interface to

the OVSNMP API, you must be prepared to handle a much larger set of
possible error codes than was possible with the SNMPv1-only interface.

46 Chapter 3
 The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

Table 3-2, Protocol Error Status Supported by the OVSNMP API, shows
the errors that can be returned when using each of the OVSNMP API
interface modes. The original SNMPv1-style interface supports only the
error codes listed under “v1-style Interface.” SNMPv1 error codes are not
translated to SNMPv2C code. The SNMPv2C codes are more specific
than SNMPv1 codes, so there is no one-to-one translation between the
two.
Applications using the bilingual protocol mode must be able to deal with
error codes that do not appear as SNMPv1 error codes, even if the
messages originate from an SNMPv1 remote system. The bilingual mode
is designed to hide the details of the lower level protocol, and to allow
developers to write applications that work equally well when
communicating with SNMPv1 and SNMPv2C-compatible remote
systems.
When using the SNMPv2-style API interface, the set of possible errors
returned is the same, regardless of the actual SNMP protocol used to
communicate with the remote system. See Table 3-2, “Protocol Error
Status Supported by the OVSNMP API.”
Table 3-2 Protocol Error Status Supported by the OVSNMP API

v2-style Interface
v1 style
SNMP Response Errors
Interface v1 v2
Bilingual
native native

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
The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

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

v2-style Interface
v1 style
SNMP Response Errors
Interface v1 v2
Bilingual
native native

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

Selecting the Interface Style and Communication

Protocol
The OVSNMP API provides straightforward access to the original
SNMPv1-style, or to the newer SNMPv2-style interface and
communication protocol selection.
By default, a session created while using any of the session API functions
operates with the original SNMPv1-style interface. This provides full
backward compatibility for existing applications.
To place the OVSNMP API in the SNMPv2-style interface mode, first
create the session structure using any of the standard session API
routines, such as OVsnmpOpen().
Next, set the OVSNMP_V2API bit in the session_flags field of the
OVsnmpSession structure. (The OVsnmpSession structure is described
later in this chapter.) Thereafter, all calls to the OVSNMP API will
return results or errors that conform to the SNMPv2-style interface.

48 Chapter 3
 The OVSNMP Communications API
SNMPv1 and SNMPv2C Protocol Support

Optionally, if you want to specify a particular communications protocol

rather than use bilingual protocol support, you can set the
protocol_version field in the OVsnmpSession structure. All
communication from that point on will use the specified communication
protocol. Valid choices for the protocol version are:

• SNMP_VERSION_1
• SNMP_VERSION_2C
• SNMP_USE_DEFAULT_VERSION (bilingual)

Chapter 3 49
The OVSNMP Communications API
OVSNMP Over UDP/IP and IPX

OVSNMP Over UDP/IP and IPX

The OVSNMP API supports communication with SNMP agent systems
using either the User Datagram/Internet Protocol (UDP/IP) or Novell’s
Internet Packet Exchange (IPX) protocol.

NOTE Actual SNMP transmission over IPX is supported on the Windows

operating systems only. However, the multi-transport interface to enable
both UDP/IP and IPX can be used on all platforms to facilitate
cross-platform portability.

The multi-transport interface for the OVSNMP API is nearly identical to

the UDP/IP-only interface of previous releases. Existing applications
continue to support SNMP over UDP/IP without any need to be modified.
In addition, most of those applications, when ported to the
WindowsNT/2000 operating system, will realize both UDP/IP and IPX
support without any modification as well. Only applications that
override the SNMP destination on a per-request (PDU) basis must be
enhanced to realize full IPX support.
The multi-transport capabilities are exported to an application in two
areas: the OVsnmpOpen() function and the OVsnmpPdu structure.

The OVsnmpOpen() Function

The OVsnmpOpen(), OVsnmpXOpen(), and OVsnmpWOpen() functions take
peername and remote_port parameters as input.
The peername is a character string that identifies the destination of
SNMP requests issued on the session. The peername can be an IP
hostname, 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 of
the SNMP agent. If SNMP_USE_DEFAULT_REMOTE_PORT is specified for
remote_port, the appropriate default value is used (such as UDP/161 or
IPX/36879).

50 Chapter 3
 The OVSNMP Communications API
OVSNMP Over UDP/IP and IPX

Communication with the HP OpenView Event

Subsystem
The event subsystem passes all HP OpenView events between HP
OpenView applications. The Event Correlation Services (ECS) engine is
an integral part of the event subsystem. Event correlation logic can be
loaded into the ECS engine. This logic changes the combination of events
available for subscription from the event subsystem. The concepts of
event flows and event streams distinguish the combination of events
available for subscription.
An application subscribing to events must specify one of three event
flows: RAW, CORR, or ALL. The RAW event flow includes all events
received by the event subsystem excluding events originating in the ECS
engine. The correlated (CORR) event flow includes all events coming
from a named event stream. The ALL event flow includes all events
received by the event subsystem plus all events created inside the ECS
engine.
Using OVsnmpEventOpen() or its variants, applications can establish a
direct communication session with the event subsystem to send and
receive events. Through the filter parameter of OVsnmpEventOpen(), you
can specify the type of event flow (RAW, CORR, or ALL) from which to
receive HP OpenView events. In the case of CORR event flow, you can
specify 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 through
OVsnmpEventSend() or OVsnmpExtractUUID(). OVsnmp UUID data can
be manipulated through OVsnmpUuidFromStr() or OVsnmpUuidToStr().
To identify an existing event in the event subsystem see the
OVsnmpEventAck (3), OVsnmpEventDel (3), OVsnmpEventUnack (3),
OVsnmpEventChange (3), OVsnmpEventChangeCat (3), and
OVsnmpEventCorrelate (3) online reference pages.

Chapter 3 51
The OVSNMP Communications API
OVSNMP Over UDP/IP and IPX

The OVsnmpPdu Structure

The second area in which multi-transport capabilities are exported to
applications is the OVsnmpPdu structure. This structure contains an
“address” member that is defined by default as sockaddr_in (internet
socket).
To fully enable the multi-transport interface, insert the compiler
directive
#define OVSNMP_MULTI_TRANSPORT
into the application source code before including OVsnmp.h. This
redefines the OVsnmpPdu address member to be a sockaddr (generic
socket) structure. The address.sa family value then determines the
type of address specified in the PDU. If this value is AF_UNSPEC, the
session peername is used as the destination. Otherwise, AF_INET
indicates a UDP/IP address (sockaddr_in format); and AF_IPX indicates
an IPX address (sockaddr_in format).
Existing applications that rely on the session peername when sending
SNMP requests do not need to be modified. However, applications that
override the destination on a per-request (PDU) basis must be modified
to do the following:

• Use the new multi-transport interface directive.

• Reference the OVsnmpPdu address structure accordingly. Further, the
OVsnmpPdu address type must be the same type as that of the session
peername. Otherwise, the SNMP request will fail with
SNMP_ERR_INVALID_HOST.
Developers of new applications are encouraged to use the
multi-transport interface directive in all cases.

52 Chapter 3
 The OVSNMP Communications API
Blocking and Nonblocking Programming Models

Blocking and Nonblocking Programming

Models
The OVSNMP API lets you communicate with an SNMP agent system in
either a blocking or nonblocking mode. The choice between blocking and
nonblocking mode depends on whether the application is suspended
while the request is being processed.
If you issue a blocking request, your application is suspended until either
a response is received or a timeout occurs. The OVSNMP API
transparently manages a number of communications behaviors, such as
retransmission, on behalf of the application.
If you issue a nonblocking request, control returns to your application as
soon as the request is submitted, but before a response is received. This
can be advantageous if the response may not return promptly, or if your
application needs to process other events while waiting for a response.
In nonblocking communication, the OVSNMP stack needs a mechanism
for informing your application when a response arrives. This is the role
of the callback function. Thus, when you issue a nonblocking request, you
also must supply the name of a callback function that will be invoked
when the response is received.

Retransmission Support
OVSNMP uses either the User Datagram Protocol (UDP) or Internet
Packet Exchange (IPX)1 at the transport layer. These connectionless
protocols provide a simple but unreliable transport. A message can get
lost 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 handles
retransmission based on the timeout and retry values established when
the session is first opened.
If your application uses nonblocking requests, the SNMP API provides
three ways to manage retransmission:

1. OVSNMP over IPX is supported on Windows operating systems

only.

Chapter 3 53
The OVSNMP Communications API
Blocking and Nonblocking Programming Models

• manual retransmission based on the select function

• automatic retransmission using the Win32 message loop (Windows
only)
• automatic retransmission using the X11 event loop (UNIX only)
Each of the three modes uses a variant of the OVsnmpOpen function to
create the OVsnmpSession, plus a slightly different mechanism for
managing retransmission and determining when a response arrives.
However, all other functions such as OVsnmpSend, OVsnmpCancel, and
OVsnmpClose can be used with any type of OVsnmpSession.
If you use OVsnmpOpen to create the session, you must call select() to
wait for SNMP events to occur, such as the arrival of a response or the
need for a retransmission.
If you use the X11 or Win32 forms of nonblocking calls, you can rely on
the X11 or Win32 event-processing loop to determine when responses
arrive. With these types of nonblocking functions, retransmissions are
automatically managed for you.
The communications functions for the OVSNMP API are described in
more detail later in this chapter and in the online reference pages.

Select-based Retransmission
Event-driven, select-based applications make nonblocking requests. As
shown in the sample code fragment below, these applications create an
OVsnmpSession by using OVsnmpOpen, then manage retransmissions by
calling select() and the OVsnmpGetRetryInfo and OVsnmpDoRetry
functions (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
*/

54 Chapter 3
 The OVSNMP Communications API
Blocking and Nonblocking Programming Models

Automatic Retransmission Using the Win32 Message Loop

The OVSNMP API on Windows operating systems includes native Win32
support for event-driven (nonblocking) applications. As illustrated in the
sample code fragment below, you use this feature by calling the
OVsnmpWOpen and OVsnmpSend functions, along with the Win32 message
loop consisting of GetMessage to DispatchMessage. The
OVsnmpGetRetryInfo and OVsnmpDoRetry functions are not used in this
mode 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-driven
X11-based applications. These applications use OVsnmpXOpen and
OvsnmpSend. When you use this feature, the SNMP library manages all
message retransmissions for you using XtAppMainLoop(3). The sample
code 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 API
The SNMP Communications API Functions

The SNMP Communications API Functions

Table 3-3, SNMP Communications API Functions, shows how the
OVSNMP API functions are grouped, and the name and description of
each OVSNMP API function.
Table 3-3 SNMP Communications API Functions

Function Name Description

SESSION MANAGEMENT FUNCTIONS

OVsnmpOpen() Establishes a logical session with the OVsnmpAPI for

the purpose of communicating with a specific remote
system.

OVsnmpXOpen() Equivalent to OVsnmpOpen(), but prepares a logical

session for use in an X-Windows programming
environment.

OVsnmpWOpen() Equivalent to OVsnmpOpen(), but prepares a logical

session for use in a Windows operating system
programming environment.

OVsnmpClose() Terminates an SNMP session created by any of the

OVSNMP session open functions.

OVsnmpXClose() Provided for backward compatibility of existing X11

applications.

EVENT FRAMEWORK SESSION FUNCTIONS

OVsnmpEventOpen() Successor to OVsnmpTrapOpen(). Establishes a logical
session with the OVsnmpAPI for the purpose of receiving
SNMP events via the OpenView Event Framework. It
allows filters to be applied to events to reduce the
number of events that are received.

OVsnmpXEventOpen() Equivalent to OVsnmpEventOpen(), but prepares a

logical session for use in an X-Windows programming
environment.

56 Chapter 3
 The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-3 SNMP Communications API Functions (Continued)

Function Name Description

OVsnmpWEventOpen() Equivalent to OVsnmpEventOpen(), but prepares a

logical session for use in a WindowsNT/2000 operating
system programming environment.

OVsnmpTrapOpen() Predecessor to the OVsnmpEventOpen() function. This

function is provided for backward compatibility only. Use
the OVsnmpEventOpen() routine in the future.

OVsnmpXTrapOpen() Provided for backward compatibility of existing X11

applications.

MESSAGE SETUP and MANIPULATION FUNCTIONS

OVsnmpCreatePdu() Allocates and initializes an OVsnmpPdu data structure

suitable for the specified SNMP request operation.

OVsnmpAddNullVarBind() Used in conjunction with SNMP Get, GetNext, and

SNMPv2 GetBulk Requests. Allocates, initializes, and
appends an OVsnmpVarBind structure for the specified
SNMP MIB object to the SNMP Request PDU.

OVsnmpAddTypedVarBind() Used in conjunction with SNMP Set, Trap, and

SNMPv2Inform Requests. Allocates, initializes, and
appends an OVsnmpVarBind structure for the specified
SNMP MIB object to the SNMP Request PDU.

OVsnmpFixPdu() Allocates and initializes a new SNMP request PDU

based on the specified response PDU. Any invalid
variable bindings are omitted from the resulting PDU.

OVsnmpCopyPdu() Creates a copy of the specified OVsnmpPdu data structure

and its contained elements.

OVsnmpFreePdu() Deallocates the specified OVsnmpPdu data structure and

its contained elements.

OVsnmpExtractUuid() Extract the OVsnmp UUID from an OVsnmpPdu

OVsnmpUuidFromStr() Convert a string representation of an OVsnmp UUID to

its packed form.

Chapter 3 57
The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-3 SNMP Communications API Functions (Continued)

Function Name Description

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

ASCII string.

OVsnmpOidAppend() Appends one object identifier fragments of type ObjectID

to another object identifier.

OVsnmpOidAppendN() Appends one or more object identifier fragments of type

ObjectID to another object identifier.

OVsnmpOidConcat() Concatenates two object identifier fragments of type

ObjectID together to produce a new object identifier.

OVsnmpOidConcatN() Concatenates two or more object identifier fragments of

type 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 for

lexicographic ordering (less than, equal to, greater than).

OVsnmpOidFromStr() Create a new object identifier of type ObjectID from a

string in dotted-numeric notation.

OVsnmpOidFromName() Create a new object identifier of type ObjectID from a

string in either dotted-numeric notation, or mnemonic
descriptor (name) form as defined in the HP OpenView
loaded MIB database.

OVsnmpOidToStr() Format an object identifier of type ObjectID as a string in

dotted-numeric notation.

OVsnmpOidToName() Format an object identifier of type ObjectID as a string

using the mnemonic descriptor (name) defined in the HP
OpenView 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 allocated

memory.

58 Chapter 3
 The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-3 SNMP Communications API Functions (Continued)

Function Name Description

OVsnmpFree() Deallocate a block of previously allocated dynamic

memory.

COMMUNICATIONS FUNCTIONS — BLOCKING MODE

OVsnmpBlockingSend() Sends a request PDU to an SNMP agent and waits for a

response to be received.

OVsnmpRecv() Receives an SNMP response or trap and returns the

result. If no data is available, the call is suspended until
data arrives.

COMMUNICATIONS FUNCTIONS — NONBLOCKING MODE

OVsnmpSend () Sends a request PDU to an SNMP agent, but does not

wait for a response.

OVsnmpEventSend() Send a notification PDU to the OpenView Event

subsystem. Caller can override the source address and
retrieve the OVsnmp UUID of the out going event.

OVsnmpRead() Receives incoming data on pending sessions. Information

is returned via the callback function.

OVsnmpGetRetryInfo() Gets retransmission information on pending SNMP

requests for use in the select() routine.

OVsnmpDoRetry() Retransmits a pending SNMP request.

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

OVsnmpCallback() The application-defined function that handles responses

to non-blocking requests.

OVsnmpEventAck() Acknowledge an event in the HP OpenView Event

Subsystem.

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

OVsnmpEventCorrelate() Correlate two events in the HP OpenView Event

Subsystem.

Chapter 3 59
The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-3 SNMP Communications API Functions (Continued)

Function Name Description

OVsnmpEventUnack() Unacknowledge an alarm in the HP OpenView Event

Subsystem.

OVsnmpEventChangeSev() Change the severity of an alarm HP OpenView Event

Subsystem.

OVsnmpEventChangeCat() Change the category of an alarm in the HP OpenView

Event Subsystem.

COMMUNICATIONS FUNCTIONS — X11 NONBLOCKING MODE

OVsnmpXSend() Superseded by OVsnmpSend(). It is provided for

backward compatibility of existing X11 applications.

OVsnmpXCancel() Superseded by OVsnmpCancel(). It is provided for

backward compatibility of existing X11 applications.

ERROR REPORTING FUNCTIONS

OVsnmpErrString() Obtains a pointer to an error message string that

corresponds to the specified OVsnmpErrno error code.

SNMP_STD2OV_ERR() Translates a pdu→error_status value into an

OVSNMP error code that is suitable for calling
OVsnmpErrString().
Note: This is required only if you are using the V2-style
API. The V1-style API allows pdu→error_status to be
passed directly.
OVUint64 ARITHMETIC FUNCTIONS

OVuint64FromStr() Converts ASCII string notation of an unsigned 64-bit

integer into OVuint64 data type.

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

OVuint64Assign() Assigns the low and high order portions of an OVuint64

value from two 32-bit values.

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

and greater than.

60 Chapter 3
 The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-3 SNMP Communications API Functions (Continued)

Function Name Description

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 the

difference.
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 OVunit64

value for less than, equality, and greater than.

OVuint64AddUInt32() Adds an unsigned 32-bit value to an OVuint64 value and

returns the sum.

OVuint64SubtractUInt32() Subtracts an unsigned 32-bit value from an OVuint64

value and returns the difference.

OVuint64MultiplyUInt32() Multiplies an OVuint64 value by an unsigned 32-bit and

returns the product.

OVuint64DivideUInt32() Divides an OVuint64 value by an unsigned 32-bit and

returns the quotient.

Memory Management
The HP OVSNMP Communications API uses two rules of thumb for
memory management:

• When you pass a data structure into a library function, it is

consumed. The memory it occupies is deallocated by the library. For
example, the call to open a session creates an OVsnmpSession data
structure, which is later consumed by the OVsnmpClose() call.
• When you obtain a data structure from a library function, you must
deallocate the associated memory using an OVsnmp library function.

Chapter 3 61
The OVSNMP Communications API
The SNMP Communications API Functions

Sometimes you may supply data to fill in a structure that the SNMP
library has allocated. For example, you might assign a Notification OID
or Enterprise OID to an SNMP Trap PDU. Such data must always be
dynamically allocated. Otherwise, a failure occurs when the library
attempts to deallocate statically allocated memory.
Make sure that whenever memory is allocated — whether by the SNMP
library or by your application — it is later deallocated. Neglecting this
can result in a “memory leak” which gradually consumes resources until
a failure occurs.
Four functions are provided for you to allocate and deallocate ancillary
data assigned to OVSNMP data structures. The are: OVsnmpMalloc(),
OVsnmpCalloc(), OVsnmpRealloc() and OVsnmpFree(). These functions
behave the same as, and are implemented using, the underlying
operating system malloc(), calloc(), realloc() and free()
functions, respectively. The purpose of the OVSNMP API versions of
these functions is to provide common memory allocation and
deallocation, particularly on the WindowsNT/2000 operating system
where the DEBUG (msvcrtd.dll) and non-DEBUG (msvcrt.dll)
versions of the C-runtime library are not compatible with each other. The
functions are also provide on UNIX systems for cross-platform
portability.
Table 3-4, OVsnmpAPI Memory Management, summarizes the types of
data 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() Allocates returned OVsnmpSession.

OVsnmpXOpen()
OVsnmpWOpen()
OVsnmpTrapOpen()
OVsnmpXTrapOpen()
OVsnmpEventOpen()
OVsnmpXEventOpen()
OVsnmpWEventOpen()

62 Chapter 3
 The OVSNMP Communications API
The SNMP Communications API Functions

Table 3-4 OVsnmpAPI Memory Management (Continued)

OVsnmpAPI Function Memory Management Performed

OVsnmpClose() Deallocates specified OVsnmpSession.

OVsnmpXClose()

OVsnmpCreatePdu() Allocates returned OVsnmpPdu.

OVsnmpAddNullVarbind() Attaches allocated OVsnmpVarBind to a

PDU.
OVsnmpAddTypedVarbind()

OVsnmpCopyPdu() Allocates returned OVsnmpPdu (makes a

duplicate of specified pdu).

OVsnmpFixPdu() Deallocates specified OVsnmpPdu. Allocates

returned OVsnmpPdu.

OVsnmpSend() Conditionally deallocates specified

OVsnmpPdu based on associated session
OVsnmpXSend()
FREE_Pdu flag.
OVsnmpBlockingSend()
If enabled, deallocates input PDU (only if
OVsnmpEventSend() no error occurs) otherwise caller must free
input PDU.

OVsnmpRecv() Allocates returned OVsnmpPdu; application

must deallocate via OVsnmpFreePdu().

OVsnmpCallback()(application supplied) API allocated OVsnmpPdu passed as input;

application must deallocate via
OVsnmpFreePdu.

OVsnmpFreePdu() Deallocates specified OVsnmpPdu.

OVsnmpMalloc() Allocates an object ID sequence that must

be assigned to an OVsnmpPdu or deallocated
OVsnmpCalloc()
using OVsnmpFree().
OVsnmpRealloc()

OVsnmpFree() Deallocates specified OVsnmpPdu.

Chapter 3 63
The OVSNMP Communications API
The SNMP Communication API Data Structures

The SNMP Communication API Data

Structures
This section introduces the key data structures. See the online reference
pages for specific details about other data structures. The reference
pages also contain information on compiling and linking your
application.

NOTE HP recommends that HP-UX developers use an ANSI C compiler, such

as the HP-UX C/ANSI C compiler, for the HP 9000 Series computers. For
C++ source code, the HP Cfront C++ compiler must be used for
development on HP-UX 10.X operating systems.
For HP 11.0, the HP ANSI C++ compiler must be used for C++ source
code. 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 to
the Release Notes for the required version.
For Solaris 2.x HP recommends that developers use an ANSI C compiler
for C source code, for C++ source code HP recommends the use of the
SPARCworks compiler suite. Refer to the Release Notes for the required
version.

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

64 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-5 OVSNMP Header Files

Header File Purpose

$OV_HEADER/OV/OVsnmp.h The main header file for OVSNMP applications. This

file includes all other header files (except
OVsnmpWfns.h and OVsnmpXfns.h) as a convenience.

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

control definitions.

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

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

$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-specific

functions.

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

OVSNMP library.

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

Chapter 3 65
The OVSNMP Communications API
The SNMP Communication API Data Structures

Guidelines for Applications Using the SNMPv2 API

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

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

— OVsnmpCreatePDU()
— OVsnmpCopyPDU()
— OVsnmpFixPDU()
— OVsnmpBlockingSend()
— OVsnmpRecv()
or passed to the nonblocking mode OVsnmpCallback() function.
• Error values derived from a PDU’s error_status field must be
mapped to the OVSNMP API error code space before being passed to
OVsnmpErrString(). This mapping is performed by the newly
provided SNMP_STD2OV_ERR macro. Examples of how this macro is
used can be found in $OV_MAIN_PATH/prg_samples/ovsnmp_app.

66 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

Data Structures
The key data structures you will use with the OVSNMP API are
described in Table 3-6.
Table 3-6 SNMP API Key Data Structures

Data Structure Description

Name

OVsnmpSession Obtained by a call to OVsnmpOpen(), it identifies a particular

SNMP communication session. Used as an input parameter to
several other functions. Created by OVsnmpOpen(); freed by
OVsnmpClose().

OVsnmpPdu Container for an SNMP message. It includes information about

the type of message (“Get,” “Get Next,” “GetBulk,” “Set,” “Trap,”
or “Inform”), as well as the message data itself. Created by
OVsnmpCreatePdu(); freed by OVsnmpFreePdu().

OVsnmpVarBind Elements on a linked list of variables. Each element of the list

includes an object identifier for the variable and the variable's
value. Part of the OVsnmpPdu structure. Created by
OVsnmpAddVarBind(); freed by OVsnmpFreePdu().

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

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

Chapter 3 67
The OVSNMP Communications API
The SNMP Communication API Data Structures

The OVsnmpSession Structure

OVsnmpSession identifies a logical session between the manager and a
specific destination SNMP agent. The OVsnmpSession structure is
allocated by a call to OVsnmpOpen, and is an input parameter to several
other 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 OVSNMP
configuration database. When the session is
closed, 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 in

SNMP 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 to
establish the read mask for calls to select().

(*callback)() (void *)() Points to the callback function to be invoked when

a response returns from a call to OVsnmpSend() or
OVsnmpXSend(), or when a notification is received
using OVsnmpRead(). These two send functions
are nonblocking, and the callback function is to be
invoked when the corresponding response arrives.
callback_data void * Points to application data the callback function is
to receive (note the syntax of the callback
invocation below). The memory is not accessed by
the library.

68 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-7 OVsnmpSession Fields (Continued)

Field Name Type Description

protocol_version long Defines a specific SNMP protocol version to use for

this session. It is only valid when the
OVSNMP_V2API bit in the session_flags field is
enabled.
Valid values are:
SNMP_VERSION_1
SNMP_VERSION_2C
SNMP_USE_DEFAULT_VERSION

session_flags u_short A bitmask for information and control. The

following values are defined:

• OVSNMP_FREE_PDU (and FREE_PDU): If set, the

send functions deallocate memory associated
with the input OVsnmpPdu structure. The
default for this flag is set.
• OVSNMP_RECV_EVENTS (and RECV_TRAPS): Set
this flag if you want notifications (traps and
informs) to be passed to the calling
application.
• The default when using OVsnmpOpen() or
OVsnmpXOpen() is unset.
• The default when using OVsnmpEventOpen(),
OVsnmpXEventOpen(), OVsnmpTrapOpen(), or
OVsnmpXTrapOpen() is set.
• OVSNMP_V2API: Controls the interface
semantics of the OVsnmpAPI with regard to
SNMPv1 versus SNMPv2-style operation. The
default for this flag is unset.
• OVSNMP_CLOSE_CALLBACK: If set, the
nonblocking application callback function is
invoked for each outstanding request that
exists at the time the session is closed (via
OVsnmpClose() or OVsnmpXClose(). The
default for this flag is unset.

Chapter 3 69
The OVSNMP Communications API
The SNMP Communication API Data Structures

The Callback Function

Your application determines the structure and purpose of the callback
function. If you use the nonblocking calls in the OVSNMP API, the
callback function defines the interaction of your application and the
remote peer.
The callback function is automatically invoked when your application
uses OVsnmpRead() to obtain the response to a nonblocking send request.
In X applications, the callback is invoked automatically when the
response arrives. The call syntax is as follows:
callback (command, session, pdu, callback_data)
If the response or notification is obtained with OVsnmpRecv instead, the
callback does not occur.
Your callback function must define the parameters in Table 3-8. These
input parameters are passed to the callback function. They are described
further in the OVsnmpPdu data structure section.
Table 3-8 CallBack Parameters

Parameter Description

command An integer. Indicates why the callback function

was called. See Table 3-9 for details.

session An OVsnmpSession structure. Identifies the

session with which the incoming PDU is
associated.

pdu An OVsnmpPdu structure. This is the PDU that was

received, or a copy of the original request PDU on
some error conditions.

callback_data Application-specific data, which is specified as the

value passed into the OVsnmpOpen call.

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

70 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-9 CallBack Command Values

Command Value Note Description

GET_REQ_MSG 1 The pdu parameter contains the RESPONSE to

the respective type of outstanding SNMP
GETNEXT_REQ_MSG
request.
SET_REQ_MSG

RESPONSE_MSG 2 The pdu parameter contains the RESPONSE to an

outstanding SNMP request.

V1TRAP_REQ_MSG 1 The pdu parameter contains unsolicited trap

notifications.

V2TRAP_REQ_MSG 2 The pdu parameter contains unsolicited trap

notifications.

INFORM_REQ_MSG 2 The pdu parameter contains an unsolicited

inform notification.

SNMP_ERR_NO_RESPONSE 1, 2 A timeout occurred without receiving a

response. OVsnmpNoRspID (global variable)
contains the outstanding request ID. structure.
The pdu is NULL. The pdu is a copy of the
outstanding request.

SNMP_SYSERR_LOST_CONN 3 Indicates the connection to OpenView Event

subsystem is disconnected. For example, the
pmd process has terminated via ovstop. The
pdu is NULL.

SNMP_ERR_CLOSING_SESSION 4 Indicates the specified session is being closed by

OVsnmpClose (or OVsnmpXClose) when an
SNMP request is still outstanding. The pdu is a
copy of the outstanding request.
Notes

(1) Occurs only if the SNMP_V2API bit in the session_flags field is not set for the specified
session parameter.

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

Chapter 3 71
The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-9 CallBack Command Values (Continued)

Command Value Note Description

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

(4) Occurs only if the OVSNMP_CLOSE_CALLBACK bit in the session_flags field is set for the
specified session parameter.

The OVsnmpPdu Structure

The OVsnmpPdu data structure represents the SNMP Request, Response,
or Trap PDU that is sent or received by the calling application. The
information in this structure is encoded into and decoded from the ASN.1
contents of the SNMP packet.
The OVsnmpPdu is created in one of two ways:

• Through a call to OVsnmpCreatePdu(). This is done while preparing

to send a request.
• When a response or notification is received.
The SNMP send functions normally deallocate the memory associated
with input PDU structures.1 To deallocate the PDU associated with a
response or notification, use OVsnmpFreePdu().

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

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

72 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

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 the
elements in the OVsnmpPdu data structure.

Figure 3-2 OVsnmpPDU Structure

OVsnmpPdu
address
command
request_id
error_status
error_index OVsnmpVarBind OVsnmpVarBind
*community *next_variable *nex_variable NULL
community_len *oid *oid
*variables oid_length oid_length
Specific *notify_oid type type
toV2 Traps
& Informs notify_oid_length val val
generic_type *integer *integer
Specific
toV1 Traps specific_type *string *string
union

union

*enterprise *object_id *object id

Specific
toV1 & V2 enterprise_length *uint32 *uint32
Traps & agent_addr *uint64 *uint64
Informs
time val_len val_len

Chapter 3 73
The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-10 Elements of the OVsnmpPdu Data Structure

Field Name Type Description

address struct The address of the agent. Supported

address types are AF_UNSPEC (the default),
sockaddr
AF_INET, and AF_IPX (Windows only). See
“OVSNMP Over UDP/IP and IPX” on
page 50 for details.

protocol_version long Defines the specific SNMP protocol version

that applies for this pdu. It is only valid if
the OVSNMP_V2API mode of operation is
enabled.
Valid values are:
SNMP_VERSION_1
SNMP_VERSION_2
SNMP_USE_DEFAULT_VERSION

command int The SNMP specific type of command. Must

be 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 your
application.

74 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

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

Field Name Type Description

error_status int When a response PDU is received, this

variable contains a positive value if an
error occurred on the request. If no error
occurred, the value is zero. This value is
ignored in a call to a send function.

error_index int An index into the variable list. If

error_status shows that an error
occurred, then error_index indicates
which element of the list caused the error.

community u_char * When specified in a request PDU, this

variable overrides the community name in
the session parameter for this request only
when a response PDU or trap PDU is
received. This variable contains the
community name returned by the agent.

community_len u_int The number of bytes in the community

name.

variables OVsnmpVarBind * This is a pointer to a linked list of

variables, each element of which is an
OVsnmpVarBind data structure. Memory
referenced by this pointer is deallocated by
a call to OVsnmpFreePdu(),
OVsnmpFixPdu(), or any send function.
The following fields are specific to SNMPv1 trap and SNMPv2 trap/inform PDUs, and are
invalid for all other PDUs.

enterprise ObjectID A vendor-specific identifier that uniquely

identifies the type of device sending the
trap. Optional for SNMPv2 traps and
informs.

enterprise_length u_int The number of elements in the object ID.

The default has 11 elements.

Chapter 3 75
The OVSNMP Communications API
The SNMP Communication API Data Structures

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

Field Name Type Description

agent_addr u_long The IP address of the agent that sent the

trap. Represented in Network Byte Order.
For OVSNMP over IPX, this value is zero.

time u_long The time (in tenths-of-seconds) since the

agent was last activated. The default is the
length of time that the application has been
running.
The following fields are specific to SNMPv1 trap requests, and are invalid for all other
PDUs.

generic_type int One of the SNMP-defined types of trap. See

RFC 1157 for details.

specific_type int When generic_type indicates that an

enterprise-specific trap has occurred, the
value of specific_type contains the
specific trap. Otherwise, the value is
meaningless.

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

notify_oid ObjectID * Contains the snmpTrapOID variable

bindings in the raw SNMPv2 Trap or
Inform Request message.

notify_oid_len u_int The number of elements in the object ID.

The OVsnmpVarBind Data Structure

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

76 Chapter 3
 The OVSNMP Communications API
The SNMP Communication API Data Structures

Table 3-11 Elements of the OVsnmpVarBind Data Structure

Field Name Type Description

next_variable OVsnmpVarBind * Points to the next element in the variable

list. NULL in last element.

oid ObjectID * The object identifier (object ID) for this

variable.

oid_length u_int The number of elements in the object ID for

this variable.

type u_char The ASN.1 type of the variable. Must be

one 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 the

variable. Note that this may not equal the
number of bytes in the “val”; object IDs, for
example, consist of an array of long
integers.

Chapter 3 77
The OVSNMP Communications API
The SNMP Communication API Data Structures

The OVsnmpVal data structure is a union of the possible data types for
the variable. The OVsnmpVal data can be any of the Union Members
listed in Table 3-12.
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

To see how the OVsnmpVal data structure relates to the OVsnmpVarBind

data structure, see Figure 3-2.

78 Chapter 3
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 NNM
Event Database API. It includes descriptions of the following:

• The NNM Event Database

• NNM Event Database API functions

80 Chapter 4
 The NNM Event Database API
The NNM Event Database

The NNM Event Database

The OVEventDb API is a set of library functions which provide read
access to the OpenView Event Database. (see eventdb (4) for a
description of the OpenView Event Database.) It enables the calling
application to retrieve log events and/or stream events stored in the
OpenView Event Database. Applications can also get correlation
information between events from the OpenView Event Database. There
are four log file groups in the OpenView database.

• Event Log File Group contains all the raw events received by pmd and
all the events generated by the Event Correlation engine with the
following exception. Events configured as IGNORE in trapd.conf
are 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 Manager
databases (NDBM) which are maintained in “lock-step” with the
Event Log File Group. That is, whenever an event record is written
to an Event Log File, a corresponding NDBM event offset record is
written to the corresponding NDBM Offset File. There is no API to
directly access this file group.
• Stream Log File Group is a series of four binary files that record the
association 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 record
the association of two events within an ECS event stream. The
correlation log contains records of this relationship. Often, an event
is the parent of several child events. In this case, the log contains a
corresponding number or records, each with the same parent event
in the association but with different child events.
OVEventDbOpenCorrLogForReading(),
OVEventDbFindCorrelatedEvents(),
OVEventDbGetCorrelationTree(), and other related API functions
can access data from this file group (see the OVEventdb API list
below).

Chapter 4 81
The NNM Event Database API
The NNM Event Database

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

• Use OVEventDbFindCorrelatedEvents() and

OVEventDbEventListGetNext() to retrieve a list of events, which
are directly correlated to the parent event.
• Use OVEventDbGetCorrelationTree() and related API functions to
recursively find all child events correlated to the parent event. Since
each child event may have children, this operation involves a
recursive descent. These events are stored in a list and returned in
depth first order. The operation can be lengthy, because the entire
correlation log must be searched to find the correlations.

82 Chapter 4
 The NNM Event Database API
The NNM Event Database API Functions

The NNM Event Database API Functions

The functions in the NNM Event Database AP fall into the following
categories: database access, freeing resources, and other data
manipulation such as correlating events, and determining tree events.
Table 4-1 NNM Event Database API Functions

Function Description

DATABASE ACCESS and QUERYING

Open the OpenViewEvent Database

OVEventDbOpenCorrLogforReading()
Correlation log file group for reading.

Open the OpenView Event Database log

OVEventDbOpenLogforReading()
file group for reading.

Open the OpenView Event Database

OVEventDbOpenStreamforReading()
stream log file group for reading.

Retrieve the next correlation entry from

OVEventDbReadNextCorrEntry()
the open database.

Reactivate the next event from the open

OVEventDbReadNextEvent()
database.

OVEventDbClose() Close the eventdb handle.

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

Find a list of events that are correlated

OVEventDbFindCorrelatedEvents()
with a particular event.

Recursively find all child events which

OVEventDbGetCorrelationTree()
are correlated under a particular event.

FREEING RESOURCES

Free the resources associated with an

OVEventDbFreeEvent()
OVeventHandle.

Free the resources associated with an

OVEventDbFreeCorrEntry()
OVcorrEntryHandle.

Chapter 4 83
The NNM Event Database API
The NNM Event Database API Functions

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

Function Description

Free the resources associated with an

OVEventDbFreeEventList()
OVeventListHandle.

Free the resources associated with an

OVEventDbFreeCorrEntryList()
OVcorrEntryListHandle.

OTHER DATA MANIPULATION

Iterate through an event list and return

OVEventDbEventListGetNext()
the next event handle in the list.

Iterate through a correlation entry list

OVEventDbCorrEntryListGetNext() and return the next correlation entry in
the list.

Return the number of elements in the list

OVEventDbCorrEntryListGetNumElements() associated with the
OVcorrEntryListHandle.

Return the status of a correlated event

OVEventDbGetCorrEventStatus()
associated with the OVcorrEntryHandle.

Return the eventId of the parent event

OVEventDbGetParentId()
associated with a OVcorrEntryHandle.

Return the eventId of the child event

OVEventDbGetChildId()
associated with an OVcorrEntryHandle.

Return the number of descendent events

OVEventDbGetNumChildren()
that are correlated below corrEntry.

Return an OVeventHandle that refers to

OVEventDbGetChildEvent() the child event associated with an
OVcorrEntryHandle.

Return the number of ancestor events

OVEventDbGetTreeLevel()
that are correlated above corrEntry.

Create an OVsnmpPdu from an event

OVEventDbGetOVsnmpPdu()
packet.

84 Chapter 4
 The NNM Event Database API
The NNM Event Database API Functions

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

Function Description

Convert OVeventId into OVsnmpUuid

OVEventDbEventIdtoUuid()
format.

Convert OVsnmpUuid into OVevent

OVEventDbUuidToEventId()
format.

Chapter 4 85
The NNM Event Database API
Memory Management

Memory Management
If an OVEventDb API returns a handle, the calling application must free
the memory associated with the handle.
If the API has an output pointer, the calling application must free the
memory associated with the output pointer.

Data Structure
Data structure handles in OVEventDb API are opaque to the
application. You must use related API to manipulate them:
typedef void *OVeventDbHandle;
typedef void *OVeventHandle;
typedef void *OVeventListHandle;
typedef void *OVcorrEntryHandle;
typedef void *OVcorrEntryListHandle;

86 Chapter 4
5 The OVSNMP Configuration
API

Chapter 5 87
The OVSNMP Configuration API

This chapter describes the functions and data structures in the HP

OVSNMP Configuration API. It includes descriptions of the following:

• the OVSNMP Configuration database

• OVSNMP Configuration API functions
• key data structures in the OVSNMP Configuration API, including
each element and its use

88 Chapter 5
 The OVSNMP Configuration API
The OVSNMP Configuration Database

The OVSNMP Configuration Database

The OVSNMP configuration database is a repository on the management
station for the configuration information that controls the behavior of an
SNMP 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 the
SNMP configuration database. Three classes of configuration parameters
are 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 are
requested, they are obtained from these three classes of stored
information. The resulting parameters and the associated IP address of
the destination can be cached, allowing subsequent lookups to be
performed more quickly.

Chapter 5 89
The OVSNMP Configuration API
The OVSNMP Configuration API Functions

The OVSNMP Configuration API Functions

The thirty-two functions in the OVSNMP Configuration API fall into five
categories: database access, resolution, editing, administration, and
miscellaneous.
Table 5-1 SNMP Configuration API Functions

Function Name Description

DATABASE ACCESS

OVsnmpConfOpen() Open the SNMP configuration database for subsequent

access.

OVsnmpConfClose() Close the SNMP configuration database.

OVsnmpConfDbName() Obtain the pathname of the SNMP configuration

database.

OVsnmpConfFileName() Obtain the pathname of the backwards compatibility

(shadow) file that is associated with the SNMP
configuration database.

RESOLUTION

OVsnmpConfResolveDest() Obtain the effective configuration parameters for a

specified destination agent.

OVsnmpConfFreeDest() Deallocate all memory associated with the

OVsnmpConfDest structure returned by
OVsnmpConfResolveDest(3).

EDITING

OVsnmpConfReadNextEntry() Sequentially read specific node records from the SNMP

configuration database.

OVsnmpConfReadEntry() Read a specific node record from the SNMP

configuration database.

OVsnmpConfCreateEntry() Create a new specific node record in the SNMP

configuration database. This operation will fail if a
record already exists for the specified node.

90 Chapter 5
 The OVSNMP Configuration API
The OVSNMP Configuration API Functions

Table 5-1 SNMP Configuration API Functions (Continued)

Function Name Description

OVsnmpConfStoreEntry() Create or replace, as necessary, a specific node record in

the SNMP configuration database.

OVsnmpConfDeleteEntry() Delete a specific node record from the SNMP

configuration database.

OVsnmpConfAllocEntry() Allocate an OVsnmpConfEntry structure.

OVsnmpConfCopyEntry() Allocate and initialize an OVsnmpConfEntry structure

with the values from the specified OVsnmpConfEntry
structure.

OVsnmpConfParseEntry() Allocate and initialize an OVsnmpConfEntry structure

with the values extracted from a configuration string in
the format of an ovsnmp.conf(4) configuration file entry.

OVsnmpConfFreeEntry() Deallocate all memory associated with the specified

OVsnmpConfEntry structure.

OVsnmpConfReadWcList() Read the list of IP address wildcard records from the

SNMP configuration database. Since the semantics of
wildcard records are partly dependent upon the order of
the records in the database, these records can only be
updated as a single list.

OVsnmpConfStoreWcList() Create or replace, as necessary, the list of IP address

wildcard records in the SNMP configuration database.

OVsnmpConfAllocWcLis() Allocate memory for an OVsnmpConfWcList structure.

This structure may then be inserted into the wildcard
list obtained using OVsnmpConfReadWcList(3).

OVsnmpConfFreeWcList() Deallocate all memory associated with the specified list

of OVsnmpConfWcList structures.

OVsnmpConfReadDefault() Read the global default record from the SNMP

configuration database.

OVsnmpConfStoreDefault() Create or replace, as necessary, the global default

record in the SNMP configuration database.

Chapter 5 91
The OVSNMP Configuration API
The OVSNMP Configuration API Functions

Table 5-1 SNMP Configuration API Functions (Continued)

Function Name Description

OVsnmpConfGetVersions() Determine which SNMP protocol versions are

supported by an agent by reading the SNMP
configuration database.

OVsnmpConfSetVersions() Store or modify the field in the SNMP configuration

database that indicates the SNMP protocol versions,
which are supported by a particular agent.

OVsnmpConfImportFile() Replace the contents of the SNMP configuration

database with records extracted from configuration
strings in the specified ovsnmp.conf configuration file.

OvsnmpConfExportFile() Dump the contents of the SNMP configuration database

to the specified ovsnmp.conf configuration file.

ADMINISTRATION

OVsnmpConfReadCntl() Read the current SNMP configuration database

administration record. This record contains options
which control run-time caching and use of the backward
compatibility configuration file.
OVsnmpConfStoreCntl() Update the current SNMP configuration database
administration record. This enables you to modify the
options which control runtime caching and use of the
backward compatibility file.

MISCELLANEOUS

OVsnmpConfDeleteCache() Remove all entries from the SNMP configuration

run-time cache. New entries accumulate in the cache as
applications call OVsnmpOpen() and
OVsnmpConfResolveDest().

OVsnmpConfReadNextDest() Sequentially read entries from the SNMP configuration

run-time cache. This function is provided for
troubleshooting only (such as dumping the contents of
the cache for inspection.)

92 Chapter 5
 The OVSNMP Configuration API
The OVSNMP Configuration API Functions

Table 5-1 SNMP Configuration API Functions (Continued)

Function Name Description

OVsnmpConfPrintDest() Print the contents of an OVsnmpConfDest structure to

stdout on UNIX systems or to the console window on
Windows operating systems.

OVsnmpConfPrintEntry() Print the contents of an OVsnmpConfEntry structure to

stdout on UNIX systems or to the console window on
Windows operating systems.

OVsnmpConfPrintCntl() Print the contents of an OVsnmpConfCntl structure to

stdout on UNIX systems or to the console window on
Windows operating systems.

Chapter 5 93
The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

Data Structures for the OVSNMP

Configuration API
This section describes key data structures, including their purposes and
relationships. Specific details about other parameters to SNMP functions
are available in the online reference pages.

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

Data Structures
Table 5-2 describes the key data structures that are used with the
OVSNMP Configuration API.
Table 5-2 SNMP Configuration API Data Structures

Data Structure Description

OVsnmpConfEntry This structure contains the parameters that

make up an SNMP configuration record for a
particular destination in the managed
environment. It is also used as a substructure
in the OVsnmpConfWcList and OVsnmpConfDest
structures.

OVsnmpConfWcList This structure forms an element of a linked list

used to represent the IP address wildcard list.

1. See the reference page for ov.envvars for details on the

environment variable $OV_HEADER.

94 Chapter 5
 The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

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

Data Structure Description

OVsnmpConfDest This structure contains the fully-resolved

configuration parameters for a particular
destination in the managed environment.
Additionally, it contains addressing information
which is determined at run time instead of
being stored in the configuration database.

OVsnmpConfCntl This structure contains administrative options

which control how run-time caching and the
backward compatibility configuration file are
used by the OVSNMP API.

The OVsnmpConfEntry Structure

The OVsnmpConfEntry structure is the principal data structure used for
SNMP configuration. This structure contains the parameters that make
up the SNMP configuration record for a particular destination in the
managed environment. When used alone or in the OVsnmpConfWcList
structure with the configuration editing function, some of the fields may
not be filled in; that is, they are assigned a value that indicates use
default. In this case the actual configuration value is determined at
runtime by the OVsnmpConfResolveDest() function as part of the
OVsnmpConfDest structure.
The OVsnmpConfEntry structure has the fields shown in Table 5-3:
Table 5-3 OVsnmpConfEntry Structure

Type Name Description

char * name The name of the destination for which the configuration
parameters apply. This may be an IP hostname, an IP
address, an IP address wildcard, or a non-SNMP entity that
is proxied for.

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

Chapter 5 95
The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

Table 5-3 OVsnmpConfEntry Structure (Continued)

Type Name Description

char * setCommunity The SNMP community name, which is used by the

management application when issuing SNMP Set requests
to the destination.

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

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

int retry The maximum number of retransmissions the OVSNMP

API will attempt before generating a no response condition
for an SNMP request.

int pollInterval The frequency, in seconds, at which netmon determines the

status of the destination node. This field is not used by the
OVSNMP API.

u_short remotePort The UDP port number on the destination or proxy node (as
appropriate) where the SNMP agent on that node expects to
receive SNMP requests for the destination. The standard
SNMP port is 161. This field is generally used only for
specialized proxy agents which do not listen to the standard
SNMP port.

The OVsnmpConfWcList Structure

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

96 Chapter 5
 The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

In Figure 5-1, the fields of the OVsnmpConfWcList structure are shown in

order. Note that the configuration parameters are contained in an
OVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-1 OVsnmpConfWcList Structure

OVsnmpConfWcList OVsnmpConfWcList
* next * next NULL
* confEntry * confEntry

OVsnmpConfEntry OVsnmpConfEntry
*name *name
*community *community
*setCommunity *setCommunity
*proxy *proxy
timeout timeout
retry retry
pollInterval pollInterval
remotePort remotePort

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

Table 5-4 OVsnmpConfWcList Structure

Type Field Name Description

struct next A pointer to the next OVsnmpConfWcList entry in

SNMPconfwclist * the IP address wildcard list. The value for this
field should be NULL for the last entry in the list.

OVsnmpConfEntry * confEntry A pointer to the OVsnmpConfEntry structure that

contains the configuration parameters for the IP
Address wildcard entry.

Chapter 5 97
The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

The OVsnmpConfWcList structure is returned by a call to

OVsnmpConfReadWcList() and should be deallocated by a call to
OVsnmpConfFreeWcList().

The OVsnmpConfDest Structure

The OVsnmpConfDest structure contains the fully resolved configuration
parameters for a particular destination in the managed environment. It
is based upon the OVsnmpConfEntry structure, and it contains
addressing information which is determined at run time instead of being
stored in the configuration database. The values assigned to the
OVsnmpConfEntry portion of this structure are obtained from a
combination of specific node, IP address wildcards and global default
configuration records to determine an actual configuration value for each
field.
The OVsnmpConfDest structure is returned by a call to
OVsnmpConfResolveDest() and should be deallocated by a call to
OVsnmpConfFreeDest().
In Figure 5-2 the fields of the OVsnmpConfDest structure are shown in
order. The configuration parameters are contained in an
OVsnmpConfEntry structure pointed to by the confEntry field.

Figure 5-2 OVsnmpConfDest Data Structure

OVsnmpConfDest
*confEntry
isProxied OVsnmpConfEntry
*name
ipAddr
*community
ipAddrAge
*setCommunity
agent name
*proxy
agentAddr
timeout
retry
pollInterval
remotePort

98 Chapter 5
 The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

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 structure

which contains the fully-resolved configuration
parameters for the specified destination.

short isProxied A boolean flag indicating whether or not the IP

address for this destination is that of the actual
destination (FALSE) or that of a proxy node (TRUE).

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

u_long ipAddr The IP address of the peer entity to which SNMP

requests should be sent for the specified
destination. This field has been replaced by
agentAddr. It is retained for backwards
compatibility of existing applications. For IP
agents, 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 last
queried from the IP address name server. This
value is obtained from time().

char * agentName The fully distinguished name of the nex_hop

agent associated with the destination target.

Chapter 5 99
The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

The OVsnmpConfCntl Structure

The OVsnmpConfCntl structure contains administrative options which
control how run-time caching and the backward compatibility
configuration file is used by the OVSNMP API. Its fields are shown in
Table 5-6.
Table 5-6 OVsnmpConfCntl Structure

Type Name Description

int ipAddrAge The age limit, in seconds, for IP address stored in the
SNMP configuration run-time cache. This value is used
by OVsnmpConfResolveDest() to determine when a
cached IP address must be updated by consulting the
system’s IP address name server.

cacheFlags_t cacheFlags The level of run-time cache enabled for the SNMP
configuration database. By default, resolved
configuration parameters and the IP address of
previously referenced destinations are cached. This
improves the performance of applications when the
same destination is subsequently referenced.

compat3_2_t compatFlags The level of backward compatibility for SNMP Platform

Release 3.2 that is enabled for the SNMP configuration
database. This compatibility mode is disabled by
default beginning with NNM Release 5.0.

Cache Flags
The cache flag in the OVsnmpConfCntl structure may be set to one of the
following:

• SNMP_CONF_CACHE_NONE
Run-time caching of SNMP configuration parameters and IP
addresses is disabled. The information is recomputed each time a
destination is referenced.

100 Chapter 5
 The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

• SNMP_CONF_CACHE_NOADDR
SNMP configuration parameters for previously referenced
destinations are maintained in the SNMP configuration run-time
cache. However, the IP address of those destinations is not
maintained in the cache. The IP address is determined each time the
destination is referenced by consulting the IP address name server.
• SNMP_CONF_CACHE_ALL
Both SNMP configuration parameters and the IP address of
previously referenced destinations are maintained in the SNMP
configuration run-time cache.

Compatibility Flags
The compatibility flag in the OVsnmpConfCntl structure may be set to
one of the following:

• SNMP_CONF_SHADOW_NONE
The configuration file for release 3.2 backward compatibility is not
maintained. This mode of operation should only be used if all
OVSNMP API-based applications installed and running on the
system 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 for
communications, are maintained in the backward compatibility file.
This will optimize performance of Release 3.2-based applications.
However, if the xnmsnmpconf -import command is subsequently
used with the resulting shadow file, some information in the SNMP
configuration database will be lost.
• SNMP_CONF_SHADOW_ALL
All entries in the SNMP configuration database are maintained in
the Release 3.2-compatible configuration file. This mode of operation
ensures absolute consistency between the SNMP configuration
database and the compatibility configuration file. However, this
mode may cause unnecessary performance degradation of Release
3.2-based applications if there are many proxy entries which use a
non-default SNMP port configured in the SNMP configuration
database.

Chapter 5 101
The OVSNMP Configuration API
Data Structures for the OVSNMP Configuration API

102 Chapter 5
6 Integrating with Logging and
Tracing

Chapter 6 103
Integrating with Logging and Tracing

Network management applications (managers and agents) are generally

complex. Whenever unexpected behavior is seen, it is useful to have
detailed information about the state of the application, and even a
history of what preceded the behavior. Logging and tracing are two tools
for obtaining this kind of information. They both involve tracking state
changes 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 particular
value is set. A key attribute of each incident is its severity, which is one
of four levels ranging from INFORMATIVE to DISASTER.
Tracing, on the other hand, is used to trace step-by-step the execution of
your program. For example, trace messages are typically written at the
entry and exit points of each function.

104 Chapter 6
 Integrating with Logging and Tracing
Overview 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 system
or network administrators and some sophisticated end
users. The messages you log should be understandable
to this class of user. The system administrator uses the
nettl utility to configure, filter, and format log
messages. Owing to its implementation, HP OpenView
logging has practically no impact on the performance of
your manager or agent. Therefore, logging is generally
turned on at all times.
Tracing Tracing is far more comprehensive in its intent.
Tracing provides unambiguous evidence about the
state of execution at key points in the code. Tracing is
intended primarily for the developer, to assist during
the testing phase of development. It is not intended for
end-customer use; the information in the tracing files is
typically understood only by the developer, or by
trained field support personnel. When you turn tracing
on, you should expect to experience a moderate
degradation of performance. Therefore, tracing is
generally on only during testing and debugging.
The OVuTL API is provided to let you integrate your application with the
common logging and tracing facility called nettl. This facility uses
daemon processes to receive log and trace data from network
applications (including the platform itself), and to direct that data to its
appropriate 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 Tracing
Overview of Logging and Tracing

Windows Operating Systems

On Windows operating systems, the Event Log APIs provide a way to
handle application and system logging. The Event Viewer application
lets 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 and
overwrite options. The Event Viewer also formats and displays the data.
The OVuTL API lets you integrate your application with the common
logging and tracing facility using the Event Viewer.
The Event Viewer, shown below, is found in the Administrative Tools
program group. Refer to your Windows operating system documentation
for details on using the Event Viewer.

Figure 6-1 Windows Event Viewer

106 Chapter 6
 Integrating with Logging and Tracing
The OVuTL Application Programming Interface

The OVuTL Application Programming

Interface
There are three functions in the OVuTL API:
Table 6-1 Functions in the OVuTL API

Function Description

OVuTLInit() Initializes the name of the calling software and the hostname for the
logging 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).

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

Chapter 6 107
Integrating with Logging and Tracing
The OVuTL Application Programming Interface

108 Chapter 6
7 Integrating with Process
Management

Chapter 7 109
Integrating with Process Management

The HP OpenView platform provides a robust process management

mechanism, which coordinates the startup, shutdown, pause, and
resume of the various NNM processes. This permits you to specify which
processes 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 OpenView

platforms
• the OVsPMD application programming interface (OVsPMD API)
• guidelines for constructing the first and second lines of a Local
Registration File
• guidelines for integrating your application with NNM’s automated
backup

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, since
these lines pertain to process management. Any additional lines in this
file are not relevant to Network Node Manager.

110 Chapter 7
 Integrating with Process Management
Process Management for HP OpenView Applications

Process Management for HP OpenView

Applications
From the perspective of a system administrator, process management on
the 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 safe
backup and returns them to normal processing.
Behind these commands, however, is the process management daemon
ovspmd, 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, log
files, and configuration files and returns these processes to normal
processing
• monitors processes for termination
• logs startup and shutdown information to the tracing and logging
subsystem.
ovspmd obtains information about which processes to start, and when to
start them, from the “startup” file, or SUF. The SUF is constructed by the
ovaddobj command, which adds startup information each time it is run,
based on the Local Registration File that it reads.

Chapter 7 111
Integrating with Process Management
Process Management for HP OpenView Applications

NOTE On Windows operating systems, ovspmd is a “service.” Refer to your

Windows operating system documentation for details on services.

Figure 7-1 Process Management

Administrative Commands:
ovaddobj
LRF command
ovstart, ovstop, ovpause,
ovresume,ovstatus

Requests
Responses ovsuf

ovsnmpd
Tracing &
Logging
Subsystem

Well-behaved Well-behaved Non-well-behaved Daemon

Process Process Process Process

Figure 7-1 illustrates how the ovspmd process operates. Note that the
diagram shows three kinds of processes:
Well-behaved Processes
A well-behaved process uses the OVsPMD API — the
topic of the next section — to communicate with
ovspmd. It sends ovspmd status information regarding
successful and unsuccessful initialization, normal and
abnormal termination, and pause and resume
information if configured to do so. ovspmd considers a
“well-behaved” process to have initialized successfully
only when it explicitly reports that it has. A
“well-behaved” process also exits when it receives the
command OVS_CMD_EXIT from ovspmd. If the process
fails to respond, the exit command is escalated to

112 Chapter 7
 Integrating with Process Management
Process Management for HP OpenView Applications

SIGTERM, and eventually to SIGKILL. It will respond to

OVS_CMD_PAUSE and OVS_CMD_RESUME commands if it
is configured to receive them.
The status information passed by the managed process
to ovspmd is used by ovstart, ovstop, ovstatus,
ovpause or ovresume, if currently running. The last
message received from each managed process is saved,
and forwarded, on request, to ovstatus. The messages
received from “well-behaved” processes are also logged
using the nettl logging and tracing facility.
Non-well-behaved Process
ovspmd can also manage object managers that do not
use the OVsPMD API (“non-well-behaved” processes)
only if they do not go into the background of their own
accord (see OVs_DAEMON which follows). Since a
“non-well-behaved” process returns no status
messages, ovspmd considers such processes to have
initialized successfully if the process has not exited
within the lrf specified timeout interval.
During shutdown, the ovspmd process sends SIGTERM
to non-well- behaved processes to notify them of the
need to terminate. Non-well-behaved processes that
fail to terminate within the configured timeout are sent
SIGKILL.
Daemon Process
Managed processes that go into the background cannot
be managed either with a communication channel or
with signals. ovspmd can start such a process, but
cannot stop or report meaningful status about it, since
it has neither a communication channel nor a process
ID for it.
However, you can run a script or program to stop the
daemon. Refer to “Field 7: Daemon Stop Command” on
page 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 the
OVsPMD API and create a well-behaved process. This is by far the
best choice.

Chapter 7 113
Integrating with Process Management
Process Management for HP OpenView Applications

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-behaved
process. This may be expedient, but it is less than ideal. It would be
better to take a little time to incorporate simple calls to the OVsPMD
API and create a well-behaved process.
3. If you have an existing process that does go into the background, you
can decide to not modify it, and declare it a daemon process. This too
may 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 the
OVsPMD API, the topic of the next section.

114 Chapter 7
 Integrating with Process Management
The OVsPMD Application Programming Interface

The OVsPMD Application Programming

Interface
To create a well-behaved process, you need to use the OVsPMD API,
which has these functions:
Table 7-1 Functions in the OVsPMD API

Function Description

OVsInit() Indicates that the process is beginning its initialization

phase. Returns a file descriptor (communication channel)
for communicating with ovspmd.

OVsInitComplete() Indicates that the process has finished its initialization

phase.

OVsReceive() Receives a command from ovspmd. The commands are

OVS_CMD_EXIT, which indicates that your process should
terminate, OVS_CMD_PAUSE which indicates that your
process should pause, and OVS_CMD_RESUME which
indicates that your process should resume.

OVsDone() Informs ovspmd that the process is terminating normally.

One parameter is a text message used to indicate the
reason for termination.

OVsResponse() Responds to pause and resume commands issued by

ovspmd.

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

1. Call OVsInit() when your process begins initialization. This gives

you a socket for later communication with the ovspmd process.
2. After initialization is complete—and regardless of whether it was
successful or not—you must call OVsInitComplete(). A parameter
to OVsInitComplete() indicates the initialization status; if
initialization failed, your process should call OVsInitComplete()
and exit (do not call OVsDone()).

Chapter 7 115
Integrating with Process Management
The 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, use
OVsReceive() to get the command from ovspmd. OVS_CMD_EXIT
means your process should “clean up”, call OVsDone(), and exit.
OVS_CMD_PAUSE means 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, without
instructions from ovspmd), call OVsDone(), indicating in the message
parameter the reason for termination. This message will be logged
by ovspmd along with other exit information.
6. Never go into the background (fork and exit in the parent); the child
process cannot be managed by ovspmd.

116 Chapter 7
 Integrating with Process Management
The Local Registration File

The Local Registration File

Each 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 process
manages. (These declarations appear in any additional lines after
the first two in the LRF)
As a developer, it is your responsibility to provide an LRF with your
process. The LRF makes it possible for the HP OpenView platform to
manage your process. The LRF must contain the first two lines of
information, 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 its

executable file.

Second Specifies process management information, which is

described next.

Chapter 7 117
Integrating with Process Management
The Local Registration File

General Syntax
Each line in an LRF contains two or more fields. Each field is terminated
by a colon, including the last field. Some fields are optional; it is
recommended that you still include the colon terminator for the missing
fields.
The number symbol (#) indicates the beginning of a comment, which
continues to the end of the line. White space (spaces, tab characters, and
newlines) is not permitted within any field, nor are any multibyte
characters. In the first two lines of the LRF, only printable ASCII
characters are allowed (values between decimal 32 and 126). The colon
(:), comma (,), backslash (\), and number sign (#) can only appear as
terminator characters, as noted above and in later syntax descriptions.

NOTE You must put a backslash in front of the colon that specifies the drive
specification on the Windows operating systems. This prevents the colon
in 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:
Table 7-3 First Line of the LRF

Field Syntax Default

1: Name A character string for None (must be

the process name. specified).

2: Path A character string. None (must be

specified).

Field 1: Name
Specifies the name of the process being registered. You are responsible
for ensuring the uniqueness of the process name.
For example, you could append your company’s name:
IPMgr_A.017.0_MegaCorp_International

118 Chapter 7
 Integrating with Process Management
The Local Registration File

The name must be the same name used in the session parameter to the
mp_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 can
specify 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 drive
specification on Windows operating systems. This prevents the colon in
the path from being interpreted as a field terminator. For example,
IPMgr_A.017.0_MegaCorp_International:C\:install_dir\bin\netmon:

LRF Line One Example

Following are examples of the first line of a hypothetical LRF on HP-UX
or 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 on
Windows. The process executable is located in
C: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
Integrating with Process Management
The Local Registration File

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

Field Syntax Default

1: Initial Start A character string; OVs_NO_START

Flag optional.

2: Dependencies A series of character None (that is, can be

strings, separated started at any time).
by commas;
optional.

3: Arguments A series of character None (no arguments

strings, separated required).
by commas;
optional.

4: Behavior A character string; OVs_NON_WELL_BEHAVED

optional.

5: Timeout An integer; optional. 5 seconds.

6: Pause A character string; NOPAUSE

optional.

7: Daemon Stop A character string; Empty string

optional

Field 1: Initial Start Flag

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

• The OVs_YES_START flag means the process will be started by the

ovstart command.
• The OVs_NO_START flag means the process will not be started by the
ovstart command.
Processes that use OVs_NO_START must be explicitly started by name
(for example, ovstart process_name).

120 Chapter 7
 Integrating with Process Management
The Local Registration File

Field 2: Dependencies
This is a list of process names, separated by commas, that must already
be running before your process can be started. ovspmd uses this
information to determine the order in which to start processes. Use the
names 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 starts
up, just as if a user had passed them from the command line. Commas or
blanks can be used to separate multiple arguments in this field. For
example, suppose the arguments field had this entry—
“-i,-b,amazon:”. This would be equivalent to “-i -b amazon” on the
command line.

Field 4: Behavior
This field specifies how the process will interact with ovspmd. Processes
can be “well-behaved,” “non-well-behaved,” or “daemons,” as described
earlier. 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 startup
failures. There are two cases:

• Your process invokes OVsInitComplete() and returns

OVS_RSP_FAILURE in the status code parameter, but fails to
terminate before the timeout expires.
• Your process invokes OVsDone(), but fails to terminate before the
timeout expires.
In either case, ovspmd terminates the process, sending it SIGTERM and
if necessary, SIGKILL.
If your process is either “non-well-behaved,” or a “daemon,” ovspmd waits
until the timeout expires before starting any process that lists your
process in its “Dependencies” field. Also, after ovspmd sends your process
SIGTERM, it waits until the timeout expires before sending it a SIGKILL
signal.

Chapter 7 121
Integrating with Process Management
The Local Registration File

This field is also used as the PAUSE timeout. It specifies the amount of
time a process has to respond to an OVS_CMD_PAUSE. If the process does
not respond in time, the pause operation fails.
For “well-behaved” processes with Field 6 set to PAUSE, the timeout field
is also used to manage a failure to respond to an OVs_CMD_PAUSE. A
failure 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 and
resume messages. Possible values for this field include: PAUSE and
NOPAUSE. The default is NOPAUSE: specifying NOPAUSE or leaving the
field blank prevents ovspmd from sending pause and resume messages to
your process.
A process that is dependent on one or more NNM processes must
accurately specify these dependencies in its LRF to ensure that it is
paused before and resumed after all processes on which it is dependent.
For more information about backup refer to “Integration with NNM
Automated Backup” on page 123.

Field 7: Daemon Stop Command

This field can be used only for OVS daemon processes. It follows the
same 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. It
may contain optional parameters. If a specific path is not specified,
\install_dir\BIN (Windows) or $OV_BIN (UNIX) is assumed. The
command 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::

122 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

Integration with NNM Automated Backup

This section provides information about automated backup’s integration
model and discusses integrating with automated backup as it applies to
developers of new applications and to developers enhancing existing
applications.
Before reading this chapter, review the description of automated backup
in 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 the
relevance 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 API
calls. Applications and services (background processes) that do not
integrate with automated backup, but that do interact with
HP OpenView APIs and processes cannot communicate with NNM while
the HP OpenView processes are paused. For this reason, you need to
understand and possibly respond to the backup model even though you
do 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 of
NNM. There is nothing in the automated backup implementation that
breaks existing applications. However, there is the opportunity to modify
these applications to take advantage of the automated backup feature
and provide the end-user with some benefits.

Chapter 7 123
Integrating with Process Management
Integration with NNM Automated Backup

The Backup Model

This section provides an overview of the automated backup process. For
details refer to the ovbackup.ovpl reference page.
The backup utility, ovbackup.ovpl is intended to be integrated into a
preexisting backup procedure or to have a backup procedure built around
it. ovbackup.ovpl is a Perl script that creates a snapshot image of
HP OpenView data, assuring that synchronization between dependent
data stores is maintained. It then places the snapshot in the staging
area, $OV_TMP/ovbackup, where it can be copied to long term backup
media.
As Figure 7-2 shows, ovbackup.ovpl operates in two phases. These
phases are known as the operational phase and the analytical phase. The
operational phase is run first; its purpose is to create a snapshot of all
data that must be synchronized together. This data is called the
operational 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

124 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

Figure 7-2 Backup

Data Copy
Stage

initiate
backup
Data Archive
Stage
Operational pause
Phase copy data to
processes permanent
archive
copy
operational data
to staging area
Data Restore
Stage
Analytical resume
Phase processes copy data
from
permanent
archive
copy
analytical data
to staging area

To guarantee the synchronization of the operational data,

ovbackup.ovpl uses ovpause to issue a pause that is sent to every
ovspmd process that has registered to receive pause notifications. (Refer
to the ovspmd reference page for details.) After all processes have paused,
ovbackup.ovpl creates a data snapshot by running any script found in
the $OV_CONF/ovbackup/checkpoint/operational directory. Because
all processes are paused when the snapshot is created, all data contained
in the snapshot is guaranteed to be synchronized. As soon as the
snapshot is created, ovresume is called, and all processes are released
from the paused state.

Chapter 7 125
Integrating with Process Management
Integration with NNM Automated Backup

After the operational phase has completed, the analytical phase is run.
The purpose of this phase is to create a snapshot of any HP OpenView
data that needs to be backed up, but does not need to be synchronized
with the operational data. During the analytical phase NNM provides
scripts 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. A
snapshot of the HP OpenView data is in the staging area, ready to be
copied to long term backup media.
Options to ovbackup.ovpl enable an administrator to back up only the
operational data (- operational) or only the analytical data
(- analytical).

Archiving Data
The automated backup utilities do not provide tools for archiving the
data after it is placed into the staging directory. Each site needs to
provide 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 the
administrator 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 should
integrate with automated backup is the same for developers of both new
applications and applications that are being updated to take advantage
of the NNM 6.0 features.
There are three ways of integrating with automated backup. It may be
appropriate for an application to be integrated with automated backup
by using all three or only one or two of them. For other applications there
may be no benefit to integrating at all.

126 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

The three ways of integrating are script integration, ovwMapClose

integration, and background process integration:

• Script integration is done by adding scripts to the backup script

directories. It is a way for an application to get its data backed up
along with the NNM data.
• ovwMapClose integration is done by making an application’s
behavior sensitive to the OVwEventSource parameter in the
ovwMapClose callback. It is a way for an application to optimize its
behavior by eliminating those actions that are necessary for
responding to a real map close but not for responding to a paused
system. This is what applications must do to receive PAUSE
notification.
• Background process integration (integrating via services) is done by
modifying a background process to receive and handle pause and
resume notification. It is a way for a background process to change
its behavior during backup or to act as a proxy to inform other
processes of the paused state of the system so that those processes
can change their behavior. This is how background processes or
proxies receive PAUSE notification.

Evaluating An Application
To make it easy to integrate with automated backup this section provides
the information to help you determine which means of integrating are
relevant to your application. Then, you can focus on those sections of the
documentation which provide the integration information needed by
your application, while skipping the other sections.
For each decision tree, answer the question in the diamonds based on
what you know about the internals of your application.
When you reach the end of each decision tree you will know if that form
of integration is relevant to your application. The sections referenced at
the end points of the decision trees are the parts of the documentation
which provide additional information about how to integrate. Note that
the three means of integrating are not mutually exclusive. For a
particular application one, two, or all three may be appropriate.

Chapter 7 127
Integrating with Process Management
Integration with NNM Automated Backup

Script Integration
Script integration is done by adding scripts to the backup script
directories. It is a way for an application to get its data backed up along
with the NNM data.
Script integration consists of providing a backup script and a recovery
script for the application’s data. The script may be integrated into the
operational or analytical directory, depending on the relationship of the
application’s data to the NNM operational data. If this applies to your
application, refer to “Writing Backup Scripts” on page 131.

Figure 7-3 Decision Tree for Script Integration

Does the application have There is no need for the

its own data store? application to provide
NO
scripts.

YES

Investigate script integration for

the application. See Writing Backup Scripts.

Integration Via ovwMapClose Event

This type of integration applies to applications that use the OVw API
and register with OVW via an application registration file.
ovwMapClose integration is done by making an application’s behavior
sensitive to the OVwEventSource parameter in the ovwMapClose
callback. It is a way for an application to optimize its behavior by
eliminating those activities which, while necessary for responding to a
real map close, are not necessary for responding to a pause.
ovwMapClose integration consists of looking at the OVwEventSource in
the ovwMapClose callback and optimizing the application’s behavior
when the value of the OVwEventSource indicates that the event

128 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

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

Figure 7-4 Decision Tree for ovwMapClose Event Integration

Does the application register ovwMapClose integration is not

for the ovwMapClose event? NO relevant to the application.

YES

Consider ovwMapClose integration.

See Integration Via ovwMapClose.

Background Process Integration

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

Chapter 7 129
Integrating with Process Management
Integration with NNM Automated Backup

Background process integration consists of 1) registering to receive

pause and resume notification from ovspmd when backup takes place and
2) implementing the pause behavior that is appropriate for the
background 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 a

background process that Background process
registers with ovspmd? NO integration does not apply.

YES

NO
Does that background
Does the background process
process have dependencies
access the application’s data
on other NNM background NO
store?
processes?

YES YES

Consider background process

integration. See Integrating Via
Services.

130 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

Writing Backup Scripts

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

Figure 7-6 Backup Scripts

ovbackup.ovpl
runs: Data Copy Stage

Data Archive Stage

initiate
backup
pre-pause copy data to
scripts permanent
pause archive
system
Operational

operational copy
Data Restore Stage
Phase

scripts operational
data to staging
area
initiate administrator
restore runs restore
resume script
post-resume system restore
scripts operational
data
Analytical

copy
restore
Phase

analytical analytical data

scripts analytical
to staging area
data

The four script points include:

Chapter 7 131
Integrating with Process Management
Integration with NNM Automated Backup

• 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 application
has an SQL database that you want to prepare before continuing
with the backup.
• operational scripts: Scripts in
$OV_CONF/ovbackup/checkpoint/operational manage data that
must remain synchronized. ovbackup.ovpl calls each script in this
directory in random order.
• post-resume scripts: Like the pre-pause scripts, this step is used
infrequently. Scripts in this step are run after NNM processes are
resumed.
• analytical scripts: Scripts in
$OV_CONF/ovbackup/checkpoint/analytical manage data for
processes such as snmpCollect that are able to resynchronize their
data with the main NNM databases or that do not require their data
to correlate directly with NNM databases. ovbackup.ovpl calls each
script in this directory in random order.
When writing backup scripts for your application, the most important
decision to make is whether to locate the scripts in the operational
directory or the analytical directory. The key to making this decision is
whether your data is dependent on the data in one or more of NNM’s
databases.
NNM processes remain paused while all scripts in the
$OV_CONF/ovbackup/checkpont/operational directory run. Adding
scripts to this directory increases the time that NNM is unavailable to
users 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 the
operational directory. Otherwise, locate your script in the analytical
directory.
The analytical step is provided for data that is not dependent on the
operational 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 and
restored with the NNM-dependent data is data that uses an OVW object
ID as a key. In this case, you would provide a script for the operational
directory.

132 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

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 on
backup scripts.

Integration via ovwMapClose

As Figure 7-7 shows, applications that integrate via OVw APIs receive
notification of pause and resume operations via the ovwMapClose and
ovwMapOpen events.
When an OVW process receives the command to pause, it sends an
ovwMapClose event to those applications registered to receive map close
events. This particular ovwMapClose event contains an OVwEventSource
parameter value of ovwEventSourcePause, to allow applications to
distinguish it from other map close events.
Applications that receive an ovwMapClose event must complete any
current operations related to the map, and then acknowledge the map
close event by calling OVwAckMapClose(). There are, however, some
potential performance gains for applications that choose to recognize the
special pause condition. Specifically, applications may choose to keep
their map-related information, rather than deleting it, and may choose to
accept the proposed closing-time value rather that engage in any special
calculations.
When commanded to pause, ovw does not really close the map, but rather
puts the map into a stable state (for example, for a backup operation),
and then makes the map unavailable for the duration of the paused
state. ovw will not respond to API calls while paused (a process that
makes an OVw API call to clock).
When later commanded to resume, OVW sends an ovwMapOpen event to
those applications registered to receive map open events. This map open
event contains an OVwEventSource parameter value of
ovwEventSourcePause, and indicates that the formerly unavailable map
is one again available.

Chapter 7 133
Integrating with Process Management
Integration with NNM Automated Backup

Applications that choose to keep their map-related information rather

than deleting it can simply resume operations as though the pause had
not taken place. Other applications must reload their map information.

Figure 7-7 API integration with Backup

Data Copy Stage

Integrating Application
Data Archive Stage
initiate
backup
copy data to
ovwMapClose Acknowledge permanent
and respond archive
pause
system
ovwAckMapClose

copy Data Restore Stage

Place
operational data
application in
to staging area
appropriate state
initiate
restore
ovwMapOpen
resume
Resume restore
system
communication operational
with NNM data

copy
analytical data restore
to staging area analytical
data

Integrating via Services (Background Processes)

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

134 Chapter 7
 Integrating with Process Management
Integration with NNM Automated Backup

it is dependent. For more information on well-behaved processes and

how to use the LRF, refer to See “The Local Registration File” on
page 117 and to the lrf (4) reference page.
To integrate with backup you must specify PAUSE in Field 6 of the LRF so
that pause and resume messages will be sent to your service.
As Figure 7-8 shows, when ovbackup.ovpl executes ovpause, ovspmd
sends notification (OVS_CMD_PAUSE) to all registered services. When your
service receives this notification, it should stop all operations, flush data
to disk if necessary, and acknowledge the pause request with
OVsResponse(OVW_RSP_PAUSE_ACK, "Paused"). If your service cannot
stop operations, the proper response is
OVsResponse(OVW_RSP_PAUSE_NACK,"Text"). The text, which is sent to
ovpause, should describe the reason for the negative acknowledgment.

Figure 7-8 Backup via Background Services

Data Copy Stage

initiate
backup

pause OVS_CMD_PAUSE well-

processes behaved
OVS_RSP_PAUSE_ACK process

copy
operational data
to staging area

resume OVS_CMD_RESUME well-

processes behaved
OVS_RSP_RESUME_ACK process

copy
analytical data
to staging area

Chapter 7 135
Integrating with Process Management
Integration with NNM Automated Backup

After NNM completes the dependent phase of its backup process, ovspmd
sends notification (OVS_CMD_RESUME) to registered services. Your service
should acknowledge the resume message using
OVsResponse(OVS_RSP_RESUME_ACK "text").
If your service cannot resume operations, use
OVsResponse(OVS_RSP_RESUME_NACK "text")
Care should be taken when choosing a timeout value for your process. If
the timeout duration is too short, your process may cause the ovpause
command to fail (and therefore cause ovbackup.ovpl to fail). If it is too
long, the system could take too long to report a valid error with your
process. Some of the ovw processes will have been paused already, and
the user will be unable to interact with these subsystems. Remember
that the timeout value is specified in seconds. Also keep in mind that
some users may have slow machines.

136 Chapter 7
 Index
A D
agent, 25 data structures, 64, 67, 94
agents memory management, 62
daemon, 113, 121 data types
non-well-behaved, 121 ASN.1, 35
well-behaved, 112 dot notation, 34
API architecture, 21
applications E
SNMPv2 style, 66 enterprise-specific MIB, 35
ASN.1, 35, 73, 76 environment variables
data representation, 35 OV_HEADER, 64
data types, 35 error codes, 46
error values
B macro for mapping, 66
background, sending your process into, 116 Event Log File Group, 81
bilingual communication mode, 45 extended MIB, 35
BITS, 35
blocking mode, 27, 53 F
file descriptor for a session, 68
C flags, 100, 101
cache flags, in OVsnmpConfCntl, 100 foreign device
callback definition, 26
function, 70
parameters, 70 G
ccitt(0), 33 Gauge, 35
communications APIs Gauge32, 35
for communications, 56 Get Bulk Request, 30
for manual retransmission, 56 Get Next Request, 29
for message setup/management, 56 Get Request, 29
for session management, 56 Get Response, 29
in SNMP library, 56
communications model H
agent process, 25 header files, 64, 94
manager process, 25
SNMP, 25 I
compatibility flags, in OVsnmpConfCntl, 101
compiling and linking, 64 include files, 64, 94
configuration API, 89 inform message, 28
data structures, 94 Inform Request, 30
header files, 94 installing the SDK, 19
INTEGER, 35
connectionless operation, 26 Integer32, 35
conventions integration
typographical, 13 with logging, 105
correlated events with process management, 111
receiving, 51
with tracing, 105
Correlation Log File Group, 81
Counter, 35 interface behavior, 45
Counter32, 35 IPAddress, 35
Counter64, 35 IPX protocol, 50
iso(1), 33

137
Index
J O
joint-iso-ccitt(2), 33 OBJECT IDENTIFIER, 35
object identifier, 33, 34
L OCTET STRING, 35
OID, 33, 34
linking, with library, 64 OID, dot notation, 34
location transparency and proxies, 37 OV_HEADER, 64
logging ovaddobj, and SUF, 111
and OVuTL API, 105 OVEventDb API, 81
description of, 105 OVEventDbClose, 83
severity levels, 105 OVEventDbCorrEntryListGetNext, 84
LRF, 111 OVEventDbCorrEntryListGetNumElements
agent name and location, 118 , 84
and ovstart, ovstop, ovstatus, and OVEventDbEventIdtoUuid, 85
mp_bind(), 119 OVEventDbEventListGetNext, 82, 84
and Process Management, 117 OVEventDbFindCorrelatedEvents, 82, 83
contents of, 117 OVEventDbFreeCorrEntry, 83
general syntax, 118 OVEventDbFreeCorrEntryList, 84
OVEventDbFreeEvent, 83
line 1 syntax, 118 OVEventDbFreeEventList, 84
line 2 syntax, 120 OVEventDbGetChildEvent, 84
mandatory, 22 OVEventDbGetChildId, 84
OVEventDbGetCorrelationTree, 82, 83
M OVEventDbGetCorrEventStatus, 84
Management Information Base, 31 OVEventDbGetNumChildren, 84
manager, 25 OVEventDbGetOVsnmpPdu, 84
manual retransmission communications OVEventDbGetParentId, 84
APIs, 56 OVEventDbGetTreeLevel, 84
memory management, 61 OVEventDbIsEventCorrelated, 83
message setup/management OVEventDbOpenCorrLogforReading, 83
communications APIs, 56 OVEventDbOpenLogforReading, 83
MIB OVEventDbOpenStreamforReading, 83
enterprise-specific, 35 OVEventDbReadNextCorrEntry, 83
OVEventDbReadNextEvent, 83
extended, 35 OVEventDbUuidToEventId, 85
MIB-II, 31 OVsDone(), 115
MIB-II object definition OVsInit(), 115
OID, 33 OVsInitComplete(), 115
OVSNMP API, 19
N enhanced error codes, 47
naming tree, 33 IPX support, 50
ccitt(0), 33 memory management, 61
iso(1), 33 multitransport interface, 50
joint-iso-ccitt(2), 33 on Windows, 55
NDBM Offset File Group, 81 protocol support, 43, 48
nettl, 105 protocol translations, 45
NetworkAddress, 35 OVSNMP API, architecture, 21
non-blocking mode, 27, 53 OVSNMP configuration API, 89
notifications, 25, 28 functions, 90
NT. See Windows OVsnmpAddNullVarBind, 56
OVsnmpAddTypedVarBind, 56
OVsnmpBlockingSend, 56

138
 Index
OVsnmpCallback, 56 OVuint64CmpUInt32, 56
OVsnmpCancel, 56 OVuint64Divide, 56
OVsnmpClose, 56 OVuint64DivideUInt32, 56
OVsnmpConfCntl structure OVuint64FromStr, 56
cache flags, 100 OVuint64Multiply, 56
compatibility flags, 101 OVuint64MultiplyUInt32, 56
description of, 100 OVuint64Shift, 56
OVsnmpConfDest structure, 98 OVuint64Subtract, 56
OVsnmpConfEntry structure, 95 OVuint64SubtractUInt32, 56
OVsnmpConfWcList structure, 96 OVuint64ToStr, 56
OVsnmpCopyPdu, 56 OVuLog(), 107
OVsnmpCreatePdu, 56 OVuTL API
OVsnmpErrString, 56 functions of, 107
OVsnmpEventOpen, 56 tracing and logging, 105
OVsnmpFixPdu, 56 OVuTrace(), 107
OVsnmpFreePdu, 56
OVsnmpGetRetryInfo, 56 P
OVsnmpOpen, 50, 56 PDU
OVsnmpPdu, 72, 76, 96, 98 description of, 26
OVsnmpPdu structure, 52, 67, 72, 76
OVsnmpRead, 56 trap, 73, 76
OVsnmpRecv, 56, 70 process management, 111
OVsnmpSend, 56 ovspmd, 111
OVsnmpSession structure, 54, 68 OVsPMD API, 115
OVsnmpTrapOpen, 56 ovstart, 111
OVsnmpVal, 67, 78 ovstatus, 111
OVsnmpVarBind, 67 ovstop, 111
OVsnmpVarBind structure, 73, 76 protocol support, 43
OVsnmpWEventOpen, 56 protocols
OVsnmpWOpen, 56 SNMP, 29
OVsnmpXCancel, 56 proxy
OVsnmpXClose, 56 and location transparency, 37
OVsnmpXEventOpen, 56 description of, 26
OVsnmpXOpen, 56
OVsnmpXSend, 56
OVsnmpXTrapOpen, 56 R
ovspmd references to other documents, 38
diagram, 111 retransmission communications APIs, 56
process management daemon, 111 retransmissions, 53, 55
OVsPMD API RFC list, 38
functions in, 115
rules for use, 115 S
OVsReceive(), 115 select(), 116
ovstart, 111 select(2), 68
ovstatus, 111 session management communications APIs,
ovstop, 111 56
ovtrapd session, sequence of communication, 27
on UNIX, 28 Set Request, 29
on Windows, 28 SMI, 31
OVuint64Add, 56 SNMPv1, 31
OVuint64AddUInt32, 56 SNMP
OVuint64Assign, 56 operations, 29
OVuint64Cmp, 56

139
Index
SNMP Configuration API WinSNMP API, 20
data structures, 94
functions in, 90 X
header files, 94 X11 event loop, 55
SNMP library, communications API
functions in, 56
SNMP session
sequence of actions, 27
SNMP_STD2OV_ERR, 56
SNMPv1
operations, 29
SNMPv1 protocol, 29, 43
SNMPv2
operations, 30
SNMPv2 Trap Request, 30
SNMPv2C protocol, 29, 43
Software Development Kit, 19
startup file (SUF), 111
Stream Log File Group, 81
Structure of Management Information, 31
structures, 94, 100
OVsnmpConfDest, 98
OVsnmpConfEntry, 95
OVsnmpConfWcList, 96
OVsnmpPdu, 52, 72, 76
OVsnmpSession, 68
OVsnmpVarBind, 73, 76

T
Timeticks, 35
tracing
and OVuTL API, 105
description of, 105
trap PDU, 73, 76
Trap Request, 29
trapd, 28
traps, 25, 28, 73, 76
communication sequence, 28

U
UDP, 26, 50
User Datagram Protocol/Internet Protocol,
27

W
Win32 message loop, 55
Windows
IPX support, 50
ported application support, 50
traps, 28

140